GE Hook Catalog

Every GE hook with signatures and descriptions — lifecycle, per-frame, vehicle, physics, world, input, and file system hooks.

This is the complete list of hooks your GE extension can subscribe to. Define a matching function on your M table to receive any of these events.

:::tip[How hooks work] Define local function onVehicleSpawned(vid, vehObj) end and export it as M.onVehicleSpawned = onVehicleSpawned. The engine calls it automatically when a vehicle spawns. :::

Lifecycle Hooks (Boot → Level → Shutdown)

Hook	Signature	Source	Description
`onExtensionLoaded`	`(deserializedData)` or `(name)`	extensions.lua	Called on self-load (no args or deserialized state) and when other extensions load (receives their name)
`onInit`	`(deserializedData)`	extensions.lua	GE-only second-phase init after all batch extensions call onExtensionLoaded
`onFirstUpdate`	`()`	main.lua	Very first frame after init. One-shot.
`onUiReady`	`()`	main.lua	CEF UI fully loaded and responsive
`onClientPreStartMission`	`(levelPath)`	main.lua	Before mission resources are loaded
`onClientPostStartMission`	`(levelPath)`	main.lua	Level Lua loaded, scene objects available
`onClientStartMission`	`(levelPath)`	main.lua	Level items loaded (uses `hookNotify`)
`onWorldReadyState`	`(state)`	main.lua	0=not ready, 1=loading materials, 2=fully loaded
`onClientEndMission`	`(levelPath)`	main.lua	Leaving level (uses `hookNotify`)
`onPreWindowClose`	`()`	main.lua	Window close button pressed
`onPreExit`	`()`	main.lua	About to shut down
`onExit`	`()`	main.lua	Final shutdown

Per-Frame Hooks

Hook	Signature	Source	Description
`onUpdate`	`(dtReal, dtSim, dtRaw)`	main.lua	Every frame, after input, before physics
`onPreRender`	`(dtReal, dtSim, dtRaw)`	main.lua	Every frame, after physics, before render
`onGuiUpdate`	`(dtReal, dtSim, dtRaw)`	main.lua	Every frame, during update() when UI flag set
`onDrawDebug`	`(focusPos, dtReal, dtSim, dtRaw)`	main.lua	Debug visualization pass (during luaPreRender)

dt arguments:

dtReal - Wall-clock time since last frame
dtSim - Simulation time (affected by slow-motion/bullettime)
dtRaw - Unscaled raw delta

Vehicle Hooks

Hook	Signature	Source	Description
`onPreVehicleSpawned`	`(vid, vehObj)`	main.lua	Before spawn hooks - use for data init
`onVehicleSpawned`	`(vid, vehObj)`	main.lua	Vehicle fully spawned
`onVehicleDestroyed`	`(vid)`	main.lua	Vehicle removed from scene
`onVehicleSwitched`	`(oldId, newId, player)`	main.lua	Player changed active vehicle
`onVehicleResetted`	`(vehicleID)`	main.lua	Vehicle reset (R key)
`onVehicleActiveChanged`	`(vehicleID, active)`	main.lua	Vehicle activated/deactivated (traffic pooling)

Physics Hooks

Hook	Signature	Source	Description
`onPhysicsEngineEvent`	`(args)`	main.lua	Physics engine events
`onPhysicsPaused`	`()`	main.lua	Physics paused (from physicsStateChanged)
`onPhysicsUnpaused`	`()`	main.lua	Physics resumed (from physicsStateChanged)
`onResetGameplay`	`(playerID)`	main.lua	Gameplay reset

Coupler Hooks

Hook	Signature	Source	Description
`onCouplerAttached`	`(objId1, objId2, nodeId, obj2nodeId)`	main.lua	Vehicles coupled (trailer)
`onCouplerDetached`	`(objId1, objId2, nodeId, obj2nodeId)`	main.lua	Coupler physically separated
`onCouplerDetach`	`(objId, nodeId)`	main.lua	User-initiated coupler detach

World/Environment Hooks

Hook	Signature	Source	Description
`onBeamNGTrigger`	`(data)`	main.lua	BeamNGTrigger zone entered/exited
`onBeamNGWaypoint`	`(args)`	main.lua	Waypoint reached
`onSetClusterPosRelRot`	`(vehicleID, cNodeId)`	main.lua	Vehicle cluster teleported
`onClusterTeleportNoReset`	`(vehicleID, nodeId, px, py, pz, rdx, rdy, rdz, rdw)`	main.lua	Cluster teleport without reset
`onAiModeChange`	`(vehicleID, newAiMode)`	main.lua	AI mode changed

Input Hooks

Hook	Signature	Source	Description
`onMouseLocked`	`(locked)`	main.lua	Mouse lock state changed

Editor Hooks

Hook	Signature	Source	Description
`onEditorEnabled`	`(enabled)`	main.lua	Editor toggled on/off

File System Hooks

Hook	Signature	Source	Description
`onFilesChanged`	`(files)`	main.lua:679	File change batch detected
`onFileChanged`	`(filename, type)`	main.lua:681	Individual file change
`onFileChangedEnd`	`()`	main.lua:683	File change batch complete
`onTexDrawPrimCompressDone`	`(textureName)`	main.lua	Texture compression finished

UI/Screen Hooks (from extensions, not main.lua)

Hook	Signature	Source	Description
`onScreenFadeState`	`(state)`	ui/fadeScreen.lua	1=fading to black, 2=fully black, 3=fading from black
`onModManagerStateChanged`	`()`	core/modmanager.lua	Mod installed/activated/deactivated
`onBeforeMountEntry`	`(filename, mountPoint)`	core/modmanager.lua	Before mod is mounted into VFS

Usage Pattern

local M = {}

-- Subscribe to any hook by exporting a function with that name
local function onVehicleSpawned(vid, vehObj)
  log('I', 'myext', 'Vehicle spawned: ' .. tostring(vid))
end

local function onWorldReadyState(state)
  if state == 2 then
    -- World fully loaded, safe to do work
  end
end

M.onVehicleSpawned = onVehicleSpawned
M.onWorldReadyState = onWorldReadyState
return M

Notes

hookNotify (used by onClientStartMission, onClientEndMission) differs from hook - it processes the "loaded fresh" list immediately, meaning extensions loaded during this hook get their onExtensionLoaded called right away.
All hooks are called in dependency-resolved order.
A hook function returning false does NOT cancel propagation to other extensions (except onExtensionLoaded which aborts loading of THAT extension).

Lifecycle Hooks (Boot → Level → Shutdown)

Hook	Signature	Source	Description
`onExtensionLoaded`	`(deserializedData)` or `(name)`	extensions.lua	Called on self-load (no args or deserialized state) and when other extensions load (receives their name)
`onInit`	`(deserializedData)`	extensions.lua	GE-only second-phase init after all batch extensions call onExtensionLoaded
`onFirstUpdate`	`()`	main.lua	Very first frame after init. One-shot.
`onUiReady`	`()`	main.lua	CEF UI fully loaded and responsive
`onClientPreStartMission`	`(levelPath)`	main.lua	Before mission resources are loaded
`onClientPostStartMission`	`(levelPath)`	main.lua	Level Lua loaded, scene objects available
`onClientStartMission`	`(levelPath)`	main.lua	Level items loaded (uses `hookNotify`)
`onWorldReadyState`	`(state)`	main.lua	0=not ready, 1=loading materials, 2=fully loaded
`onClientEndMission`	`(levelPath)`	main.lua	Leaving level (uses `hookNotify`)
`onPreWindowClose`	`()`	main.lua	Window close button pressed
`onPreExit`	`()`	main.lua	About to shut down
`onExit`	`()`	main.lua	Final shutdown

Per-Frame Hooks

Hook	Signature	Source	Description
`onUpdate`	`(dtReal, dtSim, dtRaw)`	main.lua	Every frame, after input, before physics
`onPreRender`	`(dtReal, dtSim, dtRaw)`	main.lua	Every frame, after physics, before render
`onGuiUpdate`	`(dtReal, dtSim, dtRaw)`	main.lua	Every frame, during update() when UI flag set
`onDrawDebug`	`(focusPos, dtReal, dtSim, dtRaw)`	main.lua	Debug visualization pass (during luaPreRender)

dt arguments:

dtReal - Wall-clock time since last frame
dtSim - Simulation time (affected by slow-motion/bullettime)
dtRaw - Unscaled raw delta

Vehicle Hooks

Hook	Signature	Source	Description
`onPreVehicleSpawned`	`(vid, vehObj)`	main.lua	Before spawn hooks - use for data init
`onVehicleSpawned`	`(vid, vehObj)`	main.lua	Vehicle fully spawned
`onVehicleDestroyed`	`(vid)`	main.lua	Vehicle removed from scene
`onVehicleSwitched`	`(oldId, newId, player)`	main.lua	Player changed active vehicle
`onVehicleResetted`	`(vehicleID)`	main.lua	Vehicle reset (R key)
`onVehicleActiveChanged`	`(vehicleID, active)`	main.lua	Vehicle activated/deactivated (traffic pooling)

Physics Hooks

Hook	Signature	Source	Description
`onPhysicsEngineEvent`	`(args)`	main.lua	Physics engine events
`onPhysicsPaused`	`()`	main.lua	Physics paused (from physicsStateChanged)
`onPhysicsUnpaused`	`()`	main.lua	Physics resumed (from physicsStateChanged)
`onResetGameplay`	`(playerID)`	main.lua	Gameplay reset

Coupler Hooks

Hook	Signature	Source	Description
`onCouplerAttached`	`(objId1, objId2, nodeId, obj2nodeId)`	main.lua	Vehicles coupled (trailer)
`onCouplerDetached`	`(objId1, objId2, nodeId, obj2nodeId)`	main.lua	Coupler physically separated
`onCouplerDetach`	`(objId, nodeId)`	main.lua	User-initiated coupler detach

World/Environment Hooks

Hook	Signature	Source	Description
`onBeamNGTrigger`	`(data)`	main.lua	BeamNGTrigger zone entered/exited
`onBeamNGWaypoint`	`(args)`	main.lua	Waypoint reached
`onSetClusterPosRelRot`	`(vehicleID, cNodeId)`	main.lua	Vehicle cluster teleported
`onClusterTeleportNoReset`	`(vehicleID, nodeId, px, py, pz, rdx, rdy, rdz, rdw)`	main.lua	Cluster teleport without reset
`onAiModeChange`	`(vehicleID, newAiMode)`	main.lua	AI mode changed

Input Hooks

Hook	Signature	Source	Description
`onMouseLocked`	`(locked)`	main.lua	Mouse lock state changed

Editor Hooks

Hook	Signature	Source	Description
`onEditorEnabled`	`(enabled)`	main.lua	Editor toggled on/off

File System Hooks

Hook	Signature	Source	Description
`onFilesChanged`	`(files)`	main.lua:679	File change batch detected
`onFileChanged`	`(filename, type)`	main.lua:681	Individual file change
`onFileChangedEnd`	`()`	main.lua:683	File change batch complete
`onTexDrawPrimCompressDone`	`(textureName)`	main.lua	Texture compression finished

UI/Screen Hooks (from extensions, not main.lua)

Hook	Signature	Source	Description
`onScreenFadeState`	`(state)`	ui/fadeScreen.lua	1=fading to black, 2=fully black, 3=fading from black
`onModManagerStateChanged`	`()`	core/modmanager.lua	Mod installed/activated/deactivated
`onBeforeMountEntry`	`(filename, mountPoint)`	core/modmanager.lua	Before mod is mounted into VFS

Usage Pattern

local M = {}

-- Subscribe to any hook by exporting a function with that name
local function onVehicleSpawned(vid, vehObj)
  log('I', 'myext', 'Vehicle spawned: ' .. tostring(vid))
end

local function onWorldReadyState(state)
  if state == 2 then
    -- World fully loaded, safe to do work
  end
end

M.onVehicleSpawned = onVehicleSpawned
M.onWorldReadyState = onWorldReadyState
return M

Notes

hookNotify (used by onClientStartMission, onClientEndMission) differs from hook - it processes the "loaded fresh" list immediately, meaning extensions loaded during this hook get their onExtensionLoaded called right away.
All hooks are called in dependency-resolved order.
A hook function returning false does NOT cancel propagation to other extensions (except onExtensionLoaded which aborts loading of THAT extension).

GE Hook Catalog

Lifecycle Hooks (Boot → Level → Shutdown)

Per-Frame Hooks

Vehicle Hooks

Physics Hooks

Coupler Hooks

World/Environment Hooks

Input Hooks

Editor Hooks

File System Hooks

UI/Screen Hooks (from extensions, not main.lua)

Usage Pattern

Notes

See Also

On this page

GE Hook Catalog

Lifecycle Hooks (Boot → Level → Shutdown)

Per-Frame Hooks

Vehicle Hooks

Physics Hooks

Coupler Hooks

World/Environment Hooks

Input Hooks

Editor Hooks

File System Hooks

UI/Screen Hooks (from extensions, not main.lua)

Usage Pattern

Notes

See Also

On this page