Actions

Overview

An Action is each of the in-game activities that can take place after the player has manipulated a Control.

E.g. steer left, change camera, toggle menu.

Actions are defined in one or more .json files.

It is possible to provide new extra actions through mods. Just remember that, if you don’t also provide some bindings, then the users of your mod will need to manually configure his controllers.

There are two basic kinds of actions: Regular actions and Vehicle-specific actions:

Regular actions

Regular actions are those that can take place regardless of which vehicle is currently used.

They can therefore be available for use even while in the main menu, before entering any level or spawning any vehicle.

BeamNG.drive comes with many predefined regular actions. These are defined in:

lua/ge/input_actions.json

Mods can bundle additional regular actions. To do so, they must provide one or more additional json files following this naming convention:

lua/ge/input_actions*.json

For example:

lua/ge/input_actions_explosions_mod.json
lua/ge/input_actions_advanced_menus.json

Any actions defined there will be available to end-users in the Options > Controls menu, mixed in with the default actions provided by BeamNG.drive..

Note: while it is possible to override the default input_actions.json file with a customized one, this means the mod author will need to constantly update his modified file each time a BeamNG.drive update comes out with new actions (or modified actions, or removed ones). It is therefore strongly advised against.

Vehicle-specific actions

Vehicle-specific actions are those that can only be triggered while driving an specific vehicle. If you switch to a different kind of vehicle, they’ll be replaced by the actions of the new vehicle.

Some of BeamNG.drive official vehicles come with a few predefined vehicle-specific actions. For example, the Small Cannon provides the ability to open fire with your controller. These vehicle-specific actions are defined in:

vehicles/vehicle_directory_name/input_actions.json

Similarly to Regular actions, mods can bundle additional vehicle-specific actions too. The mod-provided files must follow this naming convention:

vehicles/vehicle_directory_name/input_actions*.json

For example:

vehicles/hatch/input_actions_hydraulic_suspension.json
vehicles/pickup/input_actions_winch_cable.json

All of these actions will be typically found in the “Vehicle-specific” category of the Options > Controls menu.

Note: Again, it is necessary to use unique file names for your vehicle-specific actions, to make sure your actions are not overriden by other mods using the same file names.

Action files format

Action 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:

{
    "an_action"     : {"order":1,  "title":"Do Something", ...},
    "another_action": {"order":2,  "title":"Do Something Else", ...},
    "third_action"  : {"order":10, "title":"Do More Things", ...},
    //...
}
Each line has two parts:
  • The first string on each line is the action name. E.g. "an_action".
  • The rest of the line contains the parameters of the action. E.g. "order", "title", "ctx", and more.

Here’s more information about them:

Action names

Action names must be unique, otherwise they may get overriden by other mods using the same action names. Specifically:

The easiest way to ensure the action names are unique, is to use a unique prefix. For example:

{
    "extra-menus-mod_an_action"     : { ... },
    "extra-menus-mod_another_action": { ... },
    "extra-menus-mod_third_action"  : { ... },
    //...
}

Action parameters

The parameters of an action controls what the action actually does and how it’s displayed in the menus. Here’s a table with all details:

Note: Vehicle-specific actions have some particularities, which are also described below

Name Type Optional Default Value Description
title ../../_images/string.png ../../_images/nok.png n/a Very short name of the action, will be displayed in various game menues
desc ../../_images/string.png ../../_images/nok.png n/a Full description, may be displayed as tool-tip, should be about one sentence long.
isBasic ../../_images/bool.png ../../_images/ok.png true Whether it is shown by default in the Controls > Binding menu (true) or user needs to check “List advanced bindings too” (false)
cat (regular actions) ../../_images/string.png ../../_images/nok.png n/a See Action categories
cat (vehicle-specific actions) ../../_images/string.png ../../_images/ok.png “vehicle_specific” See Action categories
order ../../_images/int.png ../../_images/nok.png n/a Can influence in which order actions are displayed on various UI menus, with 1 coming first, and larger values (2, 3…) coming later.
isCentered ../../_images/bool.png ../../_images/ok.png false 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).
actionMap (regular actions) ../../_images/string.png ../../_images/ok.png “Normal”

Determines which Action Map the action will be assigned into. In order of priority, the most common action maps are:

  • “Global” - will work even when the UI has focus (useful for very few actions, such as ALT-F4 binding)
  • “Menu” - assigned automatically when “cat” (category) is “Menu”
  • “Normal” - default map. This, and the action maps below. won’t get triggered if a Menu action is triggered with the same control
  • “VehicleCommon” - actions that may apply to numerous kinds of vehicles. Assigned automatically IF this action context is “vlua”
  • “VehicleSpecific” - actions that only apply to the currently active vehicle. Assigned automatically IF this is a vehicle-specific actions .json file

Custom names can be specified, and the corresponding action map will be automatically created. This can be useful for mods that want to quickly de/activate certain set of actions, etc.

actionMap (vehicle-specific actions) ../../_images/string.png ../../_images/ok.png “VehicleSpecific” Determines which action map the action will be assigned into. In order of priority, the most common action maps are:
ctx (regular actions) ../../_images/string.png ../../_images/nok.png n/a

Defines how the code defined in onChange/onUp/onDown/onRelative will be executed:

  • “ui” for user interface - javascript (async)
  • “vlua” for active vehicle - lua (async)
  • “bvlua” for all vehicles - lua (async)
  • “elua” for game engine - lua (async)
  • “tlua” for game engine - lua (sync)
  • “ts” for game engine - torquescript (sync)
ctx (vehicle-specific actions) ../../_images/string.png ../../_images/ok.png “vlua” See the description above

onChange

onDown

onUp

onRelative

../../_images/string.png ../../_images/nok.png n/a

Specifies which source code will be executed when the action is triggered. The code execution context is defined in the ctx parameter of the current action

At least one of them must be defined. They are triggered like this:

  • onChange: runs when the controller position changes. Supports: keys/buttons and axes
  • onDown: runs when a key/button is pressed down. Supports: keys/buttons
  • onUp: runs when a key/button is lifted up. Supports: keys/buttons
  • onRelative: runs when holding the right mouse button and moving the mouse (don’t use unless you know what you’re doing)

Action categories

The category of an action is a mandatory parameter with only cosmetic effects.

It will influence where the action may be displayed in various in-game menus (such as the Options > Controls hierarchy of actions).

To see a list of available categories, please refer to the following file: lua/ge/input_categories.lua