The space_objects module

Spatial queries, targeting, positioning, and engineering value access for space objects.

Overview

The space objects module provides the main tools for working with the simulation's 3D space: finding nearby objects, targeting, reading and writing positions, and reading engineering values (shields, energy, etc.).

Spatial queries use a broad-phase test (broad_test) that returns a set of agent IDs within a radius, filtered further by set operations with role(). closest and its variants return the nearest match. All of these work with the same role-based filtering as the rest of the procedural API.

Targeting functions (target, target_pos, target_shoot) tell an NPC which object or position to move toward or attack. clear_target stops the NPC.

Position functions (get_pos, set_pos) read and write 3D world coordinates as Vec3 objects.

Engineering values (get_engineering_value, set_engineering_value) access named ship system parameters such as "shieldStrengthFront", "energy", "speed", etc.

Quick example

MAST pyMAST

== patrol ==
    enemies = broad_test_around(get_pos(ship_id), 2000) & role("enemy")
    nearest = closest(ship_id, enemies)
    if nearest: target(ship_id, nearest)

== recharge ==
    set_engineering_value(ship_id, "energy", 1000)
    set_pos(ship_id, 0, 0, 0)
    ->END

from sbs_utils.procedural.space_objects import (
    broad_test_around, closest, target, clear_target,
    get_pos, set_pos, get_engineering_value, set_engineering_value,
    delete_object,
)
from sbs_utils.procedural.roles import role

pos = get_pos(ship_id)
enemies = broad_test_around(pos, 2000) & role("enemy")
nearest = closest(ship_id, enemies)
if nearest:
    target(ship_id, nearest)
else:
    clear_target(ship_id)

set_pos(ship_id, 0, 0, 0)
set_engineering_value(ship_id, "energy", 1000)

Spatial query functions

Function	Returns
broad_test(id, radius)	Set of IDs within radius of id
broad_test_around(pos, radius)	Set of IDs within radius of a Vec3
closest(id, candidates)	Nearest agent from candidates to id
closest_to_point(pos, candidates)	Nearest agent from candidates to a Vec3
closest_list(id, candidates, count)	count nearest agents as a list

API

broad_test(x1, z1, x2, z2, broad_type=65520)

Return the set of object IDs inside a rectangular region of the simulation.

Parameters:

Name	Type	Description	Default
x1	float	Left X boundary.	required
z1	float	Top Z boundary.	required
x2	float	Right X boundary.	required
z2	float	Bottom Z boundary.	required
broad_type	int	Bitmask filtering which object types to include. TERRAIN=0x01, NPC=0x10, PLAYER=0x20, ALL=0xffff, NPC_AND_PLAYER=0x30. Defaults to 0xfff0.	65520

Returns:

Type	Description
	set[int]: IDs of objects inside the rectangle.

broad_test_around(id_or_obj, width, depth, broad_type=65520)

Return the set of object IDs inside a rectangle centered on an agent or point.

Parameters:

Name	Type	Description	Default
id_or_obj	Agent | int | Vec3	Center agent ID, object, or position.	required
width	float	Total width of the search rectangle (X axis).	required
depth	float	Total depth of the search rectangle (Z axis).	required
broad_type	int	Bitmask filtering which object types to include. TERRAIN=0x01, NPC=0x10, PLAYER=0x20, ALL=0xffff, NPC_AND_PLAYER=0x30. Defaults to 0xfff0.	65520

Returns:

Type	Description
	set[int]: IDs of objects inside the rectangle.

clear_target(chasers, throttle=0)

Clear the movement and weapons target on one or more agents.

Sets the target position to the agent's current position and zeroes the weapon target ID, effectively stopping pursuit.

Parameters:

Name	Type	Description	Default
chasers	Agent | int | set[Agent | int] | CloseData | SpawnData	Agent(s) to update.	required
throttle	float	Throttle to apply after clearing. Defaults to 0.	0

closest(the_ship, the_set, max_dist=None, filter_func=None)

Return the closest object to a source from a candidate set.

Parameters:

Name	Type	Description	Default
the_ship	Agent | int | Vec3	Reference agent ID, object, or position.	required
the_set	Agent | int | set[Agent | int]	Candidate agent(s) to test.	required
max_dist	float	Maximum distance to consider. Defaults to None (no limit).	None
filter_func	Callable	Extra predicate f(agent) -> bool. Defaults to None.	None

Returns:

Type	Description
CloseData	CloseData | None: Distance data for the closest match, or None if no candidates qualify.

closest_list(source, the_set, max_dist=None, filter_func=None)

Return all objects in a set within optional distance and filter criteria.

Parameters:

Name	Type	Description	Default
source	Agent | int | CloseData | SpawnData | Vec3	The reference agent ID, object, or position.	required
the_set	set[int]	IDs of candidates to test.	required
max_dist	float	Maximum distance to include. Defaults to None (no limit).	None
filter_func	Callable	Extra predicate f(agent) -> bool applied to each candidate. Defaults to None.	None

Returns:

Type	Description
list[CloseData]	list[CloseData]: All qualifying candidates with their distances.

closest_object(the_ship, the_set, max_dist=None, filter_func=None)

Return the closest agent object to a source from a candidate set.

Parameters:

Name	Type	Description	Default
the_ship	Agent | int | Vec3	Reference agent ID, object, or position.	required
the_set	Agent | int | set[Agent | int]	Candidate agent(s) to test.	required
max_dist	float	Maximum distance to consider. Defaults to None (no limit).	None
filter_func	Callable	Extra predicate f(agent) -> bool. Defaults to None.	None

Returns:

Type	Description
Agent	Agent | None: The closest agent, or None if no candidates qualify.

closest_to_point(point, the_set, max_dist=None, filter_func=None)

Return the closest object to a Vec3 point from a candidate set.

Parameters:

Name	Type	Description	Default
point	Vec3	Reference position in simulation space.	required
the_set	Agent | int | set[Agent | int]	Candidate agent(s) to test.	required
max_dist	float	Maximum distance to consider. Defaults to None (no limit).	None
filter_func	Callable	Extra predicate f(agent) -> bool. Defaults to None.	None

Returns:

Type	Description
CloseData	CloseData | None: Distance data for the closest match, or None if no candidates qualify.

delete_object(id_or_objs)

Delete one or more agents from the simulation.

Parameters:

Name	Type	Description	Default
id_or_objs	Agent | int | set[Agent | int]	Agent(s) to delete.	required

delete_objects_box(x, y, z, w, h, d, broad_type=15, roles=None)

Delete all objects inside a box that match an optional role filter.

Parameters:

Name	Type	Description	Default
x	float	Center X coordinate.	required
y	float	Center Y coordinate.	required
z	float	Center Z coordinate.	required
w	float	Half-width of the box along the X axis.	required
h	float	Half-height of the box along the Y axis.	required
d	float	Half-depth of the box along the Z axis.	required
broad_type	int	Bitmask filtering which object types to consider. TERRAIN=0x01, NPC=0x10, PLAYER=0x20, ALL=0xffff, NPC_AND_PLAYER=0x30. Defaults to 0x0F.	15
roles	str	Comma-separated roles — only objects with all listed roles are deleted. Defaults to None (delete all matches).	None

delete_objects_sphere(x, y, z, radius, broad_type=15, roles=None)

Delete all objects inside a sphere that match an optional role filter.

Parameters:

Name	Type	Description	Default
x	float	Center X coordinate.	required
y	float	Center Y coordinate.	required
z	float	Center Z coordinate.	required
radius	float	Sphere radius in simulation units.	required
broad_type	int	Bitmask filtering which object types to consider. TERRAIN=0x01, NPC=0x10, PLAYER=0x20, ALL=0xffff, NPC_AND_PLAYER=0x30. Defaults to 0x0F.	15
roles	str	Comma-separated roles — only objects with all listed roles are deleted. Defaults to None (delete all matches).	None

get_engineering_value(id_or_obj, name, default=None)

Get a named engineering control value from a ship.

Parameters:

Name	Type	Description	Default
id_or_obj	Agent | int	Agent ID or object.	required
name	str	The engineering control label to look up (case-insensitive).	required
default	float	Value returned if the label is not found. Defaults to None.	None

Returns:

Type	Description
	float | None: The current value of the control, or default.

get_pos(id_or_obj)

Return the current position of an agent.

Parameters:

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

Returns:

Type	Description
	Vec3 | None: The agent's position, or None if it does not exist.

set_engineering_value(id_or_obj, name, value)

Set a named engineering control value on a ship.

Parameters:

Name	Type	Description	Default
id_or_obj	Agent | int	Agent ID or object.	required
name	str	The engineering control label to update (case-insensitive).	required
value	float	The new value.	required

set_pos(id_or_obj, x, y=None, z=None)

Teleport one or more agents to a position.

Parameters:

Name	Type	Description	Default
id_or_obj	Agent | int | set[Agent | int]	Agent(s) to reposition.	required
x	float | Vec3	X coordinate, or a Vec3 when y is omitted.	required
y	float	Y coordinate. If None, x is treated as a Vec3. Defaults to None.	None
z	float	Z coordinate. Defaults to None.	None

target(set_or_object, target_id, shoot=True, throttle=1.0, stop_dist=None)

Direct one or more agents to move toward and optionally shoot a target.

Parameters:

Name	Type	Description	Default
set_or_object	Agent | int | set[Agent | int]	Agent(s) to command.	required
target_id	Agent | int	The target agent ID or object.	required
shoot	bool	If True, lock weapons on the target as well as moving toward it. Defaults to True.	True
throttle	float	Movement speed multiplier (0.0–1.0). Defaults to 1.0.	1.0
stop_dist	float	Stop the agent (throttle→0) when it comes within this distance of the target. Defaults to None.	None

target_pos(chasers, x, y, z, throttle=1.0, target_id=None, stop_dist=None)

Direct one or more agents to move toward a position in simulation space.

Parameters:

Name	Type	Description	Default
chasers	Agent | int | set[Agent | int] | CloseData | SpawnData	Agent(s) to command.	required
x	float	Target X coordinate.	required
y	float	Target Y coordinate.	required
z	float	Target Z coordinate.	required
throttle	float	Movement speed multiplier (0.0–1.0). Defaults to 1.0.	1.0
target_id	Agent | int	If set, agents will also fire at this target. Defaults to None.	None
stop_dist	float	Stop the agent (throttle→0) when within this distance of the target. Defaults to None.	None

target_shoot(chasers, target_id=None)

Set the weapons target on one or more agents without changing their movement.

Parameters:

Name	Type	Description	Default
chasers	Agent | int | set[Agent | int] | CloseData | SpawnData	Agent(s) to update.	required
target_id	Agent | int	The agent to fire at. Defaults to None.	None