space-game/apps/viewer/src/contracts.ts

export interface WorldSnapshot {
  label: string;
  seed: number;
  sequence: number;
  tickIntervalMs: number;
  generatedAtUtc: string;
  systems: SystemSnapshot[];
  spatialNodes: SpatialNodeSnapshot[];
  localBubbles: LocalBubbleSnapshot[];
  nodes: ResourceNodeSnapshot[];
  stations: StationSnapshot[];
  claims: ClaimSnapshot[];
  constructionSites: ConstructionSiteSnapshot[];
  marketOrders: MarketOrderSnapshot[];
  policies: PolicySetSnapshot[];
  ships: ShipSnapshot[];
  factions: FactionSnapshot[];
}

export interface WorldDelta {
  sequence: number;
  tickIntervalMs: number;
  generatedAtUtc: string;
  requiresSnapshotRefresh: boolean;
  events: SimulationEventRecord[];
  spatialNodes: SpatialNodeDelta[];
  localBubbles: LocalBubbleDelta[];
  nodes: ResourceNodeDelta[];
  stations: StationDelta[];
  claims: ClaimDelta[];
  constructionSites: ConstructionSiteDelta[];
  marketOrders: MarketOrderDelta[];
  policies: PolicySetDelta[];
  ships: ShipDelta[];
  factions: FactionDelta[];
  scope?: ObserverScope | null;
}

export interface SimulationEventRecord {
  entityKind: string;
  entityId: string;
  kind: string;
  message: string;
  occurredAtUtc: string;
  family?: string;
  scopeKind?: string;
  scopeEntityId?: string | null;
  visibility?: string;
}

export interface ObserverScope {
  scopeKind: string;
  systemId?: string | null;
  bubbleId?: string | null;
}

export interface Vector3Dto {
  x: number;
  y: number;
  z: number;
}

export interface SystemSnapshot {
  id: string;
  label: string;
  galaxyPosition: Vector3Dto;
  starKind: string;
  starCount: number;
  starColor: string;
  starSize: number;
  planets: PlanetSnapshot[];
}

export interface PlanetSnapshot {
  label: string;
  planetType: string;
  shape: string;
  moonCount: number;
  orbitRadius: number;
  orbitSpeed: number;
  orbitEccentricity: number;
  orbitInclination: number;
  orbitLongitudeOfAscendingNode: number;
  orbitArgumentOfPeriapsis: number;
  orbitPhaseAtEpoch: number;
  size: number;
  color: string;
  hasRing: boolean;
}

export interface ResourceNodeSnapshot {
  id: string;
  systemId: string;
  localPosition: Vector3Dto;
  sourceKind: string;
  oreRemaining: number;
  maxOre: number;
  itemId: string;
}

export interface ResourceNodeDelta extends ResourceNodeSnapshot {}

export interface SpatialNodeSnapshot {
  id: string;
  systemId: string;
  kind: string;
  localPosition: Vector3Dto;
  bubbleId: string;
  parentNodeId?: string | null;
  occupyingStructureId?: string | null;
  orbitReferenceId?: string | null;
}

export interface SpatialNodeDelta extends SpatialNodeSnapshot {}

export interface LocalBubbleSnapshot {
  id: string;
  nodeId: string;
  systemId: string;
  radius: number;
  occupantShipIds: string[];
  occupantStationIds: string[];
  occupantClaimIds: string[];
  occupantConstructionSiteIds: string[];
}

export interface LocalBubbleDelta extends LocalBubbleSnapshot {}

export interface InventoryEntry {
  itemId: string;
  amount: number;
}

export interface StationSnapshot {
  id: string;
  label: string;
  category: string;
  systemId: string;
  localPosition: Vector3Dto;
  nodeId?: string | null;
  bubbleId?: string | null;
  anchorNodeId?: string | null;
  color: string;
  dockedShips: number;
  dockingPads: number;
  energyStored: number;
  inventory: InventoryEntry[];
  factionId: string;
  commanderId?: string | null;
  policySetId?: string | null;
  population: number;
  populationCapacity: number;
  workforceRequired: number;
  workforceEffectiveRatio: number;
  installedModules: string[];
  marketOrderIds: string[];
}

export interface StationDelta extends StationSnapshot {}

export interface ClaimSnapshot {
  id: string;
  factionId: string;
  systemId: string;
  nodeId: string;
  bubbleId: string;
  state: string;
  health: number;
  placedAtUtc: string;
  activatesAtUtc: string;
}

export interface ClaimDelta extends ClaimSnapshot {}

export interface ConstructionSiteSnapshot {
  id: string;
  factionId: string;
  systemId: string;
  nodeId: string;
  bubbleId: string;
  targetKind: string;
  targetDefinitionId: string;
  blueprintId?: string | null;
  claimId?: string | null;
  stationId?: string | null;
  state: string;
  progress: number;
  inventory: InventoryEntry[];
  requiredItems: InventoryEntry[];
  deliveredItems: InventoryEntry[];
  assignedConstructorShipIds: string[];
  marketOrderIds: string[];
}

export interface ConstructionSiteDelta extends ConstructionSiteSnapshot {}

export interface MarketOrderSnapshot {
  id: string;
  factionId: string;
  stationId?: string | null;
  constructionSiteId?: string | null;
  kind: string;
  itemId: string;
  amount: number;
  remainingAmount: number;
  valuation: number;
  reserveThreshold?: number | null;
  policySetId?: string | null;
  state: string;
}

export interface MarketOrderDelta extends MarketOrderSnapshot {}

export interface PolicySetSnapshot {
  id: string;
  ownerKind: string;
  ownerId: string;
  tradeAccessPolicy: string;
  dockingAccessPolicy: string;
  constructionAccessPolicy: string;
  operationalRangePolicy: string;
}

export interface PolicySetDelta extends PolicySetSnapshot {}

export interface ShipSnapshot {
  id: string;
  label: string;
  role: string;
  shipClass: string;
  systemId: string;
  localPosition: Vector3Dto;
  localVelocity: Vector3Dto;
  targetLocalPosition: Vector3Dto;
  state: string;
  orderKind: string | null;
  defaultBehaviorKind: string;
  controllerTaskKind: string;
  nodeId?: string | null;
  bubbleId?: string | null;
  dockedStationId?: string | null;
  commanderId?: string | null;
  policySetId?: string | null;
  cargoCapacity: number;
  workerPopulation: number;
  energyStored: number;
  inventory: InventoryEntry[];
  factionId: string;
  health: number;
  history: string[];
  spatialState: ShipSpatialStateSnapshot;
}

export interface ShipDelta extends ShipSnapshot {}

export interface ShipSpatialStateSnapshot {
  spaceLayer: string;
  currentSystemId: string;
  currentNodeId?: string | null;
  currentBubbleId?: string | null;
  localPosition?: Vector3Dto | null;
  systemPosition?: Vector3Dto | null;
  movementRegime: string;
  destinationNodeId?: string | null;
  transit?: ShipTransitSnapshot | null;
}

export interface ShipTransitSnapshot {
  regime: string;
  originNodeId?: string | null;
  destinationNodeId?: string | null;
  startedAtUtc?: string | null;
  arrivalDueAtUtc?: string | null;
  progress: number;
}

export interface FactionSnapshot {
  id: string;
  label: string;
  color: string;
  credits: number;
  populationTotal: number;
  oreMined: number;
  goodsProduced: number;
  shipsBuilt: number;
  shipsLost: number;
  defaultPolicySetId?: string | null;
}

export interface FactionDelta extends FactionSnapshot {}