Aetheria/docs/original-game-simulation-spec.md

Original Game Simulation Specification

Baselines: RTS d12d7c5c^; ARPG origin/master at ab2c2944.

Entity Lifecycle

Entity construction starts from a hull item. It maps the hull grid, initializes armor, thermal mass, conductivity, hardpoints, equipment occupancy, behavior groups, and weapon groups. Activation initializes behaviors and subscriptions for zone membership, hostility, targeting, visibility, and destruction.

Deactivation disposes subscriptions and stops active behavior updates. Parent and child entities share parent pose/velocity and child mass contributes to parent mass. Docking removes the ship from the zone and parents it to a docking entity; undocking restores zone membership and activation.

Death may result from hull depletion, cockpit destruction, heatstroke, or hypothermia. Equipment fitting and cargo placement preserve item identity and validate geometric occupancy.

Evidence: ServerShared/Entity.cs, Zone.cs, Ship.cs, EntitySerializer.cs.

Stat Evaluation

Behavior stats combine authored data with item quality, durability performance, thermal performance, wear, and attached modifiers. Additive and multiplicative modifiers can be attached dynamically by equipment and timed consumables.

The daemon must execute one catalog-derived behavior graph. It must not retain one set of broad serialized fields while advancing a separate synthetic stat model.

Thermal Grid

Each hull/equipment cell has temperature and thermal mass. Orthogonal cells exchange heat according to conductivity edges and mass ratios. Exterior cells radiate according to authored curves and radiation contributes visibility. Behaviors deposit or move heat at their installed location. Item thermal performance and online state derive from local temperature.

Cockpit temperature advances heatstroke/hypothermia accumulation and recovery. Threshold crossings and death are authoritative events.

Above 330 K, heatstroke advances by (temperature - 330)^2 * 0.00001 * dt; below the threshold it recovers by 0.2 * dt. Below 273 K, hypothermia advances by (273 - temperature)^2 * 0.00001 * dt; above the threshold it also recovers by 0.2 * dt. Values saturate to [0,1], severe risk crosses at 0.25, and a value above 0.99 kills through the ordinary entity death path. The fossil's hypothermia risk comparison accidentally read heatstroke; the daemon implements the intended symmetric threshold crossing while retaining the exact exposure and death formulas.

The daemon derives the grid from the equipped catalog, rather than accepting a renderer-authored heat scalar. Hull mass and specific heat are distributed over the hull shape; installed equipment contributes thermal mass and replaces the conductivity of its occupied cells. Equipment temperature is the mean of those cells. Authored thermal-performance curves and durability derive each item's current performance and online state. Generic wear and weapon-triggered wear consume the same temperature-derived wear potential.

Energy Network

Capacitors store charge. A demand drains charged capacitors evenly first, then divides unmet demand among online reactors. Behaviors succeed or fail according to the actual transaction. Radiators consume energy to pump heat and produce waste heat. Shields consume energy per intercepted damage.

Per daemon tick, equipment performance is derived before behavior execution and all energy consumers transact against the same equipped network. Radiators then pump heat and add their demand, reactors settle baseline output, overload, capacitor refill, throttling and equipment heat, and finally the thermal grid conducts and radiates. Thermal and radiator radiation are independently replaced visibility contributions; they are not cumulative scalar drift. A client may request semantic controls, but cannot set charge, heat, wear, or online state.

Behavior Execution

Required behavior families:

• propulsion: thruster and Aether drive;
• energy: capacitor, reactor, conversion;
• thermal: radiator, heatsink, thermotoggle;
• sensors: sensor, ping, reflector, visibility;
• defense: shield and hull/armor consequences;
• weapons: instant, automatic, constant, charged, lock, launcher, guided;
• utility: tractor, mining, scanner, item usage, velocity limit;
• composition: switches, triggers, behavior groups, stat modifiers;
• timed consumables containing ordinary behaviors.

Behavior groups expose semantic switches, triggers, or analog controls. The daemon advertises those controls as current actions. Clients never invoke the behavior implementation directly.

Consumables

Activation requires the actual item in cargo. Non-stackable effects reject a duplicate active effect. Activation removes the item instance and executes its behaviors for authored duration. Quality contributes to stat evaluation. Expiration removes effects and attached modifiers exactly once. ItemUsage may consume another configured cargo item.

Sensors And Visibility

Visibility sources are independently identified and decayed. Passive sensors accumulate observer-relative information from installed sensor sensitivity, target signature, and distance. Passive reach is derived from enabled installed sensor arrays; multiple arrays combine with diminishing returns. Stations have no class bonus: their advantage comes from spending hull volume, mass, power, cooling, and computation on sensor equipment ships cannot afford. Cargo-held sensors contribute nothing. Threshold transitions create/remove classified contacts. Ping consumes energy, raises source visibility, expands in space, and grants information on crossing. Hostility uses faction ownership, security, and presence rules.

Sensor reach and emitted visibility are separate quantities. Contact refresh must never overwrite the thermal, propulsion, weapon, reflector, and ping sources that make an entity detectable.

AI

Agents own root/current state, task, controls, acceleration, and transitions. Steering compares desired/current velocity. MoveTo is stopping-aware; MatchVelocity converges to target motion. Combat evaluates useful weapon groups and optimum range. Civilian tasks include hauling, mining, patrol, towing, survey, and wandering.

AI reads the same contacts, behavior graph, physics, and command primitives as players. It does not use privileged damage or movement shortcuts.

The original corporation scheduler is preserved in commit ab8aa5fb, ServerShared/GameContext.cs. For each corporation it filters unreserved tasks, groups them by task type, discards groups with no compatible available controller, orders jobs by descending priority, zips them with compatible controllers, flattens the assignments, reserves each task, and calls the controller's ordinary AssignTask entry point. The daemon scheduler must retain that queue/capability/priority/availability contract. Assignment state is durable; task execution drives the same semantic controls used by players.

The historical hauling controller (991d411c) travels to the origin, docks, loads up to available capacity and outstanding quantity, waits, travels to the destination, docks, unloads, and repeats until the requested quantity is delivered. Daemon task phases may advance only from accepted movement, docking, and cargo-transfer results. A rejected transfer leaves both cargo and task phase unchanged.

The remaining implemented RTS controllers at d12d7c5c^ are normative:

• MiningController selects the nearest extant asteroid, approaches tool range, aims and activates the mining switch, chooses another depleted asteroid, and returns home to unload when cargo is full.
• SurveyController chooses the nearest unsurveyed planet or belt asteroid, approaches scanner range while matching target motion, aims and scans until the corporation survey floor satisfies scanner density, then advances.
• TowingController travels to the station, parents the station to the tug, carries it to the requested orbital radius, detaches it, creates the orbit, and completes.
• PatrolController continuously selects orbital targets and uses locomotion until it reaches the configured target distance.
• WanderController chooses random planets or orbitals; orbital wandering can dock for a randomized duration before selecting another target.

Evidence: d12d7c5c^:Assets/Scripts/ServerShared/Behaviors/{Mining, Survey,Towing,Patrol,Wander,Hauling}Controller.cs and ab8aa5fb:Assets/Scripts/ServerShared/GameContext.cs.

Quality And Progression

Crafted items carry continuous quality. Quality changes performance, durability response, thermal response, price, and wear. Rarity tiers map quality bands and derive tier/upgrade count. There is no XP/skill-tree system in the baseline.

Ymir Boundary

Ymir owns deterministic bodies, integration, fields, shape/ray/sweep queries, contacts, impulses, projectile trajectories, and spatial placement candidates. The daemon owns equipment interpretation, accepted controls, resource costs, damage meaning, lifecycle, inventory, and persistence.

Daemon projectile integration and contact detection now call standalone Ymir.Core. Ship flight, gravity, tractor interaction, docking placement, and the remaining Unity query bridge still need to enter that same world before the boundary is complete.

Simulation Pipeline

typed commands + elapsed fixed time + catalog-derived behavior graph
  -> validate semantic controls and resource transactions
  -> derive forces/bodies/queries for Ymir
  -> Ymir deterministic spatial step
  -> interpret contacts and spatial results
  -> advance thermal, energy, sensors, AI, behaviors, lifecycle
  -> one atomic daemon commit
  -> durable state + deduplicated event chronology
  -> Eve projections

Order must be made explicit and parity-tested against the baseline. Full daemon boot is not the unit-test boundary: each organ requires narrow ports, mockable clock/physics/catalog dependencies, and adjacent pipeline smokes.