diff --git a/NEXT-STEPS.md b/NEXT-STEPS.md deleted file mode 100644 index bf8a7ba..0000000 --- a/NEXT-STEPS.md +++ /dev/null @@ -1,137 +0,0 @@ -# Next Steps - -## Immediate Backend Follow-Up - -The simulation now has the beginnings of a self-sustaining bootstrap: - -- ore miner -- gas miner -- station-side `gas -> fuel` -- constructor-led station module installation -- pad-based docking with reservation -- timed mining, spool-up, docking, and undocking - -The next step is to close the remaining logistics and simulation gaps around that bootstrap. - -Recommended work: - -- add constructor material logistics - - allow the constructor to fetch module materials instead of assuming they are already on the target station - - add pickup / load phases and delivery priorities -- expose station installed modules and active construction to the viewer - - installed modules - - current build target - - build progress -- harden dock management - - make dock eligibility depend on dock type / ship class if needed - - surface pad occupancy in debug UI -- add stronger action timing coverage - - timed final approach / berthing if desired - - timed station-side processing queues if multiple modules run concurrently -- add recovery behavior for stranded ships - - rescue / tow / emergency refuel - - better handling after full fuel and power depletion - -## Economy / Logistics - -The economy now has a more explicit resource chain: - -1. mining ore -2. harvesting gas -3. processing `gas -> fuel` -4. refining ore -5. spending refined goods on station growth - -The next step is to make those logistics deliberate instead of bootstrap-scripted. - -Recommended work: - -- split logistics roles more clearly - - ore miner - - gas miner - - hauler / constructor transport -- make station build priorities responsive - - fuel chain first when reserves are low - - ore refining when fuel is stable - - docking expansion when traffic backs up -- make fuel scarcity visible in debug UI - - fuel throughput - - gas stock - - dock contention -- move away from generic node selection - - let miners prefer nearby valid nodes - - factor travel cost and dock turnaround into throughput planning - -## Concrete Implementation Order - -1. Add constructor pickup / delivery behavior for module materials. -2. Expose station installed modules, dock pads, and active construction in the contracts and viewer. -3. Add rescue / recovery behavior for power-starved ships. -4. Add faction build priorities based on fuel, ore throughput, and dock saturation. -5. Improve pirate targeting so industrial ships and docking lanes are high-value harassment targets. -6. Break backend simulation responsibilities into smaller planning / faction / combat / logistics modules. - -## Network / Multiplayer - -The repository now has a split architecture: - -- [apps/backend](/home/jbourdon/repos/space-game/apps/backend) - - authoritative .NET simulation -- [apps/viewer](/home/jbourdon/repos/space-game/apps/viewer) - - rendering and observer UI -- `GET /api/world` - - initial snapshot -- `GET /api/world/stream` - - incremental SSE delta stream - -The next networking step is not “move the simulation into .NET.” That is already done for the active runtime. - -The next steps are about scaling the transport and authority model cleanly. - -Recommended work: - -- add client-to-server command submission - - direct orders - - automation changes - - selection / observer commands only where useful -- add persistence - - saves - - world seeds - - reconnect support -- add player ownership / permissions - - command authority - - eventually fog of war / restricted information -- harden replication contracts - - explicit entity lifecycle events - - versioning - - reconnect / catch-up semantics - -## Viewer / Debugging - -The viewer still works as an observer/debug client first. - -Recommended work: - -- keep tuning the tactical and `camera-follow` camera feel -- add clearer camera mode affordances in the HUD / ship rail -- show station module state and construction state -- show dock occupancy and waiting ships -- expose fuel-chain health - - gas stock - - fuel stock - - refinery / processor activity -- improve event typing for: - - dock request - - dock granted - - refuel - - construction started / completed - -## Interest Management - -The stream is still world-wide. - -Recommended work: - -- add observer/view-scoped subscriptions -- send only relevant deltas per observer -- keep strategic summaries for off-screen context diff --git a/SESSION.md b/SESSION.md deleted file mode 100644 index 5271acc..0000000 --- a/SESSION.md +++ /dev/null @@ -1,288 +0,0 @@ -# Session Summary - -## Current State - -The repository is now split into two apps that live side-by-side: - -- [apps/backend](/home/jbourdon/repos/space-game/apps/backend) - - authoritative ASP.NET Core simulation -- [apps/viewer](/home/jbourdon/repos/space-game/apps/viewer) - - Three.js/Vite observer client -- [shared/data](/home/jbourdon/repos/space-game/shared/data) - - shared scenario data - -The complete simulation runs in the backend. The viewer fetches one world snapshot, then subscribes to an SSE delta stream and renders the world as an observer. - -The world model is now hierarchical: - -- systems live in galaxy space -- ships, stations, and resource nodes live in system-local space -- the viewer applies a local presentation layer for the active system - -## Runtime / Networking - -The backend currently provides: - -- `GET /api/world` - - initial authoritative snapshot -- `GET /api/world/stream` - - incremental SSE deltas after a sequence number - -The viewer currently does: - -1. fetch the world once -2. connect to the stream -3. apply deltas into a local render model -4. interpolate and briefly extrapolate moving ships for presentation -5. compose galaxy-space systems with system-local entities for rendering - -This supports multiple simultaneous observers on the same world. Interest management is not implemented yet, so every observer still receives full-world deltas. - -## Viewer Status - -The viewer currently supports: - -- single-click selection for ships, stations, nodes, planets, and stars -- rectangular marquee selection - - constrained to one group at a time: - - ships - - structures - - celestials -- `WASD` panning on the `XZ` plane -- middle-mouse tactical orbit camera -- smooth wheel zoom across local, system, and universe scales -- layered system presentation - - one active local system with detailed content - - non-local systems projected as distant shell markers -- procedurally animated planets and moons from orbital metadata -- ringed planets, binary star presentation, and richer resource visuals -- explicit camera modes - - tactical free-move / orbit camera - - `camera-follow` third-person trailing camera for ships -- dedicated `System` and `Focus` panels on the right HUD -- hover labels for projected system markers -- a bottom ship list with horizontally scrolling ship cards - - card click selects the ship - - card double-click selects, focuses, and enables `camera-follow` - - cards now span the full screen width as a compact bottom rail - - cards show ship name, class, fuel, energy, state, and order - - cards include a compact history icon button under the ship-class tag -- multiple floating history windows for debugging - - openable from ship cards - - independently movable and resizable - - copy-to-clipboard support with a DOM fallback path - -Local presentation is now intentionally isolated: - -- only the active system renders local detail - - ships - - stations - - resource nodes - - planets - - moons -- other systems render as distant stars plus compact summary presentation -- projected systems can show shell reticles and hover labels -- distant galaxy motion now has only minimal parallax while moving inside a system - -The viewer also includes plain-text HUD readouts for: - -- game state -- network statistics -- ship debugging history in separate floating windows - -The viewer now consumes richer celestial metadata from the backend: - -- star kind and star count -- planet type, shape, moon count, and orbital elements -- resource node source kind such as `asteroid-belt` and `gas-cloud` -- galaxy-space system positions -- system-local entity positions and velocities - -Planets and moons are not simulated as networked entities. Their positions are reconstructed client-side from snapshot time plus orbital configuration. - -Viewer-side orbital presentation now also applies to: - -- resource nodes -- stations - -These orbitals prefer nearby planets or moons as anchors, with fallback to the system star. - -## Simulation Status - -The backend simulation already includes: - -- autonomous ships -- orbital travel -- pad-based docking and undocking - - stations expose docking capacity through installed dock-bay modules - - ships reserve an empty pad before docking - - ships wait in a holding pattern when no pad is available -- mining and refinery delivery -- module-gated ship and station capabilities - - ships require fitted modules such as reactor, capacitor, mining turret, gas extractor, or gun turrets - - stations require installed modules such as power, docking, refinery, fuel processing, and storage modules -- fuel-to-energy power simulation - - gas clouds provide raw `gas` - - station fuel processors convert `gas` into `fuel` - - ship reactors consume `fuel` to charge capacitors - - station power cores consume `fuel` to charge station energy buffers - - powered actions stop when fuel and energy are depleted -- constructor-led station module construction - - stations now track installed modules per instance instead of relying only on static constructible definitions - - module construction uses station inventory plus timed build progress -- explicit action timing in the control loop - - mining now runs on a fixed cycle - - warp and FTL travel require spool time - - docking and undocking have explicit durations -- refining / fabrication -- faction growth through ship and outpost production -- pirate pressure and combat -- procedural galaxy generation with deterministic expansion beyond the authored scenario -- handcrafted `Sol` system easter egg with Saturn and rings -- resource geography beyond simple ore nodes - - asteroid belts for ore - - gas clouds for gas -- hierarchical coordinates for replication - - systems in galaxy space - - in-system entities in local space -- item-based inventories for ships and stations - - ore, refined metals, raw gas, fuel, and cargo now flow through per-item inventories instead of ad hoc stock fields - -The runtime model still follows the intended layered control architecture: - -1. `order` -2. `defaultBehavior` -3. `assignment` -4. `controllerTask` -5. `state` - -## Important Recent Changes - -- split the old monolith into `apps/backend` and `apps/viewer` -- moved simulation authority fully into .NET -- replaced frontend polling with snapshot-plus-delta SSE replication -- added viewer-side interpolation / short extrapolation for movement -- added a plain-text network statistics readout -- reworked the camera with smoother zoom, orbit, panning, and marquee selection -- split viewer camera behavior into tactical and `camera-follow` modes -- added ship-card double-click to focus and enter follow mode -- cleaned up several viewer HUD elements and removed redundant panel content -- expanded the backend world into a large procedural galaxy with elevated vertical variance -- added deterministic orbital metadata for planets and client-side orbital animation in the viewer -- added moon rendering in the viewer -- added backend-generated asteroid belts and gas clouds as resource sources -- injected the `Sol` system into the generated galaxy -- refactored contracts from flat world coordinates to galaxy-space systems plus system-local entities -- normalized authored scenario placements and patrol routes into system-local coordinates during load -- added viewer-side local-focus / floating-origin style presentation for the active system -- reworked local-vs-remote rendering so only one system shows detail at a time -- added projected shell markers and hover labels for distant systems while inside a local system -- added viewer-side orbital motion for stations and resource nodes -- tuned local movement so the rest of the galaxy remains mostly fixed during in-system travel -- reduced the starting faction to a minimal bootstrap - - one modular station - - one constructor ship - - one mining ship -- added a gas mining ship for bootstrap fuel logistics -- moved the starting ships close to the `helios` star and next to each other -- added modular ship and station data - - new station power and storage modules - - new fuel processing and docking bay modules - - new ship reactor, capacitor, mining turret, gas extractor, and gun turret modules -- refactored simulation inventories to per-item storage - - stations and ships now replicate inventories instead of specialized ore/refined/cargo counters -- split raw `gas` from burnable `fuel` in the simulation loop -- added module recipe data and per-station installed-module runtime state -- added constructor-led station module construction for the bootstrap station -- added gas harvesting, gas-to-fuel processing, and explicit ship refueling behavior -- reworked docking into pad reservation with visible stand-off positions instead of snapping ships into station centers -- added action timing for mining cycles, warp / FTL spool-up, and undocking -- replaced the viewer bottom faction strip with a horizontal ship-card debugging rail -- added movable, resizable, multi-window history panels in the viewer -- fixed the auto-miner undock controller transition - - ships now keep their docked station link until the undock move actually completes - - this prevents auto-miners from falling into `idle` immediately after unloading - -## Current Known Limitations - -- replication is still world-wide - - no observer-scoped interest management yet -- the viewer is still observer-focused - - no command submission UI yet -- local / projected / galaxy presentation is now workable but still needs tuning - - shell marker art direction and scaling still need polish - - tactical/follow camera tuning still needs iteration - - projected-system composition is still a viewer illusion, not a full multi-layer renderer -- the galaxy is much larger now, so viewer performance and visual density need active tuning -- moon rendering is procedural from counts, not authored moon-by-moon data -- resource extraction behavior still treats all resource nodes generically -- item inventories exist, but storage/module restrictions are still partial - - station storage capacity is now enforced by storage class and installed module - - ship cargo compatibility is still mostly data-convention driven - - hull-specific module restrictions are not enforced yet -- constructor logic only builds from station-local inventory - - it does not yet fetch module materials from other stations or ships -- station installed modules and active construction are not yet exposed in the viewer contract -- piracy and faction growth are still functional rather than strategically deep -- no persistence for saves, seeds, or reconnect state - -## Important Files - -- [apps/backend/Program.cs](/home/jbourdon/repos/space-game/apps/backend/Program.cs) - - backend API endpoints -- [apps/backend/Simulation/WorldService.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) - - authoritative world state and stream coordination -- [apps/backend/Simulation/SimulationEngine.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) - - simulation advancement - - snapshot / delta composition for galaxy-space systems and local-space entities - - inventory, gas/fuel, and energy processing - - station module construction - - gas harvesting, refueling, and pad-based docking - - action timing for mining, spool-up, docking, and undocking -- [apps/backend/Simulation/ScenarioLoader.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) - - faction bootstrap - - galaxy generation - - special systems - - procedural celestial/resource content - - normalization of authored placements into system-local space - - minimal startup seeding for ships, station, fuel, and module materials -- [apps/backend/Contracts/WorldContracts.cs](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) - - snapshot and delta contract shape - - station dock-pad count -- [apps/backend/Simulation/RuntimeModels.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) - - runtime vector math and world model - - per-item inventories on ships and stations - - per-station installed modules and docking pad assignments -- [apps/viewer/src/GameViewer.ts](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) - - camera, selection, streaming integration, and presentation - - layered local/remote system presentation - - orbital reconstruction and moon rendering - - projected shell markers and hover labels - - ship card list and multi-window history debugging UI - - station HUD docked/pad count readout -- [apps/viewer/src/style.css](/home/jbourdon/repos/space-game/apps/viewer/src/style.css) - - HUD layout - - ship-card rail - - floating history window styling -- [apps/viewer/src/api.ts](/home/jbourdon/repos/space-game/apps/viewer/src/api.ts) - - snapshot fetch and SSE stream integration -- [apps/viewer/src/contracts.ts](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) - - viewer-side snapshot contract for galaxy-space systems and local-space entities -- [shared/data](/home/jbourdon/repos/space-game/shared/data) - - scenario and world data definitions - - `module-recipes.json` now defines timed module construction costs - -## Validation - -Validation passing at the end of this session: - -- `dotnet build apps/backend/SpaceGame.Simulation.Api.csproj` - -Validation currently failing / blocked: - -- `cd apps/viewer && npm run build` - - fails because `apps/viewer/src/GameViewer.ts` references a missing `followedShipId` property - -## Last Commit - -- `ef62577` diff --git a/STATES.md b/STATES.md deleted file mode 100644 index d3d1700..0000000 --- a/STATES.md +++ /dev/null @@ -1,543 +0,0 @@ -# States, Orders, Behaviours, Assignments - -This document defines the intended gameplay model for the project: a multiplayer X4-inspired RTS with strong automation and strong direct control. - -It is no longer purely aspirational. The current runtime now uses the same top-level control layers described here: - -1. `order` -2. `defaultBehavior` -3. `assignment` -4. `controllerTask` -5. `state` - -What is still incomplete is scope, not structure. - -## Design Goals - -The game should support both: - -- RTS-style direct control: `move-to`, `mine-this`, `hold-here`, `dock-there`, `attack-this` -- X4-style automation: `auto-mine`, `patrol`, `escort`, `trade`, `defend-area` - -The intended player experience is: - -- you can micro units at any time -- automation resumes when direct intervention is over -- fleets, stations, carriers, and sectors can provide reusable command structure - -## Control Layers - -Each ship should be modeled with five layers: - -1. `order` -2. `defaultBehavior` -3. `assignment` -4. `controllerTask` -5. `state` - -### `order` - -A direct player-issued instruction with highest priority. - -Properties: - -- one-shot unless explicitly marked persistent -- can preempt automation -- may complete, fail, cancel, or timeout -- after resolution, ship falls back to `defaultBehavior` - -Current active examples: - -- `move-to(destination)` -- `mine-this(node, refinery)` -- `dock-at(target)` - -### `defaultBehavior` - -Persistent automation the ship should run when no direct order is active. - -Properties: - -- long-lived -- self-replanning -- normally loops or maintains a standing objective -- resumes automatically after one-shot order resolution - -Current active examples: - -- `idle` -- `auto-mine(area, refinery)` -- `patrol(route)` -- `escort-assigned` - -### `assignment` - -The command relationship the ship belongs to. - -Examples: - -- assigned to fleet -- assigned to carrier -- assigned to station -- assigned to sector command -- assigned to mining group - -Assignment does not necessarily tell the ship what exact task to do every second. It provides authority, context, operating area, logistics ownership, and fallback doctrine. - -Current active examples: - -- `unassigned` -- `commander-subordinate(commanderId, role)` -- `station-based(stationId, role)` -- `mining-group(controllerId)` - -### `controllerTask` - -The immediate executable action. - -Examples: - -- travel -- dock -- undock -- mine/extract -- unload -- follow -- hold-position - -Current active examples: - -- `idle` -- `travel(destination, threshold)` -- `dock(host, bay)` -- `undock(host)` -- `extract(node)` -- `unload(target)` -- `follow(target, offset)` - -### `state` - -The physical/runtime state of the unit. - -Examples: - -- idle -- spooling-warp -- warping -- docking -- docked -- mining -- attacking -- holding - -## Precedence Rules - -Control precedence should be: - -1. `order` -2. `defaultBehavior` -3. `assignment doctrine` -4. safety/failsafe logic - -Interpretation: - -- if a one-shot order exists, it drives planning -- if no order exists, the ship executes its default behavior -- if no explicit default behavior exists, assignment may supply one -- if none of the above apply, ship uses idle/safe fallback - -This is the active planner model in the codebase. - -## Order Lifecycle - -One-shot orders are the RTS-facing layer. - -Each order should move through: - -1. `queued` -2. `accepted` -3. `planning` -4. `executing` -5. one of `completed`, `failed`, `cancelled`, `blocked` - -Recommended behavior: - -- `completed`: clear order and resume `defaultBehavior` -- `cancelled`: clear order immediately and resume `defaultBehavior` -- `failed`: clear order or retry depending on order policy -- `blocked`: wait, reroute, or escalate depending on order policy - -Current implementation notes: - -- direct orders already move through `queued`, `accepted`, `planning`, `executing` -- `completed`, `failed`, and `blocked` are already represented -- full queued-order chains do not exist yet - -## Command Categories - -### One-shot direct orders - -These are the core RTS commands. - -| Order | Intent | Status | -| --- | --- | --- | -| `move-to(destination)` | go to a position or object | active | -| `mine-this(node)` | mine this specific node | active | -| `dock-at(target)` | dock at target | active | -| `undock` | leave current host | not first-class yet | -| `hold-here(position)` | stay at current or assigned point | not implemented | -| `attack(target)` | attack a specific unit/object | not implemented as direct order | -| `intercept(target)` | chase and engage moving target | not implemented | -| `escort(target)` | follow and defend a specific target | not implemented as direct one-shot order | -| `transfer-cargo(target, item, amount)` | move cargo between entities | not implemented | -| `build-here(site)` | construct at location | not implemented | -| `salvage-this(target)` | recover specific wreck/resource | not implemented | -| `retreat-to(destination)` | disengage and move to safety | not implemented | - -### Persistent default behaviours - -These are the automation layer. - -| Behavior | Intent | Status | -| --- | --- | --- | -| `idle` | do nothing beyond safety drift / local maintenance | active | -| `auto-mine(area, refinery)` | find nodes, mine, deliver, repeat | active | -| `patrol(route or area)` | move across checkpoints and react to threats | active | -| `escort-assigned` | stay with assigned commander or protected ship | active | -| `defend-area(area)` | hold area and engage threats inside rules | not implemented | -| `trade(route or policy)` | acquire, move, and deliver goods automatically | not implemented | -| `resupply(host or fleet)` | fetch and deliver fuel/ammo/cargo | not implemented | -| `ferry-units(host)` | shuttle units between hosts or waypoints | not implemented | -| `harvest(area)` | collect local resources automatically | not implemented | -| `hold-area(center, radius)` | remain in zone with low autonomy | not implemented | - -### Assignments - -Assignments define command context. - -| Assignment | Meaning | Status | -| --- | --- | --- | -| `unassigned` | independent unit | active | -| `fleet-member(fleetId, role)` | unit belongs to a fleet structure | not implemented | -| `commander-subordinate(commanderId, role)` | subordinate follows commander doctrine | active | -| `carrier-wing(carrierId, role)` | launch/recover/escort under carrier | not implemented as distinct type | -| `station-based(stationId, role)` | station-owned logistics or defense unit | active | -| `sector-command(sectorId, role)` | unit operates inside a sector mandate | not implemented | -| `mining-group(controllerId)` | industrial unit tied to a mining controller | active | - -Assignments can supply default behavior if the unit has none explicitly set. - -## Planner Model - -Planning works like this: - -1. if `order` exists, derive `controllerTask` from it -2. else if `defaultBehavior` exists, derive `controllerTask` from it -3. else if `assignment` implies doctrine, derive `defaultBehavior` -4. else run idle fallback - -This preserves RTS responsiveness while keeping X4-style automation. - -Current implementation detail: - -- mining and patrol progress are stored directly on `order` or `defaultBehavior` -- there is no separate high-level “captain” intent layer anymore - -## Physical States - -These are the intended physical states for ships. - -| State | Meaning | Status | -| --- | --- | --- | -| `idle` | no active movement or operation | active | -| `holding` | maintaining current position/formation/anchor | reserved | -| `spooling-warp` | charging local fast-travel | active | -| `warping` | high-speed in-system travel | active | -| `spooling-ftl` | charging inter-system travel | active | -| `ftl` | inter-system travel | active | -| `arriving` | final approach after warp/ftl | active | -| `approaching` | standard approach to target | reserved | -| `docking-approach` | approach to docking lane or bay | active | -| `docking` | docking procedure in progress | active | -| `docked` | physically docked | active | -| `undocking` | undocking procedure in progress | active | -| `mining-approach` | aligning to resource node | active | -| `mining` | active extraction | active | -| `transferring` | moving cargo, fuel, or units | active | -| `building` | performing construction | reserved | -| `repairing` | performing repair actions | reserved | -| `patrolling` | movement as part of patrol | active | -| `escorting` | movement as part of escort | active | -| `attacking` | active weapons engagement | reserved | -| `retreating` | disengaging toward safety | reserved | -| `disabled` | cannot act | reserved | -| `destroyed` | removed from play | active outcome | - -## Controller Tasks - -These are the low-level tasks the planner can issue. - -| Task | Purpose | Status | -| --- | --- | --- | -| `idle` | no task | active | -| `travel(destination, threshold)` | move to destination | active | -| `hold(position, radius)` | maintain a point | not implemented | -| `dock(host, bay)` | dock at host | active | -| `undock(host)` | undock from host | active | -| `extract(node)` | mine/extract resource | active | -| `unload(target, item, amount?)` | move cargo out | active | -| `load(target, item, amount?)` | move cargo in | not implemented | -| `follow(target, offset)` | maintain formation | active | -| `attack(target)` | engage target | not implemented as controller task | -| `intercept(target)` | chase moving target | not implemented | -| `orbit(target, radius)` | remain in orbit around target | not implemented | -| `build(site)` | perform construction | not implemented | -| `repair(target)` | perform repair | not implemented | -| `scan(target)` | gather intel | not implemented | - -## Events - -Events should be explicit and usable by both gameplay and debug tools. - -### Order events - -| Event | Meaning | Status | -| --- | --- | --- | -| `order-issued` | player or AI created an order | partially implicit | -| `order-accepted` | unit accepted order | represented in order status | -| `order-rejected` | unit cannot accept order | not explicit yet | -| `order-started` | execution began | represented in order status | -| `order-blocked` | execution cannot proceed for now | represented in order status | -| `order-completed` | order finished successfully | represented and logged | -| `order-failed` | order failed | represented and logged | -| `order-cancelled` | order was manually cleared or overridden | reserved | - -### Behavior events - -| Event | Meaning | Status | -| --- | --- | --- | -| `behavior-set` | default behavior assigned | represented in debug history | -| `behavior-cleared` | default behavior removed | represented in debug history | -| `behavior-resumed` | resumed after order completion | implicit | -| `behavior-paused` | temporarily suspended | implicit | -| `behavior-phase-changed` | automation phase updated | represented in debug history | - -### Assignment events - -| Event | Meaning | Status | -| --- | --- | --- | -| `assignment-set` | unit assigned | represented in debug history | -| `assignment-cleared` | assignment removed | represented in debug history | -| `assignment-role-changed` | subordinate role changed | partially represented | -| `commander-lost` | assigned leader unavailable | implicit | - -### Controller/runtime events - -| Event | Meaning | Status | -| --- | --- | --- | -| `arrived` | destination reached | active | -| `docking-clearance-granted` | docking permission accepted | active via history | -| `docking-clearance-denied` | docking permission denied | active via history | -| `docking-begin` | docking procedure started | active | -| `docked` | docking complete | active | -| `undocked` | undocking complete | active | -| `cargo-full` | cargo reached capacity | active via history | -| `cargo-empty` | cargo emptied | active via history | -| `target-lost` | attack/escort target unavailable | not explicit yet | -| `hostile-detected` | threat found | not explicit yet | -| `resource-depleted` | node exhausted | not explicit yet | -| `damaged` | ship took damage | not explicit yet | -| `destroyed` | ship destroyed | active outcome | - -## Transition Rules - -### Core fallback rule - -When a direct order resolves: - -- clear `order` -- emit terminal order event -- resume `defaultBehavior` -- if no explicit `defaultBehavior`, ask `assignment` for fallback -- if none exists, become `idle` - -This is the main rule that keeps automation and RTS control compatible. - -### Example: direct move order - -1. player issues `move-to` -2. ship order becomes `move-to(destination)` -3. planner emits `travel(destination)` -4. ship moves through travel states -5. on `arrived`, order completes -6. ship resumes previous default behavior, such as `patrol` or `auto-mine` - -### Example: direct mine-this order - -1. player issues `mine-this(node)` -2. order overrides `auto-mine` -3. planner travels to node -4. planner extracts until cargo is full -5. order completes -6. unit returns to `auto-mine` - -Current limitation: - -- the one-shot `mine-this` order does not yet auto-deliver once before completing - -### Example: assignment-driven escort - -1. fighter assigned to `commander-subordinate(commanderId, escort)` -2. assignment implies default behavior `escort-assigned` -3. on no direct order, fighter follows commander -4. when direct order ends, fighter resumes escort automatically - -## Blocking and Waiting - -Blocked execution should be explicit, not hidden inside `idle`. - -Common blocked reasons: - -- no docking bay free -- no path to destination -- no cargo space -- no valid mining target -- no ammo/fuel/energy -- target out of command scope -- waiting for commander or carrier - -Recommended blocked substate or status: - -- `blocked(waiting-for-bay)` -- `blocked(waiting-for-target)` -- `blocked(waiting-for-resource)` -- `blocked(waiting-for-order-scope)` - -Current implementation: - -- blocked status exists on `order` -- blocked reason metadata does not yet exist - -## Queue and Override Rules - -For RTS feel, orders should support: - -- immediate replace -- optional shift-queue -- cancel current order -- clear all queued orders - -Recommended semantics: - -- normal click command replaces current direct order -- shift-command appends to order queue -- automation only runs when order queue is empty - -Current implementation: - -- immediate replace behavior exists -- shift queues do not exist yet - -## Suggested Data Shape - -Current runtime shape is effectively: - -```ts -type ShipMind = { - order?: ShipOrder; - defaultBehavior: ShipBehavior; - assignment: ShipAssignment; - controllerTask: ControllerTask; - state: UnitState; -}; -``` - -Future expansion can add: - -```ts -type ShipMindExtensions = { - queuedOrders?: ShipOrder[]; - blockedReason?: BlockedReason; - stance?: CombatStance; -}; -``` - -## Mapping To Current Project - -Current runtime concepts map like this: - -| Runtime concept | Current implementation | -| --- | --- | -| direct move | one-shot `order = move-to` | -| direct mining | one-shot `order = mine-this` | -| direct docking | one-shot `order = dock-at` | -| automation mining | `defaultBehavior = auto-mine` | -| automation patrol | `defaultBehavior = patrol` | -| assignment escort | `assignment = commander-subordinate` plus `defaultBehavior = escort-assigned` | -| execution | `controllerTask` | -| physical movement / interaction | `state` | - -## Recommended Next Scope - -To move the game forward without overbuilding, the highest-value next steps are: - -### Direct orders - -- `hold-here` -- `attack` -- `escort` as a first-class direct order - -### Default behaviors - -- `defend-area` -- `trade` -- `resupply` - -### Assignments - -- `fleet-member` -- `carrier-wing` -- `sector-command` - -### Runtime support - -- blocked reason handling -- optional order queue -- better event emission -- more explicit threat / target events - -### Faction strategy - -- reactive shipbuilding priorities -- better pirate harassment of industrial targets -- clearer economic pressure and throughput visibility - -## Non-Goals - -This model should not force: - -- full economic AI before direct control feels good -- full hierarchy simulation before ship orders work -- perfect X4 parity - -The target remains a practical hybrid: - -- faster and clearer than a pure sim -- deeper and more autonomous than a pure RTS - -## Summary - -The active design is now: - -- one-shot orders for direct RTS control -- default behaviors for persistent automation -- assignments for organizational structure -- controller tasks for immediate execution -- physical states for movement and interaction - -That structure supports the gameplay goal cleanly: - -- players can micro ships directly -- ships remain useful when not microed -- factions can scale through automation -- the game can feel like an RTS without losing simulation depth diff --git a/docs/COMBAT.md b/docs/COMBAT.md new file mode 100644 index 0000000..5f1bc92 --- /dev/null +++ b/docs/COMBAT.md @@ -0,0 +1,229 @@ +# Combat + +This document defines the intended combat model for the simulation. + +Combat is primarily a local-space activity. It is how factions, pirates, and defenders contest access, claims, stations, and logistics. + +## Design Goals + +The combat model should support: + +- local-space tactical fights +- piracy and harassment +- claim destruction and station contestation +- station defense +- commander-driven engagement behavior +- policy-aware hostility and access denial + +## Core Principles + +- combat happens in `local-space` +- claims and structures are physically contestable +- piracy should target valuable traffic and vulnerable infrastructure +- stations should be defensible but not magically safe +- combat behavior should come from commanders and policy, not only from raw proximity + +## Combat Space + +Combat belongs in `local-space`. + +This is where entities can: + +- maneuver with thrusters +- approach targets +- engage with weapons +- defend stations and claims +- intercept miners, haulers, and construction support + +Ships in `system-space` warp transit are not in normal tactical combat. + +This keeps tactical fighting distinct from travel. + +## Combat Actors + +The main combat actors are: + +- combat ships +- escorts +- station defenses +- pirates +- claim objects +- vulnerable civilian or industrial ships + +Combat should matter not only for fleet battle, but also for logistics disruption and territorial contest. + +## Claims As Combat Targets + +Claims at Lagrange points should be valid combat targets. + +That means: + +- enemies may destroy a claim before it matures +- pirates may harass or destroy claims +- destroying a claim reopens the location for future contest + +Claims should not be protected by abstract immunity. + +They are real objects in the world. + +## Construction As A Vulnerable Phase + +Station founding and expansion should be dangerous. + +Vulnerable targets include: + +- claim objects +- construction storage +- constructor ships +- supplying haulers + +This makes station growth something that may require escort and local protection rather than being a purely economic background action. + +## Station Defense + +Stations should be able to defend themselves through modules and local defenders. + +Station defense may come from: + +- defense modules +- docked or assigned defenders +- nearby fleet response +- friendly system presence + +Station safety should depend on actual defensive capacity, not only ownership flags. + +## Piracy + +Pirates should be a meaningful local-space threat. + +They should favor: + +- industrial ships +- haulers +- construction traffic +- station approaches +- valuable logistics lanes + +Piracy is especially important because it creates pressure on: + +- escorts +- trade profitability +- claim security +- station recovery + +Pirates should not behave like generic random attackers if the game can instead make them economically disruptive predators. + +## Hostility And Access + +Combat should interact with policy and diplomacy, but not be replaced by them. + +Examples: + +- a hostile faction may be denied docking and attacked on approach +- a neutral faction may be tolerated in-system but not allowed to build +- pirates may ignore policy altogether and simply attack vulnerable targets + +See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for the access side of this relationship. + +## Commander Role In Combat + +Commanders should determine combat behavior. + +Examples: + +- faction commanders set threat posture +- station commanders request local defense +- ship commanders choose whether to attack, escort, retreat, or hold + +Combat should therefore depend on: + +- commander doctrine +- assigned role +- local threat level +- policy and hostility state + +This is better than a purely reflexive “closest target” model. + +## Engagement Rules + +Commanders should eventually carry engagement rules such as: + +- attack hostiles on sight +- defend only if attacked +- prioritize claims and stations +- prioritize civilian protection +- avoid battle unless escorted + +These rules can begin simple, but they are important for faction identity. + +## Civilian And Industrial Vulnerability + +Non-combat ships should not be expected to behave like warships. + +Industrial or civilian commanders should prefer: + +- fleeing +- docking +- requesting escort +- rerouting +- abandoning low-value trade under danger + +This gives escorts and station defense real purpose. + +## Claim And Station Contest + +A system can be contested without full conquest mechanics. + +Useful examples: + +- destroy the enemy claim before activation +- raid construction storage +- kill the constructor ship +- deny safe trade to a vulnerable station +- force expensive escort commitments + +This creates strategic conflict even before fully mature station warfare exists. + +## Destruction And Recovery + +Combat should create lasting economic consequences. + +Examples: + +- destroyed claims delay expansion +- destroyed haulers create shortages +- destroyed defenders weaken a system +- damaged or powerless stations need recovery support + +This is one of the main ways combat feeds back into the economy. + +See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the combat and claim-related event families. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- combat is primarily a local-space activity +- claims are destructible and contestable +- station construction is a vulnerable phase +- piracy should prefer valuable and vulnerable traffic +- station defense depends on real assets +- commander doctrine should influence combat behavior +- combat outcomes should affect logistics and expansion + +## Relationship To Other Documents + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - defines where combat is allowed + +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) + - defines access and hostility context + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - defines who decides engagement behavior + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - defines vulnerable stations, claims, and local defense context + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - defines the economic consequences of combat disruption diff --git a/docs/COMMANDERS.md b/docs/COMMANDERS.md new file mode 100644 index 0000000..bd12d5b --- /dev/null +++ b/docs/COMMANDERS.md @@ -0,0 +1,365 @@ +# Commanders + +This document defines commander entities and the command model for the simulation. + +The core idea is that meaningful autonomous behavior comes from commanders. Ships, stations, and factions act through commanders rather than through ad hoc local logic alone. + +## Design Goals + +The commander model should support: + +- clear AI ownership of decisions +- delegation across multiple scales +- player override without destroying autonomy +- market-aware economic behavior +- station and ship behavior that remains coherent over time + +## Core Principle + +A ship without a commander cannot do much. + +A station without a commander cannot do much. + +A faction without a commander cannot coordinate its assets coherently. + +Commanders are the AI actors that interpret goals, issue orders, react to conditions, and maintain doctrine. + +Commander availability should ultimately depend on faction population as described in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). + +## Commander Levels + +The intended command hierarchy has three primary levels: + +1. `faction commander` +2. `station commander` +3. `ship commander` + +Additional specialized commanders may exist later, such as: + +- fleet commander +- task-group commander +- convoy commander +- sector commander + +## Commander Entity Model + +Commanders should be first-class simulation entities. + +At minimum, a commander should conceptually have: + +- `commanderId` +- `kind` +- `ownerFactionId` +- `parentCommanderId?` +- `controlledEntityId?` +- `doctrine` +- `current goals` +- `known constraints` +- `subordinate commanders` + +This matters because commanders are not just labels. They are the units of decision-making in the simulation. + +Commander creation is population-backed rather than free. + +See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the recommended commander entity shape. + +## Faction Commander + +The faction commander is the highest routine AI authority for a faction. + +Responsibilities: + +- define faction priorities +- allocate strategic resources +- establish expansion and defense goals +- create or retire station and fleet objectives +- respond to large-scale shortages, threats, and opportunities + +The faction commander should reason mostly across `universe-space`, `galaxy-space`, and strategic `system-space`. + +It should not micromanage every ship constantly. + +Typical outputs: + +- strategic priorities +- economic policy +- expansion goals +- threat posture +- standing doctrine for subordinate commanders + +## Station Commander + +Each station should have a station commander. + +A station commander is the operational brain of a station. + +Responsibilities: + +- manage the station's local objectives +- manage docking priorities +- create and maintain buy orders +- create and maintain sell orders +- request logistics support +- evaluate shortages and surpluses +- assign local defense expectations +- request construction, repair, and expansion work + +A station without a commander may still exist physically, but it should have very limited behavior. + +Without a station commander, a station should not be expected to: + +- participate meaningfully in the market +- coordinate logistics +- react intelligently to shortages +- manage production priorities + +Typical outputs: + +- buy orders +- sell orders +- dock priority rules +- local logistics requests +- local defense requests +- module and expansion priorities + +Important limitation: + +- a station commander does not own ships + +It is better to think of the station commander as publishing needs, priorities, and requests rather than directly possessing a private ship roster by definition. + +Station construction does not require that a commander already be present on-site. + +A higher-level actor such as a faction commander, another AI authority, or the player may force initial resource transfers and construction support before the station has its own commander. + +## Ship Commander + +Each ship should have a ship commander, even if that commander is extremely simple. + +A ship commander is responsible for translating high-level intent into behavior. + +Responsibilities: + +- accept player or superior orders +- maintain standing doctrine when idle +- react to danger and safety rules +- choose the next immediate task +- handle travel and local action transitions + +Ship commanders may adopt behaviors that tie them closely to a station, such as mining or hauling for a station, without making the station commander their owner in the strict sense. + +A ship without a commander should be heavily limited. + +At minimum, a commanderless ship should only be able to: + +- remain idle +- hold position +- drift in a failsafe state +- accept direct external control if explicitly ordered + +It should not run meaningful autonomous loops. + +Typical outputs: + +- current destination node +- local tactical task +- retreat decision +- docking/refuel intent +- trade or delivery acceptance + +## Commander Ownership + +A commander may directly own: + +- one faction +- one station +- one ship +- a group of subordinate commanders + +Command should be hierarchical rather than flat. + +Examples: + +- a faction commander owns station commanders +- a station commander owns station-based ship commanders +- a fleet commander owns combat ship commanders + +Recommended ownership rule: + +- one commander should have one clear controlling scope +- delegation downward should be explicit +- conflicts should resolve through hierarchy, not through independent competing AI + +This means station command and ship command should remain distinct even when they cooperate heavily. + +## Delegation Model + +Commanders should not directly perform simulation actions. They should issue intent downward. + +Recommended flow: + +1. commander evaluates state +2. commander selects priorities +3. commander issues or updates orders +4. ship or station control logic turns orders into executable tasks +5. runtime state changes feed back into commander decisions + +This preserves separation between: + +- strategic intent +- operational planning +- physical execution + +Recommended command chain: + +1. faction commander sets strategic doctrine and priorities +2. station or fleet commander translates those into local objectives +3. ship commander turns local objectives into ship behavior +4. runtime movement and action systems execute the current task + +The deeper the layer, the shorter the planning horizon should be. + +See [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) for the execution-layer model beneath commander intent. + +## Player Interaction + +Players should be able to override commanders without deleting the command structure. + +Recommended rule: + +- direct player orders temporarily preempt commander autonomy +- once direct orders resolve, the unit resumes its commander-driven behavior + +That allows: + +- RTS-like intervention +- long-lived autonomous play + +Recommended override behavior: + +- player orders override the local commander immediately +- the superior command structure remains intact +- after the player order completes, the ship or station returns to commander control + +## Commander Doctrine + +Commanders should carry doctrine, not just orders. + +Examples: + +- risk tolerance +- engagement rules +- reserve thresholds +- trade policy +- build policy +- territorial preference +- preferred supply sources + +Doctrine is what lets two stations or factions behave differently even with similar assets. + +Doctrine should exist at multiple levels: + +- faction doctrine +- station doctrine +- fleet doctrine +- ship doctrine + +Lower-level doctrine should inherit from higher-level doctrine unless explicitly overridden. + +See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for explicit access and restriction rules that doctrine can express. + +Combat-specific doctrine and engagement behavior should be defined alongside the combat model in [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md). + +## Market Responsibility + +The market is not abstracted away from commanders. + +Commanders are expected to participate in the economy. + +In particular: + +- station commanders create buy and sell orders +- faction commanders shape economic policy +- ship commanders execute logistics and trade work in response to those incentives + +This is the main bridge between command AI and the market-driven simulation. + +Recommended responsibility split: + +- faction commander decides broad economic posture +- station commander publishes concrete local market intent +- ship commander accepts and executes logistics opportunities + +This avoids putting the whole economy in one planner. + +## Command And Market Loop + +The intended loop is: + +1. faction commander sets strategic priorities +2. station commander evaluates inventory, production, and risk +3. station commander updates buy and sell orders +4. ship commanders or higher logistics commanders select work from those opportunities +5. ships move goods through the spatial model +6. resulting stock and price changes feed back into commander decisions + +This loop should be a core backbone of the simulation. + +## Minimum Autonomy By Commander Type + +### Faction commander without subordinates + +Can do little beyond preserve faction identity and global flags. + +### Station without station commander + +Should be limited to: + +- passive existence +- fixed service availability if any +- emergency safety behavior only + +It may still receive externally forced support, but it should not run a healthy autonomous economy on its own. + +### Ship without ship commander + +Should be limited to: + +- idle +- hold +- explicit direct player order execution +- emergency retreat or failsafe only + +## Minimal Functional Rules + +The following rules should remain true unless there is a deliberate exception: + +- every active station should have a commander +- every active ship should have a commander +- every faction should have a commander +- commanders issue intent; they do not replace physical simulation +- direct player orders can override commanders temporarily +- stations participate in the economy through commander-set market behavior + +## Relationship To Other Documents + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - defines where action happens + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - defines how commanders express market participation + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - defines ship capabilities and behavior expectations + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - defines station roles and station-side responsibilities + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - defines population, worker growth, and commander generation + +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) + - defines access rules and operational restrictions commanders can set + +- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) + - defines how commanders apply threat posture and engagement behavior diff --git a/docs/DATA-MODEL.md b/docs/DATA-MODEL.md new file mode 100644 index 0000000..3fde84f --- /dev/null +++ b/docs/DATA-MODEL.md @@ -0,0 +1,501 @@ +# Data Model + +This document defines the intended high-level data model for the simulation. + +It is a design-side schema document. It does not describe the current codebase exactly. It describes the durable entity vocabulary the codebase should move toward. + +## Design Goals + +The data model should support: + +- the layered spatial model +- commander-driven behavior +- market-driven economy +- module-based capability +- population and workforce +- claimable construction sites +- local-space combat +- scalable replication and future sharding + +## Core Principles + +- important game concepts should exist as explicit entities or records +- IDs should be stable and durable +- spatial state should be explicit, not inferred from one generic position alone +- access, market, and behavior restrictions should be data-driven +- construction, production, and logistics should all use shared entity vocabulary + +## Identity + +Every major persistent entity should have: + +- a stable ID +- an owning faction where relevant +- a type or kind +- a current lifecycle or state + +Recommended global ID families: + +- `factionId` +- `commanderId` +- `systemId` +- `nodeId` +- `bubbleId` +- `stationId` +- `shipId` +- `moduleId` +- `claimId` +- `orderId` +- `recipeId` +- `policyId` +- `marketOrderId` +- `constructionSiteId` + +## Core Entity Set + +The intended core entities are: + +1. `Faction` +2. `Commander` +3. `System` +4. `Node` +5. `LocalBubble` +6. `Station` +7. `Ship` +8. `ModuleInstance` +9. `Claim` +10. `ConstructionSite` +11. `MarketOrder` +12. `Recipe` +13. `PolicySet` + +## Faction + +A faction is the top-level strategic actor. + +Suggested fields: + +- `factionId` +- `label` +- `color` +- `doctrine` +- `populationTotal` +- `credits` if retained +- `relation state to other factions` +- `commanderIds` +- `policy defaults` + +## Commander + +Commanders are first-class AI actors. + +Suggested fields: + +- `commanderId` +- `kind` +- `ownerFactionId` +- `parentCommanderId?` +- `controlledEntityId?` +- `doctrine` +- `policy overrides` +- `goal set` +- `subordinateCommanderIds` +- `alive` + +Recommended commander kinds: + +- `faction` +- `station` +- `ship` +- `fleet` +- `sector` +- `task-group` + +## System + +A system is a strategic world entity in galaxy space. + +Suggested fields: + +- `systemId` +- `label` +- `galaxyPosition` +- `star definition` +- `nodeIds` +- `faction influence later` + +## Node + +A node is a meaningful location in system space that owns a local bubble. + +Suggested fields: + +- `nodeId` +- `systemId` +- `kind` +- `systemPosition` +- `bubbleId` +- `parentNodeId?` +- `orbital metadata?` +- `occupyingStructureId?` + +Recommended node kinds: + +- `star` +- `planet` +- `moon` +- `lagrange-point` +- `station` +- `gate` +- `resource-site` +- `structure` + +## LocalBubble + +A local bubble is the tactical simulation context attached to one node. + +Suggested fields: + +- `bubbleId` +- `nodeId` +- `systemId` +- `radius` +- `occupantShipIds` +- `occupantStationIds` +- `occupantClaimIds` +- `occupantConstructionSiteIds` +- `serverAuthorityId later` + +## Station + +A station is a structure attached to a Lagrange-point node. + +Suggested fields: + +- `stationId` +- `ownerFactionId` +- `commanderId?` +- `nodeId` +- `systemId` +- `bubbleId` +- `moduleIds` +- `inventory` +- `population` +- `workforceCapacity` +- `workforceEfficiency` +- `power state` +- `policySetId?` +- `marketOrderIds` +- `construction state if incomplete` +- `docking state` + +## Ship + +A ship is a mobile actor that changes movement regime over time. + +Suggested fields: + +- `shipId` +- `ownerFactionId` +- `commanderId?` +- `shipClass` +- `role` +- `moduleIds` +- `inventory` +- `health` +- `power state` +- `currentSpatialState` +- `policySetId?` +- `current goal/order/task references` + +## ModuleInstance + +A module instance is a fitted capability component on a ship or station. + +Suggested fields: + +- `moduleId` +- `definitionId` +- `hostKind` +- `hostId` +- `category` +- `operational state` +- `construction state` +- `workforceRequirement` +- `power requirement` + +Recommended host kinds: + +- `ship` +- `station` + +## Claim + +A claim is a vulnerable object placed at a Lagrange point before construction. + +Suggested fields: + +- `claimId` +- `ownerFactionId` +- `commanderId?` +- `systemId` +- `nodeId` +- `bubbleId` +- `placedAt` +- `activatesAt` +- `state` +- `health` + +Recommended claim states: + +- `placed` +- `activating` +- `active` +- `destroyed` + +## ConstructionSite + +A construction site is the market-facing and build-facing record for an incomplete structure or expansion. + +Suggested fields: + +- `constructionSiteId` +- `ownerFactionId` +- `nodeId` +- `bubbleId` +- `targetKind` +- `targetDefinitionId` +- `requiredItems` +- `deliveredItems` +- `progress` +- `assignedConstructorIds` +- `marketOrderIds` +- `state` + +Recommended target kinds: + +- `station` +- `station-module` +- `ship later` + +## MarketOrder + +A market order expresses station-side demand or supply. + +Suggested fields: + +- `marketOrderId` +- `stationId` or `constructionSiteId` +- `ownerFactionId` +- `kind` +- `itemId` +- `amount` +- `remainingAmount` +- `valuation` +- `reserveThreshold?` +- `policy restrictions` +- `state` + +Recommended market order kinds: + +- `buy` +- `sell` + +Recommended market order states: + +- `open` +- `partially-filled` +- `filled` +- `cancelled` +- `expired later` + +## Recipe + +A recipe defines a conversion from inputs to outputs. + +Suggested fields: + +- `recipeId` +- `label` +- `inputItems` +- `outputItems` +- `cycleTime` +- `validModuleCategories` +- `powerRequirement?` +- `workforceModifier?` + +## PolicySet + +A policy set defines access and restriction rules. + +Suggested fields: + +- `policySetId` +- `ownerKind` +- `ownerId` +- `tradeAccessPolicy` +- `dockingAccessPolicy` +- `constructionAccessPolicy` +- `operationalRangePolicy` +- `hostility rules later` + +Recommended owner kinds: + +- `faction` +- `station` +- `commander` +- `ship` + +## Spatial State + +Ships should not be modeled with only one generic position and target. + +Recommended ship spatial state fields: + +- `spaceLayer` +- `currentSystemId` +- `currentNodeId?` +- `currentBubbleId?` +- `localPosition?` +- `systemPosition?` +- `movementRegime` +- `destinationNodeId?` +- `transitState?` + +Recommended space layers: + +- `universe-space` +- `galaxy-space` +- `system-space` +- `local-space` + +Recommended movement regimes: + +- `local-flight` +- `warp` +- `stargate-transit` +- `ftl-transit` + +## Population State + +Population should remain explicit rather than hidden in generic inventory only. + +Suggested station-side workforce fields: + +- `population` +- `populationCapacity` +- `workforceRequired` +- `workforceEffectiveRatio` +- `workerConsumptionRates` + +Commanders should not be ordinary cargo items even if they are population-derived. + +## Power State + +Ships and stations both need explicit operational power state. + +Suggested fields: + +- `fuelInventory` +- `energyStored` +- `powerOperational` +- `powerDeficitReason?` + +This matters because no fuel leads to no power, and no power halts major operations. + +## Inventories + +Inventories should remain generic item maps, but hosts should also have explicit context. + +Recommended inventory host kinds: + +- `ship` +- `station` +- `construction-site` + +This prevents construction storage from being a special-case invisible system. + +## Ownership vs Access + +The model should separate: + +- ownership +- commander control +- policy-based access +- current occupancy + +These are not the same thing. + +Examples: + +- a faction owns a station +- a station commander operates it +- another faction may be allowed to trade there +- multiple factions may be present in the same system + +## Minimum Enums + +The following enum families should exist somewhere in the model: + +- `SpaceLayer` +- `MovementRegime` +- `NodeKind` +- `CommanderKind` +- `ModuleCategory` +- `MarketOrderKind` +- `MarketOrderState` +- `ClaimState` +- `ConstructionTargetKind` +- `TradeAccessPolicy` +- `DockingAccessPolicy` +- `OrderState` +- `TaskState` +- `TaskKind` + +## Replication Implication + +This entity model is also intended to support replication. + +That means entity shape should make it easy to stream: + +- strategic summaries from higher layers +- detailed updates from lower layers +- explicit lifecycle changes +- explicit claim, market, and construction updates + +See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the typed event layer built on top of this model. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- important world concepts should have explicit records +- ships need explicit spatial state +- claims and construction sites are real entities +- market orders are real entities +- modules are real instances attached to hosts +- policy is separate from ownership +- population is explicit at the station level + +## Relationship To Other Documents + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - defines the layered world structure + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - defines commander roles and hierarchy + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - defines market behavior + +- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md) + - defines capability-bearing module instances + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - defines population and commander generation + +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) + - defines the policy sets attached to entities + +- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) + - defines the execution-layer fields that entities should carry diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..ba4e833 --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,108 @@ +# Design Documents + +This repository uses a small set of official design documents to define intended gameplay and simulation behavior. + +These documents are design-first. They describe target structure and rules, not temporary implementation status. + +For the implementation migration path from the current codebase to this design set, see [ROADMAP.md](/home/jbourdon/repos/space-game/docs/ROADMAP.md). + +## Core Documents + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - spatial layers + - nodes and local bubbles + - movement regimes + - viewer scale expectations + - replication and interest management implications + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - commander roles for factions, stations, and ships + - command hierarchy + - orders, doctrine, and delegation + - minimum autonomy rules + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - market-driven simulation + - buy and sell orders + - station market behavior + - logistics and production incentives + +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) + - item categories + - life-support goods + - construction goods + - fuel-chain goods + - population-related units + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - population + - habitats + - workforce efficiency + - worker transport + - commander generation + +- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md) + - ship and station module categories + - capability gating + - workforce and power interaction + - module-driven growth and specialization + +- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) + - recipes and conversion logic + - module-driven processing + - throughput and queues + - construction as production + +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) + - trade and docking permissions + - construction access + - territorial and regional restrictions + - policy-based behavior limits + +- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) + - local-space combat + - piracy and station defense + - claim destruction and contest + - commander-driven engagement behavior + +- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) + - core entities and IDs + - major enums + - runtime fields implied by the design + - replication-friendly entity vocabulary + +- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) + - typed world events + - lifecycle and replication visibility + - market, construction, and combat event families + - human-readable summaries for logs and UI + +- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) + - goals, orders, behaviors, tasks, and states + - planner precedence + - executable ship and station work + - safety and policy-aware tasking + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - ship roles + - movement capabilities + - onboard command requirements + - ship behavior expectations + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - station roles + - local bubble functions + - station command requirements + - station services, docking, and market responsibilities + +## Document Rules + +These documents should aim to: + +- define durable game concepts +- avoid temporary work logs +- avoid implementation changelists +- avoid short-lived task lists +- reference each other where concepts overlap + +If a note is only about current runtime state, active experiments, or a one-off migration, it should not live in the official design set. diff --git a/docs/ECONOMY.md b/docs/ECONOMY.md new file mode 100644 index 0000000..19a7b99 --- /dev/null +++ b/docs/ECONOMY.md @@ -0,0 +1,349 @@ +# Economy + +This document defines the intended economic model for the simulation. + +The economy should be market driven. + +That means production, transport, shortages, and prices should emerge from station behavior, commander intent, and resource availability rather than from fixed scripted chains alone. + +See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the intended entity vocabulary behind market orders, construction sites, and policy sets. + +## Design Goals + +The economy should support: + +- real shortages and surpluses +- trade incentives +- meaningful logistics +- station specialization +- commander-driven buy and sell behavior +- faction growth constrained by market conditions +- workforce support through life-support goods + +See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the shared item vocabulary behind these flows. + +## Core Principle + +Stations participate in the economy by publishing market intent. + +The primary mechanism is: + +- buy orders +- sell orders + +These orders should be created and maintained by station commanders. + +## Market Actors + +The intended market actors are: + +- stations +- factions +- ships acting on behalf of commanders + +Stations are the main visible market nodes. + +Factions shape policy and strategy. + +Ships execute transport, procurement, and delivery. + +For now, market exchange should be station-centric: + +- ship-to-station trading is supported +- ship-to-ship trading is out of scope for now + +## Market Units + +The economy should be expressed through explicit market units rather than vague station desires. + +Recommended market units: + +- `buy order` +- `sell order` +- `reservation` +- `fulfilled trade` +- `cancelled trade` + +This gives the economy observable state and event history. + +See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the market and trade event families that should represent this history. + +## Buy Orders + +A buy order expresses that a station wants to acquire a resource. + +A buy order should include, conceptually: + +- item +- desired amount +- price or valuation +- minimum delivery size if needed +- urgency or priority +- optional sourcing restrictions + +Buy orders let a station express: + +- production input demand +- fuel shortages +- construction material shortages +- military resupply needs + +Construction storage for a planned station should be allowed to publish buy orders before the finished station is fully operational. + +Recommended additional fields later: + +- issuing station +- expiry or review time +- maximum acceptable route cost +- whether partial fulfillment is acceptable + +## Sell Orders + +A sell order expresses that a station is willing to release a resource. + +A sell order should include, conceptually: + +- item +- offered amount +- price or valuation +- reserve threshold +- optional buyer restrictions + +Sell orders let a station express: + +- exportable surplus +- intentional specialization +- market-facing production + +Recommended additional fields later: + +- issuing station +- reserve floor +- preferred buyer class if needed +- priority relative to internal faction demand + +## Station Commander Market Role + +The station commander is responsible for market participation. + +The station commander should: + +- observe stock levels +- observe production demand +- observe dock throughput and logistics health +- set or adjust buy orders +- set or adjust sell orders +- choose production priorities +- request support when shortages threaten station function + +Without a station commander, a station should not act like a healthy market participant. + +If the station has no fuel and therefore no power, it should not continue normal market operation. + +However, there is an important exception during founding or emergency intervention: + +- a higher actor may force transfers toward the station or construction site even without ordinary market behavior + +Recommended review loop: + +1. inspect current inventory +2. inspect production queues or goals +3. inspect incoming and outgoing reservations +4. inspect fuel, defense, and construction reserves +5. update buy orders +6. update sell orders +7. request logistics or strategic help if necessary + +## Prices And Valuation + +The design does not require a single global static price list. + +It is better to think in terms of valuation driven by: + +- local scarcity +- strategic need +- production usefulness +- reserve thresholds +- faction doctrine + +This allows stations to value the same item differently at different times. + +Recommended interpretation: + +- prices are not only “market prices” +- they are commander valuations +- commander valuations can still produce a market when many actors interact + +There should not be a mandatory fixed global baseline price underneath this system. + +Traders should optimize for profit, not just headline sale price. + +## Resource Flow + +The intended economy should eventually support flows such as: + +1. extract raw resources +2. move them to useful stations +3. refine or process them +4. consume them for fuel, production, or expansion +5. produce intermediate and advanced goods +6. sell surpluses or acquire shortages through the market + +The important design point is that each stage should create economic pressure for the next, not just scripted state transitions. + +See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the conversion-side rules behind these flows. + +## Logistics + +Logistics should emerge from market demand, not only from hardcoded behavior loops. + +Examples: + +- a hauler sees a profitable sell-to-buy opportunity +- a station commander requests urgent fuel delivery +- a faction commander subsidizes strategic resource movement + +This is a better long-term basis than one-off scripted “mine and deliver to this exact station” logic. + +Traders should generally prefer the best reachable buy opportunity within their allowed operational range, subject to: + +- travel time +- fuel cost +- risk +- behavioral restrictions +- territorial or regional limits + +Recommended logistics sources of work: + +- open buy orders +- profitable route opportunities +- commander-assigned emergency deliveries +- faction-priority strategic transfers + +Not every cargo move needs to be pure free-market behavior, but the market should be the baseline. + +Behavior-restricted work should still exist. + +Example: + +- `mine-for-station` is a constrained behavior, not a different economic ontology + +The ship still sells into the market structure, but with restrictions on where and for whom it will trade. + +## Reservations And Commitments + +The economy will work better if stations can reserve expected inventory changes. + +Examples: + +- incoming fuel is reserved for station power +- outbound metals are reserved for a construction project +- a hauler claims part of a sell order before pickup + +Without reservations, the same goods are too easy to double-allocate. + +Current design choice: + +- first one to deliver wins + +This means market competition can remain simple at first, even if fuller reservation logic is introduced later for other workflows. + +## Market Visibility + +Market intent should generally be open knowledge, subject to access rules. + +The baseline assumption is that buy and sell orders are visible to authorized observers and usable as input for commander planning. + +Worker support goods are economically important because workforce depends on them. See [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). + +Those support goods are defined as item roles in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md). + +## Market And Space + +The market should respect the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md). + +Implications: + +- stations are nodes with local bubbles +- docking and transfer happen in local-space +- in-system logistics move through warp between nodes +- inter-system trade moves through stargates or FTL + +Distance and travel friction should matter economically. + +This means: + +- a nearby station may be economically better than a richer but distant one +- warp and dock congestion affect profitability +- inter-system trade should be slower and riskier than local trade + +Operational range restrictions should come from behavior and policy, not only from physics. + +Examples: + +- stay in-system +- stay in-region +- faction-only trade +- station-serving behavior + +See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for the policy layer behind these restrictions. + +## Minimal Functional Rules + +The following rules should remain true unless deliberately broken: + +- stations express demand through buy orders +- stations express surplus through sell orders +- station commanders manage those orders +- logistics ships respond to economic incentives, not only fixed scripts +- shortages should propagate into visible gameplay effects +- market state should influence production, travel, and expansion + +## Minimum Viable Economic Loop + +The smallest useful version of this system would be: + +1. stations publish buy and sell orders +2. station commanders update those orders from inventory thresholds +3. logistics ships choose a station demand to satisfy +4. cargo transfer creates reservations +5. delivery fulfills reservations and updates inventory +6. shortages and surpluses visibly change future orders + +## Station Construction Demand + +A planned station should generate economic demand before full completion. + +The recommended mechanism is: + +1. claim becomes active +2. construction storage appears +3. station design determines required build materials +4. construction storage publishes buy orders for those materials +5. deliveries accumulate +6. constructor ships consume them into built progress + +This lets station construction participate directly in the same economic model as ordinary station operation. + +## Relationship To Other Documents + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - defines who owns market decisions + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - defines station roles and market participation + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - defines logistics and industrial ship roles + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - defines population demand and workforce consequences + +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) + - defines the item categories moving through the market + +- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) + - defines how goods are transformed into other goods over time + +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) + - defines who may participate in trade and under what restrictions diff --git a/docs/EVENTS.md b/docs/EVENTS.md new file mode 100644 index 0000000..c888565 --- /dev/null +++ b/docs/EVENTS.md @@ -0,0 +1,328 @@ +# Events + +This document defines the intended event model for the simulation. + +Events are the explicit record of meaningful changes in the world. + +They should support gameplay logic, debugging, UI presentation, replication, and future persistence. + +## Design Goals + +The event model should support: + +- clear lifecycle visibility +- replayable and inspectable world changes +- useful observer replication +- commander and player feedback +- debugging without relying on implicit state diffs only + +## Core Principles + +- important world changes should emit explicit events +- events should reference stable entity IDs +- events should be typed, not only free-form text +- events should be useful for both machines and humans +- event detail should vary by space layer and relevance + +## Event Structure + +Every event should conceptually have: + +- `eventId` +- `sequence` +- `occurredAt` +- `kind` +- `spaceLayer` +- `systemId?` +- `bubbleId?` +- `primaryEntityKind` +- `primaryEntityId` +- `relatedEntityIds` +- `payload` +- `humanSummary` + +This preserves both programmatic utility and debug readability. + +## Event Scope + +Events should naturally inherit spatial scope from the world model. + +Examples: + +- universe-scale events belong to `universe-space` +- strategic system events belong to `galaxy-space` or `system-space` +- combat, docking, and claims belong to `local-space` + +This is important for interest management. + +## Event Families + +The major event families should be: + +1. lifecycle events +2. movement events +3. market events +4. production events +5. construction events +6. population events +7. policy events +8. combat events +9. commander events +10. replication/system events + +## Lifecycle Events + +These describe entity creation, destruction, and state milestones. + +Examples: + +- `ship-created` +- `ship-destroyed` +- `station-founded` +- `station-destroyed` +- `claim-placed` +- `claim-destroyed` +- `construction-started` +- `construction-completed` +- `commander-created` +- `commander-killed` + +These are especially important because entity lifecycles should not be inferred only from snapshots. + +## Movement Events + +These describe meaningful transitions in movement regime or location context. + +Examples: + +- `entered-local-bubble` +- `left-local-bubble` +- `warp-spooling-started` +- `warp-started` +- `warp-arrived` +- `stargate-transit-started` +- `ftl-transit-started` +- `dock-requested` +- `dock-granted` +- `dock-denied` +- `docked` +- `undocked` + +Movement events should capture transitions, not every tiny positional change. + +## Market Events + +These describe market intent and fulfillment. + +Examples: + +- `buy-order-opened` +- `buy-order-updated` +- `buy-order-filled` +- `buy-order-cancelled` +- `sell-order-opened` +- `sell-order-updated` +- `sell-order-filled` +- `sell-order-cancelled` +- `trade-delivered` +- `trade-rejected` + +These events are useful for: + +- economic debugging +- UI history +- future analytics + +## Production Events + +These describe recipe and processing state. + +Examples: + +- `recipe-started` +- `recipe-blocked-no-input` +- `recipe-blocked-no-power` +- `recipe-completed` +- `production-stalled-output-full` + +Production events should explain why stations are or are not producing. + +## Construction Events + +These describe founding, module expansion, and build progress. + +Examples: + +- `claim-activation-started` +- `claim-activated` +- `construction-storage-created` +- `construction-material-delivered` +- `construction-progressed` +- `module-construction-started` +- `module-construction-completed` +- `station-construction-completed` + +Construction events are especially important because claims and building are contestable. + +## Population Events + +These describe demographic and workforce changes. + +Examples: + +- `population-grew` +- `population-transferred` +- `population-arrived` +- `population-loss-food` +- `population-loss-water` +- `population-loss-energy` +- `commander-generated` + +These help explain why a station's efficiency is changing. + +## Policy Events + +These describe access and restriction changes. + +Examples: + +- `trade-policy-changed` +- `docking-policy-changed` +- `construction-policy-changed` +- `range-policy-changed` + +These are useful because policy changes alter behavior without directly changing physical state. + +## Combat Events + +These describe tactical engagement and destruction. + +Examples: + +- `combat-started` +- `target-acquired` +- `under-attack` +- `claim-attacked` +- `construction-site-attacked` +- `ship-damaged` +- `ship-destroyed` +- `station-damaged` +- `station-defense-engaged` +- `pirate-raid-detected` +- `retreat-started` + +Combat events should favor meaningful state changes over weapon-by-weapon spam. + +## Commander Events + +These describe decision-level changes by AI authority. + +Examples: + +- `commander-created` +- `commander-assigned` +- `commander-killed` +- `goal-changed` +- `doctrine-changed` +- `priority-changed` +- `support-requested` + +These make it easier to understand why entities changed behavior. + +Task and order transition events should also exist as a first-class part of the event model. + +Examples: + +- `order-accepted` +- `order-cancelled` +- `task-started` +- `task-blocked` +- `task-completed` +- `task-failed` +- `behavior-changed` + +See [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) for the planner and execution model behind these transitions. + +## Replication And System Events + +These describe transport-level or observer-level system changes. + +Examples: + +- `snapshot-issued` +- `delta-issued` +- `observer-scope-changed` +- `requires-refresh` + +These may remain more internal than gameplay-facing, but they still benefit from consistent typing. + +## Event Visibility + +Not every observer needs every event. + +The intended rule should be: + +- high-layer events are broad and low-detail +- low-layer events are narrow and high-detail + +Examples: + +- a local viewer should see nearby combat and docking events +- a system viewer should see claim and station progress events +- a galaxy viewer may only need summarized strategic events + +## Event Retention + +The runtime may not keep full history forever, but events should still be designed as if they are useful beyond one frame. + +Useful retention targets: + +- short-term debug history +- player-facing notifications +- recent replication catch-up +- future persistence or replay systems + +## Human Summary + +Every event should be capable of producing a concise human-readable summary. + +Example style: + +- `Claim at Helios IV L4 destroyed by pirates` +- `Station buy order for fuel opened` +- `Miner completed warp to refinery node` + +This helps reuse the same event model for: + +- logs +- notifications +- debug panels +- event history UI + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- important world changes emit typed events +- events reference stable entity IDs +- events carry enough scope for interest management +- events should support both machine use and human summaries +- lifecycle events should not rely only on snapshot inference +- local combat and construction conflict should be explicitly represented + +## Relationship To Other Documents + +- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) + - defines the entities referenced by events + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - defines event scope by space layer + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - defines market and trade-related event domains + +- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) + - defines recipe and production event domains + +- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) + - defines combat and claim-related event domains diff --git a/docs/ITEMS.md b/docs/ITEMS.md new file mode 100644 index 0000000..5662fb5 --- /dev/null +++ b/docs/ITEMS.md @@ -0,0 +1,227 @@ +# Items + +This document defines the intended item vocabulary for the simulation. + +Items are the goods that move through the economy, sustain population, enable construction, and support logistics. + +The goal of this document is not to lock every final item name immediately. It is to define the categories and roles that the economy depends on. + +## Design Goals + +The item model should support: + +- market-driven trade +- construction demand +- station operation +- workforce support +- transport specialization +- future industrial depth without immediate overcomplication + +## Core Principles + +- items should have clear economic purpose +- items should belong to recognizable categories +- population needs should be represented with real goods +- station construction should consume real goods +- cargo specialization should matter where useful + +## Major Item Categories + +The intended categories are: + +1. raw resources +2. processed industrial goods +3. life-support goods +4. civilian goods +5. fuel and power-chain goods +6. construction goods +7. population-related units +8. special logistics goods later + +## Raw Resources + +These are extracted directly from the world or from near-direct processing. + +Examples: + +- ore +- gas +- water if treated as an extractable resource +- biological feed inputs later if needed + +Raw resources are the base of the production chain. + +## Processed Industrial Goods + +These are materials produced from raw resources and used for further production. + +Examples: + +- refined metals +- structural materials +- electronics later +- machinery later + +These goods should feed construction, station operation, and advanced industry. + +## Life-Support Goods + +These are required to sustain population. + +Core life-support goods: + +- food +- water +- energy + +These are not optional luxuries. They are fundamental operating requirements for workforce survival. + +## Civilian Goods + +These are goods consumed by population beyond pure survival. + +Current important example: + +- consumer goods + +These goods should matter for workforce health, quality of life, and possibly future growth modifiers. + +## Fuel And Power-Chain Goods + +These are the goods that keep ships and stations running. + +Examples: + +- gas as an energy-chain input +- fuel as a refined operational good + +The exact chain may evolve, but the important distinction is: + +- some goods are energy inputs +- some goods are operational fuels + +## Construction Goods + +These are the goods used to build stations and possibly ships. + +Examples: + +- station construction materials +- ship construction materials +- module construction materials + +The exact item split can remain flexible for now, but construction should consume real goods rather than abstract progress only. + +Construction storage at a station site should create demand for these goods through the normal market system. + +## Population-Related Units + +Population itself should be treated as a tracked resource, but not as an ordinary trade good in the same sense as metal or fuel. + +Important distinctions: + +- workers are population units +- commanders are population-derived special units +- workers can be transported +- commanders are created from population over time + +Population transport should remain controlled by workforce and ship rules rather than being treated as a trivial cargo commodity. + +## Livestock And Food Loop + +Livestock should exist as part of the food loop. + +This implies: + +- livestock is distinct from workers +- livestock may require dedicated transport or handling rules later +- livestock supports food production rather than station staffing + +## Item Role Examples + +The current design implies at least these roles: + +- `ore` + - raw industrial input + +- `gas` + - raw fuel-chain input + +- `fuel` + - operational energy good + +- `food` + - workforce life-support + +- `water` + - workforce life-support + +- `consumer-goods` + - workforce support / civilian demand + +- `workers` + - transported population units + +- `construction-materials` + - station and module building input + +The final names can change, but the economic roles should stay stable. + +## Storage And Compatibility + +Not every item should necessarily fit in every hold type forever. + +Useful distinctions later may include: + +- bulk industrial cargo +- liquid cargo +- gas cargo +- containerized finished goods +- human transport capacity +- livestock capacity + +For now, the important rule is simply: + +- item class should eventually matter for transport and storage design + +## Market Behavior + +Items should participate in the market according to their role. + +Examples: + +- life-support goods generate recurring demand +- fuel goods generate operational demand +- construction goods generate burst demand during expansion +- industrial goods feed production chains +- worker transport supports station staffing + +This should help the economy create natural recurring and temporary market pressures. + +## Item Importance To Other Systems + +Items are the bridge between major game systems: + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - buy and sell orders are item-driven + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - population survival depends on specific goods + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - station construction and operation consume goods + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - ship transport depends on what kind of item is being moved + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- workforce depends on real support goods +- station construction depends on real construction goods +- fuel and industrial chains are item-based +- workers are movable population units +- commanders are not ordinary trade cargo +- livestock is distinct from workers +- item categories should eventually matter for storage and transport diff --git a/docs/MODULES.md b/docs/MODULES.md new file mode 100644 index 0000000..d0aaf09 --- /dev/null +++ b/docs/MODULES.md @@ -0,0 +1,294 @@ +# Modules + +This document defines the intended module model for ships and stations. + +Modules are the primary way ships and stations gain capability. + +They determine what an entity can do, what goods it can handle, what services it can provide, and how much workforce or support it requires. + +## Design Goals + +The module system should support: + +- X4-style composable stations +- role-defined ships without excessive hardcoding +- meaningful logistics and infrastructure requirements +- clear capability gating +- future expansion without changing the basic architecture + +## Core Principles + +- ships and stations gain most capabilities through modules +- modules should define function, not just stats +- modules should have real operational requirements +- modules should interact with workforce, items, and command logic +- a hull or station frame without the right modules should be meaningfully limited + +## Module Ownership + +Modules belong to either: + +- ships +- stations + +Some module categories conceptually exist on both, but their use may differ. + +Examples: + +- storage +- habitat +- power-related modules + +## Capability Gating + +Modules should gate real gameplay abilities. + +Examples: + +- no docking module means no docking service +- no habitat module means no population growth or human transport +- no refinery module means no refining +- no fuel-processing module means no gas-to-fuel conversion +- no storage module means reduced or absent inventory capability +- no shipyard-related module means no ship production + +This should remain a core rule of the simulation. + +## Ship Modules + +Ship modules define what a ship can do. + +Likely ship-side categories include: + +- reactor or power generation +- capacitor or energy buffer +- thruster package later if separated +- warp-capable propulsion support later if needed +- FTL capability where applicable +- cargo storage +- habitat for human transport +- livestock transport +- mining equipment +- gas harvesting equipment +- weapons +- support or utility systems later + +Ship identity should be influenced by: + +- hull class +- fitted modules +- commander behavior + +Not every industrial role needs a distinct hardcoded hull if modules can express the difference clearly enough. + +## Station Modules + +Station modules define what a station can do. + +Likely station-side categories include: + +- power generation +- docking +- storage +- habitat +- refinery +- fuel processing +- manufacturing +- shipyard or construction support +- defense +- trade or logistics support later +- livestock or food-chain support later + +Station identity should largely come from module composition. + +This is especially important because your station model is configuration-based rather than having every station type be a wholly separate structure class. + +## Structural Rule + +Stations are built at one Lagrange point and expanded by adding modules. + +That means modules are the main axis of station growth. + +A station does not sprawl across multiple sites. + +## Module Categories + +For design purposes, modules can be grouped into a few major classes: + +1. structural modules +2. operational modules +3. production modules +4. logistics modules +5. population modules +6. military modules + +### Structural Modules + +These define physical expansion and attachment capacity. + +Examples: + +- core station body +- structural extensions +- future hardpoint or attachment frames + +### Operational Modules + +These keep the entity functioning. + +Examples: + +- reactor +- capacitor +- station power core +- fuel systems + +### Production Modules + +These convert goods into other goods or into built output. + +Examples: + +- refinery +- fuel processor +- factory +- shipyard support + +### Logistics Modules + +These let an entity store, receive, and move goods or people. + +Examples: + +- cargo storage +- docking bay +- transfer systems later +- habitat transport support +- livestock handling + +### Population Modules + +These support humans and long-term station staffing. + +Examples: + +- habitat +- civilian support modules later + +Population modules are especially important because they connect stations to [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). + +### Military Modules + +These allow defense and force projection. + +Examples: + +- turrets +- missile systems later +- shield or defensive utility later +- station defense platforms as module sets + +## Module Requirements + +Modules should not be treated as free magic unlocks. + +They may require: + +- construction materials +- build time +- power +- workforce +- fuel or energy inputs +- docking or logistics support + +This should let stations and ships fail in believable ways when underbuilt or undersupplied. + +## Workforce Interaction + +Modules should interact with workforce through a simple rule at first: + +- every module contributes to the station's workforce requirement +- workforce satisfaction scales module effectiveness equally + +That keeps the first model simple while preserving the idea that bigger stations need more people. + +## Item Interaction + +Modules should define which item flows an entity can participate in. + +Examples: + +- a habitat module enables population support +- a fuel-processing module consumes gas and produces fuel +- a refinery consumes raw resources and produces processed goods +- a storage module determines what volume or class of goods can be held +- a livestock module participates in the food chain + +See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the item-side vocabulary. +See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the recipe-side model. + +## Construction And Module Demand + +Module construction should use the same economic logic as station construction more broadly. + +That means: + +- module builds consume real goods +- construction storage can publish demand +- expansion creates burst economic pressure + +This keeps station growth tied to the market rather than detached from it. + +## Operational Failure + +Modules should help determine failure modes. + +Examples: + +- no power means operational modules fail +- no docking module means the station cannot offer docking service +- no habitat means no local population growth +- no storage means goods handling becomes impossible or severely constrained + +This helps capability loss emerge from the world state instead of from arbitrary toggles. + +## Fitting Philosophy + +The intended philosophy should be: + +- hulls and station frames define limits +- modules define capabilities + +That means the simulation should avoid making every role a unique special-case entity if a module composition can express it more cleanly. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- modules gate real capabilities +- stations grow by module addition at one location +- ships depend on fitted modules for specialized roles +- modules consume real construction goods +- modules interact with workforce and power +- habitat modules are required for population support or human transport +- storage and logistics modules matter for market participation + +## Relationship To Other Documents + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - station growth and services + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - ship capabilities and specialization + +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) + - goods consumed or enabled by modules + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - workforce and habitat interaction + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - market demand created by module construction and operation + +- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) + - recipes executed by production-capable modules diff --git a/docs/POLICIES.md b/docs/POLICIES.md new file mode 100644 index 0000000..ae3becf --- /dev/null +++ b/docs/POLICIES.md @@ -0,0 +1,199 @@ +# Policies + +This document defines policy rules for trade, docking, construction access, territorial behavior, and operational restrictions. + +Policies are how commanders turn general strategy into concrete permissions and limits. + +They sit between diplomacy, economy, space control, and ship behavior. + +## Design Goals + +The policy model should support: + +- policy-based market access +- policy-based docking and service access +- regional or system-limited ship behavior +- construction rights at valuable locations +- faction differentiation without changing core mechanics + +## Core Principles + +- policy should constrain behavior without replacing command AI +- access should be explicit rather than assumed +- policy can restrict market participation even when market data is visible +- policy should operate at multiple levels +- ships and stations should obey policy limits when selecting work + +## Policy Levels + +Policies should exist at multiple levels: + +- faction policy +- station policy +- ship or commander behavior policy + +Higher-level policy sets the default. + +Lower-level policy may narrow or specialize it. + +Examples: + +- a faction allows trade with neutrals +- one station is faction-only +- one ship is restricted to a single system + +## Trade Access Policy + +Trade access determines who may participate in a station's market. + +Possible policies include: + +- open trade +- faction-only trade +- friendly-only trade +- whitelist-based trade later +- blacklist-based trade later + +Important distinction: + +- market information may be visible +- actual participation may still be restricted by policy + +This preserves your rule that station market intent is generally open knowledge while still allowing trade control. + +## Docking Policy + +Docking access should also be policy-controlled. + +Possible policies include: + +- open docking +- faction-only docking +- friendly-only docking +- emergency-only docking later +- denied docking for hostile factions + +Docking policy matters because no trade or transfer can happen without actual local access. + +## Construction Policy + +Construction rights should be policy-relevant at the faction and system level. + +This does not override the hard structural rule from [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md): + +- one structure per Lagrange point + +But it does help define who is permitted or tolerated to claim and build in a given system. + +Examples: + +- a faction allows allies to build in its system +- a faction contests all foreign construction +- piracy or warfare makes claims vulnerable regardless of nominal policy + +## Operational Range Policy + +Ships should be able to operate under geographic or territorial restrictions. + +Examples: + +- stay in local system +- stay in assigned region +- stay near assigned station +- use only faction-controlled stations +- avoid hostile territory + +These restrictions should be expressible as policy and behavior, not only as one-off hardcoded AI. + +## Behavior Restrictions + +Policy should be able to constrain ship work selection. + +Examples: + +- a trader may only serve faction stations +- a miner may only sell within one system +- a hauler may ignore low-profit trades outside an assigned region +- a station-serving ship may prioritize one station's needs even when broader market opportunities exist + +This is how the simulation gets meaningful local identities and doctrines. + +## Market Visibility vs Market Access + +These should remain separate concepts. + +Baseline design: + +- station market intent is generally visible +- actual buying, selling, docking, or transfer may still be restricted by policy + +This is important because intelligence and permission are not the same thing. + +## Policy And Commanders + +Policies should be authored or maintained by commanders. + +Recommended responsibility split: + +- faction commander sets broad access and territorial doctrine +- station commander sets station-specific access and market policy +- ship commander applies local behavioral restrictions when choosing work + +This keeps policy tied to decision-making rather than existing as disconnected static data. + +## Policy And Diplomacy + +Policy should eventually connect to faction relationships. + +Examples: + +- friendly factions may trade and dock +- neutral factions may trade but not build +- hostile factions may be denied docking and targeted in local-space + +The exact diplomacy system can evolve later, but policy should be ready to consume those relationship states. + +## Policy And Claims + +Claim objects at Lagrange points are visible and contestable. + +Policy influences: + +- who may place claims without triggering hostility +- who is tolerated in a system +- who may receive peaceful access to build + +But policy should not make claims magically invulnerable. + +Claims remain physically contestable objects. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- trade access is policy-based +- docking access is policy-based +- behavior range restrictions are policy-capable +- market visibility and market access are separate +- station and faction commanders should be able to define access rules +- policy constrains work selection without replacing command logic + +## Relationship To Other Documents + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - commanders define and apply policy + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - policy constrains trade participation + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - policy interacts with claims, systems, and local access + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - station commanders apply local market and docking policy + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - ship behavior should obey operational restrictions + +- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) + - policy interacts with hostility, defense, and contested access diff --git a/docs/PRODUCTION.md b/docs/PRODUCTION.md new file mode 100644 index 0000000..0193927 --- /dev/null +++ b/docs/PRODUCTION.md @@ -0,0 +1,271 @@ +# Production + +This document defines the intended production model for the simulation. + +Production is how modules consume inputs over time and turn them into useful outputs. + +It connects items, modules, workforce, and market behavior into a continuous economic loop. + +## Design Goals + +The production model should support: + +- clear input-to-output conversion +- station specialization through module choice +- real supply-chain pressure +- visible bottlenecks +- workforce-sensitive throughput +- construction as part of the same economic logic + +## Core Principles + +- production should consume real goods +- production should take time +- production should depend on module capability +- production should be affected by workforce and power state +- shortages should halt or degrade output naturally + +## Production Units + +The core production concepts should be: + +- `recipe` +- `production module` +- `input inventory` +- `output inventory` +- `cycle time` +- `throughput` + +This is enough to define most of the industrial simulation at a high level. + +## Recipes + +A recipe is a conversion rule from one set of goods to another. + +A recipe should conceptually define: + +- required input items +- produced output items +- cycle time +- valid producing module types +- optional workforce requirement +- optional power or fuel requirement + +Recipes should be first-class design objects, not hidden assumptions inside modules. + +## Production Modules + +Recipes are executed by production-capable modules. + +Examples: + +- refinery module +- fuel processing module +- factory module +- food-chain module later +- shipyard support module + +Modules define what recipes an entity can run. + +Recipes define what actual transformation occurs. + +## Production Flow + +The intended production flow is: + +1. a station has the required production module +2. required inputs exist in inventory +3. the module has enough power and operational support +4. the recipe runs for its cycle time +5. outputs are added to station inventory +6. the station commander updates market behavior based on new shortages or surpluses + +This keeps production grounded in world state rather than in abstract magic conversion. + +## Time And Throughput + +Production should be time-based. + +That means: + +- recipes take time to complete +- modules have finite throughput +- more modules should generally mean more production capacity +- better staffing should improve effective throughput + +Throughput should be visibly affected by: + +- module count +- workforce percentage +- input availability +- power availability + +## Workforce Interaction + +Production should respect the workforce rules in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). + +For now: + +- workforce scales production effectiveness the same way it scales other module effectiveness +- zero-workforce stations still retain baseline production +- full staffing yields peak production + +This keeps the initial system consistent and simple. + +## Power Interaction + +Production should also respect power and fuel state. + +Without power: + +- production stops + +This is especially important for stations because no-fuel means no-power, and no-power means no normal operation. + +## Input Shortage Behavior + +If inputs are missing: + +- the recipe cannot complete + +This should naturally create market demand rather than needing a special shortage system layered on top. + +Input shortage should be one of the primary reasons station commanders publish buy orders. + +## Output And Inventory Pressure + +Production also depends on output handling. + +If output storage is full or constrained: + +- production should stop or stall + +This gives storage modules and logistics real importance. + +## Example Production Chains + +The exact recipes can evolve, but the intended shape includes chains like: + +1. raw extraction + - ore + - gas + - water later if extracted directly + +2. refining or processing + - ore -> refined goods + - gas -> fuel + - food-loop conversions later + +3. industrial use + - refined goods -> construction goods + - processed goods -> module or ship build inputs + +4. population support + - food, water, energy, consumer goods -> workforce survival and growth support + +These chains should create meaningful interdependence between station roles. + +## Construction As Production + +Construction should be treated as a special production form rather than a completely unrelated system. + +This applies to: + +- station founding +- station module expansion +- ship construction later + +The same general pattern should hold: + +1. desired build target defines required goods +2. required goods are delivered +3. build progress consumes those goods over time +4. build output becomes a completed structure, module, or ship + +This keeps construction inside the same economic language as the rest of the simulation. + +## Construction Storage + +Construction storage should act as the temporary industrial interface for building. + +It should: + +- hold required construction goods +- publish demand through buy orders +- allow delivery by traders or support ships +- feed the actual building process + +This is especially important during station founding at claimed Lagrange points. + +## Production Queues + +Stations should eventually be able to run more than one productive concern at once. + +The exact queue model can stay simple for now, but the design should support: + +- one recipe per module at a time +- multiple modules running independently +- commander-controlled production priorities + +That is enough to express useful industrial behavior without needing a fully complex factory UI yet. + +## Commander Interaction + +Production should feed directly into station commander behavior. + +Station commanders should observe: + +- current recipe needs +- input shortages +- output surpluses +- workforce limitations +- power limitations + +Based on that, they should: + +- create buy orders +- create sell orders +- reprioritize station activity +- request logistics support + +## Profit And Production + +Production is not only about self-sufficiency. + +Stations should produce when it is useful because: + +- they need the output internally +- the output can be sold profitably +- the output supports faction strategy + +This lets industrial behavior emerge from a mix of necessity and opportunity. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- production consumes real inputs +- production takes time +- modules determine what recipes can run +- workforce affects production throughput +- lack of power stops normal production +- lack of inputs halts recipe completion +- storage limits can bottleneck output +- construction is a specialized form of production + +## Relationship To Other Documents + +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) + - defines what goods flow through recipes + +- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md) + - defines which modules can execute production + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - defines how production shortages and surpluses affect the market + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - defines station roles that host production + +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) + - defines workforce scaling and survival constraints diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..76852df --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,461 @@ +# Roadmap + +This document maps the current codebase to the target design in the official docs and defines the recommended migration order. + +It is not a feature wishlist. It is a gap analysis plus an incremental refactor plan. + +## Current Architecture + +The current codebase already has a functioning simulation loop, backend API, and viewer. It also has useful authored data for ships, items, modules, constructibles, and module build recipes. + +The current implementation is still centered on a flatter world model: + +- systems +- resource nodes +- stations +- ships +- factions + +The current simulation behavior is driven mostly by: + +- ship `Order` +- ship `DefaultBehavior` +- ship `ControllerTask` +- string-based ship `State` +- direct position and target-position movement + +This gives the project a working prototype, but it does not yet reflect the design in: + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) +- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) +- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) +- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) + +## Existing Strengths + +These parts are worth preserving and extending rather than replacing outright: + +- Data-driven definitions already exist in [`shared/data/items.json`](/home/jbourdon/repos/space-game/shared/data/items.json), [`shared/data/modules.json`](/home/jbourdon/repos/space-game/shared/data/modules.json), [`shared/data/module-recipes.json`](/home/jbourdon/repos/space-game/shared/data/module-recipes.json), and [`shared/data/ships.json`](/home/jbourdon/repos/space-game/shared/data/ships.json). +- The loader already supports authored station placement hints in [`shared/data/scenario.json`](/home/jbourdon/repos/space-game/shared/data/scenario.json) via `planetIndex` and `lagrangeSide`. +- The backend already has snapshot and delta transport in [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) and [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs). +- The simulation loop in [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) already has useful concepts like docking, extraction, construction, warp spooling, and FTL spooling. +- The viewer stack already consumes a live world snapshot and delta stream through [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts), [`api.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/api.ts), and [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts). + +## Gap Analysis + +### Spatial Model + +Target design: + +- `universe-space` +- `galaxy-space` +- `system-space` +- `local-space` +- node-attached local bubbles +- one structure per Lagrange point +- warp between nodes +- local gameplay inside bubbles + +Current state: + +- systems are first-class +- planets exist only as system snapshot data +- resource nodes exist, but only as extractable asteroid/gas sites +- stations are positioned directly in system coordinates +- ships move by `Position` and `TargetPosition` +- no first-class system node graph +- no first-class local bubbles +- no claim entities +- no construction-site entities + +Primary gaps: + +- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no `NodeRuntime`, `LocalBubbleRuntime`, `ClaimRuntime`, or `ConstructionSiteRuntime`. +- [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) computes station positions directly instead of creating node-backed placement. +- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) still treats travel as raw coordinate movement rather than node-to-node transit between spaces. + +### Command and Control + +Target design: + +- commanders are first-class simulation entities +- factions, stations, and ships act through commanders +- orders, behaviors, tasks, and state are distinct layers + +Current state: + +- no commander entity exists +- command logic is embedded in ship runtime fields +- station autonomy is implicit, not represented by a station commander +- faction doctrine and policy are not first-class + +Primary gaps: + +- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has `ShipOrderRuntime`, `DefaultBehaviorRuntime`, and `ControllerTaskRuntime`, but no commander model. +- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) plans and executes directly on ships in a centralized loop. +- [`TASKS.md`](/home/jbourdon/repos/space-game/docs/TASKS.md) is ahead of the current code; the code still uses stringly typed control layers. + +### Economy and Market + +Target design: + +- market-driven simulation +- station buy and sell orders +- open visibility with policy-based access +- profit-driven ship trade +- construction storage as market demand + +Current state: + +- stations have inventory +- ships can transfer and mine +- factions have credits +- there are no explicit market orders +- there is no order reservation, fulfillment, pricing, or policy gating + +Primary gaps: + +- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no `MarketOrderRuntime`, `ConstructionStorageRuntime`, or policy objects. +- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) has logistics behavior, but not a real market loop. +- [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) exposes inventory, but not orders, prices, or access policies. + +### Workforce and Population + +Target design: + +- station-local population +- faction-wide aggregate population +- habitat-driven growth +- workforce efficiency scaling +- commanders generated from population over time +- worker transport as a real logistics concern + +Current state: + +- no population model +- no workforce efficiency +- no habitat-backed growth +- no worker transport +- no commander generation from population + +Primary gaps: + +- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no workforce or population state on factions or stations. +- [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) has item, recipe, and constructible definitions, but no population or habitat-specific runtime schema yet. +- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) cannot model production efficiency, starvation, or worker movement. + +### Policies and Access + +Target design: + +- policy-driven trade access +- docking access +- construction access +- system or region restrictions on ship behavior + +Current state: + +- behavior restriction is implicit inside ship behavior kinds +- there is no reusable policy object +- no faction/station policy layering + +Primary gaps: + +- no `PolicySet` entity in [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) +- no policy fields in faction, station, ship, market, or construction runtime state +- no policy payloads in [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) + +### Events and Replication + +Target design: + +- typed events +- scope-aware visibility +- streaming by relevance across space layers +- interest management for clients and eventually services + +Current state: + +- a single world-wide snapshot and delta stream +- a minimal event record with string fields +- all subscribers receive the same deltas + +Primary gaps: + +- [`SimulationEventRecord`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs#L20) is too small for the event model in [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md). +- [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) broadcasts a single `WorldDelta` to all observers. +- there is no notion of observer scope, visible systems, visible bubbles, or higher-space filtered streaming. + +### Viewer + +Target design: + +- zoomable universe/galaxy view +- system view centered on nodes and transit +- local view centered on one bubble +- clear transitions between movement regimes and spaces + +Current state: + +- viewer consumes a flat snapshot of systems, resource nodes, stations, ships, and factions +- systems are strategic and visual, but not tied to explicit multi-space simulation layers +- no contracts for bubbles, claims, construction sites, market orders, commanders, or policies + +Primary gaps: + +- [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) mirrors the old backend model. +- [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) cannot render node graph, local bubbles, claims, or construction states because that data does not exist yet. + +## Subsystem Assessment + +### Keep and Extend + +- [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) +- [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) +- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) +- [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) +- [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) +- [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) + +These should evolve in place. + +### Replace Gradually + +- string-based ship state with explicit enums and structured movement state +- ship-only planning fields with commander/task-layer entities +- direct station placement with node, claim, and construction-site placement +- flat event records with typed event payloads + +### Avoid + +- avoid a big-bang rewrite of [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) +- avoid rewriting the viewer before contracts and runtime state exist +- avoid introducing commander logic only in the viewer or only in docs + +## Recommended Sequencing + +### Phase 1: Align the Runtime Vocabulary + +Goal: + +- make the backend world model match the minimum entity vocabulary in [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) + +Work: + +- extend [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) with: + - `NodeRuntime` + - `LocalBubbleRuntime` + - `CommanderRuntime` + - `ClaimRuntime` + - `ConstructionSiteRuntime` + - `MarketOrderRuntime` + - `PolicySetRuntime` +- add explicit enums or enum-like constants for: + - space layers + - movement regimes + - task kinds + - order kinds + - commander kinds +- add structured ship spatial state: + - current space layer + - current node + - current bubble + - current transit + +Why first: + +- every later change depends on this vocabulary existing in runtime state + +### Phase 2: Refactor Scenario and World Building Around Nodes + +Goal: + +- make systems produce a real node graph with local bubbles and Lagrange-backed construction points + +Work: + +- extend [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) with authored node and claim-related definitions only where necessary +- update [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) to: + - generate system-space nodes for stars, planets, moons, stations, and Lagrange points + - attach local bubbles to nodes + - translate existing `planetIndex` and `lagrangeSide` station hints into actual node IDs + - stop treating station placement as an arbitrary coordinate +- preserve current authored content while migrating scenario interpretation + +Why second: + +- movement, claims, construction, and viewer transitions all depend on real nodes + +### Phase 3: Introduce Founding, Claims, and Construction Sites + +Goal: + +- move station creation from “spawned finished station” toward the designed claim and construction flow + +Work: + +- add claim lifecycle state: + - planted + - activating + - active + - destroyed +- add construction-site runtime state with: + - target node + - blueprint or constructible reference + - construction storage inventory + - construction buy orders +- update [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) to support: + - claim activation + - claim destruction + - construction delivery + - builder progress + +Why here: + +- it lets the code start reflecting the station and Lagrange rules without requiring the full economy rewrite first + +### Phase 4: Replace Raw Travel With Space-Aware Movement + +Goal: + +- make ship movement follow the spatial design rather than raw target positions + +Work: + +- replace direct long-range movement with: + - local thruster movement inside a bubble + - in-system warp between nodes + - inter-system transit through gates or FTL +- update ship runtime in [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) +- split movement logic in [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) into clearer controllers or subsystems +- keep existing warp and FTL timings where useful, but move them under explicit movement regimes + +Why here: + +- this is the point where [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) starts becoming real in the simulation + +### Phase 5: Introduce Commanders and Task Layers + +Goal: + +- replace the current ship-only control stack with the design in [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) and [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) + +Work: + +- add `CommanderRuntime` and commander assignment to ships and stations +- split: + - goals + - orders + - behaviors + - tasks + - control state +- migrate existing `ShipOrderRuntime`, `DefaultBehaviorRuntime`, and `ControllerTaskRuntime` incrementally rather than deleting them in one step +- add faction and station policy references into planning + +Why here: + +- commanders need the spatial model first; market and production loops also need someone to make decisions + +### Phase 6: Build the Market and Workforce Loop + +Goal: + +- implement the first real economic loop that matches [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md), [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md), [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md), and [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) + +Work: + +- add market orders to stations and construction storage +- add price evaluation and ship profit selection +- add station population and workforce efficiency +- add habitat growth and worker consumption +- add transport rules for workers requiring habitat capacity on ships +- wire production throughput to workforce percentage and power availability + +Why here: + +- once commanders and nodes exist, this becomes a coherent system instead of isolated resource transfers + +### Phase 7: Upgrade Events and Streaming + +Goal: + +- make the event and replication layer match [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) + +Work: + +- replace the current minimal event shape in [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) with typed event families or a typed envelope +- add event scope metadata: + - universe + - galaxy + - system + - local bubble +- refactor [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) so subscriptions are observer-scoped rather than globally broadcast +- support higher-space streaming with filtering into lower-space views + +Why here: + +- this is the first phase that directly benefits multiplayer-style interest management and scalable service boundaries + +### Phase 8: Rebuild Viewer Contracts and Presentation + +Goal: + +- update the viewer to the new simulation truth + +Work: + +- extend [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) for: + - nodes + - local bubbles + - claims + - construction sites + - market orders + - policies where relevant + - richer ship movement state +- update [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) to support: + - galaxy/system/local scale transitions + - node-centric system view + - local bubble detail + - regime-aware ship rendering + +Why last: + +- the viewer should follow the backend contract, not invent the model ahead of it + +## Suggested First Refactor Seams + +If implementation starts immediately, the first files to change should be: + +1. [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) +2. [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) +3. [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) +4. [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) +5. [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) +6. [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) +7. [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) +8. [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) + +That order keeps the simulation model ahead of the API, and the API ahead of the viewer. + +## Practical Guidance + +- Keep the current prototype alive while refactoring. +- Prefer additive migration over destructive replacement until each layer is proven. +- Do not start with the viewer. +- Do not start with combat polish. +- Start with the backend data model and scenario loading, because the current architecture is still defined there. + +## Exit Criteria for “Docs to Code” Transition + +The design set is ready to drive implementation once these minimum conditions are met: + +- runtime state has first-class nodes, bubbles, commanders, claims, and market orders +- ships no longer rely on raw free-flight for all in-system travel +- station founding can exist as claim plus construction rather than only finished stations +- market and workforce state exist in contracts, not only internal runtime +- event streaming can be scoped by relevance instead of one global feed + +When those are true, the codebase will match the design direction closely enough that tuning and gameplay iteration become meaningful rather than structural. diff --git a/docs/SHIPS.md b/docs/SHIPS.md new file mode 100644 index 0000000..3120b4b --- /dev/null +++ b/docs/SHIPS.md @@ -0,0 +1,93 @@ +# Ships + +This document defines the intended role of ships in the simulation. + +Ships are mobile actors that operate across the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) under the authority of commanders defined in [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md). + +## Core Principles + +- every active ship should have a commander +- ships operate in explicit movement regimes +- ships execute logistics, combat, construction, scouting, and transport roles +- ship capability depends on hull, modules, and commander intent + +## Ship Roles + +Common roles include: + +- mining +- hauling +- construction +- escort +- patrol +- combat +- scouting +- passenger or utility support later + +From a simulation point of view, the important distinction is not only hull category but also commander role: + +- self-directed industrial ship +- station-assigned ship +- fleet-assigned ship +- faction-directed strategic ship + +## Movement + +Ships should move according to the layered spatial model: + +- thrusters in `local-space` +- warp in `system-space` +- stargate or FTL for inter-system travel + +Ships should not behave as if an entire system is one continuous local dogfighting field. + +## Command Requirements + +A ship without a commander should be severely limited. + +At minimum, it should not perform meaningful autonomous loops such as: + +- mining cycles +- trade runs +- route planning +- combat patrols +- logistics procurement + +Ship commanders should be able to receive work from: + +- player direct orders +- a superior commander +- economic opportunities exposed by the market + +Some ships should also specialize in worker transport, provided they carry the required human habitat module defined in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). + +Ship work selection should also obey policy restrictions such as allowed trade partners, regional limits, and station-serving constraints. See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md). + +## Capabilities + +Ship capability should depend on: + +- hull class +- fitted modules +- cargo and storage compatibility +- propulsion capability +- docking compatibility +- optional warp and FTL capability + +Cargo and movement capability should materially affect which market opportunities a ship can accept. + +This should eventually include item-class compatibility as described in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md). + +Those capabilities should primarily come from fitted modules as described in [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md). + +## Relationship To Other Documents + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) + +- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md) +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) diff --git a/docs/SPACES.md b/docs/SPACES.md new file mode 100644 index 0000000..010671b --- /dev/null +++ b/docs/SPACES.md @@ -0,0 +1,518 @@ +# Spaces + +This document defines the intended spatial model for the project. + +It is a gameplay and simulation document first. The viewer should expose these layers clearly, but it does not define them. + +The core idea is that the world is not one continuous field of arbitrary movement. Instead, gameplay happens across nested spatial layers with different rules, scales, and valid actions. + +See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the entity vocabulary that should represent these layers. + +## Design Goals + +The spatial model should support: + +- EVE-like travel pacing and readability +- explicit transitions between tactical space and transit space +- local combat and interaction bubbles +- scalable simulation partitioning +- scalable replication and interest management +- future server-side sharding by local bubble if necessary + +The intended feel is: + +- local maneuvering is slow, deliberate, and readable +- in-system travel is warp-based, not long free-flight +- inter-system travel is explicit and infrastructural +- zooming the viewer reveals different valid abstractions of the same world + +## Space Layers + +The simulation is divided into four major space layers: + +1. `universe-space` +2. `galaxy-space` +3. `system-space` +4. `local-space` + +These are simulation layers, not just camera levels. + +### `universe-space` + +The broadest simulation layer. + +This is where universe-wide state and events live, such as: + +- global time +- global factions and diplomacy +- universe-scale event scheduling +- future crises, anomalies, migrations, or story events + +`universe-space` is not primarily about positional navigation. It is the top-most simulation context. + +### `galaxy-space` + +The layer where star systems exist as spatially arranged world entities. + +This is where the game models: + +- system positions +- large-scale routes and proximity +- inter-system connectivity +- strategic movement between systems + +Ships do not dogfight in `galaxy-space`. It is the strategic layer connecting systems. + +### `system-space` + +The layer inside a single star system where travel occurs between meaningful locations. + +This is where the game models: + +- stars +- planets +- moons +- stations +- structures +- gates +- resource locations, if they should be direct destinations +- Lagrange points +- travel relationships between these locations + +`system-space` is the travel layer between local bubbles. Gameplay-wise, this can also be referred to as warp-space for ship movement inside a system. + +### `local-space` + +The tactical simulation bubble attached to a specific node. + +This is where close interaction happens: + +- thruster flight +- combat +- docking +- undocking +- mining +- construction +- rendezvous +- local hazards + +Each `local-space` is an isolated simulation bubble attached to one node. Ships leave one local bubble, exist in `system-space` during warp transit, then enter another local bubble on arrival. + +Local bubbles are also the intended future unit of simulation partitioning. A later runtime may move one or more bubbles to dedicated servers without changing the gameplay model. + +## Nodes + +A node is a meaningful location in `system-space` that owns a `local-space` bubble. + +Examples of nodes: + +- star +- planet +- moon +- station +- structure +- gate +- major resource location if desired +- each Lagrange point associated with a massive orbital + +Each node should have: + +- a stable identifier +- a parent system +- a type +- a position in `system-space` +- a local bubble radius +- optional parent/child relationships +- optional orbital metadata + +Examples: + +- a planet node orbits a star node +- a moon node orbits a planet node +- a station or structure node is built at a Lagrange point + +## Lagrange Points + +Each massive orbital should expose five Lagrange points: + +- `L1` +- `L2` +- `L3` +- `L4` +- `L5` + +These are valid nodes in `system-space`, each with its own `local-space`. + +They should be computed from orbital relationships rather than authored by hand in most cases. + +Construction rule: + +- each Lagrange point can host exactly one structure + +This scarcity is intentional. Lagrange points should be valuable strategic locations rather than interchangeable empty coordinates. + +Recommended applicability: + +- major orbitals should expose all five Lagrange points +- this should apply at least to sufficiently massive planets +- moons may expose none or fewer, depending on the final simulation rule + +Lagrange points should not always be immediately buildable by default. + +Recommended structure founding flow: + +1. claim the Lagrange point +2. protect the claim until it matures +3. activate the claim +4. begin station construction + +Lagrange points are useful for: + +- staging areas +- logistics hubs +- military control points +- hidden or contested infrastructure +- future economy and navigation design +- station and structure placement + +## Structures At Lagrange Points + +Stations and other built structures should always be placed at Lagrange points. + +This should be treated as a world rule, not merely a common pattern. + +Implications: + +- player and AI construction targets for major structures are Lagrange nodes +- stations do not occupy arbitrary free positions in system-space +- structure placement is tied to orbital geometry +- economically and militarily valuable station locations are legible from the system map +- each Lagrange point supports only one built structure +- to create another station, a faction must secure another valid location + +This makes system geography more understandable and gives Lagrange points durable strategic meaning. + +## Claiming Lagrange Points + +Station construction should begin with an explicit claim on a Lagrange point. + +The claim should behave like a vulnerable placed object. + +Properties: + +- it marks intent to occupy the Lagrange point +- it can be attacked or destroyed by enemies or pirates +- it requires an activation period before full construction can begin + +Recommended founding sequence: + +1. a faction places a claim object at the target Lagrange point +2. the claim survives for its activation time +3. the claim becomes active +4. station construction storage appears +5. the desired station design creates demand for required construction materials +6. constructor ships consume those materials to build the station + +This makes Lagrange occupation contestable and visible. + +## Local Bubbles + +Each node owns exactly one local bubble. + +A local bubble defines: + +- the local simulation frame +- the tactical interaction radius +- the list of occupants +- the set of legal actions inside that space +- the future server authority boundary + +Local bubbles should be treated as separate simulation contexts, not merely camera zoom-ins. + +Rules: + +- a ship in `local-space` belongs to exactly one bubble +- actions such as combat, docking, mining, and construction happen only inside a local bubble +- leaving a bubble is an explicit transition into `system-space` +- entering a destination bubble is an explicit arrival transition from `system-space` + +See [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) for the combat consequences of this rule. + +## Movement Regimes + +Ships do not move with one universal locomotion model. Their movement depends on their current space layer and travel regime. + +Primary regimes: + +- `local-flight` +- `warp` +- `stargate-transit` +- `ftl-transit` + +### `local-flight` + +Used inside `local-space`. + +Characteristics: + +- uses normal thrusters +- supports fine positioning +- supports docking and undocking +- supports combat +- supports mining and close interaction + +This regime should feel heavy, readable, and tactical. + +### `warp` + +Used in `system-space` to travel between nodes in the same system. + +Characteristics: + +- exits one local bubble +- enters spool-up +- travels through `system-space` +- drops out at a destination node +- enters the destination local bubble + +The intended feel is close to EVE, but with spool-up emphasis rather than strict align mechanics. + +Recommended warp phases: + +1. `warp-spooling` +2. `in-warp` +3. `warp-dropout` + +During warp, ships should not be treated as locally maneuvering units. + +### `stargate-transit` + +Used to travel between systems through infrastructure. + +Characteristics: + +- starts from a gate node in local-space +- transitions through a gate sequence +- arrives at a gate node in another system + +This should be a discrete inter-system travel mode, not merely a very long warp. + +### `ftl-transit` + +Used by ships that have their own FTL capability. + +Characteristics: + +- explicit inter-system travel regime +- likely stronger costs, constraints, or cooldowns than gates +- may bypass some infrastructure requirements + +This remains distinct from in-system warp. + +## Valid Actions By Space + +### In `universe-space` + +Examples: + +- resolve universe-scale events +- evaluate global strategic conditions +- future narrative or crisis systems + +### In `galaxy-space` + +Examples: + +- reason about systems +- evaluate strategic routes +- choose inter-system destinations + +### In `system-space` + +Examples: + +- choose destination nodes +- execute warp travel +- evaluate node-to-node movement + +### In `local-space` + +Examples: + +- maneuver with thrusters +- dock +- undock +- mine +- fight +- build +- transfer cargo locally + +Rule of thumb: + +- tactical interaction belongs to `local-space` +- transit belongs to `system-space` +- strategic topology belongs to `galaxy-space` + +## Ship Spatial State + +Ships should eventually be modeled with explicit spatial state, not just one position plus one target position. + +At minimum, a ship should know: + +- current `systemId` +- current `spaceLayer` +- current `nodeId`, if in local-space +- current `localPosition`, if in local-space +- current transit data, if in warp or inter-system travel + +Recommended movement/runtime states include: + +- `idle` +- `local-flight` +- `warp-spooling` +- `in-warp` +- `warp-dropout` +- `docking` +- `docked` +- `undocking` +- `using-stargate` +- `ftl-spooling` +- `in-ftl` +- `arriving-from-ftl` + +This spatial model works together with the command and economy documents: + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - defines who decides and delegates + +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) + - defines how stations and factions participate economically + +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) + - defines ship-side capability and behavior + +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) + - defines station-side role and responsibility + +## Orders And Destinations + +Orders should target valid destinations in the spatial model. + +In practice, that means ships should target nodes and bubbles rather than arbitrary points across an entire system. + +Examples: + +- travel to node +- warp to node +- dock at structure in node +- mine in node +- use gate to system +- jump to system + +This makes planning clearer and keeps traversal tied to the intended world structure. + +## Viewer Expectations + +The viewer should reveal these layers as the player zooms or changes context. + +Desired viewer scales: + +1. `universe/galaxy view` +2. `system view` +3. `local view` + +### `universe/galaxy view` + +Shows: + +- systems +- strategic relationships +- large-scale motion and events + +### `system view` + +Shows: + +- nodes inside one system +- warp destinations +- route structure +- high-level in-system movement + +This view should not pretend that all tactical detail is always present. + +### `local view` + +Shows: + +- one node bubble in detail +- ships maneuvering with thrusters +- combat, docking, mining, and construction + +Viewer zoom should expose valid abstractions of simulation truth rather than inventing unrelated presentation layers. + +## Interest Management + +This spatial model naturally supports interest management for streaming. + +The general rule should be: + +- always stream context from higher spaces +- filter detailed context from lower spaces based on interest + +Examples: + +- a client viewing a local bubble still needs relevant system, galaxy, and universe context +- a client viewing a system does not need full-fidelity tactical events from every local bubble +- a client viewing the galaxy does not need continuous local combat state for every bubble + +Suggested replication principle: + +- high-layer events are broad but low-detail +- low-layer events are narrow but high-detail + +Example filtering: + +- `universe-space` events can be broadcast widely +- `galaxy-space` events can be scoped by region or strategic relevance +- `system-space` events can be scoped by current or observed system +- `local-space` events can be scoped by the specific bubble being observed or occupied + +This should make future multiplayer scaling easier than a flat world-wide stream. + +## Recommended Backend Direction + +The backend should move toward: + +- explicit node definitions +- explicit local bubble definitions +- explicit ship travel regimes +- explicit transitions between local, system, and inter-system movement + +Recommended progression: + +1. define nodes and local bubbles in world/runtime contracts +2. compute and include Lagrange points for major orbitals +3. refactor ship movement around regimes instead of free system-local travel +4. restrict tactical actions to local-space +5. expose regime and bubble membership in replication contracts +6. redesign viewer zoom and replication around these layers + +## Invariants + +These rules should remain true unless there is a very deliberate design reason to break them: + +- every local bubble belongs to exactly one node +- every ship is in exactly one major movement regime at a time +- ships in different local bubbles are not co-located, even if they are in the same system +- movement inside local-space uses thrusters +- movement between nodes inside a system uses warp +- movement between systems uses stargates or ship FTL +- combat, docking, mining, and construction happen only in local-space +- viewer abstractions should map back to real simulation layers +- every structure occupies exactly one Lagrange point +- every Lagrange point supports at most one structure +- a station site must be claimed before full construction begins + +## Open Follow-Up Documents + +This document is part of the official design set listed in [DESIGN.md](/home/jbourdon/repos/space-game/docs/DESIGN.md). diff --git a/docs/STATIONS.md b/docs/STATIONS.md new file mode 100644 index 0000000..4bedebd --- /dev/null +++ b/docs/STATIONS.md @@ -0,0 +1,213 @@ +# Stations + +This document defines the intended role of stations in the simulation. + +Stations are persistent nodes in the world that own local bubbles, provide services, participate in the economy, and act through station commanders. + +## Core Principles + +- every active station should have a commander +- stations are major market actors +- stations exist at meaningful nodes in space +- stations provide local services and strategic value + +## Station Identity + +A station lives at one location. + +It does not spread across multiple construction points. + +Station growth happens by adding modules to the existing station at its current Lagrange point. + +To create another station, a faction needs: + +- another valid location +- another station +- another station commander + +Before station construction itself, the faction should also secure the site through the Lagrange-point claim process defined in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md). + +Station identity and capability should primarily come from module composition, as described in [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md). + +## Station Roles + +Stations may serve as: + +- markets +- refineries +- production centers +- logistics hubs +- shipyards +- military outposts +- defensive strongholds +- staging points + +## Spatial Role + +Stations are nodes in `system-space` with their own `local-space`. + +Stations and other built structures should always be located at Lagrange points. + +Each Lagrange point can hold only one structure. + +Their local bubbles are where: + +- docking happens +- cargo transfer happens +- defense happens +- local construction happens +- player and AI interaction happens + +Local-space defense and contestation are described further in [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md). + +## Founding A Station + +The intended founding flow is: + +1. claim a valid Lagrange point +2. wait for the claim to activate +3. create station construction storage +4. publish buy orders for the required construction materials +5. deliver materials +6. have constructor ships build the station from those materials + +The construction storage should act as the early economic interface of the future station. + +That means a station can begin expressing demand before the full station is operational. + +Those construction requirements should be expressed through real goods as described in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md). + +## Commander Requirements + +A station without a commander should be limited. + +Without a commander, a station should not be expected to: + +- manage buy orders +- manage sell orders +- adapt production priorities +- coordinate logistics +- respond intelligently to shortages or dock congestion + +Important boundary: + +- a station commander is responsible for station operation +- a station commander does not own ships + +Ships may still serve a station through assignment, doctrine, or market incentives, but that is not the same thing as station ownership. + +Station founding does not require a station commander at the first moment of construction. + +However, a fully operating station should require one to function normally. + +The commander must be brought to the station rather than appearing automatically. + +This implies stations will eventually depend on population and worker logistics. + +Workers should be treated as a real station resource, not as a free abstraction. + +See [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) for the workforce model. + +## Market Role + +Stations are the main local market-makers of the simulation. + +A station commander should: + +- publish buy orders +- publish sell orders +- manage stock reserves +- control production priorities +- request imports and exports + +Stations should be the primary place where the economy becomes concrete and visible to the player. + +That means stations should expose: + +- current shortages +- current surpluses +- active buy orders +- active sell orders +- dock activity +- production intent + +Market visibility should be treated as open knowledge, subject to access and information rules defined elsewhere. + +The baseline assumption is that station market intent is visible, not hidden by default. + +Actual participation in trade and docking should still be policy-controlled. See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md). + +## Ownership And Presence + +Station ownership is not local-bubble exclusive. + +The important hard rule is: + +- one structure per Lagrange point + +Not: + +- one faction per local bubble + +This means friendly or otherwise permitted factions may build stations within the same system, so long as they use different valid locations. + +## Failure State + +Without fuel there is no power. + +Without power, station function collapses. + +A powerless station should not continue normal market or industrial behavior. + +At that point, recovery should require outside intervention such as emergency restoration, delivered fuel, or a dedicated support operation. + +This also means: + +- no loading +- no unloading +- no ordinary trade handling +- no ordinary production + +## Services + +Depending on modules and category, a station may provide: + +- docking +- storage +- refining +- fuel processing +- manufacturing +- repair later +- fitting later +- rearm and resupply later +- habitats + +The exact conversion and factory behavior behind these services is described in [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md). + +## Workforce + +Stations track their own local population. + +That population determines workforce availability and therefore station efficiency. + +For now: + +- every module benefits equally from workforce +- each module has a workforce target for peak efficiency +- stations retain a small baseline efficiency even with zero workers + +Population growth and decline follow the rules in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). + +## Relationship To Other Documents + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) +- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) + +- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md) +- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) +- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) diff --git a/docs/TASKS.md b/docs/TASKS.md new file mode 100644 index 0000000..2dc689a --- /dev/null +++ b/docs/TASKS.md @@ -0,0 +1,321 @@ +# Tasks + +This document defines the intended order, task, and runtime execution model for the simulation. + +It describes how commander intent becomes executable work. + +## Design Goals + +The task model should support: + +- direct player control +- long-lived commander autonomy +- clear precedence rules +- readable runtime state +- consistent execution across movement, logistics, construction, and combat + +## Core Principles + +- commanders decide intent +- tasks express executable work +- states describe runtime condition +- orders can temporarily override autonomy +- tasks should be concrete enough for direct simulation execution + +## Control Layers + +The intended execution stack should be: + +1. `goal` +2. `order` +3. `behavior` +4. `task` +5. `state` + +This separates long-horizon intent from short-horizon execution. + +## Goals + +Goals are high-level commander intentions. + +Examples: + +- expand into this system +- keep this station fueled +- defend this claim +- protect trade in this region +- supply this station with workers + +Goals belong primarily to commanders, not directly to ships. + +## Orders + +Orders are explicit instructions produced by the player or by higher command. + +Orders should survive replanning better than tasks. + +Examples: + +- travel to node +- dock at station +- claim Lagrange point +- build station here +- deliver fuel +- escort this ship +- defend this bubble + +Orders are the main override layer above routine autonomous behavior. + +## Behaviors + +Behaviors are persistent patterns followed when no overriding direct order exists. + +Examples: + +- idle +- auto-trade +- mine-for-station +- region trader +- claim defender +- station supplier +- local defender +- patrol route + +Behaviors should continuously refresh tasks as conditions change. + +## Tasks + +Tasks are the immediate executable actions the runtime can carry out. + +Tasks should be concrete and short-horizon. + +Examples: + +- move locally +- warp to node +- request dock +- dock +- undock +- load cargo +- unload cargo +- transfer workers +- attack target +- hold near target +- build at construction site +- claim node +- retreat + +## States + +States describe what an entity is physically or operationally doing right now. + +Examples: + +- idle +- local-flight +- warp-spooling +- in-warp +- docking +- docked +- loading +- unloading +- attacking +- retreating +- building +- disabled + +States should be readable runtime facts, not overloaded planning abstractions. + +## Precedence Rules + +Task selection should follow this priority: + +1. direct player order +2. higher-commander order +3. local commander behavior +4. safety fallback + +Interpretation: + +- explicit orders override routine autonomy +- routine autonomy resumes when those orders end +- safety logic may still interrupt if survival requires it + +## Planner Flow + +The intended execution loop is: + +1. commander evaluates world state +2. commander updates goals or behavior +3. planner resolves the highest-priority active instruction +4. planner chooses or updates the current task +5. runtime executes the task +6. state changes and events feed back into planning + +This is the bridge between command and simulation. + +## Order Lifecycle + +Orders should have an explicit lifecycle. + +Recommended order states: + +- `queued` +- `accepted` +- `planning` +- `executing` +- `completed` +- `failed` +- `cancelled` +- `blocked` + +## Task Lifecycle + +Tasks should have a simpler lifecycle. + +Recommended task states: + +- `pending` +- `active` +- `blocked` +- `completed` +- `failed` +- `cancelled` + +Tasks are shorter-lived than orders and easier to replace. + +## Common Ship Task Kinds + +Recommended core ship task kinds: + +- `idle` +- `local-move` +- `warp-to-node` +- `use-stargate` +- `use-ftl` +- `dock` +- `undock` +- `load-cargo` +- `unload-cargo` +- `load-workers` +- `unload-workers` +- `mine-node` +- `harvest-gas` +- `deliver-to-station` +- `claim-lagrange-point` +- `build-construction-site` +- `escort-target` +- `attack-target` +- `defend-bubble` +- `retreat` +- `hold-position` + +## Common Station Operational Tasks + +Stations are not ships, but station operation still implies task-like work. + +Examples: + +- publish market orders +- update production priority +- execute recipe cycle +- accept dock request +- deny dock request +- transfer goods +- request defense +- request emergency fuel support + +These may be implemented as station jobs, station operations, or station-side tasks. + +## Safety And Fallback Tasks + +Safety logic should interrupt ordinary behavior when required. + +Examples: + +- retreat from combat +- flee to nearest allowed station +- hold position if no valid route exists +- suspend trade when no legal destination exists +- wait for fuel, escort, or dock access + +This prevents autonomous loops from becoming self-destructive. + +## Space-Aware Tasking + +Tasks should respect the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md). + +That means: + +- local maneuvering is distinct from warp +- docking is local-space work +- cargo transfer is local-space work +- inter-system travel is distinct from in-system travel + +## Policy-Aware Tasking + +Tasks should respect policies from [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md). + +Examples: + +- do not dock where docking is forbidden +- do not trade where access is denied +- do not leave assigned region if behavior policy forbids it +- do not build where policy would trigger conflict unless ordered + +## Event Integration + +Task and order transitions should generate meaningful events. + +Examples: + +- `order-accepted` +- `order-cancelled` +- `task-started` +- `task-blocked` +- `task-completed` +- `task-failed` +- `behavior-changed` + +See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the event-side model. + +## Data-Model Implication + +The data model should make room for at least: + +- current goal references +- active order references +- active behavior +- active task +- current state + +See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the entity-side vocabulary. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- goals, orders, tasks, and states are not the same thing +- orders can override ordinary behavior +- tasks are the executable layer +- states are descriptive runtime condition +- safety logic may interrupt behavior +- tasking must respect space and policy rules +- meaningful task transitions should emit events + +## Relationship To Other Documents + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) + - defines who decides and delegates + +- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) + - defines where tasks can occur + +- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) + - defines restrictions tasking must obey + +- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) + - defines the entity fields that hold goals, orders, tasks, and states + +- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) + - defines the event families emitted by task and order transitions diff --git a/docs/WORKFORCE.md b/docs/WORKFORCE.md new file mode 100644 index 0000000..7bb3b5a --- /dev/null +++ b/docs/WORKFORCE.md @@ -0,0 +1,196 @@ +# Workforce + +This document defines population, workforce, habitats, and commander generation. + +Workforce is a station-side resource that connects economy, commanders, logistics, and station efficiency. + +See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the explicit station-side fields implied by this model. + +## Core Principles + +- population exists at stations, not only as an abstract total +- each station tracks its own population +- factions still have meaningful aggregate population totals +- habitats are the source of population growth +- workers consume life-support and civilian goods +- workforce determines station efficiency +- commanders are generated from faction population over time + +## Population Model + +Population should be tracked at two levels: + +- per-station population +- per-faction aggregate population + +The station level is the primary simulation truth because population lives, grows, and dies at stations. + +The faction level is the strategic aggregate used for: + +- faction scale +- workforce planning +- commander availability +- demographic growth + +## Habitats + +Population growth should happen only at stations for now. + +Habitat modules are required for population growth. + +Habitats allow stations to: + +- house workers +- grow population +- sustain future commander generation + +Ships do not generate population. + +## Worker Needs + +Workers consume, per worker: + +- food +- water +- energy +- consumer goods + +These should be understood using the item roles defined in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md). + +If these needs are not met, workers should die over time. + +This should be a gradual attrition model rather than an instant binary failure. + +## Workforce Efficiency + +A workforce is required for peak station performance. + +Each module should have a workforce requirement for `100%` efficiency. + +For now: + +- workforce scales all modules equally +- there is no special per-module workforce rule + +A station can still operate without workers, but only at a baseline level. + +Current intended baseline: + +- `10%` efficiency at `0%` workforce + +This means: + +- `0%` workforce satisfaction gives baseline operation +- `100%` workforce satisfaction gives peak operation +- intermediate staffing gives proportional efficiency + +## Population Transport + +Population can be moved between stations. + +This supports strategies such as: + +- growing population at a major habitat station +- feeding workers to industrial stations +- staffing newly founded frontier stations +- rebuilding stations after demographic collapse + +Population remains a station-side resource, even while being transported. + +## Human Transport Requirement + +Ships need a habitat module to transport humans. + +This keeps population transport distinct from ordinary cargo hauling. + +Related note: + +- livestock modules also exist as part of the food loop + +## Commanders And Population + +Commanders are created from a faction's worker base. + +The intent is: + +- more faction population yields more available commanders over time +- commanders are rare relative to workers + +An approximate working rule is acceptable for now. + +Example rule: + +- for each `1000` faction population, one commander is generated every `1 hour` + +The exact formula can change later. The important rule is that commanders are population-backed rather than free. + +## Commander Consumption + +Commanders are consumed permanently when created and assigned. + +They are not temporarily borrowed and returned to a pool. + +If a commander dies: + +- that commander is gone + +This gives commanders real cost and strategic value. + +## Founding And Staffing + +A newly founded station may begin with: + +- zero workers +- construction storage +- no local commander yet + +It can still exist and operate at baseline efficiency, but it remains weak until supplied with: + +- fuel +- workers +- support goods +- eventually a station commander + +## Failure And Attrition + +If a station loses required support resources, population should die over time. + +Relevant shortages include: + +- food shortage +- water shortage +- energy shortage +- consumer goods shortage + +This gives logistics failure lasting demographic consequences. + +## Ownership And Identity + +Station population is the local operational truth. + +Faction population is the strategic aggregate. + +That distinction is enough for now. It does not require a more complicated ownership doctrine yet. + +## Minimum Rules + +The following rules should remain true unless deliberately revised: + +- population grows only at stations for now +- habitat modules are required for growth +- workers consume food, water, energy, and consumer goods +- workforce affects station efficiency +- stations retain a small baseline efficiency at zero workforce +- population can be transported between stations +- transporting humans requires a habitat-capable ship module +- commanders are generated from faction population over time +- commanders are permanently consumed when created +- dead commanders do not return to the pool + +## Relationship To Other Documents + +- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) +- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) +- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) +- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) +- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)