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 Options
→ Controls
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 Options
→ Controls
→ RESET 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
orjson
.
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 Options
→ Controls
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
).
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 action ↔ control 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.