519 lines
14 KiB
Markdown
519 lines
14 KiB
Markdown
# 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).
|