485 lines
8.9 KiB
Markdown
485 lines
8.9 KiB
Markdown
# 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
|
|
- localspace 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`
|
|
- `anchorId`
|
|
- `localspaceId`
|
|
- `stationId`
|
|
- `shipId`
|
|
- `moduleId`
|
|
- `claimId`
|
|
- `orderId`
|
|
- `recipeId`
|
|
- `policyId`
|
|
- `marketOrderId`
|
|
- `constructionSiteId`
|
|
|
|
## Core Entity Set
|
|
|
|
The intended core entities are:
|
|
|
|
1. `Faction`
|
|
2. `Commander`
|
|
3. `System`
|
|
4. `Anchor`
|
|
5. `Localspace`
|
|
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`
|
|
- `task-group`
|
|
|
|
## System
|
|
|
|
A system is a strategic world entity in galaxy space.
|
|
|
|
Suggested fields:
|
|
|
|
- `systemId`
|
|
- `label`
|
|
- `galaxyPosition`
|
|
- `star definition`
|
|
- `nodeIds`
|
|
- `faction influence later`
|
|
|
|
## Anchor
|
|
|
|
An anchor is a meaningful location in a system that owns a localspace.
|
|
|
|
Suggested fields:
|
|
|
|
- `anchorId`
|
|
- `systemId`
|
|
- `kind`
|
|
- `systemPosition`
|
|
- `localspaceId`
|
|
- `parentAnchorId?`
|
|
- `orbital metadata?`
|
|
- `constructionIds?`
|
|
|
|
Recommended anchor kinds:
|
|
|
|
- `star`
|
|
- `planet`
|
|
- `moon`
|
|
- `lagrange-point`
|
|
- `resource-node`
|
|
|
|
## Localspace
|
|
|
|
A localspace is the tactical simulation context attached to one anchor.
|
|
|
|
Suggested fields:
|
|
|
|
- `localspaceId`
|
|
- `anchorId`
|
|
- `systemId`
|
|
- `radius`
|
|
- `occupantShipIds`
|
|
- `occupantStationIds`
|
|
- `occupantClaimIds`
|
|
- `occupantConstructionSiteIds`
|
|
- `serverAuthorityId later`
|
|
|
|
## Station
|
|
|
|
A station is a constructed structure that lives inside one localspace.
|
|
|
|
Suggested fields:
|
|
|
|
- `stationId`
|
|
- `ownerFactionId`
|
|
- `commanderId?`
|
|
- `anchorId`
|
|
- `systemId`
|
|
- `localspaceId`
|
|
- `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 valid construction anchor before construction.
|
|
|
|
Suggested fields:
|
|
|
|
- `claimId`
|
|
- `ownerFactionId`
|
|
- `commanderId?`
|
|
- `systemId`
|
|
- `anchorId`
|
|
- `localspaceId`
|
|
- `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`
|
|
- `anchorId`
|
|
- `localspaceId`
|
|
- `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`
|
|
- `currentAnchorId?`
|
|
- `currentLocalspaceId?`
|
|
- `localPosition?`
|
|
- `systemPosition?`
|
|
- `movementRegime`
|
|
- `destinationAnchorId?`
|
|
- `transitState?`
|
|
|
|
Recommended space layers:
|
|
|
|
- `universe-space`
|
|
- `galaxy-space`
|
|
- `system-space`
|
|
- `localspace`
|
|
|
|
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.
|
|
|
|
## 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
|
|
|
|
- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.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
|