322 lines
6.8 KiB
Markdown
322 lines
6.8 KiB
Markdown
# 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
|