The mission system

Structured mission lifecycle runner with init, start, objective, and complete phases.

Overview

mission_run spawns a task that drives a MAST label through a defined lifecycle. The label should contain named cmd_map blocks (using the MAST /// inline route syntax) for each phase:

Block	When it runs
`///init`	Immediately, once
`///start`	After `__START__` is set to `True` in the task
`///objective`	Each tick while running; returns `OK_SUCCESS` when the objective is met
`///complete`	Each tick while running; returns `OK_SUCCESS` when the mission is complete
`///abort`	Each tick while running; returning `FAIL_END` aborts the mission

The mission_runner generator drives these blocks in sequence. init runs first. The runner then waits until something sets task.__START__ = True before running start. After that, abort, objective, and complete are polled each tick.

This is the same pattern used by the built-in objective system — use mission_run for higher-level structured missions, and the objective module for lower-level task tracking.

Quick example

MAST pyMAST

== setup ==
    mission_run(escort_mission)
    ->END

== escort_mission ==
    ///init
    spawn_escort_target()
    ///start
    log("Escort the freighter to the station.")
    ///objective
    if freighter_arrived(): OK_SUCCESS
    OK_RUN_AGAIN
    ///abort
    if freighter_destroyed(): FAIL_END
    OK_RUN_AGAIN
    ///complete
    log("Mission complete! The freighter has arrived safely.")
    OK_SUCCESS

from sbs_utils.procedural.mission import mission_run

task = mission_run(escort_mission, data={"ship_id": ship_id})

API

`mission_find(agent_id)`

Find a mission by agent ID — currently unused and always returns None.

Parameters:

Name	Type	Description	Default
`agent_id`	`int`	Agent ID to search for.	required

`mission_run(label, data=None)`

Schedule a mission label to run as a new task.

Spawns a task running mission_runner which drives the mission label through its full init / start / objective / complete lifecycle.

Parameters:

Name	Type	Description	Default
`label`	`str \| Label`	The mission label to execute.	required
`data`	`dict`	Variables to pass into the mission. Defaults to None.	`None`

Returns:

Name	Type	Description
`MastAsyncTask`		The scheduled task.

`mission_runner(label=None, data=None)`

Generator that drives a structured mission label through its lifecycle.

Executes the init, start, abort, objective, and complete sub-blocks of a mission label in order, yielding PollResults at each step. If label is None, reads the label and data from the current task's variables (used when spawned by mission_run).

Parameters:

Name	Type	Description	Default
`label`	`str \| Label`	The mission label to run. Defaults to `None` (reads from the current task).	`None`
`data`	`dict`	Variables to pass into the mission sub-task. Defaults to None.	`None`

Yields:

Name	Type	Description
`PollResults`		`OK_RUN_AGAIN` while running, `OK_END` on completion or abort.