Galaxy Server — Architecture Overview

"And now, watch our Assistant pull a rabbit out of the hat..."

Core Principle: Split “Thinking” from “Facts”

The design divides the simulation into two layers with a clear contract between them:

• Clients (PC and NPC) do all the thinking: strategic planning, AI decision-making, local prediction, and UI rendering.
• The server owns all the facts: canonical positions, resources, damage, ownership, physics resolution, and all randomness.

Clients never send authoritative state. They send intents — “what I am trying to do” — and the server determines what actually happens, including any random element.

Zones, Sectors, and Federation

Two distinct spatial concepts govern how the simulation is organized and deployed. These terms have precise meanings and should not be used interchangeably.

Zones

A Zone is a named orbital region within a star system — a gameplay and narrative subdivision with no server boundary between them. Examples within the solar system: Earth Orbit, Mars Belt, Mars Surface Orbit, Inner Belt, Outer Belt. Ships move between Zones freely; the server managing the Sector handles all Zones within it.

Sectors

A Sector is a star-system-scale region managed by exactly one server instance. The entire solar system is one Sector. Alpha Centauri, when the simulation expands there, will be another Sector on another server instance. All Zones within a Sector are the responsibility of that Sector’s server; there is no intra-Sector server boundary.

Federation

When the simulation spans more than one Sector, a thin Galaxy Router layer connects the Sector Servers, maintaining the inter-Sector map and brokering ship handoffs at Sector boundaries. The handoff sequence when a ship crosses a Sector boundary:

1. The originating Sector Server sends a pre-arrival notification to the receiving Sector Server, including the ship’s full authoritative state.
2. The receiving server acknowledges and prepares a slot.
3. At the boundary-crossing tick, authority transfers: the originating server removes the ship; the receiving server adds it.
4. The ship’s client is notified of the new server address and reconnects.

The pre-arrival step is important because a ship near a boundary may be within sensor range of entities in both Sectors; the receiving server must know about the ship before it fully crosses.

Current status: A single server instance (SectorServer) manages all Zones. The Sector-scoped federation refactor — distributing the Galaxy class across instances and building the Galaxy Router — is a future milestone planned for when the single-Sector feature set is complete.

The Captain/XO Model

This is the central organizing concept for how human and AI captains share the same underlying control protocol. For the narrative perspective on how captains experience command through the XO, see The Captain’s Interface. For the technical architecture of the three-layer client model, see Client Architecture.

NPC Captains (headless clients)

A headless NPC client runs an AI Captain that reads the server’s snapshot for its ship, makes decisions (navigation, combat, trade), and emits a stream of control commands back to the server. The AI Captain is fully responsible for translating strategic goals into the low-level control stream.

PC Captains (GUI clients)

A PC client inserts a human between the strategic layer and the control stream, but keeps the same AI machinery underneath:

  Human Player
       │
       │  high-level orders
       │  ("attack that freighter", "plot course to Centauri", "raise shields")
       ▼
  AI Executive Officer (XO)
       │
       │  continuous control stream
       │  (throttle curves, heading adjustments, weapon fire timing, shield toggles)
       ▼
  [same command protocol as NPC]
       │
       ▼
  Galaxy Server

The XO’s job is to receive a player’s high-level intent and translate it into the same low-level control commands the NPC’s AI Captain would produce autonomously. From the server’s perspective, a PC captain and an NPC captain are indistinguishable — both emit CommandRequest objects with an originType of "pc" or "npc".

The practical consequence: the NPC codebase is the foundation. The PC codebase is the NPC codebase plus a human decision-making layer at the top. Adding a GUI does not require replacing the AI; it requires surfacing the AI’s state and intent to a human who can redirect it.

XO safety: collision prevention

The XO enforces a safety constraint on all navigation commands: it prevents maneuvers that would result in collision with celestial bodies, stations, or other vessels. A navigation order that would place the ship on a collision trajectory is rejected by the XO before it reaches the server’s command pipeline. This applies equally to PC and NPC captains — the XO does not distinguish between a human order and an AI decision when evaluating collision risk.

Deliberate ramming as a tactical action is not currently supported. If introduced in a future combat system revision, it would require an explicit override command that bypasses the XO’s collision avoidance, with appropriate risk and consequence modeling.

Character model alignment

The Character type captures this distinction:

• FictionRole: pc vs. npc — narrative role.
• controlMode: humanGui, aiAgent, script, idle — how the captain is currently being driven.

A PC captain with controlMode = humanGui has a human feeding orders to the XO. The same captain with controlMode = aiAgent runs fully autonomously — the XO becomes the captain. This makes it natural for a PC ship to run on autopilot when the player is offline.

Character struct fields

The canonical Character struct (characters/characterTypes.d) carries:

Removed fields (v0.2): role, rank, and simulationRole were vestigial narrative metadata that carried no gameplay weight. Under the singleship model the captain’s role is implicit (they are the captain) and rank is meaningless in a solo command. These fields are silently ignored when loading legacy MongoDB documents.

CrewComplement was simplified from four fields (baseCrewSlots, baseDroidSlots, currentCrewCount, currentDroidCount) to two: maxDroidSlots and currentDroidCount. Under the singleship model there are no organic crew — only the captain (fixed in the lifepod) and crewdroids. Legacy documents with the old field names are read via fallback in fromJSON().

Randomness and the Character Sheet

The galaxy is not a deterministic machine. Outcomes are shaped by two sources of randomness: the inherent unpredictability of the universe, and the varying capabilities of the captain and their crewdroids.

Dice rolls are server-side and authoritative

All dice rolls happen on the server. This is an invariant of the same character as “no negative fuel”: if clients could roll dice and report results, the anti-cheat guarantee collapses. The server is the sole source of random outcomes.

The Dice class (utilities.dice) provides the mechanism: a die of any number of sides (2–100), seeded independently per instance, with a roll returning a value in [1, sides]. Typical use is d6 (general chance), d20 (skill checks), and d100 (percentile events).

Character stats as modifiers

The Character sheet carries integer skill values that act as modifiers in the D&D tradition — a higher skill shifts the effective outcome of a roll:

The resolution pattern is:

  effective result = dice roll + stat modifier
  outcome = compare effective result against difficulty threshold

Difficulty thresholds are set per command kind by the CommandHandler for that kind.

Recording randomness in the command record

The Command type carries a metadata field specifically for dice results and modifiers. When a handler resolves a command with a roll, it records: which dice were rolled and their results, which character stats contributed and by how much, the difficulty threshold tested, and the narrative outcome category (success, partial, failure, critical). This record is included in CommandResult.details and returned to the client.

Universe-level random events

Not all randomness is tied to a command. The server’s tick loop can generate spontaneous events — equipment malfunctions, sensor anomalies, unexpected encounters, resource discoveries — by rolling against configured probability tables. These are injected as SimEvents into the event queue and arrive at clients as part of the normal snapshot stream, giving the universe a living, unpredictable quality that neither player nor AI fully controls.

Combat and Weapon Resolution

Weapon fire is resolved per-tick inside step 4.5 of SimulationController.updateVessel(). Each WeaponSystem that has a target assigned and whose fire-cycle timer has elapsed fires once per tick, subject to the following sequential checks:

1. Power check. The weapon consumes powerDraw × powerEfficiency units of vessel power. If power is insufficient, the shot does not fire and the cycle timer is not reset.
2. To-hit roll. The server rolls a d20 and applies two modifiers:
   • Crewdroid modifier — the captain’s tacticalSkill divided by 10 (integer division; baseline 50 contributes +5, max 100 contributes +10), applied only when an on-duty crewdroid is stationed at the bridge. The bridge is the ship’s tactical command center where weapon targeting systems are operated. If no crewdroid is on duty at the bridge, the skill bonus is not applied — the weapon fires with raw accuracy only. This makes crewdroid positioning a real tactical choice: pulling a droid from the bridge for EVA or damage control degrades weapon effectiveness.
   • Weapon accuracy modifier — the weapon’s accuracy stat, centred on 50: cast(int)((accuracy − 50) / 10). Accuracy 50 is neutral (±0); every 10 points above or below 50 shifts the roll by ±1.

   Full formula (with crewdroid at bridge):

     roll = d20() + tacticalSkill/10 + (accuracy − 50)/10
     hit  = (roll ≥ WEAPON_HIT_THRESHOLD)   // threshold = 12

   Full formula (no crewdroid at bridge):

     roll = d20() + (accuracy − 50)/10
     hit  = (roll ≥ WEAPON_HIT_THRESHOLD)   // threshold = 12

   At baseline with crewdroid (tacticalSkill = 50, accuracy = 50) the modifier is +5, so rolls of 7 or higher hit (70% hit rate). Without crewdroid (accuracy = 50), the modifier is +0, so rolls of 12 or higher hit (45% hit rate). A highly accurate weapon (accuracy 100) with a skilled captain (tacticalSkill 100) and crewdroid at bridge adds +10 total, making any d20 roll a hit.

3. Damage application. On a hit, applyWeaponDamage(targetId, damage) is called. The damage field on WeaponSystem is in hull-fraction units [0, 1] (e.g. 0.08 = 8% per hit). If the target’s shields are raised, damage depletes shield integrity directly (shieldIntegrity −= damage) and the hull is untouched. Otherwise, damage reduces hull integrity directly (hullIntegrity −= damage). A vessel whose hull integrity reaches zero or below is queued for destruction at end-of-tick.
4. Weapon wear. Each shot (hit or miss) degrades weaponIntegrity by a small fixed amount. A weapon at zero integrity continues to fire but may malfunction in future revisions.
5. Cycle reset. The fire-cycle timer is reset to fireCycle seconds, establishing the delay before the weapon can fire again.

Weapon stats and blueprints

Each WeaponSystem carries a set of stats rolled at instantiation time from a WeaponBlueprint. The blueprint defines ranges; the factory rolls within those ranges adjusted by quality tier. The rolled stats that influence combat are:

All rolled stats and current weaponIntegrity are persisted to MongoDB as part of the GameSnapshot in a dedicated weaponInstances array, separate from the systemHealth array used by other systems.

The Artifact Drive and Inertial Dampener

Singleships include two propulsion-related systems whose operating principles are not understood by anyone in the solar system. Both are ISystem implementations and subject to dice-modified outcomes.

Artifact Drive

The Artifact Drive produces velocities that conventional physics does not permit. It is the reason interplanetary and eventually interstellar travel is practical within a game timeframe. Key properties:

• Engagement is not guaranteed. A dice roll modified by shipAffinity and current drive integrity determines whether the drive activates on a given attempt.
• Transit range and accuracy vary. A successful engagement produces dice-modified outcomes for how precisely the ship arrives at its intended destination.
• The drive consumes drive charge — a resource tracked in ResourceState, separate from conventional fuel, that replenishes slowly and can be topped up at certain stations.
• Transit consumes fuel proportional to the distance between origin and destination zones.
• Transit takes real time proportional to distance. During transit, the vessel is in a special “in transit” state, removed from both origin and destination zones.
• The drive cannot be reverse-engineered. Human-built ships cannot be fitted with one. Ships that have been opened and modified tend to stop working.

Transit lifecycle

The full lifecycle of an Artifact Drive transit is a multi-phase process. Each phase has concrete mechanics, formulas, and failure modes.

1. Charge. The drive accumulates charge at chargeRate (default 0.03/s) toward the 1.0 maximum. Charge accumulates regardless of throttle or shield state and has no power cost. Partial charge engagement: the captain does not need full charge to transit. The required charge is proportional to distance: requiredCharge = distance / MAX_RANGE where MAX_RANGE = 250. A short 50-unit hop needs only 0.20 charge (~7s), while the longest Sol route (~183 units) needs 0.73 charge (~24s). Full charge (33s) covers any destination up to 250 coordinate units.
2. Engagement roll (see Engagement Dice Roll below). The captain issues engageDrive. The server rolls a d20 with modifiers to determine whether the drive fires. On failure, the drive does not fire, charge is preserved, and a 15-second cooldown is imposed before retry.
3. Fuel check. If the engagement roll succeeds, the server computes the fuel cost for the requested destination (see Fuel Cost Formula) and checks that the vessel has sufficient fuel. If fuel is insufficient, the engagement is rejected with status "rejected" and reason "insufficient_fuel". Charge is consumed (the drive fired) but the transit does not proceed. This is a costly mistake — the captain must wait 50 seconds to recharge.
4. Enter transit. Proportional drive charge is consumed (requiredCharge = distance / MAX_RANGE); remaining charge is preserved for future short hops. Fuel is deducted. The vessel enters the in-transit state (see In-Transit State). The drive is marked as engaged. A SimEvent of kind "arriveZone" is enqueued at currentTime + transitTime.
5. Travel. The vessel remains in transit for the computed duration (see Transit Time Formula). During this phase, drive wear accumulates each tick. No other resource drain occurs except life support.
6. Accuracy roll (see Transit Accuracy below). When the arriveZone event fires, the server rolls for landing accuracy. The result determines whether the vessel arrives at the intended zone, an adjacent zone, or a random zone with damage.
7. Arrive. The vessel exits transit, is placed in the determined arrival zone, and the drive is disengaged. Normal operations resume.

Fuel cost formula

Transit fuel cost is proportional to the Euclidean distance between origin and destination zone coordinates:

    fuelCost = FUEL_COST_PER_UNIT × distance
    FUEL_COST_PER_UNIT = 0.5

    distance = ZoneCoords.distanceTo(origin, destination)
             = sqrt((x&sub2;−x&sub1;)² + (y&sub2;−y&sub1;)² + (z&sub2;−z&sub1;)²)

The fuel check is performed after the engagement roll succeeds. If the captain does not have enough fuel, the drive fires but the transit aborts — proportional charge is consumed (the drive fired at the required level for the distance). This makes pre-flight fuel calculation important. The XO safety layer provides fuel-for-distance advisories to prevent this situation (see NPC Distance Awareness).

Transit time formula

Transit time is proportional to distance:

    transitTime = TIME_PER_UNIT × distance
    TIME_PER_UNIT = 0.35  (seconds per coordinate unit)

Representative transit table

The default Sol sector (5 zones) produces the following transit costs from common routes:

With partial charge engagement and tuned transit speed, short hops are snappy: mars-transit is a 14-second cycle. The outer-belt round trip takes ~176s. With 500 starting fuel and a 20-unit XO reserve, operational fuel is 480 — approximately 5 round trips to outer-belt or 16 to mars-transit before refueling. Leftover charge from a short hop carries over to the next jump, further reducing subsequent wait times.

In-transit state

While in transit, the vessel is in a special state with the following properties:

• No zone membership. The vessel is removed from its origin zone and is not yet in the destination zone. It does not appear in any zone’s vessel list. The vessel’s zoneId is set to "" (empty string) to indicate transit.
• Invisible to sensors. Other captains cannot see, target, or interact with a vessel in transit. The vessel does not appear in filtered game state responses.
• Invulnerable. The vessel cannot be damaged or targeted during transit. It is in Artifact Drive space, unreachable by conventional means.
• No engine/shield drain. Engine throttle is zeroed on entering transit. Shield maintenance power drain is suspended. The vessel is under Artifact Drive propulsion, not conventional engines.
• Life support continues. The captain and any active crewdroids still require life support. Life support drain continues at its normal rate (0.001/s per crew member).
• Drive wear accumulates. The drive remains engaged for the full transit duration. Self-wear at wearRate × dt per tick is the primary source of drive degradation. Cross-system wear from a degraded dampener also applies during transit.
• No commands accepted. The vessel cannot receive movement, targeting, salvage, sell, or buy commands while in transit. The only meaningful action is waiting for arrival.

Transit metadata is stored on the Vessel object: transitDestination (target zone ID), transitArrivalTime (simulation time when the arriveZone event fires). These fields enable client-side progress display (ETA countdown) and server-side validation.

Engagement dice roll

When a captain issues an engageDrive command, the server rolls for engagement success before any transit begins:

    roll = d20() + floor(shipAffinity / 10) + floor(driveIntegrity × 5) + lowChargePenalty
    lowChargePenalty = (driveCharge < 0.5) ? −2 : 0
    success = (roll ≥ ENGAGEMENT_THRESHOLD)
    ENGAGEMENT_THRESHOLD = 8

Low-charge penalty: When engaging the drive below 50% charge (emergency short-range jumps), the engagement roll takes a −2 penalty. This makes partial-charge escape jumps riskier but still possible for skilled captains with healthy drives.

Modifier breakdown:

Design intent: a healthy ship with a competent captain should transit reliably. Engagement failure is a consequence of damage, not routine. Pushing a damaged ship is risky; losing drive integrity through wear or combat makes each subsequent transit less certain.

Failed engagement: The drive does not fire. Drive charge is preserved (the drive failed to activate, not expended and missed). A 15-second cooldown is imposed before the captain can attempt engagement again. The CommandResult includes the roll details so clients can display the failure reason.

Compromised drive: If driveIntegrity ≤ 0 (isCompromised() == true), the engagement automatically fails with no roll. The drive is non-functional until repaired.

Transit accuracy

When the arriveZone event fires at the end of transit, the server rolls for landing accuracy:

    accuracyRoll = d20() + floor(shipAffinity / 10) + longDistancePenalty + lowChargePenalty
    longDistancePenalty = (distance > 100) ? −2 : 0
    lowChargePenalty    = (chargeAtEngagement < 0.5) ? −2 : 0

Low-charge accuracy penalty: When the drive was engaged below 50% charge, accuracy also takes a −2 penalty. Emergency partial-charge jumps are less precise — the captain trades navigational accuracy for speed of escape. This penalty stacks with the long-distance penalty for a maximum of −4.

At baseline (shipAffinity 50, modifier +5, distance ≤ 100): rolls of 7+ give precise arrival (70%). At long range (distance > 100, modifier +3): needs 9+ for precise arrival (60%), drift on 3–8 (30%).

A natural 1 on the d20 is always a critical failure regardless of modifiers (5% base rate). This represents the fundamental unpredictability of the Artifact Drive — even the best captains cannot fully control it.

Drift resolution: The “nearest zone” for drift outcomes is computed by coordinate distance from the intended destination, not from the origin. This means a drift on a long haul might still land the captain fairly close to where they wanted to go. The “random zone” for significant drift and critical failure is a uniform random selection from all zones in the sector excluding the origin zone.

Inertial Dampener

The Inertial Dampener is a field system that makes survival at Artifact Drive velocities and high-g combat maneuvering possible. Without it, the accelerations involved would be immediately fatal. Key properties:

• If the Artifact Drive fires while the dampener is degraded or fails, the captain and cargo take damage. The dice roll for dampener integrity is modified by evaTraining and dampener system health.
• The dampener also applies during ordinary combat maneuvering, allowing the singleship to outperform any conventional vessel in agility without killing its captain.
• Dampener failure during a transit is one of the most dangerous events a captain can face and is a meaningful risk associated with pushing a damaged ship.

Drive wear and integrity

ArtifactDriveSystem carries a driveIntegrity field [0–1] alongside its existing chargeRate and engagement state. Wear is deterministic and tick-driven; stochastic outcomes (engagement success/failure rolls) happen at command time in EngageDriveHandler and at arrival in the arriveZone event dispatcher.

Two sources of wear are applied each tick by SimulationController.updateVessel:

• Self-wear — ArtifactDriveSystem.applyTick(dt) deducts wearRate × dt from driveIntegrity while the drive is engaged. Default wearRate is 0.001/s (1000 seconds of continuous engagement to fully degrade from 1.0 to 0.0).
• Cross-system wear — after all per-system ticks, updateVessel reads the vessel’s InertialDampenerSystem.integrity and calls driveSystem.applyExternalWear(wearRate × (1.0 − dampenerIntegrity) × dt). This is linear: a fully intact dampener contributes zero cross-wear; a fully compromised dampener doubles the per-tick degradation rate.

Because the drive now stays engaged for the full transit duration, self-wear is a meaningful mechanic. Representative wear per transit:

A captain making long hauls will need to factor drive maintenance into their planning. Short hops are nearly free on drive integrity; a captain running the inner-belt/outer-belt cargo loop will need drive repair approximately every 6 round trips.

When driveIntegrity reaches 0, isCompromised() returns true. Engagement automatically fails with no roll.

Repair paths: Artifact station docking and crewdroid field repair using spareParts. Neither is implemented; driveIntegrity is in place to receive them.

Codebase

ArtifactDriveSystem and InertialDampenerSystem are both implemented as ISystem subclasses in core.system. ResourceState carries a driveCharge field; charge accumulates each tick via ResourceRegistry.accumulateDriveCharge(), called in SimulationController.updateVessel after the resource drain step. The command kind for drive engagement is engageDrive, handled by EngageDriveHandler. The existing move-vessel path remains for conventional in-Zone repositioning and docking.

Vessel gains two transit fields: transitDestination (string, target zone ID; empty when not in transit) and transitArrivalTime (double, simulation time of arrival; 0 when not in transit). A helper isInTransit() returns transitDestination != "". These fields are included in Vessel.toJSON() and persisted in vessel documents.

ZoneCoords (in core.zone) gains a distanceTo(ZoneCoords other) method returning the Euclidean distance. Constants FUEL_COST_PER_UNIT (0.5) and TIME_PER_UNIT (0.35) are defined in core.controller or commands.engageDriveHandler.

The engageDrive event dispatch path in SimulationController is expanded: compute distance, roll engagement, check fuel, deduct fuel, enter transit, enqueue arriveZone event. A new event kind "arriveZone" is dispatched at the scheduled arrival time: roll accuracy, place vessel in determined zone, disengage drive.

Both driveIntegrity (on ArtifactDriveSystem) and integrity (on InertialDampenerSystem) are persisted to MongoDB via the SystemHealthRecord struct added to db.gameStateRepo. GameSnapshot carries a systemHealth array (one record per system-id); snapshot() and restore() in SimulationController read and write it. The systemHealth key is absent in snapshots written before this feature was added; GameSnapshot.fromJSON defaults to an empty array for backward compatibility. The in-memory reset path (captureSystemEvents) also captures and replays driveIntegrity via a "setDriveIntegrity" SystemControlEvent.

Weapon Systems and Combat

WeaponSystem as ISystem

WeaponSystem is a concrete subclass of ISystem, living in core.system alongside EngineSystem, ShieldSystem, ArtifactDriveSystem, and InertialDampenerSystem. Like all systems it is owned by the SystemRegistry inside SimulationController and keyed by a string system ID. The ISystem contract (“what vessel do you belong to?”, “are you compromised?”) is the only interface the combat loop needs; the rest of the field set is WeaponSystem-specific and only touched by the combat subsystem and the two targeting commands.

Standard issue: the Pulse Lance

Each singleship has exactly one weapon mount point. The Artifact issues every new singleship with a Pulse Lance — a directed-energy weapon integrated at fabrication. The Pulse Lance is the sole Artifact weapon template currently in use. The blueprint system supports multiple templates (random selection from the pool of Artifact blueprints weighted by quality tier), but only one template is registered at present; additional Artifact weapon designs are a future expansion hook.

Weapon acquisition and swapping

Human-manufactured weapons are purchasable at market stations. Because each singleship has a single mount point, acquiring a new weapon requires selling or discarding the currently installed weapon and installing the replacement — a swap, not an addition. The transaction happens at a market station and is modeled as a future command kind (swapWeapon): validate that the vessel is docked at a station with a market, verify the captain has sufficient Credits, remove the old weapon instance, deduct Credits, and instantiate the new weapon from its blueprint.

A captain who swaps their Artifact-issued Pulse Lance for a human-manufactured weapon cannot recover it. The Artifact replaces the weapon only when it replaces the entire ship (respawn after destruction). This makes the swap decision strategically significant: human weapons offer variety and repairability at the cost of the Pulse Lance’s reliability and efficiency.

Blueprints — reference data, not simulation state

WeaponBlueprint is a read-only template struct stored in the weaponBlueprints MongoDB collection. The server loads all blueprints at startup into an in-memory BlueprintRegistry; the running simulation never writes back to that collection. A blueprint carries:

• Identity: blueprintId, name, description, category ("artifact" | "human"), isArtifactWeapon.
• Stat ranges: damageMin/Max, accuracyMin/Max, fireCycleMin/Max, powerDrawMin/Max. Final stats are rolled within these bounds at instantiation time.
• Human-weapon penalties: malfunctionChance, powerEfficiency (< 1.0 = less efficient), requiresSpareParts. All are zero / 1.0 / false for Artifact weapons.
• Quality tiers: a QualityTierEntry[] array, each with a tier name ("standard" | "superior" | "exceptional"), a statMultiplier applied to every rolled stat, and a weight for the random draw.

Blueprints are managed by db.blueprintRepo.BlueprintRepository : IBlueprintStore (MongoDB backend) and core.blueprint.BlueprintRegistry (in-memory lookup). The repository uses the weaponBlueprints collection with upsert semantics; the registry provides get(id), byCategory(cat), and artifactBlueprintIds() helpers.

Instantiation — what gets rolled, what stays fixed

The factory function instantiateWeapon(blueprint, vesselId, dice) (in core.weapon) is called by buildScenario() when arming a vessel. It is the sole site where randomness is introduced into weapon state. The lifecycle of each field is:

Known gap: The rolled combat stats (damage, accuracy, fireCycle, powerDraw, qualityTier) are part of the structural skeleton and are not in the GameSnapshot. If the server’s Dice instance is not seeded deterministically, a cold start produces different rolled stats than the previous run. Adding a seeded or recorded roll to the snapshot is a deferred milestone.

Combat loop — what happens each tick

Step 4.5 of SimulationController.updateVessel(vesselId, dt), inserted between the per-system applyTick pass and the final ResourceRegistry.setState call, runs the weapon fire cycle:

1. For each WeaponSystem on the vessel: skip if isCompromised or targetId is empty.
2. Decrement cycleTimer by dt. Skip if still positive (weapon is still on cooldown).
3. Compute powerCost = powerDraw × powerEfficiency. Skip if the vessel’s current power is insufficient.
4. Deduct powerCost from the local ResourceState being accumulated for this tick.
5. Check for an on-duty crewdroid at the bridge (the ship’s tactical command location). If present, compute roll = d20.roll() + captainTacticalSkill / 10 + (accuracy − 50) / 10. If no crewdroid is on duty at the bridge, compute roll = d20.roll() + (accuracy − 50) / 10 (no skill bonus).
6. If roll ≥ WEAPON_HIT_THRESHOLD (12), call applyWeaponDamage(targetId, weapon.damage).
7. Degrade weaponIntegrity by HUMAN_WEAPON_WEAR_PER_SHOT (0.01) per firing cycle regardless of hit or miss. (Artifact weapon wear rates are differentiated via the blueprint’s field values; the 0.01 constant applies to human weapons. Artifact weapons have negligible wear by design.)
8. Reset cycleTimer = fireCycle.

Because the tick fiber and HTTP handlers share one OS thread under Vibe.d’s cooperative scheduler, no mutex is needed. Resource changes within step 4.5 are written to the resources local copy and committed together with all other per-tick changes in the single setState call at step 5, making each tick’s resource accounting atomic.

Damage model

applyWeaponDamage(targetVesselId, damage) is a private method on SimulationController. The damage value on WeaponSystem is in hull-fraction units [0, 1] (e.g. 0.08 means 8% of full integrity per hit). Damage is applied directly without division. Resolution proceeds in two phases:

• Shield absorption: If the target has a ShieldSystem in ShieldState.raised and not compromised, shieldIntegrity −= damage, clamped to 0. No hull damage occurs. A shield at zero integrity on the next hit is compromised and passes all damage to the hull.
• Hull damage: vessel.hullIntegrity −= damage, clamped to 0. If the result is ≤ 0 and the vessel is not already in the destruction queue, its ID is appended to _destroyedThisTick.

Deferred destruction and the tick loop

Vessel destruction cannot happen synchronously inside the foreach (vesselId, _; byVessel) iteration in tick() because removing a vessel from ResourceRegistry during iteration mutates the associative array being iterated. Instead, applyWeaponDamage pushes the ID into a private string[] _destroyedThisTick scratch buffer (with a canFind dedup guard to handle multiple weapons targeting the same vessel in the same tick). After the per-vessel loop completes, tick() iterates _destroyedThisTick and calls destroyVessel(id) for each entry.

destroyVessel(vesselId): creates a Wreck entity from the vessel’s zone, class, hull integrity, and current cargo; adds it to WreckRegistry; clears every other vessel’s WeaponSystem.targetId that references the destroyed vessel; removes the vessel from EntityManager and its resource state from ResourceRegistry.

Targeting commands

Two command kinds manage WeaponSystem.targetId directly without enqueueing SimEvents — targeting is a pure system-state mutation with immediate effect, consistent with the architecture’s pattern of “direct mutation for system state, SimEvents for deferred domain changes”:

Engine System and Consumption Scaling

The EngineSystem carries a maxPower field (default 1000 for the standard singleship) that acts as a consumption scalar. All engine-related fuel and power drain is multiplied by maxPower / 1000, allowing future ship classes with larger or smaller engines to consume proportionally more or fewer resources without changing the base rate constants.

    fuelUse  = (maxPower / 1000) × baseFuelRate × throttle × dt
    powerUse = (maxPower / 1000) × basePowerRate × throttle × dt

    baseFuelRate  = 1.0  (units per second at full throttle, standard engine)
    basePowerRate = 1.0  (units per second at full throttle, standard engine)

At maxPower = 1000 (standard singleship), the multiplier is 1.0 and behavior is identical to the hardcoded rates used prior to this change. A future heavy cruiser with maxPower = 2000 would consume fuel and power at double the rate; a scout with maxPower = 500 would consume at half the rate.

Implementation note: The existing Vessel.update() hardcodes rates of 1.0. The change is to read maxPower from the EngineSystem in the systems array and apply the multiplier. The ResourceRegistry.consumeForEngines() helper already accepts configurable rate parameters and can be used as an alternative call site.

Power Balance

Power is the critical operational bottleneck for a singleship in combat. It is consumed by engines, shields, shield regeneration, and weapon fire. The balance between starting power, shield maintenance cost, and combat drain rates determines how long a captain can sustain combat operations before being forced to disengage or face systems failure.

Starting power: 350

The standard singleship blueprint provides 350 starting power (increased from 200). This change reflects the design intent that a singleship should be able to sustain a meaningful combat engagement without power being exhausted before tactical decisions can play out.

Shield maintenance: 0.5 power/sec

Shield maintenance rate remains at 0.5 power/sec while raised. This is a significant ongoing cost that forces a real tradeoff between defensive posture and operational endurance. Shields are not free — running them continuously drains operational reserves.

Combat endurance calculations

The 233-second combat window at full engagement is long enough for multi-round weapon exchanges and tactical maneuvering, while still creating pressure to manage power reserves. A captain who enters combat with depleted power from extended shield use or engine running is at a real disadvantage.

Refueling economics at 350 power

At Earth (cheapest station): full power refill = 350 × 12 CR/unit = 4,200 CR. At outer-belt (most expensive): 350 × 25 = 8,750 CR. The emergency stake (1,000 CR) buys approximately 83 power units at Earth prices — enough to restore meaningful operational capability but not a full tank.

Blueprint change

ShipBlueprint.standardSingleship() in core/artifact.d is updated: resources.power changes from 200.0 to 350.0. The audit document’s refueling costs (Section 4.4) should be recalculated with the new value. Existing vessel documents in MongoDB will retain whatever power level they had at their last save; only newly fabricated ships receive the new default.

Economy and Credits

The simulation has a functional economy. Captains earn by extracting resources or hauling cargo; they spend on supplies, equipment, and crewdroids. The economic layer is intentionally lightweight — the point is to create meaningful tradeoffs and motivate activity, not to simulate a full market economy.

Credits

Credits are the interoperable currency of the solar system, not issued by any one faction. Credits live on the Character record, not on the ship — because a captain survives the loss of their ship (the Artifact replaces it), but their financial position carries forward. A captain who loses their ship is not broke; they are shipless.

Income: extraction operations

Crewdroids can be dispatched on EVA to an asteroid, ice body, or other raw resource. The extraction command produces cargo at a dice-modified yield and quality. Higher engineeringSkill improves yield; the environment difficulty sets the base difficulty threshold.

Income: cargo hauling and contracts

Captains can accept cargo contracts from factions, stations, or other captains. Delivery is a standard command sequence: pick up, transit, dock, deliver. Payment is recorded in Credits against the captain’s Character.

Spending

• Supplies — life support consumables, spare parts, drive charge top-ups — purchased at stations.
• Crewdroids — human-manufactured droids are available for purchase at certain stations. They are functionally inferior to Artifact-issued droids and do not exhibit the same behaviors, but they are available and replaceable. Artifact droids that are lost are only replaced by the Artifact itself upon ship re-issue.
• Information and access — docking rights, sensor upgrades, faction introductions, intelligence on other captains.

Station commerce: buying supplies

The buySupplies command lets a captain spend Credits to purchase fuel, power, life support, or spare parts at a market station. The command payload specifies the vessel, station, resource type, and amount. The server validates that the vessel is in a zone with the specified market station, checks the captain’s CR balance against the total cost, deducts Credits, and adds the purchased resource amount to the vessel’s ResourceState.

Per-resource pricing is defined on Station with one price field per purchasable resource: fuelPricePerUnit, powerPricePerUnit, lifeSupportPricePerUnit, sparePartsPricePerUnit. Each has a sensible default so that stations without explicit pricing still function. The existing creditsPerCargoUnit on SellCargoHandler provides the model for this pattern.

Faction-based price variation and dynamic supply/demand pricing are noted as future enhancements. The initial implementation uses flat per-unit prices.

Codebase

Character has a credits field persisted in MongoDB via CharacterRepository. ResourceState has a cargo field for generic extractable/tradeable material. Station entities (with hasMarket flag) exist in core.station and are managed by StationRegistry inside SimulationController. The implemented sell command is sellCargo, handled by SellCargoHandler: it validates zone co-location and enqueues a cargo-deduction SimEvent, while the server layer applies the Credits to the captain’s Character record after the command is accepted (Option C two-phase pattern). The buySupplies command follows the same two-phase CR-deduction pattern. Per-station pricing and extraction commands are future work.

Crewdroids

Every ship, including the smallest singleship, is assigned at least two crewdroids. They are not Characters — they are simulation entities (Crewdroid extends Entity) managed by the EntityManager, with an energy model representing their charge level drawn from the ship’s power bus.

Roles

A droid’s role can be changed at runtime (setRole), subject to current energy and any active task.

Energy and work

All droid activity costs energy (performWork(energyCost)). A droid that lacks sufficient charge cannot perform work. Energy is replenished from the ship’s power bus (recharge(amount)), meaning crewdroid activity competes with engines, shields, life support, and drive charge for available power — a real resource tradeoff.

Dice-modified outcomes

performWork() is the dice hook. Beyond the energy check, the success and quality of a work outcome is determined by a server-side roll modified by the droid’s current role, the captain’s relevant stat, and environmental difficulty.

Group mechanics: defense and boarding

Mob defense: When a boarding party enters the ship, Security and General droids form a defensive mob. The group roll is a single die modified by the number of combat-ready droids and their aggregate energy, tested against the boarding party’s attack difficulty. Outcomes are graduated: critical success, success, partial success, failure, critical failure.

EVA boarding support: EVA-capable droids can assist in or conduct boarding operations against another ship. The attack roll is modified by squad size, energy levels, and the captain’s evaTraining stat.

Registry

Crewdroids are registered in the EntityManager as typed entities, with a dedicated CrewdroidRegistry providing per-ship lookup and group queries (artifact-issued vs. recruited). The existing CrewRegistry and its Actor/CrewMember hierarchy are being converged into the crewdroid model: the activity-state FSM from CrewMember will be incorporated into the unified Crewdroid type so that all shipboard agents share a single entity class with energy, role, EVA capability, and activity tracking.

Conquest and Salvage

When a ship’s hull reaches zero, it becomes a Wreck entity in the simulation rather than being removed. The conquering captain’s crewdroids can then conduct salvage operations against it.

Cargo salvage

EVA droids dispatched to a wreck can extract cargo, supplies, and spare parts. The server tracks a true condition for every salvageable item, but the initial report to the salvaging captain is a dice-modified estimate. As droid examination time accumulates, the estimated condition converges toward the truth. A captain who rushes a salvage operation may load damaged goods without knowing it; one who takes time gets a more accurate picture — but time has costs of its own.

Droid recruitment

The conquered ship’s crewdroids, if intact, can be offered a choice. This is a dice roll modified by the recruiting captain’s commandSkill. Success adds those droids to the captain’s complement; failure leaves them inert or resistant. Recruited droids carry a small reliability penalty on critical tasks that diminishes with accumulated service time. They were made for someone else, and they seem to know it.

Module salvage (future milestone)

The intended long-term design allows crewdroids to extract discrete ship modules from a wreck — engine components, shield emitters, sensor arrays — and attach them to the salvaging ship. This requires a ShipModule type and ModuleRegistry not yet in the codebase. Cargo-only salvage is the first implementation; module extraction is explicitly deferred and documented here as the planned next layer.

Codebase

A Wreck entity type is created when a Vessel’s hull reaches zero during combat resolution. New command kinds: scavengeWreck, recruitDroids. Crewdroid gains optional originalShipId and loyaltyLevel fields. The server tracks trueCondition and observedCondition per salvageable item; a WreckExaminationHandler improves the observed value toward truth with each dice-modified examination step.

The Artifact

The Artifact is a unique station that appeared in high Earth orbit without explanation. It is the physical anchor of the early game and the mechanical foundation of the spawn/respawn loop.

What it does

• Fabricates ships. A character who has no ship assigned — whether new to the simulation or returning after a loss — docks at the Artifact and is issued a fully equipped singleship with the captain sealed inside its lifepod, two Artifact-issued crewdroids, and both the Artifact Drive and Inertial Dampener pre-installed. The one-ship-per-captain rule is enforced by the Artifact itself.
• Repairs and refits. A ship docked at the Artifact can be restored. Repair quality and completeness are dice-modified.
• Holds blueprints. The Artifact’s ShipBlueprint registry defines the ship classes it can produce. Initially only the singleship is registered; additional classes can be unlocked or discovered.

Spawn and respawn

Character.homeArtifactId (defaulting to "artifact-earth-orbit") records which Artifact a character is anchored to. When a ship is destroyed, the captain’s lifepod ejects and returns autonomously to the home Artifact for re-fabrication. Loss of a ship is a setback that costs time and possibly Credits, not existence.

Command integration

The Artifact is an Entity in the simulation. Interactions (dock, request fabrication, request repair) are modeled as CommandRequests routed through the standard dispatcher with dedicated CommandHandler implementations.

Server Owns the Clock

The server runs an autonomous tick loop. Clients do not trigger simulation steps.

• The server advances simulation time at a fixed or semi-fixed interval (target: configurable, e.g. 100–500 ms wall time per tick).
• Each tick: processes all queued SimEvents whose scheduled time has arrived, updates resource consumption and system state for every active vessel, generates any universe-level random events, then produces outgoing snapshots for connected clients.
• Clients submit commands at any time; commands are queued and processed on the next eligible tick.
• The desiredExecuteTime field on CommandRequest allows clients to schedule actions at a future simulation time, within reason.

Current status: The tick loop is implemented as a server-driven Vibe.d background fiber (SectorServer.tickFiber()). The tick interval is configurable via tick_interval_ms in galaxy.cfg. There is no client-driven tick endpoint.

Simulation Lifecycle (GM API)

Three GM-only HTTP endpoints let an operator control the running simulation without restarting the process. All three require an authenticated session with simRole == "gm"; sessions with role "pc" or "npc" receive 403 Forbidden.

Each endpoint returns {"status": "paused"|"running"|"reset", "elapsedTime": <double>}.

Role enforcement

SectorServer.checkGmAuth() is a private helper that first calls checkAuth() (returns 401 if no session) and then checks sess.get("simRole") == "gm" (returns 403 if not). Only users authenticated from a storyteller account of type "admin" receive simRole == "gm"; guest (pc) and user (npc) accounts are rejected.

Reset scope and known limitation

reset() restores the mutable GameSnapshot layer. ISystem fields — engine throttle, shield state — are outside the snapshot contract and are therefore not restored. A future deep reset milestone will replay the initial system-control events from buildScenario() so that throttle and shield state are also consistent after a reset. See SESSION.md known issue 2 for design notes.

Baseline capture

SectorServer calls SimulationController.captureInitialSnapshot(sectorId) once in its constructor, immediately after buildScenario() and before the MongoDB restore. This locks in the buildScenario initial values as the reset target. The baseline snapshot is stored in memory only and is never written to MongoDB.

Persistence and Recovery

The server maintains a periodic snapshot of all mutable simulation state so that it can survive cold starts, crashes, and planned restarts without losing more than a few seconds of progress.

What is snapshotted

The simulation uses a dual-path persistence model. Two complementary stores capture different aspects of the world:

• GameSnapshot (fast, frequent) — the monolithic sector snapshot written every 5 seconds. It captures the simulation clock (elapsedTime), the pending SimEvent queue, per-vessel resource levels, wreck loot state, system health, and weapon instance data. This is the crash-recovery safety net: at most 5 seconds of progress can be lost.
• Vessel documents (durable, lifecycle-driven) — individual documents in the vessels MongoDB collection, one per vessel. Each document captures the full vessel definition: zone placement, resources, systems, crewdroid roster, and LocationGraph. Vessel documents are written at natural lifecycle boundaries: captain disconnect, graceful server shutdown, and onboarding. They are the canonical long-term store.

Sector infrastructure — zones, stations, and wrecks — is persisted in three per-sector MongoDB collections (zones, stations, wrecks), each document carrying a sectorId field for multi-sector filtering. On startup, the server loads sector infrastructure from these collections via ISectorStore and passes the loaded data to buildScenarioFromData(), which constructs the SimulationController with zones registered by named string key via Galaxy.addZone(). If the collections are empty for the configured sector_id, the server auto-seeds the default Sol scenario (two zones, two stations, two wrecks) before proceeding. A GM endpoint (POST /sector/seed) can re-seed at any time.

Characters are persisted independently in the global characters collection (see Persistent Entities).

Snapshot frequency and storage

A GameSnapshot is written to MongoDB every 5 wall-clock seconds, checked at the end of each tick handler. A snapshot is also written immediately on graceful shutdown (SIGTERM or SIGINT). The snapshot for a sector is stored as a single document in the gameState collection, keyed by sector-id, and upserted on each write so there is at most one document per sector at all times.

Vessel documents are written to the vessels collection at lifecycle boundaries only (not on the 5-second tick). Each vessel document carries a lastSaved ISO-8601 timestamp.

Startup sequence

The startup sequence reconstructs the world in layers:

1. Load sector infrastructure (zones, stations, wrecks) from MongoDB for the configured sector_id via ISectorStore. If no data exists, auto-seed the default Sol scenario (two zones, two stations, two wrecks) via seedDefaultSector(). Pass the loaded data to buildScenarioFromData(), which constructs the SimulationController with zones registered by named string key. No vessels or characters are created. On a cold start with an empty MongoDB, the galaxy contains no ships.
2. Load all vessel documents from the vessels collection. For each document, reconstruct the in-memory Vessel, its systems, crewdroids, and LocationGraph.
3. Load all character documents from the characters collection. Bind each character to its assignedVesselId if present.
4. Attempt to load a GameSnapshot for the configured sector_id. If one exists and its capturedAt timestamp is newer than a vessel document’s lastSaved, overlay the snapshot’s resource/system/wreck state onto the in-memory objects (the snapshot wins for crash recovery). If no snapshot exists, proceed with the state loaded from vessel documents.
5. Log “resumed with N vessels, M characters” or “cold start — empty galaxy” as appropriate.

Graceful shutdown

SIGTERM and SIGINT are caught by an extern(C) nothrow @nogc signal handler that sets an atomic flag (g_shutdown). The background tick fiber polls this flag after every tick: if set, it writes a final snapshot, stops the HTTP listener, and exits the event loop. Because the fiber runs continuously, a SIGTERM is handled promptly regardless of HTTP activity.

Multi-server sector isolation

Each server instance is assigned a sector_id in its configuration file (e.g. sector_id=sol). The gameState collection is filtered by sector-id, so multiple server instances sharing a MongoDB cluster do not interfere with each other’s simulation state. The characters collection is intentionally global and unscoped — a captain’s identity and financial position belong to the simulation at large, not to any particular sector server.

Codebase

db.gameStateRepo defines GameSnapshot and its component record types (ResourceStateRecord, WreckStateRecord, SimEventRecord), the IGameStateStore interface, and MongoGameStateStore. db.sectorRepo defines ISectorStore and MongoSectorStore for sector-scoped CRUD on the zones, stations, and wrecks collections. SimulationController has snapshot(sectorId) and restore(snap) methods. SectorServer wires snapshot writes into the constructor (restore on startup) and tick handler (periodic + shutdown). app.d registers the signal handlers and passes the shutdown flag pointer to the server.

Persistent Entities: Characters and Vessels

Characters and vessels are MongoDB-first entities. They exist as durable documents in their own collections, independent of buildScenario(), and survive server restarts without any snapshot overlay. This is the foundation of the persistent world model: a fresh MongoDB means an empty galaxy with no ships; the first captain to connect gets a ship manufactured by the Artifact.

buildScenario() scope

buildScenario() is world-only. It creates zones, planets, stations, wrecks, and celestial bodies — the structural geography that exists regardless of whether anyone is flying in it. It does not create vessels, crewdroids, or characters. Those are player/NPC-owned data loaded from MongoDB or created through the onboarding flow (see Captain Lifecycle).

MongoDB collections

The persistent world uses four MongoDB collections, three of which are shared across all galaxy server instances:

Vessel document schema

Each vessel document captures everything needed to reconstruct a fully functional vessel in memory without buildScenario():

• Identity: vesselId, shipClass (e.g. "singleship"), captainId (back-reference to owning character).
• Position: zoneId, sectorId.
• Hull: hullIntegrity [0–1], maxHull, armorRating.
• Resources: fuel, power, lifeSupport, spareParts, driveCharge, cargo.
• Systems: Array of system records (engine, shield, drive, dampener, weapon), each with type, ID, and health/integrity fields. Weapon entries include the full WeaponInstanceRecord (blueprint provenance, rolled stats, integrity).
• Crewdroids: Array of crewdroid records (ID, name, role, energy, maxEnergy, current location, activity state).
• LocationGraph: Array of location nodes and adjacency edges, sufficient to rebuild the ship’s internal spatial graph.
• Stasis: inStasis (boolean), stasisSince (ISO-8601 timestamp, null if not in stasis).
• Metadata: createdAt, lastSaved (ISO-8601 timestamps), blueprintId (which ShipBlueprint produced this vessel).

Conflict resolution: snapshot vs. vessel document

Because the GameSnapshot is written every 5 seconds and vessel documents are written only at lifecycle boundaries, a crash may leave the snapshot more recent than the vessel documents. On startup, the server applies a simple conflict rule: load vessel documents first (they are the canonical store), then overlay the GameSnapshot if its capturedAt timestamp is newer than a vessel document’s lastSaved. This ensures that crash recovery never loses more than 5 seconds of progress while keeping vessel documents as the long-term source of truth.

Artifact blueprint system

The Artifact station fabricates new singleships from a ShipBlueprint (already stubbed in core/artifact.d). The standard singleship blueprint defines:

• LocationGraph layout: bridge, corridor1, engineering (connected), lifepod (isolated).
• System complement: engine, shield, Artifact Drive, inertial dampener, Pulse Lance weapon.
• Initial resources: fuel, power, life support, spare parts at default starting levels; drive charge at zero; no cargo.
• Crewdroid complement: two Artifact-issued crewdroids (General role), placed at bridge and engineering.

The blueprint is used by the onboarding endpoint to fabricate a new vessel when a captain has no assigned ship. Additional blueprints (larger ships, specialised variants) can be registered in the Artifact’s BlueprintRegistry as a future expansion.

Codebase implications

core/composition.d: buildScenario() is refactored to world-only. Vessel, crewdroid, and system creation code moves to a new fabricateVessel(blueprint, captainId, zoneId) function used by the onboarding endpoint. db/gameStateRepo.d: gains VesselDocument struct with toJSON()/fromJSON(), IVesselStore interface, and MongoVesselStore implementation. characters/characterLoad.d: the existing ICharacterStore is enhanced with lookup-by-username and vessel-binding fields.

Captain Lifecycle: Onboarding, Session, and Disconnect

A captain’s relationship with the galaxy server follows a defined lifecycle: authenticate, onboard (create or reconnect), operate, and disconnect (graceful or detected). This section specifies each phase and the mechanisms that enforce session integrity across the fleet.

Single active logon

Only one active session per username is permitted at a time, across all galaxy server instances. This prevents a captain from being “in two places at once” and avoids the race conditions that would arise from duplicate command streams for the same vessel.

• Enforcement mechanism: The activeSessions MongoDB collection stores one document per logged-in username: { "_id": "<username>", "serverId": "<sector_id>", "loginTime": <ISO-8601>, "lastHeartbeat": <ISO-8601>, "vesselId": "<vesselId>" }.
• On POST /login: After credential validation succeeds, the server checks activeSessions for the username. If a document exists with a lastHeartbeat within 30 seconds, the login is rejected with 409 Conflict (“Account already logged in”). If the heartbeat is stale (older than 30 seconds), the document is treated as abandoned and overwritten.
• GM force-kick: A login from a GM account (simRole == "gm") always succeeds. If a session exists for the same username, it is removed (the previous session becomes invalid). This allows administrators to recover from stuck sessions.
• Heartbeat: Every authenticated API call updates lastHeartbeat on the caller’s activeSessions document. Under future WebSocket transport, the connection itself provides liveness signalling.
• Removal: The document is deleted on explicit logout or on disconnect detection (see below).

Onboarding: POST /onboard

The onboarding endpoint is the single entry point for a captain joining the simulation. It handles both first-time captains and returning captains.

Response payload: { "characterId": "...", "vesselId": "...", "zoneId": "...", "isNewCaptain": true|false }.

All clients (PC and NPC) call POST /onboard after authentication. The endpoint is idempotent for returning captains.

Disconnect detection and the stasis shield

When a captain disconnects — whether by closing the client, losing network, or crashing — the server activates a stasis shield around their vessel. This is an Artifact-origin protective mechanism: the lifepod detects that the captain has gone dormant and the ship’s Artifact systems autonomously project a defensive field that suspends all operations.

Detection

The server tracks lastActivity per authenticated session. Every API call refreshes this timestamp. A background check, piggybacked on the tick loop (every ~5 seconds), scans for sessions whose lastActivity exceeds the configurable disconnect_timeout_s (default: 60 seconds). Under future WebSocket transport, a closed connection triggers immediate disconnect handling.

Stasis effects

• The vessel becomes invulnerable: it cannot be damaged, targeted, boarded, or interacted with by other captains.
• Resource consumption stops: engine throttle is zeroed, shields are lowered (the stasis field replaces them), fuel/power/life-support drain ceases.
• Crewdroids enter a dormant state (activity FSM transitions to a dormant pseudo-state; they resume their prior activity on reconnect).
• The vessel remains visible in the zone. Other captains can see a stasis-shielded ship on sensors but cannot interact with it. The game state JSON includes "stasis": true on the vessel object.
• Character.controlMode transitions to "idle".
• The captain’s activeSessions document is removed.
• The vessel document is written to MongoDB (lifecycle boundary write).

Tactical implications

The stasis shield offers complete protection but no tactical awareness. A captain who disconnects in the open — in a contested zone, near a station under dispute, or in proximity to hostile vessels — will return to find the universe moved on around them. Enemies can position themselves around a stasis-shielded vessel, waiting for the captain to reconnect and the shield to drop. Wise captains who anticipate going dormant will first move to a safe location: deep in friendly territory, docked at a station, or in an uncontested corner of an empty zone. Going into stasis without taking precautions is a calculated risk. The Artifact protects the ship; it does not protect the captain’s position.

Duration

There is no time limit on stasis. A vessel can remain in stasis indefinitely until its captain reconnects. The persistent world holds a ship’s place regardless of how long its captain is away.

Reconnect and recovery

When a captain reconnects (authenticates and calls POST /onboard), the stasis shield drops and normal operations resume. The Artifact’s restorative properties provide a reconnect recovery bonus: a modest boost to hull integrity and resource levels (configurable; approximately +5% hull, +10 fuel, +10 power, +10 life support), representing the beneficial effects of the stasis field’s dormancy period. controlMode is restored to the appropriate active mode ("humanGui" or "aiAgent").

HTTP route access control

Every HTTP route has an explicit access level. Routes not listed as public require an authenticated session cookie; routes marked GM-only additionally require simRole == "gm".

Implementation: SectorServer.checkGmAuth() (existing) handles the GM check. A new checkAuth() wrapper is applied to all authenticated routes. The activeSessions heartbeat update is applied as middleware on every authenticated API call.

Transport Layer

See also: Transport and Server Communication in the Client Architecture document for the client-side transport abstraction and server API evolution plan.

REST (HTTP)

Used for low-frequency, request/response interactions: authentication, character management, high-level one-off orders, on-demand state snapshots, and admin/GM operations including simulation lifecycle management (POST /simulation/pause, /simulation/resume, /simulation/reset).

WebSocket (planned)

Used for the high-frequency real-time channels:

• Client → server: time-stamped control frames at ~100–200 ms intervals (throttle, heading, weapon state, drive engagement intent, etc.).
• Server → client: snapshot deltas at each tick — authoritative vessel state, sensor-filtered nearby entities, economy and cargo updates.

Current status: Only the REST channel exists. WebSocket support is a future milestone; Vibe.d supports it natively.

Command Protocol

What clients send

Each command is a CommandRequest with: commandId, originType ("pc", "npc", "gm", "system"), originId, kind, payload, requestTime / desiredExecuteTime, and schemaVersion. No packet directly sets position, resource values, enemy state, or dice results.

Implemented command kinds: moveCrewdroid (captain directive to reposition a crewdroid within the vessel — crewdroids are autonomous enough to position themselves for routine tasks, but the captain can explicitly order a droid to a specific location for tactical reasons such as damage control, EVA staging, or weapons station manning), engageDrive (Artifact Drive engagement), salvageCargo (EVA cargo extraction from a wreck), sellCargo (sell all held cargo at a market station), engageTarget (arm a weapon system against a target vessel), ceaseTarget (disarm a weapon system). Planned future kinds include: setThrottle, dockAtArtifact, extractResource, buySupplies, swapWeapon, buyCrewdroid, scavengeWreck, recruitDroids.

What the server returns

Each command produces a CommandResult with a status ("accepted", "rejected", "partial", "error"), a details payload, and where applicable the dice roll record from resolution.

Routing

CommandRequest → CommandApi → CommandDispatcher → CommandHandler (one per kind) → CommandResult. Adding a new command type means implementing a CommandHandler subclass and registering it; the dispatcher and API are unchanged.

Server-Side Invariant Enforcement

• No negative resources. Fuel, power, life support, drive charge, and Credits are all clamped at zero.
• No teleportation. Position changes are integrated from velocity only.
• Physics limits. Max acceleration, turn rate, cooldowns, and power budgets are enforced server-side.
• Conservation rules. Resource transfers between vessels must balance.
• No client-side dice. All random rolls happen on the server.
• One ship per captain. The Artifact enforces this at fabrication time.
• Wreck condition opacity. True condition of salvageable items is never sent directly; only the examined/estimated condition is included in snapshots, improving with each examination step.

NPC Scaling

NPCs are headless clients running the same control protocol as PC clients. Scaling NPC population means adding more AI worker processes, not scaling the server core. Character.isHeadlessOnly marks NPCs that should never receive a UI snapshot. The NPC and PC client architectures are detailed in Client Architecture.

NPC distance-aware destination selection

With distance-based transit, NPC pickDestination() must incorporate transit cost into destination selection. The previous approach — selecting destinations based solely on expected profit and safety — no longer works because a high-value wreck in the outer belt is not worth pursuing if the captain cannot afford the fuel or the transit time makes the effective profit rate low.

Cost-benefit scoring

Each candidate destination is scored by expected profit per unit time:

    score = expectedProfit / (chargeTime + transitTime + operationTime)

    chargeTime   = 33   (flat, seconds at 0.03/s)
    transitTime  = distance × TIME_PER_UNIT  (0.35 s per unit)
    operationTime = 30  (estimated salvage/sell cycle, seconds)
    expectedProfit = estimated cargo value at destination (from zone summaries)

The NPC selects the destination with the highest score, subject to fuel feasibility.

Fuel feasibility check

Before considering a destination, the NPC checks:

    fuelCost = FUEL_COST_PER_UNIT × distance
    available = currentFuel − FUEL_LOW_THRESHOLD  (20.0)
    feasible = (fuelCost ≤ available)

Destinations that cannot be reached with available fuel are excluded entirely. This prevents NPCs from stranding themselves in remote zones.

XO fuel-for-distance advisory

The XO safety layer (clientLib/xo/safety.d) provides a distance-aware fuel advisory. Instead of the simple FUEL_LOW_THRESHOLD check, the XO computes the fuel cost to return to the nearest Artifact-affiliated station and warns or rejects navigation goals when remaining fuel would be insufficient for the return trip. This is a soft advisory (the captain can override it), distinct from the server-side hard fuel check that prevents engagement when fuel is strictly insufficient.

Economic loop timing comparison

The distance-based system significantly changes NPC economic loop timing. Representative full trade cycles (salvage at wreck zone, sell at market, return to refuel):

Short loops near Earth remain quick and cheap. Long-haul outer-belt runs take roughly double the time and consume 36% of starting fuel per cycle. The scoring formula naturally steers NPCs toward nearby profitable destinations when fuel is limited, and toward high-value distant runs when they have a full tank.

Ship-to-Ship Communication

Status: deferred. The initial NPC client will operate on game state alone, without communication capabilities.

When implemented, ship-to-ship communication will use a controlled vocabulary / signal system rather than free-form text. The vocabulary includes structured signal types: hail, threat, trade request, distress, surrender, and similar predefined intents. This approach keeps the protocol machine-readable and ensures NPC captains can participate in communication on equal footing with PC captains.

The final NPC client should have full comms capabilities so that it behaves identically to a PC client from the server’s perspective. The communication system will be modeled as a command kind (e.g. sendSignal) with a payload specifying the signal type, target vessel, and any structured parameters. Received signals will appear in the game state snapshot for the recipient vessel.

Sensor Visibility and Information Limits

Status: implemented (zone-scoped, Phase 1). The filtered state endpoint GET /game/state?vessel={vesselId} returns zone-scoped data. The unfiltered endpoint (no query parameter) remains available for GM tools.

Zone-scoped visibility model

A captain sees all entities in their current zone at full accuracy: vessels, stations, wrecks, and planets. Nothing outside the current zone is included in the detailed data. This is the fundamental fog-of-war boundary.

Zone summaries (long-range intelligence)

For all zones other than the captain’s current zone, the server includes a lightweight zoneSummaries array. Each summary contains:

• Station names and prices — station ID, display name, market flag, and supply/cargo prices. Prices are fuzzed by a server-side dice roll (see below).
• Unlooted wreck count — the number of unlooted wrecks in the zone, also fuzzed. No wreck IDs or cargo values are revealed.

Zone metadata (ID, coordinates, planets) is always included in full for all zones, so the captain always knows where they can navigate.

Sensor noise (tacticalSkill)

Zone summary data is subject to sensor noise, giving Vessel.tacticalSkill its first gameplay purpose. The noise formula:

    noiseFactor = baseFuzz * (1.0 - tacticalSkill / 100.0 * 0.7)
    baseFuzz    = 0.15  (±15%)

    tacticalSkill   0 → ±15.0% noise
    tacticalSkill  50 → ±9.75% noise
    tacticalSkill 100 → ±4.5%  noise

Station prices are multiplied by 1.0 + uniform(-noiseFactor, +noiseFactor). Wreck counts are offset by round(uniform(-1, +1) * noiseFactor / baseFuzz), clamped to ≥ 0. Noise is re-rolled on every state request — the captain receives a fresh “sensor reading” each poll.

Uses the existing Dice module for server-authoritative randomness.

In-zone vessel sensor accuracy (future)

A future phase will add noise to observed data for other vessels within the captain’s zone — resource levels reported with ±10–20% error, hull integrity slightly off, possible missed detections for damaged sensor systems. This will further differentiate fully-operational ships from damaged ones and give tacticalSkill additional tactical depth.

GM and admin clients

When the ?vessel= query parameter is absent, GET /game/state returns the full unfiltered snapshot with no zone summaries. This preserves backward compatibility for galaxyManager and any future GM dashboards.

Filtered response schema

    {
      "galaxy":        { "zones": [...] },   // all zones (id, coords, planets)
      "vessels":       [...],                 // only vessels in captain's zone
      "stations":      [...],                 // only stations in captain's zone
      "wrecks":        [...],                 // only wrecks in captain's zone
      "zoneSummaries": [                      // all OTHER zones
        {
          "zoneId":              "mars-orbit",
          "stations":            [ { "id", "displayName", "hasMarket",
                                     "creditsPerCargoUnit", ... } ],
          "unlootedWreckCount":  2
        }
      ],
      "time":   123.4,
      "paused": false
    }

Division of Work (Target)

For a more detailed breakdown across the three client layers (Decision, AI/XO, Operations), see Division of Work Revisited in the Client Architecture document.

Implementation Map