Vehicle-Specific Bindings

It can be very useful to use a working example as reference, such as the official cannon vehicle.

Overview

You may want to first read the Input Introduction .

Starting on version 0.5, BeamNG.drive supports vehicle-specific bindings . These are special bindings that only apply to certain vehicle. For example, a binding to lift the arm of a crane; or a binding to shoot the ball in a cannon.

Vehicle specific bindings can be customized by end users in the ControlsBindings menu, just like any other binding (without editing any file at all).

Defining Vehicle-Specific Actions

In order words, the file name can be input_actions.json, but can also have a suffix, such as: input_actions_my_custom_suffix.json

Action File Format

The specified action names (“action_name_a”, etc) must be unique within the current vehicle. If a different vehicle uses the exact same action name, they won’t interfere with each other, since they belong to different vehicles.

These are the possible action arguments:

Name
Mandatory
Type
Default Value
Description
Name
title
Mandatory
Yes
Type
string
Default Value
n/a
Description
Very short name of the action, will be displayed in various game menues
Name
desc
Mandatory
Yes
Type
string
Default Value
n/a
Description
Full description, may be displayed as tool-tip, should be about one sentence long.
Name
order
Mandatory
Yes
Type
number
Default Value
n/a
Description
Can influence in which order actions are displayed on UI menues, with 1 coming first, and larger values (2, 3…) coming later.
Name
isBasic
Mandatory
No
Type
boolean
Default Value
true
Description
Whether it is shown by default in the Controls > Binding menu (true) or user needs to check “List advanced bindings too” (false)
Name
isCentered
Mandatory
No
Type
boolean
Default Value
false
Description
If false, the action will produce values in the range 0 to 1 (for example, it can be used for a brake pedal or handbrake). If true, generated values will be in the range of -1 to +1 (for example, it can be used for the steering, or for changing the camera height up and down).
Name
onChange
Mandatory
No *
Type
string
Default Value
Description
Source code that will be executed when the input value changes (when a key is pressed, lifted, or each time an axis is slightly moved).
Name
onDown
Mandatory
No *
Type
string
Default Value
Description
Source code that will be executed when a button or a key have been pressed down**.
Name
onUp
Mandatory
No *
Type
string
Default Value
Description
Source code that will be executed when a button or a key have been lifted up**.
Name
ctx
Mandatory
No
Type
string
Default Value
“vlua”
Description

Where the code defined above will be run:

  • “ui” for javascript code
  • “ts” for torquescript
  • “tlua” for game engine lua
  • “vlua” for vehicle lua.

Footnotes:

* onUp and onDown code cannot be triggered by axes, only by buttons and keyboard keys. Using onChange is recommended, if possible.

** At least one of these must be defined. More on this later, don’t worry about what to use just now.

To add a new action, insert a new line, like this:

{
"shoot": {"order":1, "onChange":"electrics.values.shoot = VALUE", "title":"Shoot ball", "desc":"Shoots the cannon ball. Cannon will need to be reset to fire again" },
}

Modding Vehicle-Specific Actions

If you are modifying an existing vehicle that already contains vehicle-specific actions , then starting at version 0.7.0.0 you can add extra actions (rather than simply replacing vehicles/my_vehicle/input_actions.json).

To do that, create new files named input_actions*.json in that same directory. For example: input_actions_my_mod.json.

All json files matching that filaname pattern will be read, allowing you to add any new actions you may need, spanning as many files as you want.

Defining Some Default Bindings

Now that we have the vehicle-specific input_actions.json file, you can create new bindings through the usual ControlsBindings menu. This will generate inputmap files in the settings/inputmaps/your_vehicle_name/ directory.

When you are happy with your set of default bindings, you can rename the files from *.diff to *.json, and move them inside vehicle/your_vehicle_name/inputmaps/.

Starting at BeamNG.drive v0.25, you also have the possibility of adding an arbitrary suffix to the file name, in order to avoid collisions with game-provided inputmap files. For example, if you are modding the pickup with additional bindings, it is a good practice of picking a custom suffix to avoid interfering with inputmaps from other mods or from defaults. For example, instead of vehicles/pickup/inputmaps/keyboard.json, you should use vehicles/pickup/inputmaps/keyboard_MyCoolMod.json. You can pick any suffix you want, just pick a name unique enough to not be used by other mods already.

Vehicle-specific bindings will automatically appear on the top-right of the window after you load a level. This way, users can easily know how to use your vehicle specific bindings.

After the initial release of your mod, for example in your second version of the mod, you can add more actions if you wish, and also add more default bindings. BeamNG.drive will make sure these new default bindings are available to all users, even if they have customized the bindings in the past.

Important: if you do not provide some default binding files, the user won’t be able to use your vehicle-specific functionality until he manually puts the effort to create the necessary bindings.

Please, always provide default bindings, users will be thankful. Well, or at least they won’t be so confused about how to use your mod.

Making the Vehicle Actually Do Stuff

So far, we have defined some default bindings, and added some lines to the vehicle input_actions.json file, but all of the onChange/onUp/onDown arguments are empty, so we will fix that now.

Simple Case

The simplest case is using a thruster or a hydro. These elements can easily react to values travelling through the electric bus of the vehicle, so we will just write some LUA code that writes to this electrics bus.

Let’s learn by example: If you have this inside input_actions.json:

"onChange":"electrics.values.shoot = VALUE"

Then you can make a hydro or a thruster react to it, like this:

  • Inside the Hydros section of a .jbeam file:
"inputSource":"shoot"
  • Or inside the Thrusters section of a .jbeam file:
"control":"shoot"

Check the cannon vehicle for a working example of a thruster.

Advanced Case

You can have complete control over what happens, if you are willing to write custom LUA code.

Action LUA Code

All of the onChange/onUp/onDown lua code can include some special symbols, that will be automatically replaced by the bindings system. You can write them in any order, any number of times. They are:

  • VALUE: will replaced with 1 in onDown, 0 in onUp, float values from 0 to 1 in onChange when isCentered argument is false, and float values from -1 to 1 in onChange when isCentered argument is true.
  • FILTERTYPE: corresponds to the “Filter” option in the binding editor menu, and will be replaced by 0 for Key filter, 1 for Pad filter, and 2 for Direct filter.
  • PLAYER: if you are using an action argument ctx different than the default "vlua" (such as "ts"), this may be useful to direct actions at the vehicle of certain player when playing in multiseat mode. If the binding was triggered by the first player, it will be replaced by 0, second player with 1, third with 2, etc.

Basic example:

"onChange":"input.event('throttle', VALUE, FILTERTYPE)"

Advanced fictional example, which makes no sense at all (it’s only intended to show you the theoretical possibilities):

"onChange":"hydros.my_function(false, true, 1337, 'sample string',  VALUE,  -1 * VALUE / 5,  math.max(1, FILTERTYPE),  FILTERTYPE == 0)"
Custom LUA Files

If your needs are complex enough, you may want to bundle some custom .lua file in your vehicle mod.

These files can include some functions that will be called back by the game engine:

M.onInit()
M.onReset()
M.updateGFX(dt)

They can also export any functions you want to be used by your custom input_actions.json code. For example a file named vehicles/my_vehicle/lua/custom_lua_file.lua:

M.enableWindshieldWipers(booleanValue)
M.setTurboLimit(psi)

The action’s code can then call those exported functions, for example:

onChange: "custom_lua_file.setTurboLimit(30 * VALUE)"

Working Example

Including a working example would involve attaching various files, that may end up out of date. It is better to take the existing cannon vehicle, which is bundled with BeamNG.drive, tested on each relase and is pretty simple, so serves as a very good starting point.

You will find this vehicle in SteamApps\common\BeamNG.drive\content\vehicles\cannon.zip, unzip to a temporary directory and take a look at the various files and directories mentioned throughout this guide.

Last modified: June 9, 2022

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.