Lua:Reference
(Redirected from Lua Reference)
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 usingCTRL + 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 viaCTRL + L
- common
Specific Lua files
modScript.lua
A modScript.lua file which is located in BeamNG.drive/scripts 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
mainLevel.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 = {} print("mainLevel.lua") return M
Game Engine Lua / GE
Generally available classes/objects/functions:
Events
Events that automatically get called by the game engine.
Event Signature | Example | Description |
---|---|---|
void onRaceStart() |
local function onRaceStart() print('onRaceStart') end |
This event gets called once the scenario countdown has run down. |
void onRaceTick(number raceTickTime) |
local function onRaceTick(raceTickTime) print('onRaceTick') end |
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') end if scenario.state == 'running' then print('onScenarioChange - the scenario just entered running state') end if scenario.state == 'post' then print('onScenarioChange - scenario just finished') end end |
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. end |
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. |
Extensions
Core
Environment
Function Signature | Example | Description |
---|---|---|
number getGravity() |
core_environment.getGravity() |
Returns the gravity of the current loaded level e.g. -9.81 |
void setGravity(number grav) |
core_environment.setGravity(-9.81) |
Sets the gravity of the current loaded level |
table getTimeOfDay() |
core_environment.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=1}) 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
Events that automatically get called by the game engine.
Event Signature | Example | Description |
---|---|---|
void onInit() |
local function onInit() print('onInit') end |
This event gets called once vehicle is spawned. |
void onReset() |
local function onReset() print('onReset') end |
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) print('updateGFX') end |
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
ColorI
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 |
Lua
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 Lua:blacklistLogLevel('DI') |
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) |
Lua:exec('foo/bar/myfile.lua') |
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 Lua:dumpStack('E') |
Dumps the Lua stack into the logs |
number Lua:getMemoryUsageKB() |
print(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) |
dump(Lua:saveObject(scenetree.myObject)) |
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 |
BeamEngine
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
- activated
- arrayConcat
- beamBroken
- beamDeformed
- bench
- createSKRect
- CatMullRomSpline
- debugDraw
- deepcopy
- dump
- dumps
dumpTableToFileUse Lua:dumpToFile- dumpToFile
- deserializeModules
- exportPersistentData
- encodeJson
- float3ToTable
- float3_2_Vector3
- graphicsStep
- graphicsStepLocal
- guiUpdate
- getDirListing
- hexdump
- importPersistentData
- init
- initSystems
- instabilityDetected
- ipairs_safe
- join
- joinES
- joinKVES
- log
- logAlways
- logAlwaysNoNewline
- logDebug
- logError
- logInfo
- logWarn
- logdev
- lpad
- module
- msgs
- newExponentialSmoothing
- newTemporalSmoothingNonLinear
- newT
- pairs_safe
- particleEmitted
- parseColor
- physicsStep
- readDictJSONTable
- readFile
- rerequire
- saveCompiledJBeam
- saveCompiledJBeamRecursive
- saveG
- serialize
- serializeModules
- serializeJsonToFile
- setConfig
- setLogLevel
- shallowcopy
- sign
- spairs
- split
- string.startswith
- string.endswith
- tableContains
- _tableDepth
- tableDepth
- tableFirstKey
- tableIsDict
- tableMerge
- tableMergeRecursive
- tableSize
- tableToColor
- tableToFloat3
- tableToFloat3Default
- testSerialization
- toJSONString
- trim
- trimr
- unserialize
- unrequire
- updateGravity
- vehicleDestroy
- vehicleResetted
- vehicleLua
- writeFile
Global tables and classes
- BeamObject
- CanvasTexture
- FSDirectory
- FilePure
- FlexMesh
- gui
- GameEngine
- HighPerfTimer
- Material
- outgauge
- outsim
- Prop
- Quaternion
- ResourceContainer
- SFXSource
- Settings
- SkCanvas
- SkCanvas_SaveFlags
- SkPaint
- SkPaint_Align
- SkPaint_Style
- SkPath
- SkPath_Direction
- SkRect
- SkTypeface
- SkTypeface_Style
- SpotLight
- TerrainBlock
- Vector3
- bdebug
- beam
- beamng
- beamstate
- beamstats
- bit
- bullettime
- canvas
- color
- debugdrawer
- drivetrain
- electrics
- float3
- groundModel
- hydros
- hydros1
- input
- input_dynamic
- io
- jit
- json
- my
- os
- package
- particleData
- particlefilter
- particles
- partmgmt
- perf
- props
- Path
- sensors
- sounds
- thrusters
- v
- wheel
- wheelData
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