Bindings

Overview

Sometimes also called input mapping or inputmap.

Bindings define which controls will trigger each action .

For example: the throttle binding binds the control with the "accelerate" action.

End-users can customize their bindings in the OptionsControls menu.

  • A single control can be bound to several actions (the action maps order will determine which will be triggered).
  • A single action can be triggered by several controls.

File Locations

Factory Bindings

Factory bindings are those bundled by default.

When you use the OptionsControlsRESET ALL button, they are returned to the factory bindings state.

They are stored in the game install folder, in two possible locations:

  • Regular bindings: settings/inputmaps/*.json
  • Vehicle bindings: vehicles/vehicle_directory_name/inputmaps/*.json

Note: some of those may have been packed inside gameengine.zip, to reduce download sizes and storage usage.

User Bindings

When end-users customize their bindings, these differences are stored in the User folder :

  • Regular bindings: settings/inputmaps/*.diff
  • Vehicle bindings: settings/inputmaps/vehicle_directory_name/*.diff

They contain only what has changed compared to the defaults (which bindings got added, which got removed or replaced, etc). If one were to remove all diff files, the game would be back at the defaults.

File Names

Binding filenames start with an identifier, optionally followed by a suffix, and ending with an extension: identifierSuffix.extension.

  • Identifier: determines which controller they belong to.
  • Suffix: starting from BeamNG.drive 0.25, a suffix can be included or omitted, using any arbitrary text you want. This allows mods to provide their own default bindings.
  • Extension: as explained above, it can be diff or json.

For example: keyboard.json, keyboardGiantExcavatorMod.json, c29b046d.diff, etc.

For the identifier field, there’s two possibilities:

Identifier: device type

The game can recognize any of the following strings:

  • ‘mouse’
  • ‘keyboard’
  • ‘xidevice’ - a controller in xbox mode (such as an xbox gamepad, or a pc+xbox steering wheel that has been set to use xbox mode instead of pc mode)
  • ‘joystick’ - joysticks (non-xbox)
  • ‘wheel’ - steering wheels (non-xbox)
  • ‘gamepad’ - gamepads (non-xbox)
  • ‘vinput’ - virtual input, which is a system to channel inputs from arbitrary origins, such as another program in the computer, or our android/ios apps for remote control

Identifier: USB Pidvid

The game can recognize USB identifiers. These will look like 8 hexadecimal characters, such as 1357acef. They represent 4 vendor ID characters + 4 product ID characters.

Important: as a mod creator or end user, you do not need to figure out pidvid names manually - this is handled automatically by BeamNG.drive when you create or modify bindings from the OptionsControls menu.

The product ID and vendor ID are codes that have been assigned to specific hardware manufacturers, for the USB products they sell. Using a pidvid allows to tailor bindings to one specific device model (e.g. “apply to all Logitech G27 devices”), rather than a generic kind of controller (e.g. “apply to any wheel”).

For example, the pidvid name c29b046d corresponds to a Logitech device (vendor ID 046d), and their G27 model (product ID c29b).

Mice, keyboards and xbox controllers don’t support pidvid identifiers in binding filenames, only “device type” identifiers.

File Format

Important: as a mod creator or end user, you do not need to know about the file format - You should not be hand-crafting these files manually, instead you should use the Options > Controls menu to define the factory bindings for your mod.

Binding files mostly follow the json format . They must start with { and end with }. Here’s a sample of how the overall structure has to look like:

keyboard.json:
{
  "bindings": [
    {"action": "menu_select", "control": "numpad9"},
    {"action": "menu_back", "control" : "numpad7"},
    // ...
  ]
}

As you can see, it’s a simple list of actioncontrol relations.

In some cases, there’s extra information for each binding (such as binding linearity, force feedback parameters, etc). We won’t go into detail about these.

If the file is a .diff file with customized user bindings , they may contain an additional "removed" list inside, like this:

keyboard.diff:
{
  "bindings": [
    {"action": "menu_select", "control": "numpad3"},
    {"action": "accelerate", "control": "up", "filterType": "1"},
  ],
  "removed": [
    {"action": "menu_back", "control" : "numpad7"},
  ]
}

The "bindings" inside a .diff file may overwrite a factory binding with a different control (menu_select in the example above) or different/new parameters (accelerate in the example above).

In addition to "bindings" and "removed", there may be other fields in these files, such as "guid", "name", etc. You don’t need to worry about these.

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.