Vehicle Lua

Vehicle Lua and HTML Homepage

Prerequisites

• Knowledge of any programming language
  • Lua is a programming language, therefore in order to use it effectively you need to understand the basics of programming. If you know how to program then you should be able to pick up Lua as you go, even if you have never used this language before. In terms of structure it is similar to visual basic in that there are no curly brackets or semi colons to end lines, this is probably the main thing to get used to if moving from a C based language.
• A text editor.
  • Any will do but it is strongly advised to use a more advanced one than NotePad, a good free option is NotePad++.

How Vehicle Lua works

• Each vehicle can have many Lua files
• Each Lua file can have many functions
• The code within these functions can monitor/control vehicle parameters such as wheel speed and throttle position

For example, you may wish to create a cruise control system for your vehicle, you may also want it to disengage when the driver presses the brake pedal. So you would write some code that watches the brake pedal while cruise control is engaged to see if the driver presses it. If the driver presses it you would then disable cruise control. This is on a basic level how vehicle Lua can function.

How Streams work

How to read data from Streams

Reading from Streams is really easy!

[Your Lua Variable] = [Stream you want data from]

So to give an example of what this may look like

local myGear = electrics.values.gear_M

However, if the player removes the gearbox from your vehicle, this could cause errors. As such you may wish to add "or 0" to your code in order to protect it from null values. This should be done with all Streams unless you have a good reason not to. The "or 0" syntax will set your variable to 0 if a null value is detected.

local myGear = (electrics.values.gear_M or 0)

So far this is looking pretty good, but what if the player has fitted an automatic gearbox to the car? You have few options in how you may wish to deal with this. One option would be to duplicate the above code but read from the "electrics.values.gear_A" Stream, and then create some logic to check which variable is valid. Another option may be to add another "or" into the above statement to accept "electrics.values.gear_A" values into your variable if no "electrics.values.gear_M" values are detected. Both options are valid, its up to you to decide which is most preferable based upon how you want your algorithms to function.

local myGear = (electrics.values.gear_M or electrics.values.gear_A or 0)

local myGearManual = (electrics.values.gear_M or 0)
local myGearAuto = (electrics.values.gear_A or 0)

[Logic to check which is valid and process]

How to write data to Streams

Writing to Streams is also easy!

[Stream you want to write to] = [Variable containing data you want to write]

In practice this would look like

electrics.values.throttle = myThrottleVariable

It is a good idea to sanitise your outputs before writing them to the games Streams in order to prevent unspecified behaviour from occurring. Usually this can be done by adding in some simple range checks.

if (myThrottleVariable > 1) then
    myThrottleVariable = 1
end
if (myThrottleVariable < 0) then
    myThrottleVariable = 0
end

Since BeamNG uses a float between the values of 0 and 1 for throttle, the range checks above will ensure that your code is outputting sensible values. While your code has likely gone wrong if these checks fail, by having them in place it reduces the damage that could be done to any further code. For example if you set throttle to "100" and another bit of code reads that value as being 100, it could cause that later section of code to fail.

Some of the most useful Streams

Here is a table containing many of the most useful and basic streams for creating vehicle dashboards.

An incomplete list of Streams can be found here: Streams

Function	Description	DataType	Lua Parameter
Vehicle Speed	The speed of 1 wheel (defined in your jbeam) is used to deduce speed of vehicle	Float	electrics.values.wheelspeed
Gear Selected (Manual)	Contains data stating which gear is selected on manual gearbox	Float	electrics.values.gear_M
Indicators / Turn Signals	Smoothed Blinking signal is produced when indicator is turned on	Float	electrics.values.signal_L / electrics.values.signal_R