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/extensions/core/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/extensions/core/input/actions/*.json

For example:

lua/ge/extensions/core/input/actions/explosions_mod.json
lua/ge/extensions/core/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.

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.

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 overridden by other mods using the same action names. Specifically:

• Regular action names must be different from all other regular actions names.
• Vehicle-specific action names must be unique within the current vehicle.

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:

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/extensions/core/input/categories.lua