The routes module

Register and manage MAST route handlers from Python.

Overview

Routes are MAST labels prefixed with // that are invoked automatically by the engine when specific events occur (damage, console focus, object selection, etc.). The routes module provides the procedural API for registering route handlers dynamically from Python or MAST, without requiring them to be declared statically in a .mast file.

route_schedule registers a label as a handler for a given route path. route_clear removes it. These functions are used internally by the library to wire up system routes, but mission scripts can use them to dynamically enable or disable route handlers mid-mission.

See the Routes overview for the full list of route paths and their trigger conditions.

Quick example

MAST pyMAST

== enable_damage_handler ==
    route_schedule("//damage/internal", on_internal_damage)
    ->END

== on_internal_damage ==
    grid_take_internal_damage_at(DAMAGE_TARGET_ID, EVENT.source_point)
    ->END

from sbs_utils.procedural.routes import route_schedule, route_clear

route_schedule("//damage/internal", on_internal_damage_label)
route_clear("//damage/internal", on_internal_damage_label)

API

RouteCommsFocus

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteCommsFocus
@label
def handle_comms_focus():
    ....
    yield PollResults.OK_YIELD

RouteCommsMessage

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteCommsMessage
@label
def handle_comms_message():
    ....
    yield PollResults.OK_YIELD

RouteCommsSelect

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteCommsSelect
@label
def handle_comms_select():
    ....
    yield PollResults.OK_YIELD

RouteDamageDestroy

Bases: RouteLifetime

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteDestroy
@label
def handle_destroy():
    ....
    yield PollResults.OK_YIELD

RouteDamageHeat

Bases: RouteDamageSource

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteDamageHeat
@label
def handle_damage_heat():
    ....
    yield PollResults.OK_YIELD

RouteDamageInternal

Bases: RouteDamageSource

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteDamageInternal
@label
def handle_damage_internal():
    ....
    yield PollResults.OK_YIELD

RouteDamageKilled

Bases: RouteLifetime

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteDestroy
@label
def handle_destroy():
    ....
    yield PollResults.OK_YIELD

RouteDamageObject

Bases: RouteDamageSource

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteDamageObject
@label
def handle_damage_object():
    ....
    yield PollResults.OK_YIELD

RouteDockHangar

Bases: RouteLifetime

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteDockHangar
@label
def handle_dock():
    ....
    yield PollResults.OK_YIELD

RouteGridFocus

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteGridFocus
@label
def handle_grid_focus():
    ....
    yield PollResults.OK_YIELD

RouteGridMessage

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteGridMessage
@label
def handle_grid_message():
    ....
    yield PollResults.OK_YIELD

RouteGridPoint

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteGridPoint
@label
def handle_grid_point():
    ....
    yield PollResults.OK_YIELD

RouteGridSelect

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteGridSelect
@label
def handle_grid_select():
    ....
    yield PollResults.OK_YIELD

RouteGridSpawn

Bases: RouteLifetime

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteGridSpawn
@label
def handle_grid_spawn():
    ....
    yield PollResults.OK_YIELD

RouteLaunchDrone

Bases: object

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteLaunchDrone
@label
def handle_drone_launch():
    ....
    yield PollResults.OK_YIELD

RouteLaunchMissile

Bases: object

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteLaunchMissile
@label
def handle_missile_launch():
    ....
    yield PollResults.OK_YIELD

RouteScienceFocus

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteScienceFocus
@label
def handle_science_focus():
    ....
    yield PollResults.OK_YIELD

RouteScienceMessage

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteScienceMessage
@label
def handle_science_message():
    ....
    yield PollResults.OK_YIELD

RouteSciencePoint

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteSciencePoint
@label
def handle_science_point():
    ....
    yield PollResults.OK_YIELD

RouteScienceSelect

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteScienceSelect
@label
def handle_science_select():
    ....
    yield PollResults.OK_YIELD

RouteSpawn

Bases: RouteLifetime

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteSpawn
@label
def handle_spawn():
    ....
    yield PollResults.OK_YIELD

RouteWeaponsFocus

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteWeaponsFocus
@label
def handle_weapons_focus():
    ....
    yield PollResults.OK_YIELD

RouteWeaponsPoint

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteWeaponsPoint
@label
def handle_weapons_point():
    ....
    yield PollResults.OK_YIELD

RouteWeaponsSelect

Bases: RouteConsole

decorator for routing to a python function or python class method

Note

The route is expected to be a label

Example

@RouteWeaponsSelect
@label
def handle_weapons_select():
    ....
    yield PollResults.OK_YIELD

follow_route_select_comms(origin_id, selected_id)

Programmatically fire the comms selection route as if the player made a selection.

Parameters:

Name	Type	Description	Default
origin_id	Agent | int	The player ship agent ID or object.	required
selected_id	Agent | int	The target space object agent ID or object.	required

follow_route_select_grid(origin_id, selected_id)

Programmatically fire the grid selection route as if the player made a selection.

Parameters:

Name	Type	Description	Default
origin_id	Agent | int	The player ship agent ID or object.	required
selected_id	Agent | int	The target grid object agent ID or object.	required

follow_route_select_science(origin_id, selected_id)

Programmatically fire the science selection route as if the player made a selection.

Parameters:

Name	Type	Description	Default
origin_id	Agent | int	The player ship agent ID or object.	required
selected_id	Agent | int	The target space object agent ID or object.	required

route_change_console(label)

Set the label shown when the "change console" button is pressed.

Typically redirects the console GUI to a console-selection screen.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to display.	required

route_collision_interactive(label)

Run a label each time an interactive collision event occurs.

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleCollision		Route handle (rarely needed to cancel the route).

route_collision_passive(label)

Run a label each time a passive space object is involved in a collision.

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleCollision		Route handle (rarely needed to cancel the route).

route_common_navigate(path, label)

Register a label under a navigation path in the button navigation map.

Parameters:

Name	Type	Description	Default
path	str	The navigation path key to extend.	required
label	str | Label	The label to add under that path.	required

route_comms_navigate(path, label)

Register a label under a comms navigation path (auto-prefixes comms/).

Parameters:

Name	Type	Description	Default
path	str	Navigation sub-path (e.g. "hail" → "comms/hail"). Pass "" to register at the root comms path.	required
label	str | Label	The label to add under that path.	required

route_console_mainscreen_change(label)

Set the label shown when the main-screen view changes.

Typically redirects the console GUI to a gui_console view.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to display.	required

route_damage_destroy(label)

Run a label each time a space object is destroyed. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleLifetime		Route handle (rarely needed to cancel the route).

route_damage_heat(label)

Run a label each time a player ship takes heat damage. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleDamage		Route handle (rarely needed to cancel the route).

route_damage_internal(label)

Run a label each time a player ship takes internal damage. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleDamage		Route handle (rarely needed to cancel the route).

route_damage_killed(label)

Run a label when a space object is about to be removed from the engine.

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleDamage		Route handle (rarely needed to cancel the route).

route_damage_object(label)

Run a label each time a space object takes hull damage. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleDamage		Route handle (rarely needed to cancel the route).

route_dock_hangar(label)

Run a label each time a space object docks. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleLifetime		Route handle (rarely needed to cancel the route).

route_focus_comms(label)

Run a label on every comms selection change (not for long-running tasks).

Use route_select_comms for tasks that need to await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_focus_comms_2d(label)

Run a label on every 2D-comms selection change (not for long-running tasks).

Use route_select_comms for tasks that need to await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_focus_grid(label)

Run a label on every engineering-grid selection change (not for long-running tasks).

Use route_select_grid for tasks that need to await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_focus_normal(label)

Run a label on every normal-view selection change (not for long-running tasks).

Use route_select_comms for tasks that need to await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_focus_science(label)

Run a label on every science selection change (not for long-running tasks).

Use route_select_science for tasks that need to await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_focus_weapons(label)

Run a label on every weapons selection change (not for long-running tasks).

Use route_select_weapons for tasks that need to await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_gui_navigate(path, label)

Register a label under a GUI navigation path (auto-prefixes gui/).

Parameters:

Name	Type	Description	Default
path	str	Navigation sub-path. Pass "" to register at the root GUI path.	required
label	str | Label	The label to add under that path.	required

route_launch_drone(label)

Run a label each time a drone is launched. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleLaunch		Route handle (rarely needed to cancel the route).

route_launch_missile(label)

Run a label each time a missile is launched. Not for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleLaunch		Route handle (rarely needed to cancel the route).

route_message_science(label)

Run a label on each science message event. Supports await scan.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_object_grid(label)

Run a label when a grid-object event fires (e.g. object arrives at a location).

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_point_comms(label)

Run a label when a point (click) event occurs on the comms view.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_point_comms_2d(label)

Run a label when a point (click) event occurs on the 2D comms view.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_point_grid(label)

Run a label when a point (click) event occurs on the engineering grid.

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_point_normal(label)

Run a label when a point (click) event occurs on the normal view.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_point_science(label)

Run a label when a point (click) event occurs on the science 2D view.

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_point_weapons(label)

Run a label when a point (click) event occurs on the weapons 2D view.

Not intended for long-running tasks.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_science_navigate(path, label)

Register a label under a science navigation path (auto-prefixes science/).

Parameters:

Name	Type	Description	Default
path	str	Navigation sub-path. Pass "" to register at the root science path.	required
label	str | Label	The label to add under that path.	required

route_select_comms(label)

Run a label each time a comms selection is made. Supports await comms.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_select_comms_2d(label)

Run a label each time a 2D-comms selection is made. Supports await comms.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_select_grid(label)

Run a label each time an engineering-grid selection is made. Supports await.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_select_normal(label)

Run a label each time a normal-view selection is made. Supports await comms.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_select_science(label)

Run a label each time a science selection is made. Supports await scan.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_select_weapons(label)

Run a label each time a weapons selection is made.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleConsoleSelect		Route handle (rarely needed to cancel the route).

route_spawn(label)

Run a label each time a space object is spawned.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleLifetime		Route handle (rarely needed to cancel the route).

route_spawn_grid(label)

Run a label each time a grid object is spawned.

Parameters:

Name	Type	Description	Default
label	str | Label	The label to run.	required

Returns:

Name	Type	Description
HandleLifetime		Route handle (rarely needed to cancel the route).