MISSION SCRIPTING

The generated SDK modules

Sunrise reads the installed game data and writes plain Lua modules from it. Your script loads them with require. They hold every identity a script needs, so a script never types a raw id.

Sunrise writes these files. Never edit them. A change is lost on the next generation.

Where they are

<game>/bin/x64/Sunrise/
    scripts/                  your scripts, loaded as require("<folder>.<file>")
    sdk/
        catalog.bin           the native catalog; not Lua
        scenarios/            native world shards; not Lua
        lua/
            manifest.json     build identity and row counts
            missions.lua      name -> mission module
            activities.lua    name -> activity module
            missions/         one module per scenario
            activities/       one module per activity
            sunrise/
                activity_sdk.lua   shared enums and editor type hints
                incidents.lua      every incident notification, by name
                mission_api.json   every call, field and event the runtime serves
                behaviors.lua      compiled behavior tables

require searches sdk/lua first, then the sdk and scripts folders of loaded mods, then scripts. A script or a mod can never hide a generated module by using the same name. The mod order is on the Mods page.

missions.lua

A table from a readable name to a module name.

local missions = require("missions")
local mission = require(missions.MISSION_DEADZONE)   -- "missions.mission_deadzone_80b9ad31"
  • The key is the scenario name in upper case.
  • The value ends in the scenario tag, so it changes if the data changes. Always go through this table. Never type the long module name.

activities.lua and activities/*.lua

The same idea for activities.

local activities = require("activities")
local activity = require(activities.ADVENTURE_GINGER)

One activity module is a small table:

fieldtypemeaning
namestringinternal name; your script folder is named after it
display_namestringname shown to the player
idstringstable id, act/<index as 4 hex digits>/<hash as 8 hex digits>
indexintegeractivity row
definition_hashintegeractivity hash
activity_root_tagintegerpackage tag of the activity root
scenario_tagintegerscenario the activity runs
matchmaking_config_taginteger0xFFFFFFFF when absent
missiontablethe mission module, already loaded

A mission module

This is the module you use most. Load it once at the top of your script.

local missions = require("missions")
local mission = require(missions.MISSION_DEADZONE)
local Slot, Squad, Directive = mission.Slot, mission.Squad, mission.Directive

The module has three plain fields: name (the scenario name), id and tag (the scenario tag). The rest are tables of two kinds. Row tables hold full records. Constant tables hold one identity per name. You pass constants to the API.

Row tables

tableone row
mission.states{id, ordinal, slice_set_index, region_index, hash, value}
mission.slots{id, name, index, type, component_class, sense_schema, auth_schema, unresourced, auth_type, auth_min_bits, auth_max_bits, auth_dynamic, auth_writable, auth_component_offset}
mission.squads{id, slot, spawner_config, spawn_rule_config, members, anchors}
mission.scenes{id, slot, config_tag, resource_tag, event_keys}
mission.tasks{id, task_slot, objective_slot, objective_bit, config_tag}
mission.trigger_volumesa list of {names, registry_key, slot_type, slot_index, position, minimum, maximum, shape_tag, shape_index, active}

Notes:

  • states, slots, squads, scenes and tasks are keyed by the same keys as the constant tables: mission.states.STATE_..., mission.slots.PT_.... trigger_volumes is a plain list.
  • states rows are what initial_state and select_state take. Pass the whole row.
  • A squad members entry is {actor_class, behavior_config, default_faction}. All three are nil when the actor class is not known exactly.
  • A squad anchors entry is {x, y, z, point}, the authored spawn points.
  • slot in a squad or scene row is a catalog row number, not a slot index.
  • unresourced = true marks a type-43 scene slot that was authored with no scene resource. The field is absent on every other slot.
  • event_keys lists the event keys of the scene’s authored event graph, in graph order. It is absent when the graph could not be read.
  • minimum and maximum of a trigger volume are the corners of its box, as the package stores them. The in-game Triggers page shows the same numbers as “world bounds”. Use them to get a rough idea of where a trigger is, then confirm it in game.

Constant tables

tablekeyvaluepass it to
mission.Slotslot keyslot id stringcontext:slot(...)
mission.Squadsquad keysquad id stringcontext:squad(...), context:cohort{...}
mission.Scenescene keyscene id stringcontext:scene(...)
mission.SceneInputscene key, then trigger name or KEY_<hash>event keykey = in send_event
mission.SceneOutputscene key, then trigger name or KEY_<hash>event keycompare with event.key in on_event_scene_output
mission.Tasktask keytask id stringreference only
mission.Statestate keythe state’s public valuereference only
mission.Authauth type, then slot keyslot id stringcontext:slot(...)
mission.TaskGroupobjective slot key, then GROUP_<n>{slot_row, group_index, tasks}task_group =
mission.ActorAbilityactor slot key, GROUP_<hash>, KEY_<hash>{slot_row, group_hash, request_hash}ability =
mission.ActorTemperamentactor or squad slot key, then KEY_<hash>{slot_row, id}temperaments =
mission.ActorChannelactor slot key, then KEY_<hash>{slot_row, channel}channel = in a channels entry
mission.DialogueCuedialogue slot key, then CUE_<n>cue numbercue =
mission.DialogueCueVariantsdialogue slot key, then cue numberlist of line textssearch only
mission.DialogueDefinitiondialogue slot key, then cue number{hash, window_ms, lines}reference only
mission.Directivedirective key{id, slot_row, sensor, name_hash, element, title, description, progress, counter}; sensor is the sensor’s mission.Slot valuedirective =
mission.PerformanceStateperformance slot key, then STATE_<hash>{slot_row, name_hash, ordinal}state = in play_performance
mission.TriggerVolumevolume name in upper casea row of trigger_volumesreference only
mission.ActorCommandcommand nameselector numbercommand = in actor_command
mission.ActorCommandDefinitioncommand name{selector, payload}reference only
mission.ActorMessagemessage namemessage schema rowreference only
mission.FactionNONE, REMOVED, HOSTILE_TO_ALLfaction numbervalue = in actor_command
mission.SimulationEventevent nameevent type numberreference only
mission.SimulationEventDefinitionevent name{event_type, primary_schema, secondary_schema}reference only
mission.RuntimeFieldTypecodec family, then type nametype codereference only

A scene’s event keys are the hashed names of its authored triggers. A scene waits on some of them and reports others:

tableholdsa script
mission.SceneInputtriggers the scene waits on and never fires itselfsends them
mission.SceneOutputtriggers the scene fires and never waits onwaits for them

A key whose trigger name is known takes that name in upper case: mission.SceneInput.SC_ZAVALA.ZAVALA_START. Any other key is KEY_<hash>. A scene with no inputs, or no outputs, has no entry in that table. Triggers the scene both fires and waits on are internal and appear in neither. The start trigger is fired by the client, so it is not an input.

local Input = mission.SceneInput
context:scene(mission.Scene.SC_ZAVALA):send_event{key = Input.SC_ZAVALA.ZAVALA_START}

A reported output raises on_event_scene_output. See Lua API reference.

A mission.Directive entry has progress, the progress label text, only when one is authored. It has counter = true only when the HUD shows counter values for it. Only such an entry accepts progress in set_directive.

A mission.TaskGroup entry’s tasks lists each task’s bounds, in the order the objective reports their counters: {minimum_members, maximum_members, maximum_squads, counter_limit}.

A mission.DialogueDefinition entry has the dialogue hash, window_ms, the authored window that bounds a delayed cue, and lines, the line count. window_ms is not a playback length.

Temperaments and channels are named only by hash in the game data, so their keys are always KEY_<hash>. See “Temperaments and channels” in the Lua API reference.

How keys are made

  • A key is the authored name in upper case. Each run of other characters becomes one _. A key that would start with a digit gets a leading _.
  • A slot with no authored name is named after its slot index in hex: SLOT_01DD. Some take their auth type name in place of SLOT.
  • A slot name used by more than one slot gets the object tag on every copy: O_CIV_0_80B4A6CB.
  • A slot key still not unique also gets the slot index as 4 hex digits: FA_ENGAGED_80BE1BA8_0011.
  • A squad and its slot share one key. mission.Squad.SQ_X pairs with mission.Slot.SQ_X.
  • A scene and its slot share one key too.
  • A directive key comes from its title. A directive with a progress label and no description takes its key from the label instead. A repeated key gets the name hash: RENDEZVOUS_WITH_HAWTHORNE_1DD5B5F6.
  • A state key is its id in upper case: STATE_<scenario>_<bubble>_<ordinal>_<entry>.
  • A repeated mission.TriggerVolume name gets _1, _2 and so on.

Every copy of a repeated slot name gets a suffix, so a slot key never depends on row order. In the other tables the first row keeps the plain key and later rows get the suffix. Keys are the same each time Sunrise generates from the same install.

Guard against a missing key

Lua returns nil for a key that does not exist. A nil in a list ends ipairs early, and the mistake stays hidden. Check every key when the module loads.

local function one(value, name)
    assert(value ~= nil, "missing mission constant: " .. name)
    return value
end

local DOOR = one(mission.Slot.D_FRONT_DOOR, "front door")

lib/mission_lib.lua has this helper as lib.one, and lib.list for lists. See The shared script libraries.

sunrise/activity_sdk.lua

Shared tables every mission module loads. Load it yourself with require("sunrise.activity_sdk").

tablemeaning
EventKindthe event kind numbers; event.kind holds one
SlotTypea few named slot types: SQUAD = 1, SEQUENCE = 5, CINEMATIC = 6, DEVICE = 23, TRIGGER = 31, TASK = 38, SCENE = 43, TRIGGER_VOLUME = 60
AuthTypeper auth type name: {name, slot_type, schema, struct_bytes, min_bits, max_bits, component_offset, dynamic, writable}
CombatantLanePrimarySchemaatom lane schema ids
CombatantLaneSecondarySchemaatom secondary lane schema ids
AuthoredBehaviorFilterClassbehavior condition class ids
ObjectFilterPredicateSchemaobject filter predicate schema ids
ActorSequenceCatalogthe extracted actor sequence tables

The file also holds ---@class comments for the LuaLS editor plugin. They are written from the same table the runtime reads, so a hint and the runtime cannot disagree.

classwhat it describes
SunriseContextthe first callback argument
SunriseStateViewthe second callback argument
SunriseSlotHandle, SunriseSquadHandle, SunriseSceneHandlethe handles context:slot, context:squad and context:scene return
Sunrise<Name>Eventone class per event view; SunriseEvent holds the fields every event has
SunriseProgramthe table a mission script returns
SunriseAtomone atom of run_atoms

A slot method’s hint ends with the slot type it accepts, for example Slot type 23 (exact).. SunriseSlot, SunriseSquad, SunriseScene and SunriseState are the generated rows of a mission module, not handles.

sunrise/incidents.lua

The activity incident notifications, by name. Load it with require("sunrise.incidents").

tablekeyvalue
Notificationthe English text in upper casethe incident target
Textthe incident targetthe English text

A repeated text gets _2, _3 and so on, in target order. Pass a Notification value as target in context:send_incident.

sunrise/mission_api.json

A machine-readable list of the whole mission Lua API. The runtime dispatches from the same table, so a member that is not in this file does not exist. Tools such as an editor plugin can read it.

The top level holds these keys:

keyholds
schemasunrise-mission-lua-api-v1
value_kindsevery word a kind can take
receiversone entry per handle type
membersone entry per field or method, receiver by receiver
eventsone entry per event kind, in EventKind order
programthe keys of the table a mission script returns
enumsthe closed collections under context.sdk

Lists keep the runtime’s order. Keys inside an object are sorted.

Receivers

keymeaning
namethe receiver name other entries refer to, for example slot
lua_classits class in activity_sdk.lua
sourcehow a script gets one
completefalse when the receiver also serves members this file does not list
member_counthow many entries of members belong to it
entriesthe collection whose entry names it also serves, when it has one
dynamic_keysother keys it serves, in words

sdk and activity_message are not complete. Their row collections and live views are on The live SDK views.

Members

keymeaning
receiverthe receiver it belongs to
namethe key a script reads
kindfield, request, query, lookup, update or maker
typea field’s value
callnamed (one table of arguments) or positional
colontrue for handle:name(...), false for handle.name(...)
argumentsthe arguments, in order
returnsthe return values, in order; empty when it returns nothing
refuses_unknown_keystrue on every named call: an undeclared key is an error
gateon a slot method, the slot it accepts
effectthe name an effect_result event reports for this request
noteone line of extra meaning

A request queues an effect and returns a RequestKey. A query reads without changing anything. A lookup returns a handle. An update changes callback state and commits with the callback. A maker builds a new value.

gate has slot_type and checks. checks names what must also match the slot type: component_class, sense_schema, auth_schema, exact_join and dialogue_cues. A gate with exact_join is an exact check.

play_sequence appears twice on slot, once per slot type. The runtime picks the type-2 form on an exact combatant and the type-5 form otherwise.

Values

Arguments, field types, return values, list elements and table fields share one shape.

keymeaning
kinda word from value_kinds
namethe key or the parameter name; absent on a return value
optionalan argument may be left out; a field or return value may be nil
refwhat the kind refers to; see below
defaultthe value an omitted argument takes
default_textthe same, in words, when it is not a plain value
minimum, maximumthe allowed value range
min_count, max_countthe allowed length of a list, or of a table’s array part
min_length, max_lengththe allowed byte length of a string
slot_gatethe slot a slot handle argument must be
scopewhat the value must belong to
handle_accepteda selector also takes a handle
elementthe value of each list entry, or of a table’s array part
fieldsthe named fields of a table or a mission row
noteone line of extra meaning

The value kinds:

kinda script passes or readsref
boolean, integer, number, stringthe Lua valueinteger may name a generated table, such as mission.SceneInput
decimal_stringa 64-bit value as decimal digits
namea timer or variable name
scalara variable value: boolean, integer, finite number or short string
selectoran id string or a row numberthe generated table, such as mission.Slot
handlea handlethe receiver name, such as slot or request_key
enuman entry of a context.sdk collectionthe collection, such as device_channels
mission_rowa row of a generated mission tablethe table, such as mission.Directive
lista dense list
tablea table with named fields
atomone atom table of run_atomsatom_kinds
functiona function

scope is one of:

scopethe value must
receiverbelong to the receiver: this slot, actor, squad or scene
same_registryshare the receiver slot’s registry
same_objectshare the receiver slot’s object and registry
argumentbelong to the slot passed in another argument

A note says when the runtime does not check a scope.

Events

keymeaning
kindthe EventKind number
namethe EventKind name, such as SQUAD_STATE
callbackthe program key, such as on_event_squad_state
lua_classits class in activity_sdk.lua
groupsthe field groups the view serves
fieldsevery field and method of the view, each a member with group in place of receiver
noteone line of extra meaning, when there is one

A field that is optional reads nil when the report did not carry it.

Program and enums

program.entries lists initial_state, seed_omit, on_start and on_load as values. program.refused lists keys the runtime refuses, such as on_event. start_parameters names the arguments of on_start and on_load. event_parameters names those of an event callback.

Each entry of enums has name, lua_class, entries and note. An entry of entries has name and a value. Most name the value value; bounded_lanes names it capacity. device_transitions adds channel and bounded_lanes adds kind. Each atom_kinds entry adds the atom’s fields, a note, and closed, which is true when a field outside that list is refused. lifetime_states has no named entries; it has minimum, maximum and default instead.

sunrise/behaviors.lua

Compiled behavior tables: Program, Channel, Input, ChannelWrite, Owner, ActivityBinding, and the small enums InputSelector, InputRole and SubmissionKind.

  • It is about 25 MB of source. A script has a 64 MiB memory limit. Do not require it from a mission script unless you need it.
  • No mission script uses it.

manifest.json

The build identity of the generated set.

keymeaning
sdk_build_idsha256:<64 hex>; the same value as context.sdk_build_id
sdk_payload_sha256, logical_ir_sha256, content_keydigests of the data the set was built from
format_versiongenerator format number
schemaschema name, sunrise-activity-sdk-v11
countsrow counts per table, useful to see how much data exists

Sunrise checks manifest.json and sunrise/mission_api.json against the catalog. If either does not match, it generates the set again.

The editor setup

An editor with the Lua language server (LuaLS) can use the generated hints. Open the scripts folder and add the SDK folder as a library, for example in .luarc.json:

{
    "runtime.version": "Lua 5.4",
    "workspace.library": ["<game>/bin/x64/Sunrise/sdk/lua"]
}

Replace <game> with the full path of your game install. The mission modules are large, so the editor may be slow to index them the first time.