docs: establish official design documentation
This commit is contained in:
501
docs/DATA-MODEL.md
Normal file
501
docs/DATA-MODEL.md
Normal file
@@ -0,0 +1,501 @@
|
||||
# Data Model
|
||||
|
||||
This document defines the intended high-level data model for the simulation.
|
||||
|
||||
It is a design-side schema document. It does not describe the current codebase exactly. It describes the durable entity vocabulary the codebase should move toward.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The data model should support:
|
||||
|
||||
- the layered spatial model
|
||||
- commander-driven behavior
|
||||
- market-driven economy
|
||||
- module-based capability
|
||||
- population and workforce
|
||||
- claimable construction sites
|
||||
- local-space combat
|
||||
- scalable replication and future sharding
|
||||
|
||||
## Core Principles
|
||||
|
||||
- important game concepts should exist as explicit entities or records
|
||||
- IDs should be stable and durable
|
||||
- spatial state should be explicit, not inferred from one generic position alone
|
||||
- access, market, and behavior restrictions should be data-driven
|
||||
- construction, production, and logistics should all use shared entity vocabulary
|
||||
|
||||
## Identity
|
||||
|
||||
Every major persistent entity should have:
|
||||
|
||||
- a stable ID
|
||||
- an owning faction where relevant
|
||||
- a type or kind
|
||||
- a current lifecycle or state
|
||||
|
||||
Recommended global ID families:
|
||||
|
||||
- `factionId`
|
||||
- `commanderId`
|
||||
- `systemId`
|
||||
- `nodeId`
|
||||
- `bubbleId`
|
||||
- `stationId`
|
||||
- `shipId`
|
||||
- `moduleId`
|
||||
- `claimId`
|
||||
- `orderId`
|
||||
- `recipeId`
|
||||
- `policyId`
|
||||
- `marketOrderId`
|
||||
- `constructionSiteId`
|
||||
|
||||
## Core Entity Set
|
||||
|
||||
The intended core entities are:
|
||||
|
||||
1. `Faction`
|
||||
2. `Commander`
|
||||
3. `System`
|
||||
4. `Node`
|
||||
5. `LocalBubble`
|
||||
6. `Station`
|
||||
7. `Ship`
|
||||
8. `ModuleInstance`
|
||||
9. `Claim`
|
||||
10. `ConstructionSite`
|
||||
11. `MarketOrder`
|
||||
12. `Recipe`
|
||||
13. `PolicySet`
|
||||
|
||||
## Faction
|
||||
|
||||
A faction is the top-level strategic actor.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `factionId`
|
||||
- `label`
|
||||
- `color`
|
||||
- `doctrine`
|
||||
- `populationTotal`
|
||||
- `credits` if retained
|
||||
- `relation state to other factions`
|
||||
- `commanderIds`
|
||||
- `policy defaults`
|
||||
|
||||
## Commander
|
||||
|
||||
Commanders are first-class AI actors.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `commanderId`
|
||||
- `kind`
|
||||
- `ownerFactionId`
|
||||
- `parentCommanderId?`
|
||||
- `controlledEntityId?`
|
||||
- `doctrine`
|
||||
- `policy overrides`
|
||||
- `goal set`
|
||||
- `subordinateCommanderIds`
|
||||
- `alive`
|
||||
|
||||
Recommended commander kinds:
|
||||
|
||||
- `faction`
|
||||
- `station`
|
||||
- `ship`
|
||||
- `fleet`
|
||||
- `sector`
|
||||
- `task-group`
|
||||
|
||||
## System
|
||||
|
||||
A system is a strategic world entity in galaxy space.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `systemId`
|
||||
- `label`
|
||||
- `galaxyPosition`
|
||||
- `star definition`
|
||||
- `nodeIds`
|
||||
- `faction influence later`
|
||||
|
||||
## Node
|
||||
|
||||
A node is a meaningful location in system space that owns a local bubble.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `nodeId`
|
||||
- `systemId`
|
||||
- `kind`
|
||||
- `systemPosition`
|
||||
- `bubbleId`
|
||||
- `parentNodeId?`
|
||||
- `orbital metadata?`
|
||||
- `occupyingStructureId?`
|
||||
|
||||
Recommended node kinds:
|
||||
|
||||
- `star`
|
||||
- `planet`
|
||||
- `moon`
|
||||
- `lagrange-point`
|
||||
- `station`
|
||||
- `gate`
|
||||
- `resource-site`
|
||||
- `structure`
|
||||
|
||||
## LocalBubble
|
||||
|
||||
A local bubble is the tactical simulation context attached to one node.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `bubbleId`
|
||||
- `nodeId`
|
||||
- `systemId`
|
||||
- `radius`
|
||||
- `occupantShipIds`
|
||||
- `occupantStationIds`
|
||||
- `occupantClaimIds`
|
||||
- `occupantConstructionSiteIds`
|
||||
- `serverAuthorityId later`
|
||||
|
||||
## Station
|
||||
|
||||
A station is a structure attached to a Lagrange-point node.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `stationId`
|
||||
- `ownerFactionId`
|
||||
- `commanderId?`
|
||||
- `nodeId`
|
||||
- `systemId`
|
||||
- `bubbleId`
|
||||
- `moduleIds`
|
||||
- `inventory`
|
||||
- `population`
|
||||
- `workforceCapacity`
|
||||
- `workforceEfficiency`
|
||||
- `power state`
|
||||
- `policySetId?`
|
||||
- `marketOrderIds`
|
||||
- `construction state if incomplete`
|
||||
- `docking state`
|
||||
|
||||
## Ship
|
||||
|
||||
A ship is a mobile actor that changes movement regime over time.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `shipId`
|
||||
- `ownerFactionId`
|
||||
- `commanderId?`
|
||||
- `shipClass`
|
||||
- `role`
|
||||
- `moduleIds`
|
||||
- `inventory`
|
||||
- `health`
|
||||
- `power state`
|
||||
- `currentSpatialState`
|
||||
- `policySetId?`
|
||||
- `current goal/order/task references`
|
||||
|
||||
## ModuleInstance
|
||||
|
||||
A module instance is a fitted capability component on a ship or station.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `moduleId`
|
||||
- `definitionId`
|
||||
- `hostKind`
|
||||
- `hostId`
|
||||
- `category`
|
||||
- `operational state`
|
||||
- `construction state`
|
||||
- `workforceRequirement`
|
||||
- `power requirement`
|
||||
|
||||
Recommended host kinds:
|
||||
|
||||
- `ship`
|
||||
- `station`
|
||||
|
||||
## Claim
|
||||
|
||||
A claim is a vulnerable object placed at a Lagrange point before construction.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `claimId`
|
||||
- `ownerFactionId`
|
||||
- `commanderId?`
|
||||
- `systemId`
|
||||
- `nodeId`
|
||||
- `bubbleId`
|
||||
- `placedAt`
|
||||
- `activatesAt`
|
||||
- `state`
|
||||
- `health`
|
||||
|
||||
Recommended claim states:
|
||||
|
||||
- `placed`
|
||||
- `activating`
|
||||
- `active`
|
||||
- `destroyed`
|
||||
|
||||
## ConstructionSite
|
||||
|
||||
A construction site is the market-facing and build-facing record for an incomplete structure or expansion.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `constructionSiteId`
|
||||
- `ownerFactionId`
|
||||
- `nodeId`
|
||||
- `bubbleId`
|
||||
- `targetKind`
|
||||
- `targetDefinitionId`
|
||||
- `requiredItems`
|
||||
- `deliveredItems`
|
||||
- `progress`
|
||||
- `assignedConstructorIds`
|
||||
- `marketOrderIds`
|
||||
- `state`
|
||||
|
||||
Recommended target kinds:
|
||||
|
||||
- `station`
|
||||
- `station-module`
|
||||
- `ship later`
|
||||
|
||||
## MarketOrder
|
||||
|
||||
A market order expresses station-side demand or supply.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `marketOrderId`
|
||||
- `stationId` or `constructionSiteId`
|
||||
- `ownerFactionId`
|
||||
- `kind`
|
||||
- `itemId`
|
||||
- `amount`
|
||||
- `remainingAmount`
|
||||
- `valuation`
|
||||
- `reserveThreshold?`
|
||||
- `policy restrictions`
|
||||
- `state`
|
||||
|
||||
Recommended market order kinds:
|
||||
|
||||
- `buy`
|
||||
- `sell`
|
||||
|
||||
Recommended market order states:
|
||||
|
||||
- `open`
|
||||
- `partially-filled`
|
||||
- `filled`
|
||||
- `cancelled`
|
||||
- `expired later`
|
||||
|
||||
## Recipe
|
||||
|
||||
A recipe defines a conversion from inputs to outputs.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `recipeId`
|
||||
- `label`
|
||||
- `inputItems`
|
||||
- `outputItems`
|
||||
- `cycleTime`
|
||||
- `validModuleCategories`
|
||||
- `powerRequirement?`
|
||||
- `workforceModifier?`
|
||||
|
||||
## PolicySet
|
||||
|
||||
A policy set defines access and restriction rules.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `policySetId`
|
||||
- `ownerKind`
|
||||
- `ownerId`
|
||||
- `tradeAccessPolicy`
|
||||
- `dockingAccessPolicy`
|
||||
- `constructionAccessPolicy`
|
||||
- `operationalRangePolicy`
|
||||
- `hostility rules later`
|
||||
|
||||
Recommended owner kinds:
|
||||
|
||||
- `faction`
|
||||
- `station`
|
||||
- `commander`
|
||||
- `ship`
|
||||
|
||||
## Spatial State
|
||||
|
||||
Ships should not be modeled with only one generic position and target.
|
||||
|
||||
Recommended ship spatial state fields:
|
||||
|
||||
- `spaceLayer`
|
||||
- `currentSystemId`
|
||||
- `currentNodeId?`
|
||||
- `currentBubbleId?`
|
||||
- `localPosition?`
|
||||
- `systemPosition?`
|
||||
- `movementRegime`
|
||||
- `destinationNodeId?`
|
||||
- `transitState?`
|
||||
|
||||
Recommended space layers:
|
||||
|
||||
- `universe-space`
|
||||
- `galaxy-space`
|
||||
- `system-space`
|
||||
- `local-space`
|
||||
|
||||
Recommended movement regimes:
|
||||
|
||||
- `local-flight`
|
||||
- `warp`
|
||||
- `stargate-transit`
|
||||
- `ftl-transit`
|
||||
|
||||
## Population State
|
||||
|
||||
Population should remain explicit rather than hidden in generic inventory only.
|
||||
|
||||
Suggested station-side workforce fields:
|
||||
|
||||
- `population`
|
||||
- `populationCapacity`
|
||||
- `workforceRequired`
|
||||
- `workforceEffectiveRatio`
|
||||
- `workerConsumptionRates`
|
||||
|
||||
Commanders should not be ordinary cargo items even if they are population-derived.
|
||||
|
||||
## Power State
|
||||
|
||||
Ships and stations both need explicit operational power state.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `fuelInventory`
|
||||
- `energyStored`
|
||||
- `powerOperational`
|
||||
- `powerDeficitReason?`
|
||||
|
||||
This matters because no fuel leads to no power, and no power halts major operations.
|
||||
|
||||
## Inventories
|
||||
|
||||
Inventories should remain generic item maps, but hosts should also have explicit context.
|
||||
|
||||
Recommended inventory host kinds:
|
||||
|
||||
- `ship`
|
||||
- `station`
|
||||
- `construction-site`
|
||||
|
||||
This prevents construction storage from being a special-case invisible system.
|
||||
|
||||
## Ownership vs Access
|
||||
|
||||
The model should separate:
|
||||
|
||||
- ownership
|
||||
- commander control
|
||||
- policy-based access
|
||||
- current occupancy
|
||||
|
||||
These are not the same thing.
|
||||
|
||||
Examples:
|
||||
|
||||
- a faction owns a station
|
||||
- a station commander operates it
|
||||
- another faction may be allowed to trade there
|
||||
- multiple factions may be present in the same system
|
||||
|
||||
## Minimum Enums
|
||||
|
||||
The following enum families should exist somewhere in the model:
|
||||
|
||||
- `SpaceLayer`
|
||||
- `MovementRegime`
|
||||
- `NodeKind`
|
||||
- `CommanderKind`
|
||||
- `ModuleCategory`
|
||||
- `MarketOrderKind`
|
||||
- `MarketOrderState`
|
||||
- `ClaimState`
|
||||
- `ConstructionTargetKind`
|
||||
- `TradeAccessPolicy`
|
||||
- `DockingAccessPolicy`
|
||||
- `OrderState`
|
||||
- `TaskState`
|
||||
- `TaskKind`
|
||||
|
||||
## Replication Implication
|
||||
|
||||
This entity model is also intended to support replication.
|
||||
|
||||
That means entity shape should make it easy to stream:
|
||||
|
||||
- strategic summaries from higher layers
|
||||
- detailed updates from lower layers
|
||||
- explicit lifecycle changes
|
||||
- explicit claim, market, and construction updates
|
||||
|
||||
See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the typed event layer built on top of this model.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- important world concepts should have explicit records
|
||||
- ships need explicit spatial state
|
||||
- claims and construction sites are real entities
|
||||
- market orders are real entities
|
||||
- modules are real instances attached to hosts
|
||||
- policy is separate from ownership
|
||||
- population is explicit at the station level
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- defines the layered world structure
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- defines commander roles and hierarchy
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines market behavior
|
||||
|
||||
- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
|
||||
- defines capability-bearing module instances
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- defines population and commander generation
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- defines the policy sets attached to entities
|
||||
|
||||
- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
|
||||
- defines the execution-layer fields that entities should carry
|
||||
Reference in New Issue
Block a user