From BeamNG

We have two separate versions of Lua running: Vehicle Lua and GameEngine Lua. Both have different API, though some is shared. Each API's entry point is its main.lua file. We'll try to explain things here a bit.

It is split like this in the game folder:

  • lua (do not put things here)
    • common
      The folder for libraries/tools that are generic enough to be used for both libbeamng and gameengine.
    • console
      This is the instance directory for the console.exe / bananabench. Its a Lua only physics console that comes without the grapics/gameengine. Will execute main.lua on start.
      Restart of the process is required to reload changes on the lua files.
    • vehicle
      This is the vehicle instance directory. Every vehicle will spawn a new process by executing main.lua.
      It can be reloaded with the vehicle using CTRL + R
    • t3d / ge
      This is the Lua instance directory for the game engine. It will spawn a process using main.lua at the start of the engine.
      It can be reloaded while the engine is running via CTRL + L

Specific Lua files


A modScript.lua file which is located in gets executed on game start. This can be used to load other extensions/modules. Place this file in a subfolder so you do not overwrite other modder's modScript.lua files.

e.g. scripts/your_unique_name/modScript.lua


One can place a mainLevel.lua file, wherever a main.level.json file of a map is located, to load it once the level is loaded.

e.g. levels/GridMap/mainLevel.lua

Keep in mind - since it's a module that gets loaded - that you have to return the module.

local M = {}


return M

Game Engine Lua / GE

Generally available classes/objects/functions:


Events that automatically get called by the game engine.

Event Signature Example Description
void onRaceStart()
local function onRaceStart()
This event gets called once the scenario countdown has run down. 
void onRaceTick(number raceTickTime)
local function onRaceTick(raceTickTime)
This event gets called every quarter-second once the scenario is running. 
void onScenarioChange(scenario)
local function onScenarioChange(scenario)
  if scenario.state == 'pre-running' then
    print('onScenarioChange - scenario is still in introduction phase')
  if scenario.state == 'running' then
    print('onScenarioChange - the scenario just entered running state')
  if scenario.state == 'post' then
    print('onScenarioChange - scenario just finished')
This event gets called everytime the scenario state changes. 
This can be used to check if a scenario already started etc.
void onCameraModeChanged(cameraMode)
local function onCameraModeChanged(cameraMode) 
  print(cameraMode) -- prints the name of the selected camera mode e.g. orbit, onboard.hood etc.
This event gets called everytime the camera mode changes 
(e.g. when pressing 'C' to change camera view).
Game is passing the current selected camera mode to the function.



Function Signature Example Description
number getGravity()
Returns the gravity of the current loaded level e.g. -9.81 
void setGravity(number grav)
Sets the gravity of the current loaded level
table getTimeOfDay()

Returns a table with the following elements:
number dayLength
number dayScale
number nightScale
bool play
number time - actual time between ''0'' and ''1'' where ''0'' and ''1'' are noon (12pm) and 0.5 is midnight (12am) 
void setTimeOfDay()

core_environment.setTimeOfDay({time=0.5, play=true})

core_environment.setTimeOfDay({dayScale=1, nightScale=1.5})
Sets values of the timeOfDay table accordingly to the values which were passed to the function

Vehicle Lua


Events that automatically get called by the game engine.

Event Signature Example Description
void onInit()
local function onInit()
This event gets called once vehicle is spawned. 
void onReset()
local function onReset()
This event gets called once the vehicle is spawned and whenever you reset the vehicle. Can be used reset values of a script. 
void updateGFX(dt)
local function updateGFX(dt)
This event gets called every frame. The game engine passes the deltaTime as argument so you can see how much time passed since the last time the event was called. 

- - - - Deprecated. Needs rework!

Global Classes


Integer Color Class. Range from 0 to 255 for all fields

Function Signature Example Description
void ColorI(number red, number green, number blue, number alpha)
local red = 50
local green = 100
local blue = 137
local alpha = 255
local c = ColorI(red, green, blue, alpha)
print(c.r) -- returns 50
print(c.g) -- returns 100
print(c.b) -- returns 137
print(c.a) -- returns 255
Constructor, number values from 0 to 255.
Attribute Name Type Description
r number (0-255) Red Channel
g number (0-255) Green Channel
b number (0-255) Blue Channel
a number (0-255) Alpha Channel


Interface for the Lua instance. Can be accessed from GameEngine Lua only via Lua

Function Signature Example Description
nil Lua:log(char level, string origin, string msg)
Lua:log('D', 'myFile', 'I am a debug message')
log('I', 'myFile', 'Using the shortcut')
Central Logging function. You can use the shortcut log() instead.
nil Lua:blacklistLogLevel(string levels)
-- disables output of all Debug a Info level messages
Blacklists all named log levels on all channels (consoles, file).

This is handy when you want to disable all outputs from some levels.

nil Lua:exec(string filename)
Executes a Lua file. Async, executed upon next frame.
nil Lua:dumpStack(char loglevel)
-- dumps the Lua stack in the log with log level Error
Dumps the Lua stack into the logs
number Lua:getMemoryUsageKB()
Returns the memory usage in kilo Bytes
nil Lua:enableStackTraceFile(string filename, boolean full)
Lua:enableStackTraceFile("lua_stacktrace.txt", true)
enables the stack tracing functions
table Lua:saveObject(SimObject obj)
serializes the properties of a simobject into a table
bool Lua:findObjectByNameAsTable(string simObjectName, table resultTableReference)
returns a simobject -- do not use: internal function. Use scenetree.findObject() instead
number Lua:findObjectsByClassAsTable(string simObjectClassName, table resultTableReference)
returns simobjects -- do not use: internal function. Use scenetree.findClassObjects() instead
boolean Lua:castSimObject(ConsoleObject obj, table resultTableReference)
internal usage - use scenetree
table Lua:getSimobjectFieldList(ConsoleObject obj)
internal usage - use scenetree
BeamNGVehicle Lua:getControlVehicle()
returns the currently controlled vehicle
nil Lua:setControlVehicle(BeamNGVehicle vehicle, number playerID)
sets the vehicle to be controlled
string Lua:getSelectedLanguage()
returns the language chosen by the user
Attribute Name Type Description
Lua.lastDebugFocusPos Point3F
Lua.userLanguage string


Function Signature Example Description
BeamNGVehicle be:getObject(number vehicleObjectID)

BeamNGVehicle be:getObjectByID(number vehiclePhysicsID)

number be:getObjectCount()

BeamNGVehicle be:getPlayerVehicle(number playerID)

string be:getFFBConfig(number FFBId)

nil be:queueAllObjectLua(string lua)

nil be:queueSystemLua(string lua)

nil be:executeJS(string js)

nil be:executeStreamJS(string streamReference, string js)

boolean be:getEnabled()

nil be:zoom(number zoomValue, number playerID)

nil be:reloadVehicle(number playerID)

nil be:resetVehicle(number playerID)

nil be:toggleEnabled()

nil be:resetCam(number playerID)

nil be:camLookBack(number playerID)

nil be:exitVehicle(number playerID)

nil be:enterNextVehicle(number playerID, number step)

nil be:enterVehicle(number playerID, BeamNGVehicle vehicleInstance)

nil be:cameraToggle(number playerID)

nil be:reloadSystemLua()

nil be:reloadStaticCollision(boolean debug)

nil be:isBlockedByFirewall()

nil be:addFirewallException()

nil be:setPhysicsSpeedFactor(number)

Used to increase simulation speed
Attribute Name Type Description
BeamEngine.persistenceLuaData string
BeamEngine.nodeStream BeamNGNodeStreamPhysFS

Global functions

Global tables and classes

Global userdata objects

  • BeamEngine
  • FS
  • Lua
  • dir
  • gameEngine
  • kARGB_ClipLayer_SaveFlag
  • kARGB_NoClipLayer_SaveFlag
  • kBold
  • kBoldItalic
  • kCCW_Direction
  • kCW_Direction
  • kCenter_Align
  • kClipToLayer_SaveFlag
  • kClip_SaveFlag
  • kDifference_Op
  • kFill_Style
  • kFullColorLayer_SaveFlag
  • kHasAlphaLayer_SaveFlag
  • kIntersect_Op
  • kItalic
  • kLeft_Align
  • kMatrixClip_SaveFlag
  • kMatrix_SaveFlag
  • kNormal
  • kReplace_Op
  • kReverseDifference_Op
  • kRight_Align
  • kStrokeAndFill_Style
  • kStroke_Style
  • kUnion_Op
  • kUnknown_Direction
  • kXOR_Op
  • BeamObject obj
  • terrainBlock