docs: establish official design documentation
This commit is contained in:
137
NEXT-STEPS.md
137
NEXT-STEPS.md
@@ -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
|
|
||||||
288
SESSION.md
288
SESSION.md
@@ -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`
|
|
||||||
543
STATES.md
543
STATES.md
@@ -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
|
|
||||||
229
docs/COMBAT.md
Normal file
229
docs/COMBAT.md
Normal file
@@ -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
|
||||||
365
docs/COMMANDERS.md
Normal file
365
docs/COMMANDERS.md
Normal file
@@ -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
|
||||||
501
docs/DATA-MODEL.md
Normal file
501
docs/DATA-MODEL.md
Normal file
@@ -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
|
||||||
108
docs/DESIGN.md
Normal file
108
docs/DESIGN.md
Normal file
@@ -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.
|
||||||
349
docs/ECONOMY.md
Normal file
349
docs/ECONOMY.md
Normal file
@@ -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
|
||||||
328
docs/EVENTS.md
Normal file
328
docs/EVENTS.md
Normal file
@@ -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
|
||||||
227
docs/ITEMS.md
Normal file
227
docs/ITEMS.md
Normal file
@@ -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
|
||||||
294
docs/MODULES.md
Normal file
294
docs/MODULES.md
Normal file
@@ -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
|
||||||
199
docs/POLICIES.md
Normal file
199
docs/POLICIES.md
Normal file
@@ -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
|
||||||
271
docs/PRODUCTION.md
Normal file
271
docs/PRODUCTION.md
Normal file
@@ -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
|
||||||
461
docs/ROADMAP.md
Normal file
461
docs/ROADMAP.md
Normal file
@@ -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.
|
||||||
93
docs/SHIPS.md
Normal file
93
docs/SHIPS.md
Normal file
@@ -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)
|
||||||
518
docs/SPACES.md
Normal file
518
docs/SPACES.md
Normal file
@@ -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).
|
||||||
213
docs/STATIONS.md
Normal file
213
docs/STATIONS.md
Normal file
@@ -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)
|
||||||
321
docs/TASKS.md
Normal file
321
docs/TASKS.md
Normal file
@@ -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
|
||||||
196
docs/WORKFORCE.md
Normal file
196
docs/WORKFORCE.md
Normal file
@@ -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)
|
||||||
Reference in New Issue
Block a user