The roles system

Tag agents with named labels for targeting, querying, and conditional logic.

Overview

Roles are string tags attached to an agent's in-memory role set. Unlike side (which is a single engine-level value), roles are dynamic, stackable, and invisible to the simulation engine itself — they live entirely in the Python/MAST layer.

Common uses:

Targeting — closest(ship_id, role("enemy")) finds the nearest enemy.
Filtering — broad_test_around(pos, 1000) & role("station") finds all stations in range.
State flags — add "__damaged__" or "exploded" to track object state.
Class membership — ship art IDs are automatically added as roles, so role("cruiser") matches all cruisers.
Side — the object's side string is also included as a role, so role("tsn") matches all TSN objects.

role() returns a set of IDs that have the given role, usable in set operations. Multiple roles can be combined with & (intersection) or | (union).

Quick example

MAST pyMAST

== setup ==
    add_role(enemy_id, "target_priority")

== targeting ==
    nearest = closest(ship_id, role("target_priority"))
    target(ship_id, nearest)

== on_explosion ==
    add_role(ship_id, "exploded")
    remove_role(ship_id, "target_priority")

from sbs_utils.procedural.roles import add_role, remove_role, has_role, role

add_role(enemy_id, "target_priority")
remove_role(enemy_id, "target_priority")

if has_role(enemy_id, "target_priority"):
    log("Still a priority target")

priority_stations = role("target_priority") & role("station")
targets = role("enemy") | role("hostile")

Using with targeting

close = closest(ship_id, role("spy"))
close = closest(ship_id, role("station"))   # ship class names are roles
close = closest(ship_id, role("tsn"))        # side is also a role

System roles

Some roles are managed automatically by the engine and library:

Role	Set by
`"__undamaged__"` / `"__damaged__"`	`grid_rebuild_grid_objects` / `grid_damage_grid_object`
`"exploded"`	`explode_player_ship`
`"_moving_"`	grid movement system
`"damcons"`, `"lifeform"`	`grid_restore_damcons`
ship art ID (e.g. `"tsn_battle_cruiser"`)	`spawn_npc` / `spawn_player`

API

`add_role(set_holder, role)`

Add a role to one or more agents.

Parameters:

Name	Type	Description	Default
`set_holder`	`Agent \| int \| set[Agent \| int]`	Agent(s) to update.	required
`role`	`str`	The role name to add.	required

`all_roles(roles)`

Return the set of agent IDs that hold every one of the given roles.

Parameters:

Name	Type	Description	Default
`roles`	`str`	A comma-separated list of role names.	required

Returns:

Type	Description
	set[int]: IDs of agents that have all specified roles.

`any_role(roles)`

Return the set of agent IDs that hold at least one of the given roles.

Parameters:

Name	Type	Description	Default
`roles`	`str`	A single role name or a comma-separated list.	required

Returns:

Type	Description
	set[int]: IDs of agents with any of the specified roles.

`get_role_list(id_or_obj)`

Return the list of role names held by an agent.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required

Returns:

Type	Description
	list[str]: Role names, or an empty list if the agent does not exist.

`get_role_string(id_or_obj)`

Return a comma-separated string of role names held by an agent.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required

Returns:

Name	Type	Description
`str`		Comma-separated role names, or `""` if the agent does not exist.

`has_any_role(so, roles)`

Return whether an agent holds at least one of the given roles.

Parameters:

Name	Type	Description	Default
`so`	`Agent \| int`	Agent ID or object.	required
`roles`	`str`	A comma-separated list of role names.	required

Returns:

Name	Type	Description
`bool`		`True` if the agent has one or more of the roles.

`has_role(so, role)`

Return whether an agent currently holds a given role.

Parameters:

Name	Type	Description	Default
`so`	`Agent \| int`	Agent ID or object.	required
`role`	`str`	The role name to test for.	required

Returns:

Name	Type	Description
`bool`		`True` if the agent has the role.

`has_roles(so, roles)`

Return whether an agent holds all of the given roles.

Parameters:

Name	Type	Description	Default
`so`	`Agent \| int`	Agent ID or object.	required
`roles`	`str`	A comma-separated list of role names.	required

Returns:

Name	Type	Description
`bool`		`True` if the agent has every role in the list.

`remove_role(agents, role)`

Remove a role from one or more agents.

Parameters:

Name	Type	Description	Default
`agents`	`Agent \| int \| set[Agent \| int]`	Agent(s) to update.	required
`role`	`str`	The role name to remove.	required

`role(role)`

Return the set of agent IDs that currently hold a given role.

Parameters:

Name	Type	Description	Default
`role`	`str`	The role name.	required

Returns:

Type	Description
	set[int]: IDs of all agents with that role.

`role_allies(id_or_obj)`

Return the set of agent IDs allied with the specified object.

Deprecated as of v1.3.0. Prefer the Sides system.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The agent ID or object.	required

Returns:

Type	Description
	set[int]: IDs of all agents on allied sides.

`role_ally_add(id_or_obj, side)`

Add a side to an agent's ally list.

Deprecated as of v1.3.0. Prefer the Sides system.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The agent ID or object to update.	required
`side`	`str`	The side name to add as an ally.	required

`role_ally_remove(id_or_obj, side)`

Remove a side from an agent's ally list.

Deprecated as of v1.3.0. Prefer the Sides system.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The agent ID or object to update.	required
`side`	`str`	The side name to remove from the ally list.	required

`role_are_allies(id_or_obj, other_id_or_obj)`

Return whether two objects share any allied side.

Deprecated as of v1.3.0. Prefer the Sides system.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	First agent ID or object.	required
`other_id_or_obj`	`Agent \| int`	Second agent ID or object.	required

Returns:

Name	Type	Description
`bool`		`True` if both objects have at least one allied side in common.

`role_matches(so, expr)`

Return whether an agent satisfies a role EXPRESSION.

The expression combines role names (a ship's side counts as a role) with set-style operators, evaluated for the single agent so:

| OR -- "__player__ | tsn" (a player OR a tsn ship)
& AND -- "__player__ & tsn" (a tsn player)
- AND-NOT -- "__player__ - cockpit" (a player that is not a fighter)
! NOT -- "!tsn" (anything not tsn); - is BINARY
( ) group -- "(tsn | raider) & !__player__"

Precedence high->low: !, then &/- (left to right), then | -- use parentheses for other groupings. An empty/None expression matches nothing.

Parameters:

Name	Type	Description	Default
`so`	`Agent \| int`	Agent ID or object to test.	required
`expr`	`str`	The role expression.	required

Returns:

Name	Type	Description
`bool`		`True` if the agent satisfies the expression.

`roles_matching(expr)`

Return the set of agent IDs that satisfy a role expression (see :func:role_matches).

Parameters:

Name	Type	Description	Default
`expr`	`str`	The role expression (`\| & - !` and parentheses).	required

Returns:

Type	Description
	set[int]: IDs of all agents matching the expression.