# 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