space-game/docs/COMMANDERS.md

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.

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

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

  • defines where action happens

• ECONOMY.md

  • defines how commanders express market participation

• SHIPS.md

  • defines ship capabilities and behavior expectations

• STATIONS.md

  • defines station roles and station-side responsibilities

• WORKFORCE.md

  • defines population, worker growth, and commander generation

• POLICIES.md

  • defines access rules and operational restrictions commanders can set

• COMBAT.md

  • defines how commanders apply threat posture and engagement behavior