ge_utils - Game Engine Utility Functions
Reference for `ge_utils.lua`. A large collection of global utility functions loaded at GE Lua startup - scenetree access, vehicle management, object creation, TorqueScript bridge, camera helpers, and
Reference for ge_utils.lua. A large collection of global utility functions loaded at GE Lua startup - scenetree access, vehicle management, object creation, TorqueScript bridge, camera helpers, and more.
Key Global Functions
Scenetree Access
| Function | Description |
|---|---|
scenetree.findObject(name) | Find scene object by name |
scenetree.findObjectById(id) | Find scene object by numeric ID |
scenetree.findClassObjects(className) | Find all objects of a class |
scenetree.findSubClassObjects(className) | Find objects including subclasses |
scenetree.getAllObjects() | Get all registered objects |
scenetree[name] | Shorthand - metamethod calls findObject |
Vehicle Functions
| Function | Description |
|---|---|
getPlayerVehicle(player) | Cached player vehicle lookup (replaces be:getPlayerVehicle) |
getAllVehicles() | Returns cached list of all BeamNGVehicle objects |
getAllVehiclesByType(typeList?) | Filters vehicles by type (Car, Truck, etc.) |
vehiclesIterator() | Iterator over all vehicles: for vid, veh in vehiclesIterator() do |
activeVehiclesIterator() | Iterator over active vehicles only |
invalidateVehicleCache() | Clears vehicle cache (called on spawn/destroy) |
invalidatePlayerVehicles() | Clears player vehicle cache |
vehicleSetPositionRotation(id, px,py,pz, rx,ry,rz,rw) | Teleport a vehicle |
getVehicleColor(vehicleID?) | Get vehicle color as string |
getRandomPaint(vehId?, commonPaintProb?) | Random paint with real-world color bias |
fillVehicleSpawnOptionDefaults(model, opt) | Fill spawn options with config defaults |
sanitizeVehicleSpawnOptions(model, opt) | Fully validate and default spawn options |
Object Creation & Prefabs
| Function | Description |
|---|---|
createObject(className) | Creates a new scene object with ref counting |
spawnPrefab(name, file, pos, rot, scale) | Spawns a prefab (v1 or v2) into MissionGroup |
removePrefab(name) | Unloads and deletes a prefab |
addPrefab(name, file, pos, rot, scale) | Creates but doesn't load a prefab |
TorqueScript Bridge
| Function | Description |
|---|---|
TorqueScriptLua.call(functor, ...) | Call a TS function with return value |
TorqueScriptLua.exec(filePath) | Execute a .cs script file |
TorqueScriptLua.getVar(name) | Get a console variable |
TorqueScriptLua.setVar(name, value) | Set a console variable |
TorqueScriptLua.getBoolVar(name) | Get console variable as boolean |
Scene Queries
| Function | Description |
|---|---|
getObjectByClass(className) | First object of class |
getObjectsByClass(className) | All objects of class |
getTimeOfDay(asString?) | Current time from TimeOfDay object |
setTimeOfDay(input) | Set time (string "HH:MM" or table) |
castRay(origin, target, terrain?, renderGeo?) | Raycast, returns hit info |
castRayDebug(...) | Raycast with debug visualization |
Misc Utilities
| Function | Description |
|---|---|
getClosestVehicle(reqID, callback) | Finds nearest vehicle to requester |
pushActionMap(map) / popActionMap(map) | Input action map stack |
queueCallbackInVehicle(veh, geFn, vluaCmd, ...) | Cross-VM callback pattern |
newFPSLimiter(targetFPS) | Creates a frame-rate limiter object |
translateDistance(value, big?) | Unit conversion (metric/imperial) |
translateVelocity(value, big?) | Speed unit conversion |
stringToTable(str, sep?) | Split string to table |
getDirs(path, levels?) | List directories |
dirContent(path) | List all files recursively |
isOfficialContent(path) | Check if path is in game directory |
How It Works
This file is loaded early in GE Lua initialization (require("ge_utils") in main.lua). It establishes the scenetree singleton with metamethods for transparent object lookup, defines the TorqueScriptLua bridge for legacy script interop, and provides a comprehensive vehicle management layer with caching to minimize garbage generation.
The scenetree object uses __index metamethod to intercept property access and delegate to findObject, making scenetree.MissionGroup equivalent to scenetree.findObject("MissionGroup").
-- Common patterns
local veh = getPlayerVehicle(0)
local tod = getObjectByClass("TimeOfDay")
local obj = createObject('TSStatic')
obj:setField('shapeName', 0, 'art/shapes/my_shape.dae')
obj:setPosition(vec3(0, 0, 10))
obj:registerObject('myObject')
scenetree.MissionGroup:add(obj.obj)server/commands - Camera & Input Commands
Reference for `server/commands.lua`. Provides camera management functions - switching between free/game cameras, positioning, and deprecated global camera accessors.
main.lua - GE Lua Entry Point & Game Loop
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