Add canonical universe model document

2026-04-06 19:11:27 -04:00
parent c9a4b474b4
commit 74b8bf4116
2 changed files with 504 additions and 5 deletions
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -8,12 +8,17 @@ For the implementation migration path from the current codebase to this design s
 ## Core Documents
 - [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md)
  - canonical world structure
  - galaxy, systems, celestials, anchors, and localspaces
  - ship and construction placement
  - intra-system warp and inter-system FTL
  - viewer hierarchy and simulation boundaries
 - [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
-  - spatial layers
+  - older spatial design document
-  - nodes and local bubbles
+  - useful migration context, but secondary to `UNIVERSE-MODEL.md`
-  - movement regimes
+  - should be aligned to the universe model over time
  - 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
--- a/docs/UNIVERSE-MODEL.md
+++ b/docs/UNIVERSE-MODEL.md
@@ -0,0 +1,494 @@
 # Universe Model
 This document defines the intended world structure for the game.
 It is the canonical reference for:
 - galaxy structure
 - solar systems
 - celestials
 - anchors
 - localspaces
 - ship and station placement
 - intra-system travel
 - inter-system travel
 - construction placement
 This document is design-first. It does not describe the current implementation. It describes the target world model the simulation and viewer should converge toward.
 Where older documents conflict with this one, this document should win.
 ## Core Intent
 The game is a galaxy simulation built from nested spatial layers.
 The structure can be understood as a tree:
 - the galaxy contains solar systems
 - each solar system contains celestials and other derived locations
 - each meaningful location is an anchor
 - each anchor owns one localspace
 The intended structure is:
 1. `galaxy`
 2. `solar system`
 3. `anchor`
 4. `localspace`
 Ships and stations do not live in arbitrary free-floating "system local space".
 They live in a localspace tied to something meaningful.
 That anchor is usually:
 - a celestial
 - a Lagrange point
 - a resource node
 Stargates and stations are not anchors by themselves. They are constructions that live inside a localspace.
 This keeps the world legible, gives travel structure, and makes infrastructure placement strategically meaningful.
 ## Galaxy
 The galaxy is the top-level navigable world map.
 It contains:
 - solar systems
 - system-to-system distances
 - inter-system connectivity
 - the strategic map used for expansion, trade planning, diplomacy, and route planning
 The galaxy is not a combat layer.
 Ships do not dogfight in galaxy space. Inter-system movement is represented strategically until a ship arrives in its destination system.
 The galaxy and system visualizations are primarily about information gathering:
 - what exists
 - what is close
 - where resources are
 - who controls what
 ## Solar Systems
 A solar system is a strategic and economic container.
 A solar system contains:
 - stars
 - planets
 - moons
 - Lagrange points
 - resource nodes
 - constructions that exist inside localspaces, such as stations and stargates
 A solar system is not itself a single tactical playspace.
 Instead, it is a collection of anchored localspaces plus the travel relationships between them.
 Systems remain important for:
 - map readability
 - strategic routing
 - economy aggregation
 - territorial and diplomatic meaning
 - visibility and ownership summaries
 ## Anchors
 An anchor is a meaningful object in a system that owns a localspace.
 Anchors are first-class world entities.
 Initial anchor types:
 - `star`
 - `planet`
 - `moon`
 - `lagrange-point`
 - `resource-node`
 Future anchor types may exist, but they should only be introduced if they create real gameplay value.
 Each anchor should have:
 - a stable ID
 - a parent `systemId`
 - an anchor type
 - a position in system space
 - optional orbital metadata
 - an associated localspace definition
 - optional parent/child relationships
 Examples:
 - a planet is an anchor and a celestial
 - a moon is an anchor and a celestial
 - a Lagrange point is an anchor but not a celestial
 - a resource node is an anchor but not a celestial
 - a Lagrange point can be the child of a moon, which is the child of a planet, which is the child of a star
 Every anchor has exactly one localspace.
 ## Celestials
 Celestials are the natural massive bodies in a system.
 Initial celestial types:
 - `star`
 - `planet`
 - `moon`
 Celestials exist for three reasons:
 1. they structure the solar system visually and strategically
 2. they define orbital relationships
 3. they provide valid anchors for localspaces and derived locations such as Lagrange points
 Every star, planet, and moon gets a localspace.
 Not all anchors are celestials, but all celestials are anchors.
 ## Lagrange Points
 Lagrange points are explicit anchors derived from celestial orbital relationships.
 They are not decorative metadata.
 They are valid construction locations, but they are not the only valid construction locations.
 Initial assumptions:
 - major orbitals can expose `L1` through `L5`
 - each exposed Lagrange point is its own anchor
 - each exposed Lagrange point has its own localspace
 - Lagrange points are valid construction sites
 For now, all five may exist for supported orbitals, but the intended direction is that only major planets should necessarily expose all five.
 Lagrange points are useful for:
 - logistics hubs
 - defense platforms
 - industrial complexes
 - stargates
 - staging areas
 ## Resource Nodes
 Resource nodes should be treated as anchors.
 That means a resource node can have:
 - a stable identity
 - a place in a solar system
 - its own localspace
 This is desirable because it allows resources to exist anywhere meaningful in a system while still fitting the anchored localspace model.
 A resource node is not a celestial.
 It is an anchor with a localspace centered on an extractable site.
 Resource nodes are not construction sites.
 That is intentional so they can be spawned, depleted, despawned, and regenerated more freely than permanent infrastructure anchors.
 ## Localspace
 `localspace` is the tactical simulation term and should be the only term used for this concept.
 Do not use:
 - `sector`
 - `local-space`
 - `anchored sector`
 Use:
 - `localspace`
 Each localspace belongs to exactly one anchor.
 Examples:
 - the localspace around a planet
 - the localspace around a moon
 - the localspace around a Lagrange point
 - the localspace around a resource node
 Localspace is where close simulation happens:
 - thruster movement
 - combat
 - docking
 - undocking
 - mining
 - station operation
 - station construction
 - local logistics
 - tactical defense
 Ships and constructions do not exist directly in system space. They exist in one localspace at a time unless they are explicitly traveling between anchors.
 ## Ship Placement
 A ship always belongs to exactly one localspace unless it is actively transitioning between anchors.
 Normal ship state should be one of:
 - in a localspace
 - traveling between localspaces in the same system
 - traveling between systems
 Inside a localspace, ships use tactical movement with thrusters.
 While moving between anchors inside a system, ships should be in an explicit warp travel state rather than pretending that the entire solar system is one free-flight arena.
 ## Station Placement
 Stations are not arbitrary coordinates in a system.
 Stations belong to localspaces.
 Stations may be built at any valid anchor that supports the intended construction.
 That includes:
 - planets
 - moons
 - Lagrange points
 That does not include resource nodes.
 Lagrange points are one important construction option, not the default answer for all stations.
 Each construction site should be understandable from the system map:
 - what localspace it belongs to
 - what role it serves
 - why it matters
 ## Stargates
 Stargates are constructed or placed objects that live inside a localspace.
 A stargate is not abstract system metadata.
 It should:
 - exist at a real place in space
 - have a tactical presence
 - be defensible or contestable
 - connect one system to another through a linked gate
 Default rule:
 - a stargate is built in a localspace related to a valid anchor
 Player factions and NPC factions can both own and build stargates.
 Inter-system travel is normally done using gates, though some ships may later support direct FTL as a special capability.
 ## System Space
 System space still exists, but it is not the primary gameplay space.
 System space is the strategic layer that relates anchors to one another.
 It is used for:
 - anchor positions
 - orbital relationships
 - path planning between anchors
 - travel graph generation
 - map presentation
 System space should not be treated as a giant tactical sandbox where ships idle, fight, mine, and build anywhere.
 That is the main implementation mistake this model is meant to prevent.
 ## Intra-System Travel
 Travel inside a solar system is movement between anchors.
 This should feel like warp travel, not long-duration manual flight across a whole star system.
 Core rule:
 - ships move tactically inside a localspace using thrusters
 - ships transition into warp travel state to move to another anchor in the same system
 - ships arrive into the destination anchor's localspace
 This means intra-system travel has two different regimes:
 1. local tactical movement by thrusters
 2. anchor-to-anchor warp transit
 Arrival timing is sufficient. The transit does not need fully continuous tactical simulation.
 Ships in warp still exist as simulated travel-state entities with:
 - an origin anchor
 - a destination anchor
 - a departure time
 - an arrival time or ETA
 - ownership
 - travel state
 Those ships may be shown individually or as grouped representations in the viewer, but that is a presentation choice rather than a different simulation rule.
 ## Inter-System Travel
 Travel between systems is explicit FTL travel.
 Initial rule:
 - inter-system travel happens through gates
 This keeps system boundaries meaningful and keeps the galaxy map strategically understandable.
 Some ships may later have direct FTL capability, probably specialized exploration ships, but that should be treated as an extension to the model rather than the baseline rule.
 ## Fleets
 Fleets are an organizational concept, not a distinct spatial simulation layer.
 A fleet is created by an owner decision:
 - player
 - AI faction
 - other future controller types if needed
 Fleets are used to:
 - group ships
 - define hierarchy
 - configure wing behavior
 - assign coordinated movement or combat roles
 That means:
 - fleets are not anchors
 - fleets do not own localspaces
 - fleets do not use a special travel model
 If ships in a fleet are in warp transit, they are still individual ships in transit.
 The viewer or command layer may choose to display them as one fleet movement when appropriate, but that is derived from ship state and ownership structure, not a different spatial rule.
 ## Construction Model
 Construction should be localspace-driven.
 That means:
 - construction starts at a valid anchor
 - the localspace determines where the construction exists
 - claims and construction remain spatially meaningful
 This does not mean every anchor type has the same restrictions. It only means construction is never detached from place.
 Recommended founding flow:
 1. identify a valid anchor
 2. place a claim or founding marker if required
 3. defend and mature the claim if required
 4. deploy construction logistics
 5. build the station or stargate in that localspace
 ## Viewer Implications
 The viewer should reflect the world model instead of flattening it.
 Desired viewer hierarchy:
 1. galaxy view
 2. system view
 3. localspace view
 Galaxy view should show:
 - systems as a cloud of stars
 - ownership
 - routes, especially stargate links
 - strategic posture
 System view should show tactical information about the system, including:
 - stars
 - planets
 - moons
 - Lagrange points
 - stations
 - gates
 - fleets
 - ships
 - enemies
 - travel relationships
 - approximate transit positions or transit state for ships moving between anchors
 - orbital relationships
 Localspace view should show:
 - ships
 - stations
 - tactical movement
 - combat
 - construction
 - docking
 The viewer should not imply that the full solar system is one continuous local battlefield.
 ## Ownership And Sovereignty
 Ownership and sovereignty should primarily be tracked at system level.
 This is not fully defined yet, but the current design direction is:
 - systems are the main sovereignty unit
 - localspaces and constructions exist inside systems
 - local conflicts and control still matter tactically
 ## Simulation Implications
 This model supports:
 - clearer AI tasking
 - clearer travel states
 - better tactical readability
 - better interest management
 - more precise placement of industry, defense, and resource activity
 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
 ## Non-Goals
 This model does not require:
 - one continuous free-flight world across the whole galaxy
 - one giant tactical playspace per solar system
 - arbitrary station placement anywhere
 - abstract gates that do not exist in space
 - non-anchored deep-space locations as a core gameplay requirement
 ## Current Naming Guidance
 Until the implementation is updated, the following terms should be used consistently in design discussions:
 - `galaxy`: the top-level strategic star map
 - `system`: the solar system container
 - `celestial`: star, planet, or moon
 - `anchor`: anything that owns a localspace
 - `localspace`: the tactical simulation bubble attached to one anchor
 - `intra-system warp`: movement between anchors in the same system
 - `inter-system FTL`: movement between systems
 Avoid using `system local space` and `sector` as design terms going forward. They are too ambiguous and encourage the wrong implementation.