Sides system

Query and manage the faction/allegiance side of space objects.

Overview

Every space object has a side string that the simulation uses for targeting and IFF (Identify Friend or Foe). Common side values are "tsn", "tur", "tsc", "skaraan", "biomech", and "unsc". The side is set at spawn time and can be changed in flight.

The side is automatically added as a role, so role("tsn") matches all TSN objects and can be combined with other role queries:

tsn_stations = broad_test_around(pos, 5000) & role("tsn") & role("station")

get_side_for_display returns a human-readable faction name (e.g. "TSN" instead of "tsn"). side_set changes an object's side and the side_changed signal is emitted.

Quick example

MAST pyMAST

== check_side ==
    if get_side(target_id) == "tsc": jump enemy_detected
    if get_side(target_id) == "tsn": jump friendly_detected

== defect ==
    side_set(npc_id, "tsn")
    log("Enemy ship has defected to TSN!")
    ->END

from sbs_utils.procedural.sides import side_set, get_side, get_side_for_display

# Check faction
if get_side(target_id) == "tsc":
    target(ship_id, target_id)

# Change side mid-mission
side_set(npc_id, "tsn")

# Human-readable name
name = get_side_for_display(target_id)  # e.g. "TSN"

Common side values

Side	Faction
`"tsn"`	Terran Stellar Navy
`"tur"`	Tur (hostile)
`"tsc"`	Terran Stellar Command (hostile in some missions)
`"skaraan"`	Skaraan
`"biomech"`	Biomech (Hegemony)
`"unsc"`	UNSC

API

`side_ally_members_set(side)`

Return the set of agent IDs from all sides allied with the given side.

Parameters:

Name	Type	Description	Default
`side`	`str \| int \| Agent`	Side key, side agent ID, or any space object whose side will be used.	required

Returns:

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

`side_are_allies(side1, side2)`

Return whether two sides are allied.

Parameters:

Name	Type	Description	Default
`side1`	`str \| int \| Agent`	First side — key, agent ID, or object.	required
`side2`	`str \| int \| Agent`	Second side — key, agent ID, or object.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the sides have a `side_ally` link.

`side_are_enemies(side1, side2)`

Return whether two sides are hostile to each other.

Parameters:

Name	Type	Description	Default
`side1`	`str \| int \| Agent`	First side — key, agent ID, or object.	required
`side2`	`str \| int \| Agent`	Second side — key, agent ID, or object.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the sides have a `side_hostile` link.

`side_are_neutral(side1, side2)`

Return whether two sides are neutral toward each other.

Parameters:

Name	Type	Description	Default
`side1`	`str \| int \| Agent`	First side — key, agent ID, or object.	required
`side2`	`str \| int \| Agent`	Second side — key, agent ID, or object.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the sides have a `side_neutral` link.

`side_are_same_side(side1, side2)`

Return whether two references resolve to the same side.

Parameters:

Name	Type	Description	Default
`side1`	`str \| int \| Agent`	First side — key, agent ID, or object.	required
`side2`	`str \| int \| Agent`	Second side — key, agent ID, or object.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if both resolve to the same side agent.

`side_display_name(key)`

Return the display name of a side.

Parameters:

Name	Type	Description	Default
`key`	`str \| int \| Agent`	Side key, agent ID, or agent.	required

Returns:

Name	Type	Description
`str`		The side's display name, or `None` if not found.

`side_enemy_members_set(side)`

Return the set of agent IDs from all sides hostile to the given side.

Parameters:

Name	Type	Description	Default
`side`	`str \| int \| Agent`	Side key, side agent ID, or any space object whose side will be used.	required

Returns:

Type	Description
	set[int]: IDs of all space objects on hostile sides.

`side_get_description(key_or_id)`

Return the description text of a side.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required

Returns:

Name	Type	Description
`str`	`str`	The side description, or `""` if not set.

`side_get_display_name(key_or_id)`

Return the display name of a side.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required

Returns:

Name	Type	Description
`str`	`str`	The side's display name, or `""` if not set.

`side_get_relations(side1, side2)`

Return the current diplomatic relationship between two sides.

Parameters:

Name	Type	Description	Default
`side1`	`str \| int \| Agent`	First side — key, agent ID, or object.	required
`side2`	`str \| int \| Agent`	Second side — key, agent ID, or object.	required

Returns:

Type	Description
	sbs.DIPLOMACY: One of `ALLIED`, `HOSTILE`, `NEUTRAL`, or `UNKNOWN`.

`side_get_side_color(key_or_id, default='#0F0')`

Return the icon color assigned to a side.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required
`default`	`str`	Color to return if the side has no color set. Defaults to `"#0F0"` (green).	`'#0F0'`

Returns:

Name	Type	Description
`str`	`str`	The hex color code assigned to the side, or `default`.

`side_get_side_icon_index(key_or_id)`

Return the icon index for a side.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required

Returns:

Name	Type	Description
`int`	`int`	The icon index, or `-1` if not found.

`side_is_color_used(color)`

Return whether any side is currently using a given icon color.

Parameters:

Name	Type	Description	Default
`color`	`str`	Hex color code to check for.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if at least one side uses that color.

`side_keys_set()`

Return the set of key strings for all registered sides.

Returns:

Type	Description
	set[str]: Side key strings (e.g. `"player"`, `"enemy"`).

`side_members_set(side)`

Return the set of agent IDs that belong to a given side.

Prefer this over role(side) as it correctly excludes the side agent itself from the result.

Parameters:

Name	Type	Description	Default
`side`	`str \| int \| Agent`	Side key, side agent ID, side agent, or any space object whose side will be used.	required

Returns:

Type	Description
	set[int]: IDs of all space objects on the specified side.

`side_set_description(key_or_id, desc)`

Set the description text for a side.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required
`desc`	`str`	The new description text.	required

`side_set_display_name(key_or_id, name)`

Set the display name for a side and update all ships on that side.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required
`name`	`str`	The new display name.	required

`side_set_icon_color(key_or_id, color)`

Set the icon color for a side, changing how its ships appear on the 2D map.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required
`color`	`str`	Hex color code or named color (e.g. `"#FF0000"` or `"red"`).	required

`side_set_object_side(id_or_obj, key)`

Assign a side to one or more space objects.

Updates both the side (key) and side_display (name) attributes on each object.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`int \| Agent \| list[int \| Agent] \| set[int \| Agent]`	The object(s) to update.	required
`key`	`str \| int \| Agent`	The target side — a key string, side agent ID, or any object whose side will be used.	required

`side_set_relations(side1, side2, relation)`

Set the diplomatic relationship between two sides.

Updates both the link-based relationship used by the scripting API and the engine's own side relationship table for 2D map rendering. Emits the side_relations_updated signal.

Parameters:

Name	Type	Description	Default
`side1`	`str \| int \| Agent`	First side — key, agent ID, or object.	required
`side2`	`str \| int \| Agent`	Second side — key, agent ID, or object.	required
`relation`	`DIPLOMACY`	New relationship value. Use `sbs.DIPLOMACY.ALLIED`, `HOSTILE`, `NEUTRAL`, or `UNKNOWN`.	required

`side_set_ship_allies_and_enemies(ship)`

No-op placeholder — deprecated as of v1.3.0, to be removed in a future version.

Parameters:

Name	Type	Description	Default
`ship`	`Agent \| int`	Unused.	required

`side_set_side_icon_index(key_or_id, icon_index)`

Set the icon index for a side, changing how its ships appear on the 2D map.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, agent ID, or object.	required
`icon_index`	`int`	The icon index to use.	required

`sides_set()`

Return the set of IDs for all registered sides (agents with the __side__ role).

Returns:

Type	Description
	set[int]: IDs of all side agents.

`to_side_id(key_or_id_or_object)`

Resolve any side reference to the side agent's ID.

Accepts a side key string, a side agent ID, a side agent object, or any space object (in which case its side property is used).

Parameters:

Name	Type	Description	Default
`key_or_id_or_object`	`str \| int \| Agent`	Side key, side agent ID, side agent, or a space object whose side should be resolved.	required

Returns:

Type	Description
	int \| None: The side agent ID, or `None` if not found.

`to_side_object(key_or_id)`

Resolve any side reference to the side agent object.

Parameters:

Name	Type	Description	Default
`key_or_id`	`str \| int \| Agent`	Side key, side agent ID, or any space object whose side will be resolved.	required

Returns:

Type	Description
	Agent \| None: The side agent, or `None` if not found.