space-game/docs/UNIVERSE-MODEL.md

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 as the tactical space around anchors
• 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 has a localspace around it

The intended structure is:

1. galaxy
2. solar system
3. anchor

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.

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
• a localspace around it
• 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 around it.

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 and derived locations such as Lagrange points

Every star, planet, and moon has a localspace around it.

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 around it
• 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 around it

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.

Resource nodes are strategic mining destinations.

That means:

• outside localspace, a miner travels to a resource-node anchor
• inside that localspace, the miner chooses a concrete extractable target

The concrete extractable target is a tactical mining concern, not a strategic travel identity.

So:

• travel uses anchorId
• local extraction uses a localspace-level target such as a rock, cluster, or gas pocket

Do not use a generic NodeId to mean both.

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 is the tactical space around 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

For mining specifically:

• the destination localspace is chosen by anchor
• the final extractable target is chosen only after the ship is inside that localspace

This preserves the distinction between:

• strategic travel to a mining site
• tactical mining behavior inside that site

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 anchor unless it is actively transitioning between anchors.

Normal ship state should be one of:

• at an anchor
• traveling between anchors 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.

Viewer zoom transitions are a client-side presentation effect.

That means:

• zooming from galaxy to system does not imply one shared coordinate space
• zooming from system to localspace does not imply one shared coordinate space
• the client may animate or blend between views for readability
• those effects do not define simulation truth

Scales And Units

Each spatial layer owns its own units.

Those units should be native to that layer, not projections of one universal master coordinate system.

Galaxy

The galaxy layer uses:

• light-years

This is the scale for:

• system positions
• inter-system distances
• strategic map layout

System

The system layer uses:

• AU

This is the scale for:

• anchor positions inside a system
• orbital relationships
• intra-system routing and warp travel

Variation at localspace scale is intentionally insignificant at this layer.

Localspace

The localspace layer uses:

• meters
• m/s

This is the scale for:

• tactical movement
• combat
• docking
• mining
• construction

Variation at system scale is intentionally insignificant at this layer.

Cross-Layer Rule

The simulation should not try to preserve one continuous coordinate frame across galaxy, system, and localspace.

Cross-layer relationships should be modeled through:

• containment
• references
• travel state

Not through:

• universal coordinate conversion
• raw projection of localspace offsets into system space
• raw projection of system offsets into galaxy space

The viewer may animate transitions between layers, but that is presentation only. It does not mean the simulation uses one continuous spatial frame.

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
• anchors 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 anchor can become one tactical 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:

• 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: a meaningful location in a system and the primary tactical simulation container
• localspace: the tactical simulation space around an anchor, not a separately identified entity
• 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.