Mission Manager

Reference for gameplay_missions_missionManager, the central orchestrator for starting and stopping missions with multi-step task pipelines.

Module Exports (M)

Hooks / Lifecycle

Task Pipeline Architecture

The manager uses a step-based task pipeline (taskData) that processes sequentially each frame:

Start Pipeline (startWithFade)

1. taskStartFadeStep - Fade screen to black (timeout: 10s)
2. taskStartRemoveVehicles - Delete all vehicles (if removeAllVehiclesBeforeMission)
3. taskStartPreMissionHandling - Process user settings, save starting info, freeze traffic, prepare vehicle stash, load custom script
4. taskStartVehicleStep - Spawn or select player vehicle, set differentials
5. taskStartStartingOptionRepairStep - Handle repair costs in career mode
6. taskStartTakePartConditionSnapshot - Snapshot vehicle part conditions
7. taskStartTrafficStep - Spawn or activate traffic/parking
8. taskStartMissionStep - Call mission:onStart(), set environment, stash vehicles

Stop Pipeline

1. taskStopMissionStep - Call mission:onStop(), restore environment/traffic/vehicles/camera
2. taskStartRemoveVehicles - Delete vehicles if needed
3. taskStopRespawnVehicleStep - Respawn default vehicle
4. taskStopRespawnTrafficStep - Restore traffic
5. taskStopFadeStep - Fade back in, reset game state to freeroam

Internals

Vehicle Stashing

Before a mission, all existing vehicles are "stashed" (deactivated). After the mission, they are "unstashed" (reactivated and unfrozen).

Traffic Management

• Freezes current traffic state before mission
• Spawns new traffic per mission's setupModules.traffic configuration
• Restores previous traffic state on stop

Environment Setup

• Saves and restores time-of-day, fog density
• Applies mission-specific time, time scale, fog, and wind settings

Foreground Exclusivity

Only one non-background mission runs at a time, tracked by foregroundMissionId.

How It Works

-- Each frame, onUpdate processes the active task pipeline:
local function onUpdate(dtReal, dtSim, dtRaw)
  if taskData.active then
    local step = taskData.steps[taskData.currentStep]
    while step do
      step.processTask(step, taskData)
      -- Timeout enforcement (default 120s)
      if step.complete then
        taskData.currentStep = taskData.currentStep + 1
        step = taskData.steps[taskData.currentStep]
      else
        step = nil -- wait for next frame
      end
    end
  end
  -- Run ongoing mission updates
  if foregroundMissionId then
    for _, mission in ipairs(gameplay_missions_missions.get()) do
      if mission._isOngoing then
        mission:onUpdate(dtReal, dtSim, dtRaw)
      end
    end
  end
end

Hooks Fired

See Also

• missions/locationsDetector - Nearby Mission Location Detection - Related reference
• missions/missionScreen - Mission UI Screen & Starting Options - Related reference
• missions/missions - Mission Registry & Data Management - Related reference
• Gameplay Systems Guide - Guide