6.7 KiB
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:
goalorderbehaviortaskstate
This separates long-horizon intent from short-horizon execution.
Goals
Goals are high-level commander intentions.
Examples:
- expand into this system
- 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 anchor
- dock at station
- claim construction anchor
- build station here
- escort this ship
- defend this localspace
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:
- direct player order
- higher-commander order
- local commander behavior
- 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:
- commander evaluates world state
- commander updates goals or behavior
- planner resolves the highest-priority active instruction
- planner chooses or updates the current task
- runtime executes the task
- 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:
queuedacceptedplanningexecutingcompletedfailedcancelledblocked
Task Lifecycle
Tasks should have a simpler lifecycle.
Recommended task states:
pendingactiveblockedcompletedfailedcancelled
Tasks are shorter-lived than orders and easier to replace.
Common Ship Task Kinds
Recommended core ship task kinds:
idlelocal-movewarp-to-nodeuse-stargateuse-ftldockundockload-cargounload-cargoload-workersunload-workersmine-nodeharvest-gasdeliver-to-stationclaim-lagrange-pointbuild-construction-siteescort-targetattack-targetdefend-bubbleretreathold-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
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 escort, or dock access
This prevents autonomous loops from becoming self-destructive.
Space-Aware Tasking
Tasks should respect the spatial model in UNIVERSE-MODEL.md.
That means:
- local maneuvering is distinct from warp
- docking is localspace work
- cargo transfer is localspace work
- inter-system travel is distinct from in-system travel
Policy-Aware Tasking
Tasks should respect policies from 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-acceptedorder-cancelledtask-startedtask-blockedtask-completedtask-failedbehavior-changed
See 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 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
-
- defines who decides and delegates
-
- defines where tasks can occur
-
- defines restrictions tasking must obey
-
- defines the entity fields that hold goals, orders, tasks, and states
-
- defines the event families emitted by task and order transitions