Scenarios Loader

Dependencies

M.dependencies = {'core_levels'}

Discovers, processes, and launches scenarios. Scans level directories for scenario JSON files, resolves prefabs/previews/extensions, applies defaults, and handles both legacy scenarios and flowgraph-based scenarios.

Internal State

Public API (Exports)

Scenario Modules (Auto-Loaded)

M.scenarioModules = {
  'scenario_scenarios', 'scenario_waypoints',
  'statistics_statistics', 'scenario_raceUI', 'scenario_raceGoals'
}

How It Works

Discovery (getList)

1. Scans all level paths under <level>/scenarios/ for .json files
2. Also scans flowgraphEditor/scenarios/ for flowgraph scenarios
3. Scans .flow.json files with isScenario = true flag
4. Optionally includes gameplay missions with isAvailableAsScenario
5. Filters restrictToCampaign in shipping builds

Processing (processScenarioData)

1. Paths: Resolves sourceFile, directory, levelName, mission, scenarioName
2. Vehicles: Defaults to {scenario_player0 = {playerUsable=true, startFocus=true}, ['*'] = {}}
3. Prefabs: Auto-discovers matching .prefab and .prefab.json files via cached directory scan
4. Previews: Auto-discovers matching .jpg files in scenario directory
5. Extensions: Auto-adds {name=scenarioName, optional=true} for co-located extension files
6. LapConfig: Processes BranchLapConfig into flat lapConfig (strings only)
7. Attempts: Initializes retry system fields if attemptsInfo is present
8. Input Filters: Sets up black/white list action filters
9. Mod Info: Detects mod source via core_modmanager.getModFromPath

Launch (start)

1. Stops any active campaign
2. If level is already loaded, defers start until unloaded
3. For flowgraph scenarios: loads flowgraph manager and sets variables
4. For legacy scenarios: loads scenario modules and calls executeScenario

Prefab Cache

M.prefabCache = {}  -- levelPath → {directory → {prefabName → prefabPath}}

Built once per level, caches all .prefab and .prefab.json files for fast lookup during scenario processing.

Usage Example

-- Get all available scenarios
local scenarios = scenario_scenariosLoader.getList()

-- Start a specific scenario
scenario_scenariosLoader.startByPath("/levels/gridmap/scenarios/drag_race.json")

-- Load and inspect scenario data
local sc = scenario_scenariosLoader.loadScenario("/levels/west_coast_usa/scenarios/hill_climb.json")
print(sc.name, sc.levelName, #sc.prefabs)

Key Notes

• Supports three scenario types: JSON, flowgraph (.flow.json), and mission-as-scenario
• processScenarioData is idempotent - applies all defaults regardless of input completeness
• The restrictScenarios setting controls whether input filters are enforced
• onFileChanged enables live reload during development
• Bus route scenarios use a specialized getLevels path with .buslines.json files
• Date field is forced to string to prevent JSON encoding data loss

Additional Exports

• M.triggerDelayedStart - (undocumented)

See Also

• Scenario Bus Driver - Bus Route Scenario Logic - Related reference
• Scenario Damage Goal - Damage-Based Win/Fail Condition - Related reference
• Scenario Demolition Derby - Last Vehicle Moving Wins - Related reference
• Scenario System Guide - Guide