jbourdon/space-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fdcf83ccecf433fd336dac70b220a6e1fa2bc3b8
space-game/docs/DATA-MODEL.md

8.9 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink