From 74b8bf411631830a7016d8427fe244b7a034d27b Mon Sep 17 00:00:00 2001 From: Jonathan Bourdon Date: Mon, 6 Apr 2026 19:11:27 -0400 Subject: [PATCH] Add canonical universe model document --- docs/DESIGN.md | 15 +- docs/UNIVERSE-MODEL.md | 494 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 504 insertions(+), 5 deletions(-) create mode 100644 docs/UNIVERSE-MODEL.md diff --git a/docs/DESIGN.md b/docs/DESIGN.md index bf52027..92b7c25 100644 --- 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 - - nodes and local bubbles - - movement regimes - - viewer scale expectations - - replication and interest management implications + - 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 diff --git a/docs/UNIVERSE-MODEL.md b/docs/UNIVERSE-MODEL.md new file mode 100644 index 0000000..bdfccd3 --- /dev/null +++ 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.