jbourdon/space-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
space-game/docs/ROADMAP.md

18 KiB
Raw Permalink Blame History

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:

Existing Strengths

These parts are worth preserving and extending rather than replacing outright:

Gap Analysis

Spatial Model

Target design:

  • universe-space
  • galaxy-space
  • system-space
  • localspace
  • anchor-owned localspaces
  • construction only at valid construction anchors
  • warp between anchors within one system
  • local gameplay inside localspaces

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 anchor graph
  • no first-class localspaces
  • no claim entities
  • no construction-site entities

Primary gaps:

  • RuntimeModels.cs has no first-class AnchorRuntime aligned with the target design, plus no fully anchor-native ClaimRuntime or ConstructionSiteRuntime.
  • ScenarioLoader.cs computes station positions directly instead of creating anchor-backed placement.
  • SimulationEngine.cs still treats travel as raw coordinate movement rather than anchor-to-anchor 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 has ShipOrderRuntime, DefaultBehaviorRuntime, and ControllerTaskRuntime, but no commander model.
  • SimulationEngine.cs plans and executes directly on ships in a centralized loop.
  • 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:

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 has no workforce or population state on factions or stations.
  • WorldDefinitions.cs has item, recipe, and constructible definitions, but no population or habitat-specific runtime schema yet.
  • 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:

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 is too small for the event model in EVENTS.md.
  • 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 localspaces, claims, construction sites, market orders, commanders, or policies

Primary gaps:

  • contracts.ts mirrors the old backend model.
  • GameViewer.ts cannot render an anchor graph, localspaces, claims, or construction states because that data does not exist yet.

Subsystem Assessment

Keep and Extend

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 anchor, claim, and construction-site placement
  • flat event records with typed event payloads

Avoid

  • avoid a big-bang rewrite of 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

Work:

  • extend RuntimeModels.cs with:
    • AnchorRuntime
    • 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 anchor
    • current transit

Why first:

  • every later change depends on this vocabulary existing in runtime state

Phase 2: Refactor Scenario and World Building Around Anchors

Goal:

  • make systems produce a real anchor graph with localspaces and supported construction anchors

Work:

  • extend WorldDefinitions.cs with authored anchor and claim-related definitions only where necessary
  • update ScenarioLoader.cs to:
    • generate system-space anchors for stars, planets, moons, Lagrange points, and resource nodes where appropriate
    • attach localspaces to anchors
    • translate existing planetIndex and lagrangeSide station hints into actual anchor 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 anchors

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 anchor
    • blueprint or constructible reference
    • construction storage inventory
    • construction buy orders
  • update SimulationEngine.cs to support:
    • claim activation
    • claim destruction
    • construction delivery
    • builder progress

Why here:

  • it lets the code start reflecting the construction-anchor 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 localspace
    • in-system warp between anchors
    • inter-system transit through gates or FTL
  • update ship runtime in RuntimeModels.cs
  • split movement logic in SimulationEngine.cs into clearer controllers or subsystems
  • keep existing warp and FTL timings where useful, but move them under explicit movement regimes

Why here:

Phase 5: Introduce Commanders and Task Layers

Goal:

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:

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 anchors 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

Work:

  • replace the current minimal event shape in WorldContracts.cs with typed event families or a typed envelope
  • add event scope metadata:
    • universe
    • galaxy
    • system
    • localspace
  • refactor 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 for:
    • anchors
    • localspaces
    • claims
    • construction sites
    • market orders
    • policies where relevant
    • richer ship movement state
  • update GameViewer.ts to support:
    • galaxy/system/local scale transitions
    • anchor-centric system view
    • localspace 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
  2. WorldDefinitions.cs
  3. ScenarioLoader.cs
  4. WorldContracts.cs
  5. SimulationEngine.cs
  6. WorldService.cs
  7. contracts.ts
  8. 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.

Reference in New Issue View Git Blame Copy Permalink