From 88e77eecf035772e9e5dc6e420ce55e3d23b6a6e Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 11 Jul 2026 17:26:01 +0100 Subject: [PATCH] Document original Aetheria game and migration contract --- docs/original-game-combat-spec.md | 138 ++++++++ docs/original-game-migration-matrix.md | 128 +++++++ docs/original-game-presentation-spec.md | 107 ++++++ docs/original-game-rendering-spec.md | 134 ++++++++ docs/original-game-simulation-spec.md | 130 +++++++ docs/original-game-specification.md | 418 +++++++++++++++++++++++ docs/original-game-world-economy-spec.md | 113 ++++++ 7 files changed, 1168 insertions(+) create mode 100644 docs/original-game-combat-spec.md create mode 100644 docs/original-game-migration-matrix.md create mode 100644 docs/original-game-presentation-spec.md create mode 100644 docs/original-game-rendering-spec.md create mode 100644 docs/original-game-simulation-spec.md create mode 100644 docs/original-game-specification.md create mode 100644 docs/original-game-world-economy-spec.md diff --git a/docs/original-game-combat-spec.md b/docs/original-game-combat-spec.md new file mode 100644 index 000000000..9883b93ae --- /dev/null +++ b/docs/original-game-combat-spec.md @@ -0,0 +1,138 @@ +# Original Game Combat Specification + +Baseline: `origin/master` at `ab2c2944`. + +## Target And Lock + +Each entity owns one target and clears it when the target leaves the zone or is +no longer a visible enemy. Sensors accumulate observer-relative information; +crossing detection thresholds updates visible friendly/enemy collections. + +`LockWeapon` resets lock when target changes. Lock accumulates only against a +hostile target and depends on target angle, lock speed, direction-impact +exponent, and gathered sensor information raised to `SensorImpact`. Outside the +lock angle it decays by `Decay * delta`. Firing requires lock above `0.99`, an +available cooldown, and strict `MinRange < TargetRange < Range`. + +Targeting also produces reciprocal `TargetedBy` state and begin, complete, +lost, visibility, and indicator feedback. + +Evidence: `ServerShared/Entity.cs`, `Behaviors/LockWeapon.cs`. + +## Weapon Families + +Base weapon performance includes damage, penetration, spread, minimum/maximum +range, energy, heat, visibility, and velocity from item performance stats. + +- **Instant:** trigger starts burst and cooldown. Damage, heat, and energy split + across rounds. Each round consumes resources, emits fire, wear, heat, + visibility, and presentation events. Magazines reload from matching cargo. +- **Automatic:** retriggers instant bursts while held after cooldown. +- **Constant:** applies continuous energy, heat, wear, and optional ammunition; + emits start, stop, and reload transitions. +- **Charged:** accumulates charge and charge-dependent damage, heat, spread, + burst, visibility, and velocity multipliers. Early release and overcharge + failure are authored behavior. +- **Lock:** instant weapon gated by progressive angular/sensor lock. +- **Launcher:** lock weapon whose projectile receives guidance, thrust, lift, + dodge frequency, and missile velocity parameters. +- **Guided:** guided projectile weapon without the lock gate. + +Evidence: `ServerShared/Behaviors/Weapon.cs`, `InstantWeapon.cs`, +`AutoWeapon.cs`, `ConstantWeapon.cs`, `ChargedWeapon.cs`, `LockWeapon.cs`, and +`Launcher.cs`. + +## Spatial Resolution + +Weapon behavior emits firing facts. Presentation binds effects to source, +barrels, and selected target, but does not own accepted damage. + +- Ballistic projectiles apply gravity and drag, sweep/raycast their segment, + ignore source, and terminate on collision, range, or optional airburst. +- Guided projectiles predict intercept, apply guidance/lift/thrust curves, + dodge procedurally, terminate after range or overshoot, and may split into + equal-damage children. +- Hitscan resolves range immediately. +- Pulse lasers resolve repeated hits over visual duration and prorate damage. +- Constant laser, lightning, and particle weapons continuously resolve hits. +- Mines arm and resolve proximity/splash behavior. + +Target owner: Ymir owns trajectories, sweeps, contacts, ray/shape queries, and +spatial hit candidates. The daemon interprets those candidates through weapon, +shield, armor, equipment, faction, and lifecycle rules. + +Evidence: `Gameplay/Weapons/Projectile.cs`, `GuidedProjectile.cs`, +`HitscanEffect.cs`, `Laser.cs`. + +## Shields And Damage Topology + +Legacy shields are not shield-HP pools. An active shield intercepts only when +the entity can pay `damage * EnergyUsage`; the hit consumes energy and deposits +`damage / Efficiency` as heat. + +Hull collision maps a hit into schematic cells from texture coordinates, +hardpoint geometry, spread, and penetration. Per affected cell damage order is: + +1. armor; +2. installed item durability; +3. hull durability. + +Splash selects exposed cells by impact direction. Damage produces distinct +incoming-hit, armor, item, hull, depleted-armor, destroyed-item, +destroyed-weapon, cockpit-destruction, and death facts. + +Evidence: `Behaviors/Shield.cs`, `Gameplay/EntityInstance.cs`, +`ServerShared/Entity.cs`. + +## Heat And Death + +Weapon and shield heat is deposited at physical item/hull locations. The cell +thermal network and radiators move or reject it. Cockpit temperature drives +heatstroke/hypothermia independently of hull durability. + +Death causes are hull destruction, cockpit destruction, heatstroke, and +hypothermia. Cause is authoritative and drives presentation. + +## Destruction And Drops + +On hull depletion the entity is marked destroyed. Every non-hull equipped item +drops independently with default probability `0.25`; all cargo drops. Pickups +receive random velocity with authored magnitude. Destruction VFX is requested +and the entity leaves the zone. + +## Required Feedback Events + +The daemon must publish deduplicated, timestamped semantic events for: + +- weapon trigger/start/round/stop/reload/cooldown; +- charge start/update/release/failure; +- lock begin/progress/complete/lost; +- projectile launch/split/impact/expire; +- shield interception and energy/heat consequence; +- armor, item, weapon, cockpit, and hull damage; +- incoming hit and controlled-entity hit confirmation; +- death cause, destruction, and each created drop. + +Durable current state and transient chronology are separate contracts. A client +joining late needs current lock/cooldown/health; it must not replay old impacts. + +## Current Migration Defects + +1. Normal daemon simulation and optional abstract combat kernel are concurrent + writers when the flag is enabled. One combat owner must replace both paths. +2. Current lock is immediate or confidence-based, not original angular lock. +3. Catalog equipment is persisted but combat executes one synthetic weapon. +4. Ammunition, reload, bursts, energy, wear, charge, and failure are absent. +5. Projectile taxonomy is collapsed to one guided circle. +6. Damage is scalar shield HP then scalar hull; original shield and cell damage + semantics are absent. +7. Thermal state is one scalar with linear decay. +8. Destruction does not transactionally generate original drops/death facts. +9. Ymir hit facts are consumed without a published feedback chronology. +10. Health normalization has competing projections and no single contract. + +## Combat Parity Proof + +For every weapon family, capture intent, daemon weapon state, Ymir query/body +timeline, accepted hit, damage topology, resource costs, event sequence, Eve +projection, and rendered feedback. Compare thresholds and timing to the fossil. diff --git a/docs/original-game-migration-matrix.md b/docs/original-game-migration-matrix.md new file mode 100644 index 000000000..1341d4390 --- /dev/null +++ b/docs/original-game-migration-matrix.md @@ -0,0 +1,128 @@ +# Original Game To Perfect Machine Matrix + +Status dimensions: + +- `reference`: behavior exists only in the fossil/reference implementation; +- `owner-exists`: target subsystem implements the primitive in isolation; +- `wired`: production Aetheria paths invoke that owner; +- `exclusive`: obsolete writers cannot decide or repair the result; +- `projected`: authoritative state reaches Eve; +- `lowered`: a generic runtime presents or controls it; +- `proven`: live parity and negative-authority checks pass. + +Dimensions are cumulative claims only when evidence proves each one. Fixture +validation proves contract shape, not wiring, exclusivity, lowering, or parity. + +| Organ | Original authority/evidence | Target owner | Eve contract | Runtime lowering | Current status | Required proof | +|---|---|---|---|---|---|---| +| Run/session state | `ServerShared`, `ActionGameManager` | Aetheria daemon/CultCache | provider/session advertisement | all clients | owner-exists; wired; projected; not proven | restart and multi-client convergence | +| Entity identity/loadout | `ServerShared/Entity*` | daemon | typed entity and inventory surfaces | EveUnity/Electron | owner-exists; wired; projected; not proven | loadout round trip and reconnect | +| Flight intent | `Ship`, `Thruster`, `AetherDrive`, input paths | daemon intent + Ymir physics | analog movement/look/tractor | EveUnity input driver | simplified daemon path wired; Ymir not wired | thrust allocation, torque, energy, heat, drag and gravity | +| Collision | Unity physics and entity handlers | Ymir | collision/result facts | visual interpolation only | owner-exists; not wired; not exclusive | link Aetheria to Ymir.Core/service, share one world, and fail old-writer negative checks | +| Targeting/contacts | sensors + `ActionGameManager` | daemon | contact/target semantics | target HUD and indicators | simplified owner wired/projected; not parity | visibility/nearest/explicit/lock cases | +| Projectile flight | weapon/projectile classes | Ymir | projectile entity/event projection | native projectile visual | local substitutes only | remove both Aetheria-local steppers; prove spawn/travel/hit/despawn through one Ymir world | +| Shield/hull damage | energy-funded shield, armor cells, equipment and hull | daemon | entity status + damage events | meters, impacts, damage VFX | synthetic scalar owner wired; not parity | typed absorption, penetration, item damage and death causes | +| Thermal/energy | cell conduction and capacitor/reactor/radiator network | daemon | ship/equipment status and warnings | schematic/post effects | reference | cell heat, shared energy and medical thresholds | +| Weapons | ServerShared behaviors + Unity effects | daemon + Ymir where spatial | action capability, weapon state, attack events | effects/audio/HUD | one synthetic weapon wired; original engine reference-only | each weapon family | +| Destruction/drops | entity death and pickup paths | daemon | death/drop events and world entities | effects and pickups | fragments wired; chronology and original drop transaction absent | exactly-once drops and cleanup | +| Tractor/scoop | analog tractor and physical timed pickups | daemon + Ymir | tractor intent, pickup entity and receipt | beam/interaction feedback | command wired; spatial/original pickup semantics absent | ramp, range, failed capacity, lifetime and pickup once | +| Dock/undock | wormhole-first interact; first eligible bay; component prerequisites | daemon + Ymir placement | dock commands/context | camera/UI transition | daemon path wired/projected; Ymir placement and parity unproven | priority, eligibility, placement and reconnect | +| Inventory/equipment | inventory panels + ServerShared | daemon | inventory/equipment surfaces | generic UI | owner-exists; wired/projected in fragments; not proven | all transfer directions and rejection | +| Trade | trade UI/economy | daemon | stock, quote, purchase commands | generic UI | purchase owner wired/projected; not proven | atomic purchase and capacity | +| Action bar/input | input shell and rebinding UI | daemon advertises actions; client owns bindings | input capability and action descriptors | universal binding UI | contracts wired; dynamic original behavior source absent | dynamic equipment/cargo actions | +| Pilot camera | ARPG follow/dock cameras | Eve view semantics + runtime | camera rig and semantic view id | EveUnity camera rig | basic follow lowered; dock/view parity absent | authored framing and dock transition | +| Render channels | Unity layers/culling masks | provider variant + runtime | semantic view id | native layer policy | specification work; incomplete uncommitted prototype | no map glyphs in pilot view | +| Minimap/tactical map | `ZoneRenderer`, map cameras | daemon world facts | explicit map projections | Unity and Electron | facts fragmented; generic lowerers absent | same state in both runtimes | +| Fields/fog/gravity | zone renderer and shaders | daemon/plugin semantics | Fields plugin documents | EveUnity fields lowerer | owner-exists; basic lowering; composition parity absent | visual parity captures | +| HUD/schematic | ARPG HUD and `SchematicDisplay` | Eve composition from daemon facts | semantic status/components | EveUnity UI | reference | source-fact and timing matrix | +| Hit/lock/warnings | `ActionGameManager` feedback | daemon event facts | transient feedback stream | VFX/UI/audio | reference | event identity and duration | +| Assets | `Assets/Resources` | Aetheria provider | asset catalog + CultMesh CDN | runtime cache/load | wired; basic lowering; not live-proven remotely | cold/warm remote-only live load and cache proof | +| Save/resume | original persistence paths | daemon/CultCache | published current state | clients rehydrate | owner-exists; not parity-proven | mid-loop restart | +| Terminus loop | original game composition | daemon/Ymir/Eve | pilot surface | Aetheria.Unity | incomplete; no scenario proof | fly/fire/loot/dock/trade | +| Starbridge | original/shared architecture intent | one daemon session | pilot + commander surfaces | Unity + Electron | incomplete; split-target proof missing | commander plus four pilots | +| Behavior engine | `ServerShared/Behaviors` composition | daemon | executable action/status projection | action bar and feedback | reference | every behavior family and modifier lifecycle | +| Sensors/visibility | decaying sources and observer information thresholds | daemon | contacts and ping events | indicators/maps | reference | threshold, decay, ping and classification timelines | +| AI/tasks | agent state/task framework | daemon | observable intent/state only | no decision authority | reference | combat range control and civilian tasks | +| Consumables | cargo-backed timed behavior containers | daemon | dynamic actions and active effects | action bar/schematic | reference | consume, stacking, duration and cleanup | + +## Ownership Invariants + +1. Unity objects never decide durable game state. +2. Target invariant: Ymir will own spatial truth; the daemon owns game meaning + and persistence. Current state: Aetheria still owns multiple local spatial + implementations. +3. Eve publishes semantic facts and commands, not Aetheria implementation + objects or runtime-specific layer numbers. +4. Runtime-specific asset metadata may map semantic view channels to native + mechanisms such as Unity layers. +5. Provider assets own authored visuals; EveUnity owns generic projection and + native hosting; Aetheria.Unity owns only provider client configuration. +6. Transient feedback has authoritative event identity so reconnect and refresh + cannot duplicate hits, drops, purchases, or deaths. +7. RTS, minimap, and pilot views are projections of one world state. + +## Migration Order + +1. Finish archaeology and replace every `reference` row with exact behavior, + source anchors, state inputs, outputs, timing, and proof cases. +2. Establish complete daemon/Ymir simulation parity before polishing clients. +3. Publish combat, thermal, contact, equipment, docking, trade, and feedback + facts through Eve without runtime-specific leakage. +4. Implement generic EveUnity presentation primitives and plugin lowering. +5. Reconstruct Aetheria's authored composition in `Aetheria.Unity` using those + generic primitives and provider assets. +6. Run scenario parity against the fossil and preserve captures, receipts, and + state timelines in conformance packs. + +## Current P0 Faults + +These are source-confirmed ownership failures, not feature backlog: + +1. **Split combat writers.** Normal daemon simulation and the optional abstract + combat kernel can both mutate combat state in one tick. Select one combat + owner and delete the other's write path. +2. **Physics is not actually delegated.** Aetheria's local + `AetheriaRuntimeYmirProjectilePhysics` reimplements projectile stepping; it + does not use standalone `Ymir.Core`. Ship flight, tractor, gravity, docking + placement, and most collision remain outside Ymir. +3. **Persisted behavior is not executable behavior.** Snapshot schemas preserve + broad equipment/behavior state while active simulation executes one + synthetic projectile weapon and simplified raider pursuit. +4. **Client feedback lacks authoritative chronology.** Hits, lock transitions, + damage topology, weapon transitions, death causes, effects, and drops have + no complete deduplicated event stream. +5. **View composition is implicit.** Provider prefabs contain pilot and map + subviews, but portable render channels, entity presentation graphs, effects, + attachment sockets, and map products are not yet first-class contracts. +6. **The game loop has no single daemon owner.** Exploration, discovery, + encounter, loot, docking, trade, refit, narrative, boss progression, + completion, failure, and continue exist as pieces rather than one explicit + run-state machine. +7. **Two Aetheria-local spatial owners.** Daemon projectile stepping and the + Unity bridge/query path independently implement Ymir-shaped behavior and can + disagree while standalone Ymir remains unwired. +8. **Live conformance has no complete owner.** Static provider packs can pass + while daemon, runtime, or split-target dependencies are absent. The current + Eve consumer smoke fails because its expected EveElectron proof is missing. +9. **Normative native presentation has no implemented owner.** Render channels, + presentation graphs, map products, attachment/effect lifecycles, material + profiles, and source-version diagnostics are assigned in specification but + lack complete Eve contracts and EveUnity lowerers. +10. **Original-game acceptance lacks an evidence ledger.** No current owner + records fossil baseline, target state timeline, commands/receipts, rendered + captures, and negative-writer checks as one scenario result. + +## Evidence Rules + +- Static fixtures and provider packs prove schema/contract shape only. +- `wired`, `exclusive`, `lowered`, and `proven` require live executable + witnesses at the claimed layer. +- A negative ownership claim must verify the obsolete path cannot produce, + override, or repair the result. +- The current `verify-aetheria-ymir-cutover.ps1` proves selected Unity callback + removal and static routing into an Aetheria bridge. It is not Ymir integration + proof until it verifies an actual Ymir.Core/service dependency and rejects + Aetheria-local spatial implementations. +- Conformance scenarios must preserve source baseline, authoritative state + timeline, Ymir timeline, command/receipt chronology, rendered capture, + runtime/package versions, and negative-authority results together. diff --git a/docs/original-game-presentation-spec.md b/docs/original-game-presentation-spec.md new file mode 100644 index 000000000..2bbab1e6d --- /dev/null +++ b/docs/original-game-presentation-spec.md @@ -0,0 +1,107 @@ +# Original Game Presentation Specification + +Baseline: `origin/master` at `ab2c2944`. + +## Provider Documents Required + +The original UI directly observes mutable entities and UniRx events. The target +must replace that graph with provider-owned typed documents: + +1. `player_cockpit_state`: systems, schematic cells, thermal state, durability, + energy, visibility, movement, shutdown, and medical state. +2. `zone_contacts`: identity, disposition, detection both ways, pose, selected + and locked state, and health disclosure. +3. `action_slots`: action identity, source equipment/cargo, icon, availability, + active state, progress/cooldown, quantity, and operation binding. +4. `inventory_layout`: shaped hull/cargo occupancy, cells, hardpoints, + durability, armor, conductivity, and temperature. +5. `trade_session`: station, stock, destinations, quotes, capacity, commands, + receipts, and typed rejection reasons. +6. `navigation_surface`: zone topology, contacts, fields, discovery, current + location, and navigation commands. +7. `presentation_events`: deduplicated hit, damage, lock, thermal, death, + weapon, effect, and audio cues. + +Names are provisional; responsibilities are normative. + +## Cockpit Schematic + +The schematic presents equipment topology and polls reactor draw, capacitor +charge/capacity, temperatures, radiator stores, cargo temperature, override +shutdown, shield active state, drive RPM, visibility, hull/item durability, +weapon ammunition/range/cooldown, and heatstroke/hypothermia thresholds. + +The target document must publish these source facts and cell topology. Eve may +compose them as grids, metrics, progress, imagery, and overlays. EveUnity may +animate transitions but may not derive state from materials or particles. + +## Target And Contact Feedback + +The selected target panel includes identity, relation, target shield state, +hull durability, gathered information in both directions, pose/range, and +selection. Hostile/friendly indicators are created from contact add/remove +facts. Detection fill, selected target, and lock indicators consume explicit +observer-relative state. + +Crosshairs and lock reticles need camera projection and attachment semantics. +Barrel endpoints and articulation groups are presentation inputs, not combat +authority. + +Hit marker is triggered only by an incoming-hit event on the selected target +whose source is the controlled entity. It remains visible for authored +`HitMarkerDuration`. This requires event identity, source, target, and time. + +## Action Bar And Input + +Slots derive from exposed action-bar inputs plus available equipment behaviors, +weapon groups, and consumables. They display binding, active state, cooldown or +duration, and cargo quantity. Activation submits semantic commands; it never +calls behavior objects in the client. + +Bindings are client-owned and portable across providers exposing the same +semantic action. Dynamic action availability is daemon-owned. + +## Inventory And Trade + +Inventory presents shaped hull and cargo grids, armor, hardpoints, occupancy, +temperature, conductivity, item condition, comparison, selection, drag preview, +and valid destination feedback. Drag state is local; mutations and rejection +reasons are daemon receipts. + +Trade presents station stock, player destinations, credits, valuation, item +details, filters, ship purchase, and resulting inventory state. Quote and commit +are separate when price can vary. + +## Map Products + +Minimap zoom changes camera/projection scale and icon scale independently from +pilot view distance. Zone map combines objects and field textures. Sector map +builds discovered topology and faction/current/entrance/exit/boss states. +These are explicit Eve projections, not hidden children of the pilot scene. + +## Distress, Damage, And Death + +Incoming damage identifies affected schematic cells and damage category so the +correct armor/item/hull feedback can pulse. Thermal distress publishes current +heatstroke/hypothermia, thresholds, and cause-specific warning transitions. +Screen post-processing intensity is a lowering of these facts plus authored +timing, with accessibility fallback. + +Death unbinds gameplay input, presents cause, and transitions to appropriate +menu/restart flow. The client cannot clear or save authoritative world state as +a side effect of playing the animation. + +## Effects And Audio + +Weapon and impact effects consume semantic event facts and provider asset refs. +Original music selection attempted to use `TargetedByCount`, but playback was a +TODO in the inspected baseline. Audio parity therefore covers authored effect +cues that exist; a complete music system is future content, not a hidden +original requirement. + +## Presentation Timing Proof + +For every element record source document/event, trigger, duration, interpolation +owner, interruption rule, reconnect behavior, and accessibility fallback. +Verify initial load, user command, daemon update, mid-transition, settled state, +refresh/reconnect, and event deduplication. diff --git a/docs/original-game-rendering-spec.md b/docs/original-game-rendering-spec.md new file mode 100644 index 000000000..f2722e60f --- /dev/null +++ b/docs/original-game-rendering-spec.md @@ -0,0 +1,134 @@ +# Original Game Rendering And View Specification + +Baseline: `origin/master` at `ab2c2944`. + +## Projection Contexts + +Aetheria does not have one universal camera. It has distinct products: + +- pilot gameplay world through main plus follow/dock virtual cameras; +- auxiliary fog and field cameras writing named textures; +- tactical minimap cameras and map-scale icons; +- full zone-map projection; +- sector/galaxy topology projection; +- world effects, transparent passes, trails, and overlays. + +`ZoneRenderer` currently coordinates many of these, but that Unity class is a +reference composition, not the target owner. + +## Entity Presentation Graph + +`EntityInstance` is a composite presentation root containing: + +- hull renderers and collision presentation; +- tactical map icon; +- influence and ping subviews; +- shield subview; +- equipment, radiator, thruster, weapon, and articulation hardpoints; +- fade-capable and persistent material partitions; +- visibility/fade lifecycle. + +`ShipInstance` adds thruster particles, Aether-drive effects, tractor beam, and +ship-specific composition. Weapon presentation adds muzzle, charge, projectile, +beam, impact, explosion, particle, and trail subviews. + +One entity/one opaque prefab is insufficient as a portable contract. Eve needs +a typed entity-presentation graph with named subviews, attachment sockets, +activation predicates, render channels, and effect bindings. + +## Semantic Render Channels + +Required Aetheria channels include: + +```text +world.geometry +world.celestial +world.transparent +world.shields +world.projectiles +world.trails +world.effects +field.fog-density +field.fog-displacement +field.gravity +field.influence +map.zone.objects +map.zone.gravity +map.minimap.objects +map.minimap.fields +map.sector.topology +overlay.targeting +``` + +Channel identity is semantic. Unity layer numbers are runtime-variant metadata. +The pilot view excludes minimap channels; map cameras include their map channels +without requiring pilot geometry. A channel may render to display or a named +texture consumed by another material/channel. + +Each channel requires space, camera role, visibility set, ordering, output +target, update policy, clear policy, composition mode, and consumer bindings. + +## Fields + +Original products include fog density/tint, displacement and patches, sector +boundary fog, gravity wells/waves/terrain/depth, influence, slime/gravity +textures, and map/minimap overlays. Eve Fields is the portable numeric base, +but parity requires named outputs, per-product resolution, blend operation, +viewport, cadence, material consumer, and camera visibility. + +## Asset And Material Contract + +Provider assets own authored transforms, bounds, meshes, materials, sprites, +textures, sounds, and effect content. Semantic radius never rescales authored +art. Runtime variants map portable roles to native resources. + +Required asset kinds include entity presentation, subview, mesh, material +profile, effect, projectile presentation, trail profile, field material, map +symbol, and audio. Entity presentations declare root asset, subviews, +attachments, material slots, visibility tags, map representations, and effect +bindings. + +Material profiles describe intent such as opaque PBR, transparent, additive, +field, shield, and celestial. They expose typed parameters and texture slots; +they do not publish Unity shader names as portable authority. + +## Effects + +Effects are semantic burst, loop, beam, trail, impact, shield-hit, destruction, +and screen-feedback lifecycles. Contracts declare source event, spawn space, +attachment socket, channel, lifetime, pooling class, parameters, and start/ +update/stop bindings. Effect realization cannot mutate gameplay state. + +Projectile simulation and projectile presentation are separate. The daemon and +Ymir own identity/pose/contact; presentation owns visual asset, trail, impact, +and visibility tags. + +## Maps + +Minimap, zone map, and sector map are separate projections sharing stable world +identities. They are not merely alternate cameras over the pilot document. + +- minimap: local contacts, icons, influence, gravity, independent zoom; +- zone map: viewport objects, fields, selection, and navigation; +- sector map: topology, links, discovery, factions, entrance/exit/boss/current. + +## Runtime Ownership + +Target ownership: EveUnity owns generic native lowering primitives once they +exist. Current implementation covers basic playable-world entities, provider +assets, input, camera following, command transport, receipts, and refresh. +Semantic render channels, entity presentation graphs, map products, material +profiles, effect lifecycles, pooling, and parity diagnostics remain incomplete +or unimplemented. + +Aetheria publishes semantic state and provider asset variants. Eve owns +portable contracts and plugin ABIs. Native layer allocation, masks, render +textures, prefab assembly, materials, GPU buffers, particles, trails, pooling, +culling, and diagnostics are derived runtime state, never portable authority. + +## Visual Parity Proofs + +Capture and compare pilot world, shield hit, each projectile/beam/trail family, +fog/fields, minimap, zone map, and sector map. Diagnostics must identify source +projection, channel, camera, target texture, visibility set, active asset +variant, and provider event/state version. diff --git a/docs/original-game-simulation-spec.md b/docs/original-game-simulation-spec.md new file mode 100644 index 000000000..0f0f037aa --- /dev/null +++ b/docs/original-game-simulation-spec.md @@ -0,0 +1,130 @@ +# Original Game Simulation Specification + +Baseline: `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. + +## 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. + +## 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 sensitivity, signature, and +range. 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. + +## 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. + +## 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. + +The current Aetheria-local `AetheriaRuntimeYmirProjectilePhysics` does not call +standalone `Ymir.Core`; it is migration scaffolding, not completion of this +boundary. + +## Simulation Pipeline + +```text +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. diff --git a/docs/original-game-specification.md b/docs/original-game-specification.md new file mode 100644 index 000000000..153cf7a1f --- /dev/null +++ b/docs/original-game-specification.md @@ -0,0 +1,418 @@ +# Aetheria Original Game Specification + +Status: source-derived living specification + +Authority: `origin/master` is the executable reference for original behavior. +This document describes that behavior without granting the fossil Unity project +authority in the target architecture. + +Pinned baseline: `ab2c294464bb30b9b5c8987cdb9108204821a92d`. + +Subsystem specifications: + +- [Simulation](original-game-simulation-spec.md) +- [Combat](original-game-combat-spec.md) +- [World, economy, and progression](original-game-world-economy-spec.md) +- [Presentation](original-game-presentation-spec.md) +- [Rendering and views](original-game-rendering-spec.md) +- [Migration matrix](original-game-migration-matrix.md) + +## Purpose + +The original Unity game contains the accumulated mechanics, timing, controls, +rendering decisions, and player feedback that define Aetheria as a game. The +target is behavioral parity through a different machine: + +- the Aetheria daemon owns game state and simulation decisions; +- Ymir owns authoritative spatial physics and collision; +- Eve surfaces expose everything a client needs to understand and present; +- EveUnity lowers those semantics into Unity rendering and interaction; +- provider assets retain authored visual, audio, and material content; +- no client reconstructs authority from presentation state. + +Parity means the same player intent produces materially the same mechanical +outcome and legible feedback. It does not require preserving Unity component +boundaries or implementation accidents. + +## Evidence Rules + +Each normative behavior must cite at least one source path in `origin/master`. +Timing, thresholds, formulas, and ordering must cite the defining source rather +than a caller that merely observes the result. Scene and prefab evidence is +valid for composition, layer, camera, and feedback behavior. Current-branch +code is evidence of migration status, not evidence of original behavior. + +The principal source bodies are: + +- `Assets/Scripts/ServerShared`: Unity-free mechanics and state transitions; +- `Assets/Scripts/Gameplay`: player orchestration and presentation feedback; +- `Assets/Scripts/Zone Display`: world, map, fog, and field presentation; +- `Assets/Scripts/UI`: HUD, inventory, trade, menus, and input display; +- `Assets/Scenes/ARPG.unity`: runtime composition and camera/layer policy; +- `Assets/Resources`: provider-authored prefabs, materials, icons, and effects; +- catalog and settings assets: authored numeric balance and content. + +## Modes And Views + +### Terminus + +Terminus is a single-player game mode using the pilot surface. The minimum +complete loop is: fly, acquire or select a target, fire, survive return fire, +destroy or disable something, scoop useful cargo, dock, and trade. It shares +pilot mechanics and presentation with the Starbridge pilot role. + +### Starbridge + +Starbridge is one multiplayer mode with two simultaneous projections of one +authoritative state: + +- one commander uses the 2D RTS view; +- up to four pilots use the 3D ARPG view; +- the Unity map panel and Electron commander backdrop are projections of the + same strategic world facts; +- view choice never creates a second simulation. + +### Pilot View + +The pilot view follows the controlled ship in 3D. It presents world geometry, +combat, fields, effects, target feedback, cockpit status, and overlays. It must +not render tactical-map glyphs embedded in provider prefabs. + +Evidence: + +- `Assets/Scenes/ARPG.unity` composes follow and dock cameras; +- `ProjectSettings/TagManager.asset` assigns `Minimap` to Unity layer 14; +- `Assets/Scripts/Gameplay/EntityInstance.cs` owns a separate `MapIcon` visual; +- `Assets/Scripts/Zone Display/ZoneRenderer.cs` sizes map icons from minimap + distance independently of world geometry. + +### Tactical And Strategic Views + +Map views render semantic contacts, bodies, fields, influence, and navigation +at map scale. Their glyph scale and visibility rules are independent from the +native geometry used by the pilot camera. A native asset may contain visuals +for multiple view channels, but each camera renders only its selected channel. + +## Core Entity Model + +An entity is a simulated body with identity, faction, transform, velocity, +visibility, target state, equipment, cargo, docking relationships, behaviors, +and derived performance. The controlled entity is selected by authoritative +run state, not by whichever client object currently has focus. + +Entity lifecycle includes creation from authored templates, activation in a +zone, observation, targeting, damage, destruction, cargo/equipment drops, +docking, undocking, zone transfer, and persistence in the run checkpoint. + +Primary evidence: + +- `Assets/Scripts/ServerShared/Entity.cs`; +- `Assets/Scripts/ServerShared/EntityData.cs` and related loadout types; +- `Assets/Scripts/Gameplay/EntityInstance.cs`; +- `Assets/Scripts/Gameplay/ActionGameManager.cs`. + +## Flight And Spatial Interaction + +Player movement is intent applied to a simulated ship, not direct client +transform mutation. Camera-relative input is converted to semantic movement; +the simulation resolves thrust, velocity, drag, control limits, heat, and +collisions. `origin/master` has no privileged boost input or boost state. +Acceleration comes from installed and active thrusters or Aether drives, +available energy, heat, mass, and movement axes. Future drive-boost or evasive +maneuver actions therefore enter as equipment-provided semantic actions rather +than being invented as hidden base-flight rules. + +Spatial mechanics include: + +- acceleration, steering, velocity, drag, and stopping behavior; +- collision bodies and collision response; +- range checks for weapons, sensors, tractor, docking, and interactions; +- tractor force and towing/scooping behavior; +- docking and undocking placement; +- projectiles and collision hits; +- zone and navigation boundaries. + +Target owner: Ymir computes authoritative spatial results from daemon-owned +intent and body state. The daemon commits resulting game state. Clients may +interpolate presentation but may not decide collisions or accepted movement. + +### Original Flight Update + +`Ship.Update` recalculates thrust and torque, clears actuator axes, allocates +lateral and longitudinal thrust banks, compensates asymmetric lateral torque, +steers toward the XZ look direction, drives Aether-drive axes, then applies +hull drag and gravity. Thrusters consume energy, apply `thrust / mass * delta`, +contribute torque, add heat, and add visibility. Aether drives separately model +rotor RPM, coupling, passive coupling, torque, energy draw, and thrust. + +Original tractor input is analog and approaches the requested value at two +units per second. Interact prioritizes a nearby wormhole and otherwise attempts +the first eligible nearby dock. Undocking requires a cockpit, propulsion, a +reactor, and a bay able to release the ship. + +Evidence: `Ship.cs`, `Thruster.cs`, `AetherDrive.cs`, and +`ActionGameManager.cs`. + +## Sensors, Visibility, And Targeting + +Visibility is simulated and observer-relative. Sensors accumulate information, +contacts distinguish visible/known/hostile state, pings alter visibility, and +target selection is constrained by available contacts and game rules. + +The pilot can select explicitly, cycle or choose nearest targets, and obtain a +lock where required by equipment. The UI distinguishes target existence, +visibility to target, target visibility, hostility, lock progress, shields, and +hull condition. + +Primary evidence: + +- sensor and visibility behaviors under `Assets/Scripts/ServerShared`; +- targeting in `Assets/Scripts/Gameplay/ActionGameManager.cs`; +- target feedback fields in the ARPG scene and HUD prefabs. + +Visibility is the sum of independently decaying sources produced by thermal +radiation, weapons, propulsion, explicit visibility behavior, reflector cross +section, and active pings. Each observer accumulates information per target. +Crossing the configured threshold creates a classified contact; falling below +it removes the contact and clears invalid targets. Active ping consumes energy, +raises the observer's signature, expands over time, and grants information as +its radius crosses entities. Targeting creates reciprocal `TargetedBy` state. + +## Equipment And Derived Performance + +Ships are assembled from a hull and slotted items. Items contribute behaviors +and stat recipes. Equipment placement, condition, temperature, energy use, +cooldowns, toggles, and active consumables affect derived ship performance. + +Required behavior families include: + +- hull, cockpit, reactor, battery, radiator, heatsink, thermotoggle; +- thruster and maneuvering modifiers; +- sensor, visibility, ping, and lock support; +- shield generation and shield state; +- instant, constant, projectile, and guided weapon behavior; +- tractor and cargo interaction; +- consumables and timed effects. + +Behavior groups expose switches, triggers, or analog controls while behaviors +own execution. The original set includes instant, constant, charged, lock, +automatic, launcher, and guided weapons; capacitors, reactors, radiators, +sensors, reflectors, visibility, mining and resource scanning; stat modifiers; +conversion, velocity-limit, trigger, switch, and thermotoggle behaviors. + +Stats derive from quality, durability performance, thermal performance, wear, +stat recipes, and attached modifiers. Persisting behavior fields without +executing this graph is not parity. + +The action bar is a binding surface over currently available semantic actions. +Its contents change with equipment and cargo. Any exposed input, including +Shift or Space, may bind to an action slot. Controller directional strings are +first-class input gestures. + +## Thermal And Energy Simulation + +Items and ship compartments exchange or generate heat according to their +behaviors. Cockpit temperature contributes to hypothermia and heatstroke. +Threshold crossings produce warnings; sustained extreme temperature can kill +the pilot. Heatstroke and hypothermia recover according to gameplay settings. + +Original formula and threshold authority: + +- `Assets/Scripts/ServerShared/Entity.cs` heatstroke/hypothermia update paths; +- `Assets/Scripts/ServerShared/Settings.cs` temperature thresholds, + multipliers, exponents, recovery speeds, and control limits. + +Presentation includes schematic temperatures, limit markers, warnings, +post-processing intensity, severe heatstroke phasing, shutdown state, and cause +of death. Presentation never computes medical state from a color or effect. + +The original thermal model is cell-based. Hull cells exchange heat with +orthogonal neighbors according to occupants, conductivity edges, and thermal +mass ratios. Exterior cells radiate through an authored power curve and this +radiation contributes visibility. Radiators consume energy to pump and reject +heat. Item online state and thermal performance derive from local temperature. + +Energy demand drains capacitors evenly first; remaining demand is distributed +across online reactors. Propulsion, weapons, shields, sensors, charging, and +cooling therefore share one energy network. A scalar heat value with linear +decay is only a placeholder. + +## Combat + +Combat order is: + +1. The actor selects or retains a valid target. +2. An available semantic weapon-group action is activated. +3. Weapon state validates lock, range, cooldown, energy, heat, ammunition, and + behavior-specific constraints. +4. The simulation emits the appropriate instant, constant, projectile, or + guided attack. +5. Ymir resolves spatial travel and collision for physical attacks. +6. Damage is applied through shields, armor/hull rules, equipment effects, and + destruction state. +7. Destruction produces authoritative drops and removes or transforms the + entity. +8. Eve publishes both durable state and transient feedback events. + +The original game exposes multiple weapon behavior classes. A single generic +bolt approximation is not parity. Each behavior's timing, targeting, damage, +visibility, energy, heat, and effect contract must be specified from +`Assets/Scripts/ServerShared` and weapon presentation code. + +Player feedback includes muzzle/beam/projectile effects, shield impact, +damage/destruction effects, audio, target meter changes, lock state, and a +time-bounded hit marker when the controlled entity damages its target. + +Primary feedback evidence: + +- `Assets/Scripts/Gameplay/ActionGameManager.cs` target and hit-marker logic; +- weapon implementations under `Assets/Scripts/Gameplay/Weapons`; +- behavior implementations under `Assets/Scripts/ServerShared`; +- `Assets/Scripts/Gameplay/EntityInstance.cs` effect materialization. + +Damage is typed and spatial. Shields are active energy-to-heat interceptors, +not regenerating shield hit points: interception requires an active shield and +energy for `damage * EnergyUsage`, then deposits `damage / Efficiency` as heat. +Remaining damage maps to schematic cells and flows through armor, fitted item +durability, then hull durability according to spread and penetration. Armor, +item, weapon, cockpit, hull, and thermal deaths are distinct facts. + +AI is a state/task system. Combat agents evaluate weapon-group damage across +range, select useful groups and optimum range, approach, retreat or match +velocity, target, and fire. Other tasks include hauling, mining, patrol, +towing, survey, and wandering. Nearest-player pursuit with one synthetic +weapon is not parity. + +## Loot, Cargo, Inventory, And Equipment + +Destroyed entities can create world pickups from authoritative cargo and +equipment decisions. A player can acquire loot through collision/scoop or +tractor interaction when rules permit. Items move between world, cargo bays, +equipment slots, docking storage, and trade stock through typed operations. + +The UI supports inspection, comparison, drag/drop transfer, valid-destination +feedback, equipment changes, cargo capacity, and action availability. Client +drag state is presentation-only; accepted transfer and resulting loadout are +daemon-owned. + +Original destroyed entities probabilistically drop non-hull equipment and all +cargo as physical pickups with inherited/random velocity and a thirty-second +lifetime. Pickup collision attempts storage in eligible cargo bays; success +destroys the pickup and failure leaves it in space. Equipment fitting validates +hull shape, rotation, occupancy, hardpoints, and placement constraints. + +## Docking, Stations, And Trade + +Docking requires a valid nearby facility and results in authoritative docking +relationships and placement. Docked presentation switches camera/context and +enables station services. Undocking restores the pilot to world simulation at +an authoritative spawn transform. + +Trade uses station stock, player funds/resources, item quality/condition, +prices, and capacity rules. Purchase and sale mutate daemon state atomically +and return receipts. The trade UI derives available commands and disabled +reasons from the published state. + +The original market is station inventory. Purchase requires credits and +destination capacity; commodities split into stack-sized lots; hull purchase +creates a docked player ship. No original sell path was found. Stations also +provide refit/loadout restoration, ship selection, local narrative, and towing. + +## World, Zones, And Progression + +The world contains zones, stations, orbitals, bodies, asteroids, factions, +connections, fields, and encounter state. Zone rendering includes world +objects plus gravity/fog/influence and map projections. Travel and progression +must preserve the original generation and transition rules before new content +extends them. + +Terminus content may be sparse, but the machinery must support a repeatable +single-player loop. Starbridge uses the same world truth while adding commander +and multi-pilot coordination. + +Travel is embodied through nearby wormholes. Transition transfers the current +entity, reveals destination adjacency, performs exit motion, and saves. +Progression is exploration, discovery, combat, loot, refit, trade, ship +acquisition, faction territory, boss-path traversal, and narrative locations. +No XP/level system was found; item quality, rarity, and acquisition are the +implemented progression axis. + +## HUD And Player Feedback + +The pilot HUD must expose, at minimum: + +- controlled ship schematic and equipment state; +- target identity, relation, visibility, lock, hull, and shield state; +- crosshair/view direction and selected-target indicators; +- action bar with live availability, cooldown, binding, and activation state; +- cargo/inventory affordances and interaction prompts; +- docking and station context; +- thermal, shutdown, damage, death, hit, and warning feedback; +- minimap/map projection through its own view channel; +- command rejection or disabled reasons where an action cannot execute. + +The UI's visual composition may be modernized, but information timing and +salience are part of behavior. A metric card containing the same number is not +automatically equivalent to the original feedback. + +## Rendering And Audio + +Provider assets may contain multiple semantic subviews: pilot geometry, +tactical glyphs, shields, combat effects, influence, and other overlays. Eve +advertises the active view. Runtime variants map semantic render channels to +native camera/layer mechanisms. The pilot camera must not render map glyphs; +map cameras must not depend on pilot geometry being visible. + +Authored prefab transforms are authoritative presentation data. Semantic world +radius is collision/selection metadata and must not rescale native art. Camera +framing derives from authored visual bounds and advertised camera semantics. + +Audio and VFX are triggered from semantic state or event facts with stable +identities and timing. They may not infer authoritative hits, deaths, or weapon +activation from local particle collisions. + +## Save, Resume, And Multiplayer Consistency + +Authoritative run state persists in CultCache and is published through +CultMesh. Reconnect, reload, and view changes must reproduce the same current +entity, zone, loadout, docking, target, combat, cargo, and progression state. +Presentation-only animation may restart; game decisions may not. + +Starbridge clients observe one shared session. A pilot and commander can issue +different semantic commands, but neither owns a private copy of the world. + +## Required Scenario Proofs + +1. **Flight:** launch Terminus, fly, turn, stop, exercise installed propulsion + actions, and collide; daemon/Ymir state and visible motion agree throughout. +2. **Target and combat:** acquire a hostile, lock where required, fire each + weapon family, observe effects and hit feedback, take return fire, and + destroy the target. +3. **Loot:** observe authoritative drops, tractor or scoop one, and see the item + appear in cargo exactly once. +4. **Dock and trade:** dock, inspect stock, buy and sell, change equipment, + undock, and observe the changed ship behavior. +5. **Thermal:** generate heat, cross warning/control thresholds, recover, and + verify HUD/post-processing follows daemon facts. +6. **Views:** show the same zone in pilot, minimap, Unity tactical map, and + Electron commander view without leaking view-specific glyphs. +7. **Persistence:** restart daemon/client mid-loop and recover authoritative + state without client repair logic. +8. **Starbridge:** one commander and multiple pilots act in the same session; + all projections converge on one command/receipt history. + +## Open Archaeology Ledger + +The following require exact source-derived sub-specs before parity can be +claimed: + +- complete weapon-family formulas and timing; +- full thermal/energy/stat-recipe update order; +- AI state machines and encounter spawning; +- docking eligibility and placement rules; +- trade price and stock mutation formulas; +- zone generation, travel, and progression rules; +- every HUD indicator's source fact, update trigger, and animation timing; +- audio event matrix; +- render-channel membership for all provider prefab subviews; +- multiplayer ownership and conflict rules from the original network model. diff --git a/docs/original-game-world-economy-spec.md b/docs/original-game-world-economy-spec.md new file mode 100644 index 000000000..c3052a252 --- /dev/null +++ b/docs/original-game-world-economy-spec.md @@ -0,0 +1,113 @@ +# Original Game World, Economy, And Progression Specification + +Baseline: `origin/master` at `ab2c2944`. + +## Docking + +Contextual interact first considers a nearby wormhole, then docking. Docking is +proximity-based, requires the ship to be unparented, iterates nearby entities, +and uses the first bay accepting `TryDock`. Success changes zone/parent +relationships, control binding, perspective, camera, inventory context, and +station services. + +Undocking requires cockpit, propulsion, reactor, and a docking bay able to +release the ship under its occupancy/cargo constraints. The daemon owns all +eligibility and placement. Eve publishes current context, available command, +disabled reason, and resulting receipt. Camera/menu transition is derived. + +## Inventory And Equipment + +Items retain stable identity, quality, durability, temperature, behavior state, +and quantity. Equipment placement validates hull shape, rotation, occupancy, +hardpoints, and equipment constraints. Cargo bays are shaped grids supporting +capacity and stacks. + +Every transfer is an atomic daemon operation with source, destination, item, +placement, resulting state, and typed rejection reason. Client drag/drop is a +proposal and preview only. Required paths include cargo-to-cargo, +cargo-to-equipment, equipment-to-cargo, equipment-to-equipment, station/player +transfers, loadout restore, naming, and current-ship selection. + +## Destruction, Loot, And Scooping + +Destroyed entities roll each non-hull fitted item independently for drop and +drop all cargo. Pickups are physical bodies with identity, item contents, +velocity, and thirty-second lifetime. Tractor affects spatial motion. Pickup +collision attempts storage in any eligible cargo bay. Success commits item +transfer and despawn exactly once; insufficient capacity leaves the pickup. + +## Stations + +Stations provide docking bays, stock cargo, trade, refit/loadout restoration, +owned/player ship selection, local narrative, and optional towing. Target +architecture publishes one coherent station workflow surface rather than a +catalog of unrelated contextual dialogs. + +## Trade + +Station inventory is the baseline market. Price comes from item data or crafted +valuation. Purchase requires credits and destination capacity. Commodities +split into stack-sized lots. Hull purchase creates a docked player ship. Credits, +stock, destination inventory, and ship ownership commit atomically. + +No baseline sell path was found. Selling, stock replenishment, scarcity, +production, and dynamic faction economy are extensions; they must not be cited +as missing baseline parity. + +## Galaxy And Zones + +Generation creates zones, links, factions, entrance/exit, critical/boss path, +initial discovery, and contents. Zone state includes entities, bodies, +asteroids/resources, orbitals, stations, fields, wormholes, encounters, and +faction/security context. + +Sector map is a discovered-topology inspection projection. Full zone map and +minimap are separate spatial projections. Shared identities link all views. + +## Travel + +Travel is embodied by entering a nearby wormhole. One daemon transaction: + +1. validates proximity and destination; +2. removes/transfers the current entity; +3. changes current zone; +4. reveals destination adjacency according to baseline rules; +5. chooses authoritative exit pose/motion through Ymir; +6. checkpoints the run; +7. publishes transition/result events and new projections. + +No Unity callback may complete discovery, transfer, or save after command +acceptance. Towing is a separate station-mediated relocation mechanic. + +## Progression Spine + +New game begins at the entrance with a generated player ship. Baseline +progression consists of: + +- exploration and discovery; +- combat and survival; +- physical loot acquisition; +- equipment fitting and refit; +- trade and ship acquisition; +- faction territory and critical/boss-path traversal; +- narrative locations; +- persistence of zone, entity, inventory, loadout, and action bindings. + +The target daemon needs an explicit run-state machine linking these pieces, +including new/continue, active encounter, docked service context, travel, +failure/death, completion, and Starbridge session roles. A collection of +documents is not itself a game loop. + +## Receipts And Player Recovery + +All rejected operations expose stable reason codes and recovery facts. Required +examples include cargo full, invalid placement, missing cockpit/propulsion/ +reactor, no eligible bay, insufficient credits, invalid target, unavailable +route, item unavailable, stale quote, and duplicate command. + +## Scenario Proof + +Run from new game through flight, wormhole travel, hostile encounter, +destruction/drop, failed and successful scoop, docking, purchase, equipment +change, undock, behavior change, save, restart, and continue. Capture daemon +commits, Ymir timeline, Eve surfaces/events, receipts, and visible client state.