MISSION SCRIPTING

Lua API reference

This is the full list of what a mission script can call and read. One table in the Sunrise source, server/activity/mission/mission_api.h, declares every member, argument and event field. The runtime dispatches from that table, and the generator writes it out as sunrise/mission_api.json; see The generated SDK modules.

The live SDK views (context.sdk.catalog, world, manifest, the row collections and the bounded lanes) have their own page, The live SDK views.

How to read this page

  • context:name(...) is a method. Call it with a colon.
  • context.name is a field. Read it with a dot.
  • Most requests take one table of named arguments: slot:transition{transition = t}.
  • An unknown key in that table is an error. A misspelled key never passes silently.
  • A request returns a RequestKey. See “Request keys”.
  • A 64-bit number is always a decimal string, because a Lua integer cannot hold every value.
  • “slot of type N” means the method errors on any other slot type.

Handles

Every object the API gives you is a locked handle. You cannot add fields to it, read its metatable, or build one yourself. A handle re-checks its row on every read. If the data changed under it, the read errors with “stale”.

handlehow you get it
contextfirst callback argument
statesecond callback argument
eventthird callback argument
slotcontext:slot(...), event.slot, context.sdk.slots:at(n)
squadcontext:squad(...), context.sdk.squads:at(n)
scenecontext:scene(...), context.sdk.authored_scenes:at(n)
request keyreturned by every request
cohortcontext:cohort{...}
lifetimecontext.lifetime

Context

The first argument of every callback.

Fields

fieldtypemeaning
sdkactivity viewthe live SDK; see The live SDK views
sdk_build_idstringsha256:<64 hex>
activity_idstringactivity id
activity_rowintegeractivity row
definition_hashintegeractivity hash
activity_rolestring"public" or "private"
player_keystringthe linked player’s key, decimal
attempt_generationstringcurrent attempt, decimal
mission_completebooleantrue after complete_mission was accepted in this attempt
host_unix_secondsintegerthe host wall clock in Unix seconds, read at each access
lifetimelifetime handlesee “Lifetime”
mod_configmod config handlesee “Mod config”
peerspeer collectionsee “Peers”
timerstimer name collectionsee “Name references”
variablesvariable name collectionsee “Name references”

Mod config

context.mod_config holds the config of the mod that supplied the script.

context.mod_config.<key> returns the current value of one entry the mod declares in its mod.json. An int entry reads as an integer, a float entry as a number and a bool entry as a boolean. An undeclared key reads as nil, and so does every key in a base or generated script. The value is read at each access, so a change on the Mods page applies at once. The handle is read-only.

local respawn = context.mod_config.respawn_ms or 5000

Lookups

methodreturnsnotes
context:slot(selector)slot handleselector is a mission.Slot id string or a slot row number
context:squad(selector)squad handleselector is a mission.Squad id string or a squad row number
context:scene(selector)scene handleselector is a mission.Scene id string or a scene row number
context:cohort{squads = list}cohort handlesee “Cohort”

Row numbers start at 1. Pass the id string or the row number, not a handle. An unknown selector is an error, for example “unknown or ambiguous activity slot”.

Mission state

methodreturnsnotes
context:set_variable(name, value)nothingvalue is a boolean, integer, finite number or string up to 127 bytes
context:clear_variable(name)booleantrue when the variable existed
context:start_timer(name, ms)stringthe timer sequence; ms is 0 to 4294967295; replaces a timer with the same name
context:cancel_timer(name)booleantrue when the timer existed
context:set_phase(n)nothingn is 0 to 4294967295; a change raises phase_entered

A name is 1 to 63 bytes of letters, digits, _, -, . and /. nil is not a value; use clear_variable.

Per-save flags

A flag is a value kept in the player’s save. It outlives the activity. Variables do not.

methodreturnsnotes
context:set_flag(name, value)nothingvalue is a boolean or an integer; nil removes the flag
context:get_flag(name)boolean, integer or nilsees a set_flag made earlier in this callback
  • Names follow the variable name rule.
  • Flags are kept per mod. A script reads only the flags of the mod that supplied it.
  • A callback writes its flags to the save when it commits. A failed save write faults the program.
  • One callback may write up to 32 flags.
  • When the game runs on a session copy of the save, a flag lasts only for that run.

Other queries

methodreturnsnotes
context:random()numbera server random number in [0, 1); only inside a callback
context:public_event_schedule{site, now}table or nilsee below

random errors when the server has no entropy. A random choice is lost on reload unless you store it with set_variable.

public_event_schedule returns the authored public event schedule of one site, as the client computes it. site is the site’s roster key. now is Unix seconds; 0 or absent reads the host clock. It returns nil before the schedule is read, or for a site no row lists.

fieldmeaning
stateincoming or active
until_startseconds to the start; 0 while active
until_finishseconds to the end of the window
slot_start, start, finishUnix seconds
slot, rowthe schedule slot, and its row from 1
selectedthe slot’s pick is this site
site, node, rallythe picked site’s roster key, map node and rally key; may be nil

World requests

methodargumentsnotes
context:select_state(state, options)state: a mission.states row; options: see belowload another authored state; moves the player when needed
context:activate_objects{slots, active, capture_plate, position}see belowreturns a list of request keys, one per object group
context:complete_mission{}nonecompletes this attempt; errors when already complete
context:hold_spawn{active}active: required booleanhold the player’s spawn, or release it
context:restart_checkpoint{region, spawn_set_hash, release_request}see belowwipe and restart the party
context:teleport{region, spawn_set_hash}see belowmove every player to a spawn set
context:set_activity_flag{key, raised}key: 1 to 4294967295; raised: required booleanraise or lower one activity flag
context:send_incident{target, payload}see belowsend one activity incident to the client

A held spawn keeps the roster’s spawn gate closed, so the player has no body yet. Use it when the mission opens on a cutscene. Release it with active = false when the player should arrive.

activate_objects arguments:

keytypemeaning
slotslist of type-4 slot ids or handleseach once; objects that share an owner go in one request
activebooleandefault true
capture_platebooleanalso send the capture-plate component; default false
position{value, snap}set the object’s state-machine position; value 0 to 1; snap default true

A raised activity flag is listed in every participation record of the activity. Authored content that tests an activity_flag condition reads it. The list holds 32 flags.

send_incident arguments:

keytypemeaning
targetinteger 0 to 7762the incident row; require("sunrise.incidents").Notification names each notification
payloadstring, up to 500 bytesraw body bytes; absent sends the empty notification body, "" sends none

A notification needs no payload. The client shows its text. A target the client cannot handle safely is an error at the call: “send_incident target N is poisoned”. An accepted incident ends with the outcome queued.

select_state options is either a plain list of slots whose objects stay out of the seed, or a table with:

keytypemeaning
[1], [2], …slot idseach slot’s object stays out of the new state’s seed; up to 32
retire_placed_propsbooleanend the map props captured from the old state before the move
spawn_set_hashinteger 1 to 4294967294the spawn set this arrival uses instead of the declared one

Any other named key is an error. A spawn_set_hash that the target region does not declare is refused.

restart_checkpoint arguments:

keytypemeaning
regioninteger 0 to 1022the region the party is in
spawn_set_hashinteger 1 to 4294967294the authored spawn set to restart at
release_requestdecimal string, optionalthe value of the arming request; releases the wipe

region and spawn_set_hash are required, also on a release.

Arming is refused unless the activity is private, the whole party is dead, the party is in region, and the spawn set exists. An accepted arm starts a new attempt. See “Wipe and restart at a checkpoint” in Recipes.

teleport arguments:

keytypemeaning
regioninteger 0 to 1022the region to arrive in
spawn_set_hashinteger 1 to 4294967294a spawn set that region declares

Both are required. The request is refused in a public activity, during a hard wipe, when the spawn set does not exist or has no point, and when the region does not declare the set. An accepted request finishes at once and the move follows. Every player in the party moves. Each sees a loading screen, then arrives at the spawn set. A move inside one region reloads the region. The client’s region legs change during a move, which raises client_state_changed. The set stays the spawn set of that region.

State

The second argument of every callback. Read-only.

memberreturnsnotes
state.phaseintegerincludes a set_phase made earlier in this callback
state.revisionstringthe committed state revision
state:variable(name)value or nilsees changes made earlier in this callback
state:has_variable(name)boolean
state:timer(name)string or nilthe timer’s deadline tick

Request keys

Every request returns a RequestKey.

membermeaning
key.valuethe key as a decimal string
key:matches(other)true when two keys are the same request

A key handle is lost on reload. Store key.value in a variable when you need to match the result later.

local key = context:select_state(mission.states.STATE_X)
context:set_variable("state_request", key.value)

Slot

Fields

fieldtypemeaning
rowintegerslot row in this activity
idstringsame as the mission.Slot value
namestringauthored name
object_idstringowning object id
object_tagintegerowning object tag
registry_keyintegerregistry key the client uses
slot_indexintegerindex in the registry
slot_typeintegerthe slot type
component_classintegercomponent class id
sense_schema, auth_schemaintegerreport and request schema ids
sense_schema_id, auth_schema_idstringthe same as text
auth_typestring or nilrequest type name, for example device_sensor
auth_min_bits, auth_max_bitsinteger or nilrequest body size
auth_component_offsetinteger or nil
auth_dynamic, auth_writableboolean or nil
flagsintegercatalog flags
point_countintegerauthored points of the slot; atoms and abilities name them from 0

Methods by slot type

Every method below returns a RequestKey unless the table says otherwise.

methodslot typearguments
set_object_active{active, with, at}4active default true; with: up to 63 more type-4 slot ids, not handles, sent together; at: a type-1 squad slot handle; each object spawns at the centre of that squad’s living members
set_interactable_object{active, used, track_owner, usable, respawn, timer}4see below
set_object_channels{values, blend_seconds}24values: 1 to 4 numbers, -100 to 100, for the first authored channels; later channels keep their value; blend_seconds default 0
watch_damage{target}20target: a type-4 slot handle
set_object_filter{players, target, targets, squad, squads, inside, inside_any}34see below
attach_hop_on{filter}26filter: a type-34 object filter slot handle; see “Hop-on sensors”
detach_hop_on()26removes the hop-on from every object that carries it
set_engagement{volumes, clear, everyone}70see below
set_occupancy_condition{value, filter}30value: int32; filter: optional slot handle; without it the client measures its default player set
set_darkness_zone{enabled, wipe_seconds}35enabled default false; wipe_seconds -1 (none) to 3, default -1; a countdown needs enabled
generate_map{record, seed, mode, anchors, enabled, values, reals, state_key}37see below
set_music_section{section, enabled}11section 0 to 127; enabled default true
set_ghost_link{active}65active default true
ghost_link()65returns {generation, progress, active}, or nil until the client reported all three; not a request
transition{transition, snap}23transition from context.sdk.device_transitions; snap default false
set_channel{channel, value, snap}23channel from context.sdk.device_channels; value from context.sdk.unit(x); snap default false
applied{channel}23returns boolean; not a request
fire_trigger()31arms the trigger
disarm_trigger()31stops it reporting
set_volume_active{volume, active}32volume: a type-60 slot handle on the toggle’s own object; active: required boolean; turns that volume on or off
set_directive{directive, state, active, settled, navpoint, waypoint, audience, progress, event, clock}68see below
clear_directives()68hides the goal
set_public_event_state{area, leave_seconds, state, player}71see below
play_sequence{choice, restart}5plays the authored sequence; see below
play_sequence{sequence}2plays an actor sequence; see “Actor sequences”
sequences()2returns the actor’s sequence collection; not a request
set_cinematic_active{active}6active default true
reset_objectives()3resets every task of the objective
task_counter{group, task}3returns one task’s counter, or nil before the objective reports it; not a request
advance_task()38advances the authored task bit
play_performance{state}42state: a mission.PerformanceState entry; may be left out when the target has one state
play_dialogue_cue{cue, filter}53cue 0 to 65535, a mission.DialogueCue value; a cue past the sensor’s cue count is refused; filter: optional type-60 slot handle
assign_combat_objective{objective, task_group, reconsider, reserved, refresh_player_awareness, temperaments}1see below
run_atoms{atoms, spawn, temperaments, channels}2see “Atom programs”
play_actor_path{path, spawn}2path: a type-58 slot on the same object
play_actor_action{ability, target, spawn}2one ability atom
set_actor_controls{temperaments, channels}2see “Actor controls”
deliver_passengers{squads}2see “Carriers”
retire_actor()2removes the actor
bind_combatant_to_squad{spawn, retire_on_return}2arms the actor for its scene’s squad spawn; see below

“Slot handle” means a value from context:slot(...), not an id string.

bind_combatant_to_squad takes two booleans, both default false. spawn = true starts a new actor life in the same body, for a combatant whose actor is gone. retire_on_return = true lets the host retire the bound actor when the client gives it up on leaving the bubble.

task_counter takes group, a mission.TaskGroup entry of this objective, and task, the task’s position in the group’s tasks list, from 0 to 23. A task admits no more squads once its counter reaches the task’s counter_limit.

set_interactable_object

keytypemeaning
activebooleandefault true
usedbooleandefault false
track_ownerbooleanreport the object’s owner; default false
usablebooleanfalse keeps the object in place but no player can use it; default true
respawnbooleanfalse keeps the object’s generation, so the object updates where it stands; default true
timer{elapsed, remaining, active}a stopped timer for the object’s timer component; seconds, 0 or more; remaining = 0 completes it

A timer completes only while its active is true.

set_object_filter

keytypeadds this test
playersbooleanobjects that are players
targettype-4 slot handle, or an exact type-2 combatantthis one object
targetslist of 1 to 8 type-4 slot handlesone test per object
squadtype-1 slot handlethis squad
squadslist of 1 to 8 type-1 slot handlesone test per squad
insidetype-60 slot handleobjects inside this volume
inside_anylist of 1 to 5 type-60 slot handlesobjects inside any of these volumes

All tests share eight places. A filter that needs more is refused.

set_engagement

Call it on a type-70 engagement sensor. It sets which players count as the encounter’s audience.

keytypemeaning
volumeslist of 0 to 8 type-60 slot handlesvolumes of the same object; a player inside one joins
clearbooleanempty the members the client has gathered; default false
everyonebooleanalso admit every present player; default false

The sensor’s reports raise engagement_state.

Hop-on sensors

A type-26 sensor carries an authored hop-on. attach_hop_on{filter} attaches it to every object the type-34 filter selects. It keeps doing so as objects start and stop matching. Set the filter first with set_object_filter. detach_hop_on() removes it again.

hop_on_state reports attached and the request_key of the attach or detach the client last applied.

set_directive

keytypemeaning
directivea mission.Directive entrythe goal to show; it must belong to this sensor
stateinteger 0 to 2directive state; default 0
activebooleantrue plays the active transition and lets the goal complete; false shows it as incoming; default false
settledbooleanthe HUD shows the goal as already presented and plays no transition; not with active; default false
navpointtype-47 slot handlemap marker target
waypointtype-60 slot handlevolume where the marker hides
audiencetype-70 slot handleengagement sensor for the mission banner
progresslist of 1 to 4 int32 valuescounter values, for example {current, maximum}
eventtype-71 slot handlepublic event sensor whose state the HUD record copies
clock{remaining, total}a countdown in whole seconds beside the goal; each 0 to 31536000; remaining at most total

progress works only on a directive whose entry has counter = true. On any other directive it is an error, because the HUD would ignore the values.

play_sequence on a type-5 slot

keytypemeaning
choiceinteger 0 to 127the choice to play, counted across the sequence’s choices
restartbooleandefault true; false keeps the running sequence and moves it to choice through its transitions

play_sequence() with no arguments plays the authored sequence.

generate_map

Call it on a type-37 map generator slot. The body holds two generator records. The call writes one of them. Every field you leave out keeps its authored value. The exception is state_key, which defaults to 0.

keytypemeaning
record1 or 2which record to write; default 1
seedinteger up to 4294967295the generator seed; a negative value keeps the authored seed
enabledbooleanturns the record on or off
modeinteger -128 to 127raw mode byte
anchorslist of exactly 4 tableseach {first, second, value, enabled}; first and second are -128 to 127
valueslist of up to 5 int32raw integer inputs; -1 in the first two keeps the authored value
realslist of up to 2 numbersraw number inputs
state_keyinteger 0 to 4294967295default 0

The meaning of mode, anchors, values and reals is not known yet. The existing scripts send only seed and enabled:

context:slot(Slot.MAP_GENERATOR_SENSOR):generate_map{seed = 12345, enabled = true}

set_public_event_state

keytypemeaning
areaslot handlethe object whose zone bounds the event area; required
leave_secondsfinite number 0 or moreseconds outside the area before the client reports it; required
stateint32shown by the HUD; default 0
playerdecimal stringthe watched player; default context.player_key

assign_combat_objective

Call it on the squad’s type-1 slot.

keytypemeaning
objectivetype-3 slot handlerequired; must be in the same registry as the squad
task_groupa mission.TaskGroup entrywhich task group to use; must belong to objective; default none
reconsiderbooleanforce the squad to pick again; default false
reservedbooleanreservation flag; left out keeps the current reservation
refresh_player_awarenessbooleandefault false
temperamentslist of mission.ActorTemperament entriesreplaces the squad’s temperaments without a new spawn; left out keeps the last list

Inside on_event_squad_state for the same squad, the request carries the reported objective revision, so the host can reject a stale change.

Temperaments and channels

A temperament is a behavior switch the actor’s behavior program holds. A channel is a number the program reads. Both come from the generated module: mission.ActorTemperament.<slot>.KEY_<hash> and mission.ActorChannel.<slot>.KEY_<hash>. Pass an entry only to the slot or squad it is listed under. A squad’s entries are under its slot key.

wheretakes
squad:place{temperaments}up to 6 distinct temperaments; every member merges them
assign_combat_objective{temperaments}the same list, without a new spawn
set_actor_controls{temperaments, channels}one actor’s whole control set
run_atoms{spawn = true, temperaments, channels}the controls a new actor starts with

A channel entry in a list is {channel = mission.ActorChannel.X.KEY_..., value = n}. A list holds up to 16 channels, one value each, and value is a finite number.

Actor controls

set_actor_controls{temperaments, channels} replaces the live actor’s whole control set. Its running program keeps going. A list left out is empty. A channel must be one that nothing on the actor drives, or one its program reads.

Carriers

A carrier is an actor that brings squads in, such as a dropship.

  1. Reserve each passenger squad on the carrier with squad:place{mode = reserve}.
  2. Fly the carrier with run_atoms or play_actor_path.
  3. Call deliver_passengers{squads = {...}} on the carrier. squads lists 1 to 8 type-1 slot handles of the carrier’s own object, each once.

The carrier unloads them through its passenger list. actor_path_state names the request in delivery_request_key. delivery_state reads 0 once no passenger is left to unload.

Squad

Fields and methods

memberreturnsmeaning
row, id, nameidentity
member_countintegermembers in the squad
default_countslistauthored count per member
anchorscollection or nilspawn points as world rows; nil when the world is stale; see The live SDK views
counts()count vectora new vector filled with the defaults
place{counts, mode, spawn_rule, retire_on_return, temperaments}RequestKeyspawn the squad
actor_command{command, value}RequestKeysend one command to every live member

place

keytypemeaning
countscount vector from this squadhow many of each member; default the authored counts
modefrom context.sdk.squad_modesreinforce (default), replace or reserve
spawn_ruletype-66 slot handlereplaces the authored spawn rule
retire_on_returnbooleanlet the host retire the squad’s old entities when the client returns them; default false
temperamentslist of mission.ActorTemperament entriessee “Temperaments and channels”; an empty list clears them; left out keeps the last list

A count vector from another squad is an error.

Count vector

membermeaning
countnumber of members
capacity8; counts() errors on a squad with more members
at(i)count of member i, from 1
set(i, n)set member i to n, 0 or more
local squad = context:squad(mission.Squad.SQ_GUARDS)
local counts = squad:counts()
counts:set(1, 3)
squad:place{counts = counts, mode = context.sdk.squad_modes.replace}

actor_command

keytypemeaning
commandinteger 0 to 4294967295a mission.ActorCommand value
valueint32the command value, for example a mission.Faction value

Scene

memberreturnsmeaning
row, ididentity
activate{spawn, initial_event}RequestKeystart the scene; spawn = true also spawns its authored cast, default false; initial_event is a mission.SceneInput key the start already carries
stop{}RequestKeystop the running scene
send_event{key}RequestKeyfire one input of the running scene; key is a mission.SceneInput entry, 1 to 4294967294

A key or initial_event that no block of this scene waits on is refused: the effect_result outcome is refused, and the log names unknown_event. Take it from this scene’s own mission.SceneInput entries.

activate{spawn = true} errors when the scene has no single authored cast.

Cohort

A cohort is a read-only view of 1 to 64 squads. squads takes squad ids or squad handles, each once.

local group = context:cohort{squads = {mission.Squad.SQ_A, mission.Squad.SQ_B}}
if group.cleared then
    -- every squad in the group is dead
end
fieldtypemeaning
alive_countinteger or niltotal alive; nil while any squad is unknown
observed_fullbooleanevery squad was seen at full strength
observed_aliveboolean or nila member of any squad was seen alive; nil while any squad is unknown
clearedbooleanseen full, and now all dead
sizeintegernumber of squads
membersintegermembers the squads hold in this attempt: the placed counts, more when more were seen, or the authored members of a squad with no counts

A squad with a placement still in the queue counts as unknown. So cleared is false until the placement is delivered and the client has reported the squad.

Lifetime

context.lifetime:set{state = s} sets the activity lifetime state. s comes from context.sdk.lifetime_states:

membermeaning
at(n)state n, 0 to 10; its value is n
defaultstate 3
count11

complete_mission sets state 6 for you. Prefer it.

Peers

context.peers lists the other sessions in this activity.

membermeaning
countnumber of peers
at(i)peer i, from 1

A peer has session_id, session_generation, member_key and join_identity, all decimal strings.

A peer handle follows its session, even when the list order changes. After that session leaves, reading the handle is an error: “peer session is no longer in the published set”.

Name references

context.timers:resolve(name) and context.variables:resolve(name) check a name and return a handle with a name field. capacity gives the store size (32 and 512). They only check names. No request takes them yet.

Value types

Device channels, device transitions, squad modes, lifetime states, context.sdk.unit(x) and context.sdk.position(x, y, z) make the values that set_channel, transition, place and context.lifetime:set take. Vocabularies lists each one, its fields and the six transitions.

Actor sequences

slot:sequences() on a type-2 actor returns its sequence collection.

membermeaning
countnumber of sequences
at(n)sequence n, from 1, or nil
<SYMBOL>the sequence with that symbol, or nil
KEY_<8 hex>the sequence with that key hash, or nil

A sequence has id, name, symbol, source_path, key, kind, resource_tag, table_index, ordinal, source_offset and playable.

local actor = context:slot(mission.Slot.SQ_BOSS_BOSS)
local sequence = actor:sequences().BERSERK_ANIMATION
if sequence ~= nil and sequence.playable then
    actor:play_sequence{sequence = sequence}
end

Only a playable sequence of this same actor is accepted.

Atom programs

slot:run_atoms{atoms = list, spawn = flag} sends a small program to a type-2 actor. The list has up to 32 atoms, run in order. An empty list releases the current program. Each atom is a table with a kind. context.sdk.atom_kinds holds the kind names.

kindfieldsmeaning
facetarget, valueturn to a point of target
snap_totarget, valuejump to a point of target
move_totarget, value, enabledmove to a point of target
sequencevalueplay a sequence by number
sleepsecondswait
trivialnonean empty step
control_flagvalue 0 to 63, default 0set a control flag
set_temperamentvalue, enabledset a temperament
set_channelchannel, valueset an actor channel to a number
abilityability, targetuse a mission.ActorAbility entry of this actor
  • target is a slot handle. value on face, snap_to and move_to is an authored point number of that target, 0 to 255, default 0. An unknown point is an error.
  • value on sequence and set_temperament, and channel on set_channel, are 0 to 4294967295. seconds and the set_channel value are finite numbers.
  • enabled defaults to false. Any value other than nil or false counts as true.
  • An ability must belong to this actor. Its optional target must have an authored point 0.
  • An ability atom refuses unknown fields. The other kinds ignore them.
  • Any atom may add quantized, 0 to 2047.
  • spawn = true creates the actor from its authored source first. It errors when the actor has no single authored source.
  • temperaments and channels need spawn = true. The new actor starts with them. Left out, the actor keeps its current ones. See “Temperaments and channels”.

play_actor_action{ability, target, spawn} is a one-atom ability program. play_actor_path{path, spawn} sends the actor along an authored type-58 path that has a destination.

Events

Every event has these fields:

fieldtypemeaning
kindintegerthe EventKind number; compare it with require("sunrise.activity_sdk").EventKind.SQUAD_STATE and the like
sequencestringevent order number
source_generationstringclient generation that produced it
attempt_generationstringattempt it belongs to

Most events also have mission_sequence (string), the input order. The events marked “no mission_sequence” in “Fields per event” do not.

Slot identity

Events about one slot also have:

fieldtype
slotslot handle, or nil when the slot is not in this activity
registry_key, object_tag, slot_index, slot_typeinteger

To test an event against a slot:

local function is_slot(context, event, id)
    return event.slot ~= nil and event.slot.id == context:slot(id).id
end

Fields per event

A field that the report did not carry reads nil. A field of another event kind also reads nil, so one handler can test the fields of several kinds. The first column is the callback name without its on_event_ prefix.

eventfields beyond the common ones
region_changedregion_index; previous_region_index (nil the first time)
client_state_changedclient_message_sequence, payload_bytes, activity_state_revision, membership_revision, region_index, current_region_index, held_region_index, region_slice_set_hash, spawn_state, teleport_state, teleport_slice_set_index, teleport_slice_set_hash, entered
player_triggerslot identity; volume_registry_key, volume_slot_type, volume_slot_index, resolved_object_id
trigger_entered, trigger_exitedslot identity; member_count, value, all_inside
trigger_stateslot identity; Sense generation; available, continuity, occupied, member_count, value, all_inside; the last four are nil when available is false
squad_stateslot identity; Sense generation; alive_count, previous_alive_count, removal_flag, slot_counts (list), initial_observation, population_available, objective_revision, alert_level, task_costs; methods task_cost{group}, task_group{objective}
squad_member_lostslot identity; Sense generation; member_slot, lost_count, previous_lost_count, removal_flag
entity_spawnedslot identity; Sense generation; member_slot, count, previous_count; never raised yet
entity_diedslot identity; Sense generation; alive_count, previous_alive_count, removal_flag
squad_provokedregistry_key, slot_type, slot_index; no slot
damage_stateslot identity; health, shield, revision, from_entity, health_level, shield_level, entity_slot, entity_incarnation, allocation_sequence, allocation_domain, suppressed, first_auth_applied
object_state, object_interactedslot identity; Sense generation; generation, present, alive (same as present), interaction_open, owner_known, has_owner, owner_key, initial_observation (first report of this generation), entry_index (the authored entry the object came from), spawn_mask_low, spawn_mask_high, plate_owner, plate_capturing, plate_occupants, plate_progress
device_stateslot identity; position, power, lock, position_sequence, power_sequence, lock_sequence, first_report, reset; method applied_request{channel}
ghost_link_stateslot identity; generation, progress, active
hop_on_stateslot identity; attached, request_key
engagement_stateslot identity; Sense generation; member_count, keys_decoded, local_member, value, complete, first_report
integrationreport_value, report_kind, context
actor_path_stateslot identity; generation, revision, path_state, delivery_revision, delivery_state, suppressed, request_key, delivery_request_key
scene_finishedslot identity; activation_token
scene_outputslot identity; key, the output key; activation_token of the run that reported it
objective_progressslot identity; objective, task, task_count, previous_task_count
cinematic_started, cinematic_terminated, cinematic_skip_requestedslot identity; runtime_object_id (string), event_value
fireteam_statealive_count, dead_count, unknown_count
session_joinedsession_id, session_generation, member_key, joined_revision
session_leftsession_id, session_generation, member_key
timer_elapsedtimer_name, timer_deadline_tick, timer_sequence
phase_enteredphase, previous_phase, state_revision
effect_resultrequest_key, effect, outcome, outcome_code
entity_slots_requestedrequested_count
sensor_sense_updatedclient_message_sequence, payload_bytes, state_revision, peer_heard_mask, objects_decoded, groups_decoded; slot identity of the first object, when there is one
incident_receivedclient_message_sequence, payload_bytes, incident_target, incident_extra_targets, incident_selector_bytes, incident_payload_bytes
incident_queued, incident_transport_staged, incident_canceled, incident_refusedincident_revision, incident_target, incident_extra_targets, incident_selector_bytes, incident_payload_bytes; no mission_sequence
client_message_receivedclient_message_sequence, payload_bytes, peer_heard_mask, state_revision, message_type, message_status, message_name, message
auth_state_committed, auth_state_transport_staged, auth_state_canceledstate_revision; no mission_sequence
scriptable_override_committed, scriptable_override_transport_staged, scriptable_override_canceledscriptable_revision; no mission_sequence
operator_refusedstate_revision; no mission_sequence

“Sense generation” is two fields, each nil when the report did not carry it:

fieldmeaning
spawn_generationthe spawn generation a squad report echoes from its placement
sense_generationthe report’s record counter, plus one

trigger_state comes from a type-30 occupancy monitor on every report it accepts, the first one included. It skips a stale report and an exact repeat. continuity says how the report relates to the one before: baseline, consecutive, duplicate, conflict, gap, reset, missing_counter, wrap or invalid. The event only informs. trigger_entered and trigger_exited still follow the occupancy level alone.

On incident_canceled the four body fields are 0 when there is no record. On incident_refused, incident_revision is always 0. On operator_refused, state_revision is 0 on most refusals.

client_state_changed in detail

The client sends state reports often, even while it loads. Most carry no change.

fieldpresent when
enteredtrue only on the host’s arrival answer; nil otherwise
held_region_indexthe host knows which region the client holds
region_indexthe report names a region leg
current_region_indexthe report names the current region
spawn_statethe report carries a spawn byte
teleport_statethe report carries a teleport byte; context.sdk.client_teleport_reset (0) marks a finished spawn

Use region_changed to react to movement. Use client_state_changed with entered == true to react to the first arrival.

squad_state in detail

membermeaning
slot_countsper member slot, the count the squad report carries; Sunrise reads it as members lost since the placement (unverified); a new spawn generation clears them
initial_observationthe first report of this squad; never a death
population_availablefalse until an alive count is reported; until then the counts are placeholder zeros
objective_revisionthe objective revision the squad echoed with its costs; 0 before any
alert_level0 never alerted, 1 alerted before but no member alerted now, 2 alerted, 3 in combat
task_coststhe reported cost per task group, keyed from 1; a group without a cost is absent
event:task_cost{group = g}cost (number or nil) and known (boolean) for a mission.TaskGroup entry
event:task_group{objective = slot}the current group (compares equal to a mission.TaskGroup entry) or nil, and assigned (boolean)

A change of the alert level alone raises squad_state.

squad_member_lost fires when one member slot’s count in slot_counts rises. lost_count is that count. Whether the game counts members lost or members created is unverified, so do not treat it as a kill count yet. member_slot counts from 0, so slot 0 is slot_counts[1]. One report raises squad_state first, then squad_member_lost per slot, then entity_died.

damage_state in detail

fieldmeaning
health, shieldthe reported levels
from_entitytrue when a replicated entity’s damage pool reported
health_level, shield_levelthe entity’s pool levels, when known
entity_slot, entity_incarnation, allocation_sequence, allocation_domainthe entity; nil unless from_entity
suppressedthe combatant’s actor is suppressed; health and shield read -1
first_auth_appliedthe combatant applied its first request; until then health and shield read -1

suppressed and first_auth_applied are nil for any reporter other than a combatant.

Capture plates

object_state carries four plate fields when the object has a capture plate. Send the plate with activate_objects{capture_plate = true}.

fieldmeaning
plate_ownerthe owner team; -3 before a capture
plate_capturingthe team capturing it; -1 for none
plate_occupantsa mask of the players on the plate
plate_progresscapture progress, 0 to 1

engagement_state and integration

engagement_state comes from a type-70 engagement sensor. It fires when the member count, the local membership or value changes.

fieldmeaning
member_countparticipants the client reported, at most 16
keys_decodedparticipant keys kept from the report
local_memberthis link’s player is in the list
valuea 16-bit field of the report; its meaning is unknown
completeevery reported key was kept
first_reportthe first report of this sensor since attach

A nonzero member_count alone does not mean this player is a member. Read local_member.

integration is one report from a Vex sacrifice trigger. It has no slot. How reports map to progress is up to the script.

actor_path_state request keys

request_key is the run_atoms or retire_actor request whose program revision this report echoes. delivery_request_key is the deliver_passengers request it echoes. Each is nil when the report echoes none of the last few requests.

device_state:applied_request

event:applied_request{channel = c} returns the RequestKey that this report satisfied on channel c, or nil.

effect_result

fieldmeaning
request_keythe key of the request
effectthe request name from the list below, or nil for any other request
outcometransport_staged, refused, expired, canceled or queued
outcome_code0 to 4 in the same order

effect names, 29 in all:

groupnames
squad and scenesquad.place, scene.activate, scene.stop, scene.send_event
objects and devicesslot.set_object_active, slot.set_interactable_object, slot.set_object_channels, slot.set_channel, slot.watch_damage, slot.set_ghost_link, slot.fire_trigger
actorsslot.run_atoms, slot.set_actor_controls, slot.retire_actor, slot.deliver_passengers, slot.assign_combat_objective
presentationslot.play_sequence, slot.set_cinematic_active, slot.play_performance, slot.reset_objectives, slot.advance_task, slot.play_dialogue_cue
missionlifetime.set, mission.set_activity_flag, mission.restart_checkpoint, mission.select_state, mission.hold_spawn, mission.send_incident, mission.teleport

Some requests report the name of the effect they share. complete_mission reports lifetime.set. activate_objects reports slot.set_object_active. transition reports slot.set_channel. disarm_trigger reports slot.fire_trigger. play_actor_path and play_actor_action report slot.run_atoms.

effect is nil for bind_combatant_to_squad, actor_command, attach_hop_on, detach_hop_on and every other slot request without a name above.

client_message_received

fieldmeaning
message_typethe message id
message_statusunclassified, decoded, decoded_partial, prefix_only, opaque, outer_decoded, prepared, prepare_refused, malformed or quarantined
message_namethe catalog name, or nil
messagethe catalog message row, or nil; see The live SDK views

A message row’s matches{event = e} tells whether an event is that message.

Errors you will see

messagecause
effect argument is not declareda misspelled or extra key in the argument table
effect arguments must be one tableyou passed a value that is not a table
<key> must be a <type>wrong type for a named argument
unknown or ambiguous activity slotthe id is not in this activity; squads and scenes say activity squad and authored scene
activity slot is not an exact type-N ...the method does not fit this slot type
activity slot is stalethe data changed under a handle you kept
mission variable name is invalidempty, too long, or a bad character
mission variable value is not a bounded scalarnil, a table, a non-finite number or a long string
mission variable capacity exceededmore than 512 variables
mission timer capacity exceededmore than 32 timers
directive does not belong to this slotthe directive comes from another sensor
directive progress requires an element with a counterprogress on a directive without counter = true
squad counts were minted by another squada count vector from a different squad
mission attempt is already completecomplete_mission called twice
flag value must be a boolean, an integer or nilset_flag with another type
flag writes in one callback exceed their capacitymore than 32 flags written in one callback
per-save flag write failedthe save refused the callback’s flags; the program faults
server randomness is unavailablecontext:random() found no entropy

Faults that stop a whole callback, such as instruction_budget, are in Common problems.