Lua API reference

This is the full list of what a mission script can call and read. It matches the runtime in server/activity/mission/mission_script_lua_*.cpp. The live SDK views (context.sdk.catalog, world, manifest) 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”.

Context

The first argument of every callback.

Fields

Lookups

An unknown selector is an error: “unknown or ambiguous activity slot”. Pass the id string, not a handle.

Mission state

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

World requests

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.

select_state options is either a plain list of type-4 slots to keep out of the seed, or a table with:

restart_checkpoint arguments:

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.

State

The second argument of every callback. Read-only.

Request keys

Every request returns a RequestKey.

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

Methods by slot type

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

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

set_object_filter

set_directive

set_public_event_state

assign_combat_objective

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

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

Squad

Fields and methods

place

A count vector from another squad is an error.

Count vector

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

Scene

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

Cohort

A cohort is a read-only view of up to 64 squads.

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

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:

complete_mission sets state 6 for you. Prefer it.

Peers

context.peers lists the other sessions in this activity.

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

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

The six transitions:

Actor sequences

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

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 1 to 32 atoms. Each atom is a table with a kind. context.sdk.atom_kinds holds the kind names.

• target is a slot handle. value on face, snap_to and move_to is an authored point number of that target, 0 to 255. An unknown point is an error.
• An ability must belong to this actor. Its optional target must have an authored point 0.
• 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.

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:

Most events also have mission_sequence (string), the input order. Delivery events do not.

Slot identity

Events about one slot also have:

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. The first column is the callback name without its on_event_ prefix.

client_state_changed in detail

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

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

squad_state methods

device_state:applied_request

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

effect_result

effect names: squad.place, scene.activate, scene.stop, scene.send_event, slot.set_object_active, slot.set_channel, slot.run_atoms, slot.retire_actor, slot.set_interactable_object, slot.set_ghost_link, slot.watch_damage, slot.assign_combat_objective, lifetime.set, mission.restart_checkpoint, slot.fire_trigger, slot.play_sequence, slot.set_cinematic_active, slot.play_performance, slot.reset_objectives, slot.advance_task, slot.play_dialogue_cue, mission.select_state, mission.hold_spawn.

client_message_received

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

Errors you will see