Load Level (Flowgraph Node)

Overview

Node Name: Load Level
Category: (custom state machine)
File: extensions/flowgraph/nodes/util/loadLevel.lua

Loads a level by path. The path is relative to levels/ and automatically appends /info.json. Supports optional vehicle model/config spawning and custom loading screens.

Pin Schema

Input Pins

Pin	Type	Description
`flow`	flow	Inflow trigger
`levelPath`	string	Path relative to `levels/` (e.g., `gridmap_v2`)
`model`	string (hidden)	Spawn with a specific vehicle model
`config`	string (hidden)	Spawn with a specific vehicle config

Output Pins

Pin	Type	Description
`flow`	flow	Fires when level loading is complete

Internals

Key Methods

Method	Description
`init()`	Sets defaults: prevent player spawning, force level load, no custom loading screen
`_executionStarted()`	Resets state machine to state 1
`postInit()`	Populates level path dropdown with `getAllLevelIdentifiers()`
`onLoadingScreenFadeout(missionFile)`	Callback when loading screen fades; transitions to state 3
`work()`	Runs the state machine each frame
`drawMiddle(builder, style)`	Shows current state number

State Machine

State	Description
1	Check - if level already loaded (and not forcing), skip to state 4. Otherwise start loading (state 2).
2	Loading - `core_levels.startLevel()` has been called; waiting for completion callback.
3	Buffer - loading done, counts down `delayBufferFrames`, then fires hooks and transitions to 4.
4	Complete - sets `flow` output to true.

Node Data Properties

Property	Default	Description
`preventPlayerSpawning`	`true`	Prevents automatic player vehicle spawn
`forceLevelLoad`	`true`	Forces reload even if the level is already loaded
`delayBufferFrames`	`0`	Extra frames to wait after loading before completing
`stopRunningOnClientEndMission`	`false`	Whether to stop the flowgraph when the mission ends
`noLoadInEdit`	`true`	Skip loading when in editor mode
`customLoadingScreen`	`false`	If true, uses a delayed callback so you can manually hide the loading screen

How It Works

State 1: Checks if the requested level is already the active mission. If so (and not forcing), jumps to complete. Otherwise calls core_levels.startLevel().
When customLoadingScreen is enabled, a callback is passed to startLevel() that transitions to state 3 instead of auto-fading.
State 3: Waits for delayBufferFrames countdown, then fires onClientPostStartMission and onClientStartMission hooks, calls map.assureLoad(), and moves to state 4.
Optionally spawns a vehicle with the specified model/config via sanitizeVehicleSpawnOptions().

Usage Example

-- Simple level load:
-- [Button] → flow → [Load Level] levelPath="west_coast_usa"
--                     → flow → [Spawn Vehicle]

-- Custom loading screen workflow:
-- [Load Level] levelPath="italy" customLoadingScreen=true
--   → (waits for manual hide)
-- [Do Setup] → [Hide Loading Screen] → finished → [Continue]

Key Dependencies

core_levels.startLevel() - engine function to load a level
getMissionFilename() - returns the current level's mission file
getAllLevelIdentifiers() - lists available levels
spawn.preventPlayerSpawning - controls automatic vehicle spawning
map.assureLoad() - ensures map data is refreshed after level switch

Overview

Node Name: Load Level
Category: (custom state machine)
File: extensions/flowgraph/nodes/util/loadLevel.lua

Loads a level by path. The path is relative to levels/ and automatically appends /info.json. Supports optional vehicle model/config spawning and custom loading screens.

Pin Schema

Input Pins

Pin	Type	Description
`flow`	flow	Inflow trigger
`levelPath`	string	Path relative to `levels/` (e.g., `gridmap_v2`)
`model`	string (hidden)	Spawn with a specific vehicle model
`config`	string (hidden)	Spawn with a specific vehicle config

Output Pins

Pin	Type	Description
`flow`	flow	Fires when level loading is complete

Internals

Key Methods

Method	Description
`init()`	Sets defaults: prevent player spawning, force level load, no custom loading screen
`_executionStarted()`	Resets state machine to state 1
`postInit()`	Populates level path dropdown with `getAllLevelIdentifiers()`
`onLoadingScreenFadeout(missionFile)`	Callback when loading screen fades; transitions to state 3
`work()`	Runs the state machine each frame
`drawMiddle(builder, style)`	Shows current state number

State Machine

State	Description
1	Check - if level already loaded (and not forcing), skip to state 4. Otherwise start loading (state 2).
2	Loading - `core_levels.startLevel()` has been called; waiting for completion callback.
3	Buffer - loading done, counts down `delayBufferFrames`, then fires hooks and transitions to 4.
4	Complete - sets `flow` output to true.

Node Data Properties

Property	Default	Description
`preventPlayerSpawning`	`true`	Prevents automatic player vehicle spawn
`forceLevelLoad`	`true`	Forces reload even if the level is already loaded
`delayBufferFrames`	`0`	Extra frames to wait after loading before completing
`stopRunningOnClientEndMission`	`false`	Whether to stop the flowgraph when the mission ends
`noLoadInEdit`	`true`	Skip loading when in editor mode
`customLoadingScreen`	`false`	If true, uses a delayed callback so you can manually hide the loading screen

How It Works

State 1: Checks if the requested level is already the active mission. If so (and not forcing), jumps to complete. Otherwise calls core_levels.startLevel().
When customLoadingScreen is enabled, a callback is passed to startLevel() that transitions to state 3 instead of auto-fading.
State 3: Waits for delayBufferFrames countdown, then fires onClientPostStartMission and onClientStartMission hooks, calls map.assureLoad(), and moves to state 4.
Optionally spawns a vehicle with the specified model/config via sanitizeVehicleSpawnOptions().

Usage Example

-- Simple level load:
-- [Button] → flow → [Load Level] levelPath="west_coast_usa"
--                     → flow → [Spawn Vehicle]

-- Custom loading screen workflow:
-- [Load Level] levelPath="italy" customLoadingScreen=true
--   → (waits for manual hide)
-- [Do Setup] → [Hide Loading Screen] → finished → [Continue]

Key Dependencies

core_levels.startLevel() - engine function to load a level
getMissionFilename() - returns the current level's mission file
getAllLevelIdentifiers() - lists available levels
spawn.preventPlayerSpawning - controls automatic vehicle spawning
map.assureLoad() - ensures map data is refreshed after level switch

Load Level (Flowgraph Node)

Overview

Pin Schema

Input Pins

Output Pins

Internals

Key Methods

State Machine

Node Data Properties

How It Works

Usage Example

Key Dependencies

See Also

On this page

Load Level (Flowgraph Node)

Overview

Pin Schema

Input Pins

Output Pins

Internals

Key Methods

State Machine

Node Data Properties

How It Works

Usage Example

Key Dependencies

See Also

On this page