Game Engine Main

Reference for `main.lua`. The root entry point for the Game Engine Lua VM - sets up the runtime environment, loads core modules, defines the main update loop, and handles all lifecycle callbacks from

Reference for main.lua. The root entry point for the Game Engine Lua VM - sets up the runtime environment, loads core modules, defines the main update loop, and handles all lifecycle callbacks from C++.

Key Global Functions

Lifecycle

Function	Description
`init(reason)`	Called on load/reload - initializes settings, extensions, mods
`onGameEngineStartup()`	Called once at engine start - bootstraps everything
`onLuaReloaded()`	Called on Ctrl+L reload
`onExit()`	Cleanup on shutdown
`onPreExit()`	Pre-shutdown hook

Frame Updates

Function	Description
`update(dtReal, dtSim, dtRaw)`	Main frame update - runs after input, before physics
`luaPreRender(dtReal, dtSim, dtRaw)`	Called before rendering, after physics
`updateFirstFrame()`	One-time first frame setup

Level Loading

Function	Description
`clientPreStartMission(levelPath)`	Before mission resources load
`clientPostStartMission(levelPath)`	After level/car fully loaded
`clientStartMission(levelPath)`	After level items loaded
`clientEndMission(levelPath)`	Level teardown
`returnToMainMenu()`	Disconnects and returns to menu

Vehicle Events

Function	Description
`vehicleSpawned(vid)`	Vehicle creation callback
`vehicleSwitched(old, new, player)`	Player changed vehicles
`vehicleReset(vid)`	Vehicle reset callback
`vehicleDestroyed(vid)`	Vehicle removal callback
`vehicleActiveChanged(vid, active)`	Activation state change
`onCouplerAttached(o1, o2, n1, n2)`	Trailer coupled
`onCouplerDetached(o1, o2, n1, n2)`	Trailer decoupled

Extension Management

Function	Description
`loadManualUnloadExtensions()`	Load persistent extensions
`loadPresetExtensions()`	Load gameplay extensions
`unloadAutoExtensions()`	Unload non-persistent extensions
`setExtensionUnloadMode(ext, mode)`	Set "manual" or "auto" unload
`endActiveGameMode(callback)`	Cleanly end current game mode

Internals

Startup Sequence

package.path set to include lua/ge/, lua/gui/, lua/common/, etc.
Core requires: luaCore, mathlib, utils, ge_utils, json, guihooks, extensions, map, settings.
onGameEngineStartup() creates MainEventManager, parses CLI args, loads client core and physics.
init() loads startup extensions, initializes settings, connects online services.
updateFirstFrame() finalizes settings, handles CLI arguments, waits for UI ready.

Extension Categories

startupExtensions: ~60 core extensions (camera, input, vehicles, UI, career, etc.) - manually unloaded.
presetExtensions: ~50 gameplay extensions (traffic, missions, weather, etc.) - auto-unloaded between levels.
editorExtensions: editor_main, editor_veMain - loaded if editor is enabled.

World Ready State Machine

worldReadyState = -1: Not in a level
worldReadyState = 0: Level loading
worldReadyState = 1: Waiting for vehicle materials to render
worldReadyState = 2: Fully ready

Key Globals Set

vmType = 'game'
gameConnection - backward compatibility (not a real scene object)
levelLoaded - path of loaded level or nil
sailingTheHighSeas - piracy detection flag
editor - editor interface table

How It Works

The update() function is the heart of the game loop, called every frame. It ticks settings, processes input bindings, updates sim time authority, then fires onUpdate and onGuiUpdate hooks across all extensions. luaPreRender() handles map updates, draw debug hooks, and the world-ready state transition.

-- The main update loop (simplified)
function update(dtReal, dtSim, dtRaw)
  settings.settingsTick(dtReal, dtSim, dtRaw)
  extensions.core_input_bindings.updateGFX(dtRaw)
  simTimeAuthority.update(dtReal)
  extensions.hook('onUpdate', dtReal, dtSim, dtRaw)
  if be:getUpdateUIflag() then
    extensions.hook('onGuiUpdate', dtReal, dtSim, dtRaw)
  end
end

Key Global Functions

Lifecycle

Function	Description
`init(reason)`	Called on load/reload - initializes settings, extensions, mods
`onGameEngineStartup()`	Called once at engine start - bootstraps everything
`onLuaReloaded()`	Called on Ctrl+L reload
`onExit()`	Cleanup on shutdown
`onPreExit()`	Pre-shutdown hook

Frame Updates

Function	Description
`update(dtReal, dtSim, dtRaw)`	Main frame update - runs after input, before physics
`luaPreRender(dtReal, dtSim, dtRaw)`	Called before rendering, after physics
`updateFirstFrame()`	One-time first frame setup

Level Loading

Function	Description
`clientPreStartMission(levelPath)`	Before mission resources load
`clientPostStartMission(levelPath)`	After level/car fully loaded
`clientStartMission(levelPath)`	After level items loaded
`clientEndMission(levelPath)`	Level teardown
`returnToMainMenu()`	Disconnects and returns to menu

Vehicle Events

Function	Description
`vehicleSpawned(vid)`	Vehicle creation callback
`vehicleSwitched(old, new, player)`	Player changed vehicles
`vehicleReset(vid)`	Vehicle reset callback
`vehicleDestroyed(vid)`	Vehicle removal callback
`vehicleActiveChanged(vid, active)`	Activation state change
`onCouplerAttached(o1, o2, n1, n2)`	Trailer coupled
`onCouplerDetached(o1, o2, n1, n2)`	Trailer decoupled

Extension Management

Function	Description
`loadManualUnloadExtensions()`	Load persistent extensions
`loadPresetExtensions()`	Load gameplay extensions
`unloadAutoExtensions()`	Unload non-persistent extensions
`setExtensionUnloadMode(ext, mode)`	Set "manual" or "auto" unload
`endActiveGameMode(callback)`	Cleanly end current game mode

Internals

Startup Sequence

package.path set to include lua/ge/, lua/gui/, lua/common/, etc.
Core requires: luaCore, mathlib, utils, ge_utils, json, guihooks, extensions, map, settings.
onGameEngineStartup() creates MainEventManager, parses CLI args, loads client core and physics.
init() loads startup extensions, initializes settings, connects online services.
updateFirstFrame() finalizes settings, handles CLI arguments, waits for UI ready.

Extension Categories

startupExtensions: ~60 core extensions (camera, input, vehicles, UI, career, etc.) - manually unloaded.
presetExtensions: ~50 gameplay extensions (traffic, missions, weather, etc.) - auto-unloaded between levels.
editorExtensions: editor_main, editor_veMain - loaded if editor is enabled.

World Ready State Machine

worldReadyState = -1: Not in a level
worldReadyState = 0: Level loading
worldReadyState = 1: Waiting for vehicle materials to render
worldReadyState = 2: Fully ready

Key Globals Set

vmType = 'game'
gameConnection - backward compatibility (not a real scene object)
levelLoaded - path of loaded level or nil
sailingTheHighSeas - piracy detection flag
editor - editor interface table

How It Works

-- The main update loop (simplified)
function update(dtReal, dtSim, dtRaw)
  settings.settingsTick(dtReal, dtSim, dtRaw)
  extensions.core_input_bindings.updateGFX(dtRaw)
  simTimeAuthority.update(dtReal)
  extensions.hook('onUpdate', dtReal, dtSim, dtRaw)
  if be:getUpdateUIflag() then
    extensions.hook('onGuiUpdate', dtReal, dtSim, dtRaw)
  end
end

Game Engine Main

Key Global Functions

Lifecycle

Frame Updates

Level Loading

Vehicle Events

Extension Management

Internals

Startup Sequence

Extension Categories

World Ready State Machine

Key Globals Set

How It Works

See Also

On this page

Game Engine Main

Key Global Functions

Lifecycle

Frame Updates

Level Loading

Vehicle Events

Extension Management

Internals

Startup Sequence

Extension Categories

World Ready State Machine

Key Globals Set

How It Works

See Also

On this page