Vehicle-Specific Bindings

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

Overview

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 Controls → Bindings 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:

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 Controls → Bindings 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.

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.