462 lines
18 KiB
Markdown
462 lines
18 KiB
Markdown
# 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.
|