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.

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