docs: establish official design documentation
This commit is contained in:
229
docs/COMBAT.md
Normal file
229
docs/COMBAT.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# Combat
|
||||
|
||||
This document defines the intended combat model for the simulation.
|
||||
|
||||
Combat is primarily a local-space activity. It is how factions, pirates, and defenders contest access, claims, stations, and logistics.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The combat model should support:
|
||||
|
||||
- local-space tactical fights
|
||||
- piracy and harassment
|
||||
- claim destruction and station contestation
|
||||
- station defense
|
||||
- commander-driven engagement behavior
|
||||
- policy-aware hostility and access denial
|
||||
|
||||
## Core Principles
|
||||
|
||||
- combat happens in `local-space`
|
||||
- claims and structures are physically contestable
|
||||
- piracy should target valuable traffic and vulnerable infrastructure
|
||||
- stations should be defensible but not magically safe
|
||||
- combat behavior should come from commanders and policy, not only from raw proximity
|
||||
|
||||
## Combat Space
|
||||
|
||||
Combat belongs in `local-space`.
|
||||
|
||||
This is where entities can:
|
||||
|
||||
- maneuver with thrusters
|
||||
- approach targets
|
||||
- engage with weapons
|
||||
- defend stations and claims
|
||||
- intercept miners, haulers, and construction support
|
||||
|
||||
Ships in `system-space` warp transit are not in normal tactical combat.
|
||||
|
||||
This keeps tactical fighting distinct from travel.
|
||||
|
||||
## Combat Actors
|
||||
|
||||
The main combat actors are:
|
||||
|
||||
- combat ships
|
||||
- escorts
|
||||
- station defenses
|
||||
- pirates
|
||||
- claim objects
|
||||
- vulnerable civilian or industrial ships
|
||||
|
||||
Combat should matter not only for fleet battle, but also for logistics disruption and territorial contest.
|
||||
|
||||
## Claims As Combat Targets
|
||||
|
||||
Claims at Lagrange points should be valid combat targets.
|
||||
|
||||
That means:
|
||||
|
||||
- enemies may destroy a claim before it matures
|
||||
- pirates may harass or destroy claims
|
||||
- destroying a claim reopens the location for future contest
|
||||
|
||||
Claims should not be protected by abstract immunity.
|
||||
|
||||
They are real objects in the world.
|
||||
|
||||
## Construction As A Vulnerable Phase
|
||||
|
||||
Station founding and expansion should be dangerous.
|
||||
|
||||
Vulnerable targets include:
|
||||
|
||||
- claim objects
|
||||
- construction storage
|
||||
- constructor ships
|
||||
- supplying haulers
|
||||
|
||||
This makes station growth something that may require escort and local protection rather than being a purely economic background action.
|
||||
|
||||
## Station Defense
|
||||
|
||||
Stations should be able to defend themselves through modules and local defenders.
|
||||
|
||||
Station defense may come from:
|
||||
|
||||
- defense modules
|
||||
- docked or assigned defenders
|
||||
- nearby fleet response
|
||||
- friendly system presence
|
||||
|
||||
Station safety should depend on actual defensive capacity, not only ownership flags.
|
||||
|
||||
## Piracy
|
||||
|
||||
Pirates should be a meaningful local-space threat.
|
||||
|
||||
They should favor:
|
||||
|
||||
- industrial ships
|
||||
- haulers
|
||||
- construction traffic
|
||||
- station approaches
|
||||
- valuable logistics lanes
|
||||
|
||||
Piracy is especially important because it creates pressure on:
|
||||
|
||||
- escorts
|
||||
- trade profitability
|
||||
- claim security
|
||||
- station recovery
|
||||
|
||||
Pirates should not behave like generic random attackers if the game can instead make them economically disruptive predators.
|
||||
|
||||
## Hostility And Access
|
||||
|
||||
Combat should interact with policy and diplomacy, but not be replaced by them.
|
||||
|
||||
Examples:
|
||||
|
||||
- a hostile faction may be denied docking and attacked on approach
|
||||
- a neutral faction may be tolerated in-system but not allowed to build
|
||||
- pirates may ignore policy altogether and simply attack vulnerable targets
|
||||
|
||||
See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for the access side of this relationship.
|
||||
|
||||
## Commander Role In Combat
|
||||
|
||||
Commanders should determine combat behavior.
|
||||
|
||||
Examples:
|
||||
|
||||
- faction commanders set threat posture
|
||||
- station commanders request local defense
|
||||
- ship commanders choose whether to attack, escort, retreat, or hold
|
||||
|
||||
Combat should therefore depend on:
|
||||
|
||||
- commander doctrine
|
||||
- assigned role
|
||||
- local threat level
|
||||
- policy and hostility state
|
||||
|
||||
This is better than a purely reflexive “closest target” model.
|
||||
|
||||
## Engagement Rules
|
||||
|
||||
Commanders should eventually carry engagement rules such as:
|
||||
|
||||
- attack hostiles on sight
|
||||
- defend only if attacked
|
||||
- prioritize claims and stations
|
||||
- prioritize civilian protection
|
||||
- avoid battle unless escorted
|
||||
|
||||
These rules can begin simple, but they are important for faction identity.
|
||||
|
||||
## Civilian And Industrial Vulnerability
|
||||
|
||||
Non-combat ships should not be expected to behave like warships.
|
||||
|
||||
Industrial or civilian commanders should prefer:
|
||||
|
||||
- fleeing
|
||||
- docking
|
||||
- requesting escort
|
||||
- rerouting
|
||||
- abandoning low-value trade under danger
|
||||
|
||||
This gives escorts and station defense real purpose.
|
||||
|
||||
## Claim And Station Contest
|
||||
|
||||
A system can be contested without full conquest mechanics.
|
||||
|
||||
Useful examples:
|
||||
|
||||
- destroy the enemy claim before activation
|
||||
- raid construction storage
|
||||
- kill the constructor ship
|
||||
- deny safe trade to a vulnerable station
|
||||
- force expensive escort commitments
|
||||
|
||||
This creates strategic conflict even before fully mature station warfare exists.
|
||||
|
||||
## Destruction And Recovery
|
||||
|
||||
Combat should create lasting economic consequences.
|
||||
|
||||
Examples:
|
||||
|
||||
- destroyed claims delay expansion
|
||||
- destroyed haulers create shortages
|
||||
- destroyed defenders weaken a system
|
||||
- damaged or powerless stations need recovery support
|
||||
|
||||
This is one of the main ways combat feeds back into the economy.
|
||||
|
||||
See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the combat and claim-related event families.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- combat is primarily a local-space activity
|
||||
- claims are destructible and contestable
|
||||
- station construction is a vulnerable phase
|
||||
- piracy should prefer valuable and vulnerable traffic
|
||||
- station defense depends on real assets
|
||||
- commander doctrine should influence combat behavior
|
||||
- combat outcomes should affect logistics and expansion
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- defines where combat is allowed
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- defines access and hostility context
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- defines who decides engagement behavior
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- defines vulnerable stations, claims, and local defense context
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines the economic consequences of combat disruption
|
||||
365
docs/COMMANDERS.md
Normal file
365
docs/COMMANDERS.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Commanders
|
||||
|
||||
This document defines commander entities and the command model for the simulation.
|
||||
|
||||
The core idea is that meaningful autonomous behavior comes from commanders. Ships, stations, and factions act through commanders rather than through ad hoc local logic alone.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The commander model should support:
|
||||
|
||||
- clear AI ownership of decisions
|
||||
- delegation across multiple scales
|
||||
- player override without destroying autonomy
|
||||
- market-aware economic behavior
|
||||
- station and ship behavior that remains coherent over time
|
||||
|
||||
## Core Principle
|
||||
|
||||
A ship without a commander cannot do much.
|
||||
|
||||
A station without a commander cannot do much.
|
||||
|
||||
A faction without a commander cannot coordinate its assets coherently.
|
||||
|
||||
Commanders are the AI actors that interpret goals, issue orders, react to conditions, and maintain doctrine.
|
||||
|
||||
Commander availability should ultimately depend on faction population as described in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
|
||||
|
||||
## Commander Levels
|
||||
|
||||
The intended command hierarchy has three primary levels:
|
||||
|
||||
1. `faction commander`
|
||||
2. `station commander`
|
||||
3. `ship commander`
|
||||
|
||||
Additional specialized commanders may exist later, such as:
|
||||
|
||||
- fleet commander
|
||||
- task-group commander
|
||||
- convoy commander
|
||||
- sector commander
|
||||
|
||||
## Commander Entity Model
|
||||
|
||||
Commanders should be first-class simulation entities.
|
||||
|
||||
At minimum, a commander should conceptually have:
|
||||
|
||||
- `commanderId`
|
||||
- `kind`
|
||||
- `ownerFactionId`
|
||||
- `parentCommanderId?`
|
||||
- `controlledEntityId?`
|
||||
- `doctrine`
|
||||
- `current goals`
|
||||
- `known constraints`
|
||||
- `subordinate commanders`
|
||||
|
||||
This matters because commanders are not just labels. They are the units of decision-making in the simulation.
|
||||
|
||||
Commander creation is population-backed rather than free.
|
||||
|
||||
See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the recommended commander entity shape.
|
||||
|
||||
## Faction Commander
|
||||
|
||||
The faction commander is the highest routine AI authority for a faction.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- define faction priorities
|
||||
- allocate strategic resources
|
||||
- establish expansion and defense goals
|
||||
- create or retire station and fleet objectives
|
||||
- respond to large-scale shortages, threats, and opportunities
|
||||
|
||||
The faction commander should reason mostly across `universe-space`, `galaxy-space`, and strategic `system-space`.
|
||||
|
||||
It should not micromanage every ship constantly.
|
||||
|
||||
Typical outputs:
|
||||
|
||||
- strategic priorities
|
||||
- economic policy
|
||||
- expansion goals
|
||||
- threat posture
|
||||
- standing doctrine for subordinate commanders
|
||||
|
||||
## Station Commander
|
||||
|
||||
Each station should have a station commander.
|
||||
|
||||
A station commander is the operational brain of a station.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- manage the station's local objectives
|
||||
- manage docking priorities
|
||||
- create and maintain buy orders
|
||||
- create and maintain sell orders
|
||||
- request logistics support
|
||||
- evaluate shortages and surpluses
|
||||
- assign local defense expectations
|
||||
- request construction, repair, and expansion work
|
||||
|
||||
A station without a commander may still exist physically, but it should have very limited behavior.
|
||||
|
||||
Without a station commander, a station should not be expected to:
|
||||
|
||||
- participate meaningfully in the market
|
||||
- coordinate logistics
|
||||
- react intelligently to shortages
|
||||
- manage production priorities
|
||||
|
||||
Typical outputs:
|
||||
|
||||
- buy orders
|
||||
- sell orders
|
||||
- dock priority rules
|
||||
- local logistics requests
|
||||
- local defense requests
|
||||
- module and expansion priorities
|
||||
|
||||
Important limitation:
|
||||
|
||||
- a station commander does not own ships
|
||||
|
||||
It is better to think of the station commander as publishing needs, priorities, and requests rather than directly possessing a private ship roster by definition.
|
||||
|
||||
Station construction does not require that a commander already be present on-site.
|
||||
|
||||
A higher-level actor such as a faction commander, another AI authority, or the player may force initial resource transfers and construction support before the station has its own commander.
|
||||
|
||||
## Ship Commander
|
||||
|
||||
Each ship should have a ship commander, even if that commander is extremely simple.
|
||||
|
||||
A ship commander is responsible for translating high-level intent into behavior.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- accept player or superior orders
|
||||
- maintain standing doctrine when idle
|
||||
- react to danger and safety rules
|
||||
- choose the next immediate task
|
||||
- handle travel and local action transitions
|
||||
|
||||
Ship commanders may adopt behaviors that tie them closely to a station, such as mining or hauling for a station, without making the station commander their owner in the strict sense.
|
||||
|
||||
A ship without a commander should be heavily limited.
|
||||
|
||||
At minimum, a commanderless ship should only be able to:
|
||||
|
||||
- remain idle
|
||||
- hold position
|
||||
- drift in a failsafe state
|
||||
- accept direct external control if explicitly ordered
|
||||
|
||||
It should not run meaningful autonomous loops.
|
||||
|
||||
Typical outputs:
|
||||
|
||||
- current destination node
|
||||
- local tactical task
|
||||
- retreat decision
|
||||
- docking/refuel intent
|
||||
- trade or delivery acceptance
|
||||
|
||||
## Commander Ownership
|
||||
|
||||
A commander may directly own:
|
||||
|
||||
- one faction
|
||||
- one station
|
||||
- one ship
|
||||
- a group of subordinate commanders
|
||||
|
||||
Command should be hierarchical rather than flat.
|
||||
|
||||
Examples:
|
||||
|
||||
- a faction commander owns station commanders
|
||||
- a station commander owns station-based ship commanders
|
||||
- a fleet commander owns combat ship commanders
|
||||
|
||||
Recommended ownership rule:
|
||||
|
||||
- one commander should have one clear controlling scope
|
||||
- delegation downward should be explicit
|
||||
- conflicts should resolve through hierarchy, not through independent competing AI
|
||||
|
||||
This means station command and ship command should remain distinct even when they cooperate heavily.
|
||||
|
||||
## Delegation Model
|
||||
|
||||
Commanders should not directly perform simulation actions. They should issue intent downward.
|
||||
|
||||
Recommended flow:
|
||||
|
||||
1. commander evaluates state
|
||||
2. commander selects priorities
|
||||
3. commander issues or updates orders
|
||||
4. ship or station control logic turns orders into executable tasks
|
||||
5. runtime state changes feed back into commander decisions
|
||||
|
||||
This preserves separation between:
|
||||
|
||||
- strategic intent
|
||||
- operational planning
|
||||
- physical execution
|
||||
|
||||
Recommended command chain:
|
||||
|
||||
1. faction commander sets strategic doctrine and priorities
|
||||
2. station or fleet commander translates those into local objectives
|
||||
3. ship commander turns local objectives into ship behavior
|
||||
4. runtime movement and action systems execute the current task
|
||||
|
||||
The deeper the layer, the shorter the planning horizon should be.
|
||||
|
||||
See [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) for the execution-layer model beneath commander intent.
|
||||
|
||||
## Player Interaction
|
||||
|
||||
Players should be able to override commanders without deleting the command structure.
|
||||
|
||||
Recommended rule:
|
||||
|
||||
- direct player orders temporarily preempt commander autonomy
|
||||
- once direct orders resolve, the unit resumes its commander-driven behavior
|
||||
|
||||
That allows:
|
||||
|
||||
- RTS-like intervention
|
||||
- long-lived autonomous play
|
||||
|
||||
Recommended override behavior:
|
||||
|
||||
- player orders override the local commander immediately
|
||||
- the superior command structure remains intact
|
||||
- after the player order completes, the ship or station returns to commander control
|
||||
|
||||
## Commander Doctrine
|
||||
|
||||
Commanders should carry doctrine, not just orders.
|
||||
|
||||
Examples:
|
||||
|
||||
- risk tolerance
|
||||
- engagement rules
|
||||
- reserve thresholds
|
||||
- trade policy
|
||||
- build policy
|
||||
- territorial preference
|
||||
- preferred supply sources
|
||||
|
||||
Doctrine is what lets two stations or factions behave differently even with similar assets.
|
||||
|
||||
Doctrine should exist at multiple levels:
|
||||
|
||||
- faction doctrine
|
||||
- station doctrine
|
||||
- fleet doctrine
|
||||
- ship doctrine
|
||||
|
||||
Lower-level doctrine should inherit from higher-level doctrine unless explicitly overridden.
|
||||
|
||||
See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for explicit access and restriction rules that doctrine can express.
|
||||
|
||||
Combat-specific doctrine and engagement behavior should be defined alongside the combat model in [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md).
|
||||
|
||||
## Market Responsibility
|
||||
|
||||
The market is not abstracted away from commanders.
|
||||
|
||||
Commanders are expected to participate in the economy.
|
||||
|
||||
In particular:
|
||||
|
||||
- station commanders create buy and sell orders
|
||||
- faction commanders shape economic policy
|
||||
- ship commanders execute logistics and trade work in response to those incentives
|
||||
|
||||
This is the main bridge between command AI and the market-driven simulation.
|
||||
|
||||
Recommended responsibility split:
|
||||
|
||||
- faction commander decides broad economic posture
|
||||
- station commander publishes concrete local market intent
|
||||
- ship commander accepts and executes logistics opportunities
|
||||
|
||||
This avoids putting the whole economy in one planner.
|
||||
|
||||
## Command And Market Loop
|
||||
|
||||
The intended loop is:
|
||||
|
||||
1. faction commander sets strategic priorities
|
||||
2. station commander evaluates inventory, production, and risk
|
||||
3. station commander updates buy and sell orders
|
||||
4. ship commanders or higher logistics commanders select work from those opportunities
|
||||
5. ships move goods through the spatial model
|
||||
6. resulting stock and price changes feed back into commander decisions
|
||||
|
||||
This loop should be a core backbone of the simulation.
|
||||
|
||||
## Minimum Autonomy By Commander Type
|
||||
|
||||
### Faction commander without subordinates
|
||||
|
||||
Can do little beyond preserve faction identity and global flags.
|
||||
|
||||
### Station without station commander
|
||||
|
||||
Should be limited to:
|
||||
|
||||
- passive existence
|
||||
- fixed service availability if any
|
||||
- emergency safety behavior only
|
||||
|
||||
It may still receive externally forced support, but it should not run a healthy autonomous economy on its own.
|
||||
|
||||
### Ship without ship commander
|
||||
|
||||
Should be limited to:
|
||||
|
||||
- idle
|
||||
- hold
|
||||
- explicit direct player order execution
|
||||
- emergency retreat or failsafe only
|
||||
|
||||
## Minimal Functional Rules
|
||||
|
||||
The following rules should remain true unless there is a deliberate exception:
|
||||
|
||||
- every active station should have a commander
|
||||
- every active ship should have a commander
|
||||
- every faction should have a commander
|
||||
- commanders issue intent; they do not replace physical simulation
|
||||
- direct player orders can override commanders temporarily
|
||||
- stations participate in the economy through commander-set market behavior
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- defines where action happens
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines how commanders express market participation
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- defines ship capabilities and behavior expectations
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- defines station roles and station-side responsibilities
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- defines population, worker growth, and commander generation
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- defines access rules and operational restrictions commanders can set
|
||||
|
||||
- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
|
||||
- defines how commanders apply threat posture and engagement behavior
|
||||
501
docs/DATA-MODEL.md
Normal file
501
docs/DATA-MODEL.md
Normal file
@@ -0,0 +1,501 @@
|
||||
# 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](/home/jbourdon/repos/space-game/docs/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](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- defines the layered world structure
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- defines commander roles and hierarchy
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines market behavior
|
||||
|
||||
- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
|
||||
- defines capability-bearing module instances
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- defines population and commander generation
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- defines the policy sets attached to entities
|
||||
|
||||
- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
|
||||
- defines the execution-layer fields that entities should carry
|
||||
108
docs/DESIGN.md
Normal file
108
docs/DESIGN.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# 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](/home/jbourdon/repos/space-game/docs/ROADMAP.md).
|
||||
|
||||
## Core Documents
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- spatial layers
|
||||
- nodes and local bubbles
|
||||
- movement regimes
|
||||
- viewer scale expectations
|
||||
- replication and interest management implications
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- commander roles for factions, stations, and ships
|
||||
- command hierarchy
|
||||
- orders, doctrine, and delegation
|
||||
- minimum autonomy rules
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- market-driven simulation
|
||||
- buy and sell orders
|
||||
- station market behavior
|
||||
- logistics and production incentives
|
||||
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
- item categories
|
||||
- life-support goods
|
||||
- construction goods
|
||||
- fuel-chain goods
|
||||
- population-related units
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- population
|
||||
- habitats
|
||||
- workforce efficiency
|
||||
- worker transport
|
||||
- commander generation
|
||||
|
||||
- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
|
||||
- ship and station module categories
|
||||
- capability gating
|
||||
- workforce and power interaction
|
||||
- module-driven growth and specialization
|
||||
|
||||
- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
|
||||
- recipes and conversion logic
|
||||
- module-driven processing
|
||||
- throughput and queues
|
||||
- construction as production
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- trade and docking permissions
|
||||
- construction access
|
||||
- territorial and regional restrictions
|
||||
- policy-based behavior limits
|
||||
|
||||
- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
|
||||
- local-space combat
|
||||
- piracy and station defense
|
||||
- claim destruction and contest
|
||||
- commander-driven engagement behavior
|
||||
|
||||
- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
|
||||
- core entities and IDs
|
||||
- major enums
|
||||
- runtime fields implied by the design
|
||||
- replication-friendly entity vocabulary
|
||||
|
||||
- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md)
|
||||
- typed world events
|
||||
- lifecycle and replication visibility
|
||||
- market, construction, and combat event families
|
||||
- human-readable summaries for logs and UI
|
||||
|
||||
- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
|
||||
- goals, orders, behaviors, tasks, and states
|
||||
- planner precedence
|
||||
- executable ship and station work
|
||||
- safety and policy-aware tasking
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- ship roles
|
||||
- movement capabilities
|
||||
- onboard command requirements
|
||||
- ship behavior expectations
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- station roles
|
||||
- local bubble 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.
|
||||
349
docs/ECONOMY.md
Normal file
349
docs/ECONOMY.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# Economy
|
||||
|
||||
This document defines the intended economic model for the simulation.
|
||||
|
||||
The economy should be market driven.
|
||||
|
||||
That means production, transport, shortages, and prices should emerge from station behavior, commander intent, and resource availability rather than from fixed scripted chains alone.
|
||||
|
||||
See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the intended entity vocabulary behind market orders, construction sites, and policy sets.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The economy should support:
|
||||
|
||||
- real shortages and surpluses
|
||||
- trade incentives
|
||||
- meaningful logistics
|
||||
- station specialization
|
||||
- commander-driven buy and sell behavior
|
||||
- faction growth constrained by market conditions
|
||||
- workforce support through life-support goods
|
||||
|
||||
See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the shared item vocabulary behind these flows.
|
||||
|
||||
## Core Principle
|
||||
|
||||
Stations participate in the economy by publishing market intent.
|
||||
|
||||
The primary mechanism is:
|
||||
|
||||
- buy orders
|
||||
- sell orders
|
||||
|
||||
These orders should be created and maintained by station commanders.
|
||||
|
||||
## Market Actors
|
||||
|
||||
The intended market actors are:
|
||||
|
||||
- stations
|
||||
- factions
|
||||
- ships acting on behalf of commanders
|
||||
|
||||
Stations are the main visible market nodes.
|
||||
|
||||
Factions shape policy and strategy.
|
||||
|
||||
Ships execute transport, procurement, and delivery.
|
||||
|
||||
For now, market exchange should be station-centric:
|
||||
|
||||
- ship-to-station trading is supported
|
||||
- ship-to-ship trading is out of scope for now
|
||||
|
||||
## Market Units
|
||||
|
||||
The economy should be expressed through explicit market units rather than vague station desires.
|
||||
|
||||
Recommended market units:
|
||||
|
||||
- `buy order`
|
||||
- `sell order`
|
||||
- `reservation`
|
||||
- `fulfilled trade`
|
||||
- `cancelled trade`
|
||||
|
||||
This gives the economy observable state and event history.
|
||||
|
||||
See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the market and trade event families that should represent this history.
|
||||
|
||||
## Buy Orders
|
||||
|
||||
A buy order expresses that a station wants to acquire a resource.
|
||||
|
||||
A buy order should include, conceptually:
|
||||
|
||||
- item
|
||||
- desired amount
|
||||
- price or valuation
|
||||
- minimum delivery size if needed
|
||||
- urgency or priority
|
||||
- optional sourcing restrictions
|
||||
|
||||
Buy orders let a station express:
|
||||
|
||||
- production input demand
|
||||
- fuel shortages
|
||||
- construction material shortages
|
||||
- military resupply needs
|
||||
|
||||
Construction storage for a planned station should be allowed to publish buy orders before the finished station is fully operational.
|
||||
|
||||
Recommended additional fields later:
|
||||
|
||||
- issuing station
|
||||
- expiry or review time
|
||||
- maximum acceptable route cost
|
||||
- whether partial fulfillment is acceptable
|
||||
|
||||
## Sell Orders
|
||||
|
||||
A sell order expresses that a station is willing to release a resource.
|
||||
|
||||
A sell order should include, conceptually:
|
||||
|
||||
- item
|
||||
- offered amount
|
||||
- price or valuation
|
||||
- reserve threshold
|
||||
- optional buyer restrictions
|
||||
|
||||
Sell orders let a station express:
|
||||
|
||||
- exportable surplus
|
||||
- intentional specialization
|
||||
- market-facing production
|
||||
|
||||
Recommended additional fields later:
|
||||
|
||||
- issuing station
|
||||
- reserve floor
|
||||
- preferred buyer class if needed
|
||||
- priority relative to internal faction demand
|
||||
|
||||
## Station Commander Market Role
|
||||
|
||||
The station commander is responsible for market participation.
|
||||
|
||||
The station commander should:
|
||||
|
||||
- observe stock levels
|
||||
- observe production demand
|
||||
- observe dock throughput and logistics health
|
||||
- set or adjust buy orders
|
||||
- set or adjust sell orders
|
||||
- choose production priorities
|
||||
- request support when shortages threaten station function
|
||||
|
||||
Without a station commander, a station should not act like a healthy market participant.
|
||||
|
||||
If the station has no fuel and therefore no power, it should not continue normal market operation.
|
||||
|
||||
However, there is an important exception during founding or emergency intervention:
|
||||
|
||||
- a higher actor may force transfers toward the station or construction site even without ordinary market behavior
|
||||
|
||||
Recommended review loop:
|
||||
|
||||
1. inspect current inventory
|
||||
2. inspect production queues or goals
|
||||
3. inspect incoming and outgoing reservations
|
||||
4. inspect fuel, defense, and construction reserves
|
||||
5. update buy orders
|
||||
6. update sell orders
|
||||
7. request logistics or strategic help if necessary
|
||||
|
||||
## Prices And Valuation
|
||||
|
||||
The design does not require a single global static price list.
|
||||
|
||||
It is better to think in terms of valuation driven by:
|
||||
|
||||
- local scarcity
|
||||
- strategic need
|
||||
- production usefulness
|
||||
- reserve thresholds
|
||||
- faction doctrine
|
||||
|
||||
This allows stations to value the same item differently at different times.
|
||||
|
||||
Recommended interpretation:
|
||||
|
||||
- prices are not only “market prices”
|
||||
- they are commander valuations
|
||||
- commander valuations can still produce a market when many actors interact
|
||||
|
||||
There should not be a mandatory fixed global baseline price underneath this system.
|
||||
|
||||
Traders should optimize for profit, not just headline sale price.
|
||||
|
||||
## Resource Flow
|
||||
|
||||
The intended economy should eventually support flows such as:
|
||||
|
||||
1. extract raw resources
|
||||
2. move them to useful stations
|
||||
3. refine or process them
|
||||
4. consume them for fuel, production, or expansion
|
||||
5. produce intermediate and advanced goods
|
||||
6. sell surpluses or acquire shortages through the market
|
||||
|
||||
The important design point is that each stage should create economic pressure for the next, not just scripted state transitions.
|
||||
|
||||
See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the conversion-side rules behind these flows.
|
||||
|
||||
## Logistics
|
||||
|
||||
Logistics should emerge from market demand, not only from hardcoded behavior loops.
|
||||
|
||||
Examples:
|
||||
|
||||
- a hauler sees a profitable sell-to-buy opportunity
|
||||
- a station commander requests urgent fuel delivery
|
||||
- a faction commander subsidizes strategic resource movement
|
||||
|
||||
This is a better long-term basis than one-off scripted “mine and deliver to this exact station” logic.
|
||||
|
||||
Traders should generally prefer the best reachable buy opportunity within their allowed operational range, subject to:
|
||||
|
||||
- travel time
|
||||
- fuel cost
|
||||
- risk
|
||||
- behavioral restrictions
|
||||
- territorial or regional limits
|
||||
|
||||
Recommended logistics sources of work:
|
||||
|
||||
- open buy orders
|
||||
- profitable route opportunities
|
||||
- commander-assigned emergency deliveries
|
||||
- faction-priority strategic transfers
|
||||
|
||||
Not every cargo move needs to be pure free-market behavior, but the market should be the baseline.
|
||||
|
||||
Behavior-restricted work should still exist.
|
||||
|
||||
Example:
|
||||
|
||||
- `mine-for-station` is a constrained behavior, not a different economic ontology
|
||||
|
||||
The ship still sells into the market structure, but with restrictions on where and for whom it will trade.
|
||||
|
||||
## Reservations And Commitments
|
||||
|
||||
The economy will work better if stations can reserve expected inventory changes.
|
||||
|
||||
Examples:
|
||||
|
||||
- incoming fuel is reserved for station power
|
||||
- outbound metals are reserved for a construction project
|
||||
- a hauler claims part of a sell order before pickup
|
||||
|
||||
Without reservations, the same goods are too easy to double-allocate.
|
||||
|
||||
Current design choice:
|
||||
|
||||
- first one to deliver wins
|
||||
|
||||
This means market competition can remain simple at first, even if fuller reservation logic is introduced later for other workflows.
|
||||
|
||||
## Market Visibility
|
||||
|
||||
Market intent should generally be open knowledge, subject to access rules.
|
||||
|
||||
The baseline assumption is that buy and sell orders are visible to authorized observers and usable as input for commander planning.
|
||||
|
||||
Worker support goods are economically important because workforce depends on them. See [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
|
||||
|
||||
Those support goods are defined as item roles in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md).
|
||||
|
||||
## Market And Space
|
||||
|
||||
The market should respect the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md).
|
||||
|
||||
Implications:
|
||||
|
||||
- stations are nodes with local bubbles
|
||||
- docking and transfer happen in local-space
|
||||
- in-system logistics move through warp between nodes
|
||||
- inter-system trade moves through stargates or FTL
|
||||
|
||||
Distance and travel friction should matter economically.
|
||||
|
||||
This means:
|
||||
|
||||
- a nearby station may be economically better than a richer but distant one
|
||||
- warp and dock congestion affect profitability
|
||||
- inter-system trade should be slower and riskier than local trade
|
||||
|
||||
Operational range restrictions should come from behavior and policy, not only from physics.
|
||||
|
||||
Examples:
|
||||
|
||||
- stay in-system
|
||||
- stay in-region
|
||||
- faction-only trade
|
||||
- station-serving behavior
|
||||
|
||||
See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for the policy layer behind these restrictions.
|
||||
|
||||
## Minimal Functional Rules
|
||||
|
||||
The following rules should remain true unless deliberately broken:
|
||||
|
||||
- stations express demand through buy orders
|
||||
- stations express surplus through sell orders
|
||||
- station commanders manage those orders
|
||||
- logistics ships respond to economic incentives, not only fixed scripts
|
||||
- shortages should propagate into visible gameplay effects
|
||||
- market state should influence production, travel, and expansion
|
||||
|
||||
## Minimum Viable Economic Loop
|
||||
|
||||
The smallest useful version of this system would be:
|
||||
|
||||
1. stations publish buy and sell orders
|
||||
2. station commanders update those orders from inventory thresholds
|
||||
3. logistics ships choose a station demand to satisfy
|
||||
4. cargo transfer creates reservations
|
||||
5. delivery fulfills reservations and updates inventory
|
||||
6. shortages and surpluses visibly change future orders
|
||||
|
||||
## Station Construction Demand
|
||||
|
||||
A planned station should generate economic demand before full completion.
|
||||
|
||||
The recommended mechanism is:
|
||||
|
||||
1. claim becomes active
|
||||
2. construction storage appears
|
||||
3. station design determines required build materials
|
||||
4. construction storage publishes buy orders for those materials
|
||||
5. deliveries accumulate
|
||||
6. constructor ships consume them into built progress
|
||||
|
||||
This lets station construction participate directly in the same economic model as ordinary station operation.
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- defines who owns market decisions
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- defines station roles and market participation
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- defines logistics and industrial ship roles
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- defines population demand and workforce consequences
|
||||
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
- defines the item categories moving through the market
|
||||
|
||||
- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
|
||||
- defines how goods are transformed into other goods over time
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- defines who may participate in trade and under what restrictions
|
||||
328
docs/EVENTS.md
Normal file
328
docs/EVENTS.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Events
|
||||
|
||||
This document defines the intended event model for the simulation.
|
||||
|
||||
Events are the explicit record of meaningful changes in the world.
|
||||
|
||||
They should support gameplay logic, debugging, UI presentation, replication, and future persistence.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The event model should support:
|
||||
|
||||
- clear lifecycle visibility
|
||||
- replayable and inspectable world changes
|
||||
- useful observer replication
|
||||
- commander and player feedback
|
||||
- debugging without relying on implicit state diffs only
|
||||
|
||||
## Core Principles
|
||||
|
||||
- important world changes should emit explicit events
|
||||
- events should reference stable entity IDs
|
||||
- events should be typed, not only free-form text
|
||||
- events should be useful for both machines and humans
|
||||
- event detail should vary by space layer and relevance
|
||||
|
||||
## Event Structure
|
||||
|
||||
Every event should conceptually have:
|
||||
|
||||
- `eventId`
|
||||
- `sequence`
|
||||
- `occurredAt`
|
||||
- `kind`
|
||||
- `spaceLayer`
|
||||
- `systemId?`
|
||||
- `bubbleId?`
|
||||
- `primaryEntityKind`
|
||||
- `primaryEntityId`
|
||||
- `relatedEntityIds`
|
||||
- `payload`
|
||||
- `humanSummary`
|
||||
|
||||
This preserves both programmatic utility and debug readability.
|
||||
|
||||
## Event Scope
|
||||
|
||||
Events should naturally inherit spatial scope from the world model.
|
||||
|
||||
Examples:
|
||||
|
||||
- universe-scale events belong to `universe-space`
|
||||
- strategic system events belong to `galaxy-space` or `system-space`
|
||||
- combat, docking, and claims belong to `local-space`
|
||||
|
||||
This is important for interest management.
|
||||
|
||||
## Event Families
|
||||
|
||||
The major event families should be:
|
||||
|
||||
1. lifecycle events
|
||||
2. movement events
|
||||
3. market events
|
||||
4. production events
|
||||
5. construction events
|
||||
6. population events
|
||||
7. policy events
|
||||
8. combat events
|
||||
9. commander events
|
||||
10. replication/system events
|
||||
|
||||
## Lifecycle Events
|
||||
|
||||
These describe entity creation, destruction, and state milestones.
|
||||
|
||||
Examples:
|
||||
|
||||
- `ship-created`
|
||||
- `ship-destroyed`
|
||||
- `station-founded`
|
||||
- `station-destroyed`
|
||||
- `claim-placed`
|
||||
- `claim-destroyed`
|
||||
- `construction-started`
|
||||
- `construction-completed`
|
||||
- `commander-created`
|
||||
- `commander-killed`
|
||||
|
||||
These are especially important because entity lifecycles should not be inferred only from snapshots.
|
||||
|
||||
## Movement Events
|
||||
|
||||
These describe meaningful transitions in movement regime or location context.
|
||||
|
||||
Examples:
|
||||
|
||||
- `entered-local-bubble`
|
||||
- `left-local-bubble`
|
||||
- `warp-spooling-started`
|
||||
- `warp-started`
|
||||
- `warp-arrived`
|
||||
- `stargate-transit-started`
|
||||
- `ftl-transit-started`
|
||||
- `dock-requested`
|
||||
- `dock-granted`
|
||||
- `dock-denied`
|
||||
- `docked`
|
||||
- `undocked`
|
||||
|
||||
Movement events should capture transitions, not every tiny positional change.
|
||||
|
||||
## Market Events
|
||||
|
||||
These describe market intent and fulfillment.
|
||||
|
||||
Examples:
|
||||
|
||||
- `buy-order-opened`
|
||||
- `buy-order-updated`
|
||||
- `buy-order-filled`
|
||||
- `buy-order-cancelled`
|
||||
- `sell-order-opened`
|
||||
- `sell-order-updated`
|
||||
- `sell-order-filled`
|
||||
- `sell-order-cancelled`
|
||||
- `trade-delivered`
|
||||
- `trade-rejected`
|
||||
|
||||
These events are useful for:
|
||||
|
||||
- economic debugging
|
||||
- UI history
|
||||
- future analytics
|
||||
|
||||
## Production Events
|
||||
|
||||
These describe recipe and processing state.
|
||||
|
||||
Examples:
|
||||
|
||||
- `recipe-started`
|
||||
- `recipe-blocked-no-input`
|
||||
- `recipe-blocked-no-power`
|
||||
- `recipe-completed`
|
||||
- `production-stalled-output-full`
|
||||
|
||||
Production events should explain why stations are or are not producing.
|
||||
|
||||
## Construction Events
|
||||
|
||||
These describe founding, module expansion, and build progress.
|
||||
|
||||
Examples:
|
||||
|
||||
- `claim-activation-started`
|
||||
- `claim-activated`
|
||||
- `construction-storage-created`
|
||||
- `construction-material-delivered`
|
||||
- `construction-progressed`
|
||||
- `module-construction-started`
|
||||
- `module-construction-completed`
|
||||
- `station-construction-completed`
|
||||
|
||||
Construction events are especially important because claims and building are contestable.
|
||||
|
||||
## Population Events
|
||||
|
||||
These describe demographic and workforce changes.
|
||||
|
||||
Examples:
|
||||
|
||||
- `population-grew`
|
||||
- `population-transferred`
|
||||
- `population-arrived`
|
||||
- `population-loss-food`
|
||||
- `population-loss-water`
|
||||
- `population-loss-energy`
|
||||
- `commander-generated`
|
||||
|
||||
These help explain why a station's efficiency is changing.
|
||||
|
||||
## Policy Events
|
||||
|
||||
These describe access and restriction changes.
|
||||
|
||||
Examples:
|
||||
|
||||
- `trade-policy-changed`
|
||||
- `docking-policy-changed`
|
||||
- `construction-policy-changed`
|
||||
- `range-policy-changed`
|
||||
|
||||
These are useful because policy changes alter behavior without directly changing physical state.
|
||||
|
||||
## Combat Events
|
||||
|
||||
These describe tactical engagement and destruction.
|
||||
|
||||
Examples:
|
||||
|
||||
- `combat-started`
|
||||
- `target-acquired`
|
||||
- `under-attack`
|
||||
- `claim-attacked`
|
||||
- `construction-site-attacked`
|
||||
- `ship-damaged`
|
||||
- `ship-destroyed`
|
||||
- `station-damaged`
|
||||
- `station-defense-engaged`
|
||||
- `pirate-raid-detected`
|
||||
- `retreat-started`
|
||||
|
||||
Combat events should favor meaningful state changes over weapon-by-weapon spam.
|
||||
|
||||
## Commander Events
|
||||
|
||||
These describe decision-level changes by AI authority.
|
||||
|
||||
Examples:
|
||||
|
||||
- `commander-created`
|
||||
- `commander-assigned`
|
||||
- `commander-killed`
|
||||
- `goal-changed`
|
||||
- `doctrine-changed`
|
||||
- `priority-changed`
|
||||
- `support-requested`
|
||||
|
||||
These make it easier to understand why entities changed behavior.
|
||||
|
||||
Task and order transition events should also exist as a first-class part of the event model.
|
||||
|
||||
Examples:
|
||||
|
||||
- `order-accepted`
|
||||
- `order-cancelled`
|
||||
- `task-started`
|
||||
- `task-blocked`
|
||||
- `task-completed`
|
||||
- `task-failed`
|
||||
- `behavior-changed`
|
||||
|
||||
See [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) for the planner and execution model behind these transitions.
|
||||
|
||||
## Replication And System Events
|
||||
|
||||
These describe transport-level or observer-level system changes.
|
||||
|
||||
Examples:
|
||||
|
||||
- `snapshot-issued`
|
||||
- `delta-issued`
|
||||
- `observer-scope-changed`
|
||||
- `requires-refresh`
|
||||
|
||||
These may remain more internal than gameplay-facing, but they still benefit from consistent typing.
|
||||
|
||||
## Event Visibility
|
||||
|
||||
Not every observer needs every event.
|
||||
|
||||
The intended rule should be:
|
||||
|
||||
- high-layer events are broad and low-detail
|
||||
- low-layer events are narrow and high-detail
|
||||
|
||||
Examples:
|
||||
|
||||
- a local viewer should see nearby combat and docking events
|
||||
- a system viewer should see claim and station progress events
|
||||
- a galaxy viewer may only need summarized strategic events
|
||||
|
||||
## Event Retention
|
||||
|
||||
The runtime may not keep full history forever, but events should still be designed as if they are useful beyond one frame.
|
||||
|
||||
Useful retention targets:
|
||||
|
||||
- short-term debug history
|
||||
- player-facing notifications
|
||||
- recent replication catch-up
|
||||
- future persistence or replay systems
|
||||
|
||||
## Human Summary
|
||||
|
||||
Every event should be capable of producing a concise human-readable summary.
|
||||
|
||||
Example style:
|
||||
|
||||
- `Claim at Helios IV L4 destroyed by pirates`
|
||||
- `Station buy order for fuel opened`
|
||||
- `Miner completed warp to refinery node`
|
||||
|
||||
This helps reuse the same event model for:
|
||||
|
||||
- logs
|
||||
- notifications
|
||||
- debug panels
|
||||
- event history UI
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- important world changes emit typed events
|
||||
- events reference stable entity IDs
|
||||
- events carry enough scope for interest management
|
||||
- events should support both machine use and human summaries
|
||||
- lifecycle events should not rely only on snapshot inference
|
||||
- local combat and construction conflict should be explicitly represented
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
|
||||
- defines the entities referenced by events
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- defines event scope by space layer
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines market and trade-related event domains
|
||||
|
||||
- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
|
||||
- defines recipe and production event domains
|
||||
|
||||
- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
|
||||
- defines combat and claim-related event domains
|
||||
227
docs/ITEMS.md
Normal file
227
docs/ITEMS.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# Items
|
||||
|
||||
This document defines the intended item vocabulary for the simulation.
|
||||
|
||||
Items are the goods that move through the economy, sustain population, enable construction, and support logistics.
|
||||
|
||||
The goal of this document is not to lock every final item name immediately. It is to define the categories and roles that the economy depends on.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The item model should support:
|
||||
|
||||
- market-driven trade
|
||||
- construction demand
|
||||
- station operation
|
||||
- workforce support
|
||||
- transport specialization
|
||||
- future industrial depth without immediate overcomplication
|
||||
|
||||
## Core Principles
|
||||
|
||||
- items should have clear economic purpose
|
||||
- items should belong to recognizable categories
|
||||
- population needs should be represented with real goods
|
||||
- station construction should consume real goods
|
||||
- cargo specialization should matter where useful
|
||||
|
||||
## Major Item Categories
|
||||
|
||||
The intended categories are:
|
||||
|
||||
1. raw resources
|
||||
2. processed industrial goods
|
||||
3. life-support goods
|
||||
4. civilian goods
|
||||
5. fuel and power-chain goods
|
||||
6. construction goods
|
||||
7. population-related units
|
||||
8. special logistics goods later
|
||||
|
||||
## Raw Resources
|
||||
|
||||
These are extracted directly from the world or from near-direct processing.
|
||||
|
||||
Examples:
|
||||
|
||||
- ore
|
||||
- gas
|
||||
- water if treated as an extractable resource
|
||||
- biological feed inputs later if needed
|
||||
|
||||
Raw resources are the base of the production chain.
|
||||
|
||||
## Processed Industrial Goods
|
||||
|
||||
These are materials produced from raw resources and used for further production.
|
||||
|
||||
Examples:
|
||||
|
||||
- refined metals
|
||||
- structural materials
|
||||
- electronics later
|
||||
- machinery later
|
||||
|
||||
These goods should feed construction, station operation, and advanced industry.
|
||||
|
||||
## Life-Support Goods
|
||||
|
||||
These are required to sustain population.
|
||||
|
||||
Core life-support goods:
|
||||
|
||||
- food
|
||||
- water
|
||||
- energy
|
||||
|
||||
These are not optional luxuries. They are fundamental operating requirements for workforce survival.
|
||||
|
||||
## Civilian Goods
|
||||
|
||||
These are goods consumed by population beyond pure survival.
|
||||
|
||||
Current important example:
|
||||
|
||||
- consumer goods
|
||||
|
||||
These goods should matter for workforce health, quality of life, and possibly future growth modifiers.
|
||||
|
||||
## Fuel And Power-Chain Goods
|
||||
|
||||
These are the goods that keep ships and stations running.
|
||||
|
||||
Examples:
|
||||
|
||||
- gas as an energy-chain input
|
||||
- fuel as a refined operational good
|
||||
|
||||
The exact chain may evolve, but the important distinction is:
|
||||
|
||||
- some goods are energy inputs
|
||||
- some goods are operational fuels
|
||||
|
||||
## Construction Goods
|
||||
|
||||
These are the goods used to build stations and possibly ships.
|
||||
|
||||
Examples:
|
||||
|
||||
- station construction materials
|
||||
- ship construction materials
|
||||
- module construction materials
|
||||
|
||||
The exact item split can remain flexible for now, but construction should consume real goods rather than abstract progress only.
|
||||
|
||||
Construction storage at a station site should create demand for these goods through the normal market system.
|
||||
|
||||
## Population-Related Units
|
||||
|
||||
Population itself should be treated as a tracked resource, but not as an ordinary trade good in the same sense as metal or fuel.
|
||||
|
||||
Important distinctions:
|
||||
|
||||
- workers are population units
|
||||
- commanders are population-derived special units
|
||||
- workers can be transported
|
||||
- commanders are created from population over time
|
||||
|
||||
Population transport should remain controlled by workforce and ship rules rather than being treated as a trivial cargo commodity.
|
||||
|
||||
## Livestock And Food Loop
|
||||
|
||||
Livestock should exist as part of the food loop.
|
||||
|
||||
This implies:
|
||||
|
||||
- livestock is distinct from workers
|
||||
- livestock may require dedicated transport or handling rules later
|
||||
- livestock supports food production rather than station staffing
|
||||
|
||||
## Item Role Examples
|
||||
|
||||
The current design implies at least these roles:
|
||||
|
||||
- `ore`
|
||||
- raw industrial input
|
||||
|
||||
- `gas`
|
||||
- raw fuel-chain input
|
||||
|
||||
- `fuel`
|
||||
- operational energy good
|
||||
|
||||
- `food`
|
||||
- workforce life-support
|
||||
|
||||
- `water`
|
||||
- workforce life-support
|
||||
|
||||
- `consumer-goods`
|
||||
- workforce support / civilian demand
|
||||
|
||||
- `workers`
|
||||
- transported population units
|
||||
|
||||
- `construction-materials`
|
||||
- station and module building input
|
||||
|
||||
The final names can change, but the economic roles should stay stable.
|
||||
|
||||
## Storage And Compatibility
|
||||
|
||||
Not every item should necessarily fit in every hold type forever.
|
||||
|
||||
Useful distinctions later may include:
|
||||
|
||||
- bulk industrial cargo
|
||||
- liquid cargo
|
||||
- gas cargo
|
||||
- containerized finished goods
|
||||
- human transport capacity
|
||||
- livestock capacity
|
||||
|
||||
For now, the important rule is simply:
|
||||
|
||||
- item class should eventually matter for transport and storage design
|
||||
|
||||
## Market Behavior
|
||||
|
||||
Items should participate in the market according to their role.
|
||||
|
||||
Examples:
|
||||
|
||||
- life-support goods generate recurring demand
|
||||
- fuel goods generate operational demand
|
||||
- construction goods generate burst demand during expansion
|
||||
- industrial goods feed production chains
|
||||
- worker transport supports station staffing
|
||||
|
||||
This should help the economy create natural recurring and temporary market pressures.
|
||||
|
||||
## Item Importance To Other Systems
|
||||
|
||||
Items are the bridge between major game systems:
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- buy and sell orders are item-driven
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- population survival depends on specific goods
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- station construction and operation consume goods
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- ship transport depends on what kind of item is being moved
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- workforce depends on real support goods
|
||||
- station construction depends on real construction goods
|
||||
- fuel and industrial chains are item-based
|
||||
- workers are movable population units
|
||||
- commanders are not ordinary trade cargo
|
||||
- livestock is distinct from workers
|
||||
- item categories should eventually matter for storage and transport
|
||||
294
docs/MODULES.md
Normal file
294
docs/MODULES.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Modules
|
||||
|
||||
This document defines the intended module model for ships and stations.
|
||||
|
||||
Modules are the primary way ships and stations gain capability.
|
||||
|
||||
They determine what an entity can do, what goods it can handle, what services it can provide, and how much workforce or support it requires.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The module system should support:
|
||||
|
||||
- X4-style composable stations
|
||||
- role-defined ships without excessive hardcoding
|
||||
- meaningful logistics and infrastructure requirements
|
||||
- clear capability gating
|
||||
- future expansion without changing the basic architecture
|
||||
|
||||
## Core Principles
|
||||
|
||||
- ships and stations gain most capabilities through modules
|
||||
- modules should define function, not just stats
|
||||
- modules should have real operational requirements
|
||||
- modules should interact with workforce, items, and command logic
|
||||
- a hull or station frame without the right modules should be meaningfully limited
|
||||
|
||||
## Module Ownership
|
||||
|
||||
Modules belong to either:
|
||||
|
||||
- ships
|
||||
- stations
|
||||
|
||||
Some module categories conceptually exist on both, but their use may differ.
|
||||
|
||||
Examples:
|
||||
|
||||
- storage
|
||||
- habitat
|
||||
- power-related modules
|
||||
|
||||
## Capability Gating
|
||||
|
||||
Modules should gate real gameplay abilities.
|
||||
|
||||
Examples:
|
||||
|
||||
- no docking module means no docking service
|
||||
- no habitat module means no population growth or human transport
|
||||
- no refinery module means no refining
|
||||
- no fuel-processing module means no gas-to-fuel conversion
|
||||
- no storage module means reduced or absent inventory capability
|
||||
- no shipyard-related module means no ship production
|
||||
|
||||
This should remain a core rule of the simulation.
|
||||
|
||||
## Ship Modules
|
||||
|
||||
Ship modules define what a ship can do.
|
||||
|
||||
Likely ship-side categories include:
|
||||
|
||||
- reactor or power generation
|
||||
- capacitor or energy buffer
|
||||
- thruster package later if separated
|
||||
- warp-capable propulsion support later if needed
|
||||
- FTL capability where applicable
|
||||
- cargo storage
|
||||
- habitat for human transport
|
||||
- livestock transport
|
||||
- mining equipment
|
||||
- gas harvesting equipment
|
||||
- weapons
|
||||
- support or utility systems later
|
||||
|
||||
Ship identity should be influenced by:
|
||||
|
||||
- hull class
|
||||
- fitted modules
|
||||
- commander behavior
|
||||
|
||||
Not every industrial role needs a distinct hardcoded hull if modules can express the difference clearly enough.
|
||||
|
||||
## Station Modules
|
||||
|
||||
Station modules define what a station can do.
|
||||
|
||||
Likely station-side categories include:
|
||||
|
||||
- power generation
|
||||
- docking
|
||||
- storage
|
||||
- habitat
|
||||
- refinery
|
||||
- fuel processing
|
||||
- manufacturing
|
||||
- shipyard or construction support
|
||||
- defense
|
||||
- trade or logistics support later
|
||||
- livestock or food-chain support later
|
||||
|
||||
Station identity should largely come from module composition.
|
||||
|
||||
This is especially important because your station model is configuration-based rather than having every station type be a wholly separate structure class.
|
||||
|
||||
## Structural Rule
|
||||
|
||||
Stations are built at one Lagrange point and expanded by adding modules.
|
||||
|
||||
That means modules are the main axis of station growth.
|
||||
|
||||
A station does not sprawl across multiple sites.
|
||||
|
||||
## Module Categories
|
||||
|
||||
For design purposes, modules can be grouped into a few major classes:
|
||||
|
||||
1. structural modules
|
||||
2. operational modules
|
||||
3. production modules
|
||||
4. logistics modules
|
||||
5. population modules
|
||||
6. military modules
|
||||
|
||||
### Structural Modules
|
||||
|
||||
These define physical expansion and attachment capacity.
|
||||
|
||||
Examples:
|
||||
|
||||
- core station body
|
||||
- structural extensions
|
||||
- future hardpoint or attachment frames
|
||||
|
||||
### Operational Modules
|
||||
|
||||
These keep the entity functioning.
|
||||
|
||||
Examples:
|
||||
|
||||
- reactor
|
||||
- capacitor
|
||||
- station power core
|
||||
- fuel systems
|
||||
|
||||
### Production Modules
|
||||
|
||||
These convert goods into other goods or into built output.
|
||||
|
||||
Examples:
|
||||
|
||||
- refinery
|
||||
- fuel processor
|
||||
- factory
|
||||
- shipyard support
|
||||
|
||||
### Logistics Modules
|
||||
|
||||
These let an entity store, receive, and move goods or people.
|
||||
|
||||
Examples:
|
||||
|
||||
- cargo storage
|
||||
- docking bay
|
||||
- transfer systems later
|
||||
- habitat transport support
|
||||
- livestock handling
|
||||
|
||||
### Population Modules
|
||||
|
||||
These support humans and long-term station staffing.
|
||||
|
||||
Examples:
|
||||
|
||||
- habitat
|
||||
- civilian support modules later
|
||||
|
||||
Population modules are especially important because they connect stations to [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
|
||||
|
||||
### Military Modules
|
||||
|
||||
These allow defense and force projection.
|
||||
|
||||
Examples:
|
||||
|
||||
- turrets
|
||||
- missile systems later
|
||||
- shield or defensive utility later
|
||||
- station defense platforms as module sets
|
||||
|
||||
## Module Requirements
|
||||
|
||||
Modules should not be treated as free magic unlocks.
|
||||
|
||||
They may require:
|
||||
|
||||
- construction materials
|
||||
- build time
|
||||
- power
|
||||
- workforce
|
||||
- fuel or energy inputs
|
||||
- docking or logistics support
|
||||
|
||||
This should let stations and ships fail in believable ways when underbuilt or undersupplied.
|
||||
|
||||
## Workforce Interaction
|
||||
|
||||
Modules should interact with workforce through a simple rule at first:
|
||||
|
||||
- every module contributes to the station's workforce requirement
|
||||
- workforce satisfaction scales module effectiveness equally
|
||||
|
||||
That keeps the first model simple while preserving the idea that bigger stations need more people.
|
||||
|
||||
## Item Interaction
|
||||
|
||||
Modules should define which item flows an entity can participate in.
|
||||
|
||||
Examples:
|
||||
|
||||
- a habitat module enables population support
|
||||
- a fuel-processing module consumes gas and produces fuel
|
||||
- a refinery consumes raw resources and produces processed goods
|
||||
- a storage module determines what volume or class of goods can be held
|
||||
- a livestock module participates in the food chain
|
||||
|
||||
See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the item-side vocabulary.
|
||||
See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the recipe-side model.
|
||||
|
||||
## Construction And Module Demand
|
||||
|
||||
Module construction should use the same economic logic as station construction more broadly.
|
||||
|
||||
That means:
|
||||
|
||||
- module builds consume real goods
|
||||
- construction storage can publish demand
|
||||
- expansion creates burst economic pressure
|
||||
|
||||
This keeps station growth tied to the market rather than detached from it.
|
||||
|
||||
## Operational Failure
|
||||
|
||||
Modules should help determine failure modes.
|
||||
|
||||
Examples:
|
||||
|
||||
- no power means operational modules fail
|
||||
- no docking module means the station cannot offer docking service
|
||||
- no habitat means no local population growth
|
||||
- no storage means goods handling becomes impossible or severely constrained
|
||||
|
||||
This helps capability loss emerge from the world state instead of from arbitrary toggles.
|
||||
|
||||
## Fitting Philosophy
|
||||
|
||||
The intended philosophy should be:
|
||||
|
||||
- hulls and station frames define limits
|
||||
- modules define capabilities
|
||||
|
||||
That means the simulation should avoid making every role a unique special-case entity if a module composition can express it more cleanly.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- modules gate real capabilities
|
||||
- stations grow by module addition at one location
|
||||
- ships depend on fitted modules for specialized roles
|
||||
- modules consume real construction goods
|
||||
- modules interact with workforce and power
|
||||
- habitat modules are required for population support or human transport
|
||||
- storage and logistics modules matter for market participation
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- station growth and services
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- ship capabilities and specialization
|
||||
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
- goods consumed or enabled by modules
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- workforce and habitat interaction
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- market demand created by module construction and operation
|
||||
|
||||
- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
|
||||
- recipes executed by production-capable modules
|
||||
199
docs/POLICIES.md
Normal file
199
docs/POLICIES.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# Policies
|
||||
|
||||
This document defines policy rules for trade, docking, construction access, territorial behavior, and operational restrictions.
|
||||
|
||||
Policies are how commanders turn general strategy into concrete permissions and limits.
|
||||
|
||||
They sit between diplomacy, economy, space control, and ship behavior.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The policy model should support:
|
||||
|
||||
- policy-based market access
|
||||
- policy-based docking and service access
|
||||
- regional or system-limited ship behavior
|
||||
- construction rights at valuable locations
|
||||
- faction differentiation without changing core mechanics
|
||||
|
||||
## Core Principles
|
||||
|
||||
- policy should constrain behavior without replacing command AI
|
||||
- access should be explicit rather than assumed
|
||||
- policy can restrict market participation even when market data is visible
|
||||
- policy should operate at multiple levels
|
||||
- ships and stations should obey policy limits when selecting work
|
||||
|
||||
## Policy Levels
|
||||
|
||||
Policies should exist at multiple levels:
|
||||
|
||||
- faction policy
|
||||
- station policy
|
||||
- ship or commander behavior policy
|
||||
|
||||
Higher-level policy sets the default.
|
||||
|
||||
Lower-level policy may narrow or specialize it.
|
||||
|
||||
Examples:
|
||||
|
||||
- a faction allows trade with neutrals
|
||||
- one station is faction-only
|
||||
- one ship is restricted to a single system
|
||||
|
||||
## Trade Access Policy
|
||||
|
||||
Trade access determines who may participate in a station's market.
|
||||
|
||||
Possible policies include:
|
||||
|
||||
- open trade
|
||||
- faction-only trade
|
||||
- friendly-only trade
|
||||
- whitelist-based trade later
|
||||
- blacklist-based trade later
|
||||
|
||||
Important distinction:
|
||||
|
||||
- market information may be visible
|
||||
- actual participation may still be restricted by policy
|
||||
|
||||
This preserves your rule that station market intent is generally open knowledge while still allowing trade control.
|
||||
|
||||
## Docking Policy
|
||||
|
||||
Docking access should also be policy-controlled.
|
||||
|
||||
Possible policies include:
|
||||
|
||||
- open docking
|
||||
- faction-only docking
|
||||
- friendly-only docking
|
||||
- emergency-only docking later
|
||||
- denied docking for hostile factions
|
||||
|
||||
Docking policy matters because no trade or transfer can happen without actual local access.
|
||||
|
||||
## Construction Policy
|
||||
|
||||
Construction rights should be policy-relevant at the faction and system level.
|
||||
|
||||
This does not override the hard structural rule from [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md):
|
||||
|
||||
- one structure per Lagrange point
|
||||
|
||||
But it does help define who is permitted or tolerated to claim and build in a given system.
|
||||
|
||||
Examples:
|
||||
|
||||
- a faction allows allies to build in its system
|
||||
- a faction contests all foreign construction
|
||||
- piracy or warfare makes claims vulnerable regardless of nominal policy
|
||||
|
||||
## Operational Range Policy
|
||||
|
||||
Ships should be able to operate under geographic or territorial restrictions.
|
||||
|
||||
Examples:
|
||||
|
||||
- stay in local system
|
||||
- stay in assigned region
|
||||
- stay near assigned station
|
||||
- use only faction-controlled stations
|
||||
- avoid hostile territory
|
||||
|
||||
These restrictions should be expressible as policy and behavior, not only as one-off hardcoded AI.
|
||||
|
||||
## Behavior Restrictions
|
||||
|
||||
Policy should be able to constrain ship work selection.
|
||||
|
||||
Examples:
|
||||
|
||||
- a trader may only serve faction stations
|
||||
- a miner may only sell within one system
|
||||
- a hauler may ignore low-profit trades outside an assigned region
|
||||
- a station-serving ship may prioritize one station's needs even when broader market opportunities exist
|
||||
|
||||
This is how the simulation gets meaningful local identities and doctrines.
|
||||
|
||||
## Market Visibility vs Market Access
|
||||
|
||||
These should remain separate concepts.
|
||||
|
||||
Baseline design:
|
||||
|
||||
- station market intent is generally visible
|
||||
- actual buying, selling, docking, or transfer may still be restricted by policy
|
||||
|
||||
This is important because intelligence and permission are not the same thing.
|
||||
|
||||
## Policy And Commanders
|
||||
|
||||
Policies should be authored or maintained by commanders.
|
||||
|
||||
Recommended responsibility split:
|
||||
|
||||
- faction commander sets broad access and territorial doctrine
|
||||
- station commander sets station-specific access and market policy
|
||||
- ship commander applies local behavioral restrictions when choosing work
|
||||
|
||||
This keeps policy tied to decision-making rather than existing as disconnected static data.
|
||||
|
||||
## Policy And Diplomacy
|
||||
|
||||
Policy should eventually connect to faction relationships.
|
||||
|
||||
Examples:
|
||||
|
||||
- friendly factions may trade and dock
|
||||
- neutral factions may trade but not build
|
||||
- hostile factions may be denied docking and targeted in local-space
|
||||
|
||||
The exact diplomacy system can evolve later, but policy should be ready to consume those relationship states.
|
||||
|
||||
## Policy And Claims
|
||||
|
||||
Claim objects at Lagrange points are visible and contestable.
|
||||
|
||||
Policy influences:
|
||||
|
||||
- who may place claims without triggering hostility
|
||||
- who is tolerated in a system
|
||||
- who may receive peaceful access to build
|
||||
|
||||
But policy should not make claims magically invulnerable.
|
||||
|
||||
Claims remain physically contestable objects.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- trade access is policy-based
|
||||
- docking access is policy-based
|
||||
- behavior range restrictions are policy-capable
|
||||
- market visibility and market access are separate
|
||||
- station and faction commanders should be able to define access rules
|
||||
- policy constrains work selection without replacing command logic
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- commanders define and apply policy
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- policy constrains trade participation
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- policy interacts with claims, systems, and local access
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- station commanders apply local market and docking policy
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- ship behavior should obey operational restrictions
|
||||
|
||||
- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
|
||||
- policy interacts with hostility, defense, and contested access
|
||||
271
docs/PRODUCTION.md
Normal file
271
docs/PRODUCTION.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# Production
|
||||
|
||||
This document defines the intended production model for the simulation.
|
||||
|
||||
Production is how modules consume inputs over time and turn them into useful outputs.
|
||||
|
||||
It connects items, modules, workforce, and market behavior into a continuous economic loop.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The production model should support:
|
||||
|
||||
- clear input-to-output conversion
|
||||
- station specialization through module choice
|
||||
- real supply-chain pressure
|
||||
- visible bottlenecks
|
||||
- workforce-sensitive throughput
|
||||
- construction as part of the same economic logic
|
||||
|
||||
## Core Principles
|
||||
|
||||
- production should consume real goods
|
||||
- production should take time
|
||||
- production should depend on module capability
|
||||
- production should be affected by workforce and power state
|
||||
- shortages should halt or degrade output naturally
|
||||
|
||||
## Production Units
|
||||
|
||||
The core production concepts should be:
|
||||
|
||||
- `recipe`
|
||||
- `production module`
|
||||
- `input inventory`
|
||||
- `output inventory`
|
||||
- `cycle time`
|
||||
- `throughput`
|
||||
|
||||
This is enough to define most of the industrial simulation at a high level.
|
||||
|
||||
## Recipes
|
||||
|
||||
A recipe is a conversion rule from one set of goods to another.
|
||||
|
||||
A recipe should conceptually define:
|
||||
|
||||
- required input items
|
||||
- produced output items
|
||||
- cycle time
|
||||
- valid producing module types
|
||||
- optional workforce requirement
|
||||
- optional power or fuel requirement
|
||||
|
||||
Recipes should be first-class design objects, not hidden assumptions inside modules.
|
||||
|
||||
## Production Modules
|
||||
|
||||
Recipes are executed by production-capable modules.
|
||||
|
||||
Examples:
|
||||
|
||||
- refinery module
|
||||
- fuel processing module
|
||||
- factory module
|
||||
- food-chain module later
|
||||
- shipyard support module
|
||||
|
||||
Modules define what recipes an entity can run.
|
||||
|
||||
Recipes define what actual transformation occurs.
|
||||
|
||||
## Production Flow
|
||||
|
||||
The intended production flow is:
|
||||
|
||||
1. a station has the required production module
|
||||
2. required inputs exist in inventory
|
||||
3. the module has enough power and operational support
|
||||
4. the recipe runs for its cycle time
|
||||
5. outputs are added to station inventory
|
||||
6. the station commander updates market behavior based on new shortages or surpluses
|
||||
|
||||
This keeps production grounded in world state rather than in abstract magic conversion.
|
||||
|
||||
## Time And Throughput
|
||||
|
||||
Production should be time-based.
|
||||
|
||||
That means:
|
||||
|
||||
- recipes take time to complete
|
||||
- modules have finite throughput
|
||||
- more modules should generally mean more production capacity
|
||||
- better staffing should improve effective throughput
|
||||
|
||||
Throughput should be visibly affected by:
|
||||
|
||||
- module count
|
||||
- workforce percentage
|
||||
- input availability
|
||||
- power availability
|
||||
|
||||
## Workforce Interaction
|
||||
|
||||
Production should respect the workforce rules in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
|
||||
|
||||
For now:
|
||||
|
||||
- workforce scales production effectiveness the same way it scales other module effectiveness
|
||||
- zero-workforce stations still retain baseline production
|
||||
- full staffing yields peak production
|
||||
|
||||
This keeps the initial system consistent and simple.
|
||||
|
||||
## Power Interaction
|
||||
|
||||
Production should also respect power and fuel state.
|
||||
|
||||
Without power:
|
||||
|
||||
- production stops
|
||||
|
||||
This is especially important for stations because no-fuel means no-power, and no-power means no normal operation.
|
||||
|
||||
## Input Shortage Behavior
|
||||
|
||||
If inputs are missing:
|
||||
|
||||
- the recipe cannot complete
|
||||
|
||||
This should naturally create market demand rather than needing a special shortage system layered on top.
|
||||
|
||||
Input shortage should be one of the primary reasons station commanders publish buy orders.
|
||||
|
||||
## Output And Inventory Pressure
|
||||
|
||||
Production also depends on output handling.
|
||||
|
||||
If output storage is full or constrained:
|
||||
|
||||
- production should stop or stall
|
||||
|
||||
This gives storage modules and logistics real importance.
|
||||
|
||||
## Example Production Chains
|
||||
|
||||
The exact recipes can evolve, but the intended shape includes chains like:
|
||||
|
||||
1. raw extraction
|
||||
- ore
|
||||
- gas
|
||||
- water later if extracted directly
|
||||
|
||||
2. refining or processing
|
||||
- ore -> refined goods
|
||||
- gas -> fuel
|
||||
- food-loop conversions later
|
||||
|
||||
3. industrial use
|
||||
- refined goods -> construction goods
|
||||
- processed goods -> module or ship build inputs
|
||||
|
||||
4. population support
|
||||
- food, water, energy, consumer goods -> workforce survival and growth support
|
||||
|
||||
These chains should create meaningful interdependence between station roles.
|
||||
|
||||
## Construction As Production
|
||||
|
||||
Construction should be treated as a special production form rather than a completely unrelated system.
|
||||
|
||||
This applies to:
|
||||
|
||||
- station founding
|
||||
- station module expansion
|
||||
- ship construction later
|
||||
|
||||
The same general pattern should hold:
|
||||
|
||||
1. desired build target defines required goods
|
||||
2. required goods are delivered
|
||||
3. build progress consumes those goods over time
|
||||
4. build output becomes a completed structure, module, or ship
|
||||
|
||||
This keeps construction inside the same economic language as the rest of the simulation.
|
||||
|
||||
## Construction Storage
|
||||
|
||||
Construction storage should act as the temporary industrial interface for building.
|
||||
|
||||
It should:
|
||||
|
||||
- hold required construction goods
|
||||
- publish demand through buy orders
|
||||
- allow delivery by traders or support ships
|
||||
- feed the actual building process
|
||||
|
||||
This is especially important during station founding at claimed Lagrange points.
|
||||
|
||||
## Production Queues
|
||||
|
||||
Stations should eventually be able to run more than one productive concern at once.
|
||||
|
||||
The exact queue model can stay simple for now, but the design should support:
|
||||
|
||||
- one recipe per module at a time
|
||||
- multiple modules running independently
|
||||
- commander-controlled production priorities
|
||||
|
||||
That is enough to express useful industrial behavior without needing a fully complex factory UI yet.
|
||||
|
||||
## Commander Interaction
|
||||
|
||||
Production should feed directly into station commander behavior.
|
||||
|
||||
Station commanders should observe:
|
||||
|
||||
- current recipe needs
|
||||
- input shortages
|
||||
- output surpluses
|
||||
- workforce limitations
|
||||
- power limitations
|
||||
|
||||
Based on that, they should:
|
||||
|
||||
- create buy orders
|
||||
- create sell orders
|
||||
- reprioritize station activity
|
||||
- request logistics support
|
||||
|
||||
## Profit And Production
|
||||
|
||||
Production is not only about self-sufficiency.
|
||||
|
||||
Stations should produce when it is useful because:
|
||||
|
||||
- they need the output internally
|
||||
- the output can be sold profitably
|
||||
- the output supports faction strategy
|
||||
|
||||
This lets industrial behavior emerge from a mix of necessity and opportunity.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- production consumes real inputs
|
||||
- production takes time
|
||||
- modules determine what recipes can run
|
||||
- workforce affects production throughput
|
||||
- lack of power stops normal production
|
||||
- lack of inputs halts recipe completion
|
||||
- storage limits can bottleneck output
|
||||
- construction is a specialized form of production
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
- defines what goods flow through recipes
|
||||
|
||||
- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
|
||||
- defines which modules can execute production
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines how production shortages and surpluses affect the market
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- defines station roles that host production
|
||||
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- defines workforce scaling and survival constraints
|
||||
461
docs/ROADMAP.md
Normal file
461
docs/ROADMAP.md
Normal file
@@ -0,0 +1,461 @@
|
||||
# Roadmap
|
||||
|
||||
This document maps the current codebase to the target design in the official docs and defines the recommended migration order.
|
||||
|
||||
It is not a feature wishlist. It is a gap analysis plus an incremental refactor plan.
|
||||
|
||||
## Current Architecture
|
||||
|
||||
The current codebase already has a functioning simulation loop, backend API, and viewer. It also has useful authored data for ships, items, modules, constructibles, and module build recipes.
|
||||
|
||||
The current implementation is still centered on a flatter world model:
|
||||
|
||||
- systems
|
||||
- resource nodes
|
||||
- stations
|
||||
- ships
|
||||
- factions
|
||||
|
||||
The current simulation behavior is driven mostly by:
|
||||
|
||||
- ship `Order`
|
||||
- ship `DefaultBehavior`
|
||||
- ship `ControllerTask`
|
||||
- string-based ship `State`
|
||||
- direct position and target-position movement
|
||||
|
||||
This gives the project a working prototype, but it does not yet reflect the design in:
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
|
||||
- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md)
|
||||
- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
|
||||
|
||||
## Existing Strengths
|
||||
|
||||
These parts are worth preserving and extending rather than replacing outright:
|
||||
|
||||
- Data-driven definitions already exist in [`shared/data/items.json`](/home/jbourdon/repos/space-game/shared/data/items.json), [`shared/data/modules.json`](/home/jbourdon/repos/space-game/shared/data/modules.json), [`shared/data/module-recipes.json`](/home/jbourdon/repos/space-game/shared/data/module-recipes.json), and [`shared/data/ships.json`](/home/jbourdon/repos/space-game/shared/data/ships.json).
|
||||
- The loader already supports authored station placement hints in [`shared/data/scenario.json`](/home/jbourdon/repos/space-game/shared/data/scenario.json) via `planetIndex` and `lagrangeSide`.
|
||||
- The backend already has snapshot and delta transport in [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) and [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs).
|
||||
- The simulation loop in [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) already has useful concepts like docking, extraction, construction, warp spooling, and FTL spooling.
|
||||
- The viewer stack already consumes a live world snapshot and delta stream through [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts), [`api.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/api.ts), and [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts).
|
||||
|
||||
## Gap Analysis
|
||||
|
||||
### Spatial Model
|
||||
|
||||
Target design:
|
||||
|
||||
- `universe-space`
|
||||
- `galaxy-space`
|
||||
- `system-space`
|
||||
- `local-space`
|
||||
- node-attached local bubbles
|
||||
- one structure per Lagrange point
|
||||
- warp between nodes
|
||||
- local gameplay inside bubbles
|
||||
|
||||
Current state:
|
||||
|
||||
- systems are first-class
|
||||
- planets exist only as system snapshot data
|
||||
- resource nodes exist, but only as extractable asteroid/gas sites
|
||||
- stations are positioned directly in system coordinates
|
||||
- ships move by `Position` and `TargetPosition`
|
||||
- no first-class system node graph
|
||||
- no first-class local bubbles
|
||||
- no claim entities
|
||||
- no construction-site entities
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no `NodeRuntime`, `LocalBubbleRuntime`, `ClaimRuntime`, or `ConstructionSiteRuntime`.
|
||||
- [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) computes station positions directly instead of creating node-backed placement.
|
||||
- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) still treats travel as raw coordinate movement rather than node-to-node transit between spaces.
|
||||
|
||||
### Command and Control
|
||||
|
||||
Target design:
|
||||
|
||||
- commanders are first-class simulation entities
|
||||
- factions, stations, and ships act through commanders
|
||||
- orders, behaviors, tasks, and state are distinct layers
|
||||
|
||||
Current state:
|
||||
|
||||
- no commander entity exists
|
||||
- command logic is embedded in ship runtime fields
|
||||
- station autonomy is implicit, not represented by a station commander
|
||||
- faction doctrine and policy are not first-class
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has `ShipOrderRuntime`, `DefaultBehaviorRuntime`, and `ControllerTaskRuntime`, but no commander model.
|
||||
- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) plans and executes directly on ships in a centralized loop.
|
||||
- [`TASKS.md`](/home/jbourdon/repos/space-game/docs/TASKS.md) is ahead of the current code; the code still uses stringly typed control layers.
|
||||
|
||||
### Economy and Market
|
||||
|
||||
Target design:
|
||||
|
||||
- market-driven simulation
|
||||
- station buy and sell orders
|
||||
- open visibility with policy-based access
|
||||
- profit-driven ship trade
|
||||
- construction storage as market demand
|
||||
|
||||
Current state:
|
||||
|
||||
- stations have inventory
|
||||
- ships can transfer and mine
|
||||
- factions have credits
|
||||
- there are no explicit market orders
|
||||
- there is no order reservation, fulfillment, pricing, or policy gating
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no `MarketOrderRuntime`, `ConstructionStorageRuntime`, or policy objects.
|
||||
- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) has logistics behavior, but not a real market loop.
|
||||
- [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) exposes inventory, but not orders, prices, or access policies.
|
||||
|
||||
### Workforce and Population
|
||||
|
||||
Target design:
|
||||
|
||||
- station-local population
|
||||
- faction-wide aggregate population
|
||||
- habitat-driven growth
|
||||
- workforce efficiency scaling
|
||||
- commanders generated from population over time
|
||||
- worker transport as a real logistics concern
|
||||
|
||||
Current state:
|
||||
|
||||
- no population model
|
||||
- no workforce efficiency
|
||||
- no habitat-backed growth
|
||||
- no worker transport
|
||||
- no commander generation from population
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) has no workforce or population state on factions or stations.
|
||||
- [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) has item, recipe, and constructible definitions, but no population or habitat-specific runtime schema yet.
|
||||
- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) cannot model production efficiency, starvation, or worker movement.
|
||||
|
||||
### Policies and Access
|
||||
|
||||
Target design:
|
||||
|
||||
- policy-driven trade access
|
||||
- docking access
|
||||
- construction access
|
||||
- system or region restrictions on ship behavior
|
||||
|
||||
Current state:
|
||||
|
||||
- behavior restriction is implicit inside ship behavior kinds
|
||||
- there is no reusable policy object
|
||||
- no faction/station policy layering
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- no `PolicySet` entity in [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs)
|
||||
- no policy fields in faction, station, ship, market, or construction runtime state
|
||||
- no policy payloads in [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs)
|
||||
|
||||
### Events and Replication
|
||||
|
||||
Target design:
|
||||
|
||||
- typed events
|
||||
- scope-aware visibility
|
||||
- streaming by relevance across space layers
|
||||
- interest management for clients and eventually services
|
||||
|
||||
Current state:
|
||||
|
||||
- a single world-wide snapshot and delta stream
|
||||
- a minimal event record with string fields
|
||||
- all subscribers receive the same deltas
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- [`SimulationEventRecord`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs#L20) is too small for the event model in [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md).
|
||||
- [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) broadcasts a single `WorldDelta` to all observers.
|
||||
- there is no notion of observer scope, visible systems, visible bubbles, or higher-space filtered streaming.
|
||||
|
||||
### Viewer
|
||||
|
||||
Target design:
|
||||
|
||||
- zoomable universe/galaxy view
|
||||
- system view centered on nodes and transit
|
||||
- local view centered on one bubble
|
||||
- clear transitions between movement regimes and spaces
|
||||
|
||||
Current state:
|
||||
|
||||
- viewer consumes a flat snapshot of systems, resource nodes, stations, ships, and factions
|
||||
- systems are strategic and visual, but not tied to explicit multi-space simulation layers
|
||||
- no contracts for bubbles, claims, construction sites, market orders, commanders, or policies
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) mirrors the old backend model.
|
||||
- [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) cannot render node graph, local bubbles, claims, or construction states because that data does not exist yet.
|
||||
|
||||
## Subsystem Assessment
|
||||
|
||||
### Keep and Extend
|
||||
|
||||
- [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs)
|
||||
- [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs)
|
||||
- [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs)
|
||||
- [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs)
|
||||
- [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs)
|
||||
- [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts)
|
||||
|
||||
These should evolve in place.
|
||||
|
||||
### Replace Gradually
|
||||
|
||||
- string-based ship state with explicit enums and structured movement state
|
||||
- ship-only planning fields with commander/task-layer entities
|
||||
- direct station placement with node, claim, and construction-site placement
|
||||
- flat event records with typed event payloads
|
||||
|
||||
### Avoid
|
||||
|
||||
- avoid a big-bang rewrite of [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs)
|
||||
- avoid rewriting the viewer before contracts and runtime state exist
|
||||
- avoid introducing commander logic only in the viewer or only in docs
|
||||
|
||||
## Recommended Sequencing
|
||||
|
||||
### Phase 1: Align the Runtime Vocabulary
|
||||
|
||||
Goal:
|
||||
|
||||
- make the backend world model match the minimum entity vocabulary in [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
|
||||
|
||||
Work:
|
||||
|
||||
- extend [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs) with:
|
||||
- `NodeRuntime`
|
||||
- `LocalBubbleRuntime`
|
||||
- `CommanderRuntime`
|
||||
- `ClaimRuntime`
|
||||
- `ConstructionSiteRuntime`
|
||||
- `MarketOrderRuntime`
|
||||
- `PolicySetRuntime`
|
||||
- add explicit enums or enum-like constants for:
|
||||
- space layers
|
||||
- movement regimes
|
||||
- task kinds
|
||||
- order kinds
|
||||
- commander kinds
|
||||
- add structured ship spatial state:
|
||||
- current space layer
|
||||
- current node
|
||||
- current bubble
|
||||
- current transit
|
||||
|
||||
Why first:
|
||||
|
||||
- every later change depends on this vocabulary existing in runtime state
|
||||
|
||||
### Phase 2: Refactor Scenario and World Building Around Nodes
|
||||
|
||||
Goal:
|
||||
|
||||
- make systems produce a real node graph with local bubbles and Lagrange-backed construction points
|
||||
|
||||
Work:
|
||||
|
||||
- extend [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs) with authored node and claim-related definitions only where necessary
|
||||
- update [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs) to:
|
||||
- generate system-space nodes for stars, planets, moons, stations, and Lagrange points
|
||||
- attach local bubbles to nodes
|
||||
- translate existing `planetIndex` and `lagrangeSide` station hints into actual node IDs
|
||||
- stop treating station placement as an arbitrary coordinate
|
||||
- preserve current authored content while migrating scenario interpretation
|
||||
|
||||
Why second:
|
||||
|
||||
- movement, claims, construction, and viewer transitions all depend on real nodes
|
||||
|
||||
### Phase 3: Introduce Founding, Claims, and Construction Sites
|
||||
|
||||
Goal:
|
||||
|
||||
- move station creation from “spawned finished station” toward the designed claim and construction flow
|
||||
|
||||
Work:
|
||||
|
||||
- add claim lifecycle state:
|
||||
- planted
|
||||
- activating
|
||||
- active
|
||||
- destroyed
|
||||
- add construction-site runtime state with:
|
||||
- target node
|
||||
- blueprint or constructible reference
|
||||
- construction storage inventory
|
||||
- construction buy orders
|
||||
- update [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) to support:
|
||||
- claim activation
|
||||
- claim destruction
|
||||
- construction delivery
|
||||
- builder progress
|
||||
|
||||
Why here:
|
||||
|
||||
- it lets the code start reflecting the station and Lagrange rules without requiring the full economy rewrite first
|
||||
|
||||
### Phase 4: Replace Raw Travel With Space-Aware Movement
|
||||
|
||||
Goal:
|
||||
|
||||
- make ship movement follow the spatial design rather than raw target positions
|
||||
|
||||
Work:
|
||||
|
||||
- replace direct long-range movement with:
|
||||
- local thruster movement inside a bubble
|
||||
- in-system warp between nodes
|
||||
- inter-system transit through gates or FTL
|
||||
- update ship runtime in [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs)
|
||||
- split movement logic in [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs) into clearer controllers or subsystems
|
||||
- keep existing warp and FTL timings where useful, but move them under explicit movement regimes
|
||||
|
||||
Why here:
|
||||
|
||||
- this is the point where [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) starts becoming real in the simulation
|
||||
|
||||
### Phase 5: Introduce Commanders and Task Layers
|
||||
|
||||
Goal:
|
||||
|
||||
- replace the current ship-only control stack with the design in [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md) and [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
|
||||
|
||||
Work:
|
||||
|
||||
- add `CommanderRuntime` and commander assignment to ships and stations
|
||||
- split:
|
||||
- goals
|
||||
- orders
|
||||
- behaviors
|
||||
- tasks
|
||||
- control state
|
||||
- migrate existing `ShipOrderRuntime`, `DefaultBehaviorRuntime`, and `ControllerTaskRuntime` incrementally rather than deleting them in one step
|
||||
- add faction and station policy references into planning
|
||||
|
||||
Why here:
|
||||
|
||||
- commanders need the spatial model first; market and production loops also need someone to make decisions
|
||||
|
||||
### Phase 6: Build the Market and Workforce Loop
|
||||
|
||||
Goal:
|
||||
|
||||
- implement the first real economic loop that matches [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md), [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md), [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md), and [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
|
||||
|
||||
Work:
|
||||
|
||||
- add market orders to stations and construction storage
|
||||
- add price evaluation and ship profit selection
|
||||
- add station population and workforce efficiency
|
||||
- add habitat growth and worker consumption
|
||||
- add transport rules for workers requiring habitat capacity on ships
|
||||
- wire production throughput to workforce percentage and power availability
|
||||
|
||||
Why here:
|
||||
|
||||
- once commanders and nodes exist, this becomes a coherent system instead of isolated resource transfers
|
||||
|
||||
### Phase 7: Upgrade Events and Streaming
|
||||
|
||||
Goal:
|
||||
|
||||
- make the event and replication layer match [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md)
|
||||
|
||||
Work:
|
||||
|
||||
- replace the current minimal event shape in [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs) with typed event families or a typed envelope
|
||||
- add event scope metadata:
|
||||
- universe
|
||||
- galaxy
|
||||
- system
|
||||
- local bubble
|
||||
- refactor [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs) so subscriptions are observer-scoped rather than globally broadcast
|
||||
- support higher-space streaming with filtering into lower-space views
|
||||
|
||||
Why here:
|
||||
|
||||
- this is the first phase that directly benefits multiplayer-style interest management and scalable service boundaries
|
||||
|
||||
### Phase 8: Rebuild Viewer Contracts and Presentation
|
||||
|
||||
Goal:
|
||||
|
||||
- update the viewer to the new simulation truth
|
||||
|
||||
Work:
|
||||
|
||||
- extend [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts) for:
|
||||
- nodes
|
||||
- local bubbles
|
||||
- claims
|
||||
- construction sites
|
||||
- market orders
|
||||
- policies where relevant
|
||||
- richer ship movement state
|
||||
- update [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts) to support:
|
||||
- galaxy/system/local scale transitions
|
||||
- node-centric system view
|
||||
- local bubble detail
|
||||
- regime-aware ship rendering
|
||||
|
||||
Why last:
|
||||
|
||||
- the viewer should follow the backend contract, not invent the model ahead of it
|
||||
|
||||
## Suggested First Refactor Seams
|
||||
|
||||
If implementation starts immediately, the first files to change should be:
|
||||
|
||||
1. [`RuntimeModels.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/RuntimeModels.cs)
|
||||
2. [`WorldDefinitions.cs`](/home/jbourdon/repos/space-game/apps/backend/Data/WorldDefinitions.cs)
|
||||
3. [`ScenarioLoader.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs)
|
||||
4. [`WorldContracts.cs`](/home/jbourdon/repos/space-game/apps/backend/Contracts/WorldContracts.cs)
|
||||
5. [`SimulationEngine.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs)
|
||||
6. [`WorldService.cs`](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs)
|
||||
7. [`contracts.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts)
|
||||
8. [`GameViewer.ts`](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts)
|
||||
|
||||
That order keeps the simulation model ahead of the API, and the API ahead of the viewer.
|
||||
|
||||
## Practical Guidance
|
||||
|
||||
- Keep the current prototype alive while refactoring.
|
||||
- Prefer additive migration over destructive replacement until each layer is proven.
|
||||
- Do not start with the viewer.
|
||||
- Do not start with combat polish.
|
||||
- Start with the backend data model and scenario loading, because the current architecture is still defined there.
|
||||
|
||||
## Exit Criteria for “Docs to Code” Transition
|
||||
|
||||
The design set is ready to drive implementation once these minimum conditions are met:
|
||||
|
||||
- runtime state has first-class nodes, bubbles, commanders, claims, and market orders
|
||||
- ships no longer rely on raw free-flight for all in-system travel
|
||||
- station founding can exist as claim plus construction rather than only finished stations
|
||||
- market and workforce state exist in contracts, not only internal runtime
|
||||
- event streaming can be scoped by relevance instead of one global feed
|
||||
|
||||
When those are true, the codebase will match the design direction closely enough that tuning and gameplay iteration become meaningful rather than structural.
|
||||
93
docs/SHIPS.md
Normal file
93
docs/SHIPS.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Ships
|
||||
|
||||
This document defines the intended role of ships in the simulation.
|
||||
|
||||
Ships are mobile actors that operate across the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md) under the authority of commanders defined in [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md).
|
||||
|
||||
## Core Principles
|
||||
|
||||
- every active ship should have a commander
|
||||
- ships operate in explicit movement regimes
|
||||
- ships execute logistics, combat, construction, scouting, and transport roles
|
||||
- ship capability depends on hull, modules, and commander intent
|
||||
|
||||
## Ship Roles
|
||||
|
||||
Common roles include:
|
||||
|
||||
- mining
|
||||
- hauling
|
||||
- construction
|
||||
- escort
|
||||
- patrol
|
||||
- combat
|
||||
- scouting
|
||||
- passenger or utility support later
|
||||
|
||||
From a simulation point of view, the important distinction is not only hull category but also commander role:
|
||||
|
||||
- self-directed industrial ship
|
||||
- station-assigned ship
|
||||
- fleet-assigned ship
|
||||
- faction-directed strategic ship
|
||||
|
||||
## Movement
|
||||
|
||||
Ships should move according to the layered spatial model:
|
||||
|
||||
- thrusters in `local-space`
|
||||
- warp in `system-space`
|
||||
- stargate or FTL for inter-system travel
|
||||
|
||||
Ships should not behave as if an entire system is one continuous local dogfighting field.
|
||||
|
||||
## Command Requirements
|
||||
|
||||
A ship without a commander should be severely limited.
|
||||
|
||||
At minimum, it should not perform meaningful autonomous loops such as:
|
||||
|
||||
- mining cycles
|
||||
- trade runs
|
||||
- route planning
|
||||
- combat patrols
|
||||
- logistics procurement
|
||||
|
||||
Ship commanders should be able to receive work from:
|
||||
|
||||
- player direct orders
|
||||
- a superior commander
|
||||
- economic opportunities exposed by the market
|
||||
|
||||
Some ships should also specialize in worker transport, provided they carry the required human habitat module defined in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
|
||||
|
||||
Ship work selection should also obey policy restrictions such as allowed trade partners, regional limits, and station-serving constraints. See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md).
|
||||
|
||||
## Capabilities
|
||||
|
||||
Ship capability should depend on:
|
||||
|
||||
- hull class
|
||||
- fitted modules
|
||||
- cargo and storage compatibility
|
||||
- propulsion capability
|
||||
- docking compatibility
|
||||
- optional warp and FTL capability
|
||||
|
||||
Cargo and movement capability should materially affect which market opportunities a ship can accept.
|
||||
|
||||
This should eventually include item-class compatibility as described in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md).
|
||||
|
||||
Those capabilities should primarily come from fitted modules as described in [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md).
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
|
||||
- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
518
docs/SPACES.md
Normal file
518
docs/SPACES.md
Normal file
@@ -0,0 +1,518 @@
|
||||
# Spaces
|
||||
|
||||
This document defines the intended spatial model for the project.
|
||||
|
||||
It is a gameplay and simulation document first. The viewer should expose these layers clearly, but it does not define them.
|
||||
|
||||
The core idea is that the world is not one continuous field of arbitrary movement. Instead, gameplay happens across nested spatial layers with different rules, scales, and valid actions.
|
||||
|
||||
See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the entity vocabulary that should represent these layers.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The spatial model should support:
|
||||
|
||||
- EVE-like travel pacing and readability
|
||||
- explicit transitions between tactical space and transit space
|
||||
- local combat and interaction bubbles
|
||||
- scalable simulation partitioning
|
||||
- scalable replication and interest management
|
||||
- future server-side sharding by local bubble if necessary
|
||||
|
||||
The intended feel is:
|
||||
|
||||
- local maneuvering is slow, deliberate, and readable
|
||||
- in-system travel is warp-based, not long free-flight
|
||||
- inter-system travel is explicit and infrastructural
|
||||
- zooming the viewer reveals different valid abstractions of the same world
|
||||
|
||||
## Space Layers
|
||||
|
||||
The simulation is divided into four major space layers:
|
||||
|
||||
1. `universe-space`
|
||||
2. `galaxy-space`
|
||||
3. `system-space`
|
||||
4. `local-space`
|
||||
|
||||
These are simulation layers, not just camera levels.
|
||||
|
||||
### `universe-space`
|
||||
|
||||
The broadest simulation layer.
|
||||
|
||||
This is where universe-wide state and events live, such as:
|
||||
|
||||
- global time
|
||||
- global factions and diplomacy
|
||||
- universe-scale event scheduling
|
||||
- future crises, anomalies, migrations, or story events
|
||||
|
||||
`universe-space` is not primarily about positional navigation. It is the top-most simulation context.
|
||||
|
||||
### `galaxy-space`
|
||||
|
||||
The layer where star systems exist as spatially arranged world entities.
|
||||
|
||||
This is where the game models:
|
||||
|
||||
- system positions
|
||||
- large-scale routes and proximity
|
||||
- inter-system connectivity
|
||||
- strategic movement between systems
|
||||
|
||||
Ships do not dogfight in `galaxy-space`. It is the strategic layer connecting systems.
|
||||
|
||||
### `system-space`
|
||||
|
||||
The layer inside a single star system where travel occurs between meaningful locations.
|
||||
|
||||
This is where the game models:
|
||||
|
||||
- stars
|
||||
- planets
|
||||
- moons
|
||||
- stations
|
||||
- structures
|
||||
- gates
|
||||
- resource locations, if they should be direct destinations
|
||||
- Lagrange points
|
||||
- travel relationships between these locations
|
||||
|
||||
`system-space` is the travel layer between local bubbles. Gameplay-wise, this can also be referred to as warp-space for ship movement inside a system.
|
||||
|
||||
### `local-space`
|
||||
|
||||
The tactical simulation bubble attached to a specific node.
|
||||
|
||||
This is where close interaction happens:
|
||||
|
||||
- thruster flight
|
||||
- combat
|
||||
- docking
|
||||
- undocking
|
||||
- mining
|
||||
- construction
|
||||
- rendezvous
|
||||
- local hazards
|
||||
|
||||
Each `local-space` is an isolated simulation bubble attached to one node. Ships leave one local bubble, exist in `system-space` during warp transit, then enter another local bubble on arrival.
|
||||
|
||||
Local bubbles are also the intended future unit of simulation partitioning. A later runtime may move one or more bubbles to dedicated servers without changing the gameplay model.
|
||||
|
||||
## Nodes
|
||||
|
||||
A node is a meaningful location in `system-space` that owns a `local-space` bubble.
|
||||
|
||||
Examples of nodes:
|
||||
|
||||
- star
|
||||
- planet
|
||||
- moon
|
||||
- station
|
||||
- structure
|
||||
- gate
|
||||
- major resource location if desired
|
||||
- each Lagrange point associated with a massive orbital
|
||||
|
||||
Each node should have:
|
||||
|
||||
- a stable identifier
|
||||
- a parent system
|
||||
- a type
|
||||
- a position in `system-space`
|
||||
- a local bubble radius
|
||||
- optional parent/child relationships
|
||||
- optional orbital metadata
|
||||
|
||||
Examples:
|
||||
|
||||
- a planet node orbits a star node
|
||||
- a moon node orbits a planet node
|
||||
- a station or structure node is built at a Lagrange point
|
||||
|
||||
## Lagrange Points
|
||||
|
||||
Each massive orbital should expose five Lagrange points:
|
||||
|
||||
- `L1`
|
||||
- `L2`
|
||||
- `L3`
|
||||
- `L4`
|
||||
- `L5`
|
||||
|
||||
These are valid nodes in `system-space`, each with its own `local-space`.
|
||||
|
||||
They should be computed from orbital relationships rather than authored by hand in most cases.
|
||||
|
||||
Construction rule:
|
||||
|
||||
- each Lagrange point can host exactly one structure
|
||||
|
||||
This scarcity is intentional. Lagrange points should be valuable strategic locations rather than interchangeable empty coordinates.
|
||||
|
||||
Recommended applicability:
|
||||
|
||||
- major orbitals should expose all five Lagrange points
|
||||
- this should apply at least to sufficiently massive planets
|
||||
- moons may expose none or fewer, depending on the final simulation rule
|
||||
|
||||
Lagrange points should not always be immediately buildable by default.
|
||||
|
||||
Recommended structure founding flow:
|
||||
|
||||
1. claim the Lagrange point
|
||||
2. protect the claim until it matures
|
||||
3. activate the claim
|
||||
4. begin station construction
|
||||
|
||||
Lagrange points are useful for:
|
||||
|
||||
- staging areas
|
||||
- logistics hubs
|
||||
- military control points
|
||||
- hidden or contested infrastructure
|
||||
- future economy and navigation design
|
||||
- station and structure placement
|
||||
|
||||
## Structures At Lagrange Points
|
||||
|
||||
Stations and other built structures should always be placed at Lagrange points.
|
||||
|
||||
This should be treated as a world rule, not merely a common pattern.
|
||||
|
||||
Implications:
|
||||
|
||||
- player and AI construction targets for major structures are Lagrange nodes
|
||||
- stations do not occupy arbitrary free positions in system-space
|
||||
- structure placement is tied to orbital geometry
|
||||
- economically and militarily valuable station locations are legible from the system map
|
||||
- each Lagrange point supports only one built structure
|
||||
- to create another station, a faction must secure another valid location
|
||||
|
||||
This makes system geography more understandable and gives Lagrange points durable strategic meaning.
|
||||
|
||||
## Claiming Lagrange Points
|
||||
|
||||
Station construction should begin with an explicit claim on a Lagrange point.
|
||||
|
||||
The claim should behave like a vulnerable placed object.
|
||||
|
||||
Properties:
|
||||
|
||||
- it marks intent to occupy the Lagrange point
|
||||
- it can be attacked or destroyed by enemies or pirates
|
||||
- it requires an activation period before full construction can begin
|
||||
|
||||
Recommended founding sequence:
|
||||
|
||||
1. a faction places a claim object at the target Lagrange point
|
||||
2. the claim survives for its activation time
|
||||
3. the claim becomes active
|
||||
4. station construction storage appears
|
||||
5. the desired station design creates demand for required construction materials
|
||||
6. constructor ships consume those materials to build the station
|
||||
|
||||
This makes Lagrange occupation contestable and visible.
|
||||
|
||||
## Local Bubbles
|
||||
|
||||
Each node owns exactly one local bubble.
|
||||
|
||||
A local bubble defines:
|
||||
|
||||
- the local simulation frame
|
||||
- the tactical interaction radius
|
||||
- the list of occupants
|
||||
- the set of legal actions inside that space
|
||||
- the future server authority boundary
|
||||
|
||||
Local bubbles should be treated as separate simulation contexts, not merely camera zoom-ins.
|
||||
|
||||
Rules:
|
||||
|
||||
- a ship in `local-space` belongs to exactly one bubble
|
||||
- actions such as combat, docking, mining, and construction happen only inside a local bubble
|
||||
- leaving a bubble is an explicit transition into `system-space`
|
||||
- entering a destination bubble is an explicit arrival transition from `system-space`
|
||||
|
||||
See [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md) for the combat consequences of this rule.
|
||||
|
||||
## Movement Regimes
|
||||
|
||||
Ships do not move with one universal locomotion model. Their movement depends on their current space layer and travel regime.
|
||||
|
||||
Primary regimes:
|
||||
|
||||
- `local-flight`
|
||||
- `warp`
|
||||
- `stargate-transit`
|
||||
- `ftl-transit`
|
||||
|
||||
### `local-flight`
|
||||
|
||||
Used inside `local-space`.
|
||||
|
||||
Characteristics:
|
||||
|
||||
- uses normal thrusters
|
||||
- supports fine positioning
|
||||
- supports docking and undocking
|
||||
- supports combat
|
||||
- supports mining and close interaction
|
||||
|
||||
This regime should feel heavy, readable, and tactical.
|
||||
|
||||
### `warp`
|
||||
|
||||
Used in `system-space` to travel between nodes in the same system.
|
||||
|
||||
Characteristics:
|
||||
|
||||
- exits one local bubble
|
||||
- enters spool-up
|
||||
- travels through `system-space`
|
||||
- drops out at a destination node
|
||||
- enters the destination local bubble
|
||||
|
||||
The intended feel is close to EVE, but with spool-up emphasis rather than strict align mechanics.
|
||||
|
||||
Recommended warp phases:
|
||||
|
||||
1. `warp-spooling`
|
||||
2. `in-warp`
|
||||
3. `warp-dropout`
|
||||
|
||||
During warp, ships should not be treated as locally maneuvering units.
|
||||
|
||||
### `stargate-transit`
|
||||
|
||||
Used to travel between systems through infrastructure.
|
||||
|
||||
Characteristics:
|
||||
|
||||
- starts from a gate node in local-space
|
||||
- transitions through a gate sequence
|
||||
- arrives at a gate node in another system
|
||||
|
||||
This should be a discrete inter-system travel mode, not merely a very long warp.
|
||||
|
||||
### `ftl-transit`
|
||||
|
||||
Used by ships that have their own FTL capability.
|
||||
|
||||
Characteristics:
|
||||
|
||||
- explicit inter-system travel regime
|
||||
- likely stronger costs, constraints, or cooldowns than gates
|
||||
- may bypass some infrastructure requirements
|
||||
|
||||
This remains distinct from in-system warp.
|
||||
|
||||
## Valid Actions By Space
|
||||
|
||||
### In `universe-space`
|
||||
|
||||
Examples:
|
||||
|
||||
- resolve universe-scale events
|
||||
- evaluate global strategic conditions
|
||||
- future narrative or crisis systems
|
||||
|
||||
### In `galaxy-space`
|
||||
|
||||
Examples:
|
||||
|
||||
- reason about systems
|
||||
- evaluate strategic routes
|
||||
- choose inter-system destinations
|
||||
|
||||
### In `system-space`
|
||||
|
||||
Examples:
|
||||
|
||||
- choose destination nodes
|
||||
- execute warp travel
|
||||
- evaluate node-to-node movement
|
||||
|
||||
### In `local-space`
|
||||
|
||||
Examples:
|
||||
|
||||
- maneuver with thrusters
|
||||
- dock
|
||||
- undock
|
||||
- mine
|
||||
- fight
|
||||
- build
|
||||
- transfer cargo locally
|
||||
|
||||
Rule of thumb:
|
||||
|
||||
- tactical interaction belongs to `local-space`
|
||||
- transit belongs to `system-space`
|
||||
- strategic topology belongs to `galaxy-space`
|
||||
|
||||
## Ship Spatial State
|
||||
|
||||
Ships should eventually be modeled with explicit spatial state, not just one position plus one target position.
|
||||
|
||||
At minimum, a ship should know:
|
||||
|
||||
- current `systemId`
|
||||
- current `spaceLayer`
|
||||
- current `nodeId`, if in local-space
|
||||
- current `localPosition`, if in local-space
|
||||
- current transit data, if in warp or inter-system travel
|
||||
|
||||
Recommended movement/runtime states include:
|
||||
|
||||
- `idle`
|
||||
- `local-flight`
|
||||
- `warp-spooling`
|
||||
- `in-warp`
|
||||
- `warp-dropout`
|
||||
- `docking`
|
||||
- `docked`
|
||||
- `undocking`
|
||||
- `using-stargate`
|
||||
- `ftl-spooling`
|
||||
- `in-ftl`
|
||||
- `arriving-from-ftl`
|
||||
|
||||
This spatial model works together with the command and economy documents:
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- defines who decides and delegates
|
||||
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- defines how stations and factions participate economically
|
||||
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- defines ship-side capability and behavior
|
||||
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- defines station-side role and responsibility
|
||||
|
||||
## Orders And Destinations
|
||||
|
||||
Orders should target valid destinations in the spatial model.
|
||||
|
||||
In practice, that means ships should target nodes and bubbles rather than arbitrary points across an entire system.
|
||||
|
||||
Examples:
|
||||
|
||||
- travel to node
|
||||
- warp to node
|
||||
- dock at structure in node
|
||||
- mine in node
|
||||
- use gate to system
|
||||
- jump to system
|
||||
|
||||
This makes planning clearer and keeps traversal tied to the intended world structure.
|
||||
|
||||
## Viewer Expectations
|
||||
|
||||
The viewer should reveal these layers as the player zooms or changes context.
|
||||
|
||||
Desired viewer scales:
|
||||
|
||||
1. `universe/galaxy view`
|
||||
2. `system view`
|
||||
3. `local view`
|
||||
|
||||
### `universe/galaxy view`
|
||||
|
||||
Shows:
|
||||
|
||||
- systems
|
||||
- strategic relationships
|
||||
- large-scale motion and events
|
||||
|
||||
### `system view`
|
||||
|
||||
Shows:
|
||||
|
||||
- nodes inside one system
|
||||
- warp destinations
|
||||
- route structure
|
||||
- high-level in-system movement
|
||||
|
||||
This view should not pretend that all tactical detail is always present.
|
||||
|
||||
### `local view`
|
||||
|
||||
Shows:
|
||||
|
||||
- one node bubble in detail
|
||||
- ships maneuvering with thrusters
|
||||
- combat, docking, mining, and construction
|
||||
|
||||
Viewer zoom should expose valid abstractions of simulation truth rather than inventing unrelated presentation layers.
|
||||
|
||||
## Interest Management
|
||||
|
||||
This spatial model naturally supports interest management for streaming.
|
||||
|
||||
The general rule should be:
|
||||
|
||||
- always stream context from higher spaces
|
||||
- filter detailed context from lower spaces based on interest
|
||||
|
||||
Examples:
|
||||
|
||||
- a client viewing a local bubble still needs relevant system, galaxy, and universe context
|
||||
- a client viewing a system does not need full-fidelity tactical events from every local bubble
|
||||
- a client viewing the galaxy does not need continuous local combat state for every bubble
|
||||
|
||||
Suggested replication principle:
|
||||
|
||||
- high-layer events are broad but low-detail
|
||||
- low-layer events are narrow but high-detail
|
||||
|
||||
Example filtering:
|
||||
|
||||
- `universe-space` events can be broadcast widely
|
||||
- `galaxy-space` events can be scoped by region or strategic relevance
|
||||
- `system-space` events can be scoped by current or observed system
|
||||
- `local-space` events can be scoped by the specific bubble being observed or occupied
|
||||
|
||||
This should make future multiplayer scaling easier than a flat world-wide stream.
|
||||
|
||||
## Recommended Backend Direction
|
||||
|
||||
The backend should move toward:
|
||||
|
||||
- explicit node definitions
|
||||
- explicit local bubble definitions
|
||||
- explicit ship travel regimes
|
||||
- explicit transitions between local, system, and inter-system movement
|
||||
|
||||
Recommended progression:
|
||||
|
||||
1. define nodes and local bubbles in world/runtime contracts
|
||||
2. compute and include Lagrange points for major orbitals
|
||||
3. refactor ship movement around regimes instead of free system-local travel
|
||||
4. restrict tactical actions to local-space
|
||||
5. expose regime and bubble membership in replication contracts
|
||||
6. redesign viewer zoom and replication around these layers
|
||||
|
||||
## Invariants
|
||||
|
||||
These rules should remain true unless there is a very deliberate design reason to break them:
|
||||
|
||||
- every local bubble belongs to exactly one node
|
||||
- every ship is in exactly one major movement regime at a time
|
||||
- ships in different local bubbles are not co-located, even if they are in the same system
|
||||
- movement inside local-space uses thrusters
|
||||
- movement between nodes inside a system uses warp
|
||||
- movement between systems uses stargates or ship FTL
|
||||
- combat, docking, mining, and construction happen only in local-space
|
||||
- viewer abstractions should map back to real simulation layers
|
||||
- every structure occupies exactly one Lagrange point
|
||||
- every Lagrange point supports at most one structure
|
||||
- a station site must be claimed before full construction begins
|
||||
|
||||
## Open Follow-Up Documents
|
||||
|
||||
This document is part of the official design set listed in [DESIGN.md](/home/jbourdon/repos/space-game/docs/DESIGN.md).
|
||||
213
docs/STATIONS.md
Normal file
213
docs/STATIONS.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Stations
|
||||
|
||||
This document defines the intended role of stations in the simulation.
|
||||
|
||||
Stations are persistent nodes in the world that own local bubbles, provide services, participate in the economy, and act through station commanders.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- every active station should have a commander
|
||||
- stations are major market actors
|
||||
- stations exist at meaningful nodes in space
|
||||
- stations provide local services and strategic value
|
||||
|
||||
## Station Identity
|
||||
|
||||
A station lives at one location.
|
||||
|
||||
It does not spread across multiple construction points.
|
||||
|
||||
Station growth happens by adding modules to the existing station at its current Lagrange point.
|
||||
|
||||
To create another station, a faction needs:
|
||||
|
||||
- another valid location
|
||||
- another station
|
||||
- another station commander
|
||||
|
||||
Before station construction itself, the faction should also secure the site through the Lagrange-point claim process defined in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md).
|
||||
|
||||
Station identity and capability should primarily come from module composition, as described in [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md).
|
||||
|
||||
## Station Roles
|
||||
|
||||
Stations may serve as:
|
||||
|
||||
- markets
|
||||
- refineries
|
||||
- production centers
|
||||
- logistics hubs
|
||||
- shipyards
|
||||
- military outposts
|
||||
- defensive strongholds
|
||||
- staging points
|
||||
|
||||
## Spatial Role
|
||||
|
||||
Stations are nodes in `system-space` with their own `local-space`.
|
||||
|
||||
Stations and other built structures should always be located at Lagrange points.
|
||||
|
||||
Each Lagrange point can hold only one structure.
|
||||
|
||||
Their local bubbles are where:
|
||||
|
||||
- docking happens
|
||||
- cargo transfer happens
|
||||
- defense happens
|
||||
- local construction happens
|
||||
- player and AI interaction happens
|
||||
|
||||
Local-space defense and contestation are described further in [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md).
|
||||
|
||||
## Founding A Station
|
||||
|
||||
The intended founding flow is:
|
||||
|
||||
1. claim a valid Lagrange point
|
||||
2. wait for the claim to activate
|
||||
3. create station construction storage
|
||||
4. publish buy orders for the required construction materials
|
||||
5. deliver materials
|
||||
6. have constructor ships build the station from those materials
|
||||
|
||||
The construction storage should act as the early economic interface of the future station.
|
||||
|
||||
That means a station can begin expressing demand before the full station is operational.
|
||||
|
||||
Those construction requirements should be expressed through real goods as described in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md).
|
||||
|
||||
## Commander Requirements
|
||||
|
||||
A station without a commander should be limited.
|
||||
|
||||
Without a commander, a station should not be expected to:
|
||||
|
||||
- manage buy orders
|
||||
- manage sell orders
|
||||
- adapt production priorities
|
||||
- coordinate logistics
|
||||
- respond intelligently to shortages or dock congestion
|
||||
|
||||
Important boundary:
|
||||
|
||||
- a station commander is responsible for station operation
|
||||
- a station commander does not own ships
|
||||
|
||||
Ships may still serve a station through assignment, doctrine, or market incentives, but that is not the same thing as station ownership.
|
||||
|
||||
Station founding does not require a station commander at the first moment of construction.
|
||||
|
||||
However, a fully operating station should require one to function normally.
|
||||
|
||||
The commander must be brought to the station rather than appearing automatically.
|
||||
|
||||
This implies stations will eventually depend on population and worker logistics.
|
||||
|
||||
Workers should be treated as a real station resource, not as a free abstraction.
|
||||
|
||||
See [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) for the workforce model.
|
||||
|
||||
## Market Role
|
||||
|
||||
Stations are the main local market-makers of the simulation.
|
||||
|
||||
A station commander should:
|
||||
|
||||
- publish buy orders
|
||||
- publish sell orders
|
||||
- manage stock reserves
|
||||
- control production priorities
|
||||
- request imports and exports
|
||||
|
||||
Stations should be the primary place where the economy becomes concrete and visible to the player.
|
||||
|
||||
That means stations should expose:
|
||||
|
||||
- current shortages
|
||||
- current surpluses
|
||||
- active buy orders
|
||||
- active sell orders
|
||||
- dock activity
|
||||
- production intent
|
||||
|
||||
Market visibility should be treated as open knowledge, subject to access and information rules defined elsewhere.
|
||||
|
||||
The baseline assumption is that station market intent is visible, not hidden by default.
|
||||
|
||||
Actual participation in trade and docking should still be policy-controlled. See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md).
|
||||
|
||||
## Ownership And Presence
|
||||
|
||||
Station ownership is not local-bubble exclusive.
|
||||
|
||||
The important hard rule is:
|
||||
|
||||
- one structure per Lagrange point
|
||||
|
||||
Not:
|
||||
|
||||
- one faction per local bubble
|
||||
|
||||
This means friendly or otherwise permitted factions may build stations within the same system, so long as they use different valid locations.
|
||||
|
||||
## Failure State
|
||||
|
||||
Without fuel there is no power.
|
||||
|
||||
Without power, station function collapses.
|
||||
|
||||
A powerless station should not continue normal market or industrial behavior.
|
||||
|
||||
At that point, recovery should require outside intervention such as emergency restoration, delivered fuel, or a dedicated support operation.
|
||||
|
||||
This also means:
|
||||
|
||||
- no loading
|
||||
- no unloading
|
||||
- no ordinary trade handling
|
||||
- no ordinary production
|
||||
|
||||
## Services
|
||||
|
||||
Depending on modules and category, a station may provide:
|
||||
|
||||
- docking
|
||||
- storage
|
||||
- refining
|
||||
- fuel processing
|
||||
- manufacturing
|
||||
- repair later
|
||||
- fitting later
|
||||
- rearm and resupply later
|
||||
- habitats
|
||||
|
||||
The exact conversion and factory behavior behind these services is described in [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md).
|
||||
|
||||
## Workforce
|
||||
|
||||
Stations track their own local population.
|
||||
|
||||
That population determines workforce availability and therefore station efficiency.
|
||||
|
||||
For now:
|
||||
|
||||
- every module benefits equally from workforce
|
||||
- each module has a workforce target for peak efficiency
|
||||
- stations retain a small baseline efficiency even with zero workers
|
||||
|
||||
Population growth and decline follow the rules in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
|
||||
- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
|
||||
- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
|
||||
321
docs/TASKS.md
Normal file
321
docs/TASKS.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Tasks
|
||||
|
||||
This document defines the intended order, task, and runtime execution model for the simulation.
|
||||
|
||||
It describes how commander intent becomes executable work.
|
||||
|
||||
## Design Goals
|
||||
|
||||
The task model should support:
|
||||
|
||||
- direct player control
|
||||
- long-lived commander autonomy
|
||||
- clear precedence rules
|
||||
- readable runtime state
|
||||
- consistent execution across movement, logistics, construction, and combat
|
||||
|
||||
## Core Principles
|
||||
|
||||
- commanders decide intent
|
||||
- tasks express executable work
|
||||
- states describe runtime condition
|
||||
- orders can temporarily override autonomy
|
||||
- tasks should be concrete enough for direct simulation execution
|
||||
|
||||
## Control Layers
|
||||
|
||||
The intended execution stack should be:
|
||||
|
||||
1. `goal`
|
||||
2. `order`
|
||||
3. `behavior`
|
||||
4. `task`
|
||||
5. `state`
|
||||
|
||||
This separates long-horizon intent from short-horizon execution.
|
||||
|
||||
## Goals
|
||||
|
||||
Goals are high-level commander intentions.
|
||||
|
||||
Examples:
|
||||
|
||||
- expand into this system
|
||||
- keep this station fueled
|
||||
- defend this claim
|
||||
- protect trade in this region
|
||||
- supply this station with workers
|
||||
|
||||
Goals belong primarily to commanders, not directly to ships.
|
||||
|
||||
## Orders
|
||||
|
||||
Orders are explicit instructions produced by the player or by higher command.
|
||||
|
||||
Orders should survive replanning better than tasks.
|
||||
|
||||
Examples:
|
||||
|
||||
- travel to node
|
||||
- dock at station
|
||||
- claim Lagrange point
|
||||
- build station here
|
||||
- deliver fuel
|
||||
- escort this ship
|
||||
- defend this bubble
|
||||
|
||||
Orders are the main override layer above routine autonomous behavior.
|
||||
|
||||
## Behaviors
|
||||
|
||||
Behaviors are persistent patterns followed when no overriding direct order exists.
|
||||
|
||||
Examples:
|
||||
|
||||
- idle
|
||||
- auto-trade
|
||||
- mine-for-station
|
||||
- region trader
|
||||
- claim defender
|
||||
- station supplier
|
||||
- local defender
|
||||
- patrol route
|
||||
|
||||
Behaviors should continuously refresh tasks as conditions change.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tasks are the immediate executable actions the runtime can carry out.
|
||||
|
||||
Tasks should be concrete and short-horizon.
|
||||
|
||||
Examples:
|
||||
|
||||
- move locally
|
||||
- warp to node
|
||||
- request dock
|
||||
- dock
|
||||
- undock
|
||||
- load cargo
|
||||
- unload cargo
|
||||
- transfer workers
|
||||
- attack target
|
||||
- hold near target
|
||||
- build at construction site
|
||||
- claim node
|
||||
- retreat
|
||||
|
||||
## States
|
||||
|
||||
States describe what an entity is physically or operationally doing right now.
|
||||
|
||||
Examples:
|
||||
|
||||
- idle
|
||||
- local-flight
|
||||
- warp-spooling
|
||||
- in-warp
|
||||
- docking
|
||||
- docked
|
||||
- loading
|
||||
- unloading
|
||||
- attacking
|
||||
- retreating
|
||||
- building
|
||||
- disabled
|
||||
|
||||
States should be readable runtime facts, not overloaded planning abstractions.
|
||||
|
||||
## Precedence Rules
|
||||
|
||||
Task selection should follow this priority:
|
||||
|
||||
1. direct player order
|
||||
2. higher-commander order
|
||||
3. local commander behavior
|
||||
4. safety fallback
|
||||
|
||||
Interpretation:
|
||||
|
||||
- explicit orders override routine autonomy
|
||||
- routine autonomy resumes when those orders end
|
||||
- safety logic may still interrupt if survival requires it
|
||||
|
||||
## Planner Flow
|
||||
|
||||
The intended execution loop is:
|
||||
|
||||
1. commander evaluates world state
|
||||
2. commander updates goals or behavior
|
||||
3. planner resolves the highest-priority active instruction
|
||||
4. planner chooses or updates the current task
|
||||
5. runtime executes the task
|
||||
6. state changes and events feed back into planning
|
||||
|
||||
This is the bridge between command and simulation.
|
||||
|
||||
## Order Lifecycle
|
||||
|
||||
Orders should have an explicit lifecycle.
|
||||
|
||||
Recommended order states:
|
||||
|
||||
- `queued`
|
||||
- `accepted`
|
||||
- `planning`
|
||||
- `executing`
|
||||
- `completed`
|
||||
- `failed`
|
||||
- `cancelled`
|
||||
- `blocked`
|
||||
|
||||
## Task Lifecycle
|
||||
|
||||
Tasks should have a simpler lifecycle.
|
||||
|
||||
Recommended task states:
|
||||
|
||||
- `pending`
|
||||
- `active`
|
||||
- `blocked`
|
||||
- `completed`
|
||||
- `failed`
|
||||
- `cancelled`
|
||||
|
||||
Tasks are shorter-lived than orders and easier to replace.
|
||||
|
||||
## Common Ship Task Kinds
|
||||
|
||||
Recommended core ship task kinds:
|
||||
|
||||
- `idle`
|
||||
- `local-move`
|
||||
- `warp-to-node`
|
||||
- `use-stargate`
|
||||
- `use-ftl`
|
||||
- `dock`
|
||||
- `undock`
|
||||
- `load-cargo`
|
||||
- `unload-cargo`
|
||||
- `load-workers`
|
||||
- `unload-workers`
|
||||
- `mine-node`
|
||||
- `harvest-gas`
|
||||
- `deliver-to-station`
|
||||
- `claim-lagrange-point`
|
||||
- `build-construction-site`
|
||||
- `escort-target`
|
||||
- `attack-target`
|
||||
- `defend-bubble`
|
||||
- `retreat`
|
||||
- `hold-position`
|
||||
|
||||
## Common Station Operational Tasks
|
||||
|
||||
Stations are not ships, but station operation still implies task-like work.
|
||||
|
||||
Examples:
|
||||
|
||||
- publish market orders
|
||||
- update production priority
|
||||
- execute recipe cycle
|
||||
- accept dock request
|
||||
- deny dock request
|
||||
- transfer goods
|
||||
- request defense
|
||||
- request emergency fuel support
|
||||
|
||||
These may be implemented as station jobs, station operations, or station-side tasks.
|
||||
|
||||
## Safety And Fallback Tasks
|
||||
|
||||
Safety logic should interrupt ordinary behavior when required.
|
||||
|
||||
Examples:
|
||||
|
||||
- retreat from combat
|
||||
- flee to nearest allowed station
|
||||
- hold position if no valid route exists
|
||||
- suspend trade when no legal destination exists
|
||||
- wait for fuel, escort, or dock access
|
||||
|
||||
This prevents autonomous loops from becoming self-destructive.
|
||||
|
||||
## Space-Aware Tasking
|
||||
|
||||
Tasks should respect the spatial model in [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md).
|
||||
|
||||
That means:
|
||||
|
||||
- local maneuvering is distinct from warp
|
||||
- docking is local-space work
|
||||
- cargo transfer is local-space work
|
||||
- inter-system travel is distinct from in-system travel
|
||||
|
||||
## Policy-Aware Tasking
|
||||
|
||||
Tasks should respect policies from [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md).
|
||||
|
||||
Examples:
|
||||
|
||||
- do not dock where docking is forbidden
|
||||
- do not trade where access is denied
|
||||
- do not leave assigned region if behavior policy forbids it
|
||||
- do not build where policy would trigger conflict unless ordered
|
||||
|
||||
## Event Integration
|
||||
|
||||
Task and order transitions should generate meaningful events.
|
||||
|
||||
Examples:
|
||||
|
||||
- `order-accepted`
|
||||
- `order-cancelled`
|
||||
- `task-started`
|
||||
- `task-blocked`
|
||||
- `task-completed`
|
||||
- `task-failed`
|
||||
- `behavior-changed`
|
||||
|
||||
See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the event-side model.
|
||||
|
||||
## Data-Model Implication
|
||||
|
||||
The data model should make room for at least:
|
||||
|
||||
- current goal references
|
||||
- active order references
|
||||
- active behavior
|
||||
- active task
|
||||
- current state
|
||||
|
||||
See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the entity-side vocabulary.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- goals, orders, tasks, and states are not the same thing
|
||||
- orders can override ordinary behavior
|
||||
- tasks are the executable layer
|
||||
- states are descriptive runtime condition
|
||||
- safety logic may interrupt behavior
|
||||
- tasking must respect space and policy rules
|
||||
- meaningful task transitions should emit events
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- defines who decides and delegates
|
||||
|
||||
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
|
||||
- defines where tasks can occur
|
||||
|
||||
- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
|
||||
- defines restrictions tasking must obey
|
||||
|
||||
- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
|
||||
- defines the entity fields that hold goals, orders, tasks, and states
|
||||
|
||||
- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md)
|
||||
- defines the event families emitted by task and order transitions
|
||||
196
docs/WORKFORCE.md
Normal file
196
docs/WORKFORCE.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# Workforce
|
||||
|
||||
This document defines population, workforce, habitats, and commander generation.
|
||||
|
||||
Workforce is a station-side resource that connects economy, commanders, logistics, and station efficiency.
|
||||
|
||||
See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the explicit station-side fields implied by this model.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- population exists at stations, not only as an abstract total
|
||||
- each station tracks its own population
|
||||
- factions still have meaningful aggregate population totals
|
||||
- habitats are the source of population growth
|
||||
- workers consume life-support and civilian goods
|
||||
- workforce determines station efficiency
|
||||
- commanders are generated from faction population over time
|
||||
|
||||
## Population Model
|
||||
|
||||
Population should be tracked at two levels:
|
||||
|
||||
- per-station population
|
||||
- per-faction aggregate population
|
||||
|
||||
The station level is the primary simulation truth because population lives, grows, and dies at stations.
|
||||
|
||||
The faction level is the strategic aggregate used for:
|
||||
|
||||
- faction scale
|
||||
- workforce planning
|
||||
- commander availability
|
||||
- demographic growth
|
||||
|
||||
## Habitats
|
||||
|
||||
Population growth should happen only at stations for now.
|
||||
|
||||
Habitat modules are required for population growth.
|
||||
|
||||
Habitats allow stations to:
|
||||
|
||||
- house workers
|
||||
- grow population
|
||||
- sustain future commander generation
|
||||
|
||||
Ships do not generate population.
|
||||
|
||||
## Worker Needs
|
||||
|
||||
Workers consume, per worker:
|
||||
|
||||
- food
|
||||
- water
|
||||
- energy
|
||||
- consumer goods
|
||||
|
||||
These should be understood using the item roles defined in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md).
|
||||
|
||||
If these needs are not met, workers should die over time.
|
||||
|
||||
This should be a gradual attrition model rather than an instant binary failure.
|
||||
|
||||
## Workforce Efficiency
|
||||
|
||||
A workforce is required for peak station performance.
|
||||
|
||||
Each module should have a workforce requirement for `100%` efficiency.
|
||||
|
||||
For now:
|
||||
|
||||
- workforce scales all modules equally
|
||||
- there is no special per-module workforce rule
|
||||
|
||||
A station can still operate without workers, but only at a baseline level.
|
||||
|
||||
Current intended baseline:
|
||||
|
||||
- `10%` efficiency at `0%` workforce
|
||||
|
||||
This means:
|
||||
|
||||
- `0%` workforce satisfaction gives baseline operation
|
||||
- `100%` workforce satisfaction gives peak operation
|
||||
- intermediate staffing gives proportional efficiency
|
||||
|
||||
## Population Transport
|
||||
|
||||
Population can be moved between stations.
|
||||
|
||||
This supports strategies such as:
|
||||
|
||||
- growing population at a major habitat station
|
||||
- feeding workers to industrial stations
|
||||
- staffing newly founded frontier stations
|
||||
- rebuilding stations after demographic collapse
|
||||
|
||||
Population remains a station-side resource, even while being transported.
|
||||
|
||||
## Human Transport Requirement
|
||||
|
||||
Ships need a habitat module to transport humans.
|
||||
|
||||
This keeps population transport distinct from ordinary cargo hauling.
|
||||
|
||||
Related note:
|
||||
|
||||
- livestock modules also exist as part of the food loop
|
||||
|
||||
## Commanders And Population
|
||||
|
||||
Commanders are created from a faction's worker base.
|
||||
|
||||
The intent is:
|
||||
|
||||
- more faction population yields more available commanders over time
|
||||
- commanders are rare relative to workers
|
||||
|
||||
An approximate working rule is acceptable for now.
|
||||
|
||||
Example rule:
|
||||
|
||||
- for each `1000` faction population, one commander is generated every `1 hour`
|
||||
|
||||
The exact formula can change later. The important rule is that commanders are population-backed rather than free.
|
||||
|
||||
## Commander Consumption
|
||||
|
||||
Commanders are consumed permanently when created and assigned.
|
||||
|
||||
They are not temporarily borrowed and returned to a pool.
|
||||
|
||||
If a commander dies:
|
||||
|
||||
- that commander is gone
|
||||
|
||||
This gives commanders real cost and strategic value.
|
||||
|
||||
## Founding And Staffing
|
||||
|
||||
A newly founded station may begin with:
|
||||
|
||||
- zero workers
|
||||
- construction storage
|
||||
- no local commander yet
|
||||
|
||||
It can still exist and operate at baseline efficiency, but it remains weak until supplied with:
|
||||
|
||||
- fuel
|
||||
- workers
|
||||
- support goods
|
||||
- eventually a station commander
|
||||
|
||||
## Failure And Attrition
|
||||
|
||||
If a station loses required support resources, population should die over time.
|
||||
|
||||
Relevant shortages include:
|
||||
|
||||
- food shortage
|
||||
- water shortage
|
||||
- energy shortage
|
||||
- consumer goods shortage
|
||||
|
||||
This gives logistics failure lasting demographic consequences.
|
||||
|
||||
## Ownership And Identity
|
||||
|
||||
Station population is the local operational truth.
|
||||
|
||||
Faction population is the strategic aggregate.
|
||||
|
||||
That distinction is enough for now. It does not require a more complicated ownership doctrine yet.
|
||||
|
||||
## Minimum Rules
|
||||
|
||||
The following rules should remain true unless deliberately revised:
|
||||
|
||||
- population grows only at stations for now
|
||||
- habitat modules are required for growth
|
||||
- workers consume food, water, energy, and consumer goods
|
||||
- workforce affects station efficiency
|
||||
- stations retain a small baseline efficiency at zero workforce
|
||||
- population can be transported between stations
|
||||
- transporting humans requires a habitat-capable ship module
|
||||
- commanders are generated from faction population over time
|
||||
- commanders are permanently consumed when created
|
||||
- dead commanders do not return to the pool
|
||||
|
||||
## Relationship To Other Documents
|
||||
|
||||
- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
|
||||
- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
|
||||
- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
|
||||
- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
|
||||
- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
|
||||
Reference in New Issue
Block a user