MISSION SCRIPTING

The live SDK views

context.sdk is the activity view. It is a read-only window into the same data as the generated modules. It is bound to the running activity. Use it to look things up at run time. Most missions only need device_channels, device_transitions, squad_modes and atom_kinds from it.

Every value here is re-read on each access. A handle kept across a data change errors with “stale” instead of returning old data.

Collections

Every collection in this page has the same shape:

local slots = context.sdk.slots
for row = 1, slots.count do
    local slot = slots:at(row)
    -- use slot
end
  • count is the number of rows.
  • at(row) returns row row, counting from 1.
  • Some collections also have resolve(name_or_id) or by_id(n).

There is no pairs in the sandbox, so always walk with a number loop like this.

context.sdk members

sunrise/mission_api.json lists only the Identity and Vocabularies members below, and only matches on a message row. This page is the reference for the rest. See The generated SDK modules.

Identity

membertypemeaning
build_idstringSDK build id, sha256:<hex>
activity_idstringactivity id
activity_rowintegeractivity row
definition_hashintegeractivity hash
client_teleport_resetintegerthe teleport state the client reports after a spawn (0)

Activity binding

These describe how the activity is matched to its scenario. They are for tools, not missions.

membertype
internal_name, display_namestring or nil
join_status, binding_disposition, binding_reason, binding_evidence_basis, runnable_statusstring name
the same five with _codeinteger
binding_full_sdk_acceptable, has_internal_name, has_matchmaking_configboolean
selected_activity_root_tag, selected_scenario_tag, matchmaking_config_taginteger or nil
activity_root_candidate_tags, scenario_name_candidate_tags, evidence_root_tagscollection of integer tags
binding_locatorscollection of {tag, offset}; offset is a decimal string

Row collections

memberrows arelookup
squadssquad handlesat(row), resolve(id)
authored_scenesscene handlesat(row), resolve(id)
slotsslot handlesat(row), resolve(id)
activity_messagesmessage rowsat(row), by_id(message_id), resolve(name)
bap_servicesservice rowsat(row), by_request_id(n), by_response_id(n), by_notification_id(n)
squad_anchorssquad anchor rows of this scenarioat(row)

The squad, scene and slot handles are the same objects context:squad, context:scene and context:slot return. See Lua API reference.

A squad anchor row is one authored spawn point. squad.anchors holds the same rows for one squad. A row has id, world_id, row, collection_row, squad_row, point_ordinal, object_list_tag, placement_ordinal, flags, placed_entry_identity and position. placed_entry_identity is a decimal string and position is a vector.

Vocabularies

memberwhat it holds
device_channelsposition, power, lock; count
device_transitionsopen, close, power_on, power_off, lock, unlock; count, at(1..6)
squad_modesreinforce, replace, reserve; count
lifetime_statesat(0..10), default, count
atom_kindsa plain table of atom kind names
bounded_lanesfixed-size client lists; count; see below
unitfunction(number); makes a device channel value
positionfunction(x, y, z); makes a world position

Each entry and each made value is a handle with these fields:

valuefieldstaken by
a device channelname, value (the type-23 wire lane)set_channel, applied
a device transitionname, channel, value (a unit value)transition
a squad modename, value (the squad placement mode)place
a lifetime stateat(n); default is 3context.lifetime:set
unit(x)value, low (0), high (1); the range is not checkedset_channel
position(x, y, z)x, y, z; each must be finiteno request

Each transition moves one channel to one end:

transitionchannelvalue
openposition1
closeposition0
power_onpower1
power_offpower0
locklock1
unlocklock0

Deep views

memberview
catalogthe native catalog; nil when it is not ready
manifestthe scenario manifest; nil when it is not ready
worldthe generated world of this scenario; nil when it is not ready

Message rows

context.sdk.activity_messages lists the activity messages the client and host exchange. A script cannot send raw messages. The rows tell you which messages exist and which Lua surface handles them.

membermeaning
row, id, namerow, message id, name
directionremote_to_client, client_to_remote, bidirectional, client_to_remote_special, name_only
coveragehow well the wire format is known
can_receivetrue when a Lua event carries this message
can_sendtrue when a typed Lua action sends it
receive_apimessage_event, typed_event or none
send_apityped_actions or none
receive_surfaces, send_surfaceslists of {id, lua_name}
matches{event = e}true when event e is this message; only when can_receive
communication (or route)a plain table with the full route record
fieldscollection of field rows
plusdirection_code, coverage_code, definition_handle, call_form, definition_state, definition_struct_size, wire_min_bits, wire_max_bits, field_count, named_field_count, graph_field_count, authored_field_count, flags

A field row has row, global_row, message_row, ordinal, path, name, type, source, struct_offset, struct_offset_abs, type_code, bias, bits, bits_min, bits_max, width_or_count_offset, repeat, nested_handle, owner_handle, depth, flags, presence_bit, coined_name, documented_row, repeated_block, data_only, confidence and exposure, with _code forms for the named enums.

BAP service rows

context.sdk.bap_services lists the outer network services. It is data only. A script can never send one. The collection itself has count (also row_count), schema, and these fixed values:

membervalue
query_onlytrue
script_sendablefalse
runtime_authority"protocol"
raw_bodies"not_exposed"
activity_message_namespace"separate_inner_activity_message_id"

A row has row, id, service_id, request_service_id, response_service_id, notification_service_id, service_role, security, response_mode, acceptance_policy, body_shape, response_body_shape, body_exact_bytes, body_prefix_bytes, alternate_body_prefix_bytes, response_body_exact_bytes, typed_payload_limit, body_codec, body_codec_path, response_body_codec, response_body_codec_path, route, route_path, activity_message_envelope, inner_message_namespace, lifecycle_scope, protocol_scope and the size fields complete_encrypted_frame_overhead_bytes and complete_encrypted_frame_max_bytes. A size or id that does not apply reads nil.

Every row also has fixed values: service_id_namespace = "bap_service_id", runtime_authority = "protocol", data_only, executable and query_only are true, and script_sendable and raw_body_exposed are false.

Bounded lanes

Some client lists have a fixed size. A bounded list cannot grow past it.

lanekindsize
gameplay_switchescount50
activity_flagscount32
nav_nodescount96
nav_node_linkscount16
type8_field_1_0count32
type8_field_2_0count16
type8_object_refsobject_ref16
type53_object_refsobject_ref129
local lane = context.sdk.bounded_lanes.nav_nodes   -- name, capacity, kind
local list = lane:list()
list:append(7)          -- a count list takes int32 values
local first = list:at(1)

A list has count, capacity, lane, at(row) and append(value). append errors when the list is full.

An object reference list takes slot handles in append and returns slot handles from at. No request takes these lists.

The catalog view

context.sdk.catalog is the whole native catalog, not just this activity.

membermeaning
sdk_build_sha256, sdk_payload_sha256, content_key_sha256, logical_ir_sha25664-char hex digests
activity_client_generationdecimal string
activity_row, scenario_rowthis activity’s rows, from 1
definition_hash, scenario_tagintegers

Collections: activities, scenarios, bubbles, states, objects, occurrences, slots, texts, capabilities, gates, refusals, actor_classes, rsat_descriptors, rsat_schemas, rsat_fields, squads, squad_members, squad_anchors, authored_scene_resources, authored_scene_squad_edges, activity_binding_locators.

Every catalog row has row. A text field x also has x_string_offset and x_string_length. A range field x is read as x_first_index and x_count.

collectionfields
activitiesactivity_index, definition_hash, id, internal_name, display_name, scenario_index, flags, aliases, capabilities, selected_activity_root_tag, selected_scenario_tag, matchmaking_config_tag, join_status, binding_disposition, binding_reason, binding_evidence_basis, runnable_status, binding_flags; plus the collections activity_root_candidate_tags, scenario_name_candidate_tags, evidence_root_tags, binding_locators
scenariostag, reserved, id, name, bubbles, states, occurrences
bubblesid, name, scenario_index, bubble_ordinal, name_hash, reserved, states
statesid, entry_id, registry_id, scenario_index, bubble_index, state_ordinal, entry_index, slice_set_index, map_bubble_index, state_hash, public_value, flags, registry_tag
objectsid, object_tag, object_key, slots, config_count, descriptor_count, placed_subblock_count, placed_leaf_count, placed_hop_count, bare_target_count, replicated_placement_count
occurrencesid, context_registry_key, registry_id, entry_id, scenario_index, bubble_index, state_index, object_index, registry_field, object_ordinal
slotsid, name, sense_schema_id, auth_schema_id, object_index, slot_index, slot_type, component_class, sense_schema, auth_schema, flags, reserved, aliases, capabilities
textsvalue, kind, reserved
capabilitiesid, operation, value_schema_id, subject_kind, subject_index, exposure_flags, candidate_exposure_flags, gates, refusals
gatesgate, status, reason_code, required, observed, would_confirm
refusalsid, exposure, status, reason_codes, capability_index, reserved
actor_classesid, definition_tag, name_hash, rsat_tag, rsat_reverse_definition_tag, object_type, descriptor_array_offset, descriptor_array_relative, descriptor_array_header_offset, descriptor_array_data_offset, descriptor_element_class, descriptors, dynamic_presence_tail_count, authored_profile_0 to authored_profile_3
rsat_descriptorsid, actor_class_index, rsat_tag, descriptor_ordinal, descriptor_offset, descriptor_element_class, component_tag, schema_index, schema_tag, schema_field_count, schema_first_field_runtime_gate, schema_first_field_raw_u32_at_10, flags, dynamic_presence_tail_ordinal, raw_row
rsat_schemasid, schema_tag, schema_class, field_count, field_array_offset, field_array_relative, field_array_header_offset, field_array_data_offset, field_element_class, first_field_runtime_gate, first_field_raw_u32_at_10, flags, fields
rsat_fieldsraw_row
squadsid, scenario_index, object_index, slot_index, spawner_config_tag, spawn_rule_config_tag, flags, occurrence_index, members, anchors
squad_membersid, squad_index, member_ordinal, member_key, actor_class_index, flags, candidate_count_0 to candidate_count_5, default_count
squad_anchorsid, squad_index, point_ordinal, object_list_tag, placement_ordinal, flags, placed_entry_identity, position_bits_x, position_bits_y, position_bits_z
authored_scene_resourcesid, slot_index, config_tag, descriptor_offset, resource_field_offset, resource_tag, resource_class, flags, reserved
authored_scene_squad_edgesid, scene_slot_index, squad_slot_index, config_tag, descriptor_offset, reference_field_offset, target_object_key, flags, reserved
activity_binding_locatorstag, reserved, offset

Field names come from mission_script_catalog_sdk_bridge.cpp. A 64-bit value is a decimal string. A byte field is lowercase hex.

The manifest view

context.sdk.manifest describes the scenario shards and how activities bind to them.

membermeaning
format_versionmanifest format
source_fingerprint, sdk_build_sha256, sdk_payload_sha256, manifest_payload_sha256, shard_payload_sha256hex digests
activity_client_generationdecimal string
activity_row, scenario_tagintegers
binding_completenessone row: total, fixed_scenario, named_definition_unavailable, no_direct_fixed_activity_name, unresolved_runnable, status, status_name
scenariosrows: scenario_tag, scenario_name, shard_payload_sha256
activity_rootsrows: activity_root_tag, scenario_tag, transition_descriptor_tag, preferred_name, selection_status, selection_status_name
activity_variantsrows: activity_index, definition_hash, activity_root_tag, scenario_tag, matchmaking_config_tag, internal_name, the binding status fields, full_sdk_acceptable, has_internal_name, has_matchmaking_config, the tag collections, and binding_locators

Every manifest row has row. Field names come from mission_script_manifest_sdk_bridge.cpp.

The world view

context.sdk.world is the generated world of this scenario: every placed object, trigger volume, spatial table and name. It is the best way to find where something is.

membermeaning
scenario_tag, scenario_namethis scenario
sdk_build_sha256, sdk_payload_sha256, source_fingerprint, manifest_payload_sha256, shard_payload_sha256hex digests
diagnosticsload diagnostics; see mission_script_lua_world_metadata.cpp
coveragecollection of coverage rows: row, family, family_index, status, status_code, loss_mask, unread, dropped, partial, detail, coverage, coverage_code

Every world row has id, a stable text world/<scenario hex>/<kind>/<row>, and row. A field that points at another row is nil when there is no row. A vector field is a handle with x, y, z, w and count.

Placement and geometry collections

collectionmain fields
trigger_volumesregistry_key, slot_index, slot_type, config_tag, position, rotation, minimum, maximum, extrusion, active, vertices, triangles, config_name, shape_resource_name, complete
authored_placementsposition, rotation, uniform_scale, object_list_tag, class_list_tag, entry_index, name_hash, identifier, source_object_row, bubble_row, state_row, object_list_name, class_list_name
embedded_placementsposition, rotation, link_row, entry_index, class_list_tag, name_hash, identifier, object_type, class_list_name
container_placementsposition, rotation, uniform_scale, list_row, object_list_tag, resource_tag, resource_class, entry_index, object_type, object_list_name, resource_name, class_list_name, complete
static_spatial_instancesposition, rotation, scale, local_minimum, local_maximum, table_row, instance_index, table_tag, bounds_tag, resource_tag, table_name, bounds_name, resource_name

Squad anchors are not under world. Read them from context.sdk.squad_anchors or squad.anchors.

A trigger volume’s vertices and triangles are collections. A vertex has value, a triangle has a, b and c.

A <prefix>_name field is the best known name, or nil. The same prefix also has _name_provenance, _name_provenance_code, _name_candidate_count, _name_source_tag, _name_source_class and _name_strongest_tier_overflow.

Structure collections

collectionmain fields
bubblesindex, name_hash, first_state_row, state_count, is_public, selected_name
statesindex, bubble_row, slice_set_index, map_bubble_index, state_hash, entry_tag, registry_tag, enabled, resolved, selected_name, entry_name, registry_name
objectsobject_index, object_tag, registry_key, registry_tag, bubble_row, state_row, first_slot_row, slot_count, safety, complete, registry_name, object_name
slotsobject_row, slot_index, slot_type, name_hash, first_descriptor_row, descriptor_count, selected_name
descriptorsslot_row, config_tag, component_class, sense_schema, auth_schema, bubble_index, placement_identifier, config_name
typed_referencessource_object_row, source_slot_row, target_object_row, target_key, target_slot_index, target_slot_type, join

The rest are for tools: embedded_placement_links, container_placement_lists, container_placement_owners, container_placement_configs, container_placement_components, type23_placement_links, type23_placement_candidates, static_spatial_tables, static_spatial_owners, trigger_volume_tables, trigger_volume_owners, trigger_volume_incoming_references, trigger_volume_vertices, trigger_volume_triangles, names, tag_names, name_candidates, inline_name_candidates, authored_squad_config_contexts, authored_squad_placement_contexts, authored_squad_point_contexts, authored_squad_point_placement_matches, authored_squad_edge_contexts. Their full field lists are in mission_script_world_sdk_fields.cpp and mission_script_lua_world_rows.cpp.

Example: list the trigger volumes whose box holds a point

The box corners are stored as the package has them. Compare them with a position you read from the same data, for example a squad anchor.

local function volumes_at(context, x, y, z)
    local found = {}
    local volumes = context.sdk.world.trigger_volumes
    for row = 1, volumes.count do
        local volume = volumes:at(row)
        local low, high = volume.minimum, volume.maximum
        if low ~= nil and high ~= nil
            and x >= low.x and x <= high.x
            and y >= low.y and y <= high.y
            and z >= low.z and z <= high.z then
            found[#found + 1] = volume.config_name or volume.id
        end
    end
    return found
end

A walk over a large collection costs instructions. A callback has a budget of five million Lua instructions. Do such searches rarely, and store the answer in a variable.

A script cannot print. To see a result, store it in a variable and read it on the “Mission state” page. See Finding things in game.