Grid object system

Query, move, and theme engineering-grid objects on player ships.

Overview

Engineering-grid objects are the nodes visible on the damage-control console: system rooms (weapon, engine, sensor, shield), hallways, damcon-team crew, markers, and tools. Each is an Agent with a host ship ID and a position in a 2D grid coordinate space.

Common tasks:

grid_objects(ship_id) — get the set of all grid-object IDs on a ship. Combine with role() to filter by type: grid_objects(ship_id) & role("engine").
grid_objects_at(ship_id, x, y) — get objects at a specific cell.
grid_closest(id, candidates) — find the nearest grid object to another.
grid_move(id, x, y) — path the grid object to a target cell.
grid_pos_data(id) — get current (x, y, path_length) of a moving object.

The theme system controls icon appearance. grid_get_grid_theme and grid_get_item_theme_data look up icon indices, colors, and damage colors by role, falling back to "default" entries.

Quick example

MAST pyMAST

== repair_run ==
    damaged = grid_objects(ship_id) & role("__damaged__")
    if len(damaged) == 0: jump done
    target_go = to_object(next(iter(damaged)))
    x, y, _ = grid_pos_data(target_go.id)
    grid_move(damcon_id, int(x), int(y))

from sbs_utils.procedural.grid import (
    grid_objects, grid_objects_at, grid_closest,
    grid_move, grid_pos_data, grid_get_grid_theme,
)
from sbs_utils.procedural.roles import role

damaged_engines = grid_objects(ship_id) & role("__damaged__") & role("engine")
grid_move(damcon_id, target_x, target_y)
curx, cury, path_len = grid_pos_data(damcon_id)

Grid roles

Role	Objects
`"weapon"`	Weapon system nodes
`"engine"`	Engine system nodes
`"sensor"`	Sensor system nodes
`"shield"`	Shield system nodes
`"damcons"` / `"lifeform"`	Damcon crew members
`"marker"`	Position marker
`"rally_point"`	Damcon idle point
`"hallway"`	Damage-fire hallway markers
`"__undamaged__"` / `"__damaged__"`	Damage state

API

`get_open_grid_points(id_or_obj)`

Gets a list of open grid locations

Parameters:

Name	Type	Description	Default
`id_or_obj`	`agent`	agent id or object to check	required

Returns:

Name	Type	Description
`set`	`set[Vec3]`	a set of Vec3 with x and y set

`grid_clear_detailed_status(id_or_obj)`

Clear the detailed status (info text) of a grid object.

Parameters:

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

`grid_clear_speech_bubble(id_or_obj)`

Clear the speech bubble for a grid object

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	agent id or object of the grid object	required

`grid_clear_target(grid_obj_or_set)`

Clear the movement target of a grid object, stopping it in place.

Parameters:

Name	Type	Description	Default
`grid_obj_or_set`	`Agent \| int \| set`	Agent, ID, or set of grid object(s) to stop.	required

`grid_close_list(grid_obj, the_set, max_dist=None, filter_func=None)`

Find and target the closest object matching the criteria

Parameters:

Name	Type	Description	Default
`grid_obj`	`Agent \| int`	The agent or id	required
`the_set`	`set[Agent]`	The items to test. Defaults to None.	required
`max_dist`	`float`	max distance. Defaults to None.	`None`
`filter_func`	`Callable`	additional filer function. Defaults to None.	`None`

Returns:

Type	Description
`list[CloseData]`	list[CloseData]: The gird close data of the closest objects

`grid_closest(grid_obj, target_set=None, max_dist=None, filter_func=None)`

Find and target the closest object matching the criteria

Parameters:

Name	Type	Description	Default
`grid_obj`	`Agent \| int`	The agent or id	required
`target_set`	`set[Agent]`	The items to test. Defaults to None.	`None`
`max_dist`	`float`	max distance. Defaults to None.	`None`
`filter_func`	`Callable`	additional filer function. Defaults to None.	`None`

Returns:

Name	Type	Description
`CloseData`	`CloseData`	The gird close data of the closest object

`grid_delete_objects(ship_id_or_obj)`

Delete all grid objects belonging to a ship.

Parameters:

Name	Type	Description	Default
`ship_id_or_obj`	`Agent \| int`	Agent or ID of the ship whose grid objects should be removed.	required

`grid_detailed_status(id_or_obj, status, color=None)`

Set the detailed status (info text) of a grid object.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`status`	`str`	Status string to display.	required
`color`	`str`	Text color. `None` keeps the current value. Defaults to None.	`None`

`grid_get_grid_current_theme()`

Get the currently active grid theme data.

Returns:

Name	Type	Description
`dict`		Theme dict with keys such as `name`, `colors`, `icons`, `damage_colors`, etc.

`grid_get_grid_data()`

Get the grid data from all the grid_data.json files

Returns:

Name	Type	Description
`dict`	`dict`	a dictionary of grid data objects.
	`dict`	key (str): The key of the dict, which is a ship key as defined in shipData.
	`dict`	value (dict): A dict with `grid_objects` as a key, and a list of grid object data as the value.

`grid_get_grid_named_theme(name)`

Get a grid theme by name, falling back to the current theme if not found.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	Theme name to look up (case-insensitive), or `None` to return the current theme.	required

Returns:

Name	Type	Description
`dict`		Theme dict with keys such as `name`, `colors`, `icons`, `damage_colors`, etc.

`grid_get_grid_theme()`

Get the grid data from all the grid_data.json files

Returns:

Name	Type	Description
`dict`		a dictionary of grid theme data
		key (str): The ship key associated with the grid theme
		value (dict): The grid theme data

`grid_get_item_theme_data(roles, name=None)`

Get icon, scale, color, and damage color for a set of roles from the grid theme.

Roles are matched in reverse priority order so the last role in the list takes precedence. Falls back to "default" entries when no role matches.

Parameters:

Name	Type	Description	Default
`roles`	`str`	Comma-separated role names.	required
`name`	`str \| None`	Theme name to use. `None` uses the current theme. Defaults to None.	`None`

Returns:

Name	Type	Description
`RetVal`		Object with `.icon` (int), `.scale` (float), `.color` (str), and `.damage_color` (str) attributes.

`grid_objects(so_id)`

Get a set of agent ids of the grid objects on the specified ship

Parameters:

Name	Type	Description	Default
`so_id`	`Agent \| int`	agent id or object	required

Returns:

Type	Description
`set[int]`	set[int]: a set of agent ids

`grid_objects_at(so_id, x, y)`

Get a set of agent ids of the grid objects on the specified ship, at the location specified

Parameters:

Name	Type	Description	Default
`so_id`	`Agent \| int`	agent id or object	required
`x`	`int`	The x grid location	required
`y`	`int`	The y grid location	required

Returns:

Type	Description
`set[int]`	set[int]: A set of agent ids

`grid_pos_data(id)`

Return the current position and path length of a grid object.

Parameters:

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

Returns:

Type	Description
	tuple[float, float, float]: `(curx, cury, path_length)`.

`grid_remove_move_role(event)`

Remove the _moving_ role when a grid object finishes its path.

Parameters:

Name	Type	Description	Default
`event`		Engine event; only acts when `event.sub_tag == "finished_path"`.	required

`grid_set_grid_current_theme(i)`

Set the active grid theme by index.

Parameters:

Name	Type	Description	Default
`i`	`int`	Index into the loaded grid theme list.	required

`grid_set_grid_named_theme(name)`

Set the active grid theme by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Theme name (case-insensitive), e.g. `"cosmos"` or `"Retro"`.	required

`grid_short_status(id_or_obj, status, color=None, seconds=0, minutes=0)`

Set the tooltip and speech bubble text of a grid object.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`status`	`str`	Status string for both the tooltip and speech bubble.	required
`color`	`str`	Text color. `None` keeps the current value. Defaults to None.	`None`
`seconds`	`int`	Duration for the speech bubble. Defaults to 0 (permanent).	`0`
`minutes`	`int`	Additional minutes for the bubble duration. Defaults to 0.	`0`

`grid_speech_bubble(id_or_obj, status, color=None, seconds=0, minutes=0)`

Sets the speech bubble text of a grid object. The text will disappear if the seconds/minutes are set

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent id or object	required
`status`	`str`	The detailed status string	required
`color`	`str`	change the color of the detailed status text. None does not change the current value	`None`
`seconds`	`int`	The seconds for the speech bubble	`0`
`minutes`		(int): The minutes for the speech bubble	`0`

`grid_target(grid_obj_or_set, target_id, speed=0.01)`

Set a grid object to target the location of another grid object

Parameters:

Name	Type	Description	Default
`grid_obj_or_set`	`Agent \| int \| set[Agent \| int]`	an id, object or set of agent(s)	required
`target_id`	`Agent`	an agent id or object	required
`speed`	`float`	the speed to move. Defaults to 0.01.	`0.01`

`grid_target_closest(grid_obj_or_set, target_set=None, max_dist=None, filter_func=None)`

Find and target the closest object matching the criteria

Parameters:

Name	Type	Description	Default
`grid_obj_or_set`	`Agent \| int \| set[Agent \| int]`	The agent or set	required
`target_set`	`set[Agent]`	The items to test. Defaults to None.	`None`
`max_dist`	`float`	max distance. Defaults to None.	`None`
`filter_func`	`Callable`	additional filer function. Defaults to None.	`None`

Returns:

Name	Type	Description
`GridCloseData`	`CloseData`	The gird close data of the closest object

`grid_target_pos(grid_obj_or_set, x, y, speed=0.01)`

Set a grid object to move toward a specific grid coordinate.

Parameters:

Name	Type	Description	Default
`grid_obj_or_set`	`Agent \| int \| set`	Agent, ID, or set of grid object(s) to move.	required
`x`	`float`	Target x grid coordinate.	required
`y`	`float`	Target y grid coordinate.	required
`speed`	`float`	Movement speed. Defaults to 0.01.	`0.01`