Unlocks

Reference for gameplay_missions_unlocks, which evaluates start/visible conditions, manages unlock dependencies between missions, and computes mission ordering depth.

Module Exports (M)

Unlock Evaluation

Unlock Comparison

Dependency Analysis

Sorting

Condition System

Conditions are loaded from /gameplay/missions/unlocks/conditions/*.lua files on extension load. Each condition type provides:

{
  info = "Description",
  editorFunction = "editorFnName",  -- optional
  getLabel = function(condition) → string/table end,
  conditionMet = function(condition) → bool, nested? end,
  hidden = bool  -- optional, hides condition from UI
}

Unlock Evaluation Flow

local function updateUnlockStatus(missions)
  -- Pass 1: Evaluate startCondition for each mission
  for _, mission in ipairs(missions) do
    mission.unlocks.startable = conditionMet(mission.startCondition).met
    -- Career+freeroam missions: always startable outside career
  end

  -- Pass 2: Evaluate visibleCondition
  for _, mission in ipairs(missions) do
    if visibleCondition.type == 'automatic' then
      -- Visible if any backward-linked mission is startable
      -- (or if no backward links exist)
    else
      mission.unlocks.visible = conditionMet(mission.visibleCondition).met
    end
  end
end

Dependency & Depth Ordering

setUnlockForwardBackward(missions):

1. Extract dependencies - Parse startCondition for mission references (missionPassed/missionCompleted)
2. Double-link - Build forward links (which missions does this unlock?)
3. Extract branch levels - Parse conditions for branchLevel and league requirements
4. Propagate branch data - Forward-propagate max branch level and branch tags
5. Compute depth - BFS from root missions (no backward links), depth = distance from root
6. Shift by branch level - Offset depth by accumulated branch level thresholds

This produces mission.unlocks.depth used for UI ordering.

Unlock Diff Structure

{
  list = { {missionId, change = {{key, old, new}, ...}}, ... },
  byId = { [missionId] = change },
  missionsList = { {name, id}, ... }  -- newly startable missions
}

Key Behaviors

• Career missions with showInCareer and showInFreeroam both true are always startable/visible outside career
• 'automatic' visible condition: visible if any predecessor is startable (or no predecessors)
• Condition types loaded dynamically from condition files (see careerConditions, genericConditions, missionConditions, vehicleConditions)
• Depth ordering ensures missions with higher branch level requirements appear later in UI

See Also

• missions/locationsDetector - Nearby Mission Location Detection - Related reference
• missions/missionManager - Mission Lifecycle Manager - Related reference
• missions/missionScreen - Mission UI Screen & Starting Options - Related reference
• Gameplay Systems Guide - Guide