The query module

Resolve and convert agent IDs, objects, and collections between formats.

Overview

All procedural API functions accept agents in multiple forms — raw integer IDs, Agent objects, CloseData (returned by closest), or SpawnData (returned by spawn calls). The query module provides the conversion functions that make this work.

The most commonly used functions:

to_id — extract an integer ID from anything.
to_object — resolve to an Agent object (returns None if destroyed).
to_set — normalise any collection into a set[int] of IDs.
to_list — normalise any collection into a list.
object_exists — check if an object is still alive in the simulation.

The is_* functions test which ID category a value belongs to. This matters because clients, space objects, grid objects, and tasks all share the same ID space but use different high bits.

Quick example

MAST pyMAST

== check_target ==
    enemy_id = to_id(closest_enemy)
    obj = to_object(enemy_id)
    if object_exists(enemy_id): target(ship_id, enemy_id)

from sbs_utils.procedural.query import (
    to_id, to_object, to_set, object_exists,
    is_space_object_id, is_client_id,
    get_comms_selection, set_science_selection,
)

enemy_id = to_id(spawn_data_or_agent_or_int)
obj = to_object(enemy_id)

if object_exists(enemy_id):
    target(ship_id, enemy_id)

comms_target = get_comms_selection(ship_id)
set_science_selection(ship_id, enemy_id)

ID type detection

Function	True when
`is_space_object_id(id)`	NPC, player ship, station, nebula, etc.
`is_grid_object_id(id)`	Engineering-grid object
`is_client_id(id)`	Player console / client
`is_task_id(id)`	MAST task
`is_story_id(id)`	Story agent (e.g. Fleets)

Engine data-set (blob)

Space and grid objects have an engine-level data blob for engine-readable attributes (e.g. dock_state, system_damage). Use to_blob / to_data_set to get the blob, then call .get(key) / .set(key, value, index):

blob = to_blob(ship_id)
damage = blob.get("system_damage", 0)  # index defaults to 0
blob.set("dock_state", "docked", 0)

API

`all_objects_exists(the_set)`

Return whether every object in a collection exists in the simulation.

Parameters:

Name	Type	Description	Default
`the_set`	`Agent \| int \| set[Agent \| int] \| list[Agent \| int]`	One or more agent IDs or objects.	required

Returns:

Name	Type	Description
`bool`		`True` if all objects exist; `False` if any is missing.

`are_variables_defined(keys)`

Return whether all named variables are defined in the current MAST task.

Parameters:

Name	Type	Description	Default
`keys`	`str`	Comma-separated variable names to check.	required

Returns:

Name	Type	Description
`bool`		`True` if every key is defined in the current task scope.

`dec_disable_selection(id_or_obj, console_selected_UID)`

Decrement the disable-count for a console selection.

Reverses an inc_disable_selection call. When the counter reaches zero the console is no longer suppressed.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`console_selected_UID`	`str`	The blob key for the console (e.g. `"weapon_target_UID"`).	required

`get_comms_selection(id_or_not)`

Return the ID of the object currently selected on the comms console.

Parameters:

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

Returns:

Type	Description
	int \| None: The selected agent ID, or `None` if unavailable.

`get_crew(id_or_obj)`

Get the crew string of a space object (defaults to the side from shipData).

Parameters:

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

Returns:

Name	Type	Description
`str`		The crew string, or `""` if the object does not exist.

`get_data_set_value(id_or_obj, key, index=0)`

Get a value from the engine data-set (blob) of a space or grid object.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The agent ID or object.	required
`key`	`str`	The data-set key.	required
`index`	`int`	The slot index within that key. Defaults to 0.	`0`

Returns:

Name	Type	Description
`any`		The stored value, or `None` if the object or key is not found.

`get_engine_data_set(id_or_obj)`

Return the engine data-set (blob) for an agent.

Parameters:

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

Returns:

Type	Description
	data_set \| None: The engine data-set, or `None` if not found.

`get_grid_selection(id_or_not)`

Return the ID of the object currently selected on the engineering grid console.

Parameters:

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

Returns:

Type	Description
	int \| None: The selected agent ID, or `None` if unavailable.

`get_origin(id_or_obj)`

Get the origin string of a space object (defaults to the side from shipData).

Parameters:

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

Returns:

Name	Type	Description
`str`		The origin string, or `""` if the object does not exist.

`get_race(id_or_obj)`

Return the race string of a space object (defaults to side from shipData).

Parameters:

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

Returns:

Name	Type	Description
`str`		The race string, or `""` if the object does not exist.

`get_science_selection(id_or_not)`

Return the ID of the object currently selected on the science console.

Parameters:

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

Returns:

Type	Description
	int \| None: The selected agent ID, or `None` if unavailable.

`get_side(id_or_obj)`

Return the side string of an agent.

Parameters:

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

Returns:

Name	Type	Description
`str`		The side string, or `""` if the object does not exist.

`get_side_display(id_or_obj)`

Return the display name of an agent's side.

Parameters:

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

Returns:

Name	Type	Description
`str`		The side display string, or `""` if the object does not exist.

`get_weapons_selection(id_or_not)`

Return the ID of the object currently selected on the weapons console.

Parameters:

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

Returns:

Type	Description
	int \| None: The selected agent ID, or `None` if unavailable.

`inc_disable_selection(id_or_obj, console_selected_UID)`

Increment the disable-count for a console selection and clear it.

Increments an internal counter tracking how many callers have suppressed the selection for this console, then zeroes the console's selected UID in the blob so the console has no active target.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`console_selected_UID`	`str`	The blob key for the console (e.g. `"weapon_target_UID"`).	required

`is_client_id(id)`

Return whether an ID belongs to a client (player console) agent.

Parameters:

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

Returns:

Name	Type	Description
`bool`		`True` if the client-console bit (0x8000…) is set.

`is_grid_object_id(id)`

Return whether an ID belongs to an engineering-grid object.

Parameters:

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

Returns:

Name	Type	Description
`bool`		`True` if the grid-object bit (0x2000…) is set.

`is_space_object_id(id)`

Return whether an ID belongs to a space object.

Parameters:

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

Returns:

Name	Type	Description
`bool`		`True` if the space-object bit (0x4000…) is set.

`is_story_id(id)`

Return whether an ID belongs to a story agent (not an engine object, e.g. Fleets).

Parameters:

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

Returns:

Name	Type	Description
`bool`		`True` if the ID has the story-object bit set.

`is_task_id(id)`

Return whether an ID belongs to a MAST task.

Parameters:

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

Returns:

Name	Type	Description
`bool`		`True` if the task-id bit (0x0080…) is set.

`object_exists(so_id)`

Return whether an object currently exists in the simulation.

Parameters:

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

Returns:

Name	Type	Description
`bool`		`True` if the engine reports the object present.

`random_id(the_set)`

Return the ID of a randomly chosen element from a collection.

Parameters:

Name	Type	Description	Default
`the_set`	`set[Agent \| int]`	A set or list of agent IDs or objects.	required

Returns:

Type	Description
	int \| None: A random agent ID, or `None` if the collection is empty.

`random_object(the_set)`

Return a randomly chosen agent object from a collection.

Parameters:

Name	Type	Description	Default
`the_set`	`set[Agent \| int]`	A set or list of agent IDs or objects.	required

Returns:

Type	Description
	Agent \| None: A random agent, or `None` if the collection is empty.

`random_object_list(the_set, count=1)`

Return a list of randomly chosen agent objects from a collection.

Parameters:

Name	Type	Description	Default
`the_set`	`set[Agent \| int]`	A set or list of agent IDs or objects.	required
`count`	`int`	Number of objects to pick. Defaults to 1.	`1`

Returns:

Type	Description
	list[Agent]: Randomly selected agents (may contain duplicates).

`safe_int(s, defa=0)`

Convert a string to an integer, returning a default on failure.

Parameters:

Name	Type	Description	Default
`s`	`str \| any`	The value to convert. Expected to be a string.	required
`defa`	`int`	Value returned if `s` is not a valid integer. Defaults to 0.	`0`

Returns:

Name	Type	Description
`int`		The converted integer, or `defa`.

`set_comms_selection(id_or_not, other_id_or_obj)`

Set the selected object on the comms console of a player ship.

Parameters:

Name	Type	Description	Default
`id_or_not`	`Agent \| int`	The player ship agent ID or object.	required
`other_id_or_obj`	`Agent \| int`	The object to select.	required

`set_console_selection(id_or_not, other_id_or_obj, console)`

Set the selected object for a named console on a player ship.

Parameters:

Name	Type	Description	Default
`id_or_not`	`Agent \| int`	The player ship agent ID or object.	required
`other_id_or_obj`	`Agent \| int`	The object to select, or `0` to clear.	required
`console`	`str`	The blob key for the console (e.g. `"comms_target_UID"`).	required

`set_data_set_value(to_update, key, value, index=0)`

Set a value in the engine data-set (blob) for one or more space or grid objects.

If to_update is a set or list, the value is applied to each member.

Parameters:

Name	Type	Description	Default
`to_update`	`Agent \| int \| set[Agent \| int] \| list[Agent \| int]`	The agent(s) to update.	required
`key`	`str`	The data-set key.	required
`value`	`any`	The value to store.	required
`index`	`int`	The slot index within that key. Defaults to 0.	`0`

`set_grid_selection(id_or_not, other_id_or_obj)`

Set the selected object on the engineering grid console of a player ship.

Parameters:

Name	Type	Description	Default
`id_or_not`	`Agent \| int`	The player ship agent ID or object.	required
`other_id_or_obj`	`Agent \| int`	The object to select.	required

`set_science_selection(id_or_not, other_id_or_obj)`

Set the selected object on the science console of a player ship.

Parameters:

Name	Type	Description	Default
`id_or_not`	`Agent \| int`	The player ship agent ID or object.	required
`other_id_or_obj`	`Agent \| int`	The object to select.	required

`set_weapons_selection(id_or_not, other_id_or_obj)`

Set the selected object on the weapons console of a player ship.

Parameters:

Name	Type	Description	Default
`id_or_not`	`Agent \| int`	The player ship agent ID or object.	required
`other_id_or_obj`	`Agent \| int`	The object to select.	required

`to_blob(id_or_obj)`

Return the engine data-set (blob) for an agent. Same as to_data_set.

Parameters:

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

Returns:

Type	Description
	data_set \| None: The engine data-set, or `None` if the object does not exist.

`to_client_object(other)`

Resolve a client/console ID or Agent to its Agent object.

Returns None when the ID is not a valid client ID or the agent no longer exists.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| int`	Client ID or agent to resolve.	required

Returns:

Type	Description
	Agent \| None: The client agent, or `None`.

`to_data_set(id_or_obj)`

Return the engine data-set (blob) for an agent. Same as to_blob.

Parameters:

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

Returns:

Type	Description
	data_set \| None: The engine data-set, or `None` if the object does not exist.

`to_engine_object(id_or_obj)`

Return the C++ engine-object pointer for an agent.

Parameters:

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

Returns:

Type	Description
	pointer \| None: The underlying C++ engine-object, or `None` if the agent does not exist.

`to_grid_object(other)`

Resolve an ID or Agent to a GridObject agent.

Returns None when the ID is not a grid-object ID or the object no longer exists.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| CloseData \| int`	ID or agent to resolve.	required

Returns:

Type	Description
	Agent \| None: The grid-object agent, or `None`.

`to_id(other)`

Extract the integer ID from an agent, CloseData, SpawnData, or bare int.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| CloseData \| SpawnData \| int`	Value to convert.	required

Returns:

Name	Type	Description
`int`		The integer agent ID.

`to_id_list(the_set)`

Convert a set or list of agents/IDs to a list of integer IDs.

Parameters:

Name	Type	Description	Default
`the_set`	`set[Agent \| int] \| list[Agent \| int]`	IDs or agent objects.	required

Returns:

Type	Description
	list[int]: Resolved integer IDs; unresolvable items are excluded.

`to_list(other)`

Normalize any agent-like value or collection into a list.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| CloseData \| int \| set \| list \| None`	Value to normalize.	required

Returns:

Name	Type	Description
`list`		A list containing whatever was passed in; `None` becomes `[]`.

`to_object(other)`

Resolve an ID, CloseData, or SpawnData to its Agent object.

Returns None when the agent no longer exists.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| CloseData \| SpawnData \| int`	Value to resolve.	required

Returns:

Type	Description
	Agent \| None: The agent, or `None` if it could not be resolved.

`to_object_list(the_set)`

Convert a set or list of IDs/agents to a list of Agent objects (excluding None).

Parameters:

Name	Type	Description	Default
`the_set`	`set[Agent \| int] \| list[Agent \| int]`	IDs or agent objects.	required

Returns:

Type	Description
	list[Agent]: Resolved Agent objects; items that cannot be resolved are excluded.

`to_py_object_list(the_set)`

Convert a set of IDs to a list of Agent objects.

Parameters:

Name	Type	Description	Default
`the_set`	`set[int]`	A set of agent IDs.	required

Returns:

Type	Description
	list[Agent]: Agents resolved from the set; items that no longer exist are included as `None`.

`to_set(other)`

Normalize any agent-like value or collection into a set of integer IDs.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| CloseData \| int \| set \| list \| None`	Value to normalize.	required

Returns:

Type	Description
	set[int]: A set of integer IDs; `None` becomes an empty set.

`to_space_object(other)`

Resolve an ID or Agent to a SpaceObject agent (NPC, player, or terrain).

Returns None when the ID is not a space-object ID or the object no longer exists.

Parameters:

Name	Type	Description	Default
`other`	`Agent \| CloseData \| int`	ID or agent to resolve.	required

Returns:

Type	Description
	Agent \| None: The space-object agent, or `None`.

`to_space_object_list(the_set)`

Convert a set or list of IDs/agents to a list of SpaceObject agents (excluding None).

Parameters:

Name	Type	Description	Default
`the_set`	`set[Agent \| int] \| list[Agent \| int]`	IDs or agent objects.	required

Returns:

Type	Description
	list[Agent]: Space-object agents only; grid/client IDs are excluded.