API Reference GE Extensions scenario Scenario Engine The main scenario engine. Manages the entire scenario lifecycle: loading, state transitions, countdown, racing, finishing, multiseat, vehicle processing, waypoint processing, and UI coordination. This
The main scenario engine. Manages the entire scenario lifecycle: loading, state transitions, countdown, racing, finishing, multiseat, vehicle processing, waypoint processing, and UI coordination. This is the largest and most central scenario file.
Field Type Description M.onRaceWaypointReachedvaries Assigned as onRaceWaypointReached
Function Signature Description M.executeScenario(sc)Starts executing a scenario (loads level, extensions) M.restartScenario()Restarts the current scenario from scratch M.stop()Stops and unloads the scenario completely M.endRace(countDownTime?)Triggers race end with optional countdown M.endScenario(countDownTime?)Finishes scenario, hooks goals, applies slow-motion M.finish(result)Pools a result (pass/fail) and triggers finish flow M.getScenario()Returns the current scenario table M.changeState(newState)Transitions scenario to a new state M.freezeAll(state)Freezes/unfreezes all scenario vehicles M.pauseScenario / M.continueScenario()Pauses/resumes simulation time M.stopRaceTimer()Stops the race timer M.getRaceDistance(scenario)Calculates total race distance from lapConfig M.uiEventRetry()Restarts scenario (called from UI button) M.uiEventFreeRoam()Transitions to free-roam mode M.getVehicleName(vehicleID)Returns vehicle name from ID M.rollingStartTriggered()Handles rolling start checkpoint crossing M.spawnPrefab(val, objName, objFileName, objPos, objRotation, objScale)- M.onClientEndMission()- M.onClientStartMission()Hook called when a mission starts M.onScenarioUIReady(state)- M.onResetGameplay(playerID)- M.prepareStartUI()- M.onCameraModeChanged(modeName)- M.trackVehicleMovementAfterDamage(vehicleName, trackingOptions)- M.onPreRender(dt, dtSim)- M.onVehicleStoppedMoving(vehicleID)- M.onPhysicsUnpaused()- M.onPhysicsPaused()- M.onFilteredInputChanged(devName, action, value)- M.onSerialize()- M.onDeserialized(data)- M.onExtensionUnloaded()- M.displayStartUI()- M.displayEndUI()- M.updateVehicleAiState(vehicleName, data)- M.onExtensionLoaded()- M.onVehicleSelected(vehicleData)- M.onBeamNGTrigger(data)- M.getscenarioName()-
State Description pre-startLevel loaded, prefabs spawned, vehicles frozen, extensions loading pre-runningUI shown, markers initialized, goals set up, vehicles frozen runningActive gameplay - sub-states: countdown, racing finishedRace ended, results being gathered postFinal UI shown, stats calculated restartRestarting (clears and re-enters pre-start)
Sub-State Description countdown3.5s countdown (or 1.5s if showCountdown is false) racingActive race - timer running, goals checking doneRace complete, transitioning to post
executeScenario(sc) stores scenario, loads extensions, starts level via core_levels.startLevelonClientStartMission fires when level loads - creates ScenarioObjectsGroup, spawns prefabs, spawns user vehiclecompleteStartUp processes vehicles, waypoints, level state changes, input filters, camera setup
pre-running → freezes vehicles, initializes markers, goals, waypointsrunning + countdown → shows countdown, unfreezes on completionrunning + racing → timer active, goals ticking, waypoints trackingendRace() → transitions to finished, hooks gather statspost → displays end UI with stats, medals, retry/freeRoam buttons
Iterates BeamNGVehicle objects in scene
Maps vehicleNameToId and vehicleIdToName
Sets playerUsable and startFocus flags from scenario JSON
Applies vehicle extensions from config
Reads driver config from scenario.vehicles[name].driver
Supports: ModeAI, AiAggression, targetAI, frozen, command, fleeTarget, roadDrivability
Multiseat : Supports multiple human players with device-to-vehicle assignmentAttempts : Configurable retry system with attemptsInfo for multiple attempts per scenarioLevel State : Can modify scene objects (time of day, etc.) and restore on exitStats : Gathers end-of-race statistics via statistics_statisticsCamera Path : Supports intro camera paths via democam SimPath objects
-- Usually launched by scenariosLoader: local sc = scenario_scenariosLoader. loadScenario (path) scenario_scenarios. executeScenario (sc) -- End race from goal code: scenario_scenarios. finish ({failed = "You crashed!" }) -- or scenario_scenarios. finish ({msg = "You won!" }) -- Get current scenario: local scenario = scenario_scenarios. getScenario () if scenario and scenario. state == 'running' then -- do something end
File is ~2200 lines - the backbone of the scenario system
Uses simTimeAuthority for bullet time (1/8 speed during end screen)
inputActionFilter manages hotkey blacklists/whitelists per scenarioCamera blacklist prevents free cam during scenarios
onDrawDebug visualizes waypoint nodes in editor modeBackward compatibility metatable warns about deprecated field names
M.onDrawDebug - (undocumented)