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

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

clear_data(name)

deletes all elements in this blob value

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

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 integer ID

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

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 (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.

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.

space_object_exists(arg0)

returns true if the spaceobject exists, by ID

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_particle_emittor(spaceObject, lifeSpan, descriptorString)

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

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)

return a list of space objects that are currently inside an x/z 2d rect ARGS: 2D bounding rect, and bitfield

clear_client_tags()

stub; does nothing yet.

create_new_sim()

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

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

delete_object(ID)

deletes a space object by its ID

delete_particle_emittor(emittorID)

deletes a particle emittor by ID.

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_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.

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.

particle_at(position, descriptorString)

emit some particles in space.

particle_emittor_exists(emittorID)

checks for the existence of a particle emittor.

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.

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.

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_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

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_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)

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)

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.