space-game/docs/DESIGN.md

Design Documents

This repository uses a small set of official design documents to define intended gameplay and simulation behavior.

These documents are design-first. They describe target structure and rules, not temporary implementation status.

For the implementation migration path from the current codebase to this design set, see ROADMAP.md.

Core Documents

• UNIVERSE-MODEL.md

  • canonical world structure
  • galaxy, systems, celestials, anchors, and localspaces
  • ship and construction placement
  • intra-system warp and inter-system FTL
  • viewer hierarchy and simulation boundaries

• COMMANDERS.md

  • commander roles for factions, stations, and ships
  • command hierarchy
  • orders, doctrine, and delegation
  • minimum autonomy rules

• ECONOMY.md

  • market-driven simulation
  • buy and sell orders
  • station market behavior
  • logistics and production incentives

• ITEMS.md

  • item categories
  • life-support goods
  • construction goods
  • population-related units

• WORKFORCE.md

  • population
  • habitats
  • workforce efficiency
  • worker transport
  • commander generation

• MODULES.md

  • ship and station module categories
  • capability gating
  • workforce and power interaction
  • module-driven growth and specialization

• PRODUCTION.md

  • recipes and conversion logic
  • module-driven processing
  • throughput and queues
  • construction as production

• POLICIES.md

  • trade and docking permissions
  • construction access
  • territorial and regional restrictions
  • policy-based behavior limits

• COMBAT.md

  • localspace combat
  • piracy and station defense
  • claim destruction and contest
  • commander-driven engagement behavior

• DATA-MODEL.md

  • core entities and IDs
  • major enums
  • runtime fields implied by the design
  • replication-friendly entity vocabulary

• EVENTS.md

  • typed world events
  • lifecycle and replication visibility
  • market, construction, and combat event families
  • human-readable summaries for logs and UI

• TASKS.md

  • goals, orders, behaviors, tasks, and states
  • planner precedence
  • executable ship and station work
  • safety and policy-aware tasking

• SHIPS.md

  • ship roles
  • movement capabilities
  • onboard command requirements
  • ship behavior expectations

• STATIONS.md

  • station roles
  • localspace functions
  • station command requirements
  • station services, docking, and market responsibilities

Document Rules

These documents should aim to:

• define durable game concepts
• avoid temporary work logs
• avoid implementation changelists
• avoid short-lived task lists
• reference each other where concepts overlap

If a note is only about current runtime state, active experiments, or a one-off migration, it should not live in the official design set.