MISSION SCRIPTING

The shared script libraries

The scripts/lib folder holds plain Lua helpers that several missions share. They use only the public API, so you can read them as worked examples. Load one with require("lib.<name>").

modulewhat it gives you
lib.mission_libconstant guards, named variable scopes, small helpers
lib.flowa step graph: steps that wait on facts, with checkpoints
lib.campaigna full linear mission built from a content table, on top of lib.flow
lib.freeroaman open-world destination: zone population, respawns, public events, Lost Sectors
lib.combatpick the cheapest combat task group

lib.mission_lib

local lib = require("lib.mission_lib")
functionwhat it does
lib.one(value, name)returns value; errors with name when it is nil
lib.list(...)returns the arguments as a list; errors on any nil
lib.scope(context, state, tag)returns a scope object; see below
lib.timer_name(tag, elapsed)returns the timer name without tag., or nil when another tag owns it
lib.is_slot(context, event, slot)true when the event names this slot
lib.place_all(context, squads, mode)places each squad with one mode
lib.activate_scenes(context, scenes)activates each scene
lib.play_idles(context, idles)calls play_performance for each {sensor, state}

Scopes

A scope puts a prefix on every variable and timer name, so two parts of one script cannot clash.

local scope = lib.scope(context, state, "port")
scope:set_variable("seed", 42)      -- stored as "port.seed"
local seed = scope:variable("seed")
scope:start_timer("wave", 45000)    -- timer "port.wave"
scope:cancel_timer("wave")
scope:clear_variable("seed")

In on_event_timer_elapsed, map the full name back:

local name = lib.timer_name("port", event.timer_name)   -- "wave", or nil

lib.flow

A flow is a list of steps. A step starts when the steps before it are done. It runs an action once, then waits until its condition is true. All progress is stored in mission variables, so a flow survives a reload.

Build a flow

local lib = require("lib.mission_lib")
local flow = require("lib.flow")

local graph = flow.new{
    key = "intro",                         -- prefix for every stored name
    facts = {
        {id = "door_used", observe = function(context, state, event)
            return lib.is_slot(context, event, mission.Slot.O_DOOR_SWITCH)
        end},
    },
    steps = {
        {id = "arrive", await = flow.fact("door_used")},
        {id = "open", after = {"arrive"}, run = function(context, state)
            context:slot(mission.Slot.D_DOOR):transition{
                transition = context.sdk.device_transitions.open,
            }
        end},
    },
}

Step fields

fieldtypemeaning
idstringunique step name
afterlist of step idssteps that must be finished first
whenconditionextra start condition; checked only before the step starts
runfunction(context, state)runs once, when the step starts
awaitconditionthe step finishes when this is true; nil means at once
checkpointbooleana restart replays from here; see below
reset_factslist of fact idsfacts to forget when this checkpoint replays; only on a checkpoint

Conditions

A condition is one of:

  • nil: always true.
  • flow.fact(id): true once that fact was seen.
  • flow.all(a, b, ...): all are true.
  • flow.any(a, b, ...): at least one is true.
  • a function function(context, state) return <boolean> end.

Facts

A fact is a flag that latches. Its observe(context, state, event) runs for every event passed to handle. Once it returns true, the fact stays true for the attempt. An event that arrived before its step started is not lost.

Drive a flow

return {
    on_start = function(context, state) graph:advance(context, state) end,
    on_load = function(context, state) graph:advance(context, state) end,
    on_event_player_trigger = function(context, state, event)
        graph:handle(context, state, event)
    end,
}
methodwhat it does
graph:advance(context, state)starts and finishes every step it can; returns true when all are finished
graph:handle(context, state, event)records facts from the event, then advances
graph:started(context, state, id)true once the step has started
graph:fact(context, state, id)true once the fact was seen
graph:finished(context, state)true when every step is finished
graph:cancel(context, state)stops the flow for this attempt

advance walks the steps in dependency order in one pass. A step that finishes lets the next step start in the same pass. handle ignores an event from an older attempt.

Attempts and checkpoints

The flow stores which attempt owns it. On a new attempt:

if (previous_attempt_reached_a_checkpoint) {
    clear(checkpoint_step);
    clear(every_step_that_depends_on_it);
    clear(checkpoint.reset_facts);
} else {
    clear(all_steps);
    clear(all_facts);
}

So a checkpoint step and everything after it run again. Steps before it stay finished.

Limits

limitvalue
facts per flow64
steps per flow64
entries in one after, all or any list64
condition nesting depth16
stored name length63 bytes, flow.<key>.<kind>.<id>
variables usedone per fact, one per step, plus 3

Keep key and ids short. Use two flows when one would pass 64 steps; lib.campaign does this.

lib.campaign

A campaign builds a whole linear mission from one content table. The Red War missions use it.

local campaign = require("lib.campaign")
local unit, line, move = campaign.unit, campaign.line, campaign.move

return campaign.new{
    key = "deadzone",
    directive_sensor = Slot.M_DIRECTIVE_SENSOR_80B9AF4B,
    dialogue_sensor = Slot.M_DIALOG_SENSOR_80B9AF4B,
    legs = {
        {id = "town", state = mission.states.STATE_80B9AD31_0033_0000_80B9A87B,
            arm = {Slot.PT_ELEVATOR_TOWN}},
    },
    steps = {
        {id = "town", directive = Directive.RENDEZVOUS_WITH_HAWTHORNE,
            navpoint = Slot.AP_ELEVATOR_TOWN,
            ends = {trigger = Slot.PT_ELEVATOR_TOWN}},
    },
    encounters = {
        {id = "devrim", squads = {unit(Squad.SQ_DEV_LUZ, Slot.SQ_DEV_LUZ)}},
    },
}

Content table

fieldmeaning
keyflow key; keep it short
directive_sensorthe type-68 slot that shows goals
dialogue_sensorthe type-53 slot for lines; needed when any step has lines
legslist of {id, state, arm, watch}; the first leg is where the player spawns
stepsthe goals, in order
encounterssquads to place, each after a step
introoptional list of {state, cinematic} cutscenes played before the first leg
outrooptional list of {state, cinematic} cutscenes played after the last step
spawn_setoptional spawn set hash for the arrival and every host move
finishoptional function(context) run before the mission completes
completefalse to end without complete_mission; default true
omitoptional list of type-4 slots to keep out of every seed

A leg’s arm lists the type-31 triggers to arm when the player enters that leg’s region. Its watch lists the type-30 occupancy monitors to set up there. Each one reports when one player is inside.

campaign.new checks the table when the script loads. These are errors:

  • a step or encounter that ends on a trigger no leg arms, or on a monitor no leg watches
  • an encounter whose after names no step
  • a health end whose at is outside 0 to 1

campaign.new builds initial_state for you. It opens on the first intro state when there is one. Otherwise it opens on the first leg’s state. It carries spawn_set and the omit list. The omit list also gets every object a step ends on with interact.

Opening cutscenes

Each intro entry is one cutscene in its own authored state, played in list order before the first leg:

intro = {
    {state = mission.states.STATE_CINE_A, cinematic = Slot.PF_OPENING_CINEMATIC},
},

What the library does:

  1. on_start holds the player’s spawn, so no body exists while the cutscene plays.
  2. Entering a cutscene’s region starts that cutscene.
  3. When a cutscene ends, is skipped or is refused, the next one is selected. After the last one, the first leg’s state is selected and the spawn is released.
  4. A reload while a cutscene is marked playing ends it instead of replaying it.

A mission with no intro never holds the spawn.

An outro works the same way after the last step, without a spawn hold. Its first state is selected when the last step finishes. The mission completes once the last outro cutscene has ended.

Step fields

fieldmeaning
idstep name
directivea mission.Directive entry to show when the step starts
navpointoptional type-47 slot for the map marker
waypointoptional type-60 volume; the marker hides inside it
lineslist of campaign.line(cue, filter) to play at start
sceneoptional mission.Scene entry to activate at start
scene_spawntrue to also spawn the scene’s authored cast
inputsoptional lib.list of mission.SceneInput keys sent to scene right after it starts
on_startoptional function(context, state)
endshow the step ends; see below
barriertrue when a later trigger must not skip this step
revisittrue when the end trigger was already crossed earlier; arms it again at start

ends can hold any of:

keyends when
triggera trigger slot, or a list of them, reports
monitora type-30 monitor slot, or a list of them, reports a player entering
regionthe player enters that leg (a leg id)
clearthe named encounter, or list, is cleared
ghost_linka Ghost scan on that slot starts and then finishes
interactthe player uses that type-4 object
destroyedevery listed object reports gone
scenethat scene’s slot reports finished after the step started
output{slot, key}: that scene reports that mission.SceneOutput key after the step started
health{slot, at}: a damage_state for that slot reports health at or below at, 0 to 1; a report from before the step started counts
awaita lib.flow condition is true

A step with no ends finishes at once. Unless barrier is set, a step also ends when the player reaches any later step’s trigger, monitor or region.

A scene that waits on an input never finishes until the input arrives. A step that ends on such a scene needs inputs. The examples use local Input, Output = mission.SceneInput, mission.SceneOutput:

{id = "reveal", scene = Scene.SCENE_IF_REVEAL,
    inputs = lib.list(Input.SCENE_IF_REVEAL.T_START_SCENE),
    ends = {scene = Slot.SCENE_IF_REVEAL}},
{id = "hop_on", scene = Scene.SC_ZAVALA,
    inputs = lib.list(Input.SC_ZAVALA.ZAVALA_START),
    ends = {output = {slot = Slot.SC_ZAVALA, key = Output.SC_ZAVALA.T_END_SCENE_START_HOP_ON}}},

scene in ends, and slot in ends.output, take the scene’s mission.Slot key, not its mission.Scene key:

{id = "minotaur", scene = Scene.SCENE_MINOTAUR, barrier = true,
    ends = {scene = Slot.SCENE_MINOTAUR}},
{id = "boss_half", barrier = true,
    ends = {health = {slot = Slot.SQ_BOSS_BOSS, at = 0.5}}},

Encounter fields

fieldmeaning
idencounter name; ends.clear uses it
afterstep id that must start first; default "arrival"
triggeroptional trigger that must also report; it must be armed by a leg
monitoroptional type-30 monitor that must also report; it must be watched by a leg
whenoptional function(context, state); the encounter waits until it returns true
objectiveoptional type-3 objective given to every squad before placing
squadslist of campaign.unit(squad, slot, group)
linesoptional lines to play
on_startoptional function(context, state)

Helpers

functionreturns
campaign.unit(squad, source, group){squad, source, group}; source is the squad’s type-1 slot
campaign.line(cue, filter){cue, filter}; filter is an optional type-60 volume
campaign.move(context, slots, transition)nothing; runs transition on each device; transition is a name such as "open"
campaign.run_seed(context)a positive integer from the attempt number; a seed for generate_map

run_seed gives a new seed on each attempt and the same seed within one attempt. For a random number, use context:random().

lib.freeroam

A freeroam program runs an open-world destination. Each zone is one authored state. The library places the zone’s population when the player enters it, respawns patrols, rotates public events and runs Lost Sectors.

local freeroam = require("lib.freeroam")
local content = require("edz_freeroam.content")
local sectors = require("edz_freeroam.sectors")

return freeroam.new{zones = content(mission, freeroam),
    sectors = sectors(mission, freeroam)}

freeroam.new returns the whole program table. It sets no initial_state.

Definition table

fieldmeaning
zoneslist of zones; see below
sectorsoptional table from region number to Lost Sector encounter {squads, boss, chest}
tick_msservice timer period; default 5000
respawn_msdelay before a dead patrol squad returns; default 30000
event_cooldown_msdelay before the next public event starts; default 120000

Delays are counted in service ticks, so a respawn can be up to one tick late.

Zone fields

fieldmeaning
regionthe zone’s region number; two zones may not share one
statethe mission.states row selected on entry
patrollist of units placed on entry and respawned after they die
ambientlist of units placed on entry, never respawned
eventslist of public event sites; see below
sectoroptional Lost Sector; see below

An event site is {sensor, objective, squads, chest}: the type-71 public event sensor, the objective to reset, the units to place, and the chest objects shown when every squad is dead. One site runs at a time. After its cooldown, the next site in the list starts. The library does not set the sensor’s public event state yet.

A sector is {squads, boss, chest, doors, blockers, crystals}. An entry in sectors for the zone’s region sets its squads, boss and chest, and makes the zone a sector if it is not one.

sector fieldmeaning
squadsunits placed when the sector starts
bossthe boss squad’s type-1 slot; its death opens the chest
chestobjects shown when the sector is cleared; without boss, every squad must die
doorslist of {slot, channel, value}; each device snaps to that value at start
blockersobjects removed at start
crystalslist of {object, monitor, guard, boss}; see below

A crystal starts hidden, and its type-20 monitor watches it. A crystal with a guard squad slot appears when that squad dies. Once every crystal without boss is destroyed, the boss crystals appear.

Units

freeroam.unit(squad, slot, options) pairs a squad with its type-1 slot. options may hold:

optionmeaning
countslist of member counts, one per authored member
objective, groupa type-3 objective and task group assigned before placing
membera type-2 slot to bind_combatant_to_squad after placing
spawn_rulea type-66 slot used instead of the authored spawn rule

Without counts, each member’s authored count is capped at 1.

What the library does

  • A public activity runs every zone without a sector. A private activity runs only the sectors.
  • A zone builds on its first entry. On a later entry, only patrol squads still waiting to respawn are placed.
  • A sector starts as soon as the client reports its region, without selecting a state. Leaving it removes its squads, so the next visit starts it again.
  • Every callback ignores events from an older attempt.
  • One timer, tick, drives every delay. The library stores its own state in the variable held and under z<region>. names.

lib.combat

functionwhat it does
combat.same_group(a, b)true when two task groups are the same
combat.lowest_cost(event, groups, current)returns the cheapest group and known; keeps current on a tie

Use it in on_event_squad_state. See “Move a squad between task groups” in Recipes.