Lua:Reference

Lua:Reference

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

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



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













Retrieved from "http://wiki.beamng.com/index.php?title=Lua:Reference&oldid=11387"


					
					
				





	


	





 

 

 



	

		

			

			Icons made by SimpleIcon from flaticon.com, used under CC