docs: establish official design documentation
This commit is contained in:
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
|
||||
Reference in New Issue
Block a user