The sbs module

The SBS Module is provided by the Artemis cosmos engine

Overview

API: SBS

DIPLOMACY

Bases: IntEnum

the different attitudes that sides have for each other

SHPSYS

Bases: IntEnum

One of four ship systems to track damage

Writer

Bases: object

class Writer

event

Bases: object

class event

client_id property

id of computer this event came from.

event_time property

long int, time this damage occured, compare to simulation.time_tick_counter

extra_extra_tag property

string, even more-more information

extra_tag property

string, even more information

origin_id property

id of space object this event came from

parent_id property

id of owner/creator of space object this event came from (like the ship that fired the missile)

selected_id property

id of space object this event is talking about, or doing something to

source_point property

vec3, 3d point this event originated from

sub_float property

float, numeric information

sub_tag property

string describing message sub-type

tag property

string describing message type

value_tag property

string, more information

grid_object

Bases: object

class grid_object

layer property writable

int, layers to help draw different grid-objects correctly. (recommend 0-8, with 0 being lowest)

name property writable

string, text name

tag property writable

string, text tag

type property writable

string, text value, broad type of object

unique_ID property

uint64, read only, id of this particular grid object

hullmap

Bases: object

class hullmap

art_file_root property writable

string, file name, used to get top-down image from disk

desc property writable

string, description text

grid_scale property writable

float, space between grid points

h property writable

int, total grid height

name property writable

string, text name

symmetrical_flag property writable

int, non-zero if the map is symmetrical

w property writable

int, total grid width

create_grid_object(name, tag, type)

returns a gridobject, after creating it

delete_grid_object(arg0)

deletes the grid object, returns true if deletion actually occurred

get_grid_object_by_id(id)

returns a gridobject, by uint64 ID

get_grid_object_by_index(index)

returns a gridobject, by position in the list

get_grid_object_by_name(name)

returns a gridobject, by name

get_grid_object_by_tag(tag)

returns a gridobject, by text tag

get_grid_object_count()

get the number of grid objects in the list, within this hullmap

get_objects_at_point(x, y)

returns a list of grid object IDs that are currently at the x/y point.

is_grid_point_open(arg0, arg1)

is the x/y point within this hullmap open (traversable)? 0 == no

navarea

Bases: navpoint

A navpoint that also defines a 2D map region — a quad of four ground-plane (x, z) corners. Being a navpoint, it carries all the standard properties (text, color, pos, visibleToShip, visibleToSide, …) and lives in the navpoint ID registry, so get_navpoint_by_id / navpoint_exists / delete_navpoint_by_id all operate on it just like the engine.

navpoint

Bases: object

class navpoint

color property writable

vec4, color on 2d radar

has_changed_flag property writable

int, if you change this navpoint, also set this flag to !0, so the server sends it down to the clients

pos property writable

vec3, position in space

text property writable

string, text label

visibleToShip property writable

uint64, id of the only space object that can see this navpoint (0 = all)

visibleToSide property writable

string, text side name of side that can see this navpoint

SetColor(arg0)

use a string color description to set the color

navproxy

Bases: object

class navproxy

color property writable

vec4, color on 2d radar

has_changed_flag property writable

int, if you change this navpoint, also set this flag to !0, so the server sends it down to the clients

pos property writable

vec3, position in space

proxy_id property writable

int64, ID of associated space object

shiptype property writable

string, hull key from shipdata.yaml

text property writable

string, text label

SetColor(arg0)

use a string color description to set the color

object_data_set

Bases: object

class object_data_set

Mock note: this carries a lightweight CHANGE counter (gen) that bumps only when a set() actually changes a stored value. Consumers (the mockgui HUD push) remember the last gen they saw per object and skip work when nothing changed - so unchanged ship vitals aren't recomputed or re-sent every tick. dirty_since(g) returns the exact keys that changed since gen g (each key is gen-stamped), which is clobber-free across multiple watchers (unlike a shared dirty set that one consumer would clear out from under another).

clear_data(name)

deletes all elements in this blob value

dirty_since(gen)

The (tag, index) keys whose value changed after gen.

get_first(name)

Get the first iterator value of the map in this element

get_next(name)

Get the next iterator value of the map in this element; None means end of list

num_elements(name)

get the number of elements in this blob value

quaternion

Bases: object

class quaternion

w property writable

float, component value

x property writable

float, component value

y property writable

float, component value

z property writable

float, component value

simulation

Bases: object

class simulation

time_tick_counter property

get current time value

AddTractorConnection(arg0, arg1, arg2, arg3)

makes a new connection between two space objects.

ClearTractorConnections()

destroys all existing tractor connections right now.

DeleteTractorConnection(arg0, arg1)

finds and deletes an existing tractor connection.

add_navarea(x1, y1, x2, y2, x3, y3, x4, y4, text, colDesc)

adds a new navarea to space; returns its (navpoint) integer ID. The four x/y pairs are ground-plane corners (the 2D map y axis is world z). A navarea is a navpoint, so it goes in the navpoint ID registry; its pos is the corner centroid so distance_to_navpoint and friends work on it.

add_navpoint(x, y, z, text, colDesc)

adds a new navpoint to space; returns integer ID

add_navproxy(proxyID, name, shipType, colDesc)

adds a new navproxy to space; returns its integer ID.

Was a no-op stub (return 0) that never populated self.navproxies - inconsistent with delete_navproxy_by_id / get_navproxy_by_id / navproxy_exists, which all key off self.navproxies. That forced tests to poke sim.navproxies directly, which THROWS in the engine (the real sim has no navproxies attribute). Now it stores like the engine so the public API works in both. proxyID is the ASSOCIATED object id (-> proxy_id); the navproxy gets its own id, which is what get/delete/exists use.

clear_navpoints()

deletes all navpoints (mock helper)

create_space_object(aiTag, dataTag, abits)

creates a new spaceobject. abits is a 16-bit bitfield for further defining the object.

delete_navpoint_by_id(id)

deletes navpoint by its id (navareas are navpoints, so this covers them)

delete_navpoint_by_name(arg0)

deletes navpoint by its name (mock helper)

delete_navpoint_by_reference(arg0)

deletes navpoint by its reference (mock helper)

delete_navproxy_by_id(id)

deletes navproxy by its id

force_update_to_clients(spaceObjectID, playerShipID)

forces this space object to update its data to the clients

get_navpoint_by_id(id)

takes an integer ID, returns the associated Navpoint object

get_navpoint_by_name(arg0)

takes a string name, returns the associated Navpoint object (mock helper)

get_navpoint_id_by_name(text)

returns a navpoint ID, given its name as the argument

get_navproxy_by_id(id)

takes an integer ID, returns the associated NavProxy object

get_navproxy_by_proxy_id(id)

takes a space object ID, returns the associated NavProxy object

get_navproxy_id_by_name(text)

returns a navproxy ID, given its name as the argument

get_shield_hit_index(sourceShip, targetShip)

returns the shield index that would be hit by a hypothetical beam. -1 if no shield facings.

get_shield_hit_index_source(sourcePoint, targetShip)

returns the shield index that would be hit by a hypothetical beam. -1 if no shield facings.

get_side_relationship(FirstSideTag, SecondSideTag)

returns the diplomatic state between two sides, in THAT order (mock helper)

get_space_object(arg0)

returns the reference to a spaceobject, by ID

is_not_paused()

returns True if the game is currently running.

launch_torpedo(source_ship, tube_index, is_fighter_flag)

launches a torpedo from the space object provided.

Engine API (a weapons console / autoplay / fighter calls it). Wires to the mock projectile sim: spend a round of a loaded torpedo type and spawn the projectile toward the ship's weapon target (straight ahead if none). The mock keys ammo by type rather than by physical tube, so tube_index fires the first loaded type (reserved for a future per-tube loadout model); is_fighter_flag is accepted for API parity - the projectile spawns from source_ship either way.

navpoint_exists(id)

returns true if the navpoint exists, by integer id

navproxy_exists(id)

returns true if the navproxy exists, by integer id

reposition_space_object(arg0, arg1, arg2, arg3)

immediately changes the position of a spaceobject

set_diplomacy_color(diplomacyEnumValue, colorString)

set the color of a diplomatic state (like DIPLOMACY::UNKNOWN or DIPLOMACY::ALLIED)

set_navproxy_pos(navproxy, x, y, z)

takes a navproxy (the reference, not the ID), and sets the xyz values

set_side_icon_color(SideTag, colorString)

set the color of a SideTag (like TSN or Raider)

set_side_icon_index(SideTag, iconIndex)

set the value of the icon of a SideTag (like TSN or Raider)

set_side_relationship(FirstSideTag, SecondSideTag, diplomacyEnumValue)

set the diplomatic state between two sides, for GUI color purposes.

DIRECTIONAL, like the engine: this records First->Second and nothing else. The mock used to key the table by frozenset, i.e. symmetric, which quietly made a caller that wrote only one direction look correct here while drawing grey contacts in the engine (colouring is a lookup from the VIEWER's side to the contact's side, so the missing direction is the one that matters). Modelling the asymmetry is what lets a test catch that; see procedural.sides.side_set_relations, which writes both directions.

space_object_exists(arg0)

returns true if the spaceobject exists, by ID

A standby (docked) object is EXISTENCE-VALID in the engine: it is only suspended from the active/physics arena, not removed from the object table (confirmed against the real engine - a pushed-to-standby object still reports space_object_exists True). The mock keeps standby objects OUT of self.space_objects so the physics/collision/blast sweeps that iterate space_objects skip them, but existence must still consult the standby list so object_exists means "alive" (not "in the arena"), matching the engine and the hangar's own object_exists liveness guards.

space_object

Bases: object

class space_object

abits property writable

unsigned 16-bit bitfield for filtering. bits 0-3 is reserved by c++.

blink_state property writable

int, positive numbers are pulse delay, negative numbers are blink delay, 0 = normal, -1 = glow off

cur_speed property writable

float, speed of object

data_set property

object_data_set, read only, reference to the object_data_set of this particular object

data_tag property writable

string, name of data entry in shipData.json

exclusion_radius property writable

float, other objects cannot be closer to me than this distance

fat_radius property writable

float, radius of box for internal sorting calculations

pos property writable

vec3, position in space

rot_quat property writable

quaternion, heading and orientation of this object

ship_data_key property writable

string, name of data entry in shipData.json

side property writable

string, friendly to other objects on this same side; leave empty for 'no side'

steer_pitch property writable

float, continuing change to heading and orientation of this object, over time

steer_roll property writable

float, continuing change to heading and orientation of this object, over time

steer_yaw property writable

float, continuing change to heading and orientation of this object, over time

tick_type property

string, name of behavior module

tick_type_ID property

int32, read only, internal representation of tick_type

unique_ID property

uint64, read only, id of this particular object

forward_vector()

returns a vec3, a vector direction, related to which way the space object is oriented

right_vector()

returns a vec3, a vector direction, related to which way the space object is oriented

set_behavior(arg0)

set name of behavior module

up_vector()

returns a vec3, a vector direction, related to which way the space object is oriented

tractor_connection

Bases: object

class tractor_connection

offset property writable

float, how much the target is pulled towards the offset every tick. 0 = infinite pull, target locked to boss

source_id property

int, ID of boss/master/major object

target_id property

int, ID of object that is attached to the other

vec2

Bases: object

class vec2

x property writable

float, component value

y property writable

float, component value

vec3

Bases: object

class vec3

x property writable

float, component value

y property writable

float, component value

z property writable

float, component value

vec4

Bases: object

class vec4

a property writable

float, component value (0.0-1.0)

b property writable

float, component value (0.0-1.0)

g property writable

float, component value (0.0-1.0)

r property writable

float, component value (0.0-1.0)

add_client_tag()

stub; does nothing yet.

add_extra_ship_data(file)

Load another set of ships from a data file, for this mission only.

ONE ARGUMENT, "a fully-pathed filename (plus suffix)" - the 2026-08-15 exe's shape. The 1.3.5 form took (name, folder) and did its own .yaml/.json search; that search now happens in sbs_utils.procedural.ship_data._read_extra_ship_data, which is what decides the suffix this is handed.

The path is EXE-RELATIVE (data/missions/...), so it is resolved against the Artemis root and NOT against the process's cwd - the runner's cwd is data/missions, so a bare open() here would look under data/missions/data/missions/... and silently find nothing. That is the whole reason a mission's hulls could be present headless and absent in the engine, or the reverse.

Merges into sbs_utils' own list, which is where _try_populate_from_ship_data looks, so a mission using this behaves the same headless. Note the REAL engine does not do that half - an add-on must merge library-side itself, behind a presence guard, or the mock double-merges.

Forgiving about a missing file, matching the engine's habit of not being fatal about data it cannot find: a mod with a broken path should be a ship with no stats, not a dead mission.

add_particle_emittor(spaceObject, lifeSpan, descriptorString)

creates a complex particle emittor and attaches it to a space object.

Mock note: particles are client-render-only, so there is nothing to draw here. What IS modeled is the BOOKKEEPING the API's own docstrings promise - handing out a real handle, honoring delete, and answering particle_emittor_exists - so a lifecycle or leak bug is catchable headlessly. It used to return a constant 0, which is falsy: every if emittor_id: cleanup silently skipped under test.

apply_damage(target_id, amount, source_id=0, kind='')

Mock-only hull-damage model.

Applies amount hull damage to target_id and queues the matching engine events so handlerhooks routes them like the real Pybind layer: - non-fatal: a damage event (origin=source, selected=target). Carries sub_tag = weapon kind (kind: "beam"/"drone"/torp type) and sub_float = the hit amount, like the engine - so //damage routes can read EVENT.sub_float / EVENT.sub_tag in the mock too. - fatal: a damage/destroyed event (fires //damage/destroy and removes the py Agent via LifetimeDispatcher) plus npc_killed or station_killed (fires //damage/killed, keyed on origin=target). Hull lives in data_set "armor"; only objects with armorMax>0 are damageable (ships from shipData). The dead mock object is removed from the sim.

assign_client_to_alt_ship(clientComputerID, controlledShipID)

Tells a client computer that the 2d radar should focus on controlledShipID, instead of its assigned ship. Turn this code off by providing zero as the second argument.

assign_client_to_ship(clientComputerID, controlledShipID)

Tells a client computer which ship it should control.

broad_test(x1, z1, x2, z2, tick_type, use_hash=True)

Return space objects inside an x/z 2D rect, filtered by the tick_type bitfield.

The engine's broad_test is BVH-backed (sub-linear), and the AI fires many of these per frame, so the mock defaults to a spatial hash: a uniform cell grid built once per (physics tick, object count) and reused across the frame's calls - a query is O(cells in rect) instead of O(all objects). The cache rebuilds when objects move (tick advances) or are spawned/killed (count changes), so a brain that spawns then queries in the same handler still sees the new object. use_hash=False forces the linear scan (parity tests / debugging). Both snapshot the object dict so a concurrent spawn/delete can't raise "dictionary changed during iteration".

cinematic_control(clientID, scriptControlsCamera, dollyID, dollyPos, targetID, targetPos)

Place/track the cinematic camera for a client's 3dview main screen.

scriptControlsCamera == 0 -> auto: track the client's assigned ship. scriptControlsCamera == 1 -> scripted: camera at dollyID + dollyPos, looking at targetID + targetPos. Pairs with set_main_view_modes(clientID, "3dview", , "cinematic").

clear_client_tags()

stub; does nothing yet.

command_line_dict()

Only the key=value launch arguments. Bare flags are absent, as in the engine.

command_line_list()

Every launch argument, exe path first.

create_new_sim()

all space objects are deleted; a blank slate is born.

Resets the existing simulation IN PLACE rather than allocating a new object. The engine reuses its sim instance, and so must the mock: a script's sim_create() runs inside a cosmos_event_handler call whose FrameContext.context already holds a reference to the sim. If we swapped in a brand-new object, everything that script spawns after sim_create (e.g. start_server's player ships) would land on the now-orphaned old instance via the stale context, while later ticks build the world on the new one - so the player ships vanish and their ids get reused. Re-initialising in place keeps the object identity, so every held reference stays valid.

delete_all_navpoints()

deletes all navpoints on server, and notifies all clients of the change

delete_all_navproxies()

deletes all navproxies on server, and notifies all clients of the change

delete_grid_object(spaceObjectID, gridObjID)

deletes the grid object, and sends the deletion message to all clients

The object must leave BOTH registries: the sim-wide grid_objects map and its host hull map's grid_items list. Popping only the former left a dangling entry on the hull map, so get_objects_at_point kept returning an id whose py-side Agent and data_set were long gone -- grid_take_internal_damage_at then hit None.set(...) the next time internal damage landed on that cell. This is the delete path DeleteQueue actually uses (delete_queue.py), so every deferred grid delete leaked; hullmap.delete_grid_object already removed from both.

delete_object(ID)

deletes a space object by its ID

ANNOUNCES IT, the way the engine does. Measured in engine 1.3.5 with LM_TestRange's test_damage_routes probe: deleting an object from script makes the engine send tag='damage', sub_tag='destroyed' with no attacker - which fires BOTH //damage/destroy (the lifetime half) and //damage/object (the damage half), for an NPC, a PLAYER SHIP and a piece of terrain alike.

The mock used to remove the object in silence, so a headless run could not see any of that: a mission whose cleanup quietly triggered its own destroy handling looked fine until it reached the engine. Missions rely on this - LM's damage/destroy.mast reacts to allied losses, and the over-count that came from deleting unused player slots is the same event arriving where nobody expected it.

Mock note: this deliberately does NOT reap that object's particle emitters. Whether the engine does is unverified, and leaving them is what gives the library's emitter janitor something to reconcile - reap them here and the test that proves the janitor works passes for the wrong reason.

delete_particle_emittor(emittorID)

deletes a particle emittor by ID.

An unknown id is a silent no-op, so double-deleting cannot throw.

distance(arg0, arg1)

returns the distance between two space objects; arguments are two spaceObjects

distance_between_navpoints(arg0, arg1)

returns the distance between two nav points; navpoints by ID

distance_id(arg0, arg1)

returns the distance between two space objects; arguments are two IDs

distance_point_line(arg0, arg1, arg2)

calculates the distance from a point to a line. Returns (dist along line, dist from start, tangent).

distance_to_navpoint(arg0, arg1)

returns the distance between a nav point and a space object; navpoint ID, then object ID

find_valid_grid_point_for_vector3(spaceObjectID, vecPoint, randomRadius)

return a list of two integers, the grid x and y that is open and is closest. The list is empty if the search fails.

find_valid_unoccupied_grid_point_for_vector3(spaceObjectID, vecPoint, randomRadius)

return a list of two integers, the grid x and y that is open and is closest. The list is empty if the search fails.

get_cinematic_camera(clientID)

Resolve the current camera + look-at world positions for a client's cinematic view, or None if no cinematic state / no resolvable object.

Returns {"cam": (x,y,z), "target": (x,y,z), "mode": str, "ship_id": str}.

get_client_ID_list()

return a list of client ids, for the computers that are currently connected to this server.

get_debug_gui_tree(clientID, tag, displayListFlag)

sends a GUI debug message from the targeted client (0 = server screen)

get_game_version()

returns the version of the game EXE currently operating this script, as a string.

get_hull_map(spaceObjectID, forceCreate=False)

gets the hull map object for this space object; setting forceCreate to True will erase and rebuild the grid (and gridObjects) of this spaceobject

get_preference_float(key)

Gets a value from preferences.json

get_preference_int(key)

Gets a value from preferences.json

get_preference_string(key)

Gets a value from preferences.json

get_screen_size()

returns a VEC2, with the width and height of the display in pixels

get_shared_string(key)

gets a shared string, given the key (itself a string). Shared strings are automatically copied from server to all clients.

get_ship_of_client(clientID)

returns the player ship ID assigned to the client computer

get_text_block_height(fontTag, textToMeasure, width)

for a font key, a string of (possibly) multiline text, and a pixel width, this returns the height of the drawn text.

Accuracy vs the engine, measured against a real capture (missions/font_measure, compare_measurements.py):

width >= 600px   0% line-count disagreement
width >= 300px   6%
width  = 100px  68%

So block heights are trustworthy at realistic column widths and are NOT at pathologically narrow ones (100px is ~10% of a 1024 wide screen -- about three glyphs at gui-6, where exactly where the engine breaks a word starts to dominate). If you are validating content sized rows inside a very narrow column, confirm it in a real engine session rather than headlessly.

get_text_line_height(fontTag, textToMeasure)

for a font key and a text string (one line, no wrapping), this returns the height of the drawn text.

get_text_line_width(fontTag, textToMeasure)

for a font key and a text string (one line, no wrapping), this returns the width of the drawn text.

get_type_of_client(clientID)

returns the consoleType previously assigned to the client computer

hide_gui_tag(clientID, tag)

makes a GUI element invisible, on the targeted client (0 = server screen)

in_standby_list(space_object)

returns true if the spaceobject is in the standby list.

in_standby_list_id(id)

returns true if the spaceobject is in the standby list.

is_demo()

Returns true if the EXE is marked as a demo version.

launch_drone(source_id, target_id, damage=20.0, speed=400.0, life=40.0)

Mock-only: launch a drone (also a projectile).

Emits a ship_launches_drone event (routes //launch/drone) and registers a homing projectile dealing damage hull damage on impact.

launch_missile(source_id, target_id, kind='Homing', damage=None, speed=600.0, life=30.0, max_range=None)

Mock-only: launch a torpedo of kind (Homing / Nuke / Mine / EMP).

Emits a player_launches_missile event (routes //launch/missile, with extra_extra_tag=kind, origin=source, selected=target). Every torp launches as a flying projectile aimed at the weapon-selected target (target_id); with no selection it flies straight along the firer's heading.

• Warhead torps (behaviour 'homing': Homing / Nuke / EMP) TRACK the target and re-acquire the nearest object if the target dies mid-flight. On contact: Homing = single hit, Nuke = lingering growing-ring blast, EMP = one-shot shield-halve.
• Mines (behaviour 'mine') fly ballistically to their distance (max_range) then DEPLOY - they stop and stick around as a stationary proximity mine that detonates its blast when a ship enters the trigger radius (or until mine-life expires).

damage defaults to the per-kind value but can be overridden (the projectile unit tests pass it explicitly).

particle_at(position, descriptorString)

emit some particles in space.

particle_emittor_exists(emittorID)

checks for the existence of a particle emittor.

particle_emittors()

Mock-only: the live emitter table, so a test can assert nothing leaked.

Not part of the engine API - never call this from library or mission code.

particle_on(spaceObject, descriptorString)

emit some particles in space from a space object.

pause_sim()

the sim will now pause; HandlePresentGUI() and HandlePresentGUIMessage() are called.

physics_tick(dt=1.0 / 60.0)

Integrate motion for active (NPC/PLAYER) objects and detect collisions.

Terrain objects (abits & 0x30 == 0) are fully static and are never dispatched, integrated, or checked against each other. Active objects can still collide with terrain (handled by _physics_collision).

Thread-safe: acquires sim._lock for the entire tick so the main thread can safely spawn and delete objects between ticks. Collision events are put() into _pending_physics_events (queue.Queue) for the mission runner to drain.

play_audio_file(clientID, filename, volume, pitch)

Plays a WAV audio file now, for just the specified client, OR zero for server.

play_music_file(ID, filename)

Plays a music file now; ID is ship, OR client, OR zero for server.

player_ship_setup_defaults(space_object)

Rebuilds the default blob data of this player ship.

player_ship_setup_from_data(space_object)

Rebuilds the blob data of this player ship from the shipdata.json and the preferences.json.

pop_next_mission()

Return and clear a pending run_next_mission() request (runner polls this).

Returns the folder string, or None when nothing is pending.

push_to_standby_list(space_object)

moves the spaceobject from normal space to the standby list.

push_to_standby_list_id(id)

moves the spaceobject from normal space to the standby list.

query_client_tags()

stub; does nothing yet.

query_client_widget_state(clientID, widgetName, fullScreenFlag)

sends a request for the client to send a 'widget_box_state' script event back.

register_behavior(tick_type, fn)

Register fn(space_object, dt_seconds) to run every physics tick for objects of this tick_type.

register_client(client_id)

Mark a WebSocket client as connected so it appears in get_client_ID_list().

remove_gui_hotkey(clientID, tag)

tells the targeted client (0 = server screen) to delete an existing hot key for a certain retained gui element.

request_client_string(clientComputerID, string_key)

requests a string value from the client computer. This results in a script message, 'client_string'

resume_sim()

the sim will now run; HandleStartMission() and HandleTickMission() are called.

retrieve_from_standby_list(space_object)

moves the spaceobject from the standby list to normal space.

retrieve_from_standby_list_id(id)

moves the spaceobject from the standby list to normal space.

run_next_mission(mission_folder)

Shuts down this script and starts the mission in the folder argument.

The real engine swaps missions at the process level. The mock can't do that from inside a tick, so record the request; the mission runner polls pop_next_mission() between ticks and performs the reload. Passing the current mission folder restarts it (the common case: pause-screen restart, autoplay results loop, mission select).

science_scan_queue(ship_id)

This ship's scan queue, head first. Entry 0 is the one actually scanning.

send_client_widget_list(clientID, consoleType, widgetList)

sends the gameplay widgets to draw, on the targeted client (0 = server screen)

send_client_widget_rects(arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)

changes the rects of a gameplay widget, on the targeted client (0 = server screen).

send_comms_button_info(arg0, arg1, arg2, arg3)

sends a complex message to the comms console of a certain ship.

send_comms_message_to_player_ship(playerID, otherID, faceDesc, titleText, titleColor, bodyText, bodyColor)

sends a complex message to the comms console of a certain ship.

send_comms_selection_info(arg0, arg1, arg2, arg3)

sends a complex message to the comms console of a certain ship.

send_grid_button_info(arg0, arg1, arg2, arg3)

sends a complex message to the engineering console of a certain ship.

send_grid_selection_info(arg0, arg1, arg2, arg3)

sends a complex message to the engineering console of a certain ship.

send_gui_3dship(clientID, parent, tag, style, left, top, right, bottom)

Creates a 3D ship box GUI element, on the targeted client (0 = server screen)

send_gui_button(clientID, parent, tag, style, left, top, right, bottom)

Creates a button GUI element, on the targeted client (0 = server screen)

send_gui_checkbox(clientID, parent, tag, style, left, top, right, bottom)

Creates a checkbox GUI element, on the targeted client (0 = server screen)

send_gui_clear(clientID, tag)

Clears all GUI elements from screen, on the targeted client (0 = server screen).

send_gui_clickregion(clientID, parent, tag, style, left, top, right, bottom)

Creates a click-region GUI element, on the targeted client (0 = server screen)

send_gui_colorbutton(clientID, parent, tag, style, left, top, right, bottom)

Creates a color button GUI element, on the targeted client (0 = server screen)

send_gui_colorcheckbox(clientID, parent, tag, style, left, top, right, bottom)

Creates a color checkbox GUI element, on the targeted client (0 = server screen)

send_gui_complete(clientID, tag)

Flips double-buffered GUI display list, on the targeted client (0 = server screen).

send_gui_dropdown(clientID, parent, tag, style, left, top, right, bottom)

Creates a dropdown GUI element, on the targeted client (0 = server screen)

send_gui_face(clientID, parent, tag, face_string, left, top, right, bottom)

Creates a face box GUI element, on the targeted client (0 = server screen)

send_gui_hotkey(clientID, category, tag, keyType, description)

tells the targeted client (0 = server screen) to handle a hot key for a certain retained gui element.

send_gui_icon(clientID, parent, tag, style, left, top, right, bottom)

Creates an icon art GUI element, on the targeted client (0 = server screen)

send_gui_iconbutton(clientID, parent, tag, style, left, top, right, bottom)

Creates an icon-button GUI element, on the targeted client (0 = server screen)

send_gui_iconcheckbox(clientID, parent, tag, style, left, top, right, bottom)

Creates an icon-checkbox GUI element, on the targeted client (0 = server screen)

send_gui_image(clientID, parent, tag, style, left, top, right, bottom)

Creates a 2d art image GUI element, on the targeted client (0 = server screen)

send_gui_rawiconbutton(clientID, parent, tag, style, left, top, right, bottom)

Creates a simple clickable icon GUI element, on the targeted client (0 = server screen)

send_gui_slider(clientID, parent, tag, current, style, left, top, right, bottom)

Creates a slider bar GUI element, on the targeted client (0 = server screen)

send_gui_sub_region(clientID, parent, tag, style, left, top, right, bottom)

Creates a subregion GUI element, on the targeted client (0 = server screen)

send_gui_text(clientID, parent, tag, style, left, top, right, bottom)

Creates a text box GUI element, on the targeted client (0 = server screen)

send_gui_typein(clientID, parent, tag, style, left, top, right, bottom)

Creates a text entry GUI element, on the targeted client (0 = server screen)

send_hold_menu(clientID, subject, object, extra, menuOptionStringSet)

sends info to client that displays a quick menu list on the 2d radar.

send_message_to_client(clientID, colorDesc, text)

sends a text message to the text box, for the specific client.

send_message_to_player_ship(playerID, colorDesc, text)

sends a text message to the text box, on every client for a certain ship.

send_speech_bubble_to_object(clientComputerID, spaceObjectID, seconds, color, text)

attaches a speech bubble to a space object on the 2d radar.

send_story_dialog(clientID, title, text, face, color)

sends a story dialog to the targeted client (0 = server screen)

set_beam_damages(clientID, playerBeamDamage, npcBeamDamage, stationBeamDamage=1)

sets the values for player base beam damage, npc base beam damage, and station base beam damage.

set_client_string(clientComputerID, string_key, string_value)

stores a string value (and its string key) to the client computer

set_command_line(args)

TEST/DEV ONLY - pretend the engine was launched with these arguments.

Pass them WITHOUT the exe path; it is prepended, so callers do not have to fake one.

set_dmx_channel(clientID, channel, behavior, speed, low, high)

set a color channel of dmx.

set_main_view_modes(clientID, main_screen_view, cam_angle, cam_mode)

sets the three modes of the main screen view for the specified client.

set_music_folder(ID, filename)

Sets the folder from which music is streamed; ID is ship, OR client, OR zero for server.

set_music_tension(ID, tensionValue)

Sets the tension value of ambient music (0-100); ID is ship, OR client, OR zero for server.

set_shared_string(key, value)

sets (or changes) a shared string, given a key and a value (both strings).

set_sky_box(clientID, artFileName)

sets the skybox art for a clientID (0 = server).

set_sky_box_all(artFileName)

sets the skybox art for all connected computers.

show_gui_tag(clientID, tag)

makes a GUI element visible, on the targeted client (0 = server screen)

start_science_scan(ship_id, target_id, tab='scan')

Queue a scan of target_id's tab for ship_id. True if it was added.

This is what the science_data widget's "Start Scan" button does. The engine has no script API for it, so the mock owns the whole life cycle. Queuing the same (target, tab) twice is a no-op rather than a duplicate entry.

stop_science_scan(ship_id, target_id, tab='scan')

Drop a queued scan - the "Stop Scan" the button becomes once queued. Removing the ACTIVE entry simply promotes the next one.

super_hyper_warp_mode(clientID, ship_hull_key, on_off_flag)

turns on (or off) the super_hyper_warp_mode screen to a particular computer

suppress_client_connect_dialog(on_off_flag)

turns on (or off) the client connect dialog on the server (arg is 1 or 0)

torp_validate(kind)

Detect problems in a torpedo's shared-string definition (set by torpedo_type()). Returns a list of human-readable problems - empty if the def is clean (or absent, which just means defaults are used). Lets tools/tests check a mission's torp string without firing one. _torp_attrs degrades gracefully on these same problems.

transparent_options_button(clientID, on_off_flag)

for a specific client (0=server machine), turns on (or off) the Options button transparency (arg is 1 or 0)

unregister_client(client_id)

Remove a WebSocket client from the connected list.