Step Handler

A sequential step-execution system for orchestrating multi-step gameplay sequences (fades, vehicle spawns, level loads, waits, traffic).

Overview

util_stepHandler provides a declarative pipeline where you define an array of steps, each with a processTask function. Steps execute sequentially in onUpdate, advancing when step.complete = true. Built-in step factories handle common tasks: screen fades, waits, vehicle spawning, traffic spawning, and level loading.

Extension path: lua/ge/extensions/util/stepHandler.lua

Exports (M)

Core

Function	Signature	Description
`startStepSequence`	`(steps, callback?)`	Begins executing the step array. Optional callback runs after the last step.
`skipToLastStepOrCallback`	`()`	Jumps to the final step (usually the callback).
`M.taskSpawnTrafficStep`	`(step)`	-
`M.taskLoadLevelStep`	`(step)`	-

Step Factories

Function	Signature	Description
`makeStepFadeToBlack`	`(duration?)`	Creates a fade-to-black step.
`makeStepFadeFromBlack`	`(duration?)`	Creates a fade-from-black step.
`makeStepWait`	`(seconds)`	Creates a timed wait step.
`makeStepReturnTrueFunction`	`(fn)`	Creates a step that completes when `fn(step, dtTable)` returns `true`.
`makeUiMessageStep`	`(message)`	Creates a step that shows a UI message and completes immediately.
`makeStepSpawnVehicle`	`(options, callback?)`	Spawns a vehicle; completes when it's ready. Callback receives `(step, vehId)`.
`makeStepSpawnVehicleSimple`	`(model, config, callback?)`	Simplified vehicle spawn step.
`makeStepSpawnTrafficSimple`	`(amount, active, generator?)`	Spawns traffic vehicles and activates traffic system.
`makeLoadLevelStep`	`(level)`	Loads a level; completes on `onClientStartMission`.

Event Hooks

Function	Signature	Description
`onUpdate`	`(dtReal, dtSim, dtRaw)`	Processes the current step each frame.
`onScreenFadeState`	`(state)`	Handles fade completion callbacks.
`onClientStartMission`	`(state)`	Marks level-load steps as complete.
`onVehicleGroupSpawned`	`(vehIds, groupId)`	Handles traffic group spawn completion.

Internals

Step Structure

Each step is a table with:

name - descriptive string
processTask(step, dtTable) - called each frame; set step.complete = true to advance
timeout - max seconds before auto-complete (default 120)
origin - debug traceback of creation site

Task Data

taskData holds:

steps - the step array
currentStep - 1-based index
active - boolean
data - shared data between steps

Timeout

If a step exceeds its timeout, it's force-completed with an error log.

Debug Window

Set showDebugWindow = true to show an ImGui window listing all steps and their states.

How It Works

Define steps using the factory functions.
Call startStepSequence(steps, callback).
Each frame, onUpdate calls the current step's processTask.
When step.complete = true, the next step begins.
After all steps, taskData.active becomes false.

Lua Examples

local stepper = extensions.util_stepHandler

-- Multi-step sequence: fade out → spawn vehicle → fade in
stepper.startStepSequence({
  stepper.makeStepFadeToBlack(0.5),
  stepper.makeStepSpawnVehicleSimple("pickup", "vehicles/pickup/d15_4wd_A.pc", function(step, vehId)
    print("Spawned vehicle: " .. vehId)
  end),
  stepper.makeStepFadeFromBlack(0.5),
}, function()
  print("Sequence complete!")
end)

-- Wait step
stepper.startStepSequence({
  stepper.makeStepWait(3),
  stepper.makeStepReturnTrueFunction(function()
    print("Done waiting!")
    return true
  end),
})

-- Load a level then spawn traffic
stepper.startStepSequence({
  stepper.makeLoadLevelStep("east_coast_usa"),
  stepper.makeStepSpawnTrafficSimple(10, 5),
})

Additional Exports

M.makeLoadLevelStep - (undocumented)
M.makeStepFadeFromBlack - (undocumented)
M.makeStepFadeToBlack - (undocumented)
M.makeStepReturnTrueFunction - (undocumented)
M.makeStepSpawnTrafficSimple - (undocumented)
M.makeStepSpawnVehicle - (undocumented)
M.makeStepSpawnVehicleSimple - (undocumented)
M.makeStepWait - (undocumented)
M.makeUiMessageStep - (undocumented)
M.onClientStartMission - (undocumented)
M.onScreenFadeState - (undocumented)
M.onUpdate - (undocumented)
M.onVehicleGroupSpawned - (undocumented)
M.skipToLastStepOrCallback - (undocumented)
M.startStepSequence - (undocumented)

A sequential step-execution system for orchestrating multi-step gameplay sequences (fades, vehicle spawns, level loads, waits, traffic).

Function	Signature	Description
`startStepSequence`	`(steps, callback?)`	Begins executing the step array. Optional callback runs after the last step.
`skipToLastStepOrCallback`	`()`	Jumps to the final step (usually the callback).
`M.taskSpawnTrafficStep`	`(step)`	-
`M.taskLoadLevelStep`	`(step)`	-

Step Factories

Function	Signature	Description
`makeStepFadeToBlack`	`(duration?)`	Creates a fade-to-black step.
`makeStepFadeFromBlack`	`(duration?)`	Creates a fade-from-black step.
`makeStepWait`	`(seconds)`	Creates a timed wait step.
`makeStepReturnTrueFunction`	`(fn)`	Creates a step that completes when `fn(step, dtTable)` returns `true`.
`makeUiMessageStep`	`(message)`	Creates a step that shows a UI message and completes immediately.
`makeStepSpawnVehicle`	`(options, callback?)`	Spawns a vehicle; completes when it's ready. Callback receives `(step, vehId)`.
`makeStepSpawnVehicleSimple`	`(model, config, callback?)`	Simplified vehicle spawn step.
`makeStepSpawnTrafficSimple`	`(amount, active, generator?)`	Spawns traffic vehicles and activates traffic system.
`makeLoadLevelStep`	`(level)`	Loads a level; completes on `onClientStartMission`.

Event Hooks

Function	Signature	Description
`onUpdate`	`(dtReal, dtSim, dtRaw)`	Processes the current step each frame.
`onScreenFadeState`	`(state)`	Handles fade completion callbacks.
`onClientStartMission`	`(state)`	Marks level-load steps as complete.
`onVehicleGroupSpawned`	`(vehIds, groupId)`	Handles traffic group spawn completion.

Internals

Step Structure

Each step is a table with:

name - descriptive string
processTask(step, dtTable) - called each frame; set step.complete = true to advance
timeout - max seconds before auto-complete (default 120)
origin - debug traceback of creation site

Task Data

taskData holds:

steps - the step array
currentStep - 1-based index
active - boolean
data - shared data between steps

Define steps using the factory functions.
Call startStepSequence(steps, callback).
Each frame, onUpdate calls the current step's processTask.
When step.complete = true, the next step begins.
After all steps, taskData.active becomes false.

Lua Examples

local stepper = extensions.util_stepHandler

-- Multi-step sequence: fade out → spawn vehicle → fade in
stepper.startStepSequence({
  stepper.makeStepFadeToBlack(0.5),
  stepper.makeStepSpawnVehicleSimple("pickup", "vehicles/pickup/d15_4wd_A.pc", function(step, vehId)
    print("Spawned vehicle: " .. vehId)
  end),
  stepper.makeStepFadeFromBlack(0.5),
}, function()
  print("Sequence complete!")
end)

-- Wait step
stepper.startStepSequence({
  stepper.makeStepWait(3),
  stepper.makeStepReturnTrueFunction(function()
    print("Done waiting!")
    return true
  end),
})

-- Load a level then spawn traffic
stepper.startStepSequence({
  stepper.makeLoadLevelStep("east_coast_usa"),
  stepper.makeStepSpawnTrafficSimple(10, 5),
})

Additional Exports

M.makeLoadLevelStep - (undocumented)
M.makeStepFadeFromBlack - (undocumented)
M.makeStepFadeToBlack - (undocumented)
M.makeStepReturnTrueFunction - (undocumented)
M.makeStepSpawnTrafficSimple - (undocumented)
M.makeStepSpawnVehicle - (undocumented)
M.makeStepSpawnVehicleSimple - (undocumented)
M.makeStepWait - (undocumented)
M.makeUiMessageStep - (undocumented)
M.onClientStartMission - (undocumented)
M.onScreenFadeState - (undocumented)
M.onUpdate - (undocumented)
M.onVehicleGroupSpawned - (undocumented)
M.skipToLastStepOrCallback - (undocumented)
M.startStepSequence - (undocumented)

Step Handler

Overview

Exports (M)

Core

Step Factories

Event Hooks

Internals

Step Structure

Task Data

Timeout

Debug Window

How It Works

Lua Examples

Additional Exports

On this page

Step Handler

Overview

Exports (M)

Core

Step Factories

Event Hooks

Internals

Step Structure

Task Data

Timeout

Debug Window

How It Works

Lua Examples

Additional Exports

On this page