From fdcf83ccecf433fd336dac70b220a6e1fa2bc3b8 Mon Sep 17 00:00:00 2001 From: Jonathan Bourdon Date: Mon, 6 Apr 2026 21:29:49 -0400 Subject: [PATCH] Consolidate spatial docs into universe model --- docs/COMBAT.md | 18 +- docs/COMMANDERS.md | 6 +- docs/DATA-MODEL.md | 64 +++-- docs/DESIGN.md | 9 +- docs/ECONOMY.md | 8 +- docs/EVENTS.md | 11 +- docs/MODULES.md | 2 +- docs/POLICIES.md | 10 +- docs/PRODUCTION.md | 2 +- docs/ROADMAP.md | 72 +++--- docs/SHIPS.md | 8 +- docs/SPACES.md | 518 ----------------------------------------- docs/STATIONS.md | 32 ++- docs/TASKS.md | 14 +- docs/UNIVERSE-MODEL.md | 7 + 15 files changed, 129 insertions(+), 652 deletions(-) delete mode 100644 docs/SPACES.md diff --git a/docs/COMBAT.md b/docs/COMBAT.md index 5f1bc92..9ed1310 100644 --- a/docs/COMBAT.md +++ b/docs/COMBAT.md @@ -2,13 +2,13 @@ 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. +Combat is primarily a localspace 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 +- localspace tactical fights - piracy and harassment - claim destruction and station contestation - station defense @@ -17,7 +17,7 @@ The combat model should support: ## Core Principles -- combat happens in `local-space` +- combat happens in `localspace` - claims and structures are physically contestable - piracy should target valuable traffic and vulnerable infrastructure - stations should be defensible but not magically safe @@ -25,7 +25,7 @@ The combat model should support: ## Combat Space -Combat belongs in `local-space`. +Combat belongs in `localspace`. This is where entities can: @@ -35,7 +35,7 @@ This is where entities can: - defend stations and claims - intercept miners, haulers, and construction support -Ships in `system-space` warp transit are not in normal tactical combat. +Ships in intra-system warp transit are not in normal tactical combat. This keeps tactical fighting distinct from travel. @@ -54,7 +54,7 @@ Combat should matter not only for fleet battle, but also for logistics disruptio ## Claims As Combat Targets -Claims at Lagrange points should be valid combat targets. +Claims at valid construction anchors should be valid combat targets. That means: @@ -94,7 +94,7 @@ Station safety should depend on actual defensive capacity, not only ownership fl ## Piracy -Pirates should be a meaningful local-space threat. +Pirates should be a meaningful localspace threat. They should favor: @@ -203,7 +203,7 @@ See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the combat a The following rules should remain true unless deliberately revised: -- combat is primarily a local-space activity +- combat is primarily a localspace activity - claims are destructible and contestable - station construction is a vulnerable phase - piracy should prefer valuable and vulnerable traffic @@ -213,7 +213,7 @@ The following rules should remain true unless deliberately revised: ## Relationship To Other Documents -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) - defines where combat is allowed - [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) diff --git a/docs/COMMANDERS.md b/docs/COMMANDERS.md index 5e8e936..7de6d35 100644 --- a/docs/COMMANDERS.md +++ b/docs/COMMANDERS.md @@ -39,7 +39,7 @@ Additional specialized commanders may exist later, such as: - fleet commander - task-group commander - convoy commander -- sector commander +- localspace defense commander ## Commander Entity Model @@ -75,7 +75,7 @@ Responsibilities: - 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`. +The faction commander should reason mostly across `universe-space`, `galaxy-space`, and strategic system-level concerns. It should not micromanage every ship constantly. @@ -343,7 +343,7 @@ The following rules should remain true unless there is a deliberate exception: ## Relationship To Other Documents -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) - defines where action happens - [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) diff --git a/docs/DATA-MODEL.md b/docs/DATA-MODEL.md index 8e1119d..01dd99e 100644 --- a/docs/DATA-MODEL.md +++ b/docs/DATA-MODEL.md @@ -14,7 +14,7 @@ The data model should support: - module-based capability - population and workforce - claimable construction sites -- local-space combat +- localspace combat - scalable replication and future sharding ## Core Principles @@ -39,8 +39,8 @@ Recommended global ID families: - `factionId` - `commanderId` - `systemId` -- `nodeId` -- `bubbleId` +- `anchorId` +- `localspaceId` - `stationId` - `shipId` - `moduleId` @@ -58,8 +58,8 @@ The intended core entities are: 1. `Faction` 2. `Commander` 3. `System` -4. `Node` -5. `LocalBubble` +4. `Anchor` +5. `Localspace` 6. `Station` 7. `Ship` 8. `ModuleInstance` @@ -108,7 +108,6 @@ Recommended commander kinds: - `station` - `ship` - `fleet` -- `sector` - `task-group` ## System @@ -124,40 +123,37 @@ Suggested fields: - `nodeIds` - `faction influence later` -## Node +## Anchor -A node is a meaningful location in system space that owns a local bubble. +An anchor is a meaningful location in a system that owns a localspace. Suggested fields: -- `nodeId` +- `anchorId` - `systemId` - `kind` - `systemPosition` -- `bubbleId` -- `parentNodeId?` +- `localspaceId` +- `parentAnchorId?` - `orbital metadata?` -- `occupyingStructureId?` +- `constructionIds?` -Recommended node kinds: +Recommended anchor kinds: - `star` - `planet` - `moon` - `lagrange-point` -- `station` -- `gate` -- `resource-site` -- `structure` +- `resource-node` -## LocalBubble +## Localspace -A local bubble is the tactical simulation context attached to one node. +A localspace is the tactical simulation context attached to one anchor. Suggested fields: -- `bubbleId` -- `nodeId` +- `localspaceId` +- `anchorId` - `systemId` - `radius` - `occupantShipIds` @@ -168,16 +164,16 @@ Suggested fields: ## Station -A station is a structure attached to a Lagrange-point node. +A station is a constructed structure that lives inside one localspace. Suggested fields: - `stationId` - `ownerFactionId` - `commanderId?` -- `nodeId` +- `anchorId` - `systemId` -- `bubbleId` +- `localspaceId` - `moduleIds` - `inventory` - `population` @@ -231,7 +227,7 @@ Recommended host kinds: ## Claim -A claim is a vulnerable object placed at a Lagrange point before construction. +A claim is a vulnerable object placed at a valid construction anchor before construction. Suggested fields: @@ -239,8 +235,8 @@ Suggested fields: - `ownerFactionId` - `commanderId?` - `systemId` -- `nodeId` -- `bubbleId` +- `anchorId` +- `localspaceId` - `placedAt` - `activatesAt` - `state` @@ -261,8 +257,8 @@ Suggested fields: - `constructionSiteId` - `ownerFactionId` -- `nodeId` -- `bubbleId` +- `anchorId` +- `localspaceId` - `targetKind` - `targetDefinitionId` - `requiredItems` @@ -354,12 +350,12 @@ Recommended ship spatial state fields: - `spaceLayer` - `currentSystemId` -- `currentNodeId?` -- `currentBubbleId?` +- `currentAnchorId?` +- `currentLocalspaceId?` - `localPosition?` - `systemPosition?` - `movementRegime` -- `destinationNodeId?` +- `destinationAnchorId?` - `transitState?` Recommended space layers: @@ -367,7 +363,7 @@ Recommended space layers: - `universe-space` - `galaxy-space` - `system-space` -- `local-space` +- `localspace` Recommended movement regimes: @@ -466,7 +462,7 @@ The following rules should remain true unless deliberately revised: ## Relationship To Other Documents -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) - defines the layered world structure - [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 92b7c25..5757c1e 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -15,11 +15,6 @@ For the implementation migration path from the current codebase to this design s - intra-system warp and inter-system FTL - viewer hierarchy and simulation boundaries -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) - - older spatial design document - - useful migration context, but secondary to `UNIVERSE-MODEL.md` - - should be aligned to the universe model over time - - [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) - commander roles for factions, stations, and ships - command hierarchy @@ -64,7 +59,7 @@ For the implementation migration path from the current codebase to this design s - policy-based behavior limits - [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) - - local-space combat + - localspace combat - piracy and station defense - claim destruction and contest - commander-driven engagement behavior @@ -95,7 +90,7 @@ For the implementation migration path from the current codebase to this design s - [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) - station roles - - local bubble functions + - localspace functions - station command requirements - station services, docking, and market responsibilities diff --git a/docs/ECONOMY.md b/docs/ECONOMY.md index 776cf76..a069b9b 100644 --- a/docs/ECONOMY.md +++ b/docs/ECONOMY.md @@ -254,13 +254,13 @@ Those support goods are defined as item roles in [ITEMS.md](/home/jbourdon/repos ## Market And Space -The market should respect the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md). +The market should respect the spatial model in [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md). Implications: -- stations are nodes with local bubbles -- docking and transfer happen in local-space -- in-system logistics move through warp between nodes +- stations live in localspaces owned by anchors +- docking and transfer happen in localspace +- in-system logistics move through warp between anchors - inter-system trade moves through stargates or FTL Distance and travel friction should matter economically. diff --git a/docs/EVENTS.md b/docs/EVENTS.md index e17f9cc..71a8cd3 100644 --- a/docs/EVENTS.md +++ b/docs/EVENTS.md @@ -34,7 +34,8 @@ Every event should conceptually have: - `kind` - `spaceLayer` - `systemId?` -- `bubbleId?` +- `localspaceId?` +- `anchorId?` - `primaryEntityKind` - `primaryEntityId` - `relatedEntityIds` @@ -51,7 +52,7 @@ 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` +- local tactical events belong to `localspace` This is important for interest management. @@ -95,8 +96,8 @@ These describe meaningful transitions in movement regime or location context. Examples: -- `entered-local-bubble` -- `left-local-bubble` +- `entered-localspace` +- `left-localspace` - `warp-spooling-started` - `warp-started` - `warp-arrived` @@ -314,7 +315,7 @@ The following rules should remain true unless deliberately revised: - [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) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) - defines event scope by space layer - [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) diff --git a/docs/MODULES.md b/docs/MODULES.md index c6f7138..968b079 100644 --- a/docs/MODULES.md +++ b/docs/MODULES.md @@ -103,7 +103,7 @@ This is especially important because your station model is configuration-based r ## Structural Rule -Stations are built at one Lagrange point and expanded by adding modules. +Stations are built at one valid construction anchor and expanded by adding modules. That means modules are the main axis of station growth. diff --git a/docs/POLICIES.md b/docs/POLICIES.md index ae3becf..12ef7dd 100644 --- a/docs/POLICIES.md +++ b/docs/POLICIES.md @@ -79,9 +79,9 @@ Docking policy matters because no trade or transfer can happen without actual lo 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): +This does not override the hard structural rule from [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md): -- one structure per Lagrange point +- construction is only valid at supported construction anchors But it does help define who is permitted or tolerated to claim and build in a given system. @@ -149,13 +149,13 @@ 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 +- hostile factions may be denied docking and targeted in localspace 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. +Claim objects at valid construction anchors are visible and contestable. Policy influences: @@ -186,7 +186,7 @@ The following rules should remain true unless deliberately revised: - [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) - policy constrains trade participation -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) - policy interacts with claims, systems, and local access - [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) diff --git a/docs/PRODUCTION.md b/docs/PRODUCTION.md index 3778a1e..8567fc5 100644 --- a/docs/PRODUCTION.md +++ b/docs/PRODUCTION.md @@ -182,7 +182,7 @@ It should: - allow delivery by traders or support ships - feed the actual building process -This is especially important during station founding at claimed Lagrange points. +This is especially important during station founding at claimed construction anchors. ## Production Queues diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 76852df..19d5856 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -26,7 +26,7 @@ The current simulation behavior is driven mostly by: 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) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.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) @@ -53,11 +53,11 @@ 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 +- `localspace` +- anchor-owned localspaces +- construction only at valid construction anchors +- warp between anchors within one system +- local gameplay inside localspaces Current state: @@ -66,16 +66,16 @@ Current state: - 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 first-class anchor graph +- no first-class localspaces - 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. +- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no `AnchorRuntime`, `LocalspaceRuntime`, `ClaimRuntime`, or `ConstructionSiteRuntime`. +- [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) computes station positions directly instead of creating anchor-backed placement. +- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) still treats travel as raw coordinate movement rather than anchor-to-anchor transit between spaces. ### Command and Control @@ -202,12 +202,12 @@ 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 +- no contracts for localspaces, 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. +- [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) cannot render an anchor graph, localspaces, claims, or construction states because that data does not exist yet. ## Subsystem Assessment @@ -226,7 +226,7 @@ These should evolve in place. - 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 +- direct station placement with anchor, claim, and construction-site placement - flat event records with typed event payloads ### Avoid @@ -246,8 +246,8 @@ Goal: Work: - extend [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) with: - - `NodeRuntime` - - `LocalBubbleRuntime` + - `AnchorRuntime` + - `LocalspaceRuntime` - `CommanderRuntime` - `ClaimRuntime` - `ConstructionSiteRuntime` @@ -261,33 +261,33 @@ Work: - commander kinds - add structured ship spatial state: - current space layer - - current node - - current bubble + - current anchor + - current localspace - current transit Why first: - every later change depends on this vocabulary existing in runtime state -### Phase 2: Refactor Scenario and World Building Around Nodes +### Phase 2: Refactor Scenario and World Building Around Anchors Goal: -- make systems produce a real node graph with local bubbles and Lagrange-backed construction points +- make systems produce a real anchor graph with localspaces and supported construction anchors Work: -- extend [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) with authored node and claim-related definitions only where necessary +- extend [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) with authored anchor 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 + - 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 nodes +- movement, claims, construction, and viewer transitions all depend on real anchors ### Phase 3: Introduce Founding, Claims, and Construction Sites @@ -303,7 +303,7 @@ Work: - active - destroyed - add construction-site runtime state with: - - target node + - target anchor - blueprint or constructible reference - construction storage inventory - construction buy orders @@ -315,7 +315,7 @@ Work: Why here: -- it lets the code start reflecting the station and Lagrange rules without requiring the full economy rewrite first +- 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 @@ -326,8 +326,8 @@ Goal: Work: - replace direct long-range movement with: - - local thruster movement inside a bubble - - in-system warp between nodes + - local thruster movement inside a localspace + - in-system warp between anchors - 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 @@ -335,7 +335,7 @@ Work: Why here: -- this is the point where [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) starts becoming real in the simulation +- this is the point where [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) starts becoming real in the simulation ### Phase 5: Introduce Commanders and Task Layers @@ -376,7 +376,7 @@ Work: Why here: -- once commanders and nodes exist, this becomes a coherent system instead of isolated resource transfers +- once commanders and anchors exist, this becomes a coherent system instead of isolated resource transfers ### Phase 7: Upgrade Events and Streaming @@ -391,7 +391,7 @@ Work: - universe - galaxy - system - - local bubble + - localspace - 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 @@ -408,8 +408,8 @@ Goal: Work: - extend [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) for: - - nodes - - local bubbles + - anchors + - localspaces - claims - construction sites - market orders @@ -417,8 +417,8 @@ Work: - 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 + - anchor-centric system view + - localspace detail - regime-aware ship rendering Why last: diff --git a/docs/SHIPS.md b/docs/SHIPS.md index 3120b4b..1f705e1 100644 --- a/docs/SHIPS.md +++ b/docs/SHIPS.md @@ -2,7 +2,7 @@ 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). +Ships are mobile actors that operate across the spatial model in [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) under the authority of commanders defined in [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md). ## Core Principles @@ -35,8 +35,8 @@ From a simulation point of view, the important distinction is not only hull cate Ships should move according to the layered spatial model: -- thrusters in `local-space` -- warp in `system-space` +- thrusters inside a `localspace` +- warp between anchors inside one system - stargate or FTL for inter-system travel Ships should not behave as if an entire system is one continuous local dogfighting field. @@ -82,7 +82,7 @@ Those capabilities should primarily come from fitted modules as described in [MO ## Relationship To Other Documents -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.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) diff --git a/docs/SPACES.md b/docs/SPACES.md deleted file mode 100644 index 010671b..0000000 --- a/docs/SPACES.md +++ /dev/null @@ -1,518 +0,0 @@ -# Spaces - -This document defines the intended spatial model for the project. - -It is a gameplay and simulation document first. The viewer should expose these layers clearly, but it does not define them. - -The core idea is that the world is not one continuous field of arbitrary movement. Instead, gameplay happens across nested spatial layers with different rules, scales, and valid actions. - -See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the entity vocabulary that should represent these layers. - -## Design Goals - -The spatial model should support: - -- EVE-like travel pacing and readability -- explicit transitions between tactical space and transit space -- local combat and interaction bubbles -- scalable simulation partitioning -- scalable replication and interest management -- future server-side sharding by local bubble if necessary - -The intended feel is: - -- local maneuvering is slow, deliberate, and readable -- in-system travel is warp-based, not long free-flight -- inter-system travel is explicit and infrastructural -- zooming the viewer reveals different valid abstractions of the same world - -## Space Layers - -The simulation is divided into four major space layers: - -1. `universe-space` -2. `galaxy-space` -3. `system-space` -4. `local-space` - -These are simulation layers, not just camera levels. - -### `universe-space` - -The broadest simulation layer. - -This is where universe-wide state and events live, such as: - -- global time -- global factions and diplomacy -- universe-scale event scheduling -- future crises, anomalies, migrations, or story events - -`universe-space` is not primarily about positional navigation. It is the top-most simulation context. - -### `galaxy-space` - -The layer where star systems exist as spatially arranged world entities. - -This is where the game models: - -- system positions -- large-scale routes and proximity -- inter-system connectivity -- strategic movement between systems - -Ships do not dogfight in `galaxy-space`. It is the strategic layer connecting systems. - -### `system-space` - -The layer inside a single star system where travel occurs between meaningful locations. - -This is where the game models: - -- stars -- planets -- moons -- stations -- structures -- gates -- resource locations, if they should be direct destinations -- Lagrange points -- travel relationships between these locations - -`system-space` is the travel layer between local bubbles. Gameplay-wise, this can also be referred to as warp-space for ship movement inside a system. - -### `local-space` - -The tactical simulation bubble attached to a specific node. - -This is where close interaction happens: - -- thruster flight -- combat -- docking -- undocking -- mining -- construction -- rendezvous -- local hazards - -Each `local-space` is an isolated simulation bubble attached to one node. Ships leave one local bubble, exist in `system-space` during warp transit, then enter another local bubble on arrival. - -Local bubbles are also the intended future unit of simulation partitioning. A later runtime may move one or more bubbles to dedicated servers without changing the gameplay model. - -## Nodes - -A node is a meaningful location in `system-space` that owns a `local-space` bubble. - -Examples of nodes: - -- star -- planet -- moon -- station -- structure -- gate -- major resource location if desired -- each Lagrange point associated with a massive orbital - -Each node should have: - -- a stable identifier -- a parent system -- a type -- a position in `system-space` -- a local bubble radius -- optional parent/child relationships -- optional orbital metadata - -Examples: - -- a planet node orbits a star node -- a moon node orbits a planet node -- a station or structure node is built at a Lagrange point - -## Lagrange Points - -Each massive orbital should expose five Lagrange points: - -- `L1` -- `L2` -- `L3` -- `L4` -- `L5` - -These are valid nodes in `system-space`, each with its own `local-space`. - -They should be computed from orbital relationships rather than authored by hand in most cases. - -Construction rule: - -- each Lagrange point can host exactly one structure - -This scarcity is intentional. Lagrange points should be valuable strategic locations rather than interchangeable empty coordinates. - -Recommended applicability: - -- major orbitals should expose all five Lagrange points -- this should apply at least to sufficiently massive planets -- moons may expose none or fewer, depending on the final simulation rule - -Lagrange points should not always be immediately buildable by default. - -Recommended structure founding flow: - -1. claim the Lagrange point -2. protect the claim until it matures -3. activate the claim -4. begin station construction - -Lagrange points are useful for: - -- staging areas -- logistics hubs -- military control points -- hidden or contested infrastructure -- future economy and navigation design -- station and structure placement - -## Structures At Lagrange Points - -Stations and other built structures should always be placed at Lagrange points. - -This should be treated as a world rule, not merely a common pattern. - -Implications: - -- player and AI construction targets for major structures are Lagrange nodes -- stations do not occupy arbitrary free positions in system-space -- structure placement is tied to orbital geometry -- economically and militarily valuable station locations are legible from the system map -- each Lagrange point supports only one built structure -- to create another station, a faction must secure another valid location - -This makes system geography more understandable and gives Lagrange points durable strategic meaning. - -## Claiming Lagrange Points - -Station construction should begin with an explicit claim on a Lagrange point. - -The claim should behave like a vulnerable placed object. - -Properties: - -- it marks intent to occupy the Lagrange point -- it can be attacked or destroyed by enemies or pirates -- it requires an activation period before full construction can begin - -Recommended founding sequence: - -1. a faction places a claim object at the target Lagrange point -2. the claim survives for its activation time -3. the claim becomes active -4. station construction storage appears -5. the desired station design creates demand for required construction materials -6. constructor ships consume those materials to build the station - -This makes Lagrange occupation contestable and visible. - -## Local Bubbles - -Each node owns exactly one local bubble. - -A local bubble defines: - -- the local simulation frame -- the tactical interaction radius -- the list of occupants -- the set of legal actions inside that space -- the future server authority boundary - -Local bubbles should be treated as separate simulation contexts, not merely camera zoom-ins. - -Rules: - -- a ship in `local-space` belongs to exactly one bubble -- actions such as combat, docking, mining, and construction happen only inside a local bubble -- leaving a bubble is an explicit transition into `system-space` -- entering a destination bubble is an explicit arrival transition from `system-space` - -See [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) for the combat consequences of this rule. - -## Movement Regimes - -Ships do not move with one universal locomotion model. Their movement depends on their current space layer and travel regime. - -Primary regimes: - -- `local-flight` -- `warp` -- `stargate-transit` -- `ftl-transit` - -### `local-flight` - -Used inside `local-space`. - -Characteristics: - -- uses normal thrusters -- supports fine positioning -- supports docking and undocking -- supports combat -- supports mining and close interaction - -This regime should feel heavy, readable, and tactical. - -### `warp` - -Used in `system-space` to travel between nodes in the same system. - -Characteristics: - -- exits one local bubble -- enters spool-up -- travels through `system-space` -- drops out at a destination node -- enters the destination local bubble - -The intended feel is close to EVE, but with spool-up emphasis rather than strict align mechanics. - -Recommended warp phases: - -1. `warp-spooling` -2. `in-warp` -3. `warp-dropout` - -During warp, ships should not be treated as locally maneuvering units. - -### `stargate-transit` - -Used to travel between systems through infrastructure. - -Characteristics: - -- starts from a gate node in local-space -- transitions through a gate sequence -- arrives at a gate node in another system - -This should be a discrete inter-system travel mode, not merely a very long warp. - -### `ftl-transit` - -Used by ships that have their own FTL capability. - -Characteristics: - -- explicit inter-system travel regime -- likely stronger costs, constraints, or cooldowns than gates -- may bypass some infrastructure requirements - -This remains distinct from in-system warp. - -## Valid Actions By Space - -### In `universe-space` - -Examples: - -- resolve universe-scale events -- evaluate global strategic conditions -- future narrative or crisis systems - -### In `galaxy-space` - -Examples: - -- reason about systems -- evaluate strategic routes -- choose inter-system destinations - -### In `system-space` - -Examples: - -- choose destination nodes -- execute warp travel -- evaluate node-to-node movement - -### In `local-space` - -Examples: - -- maneuver with thrusters -- dock -- undock -- mine -- fight -- build -- transfer cargo locally - -Rule of thumb: - -- tactical interaction belongs to `local-space` -- transit belongs to `system-space` -- strategic topology belongs to `galaxy-space` - -## Ship Spatial State - -Ships should eventually be modeled with explicit spatial state, not just one position plus one target position. - -At minimum, a ship should know: - -- current `systemId` -- current `spaceLayer` -- current `nodeId`, if in local-space -- current `localPosition`, if in local-space -- current transit data, if in warp or inter-system travel - -Recommended movement/runtime states include: - -- `idle` -- `local-flight` -- `warp-spooling` -- `in-warp` -- `warp-dropout` -- `docking` -- `docked` -- `undocking` -- `using-stargate` -- `ftl-spooling` -- `in-ftl` -- `arriving-from-ftl` - -This spatial model works together with the command and economy documents: - -- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) - - defines who decides and delegates - -- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) - - defines how stations and factions participate economically - -- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) - - defines ship-side capability and behavior - -- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) - - defines station-side role and responsibility - -## Orders And Destinations - -Orders should target valid destinations in the spatial model. - -In practice, that means ships should target nodes and bubbles rather than arbitrary points across an entire system. - -Examples: - -- travel to node -- warp to node -- dock at structure in node -- mine in node -- use gate to system -- jump to system - -This makes planning clearer and keeps traversal tied to the intended world structure. - -## Viewer Expectations - -The viewer should reveal these layers as the player zooms or changes context. - -Desired viewer scales: - -1. `universe/galaxy view` -2. `system view` -3. `local view` - -### `universe/galaxy view` - -Shows: - -- systems -- strategic relationships -- large-scale motion and events - -### `system view` - -Shows: - -- nodes inside one system -- warp destinations -- route structure -- high-level in-system movement - -This view should not pretend that all tactical detail is always present. - -### `local view` - -Shows: - -- one node bubble in detail -- ships maneuvering with thrusters -- combat, docking, mining, and construction - -Viewer zoom should expose valid abstractions of simulation truth rather than inventing unrelated presentation layers. - -## Interest Management - -This spatial model naturally supports interest management for streaming. - -The general rule should be: - -- always stream context from higher spaces -- filter detailed context from lower spaces based on interest - -Examples: - -- a client viewing a local bubble still needs relevant system, galaxy, and universe context -- a client viewing a system does not need full-fidelity tactical events from every local bubble -- a client viewing the galaxy does not need continuous local combat state for every bubble - -Suggested replication principle: - -- high-layer events are broad but low-detail -- low-layer events are narrow but high-detail - -Example filtering: - -- `universe-space` events can be broadcast widely -- `galaxy-space` events can be scoped by region or strategic relevance -- `system-space` events can be scoped by current or observed system -- `local-space` events can be scoped by the specific bubble being observed or occupied - -This should make future multiplayer scaling easier than a flat world-wide stream. - -## Recommended Backend Direction - -The backend should move toward: - -- explicit node definitions -- explicit local bubble definitions -- explicit ship travel regimes -- explicit transitions between local, system, and inter-system movement - -Recommended progression: - -1. define nodes and local bubbles in world/runtime contracts -2. compute and include Lagrange points for major orbitals -3. refactor ship movement around regimes instead of free system-local travel -4. restrict tactical actions to local-space -5. expose regime and bubble membership in replication contracts -6. redesign viewer zoom and replication around these layers - -## Invariants - -These rules should remain true unless there is a very deliberate design reason to break them: - -- every local bubble belongs to exactly one node -- every ship is in exactly one major movement regime at a time -- ships in different local bubbles are not co-located, even if they are in the same system -- movement inside local-space uses thrusters -- movement between nodes inside a system uses warp -- movement between systems uses stargates or ship FTL -- combat, docking, mining, and construction happen only in local-space -- viewer abstractions should map back to real simulation layers -- every structure occupies exactly one Lagrange point -- every Lagrange point supports at most one structure -- a station site must be claimed before full construction begins - -## Open Follow-Up Documents - -This document is part of the official design set listed in [DESIGN.md](/home/jbourdon/repos/space-game/docs/DESIGN.md). diff --git a/docs/STATIONS.md b/docs/STATIONS.md index 767a347..7328eda 100644 --- a/docs/STATIONS.md +++ b/docs/STATIONS.md @@ -2,7 +2,7 @@ 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. +Stations are persistent constructions in the world that live in a localspace, provide services, participate in the economy, and act through station commanders. ## Core Principles @@ -17,7 +17,7 @@ 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. +Station growth happens by adding modules to the existing station at its current construction location. To create another station, a faction needs: @@ -25,7 +25,7 @@ To create another station, a faction needs: - 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). +Before station construction itself, the faction should secure the chosen site through the appropriate local claim or founding process defined by the universe model. Station identity and capability should primarily come from module composition, as described in [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md). @@ -44,13 +44,15 @@ Stations may serve as: ## Spatial Role -Stations are nodes in `system-space` with their own `local-space`. +Stations are constructions that exist inside one `localspace`. -Stations and other built structures should always be located at Lagrange points. +Stations may be built at valid construction anchors such as: -Each Lagrange point can hold only one structure. +- planets +- moons +- Lagrange points -Their local bubbles are where: +Their localspaces are where: - docking happens - cargo transfer happens @@ -58,13 +60,13 @@ Their local bubbles are where: - 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). +Localspace 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 +1. claim or secure a valid construction anchor 2. wait for the claim to activate 3. create station construction storage 4. publish buy orders for the required construction materials @@ -141,15 +143,9 @@ Actual participation in trade and docking should still be policy-controlled. See Station ownership is not local-bubble exclusive. -The important hard rule is: +Ownership does not imply one faction per localspace. -- 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. +Friendly or otherwise permitted factions may build stations within the same system so long as they use different valid construction locations. ## Services @@ -181,7 +177,7 @@ Population growth and decline follow the rules in [WORKFORCE.md](/home/jbourdon/ ## Relationship To Other Documents -- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.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) diff --git a/docs/TASKS.md b/docs/TASKS.md index 3e532dd..6846218 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -55,12 +55,12 @@ Orders should survive replanning better than tasks. Examples: -- travel to node +- travel to anchor - dock at station -- claim Lagrange point +- claim construction anchor - build station here - escort this ship -- defend this bubble +- defend this localspace Orders are the main override layer above routine autonomous behavior. @@ -240,13 +240,13 @@ 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). +Tasks should respect the spatial model in [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md). That means: - local maneuvering is distinct from warp -- docking is local-space work -- cargo transfer is local-space work +- docking is localspace work +- cargo transfer is localspace work - inter-system travel is distinct from in-system travel ## Policy-Aware Tasking @@ -305,7 +305,7 @@ The following rules should remain true unless deliberately revised: - [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) +- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md) - defines where tasks can occur - [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) diff --git a/docs/UNIVERSE-MODEL.md b/docs/UNIVERSE-MODEL.md index bdfccd3..0a9ef64 100644 --- a/docs/UNIVERSE-MODEL.md +++ b/docs/UNIVERSE-MODEL.md @@ -469,6 +469,13 @@ It also gives a cleaner authority boundary for later scaling: - one localspace can become one simulation partition - one system can remain a higher-level strategic container +This supports: + +- interest management +- tactical culling +- isolated combat and logistics spaces +- future sharding without redefining the gameplay model + ## Non-Goals This model does not require: