jbourdon/space-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: establish official design documentation

Browse Source
This commit is contained in:
Jonathan Bourdon
2026-03-13 22:08:48 -04:00
parent 0ec47888eb
commit 86b8f4a73f
19 changed files with 4673 additions and 968 deletions
Download Patch File Download Diff File Expand all files Collapse all files

518
docs/SPACES.md Normal file
View File

@@ -0,0 +1,518 @@
# 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).