space-game/docs/DATA-MODEL.md

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 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

  • defines the layered world structure

• COMMANDERS.md

  • defines commander roles and hierarchy

• ECONOMY.md

  • defines market behavior

• MODULES.md

  • defines capability-bearing module instances

• WORKFORCE.md

  • defines population and commander generation

• POLICIES.md

  • defines the policy sets attached to entities

• TASKS.md

  • defines the execution-layer fields that entities should carry