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