Getting Started
Official Content
Tutorials
Modding
World Editor
Support
BeamNG.tech

Vehicle Controller

This section is work in progress! Some links might lead to pages that are not yet finished, and will not work.

 Summary

The vehicle controller is the main controller for any powered vehicle in beamNG. It manages the powertrain controls and interfaces with the different shift logic controllers for the various transmission types.

Either this controller or the dummy controller must be called on any vehicle or prop for it to work properly.

It is the main source of electrics data for engine and transmission information.

 File Info

Filename vehicleController.lua
Path /lua/vehicle/controller/vehicleController.lua
Type Main
Usage type Single
defaultOrder 500

JBeam Properties

These properties are the properties specific to the vehicle controller itself.

Each shift-logic sub-controllers will also have it’s own specific properties, depending on the type of gearbox.

lowShiftDownRPM[gear]
name
RPM
type
2000
default
Controls the RPM that the controller will downshift at when there is less than 100% throttle applied.
Only applies to automatic gearboxes and arcade mode.
highShiftDownRPM[gear]
name
RPM
type
3500
default
Controls the RPM that the controller will downshift at when there is 100% throttle applied.
Only applies to automatic gearboxes and arcade mode.
lowShiftUpRPM[gear]
name
RPM
type
2500
default
Controls the RPM that the controller will upshift at when there is less than 100% throttle applied.
Only applies to automatic gearboxes and arcade mode.
highShiftUpRPM[gear]
name
RPM
type
5000
default
Controls the RPM that the controller will upshift at when there is 100% throttle applied.
Only applies to automatic gearboxes and arcade mode.
calculateOptimalLoadShiftPoints
name
boolean
type
false
default
Overrides highShiftUpRPM and highShiftDownRPM with values calculated by looking at the engine torque curve and gear ratios.
Only applies to automatic gearboxes and arcade mode.
shiftDownRPMOffsetCoef
name
number
type
1.3
default
Moves the automatically calculated down shift points for less gear hunting
Used for the optimal shift point calculation.
gearboxDecisionSmoothingDown
name
number
type
2
default
How quickly the controller reacts to a decrease in throttle input.

Only applies to automatic gearboxes and arcade mode.

A higher value means the controller will upshift more quickly when decreasing throttle.

gearboxDecisionSmoothingUp
name
number
type
5
default
How quickly the controller reacts to an increase in throttle input.

Only applies to automatic gearboxes and arcade mode.

A higher value means the controller will downshift more quickly when increasing throttle

aggressionSmoothingUp
name
number
type
1.5
default
How quickly the controller reacts to an increase in aggression.

Only applies to automatic gearboxes and arcade mode.

A higher value means the controller will downshift more quickly when increasing throttle.

aggressionSmoothingDown
name
number
type
0.15
default
How quickly the controller reacts to a decrease in aggression input.

Only applies to automatic gearboxes and arcade mode.

A higher value means the controller will upshift more quickly when decreasing throttle

useSmartAggressionCalculation
name
boolean
type
true
default
Activates intelligent aggression calculation based on vehicle speed, and throttle and brake inputs.
Disable for to simulate mechanical or older electronic gearboxes.
aggressionHoldOffThrottleDelay
name
number
type
2.25
default
If smart aggression calculation is used, the aggression factor will be held for the set amount of time (s) after the throttle is released, before dropping.
topSpeedLimit
name
number
type
-1
default
Speed limiter. (meters/second)
Won’t be active if smaller than 0.
topSpeedLimitReverse
name
number
type
-1
default
Speed limiter in reverse gear. (meters/second)
Won’t be active if smaller than 0.
wheelSlipUpThreshold
name
number
type
20000
default
Maximum total wheel sliding speed allowed before an upshift is blocked.

Only applies to automatic gearboxes and arcade mode.

Helps stop the car from shifting up immediately when spinning the tires.

wheelSlipDownThreshold
name
number
type
30000
default
Maximum total wheel sliding speed allowed before a downshift is blocked.

Only applies to automatic gearboxes and arcade mode.

Helps stop the car from downshifting immediately when the driven tires lock up from braking.

wheelSlipShiftUpSmoothingIn
name
number
type
10
default
Controls the shift blocker logic that prevents upshifts during excessive wheelspin
wheelSlipShiftUpSmoothingOut
name
number
type
20
default
Controls the shift blocker logic that prevents upshifts during excessive wheelspin
shiftLogicName
name
string
type
gearboxType
default
Override to change which shift logic controller will be used.
Mostly used with electric motors, as they aren’t used with a gearbox.
transmissionShiftDelay
name
number
type
0.2
default
Minimum time taken (s) to complete a shift from one gear to the next, not including clutching time.

Applies to manual gearboxes when using shiftUp/shiftDown buttons, and when shifting with a DCT gearbox when chosen gear is not preselected.

Does not apply to manual gearboxes when using an H-shifter.

transmissionGearChangeDelay
name
number
type
0.5
default
Minimum time (s) between 2 consecutive shifts.
Only applies to automatic gearboxes and arcade mode.
neutralSelectionDelay
name
number
type
0.5
default
Minimum time taken (s) to shift from a gear to neutral or from neutral to a gear.
Only applies to automatic gearboxes and arcade mode.

 Public Functions

Function name
Parameters
Description
Function name
shiftUp
Parameters
Description
Shifts the transmission up one gear.
Function name
shiftDown
Parameters
Description
Shifts the transmission down one gear.
Function name
shiftToGearIndex
Parameters
index
Description
Shifts the transmission to the selected gear.
Function name
cycleGearboxModes
Parameters
Description
Switches between arcade and realistic shifting modes.
Function name
setGearboxMode
Parameters
behavior
Description
Sets the gearbox mode to the defined option.
Function name
smartParkingBrake
Parameters
ivalue, filter
Description
Applies the parking brake and keeps it on if the user is actually parking the car.
Function name
setStarter
Parameters
enabled
Description
Activates the engine starter.
Function name
setEngineIgnition
Parameters
enabled
Description
Activates engine ignition.
Function name
setFreeze
Parameters
setFreeze
Description
Enables the transmission lock.
Function name
sendTorqueData
Parameters
Description
Sends torque and power related data to the UI.
Function name
vehicleActivated
Parameters
Description
Called upon active vehicle switch, executes code that upstes the UI.

 Public Properties

Name
Description
Name
throttle
Description
Throttle input
Name
brake
Description
Brake input
Name
clutchRatio
Description
Clutch input
Name
engineInfo
Description
Array containing a lot of engine related information for use by GUI elements
Name
fireEngineTemperature
Description
Exposes the temperature of an engine-like powertrain device to the fire simulation

 Electrics

Inputs

Name
Units/Values
Description
Name
brake
Units/Values
0 to 1
Description
Brake input percentage.
Name
brakelights
Units/Values
0 to 1
Description
Brake input percentage.
Name
clutch
Units/Values
0 to 1
Description
Clutch input percentage.
Name
clutchRatio
Units/Values
0 to 1
Description
Clutch input percentage.
Name
ignition
Units/Values
boolean
Description
Indicates if the ignition is currently on. Will stay on if you stall.
Name
throttle
Units/Values
0 to 1
Description
Throttle percentage. Affected by things like rev-matching and throttle cut in the transmission shift logic.

 Engine Information

Name
Units/Values
Description
Name
checkengine
Units/Values
boolean
Description
Indicates if the engine is disabled and can’t be turned on due to an issue.
Name
engineLoad
Units/Values
0 to 1
Description
Engine load percentage,based on current torque compared to the maximum amount of torque the engine can produce.
Name
engineThrottle
Units/Values
0 to 1
Description
Effective throttle level. Will be 0 if the engine is disabled.
Name
engineRunning
Units/Values
boolean
Description
Indicates if the engine is currently on.
Name
oiltemp
Units/Values
Celsius
Description
Temperature of the engine oil (used as the main engine temp on air cooled cars).
Name
radiatorFanSpin
Units/Values
0 to 360
Description
Spin function for the radiator fan,which activates when the radiator fan turns on. Used for props.
Name
rpm
Units/Values
RPM
Description
Engine rotation speed.
Name
running
Units/Values
boolean
Description
Indicates if the ignition is currently on. Will stay on if you stall.
Name
watertemp
Units/Values
Celsius
Description
Temperature of the radiator water (used as the main engine temp on water cooled cars).

 Fuel Information

Name
Units/Values
Description
Name
fuel
Units/Values
0 to 1
Description
Percentage of fuel left in the tank.
Name
fuelCapacity
Units/Values
Liters
Description
Fuel tank capacity.
Name
fuelVolume
Units/Values
Liters
Description
Volume of fuel left in the tank
Name
lowfuel
Units/Values
boolean
Description
Indicates that there is less than 10% fuel left in the tank.

 Transmission Information

Name
Units/Values
Description
Name
gear
Units/Values
string
Description
Currently selected gear. Same as gear index for manuals,other types will return the shifter position (PRDN) and add an S/M prefix before the gear number in manual modes.
Name
gear_A
Units/Values
0 to 1
Description
Indicates the current shifter position on automatic and DCT gearboxes.
Name
gearIndex
Units/Values
numbers
Description
Currently selected gear index. Reverse gears are negative,neutral is 0
Name
isShifting
Units/Values
boolean
Description
Indicates if the gearbox is currently mid-shift
Name
smoothShiftLogicAV
Units/Values
numbers
Description
The smoothed AV shift logic uses to determine arcade reverse switch and auto braking (among other things),exposed for the AI to use

 Example Usage 

    "controller": [
        ["fileName"],
        ["vehicleController", {}],
    ],
    
    "vehicleController": {
        "calculateOptimalLoadShiftPoints": true,
        "transmissionGearChangeDelay":2,
        "gearboxDecisionSmoothingUp":2,
        "gearboxDecisionSmoothingDown":2,
        "aggressionSmoothingUp":1,
        "aggressionSmoothingDown":0.5,
        "aggressionHoldOffThrottleDelay":1.75,
        "lowShiftDownRPM":1000,
        "lowShiftUpRPM":1800,
    },

Properties for a vehicle’s vehicleController are usually split between the various engine and transmission components of the vehicle.

Components which reduce the low-end torque might raise the clutchLaunch values, while components which raise the maximum rpm of the engine will raise the highShiftRPM values.

Last modified: January 24, 2025

On this page:

Any further questions?

Join our discord
Our documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.