Interaction Maps (*.interaction.json)

Interaction maps define vehicle interaction actions in files ending with:

*.interaction.json

They use the same action-code format as input_actions.json, but they are primarily used by vehicle interactive triggers, especially triggers2 and triggerEventLinks2.

Common uses include:

• door, hood, trunk, hatch, and tailgate handles
• trailer feet and fifth wheel controls
• upfit levers
• police equipment controls
• hydraulic controls
• winches, latches, locks, and other clickable vehicle features

File location

Interaction maps are stored in vehicle folders:

vehicles/<vehicleName>/*.interaction.json

Examples:

vehicles/cannon/cannon_default.interaction.json
vehicles/us_semi/us_semi_default.interaction.json
vehicles/common/common_default.interaction.json

There can be multiple interaction map files per vehicle.

The common vehicle folder can define shared actions that other vehicles can reference.

Basic structure

{
  "fileversion": 2,
  "actions": {
    "tailgate": {
      "order": 1005.1,
      "onDown": "controller.getControllerSafe('tailgateCoupler').toggleGroup()",
      "title": "vehicle.interaction.tailgate.toggle.title",
      "desc": "vehicle.interaction.tailgate.toggle.desc"
    }
  }
}

The actions object contains the same kind of action entries used by input_actions.json.

Top-level fields

Action fields

Each entry inside actions is an input action.

Common fields:

For the full action-code model, see Writing Action Code .

Action code

Interaction actions usually run in vehicle Lua.

Example toggle:

"door_FR": {
  "order": 1000.4,
  "onDown": "controller.getControllerSafe('door_FR_coupler').toggleGroup()",
  "title": "vehicle.interaction.doors.FR.toggle.title",
  "desc": "vehicle.interaction.doors.FR.toggle.desc"
}

Example analog / held action:

"lift": {
  "order": 1.2,
  "onChange": "custom_input.liftBarrel(VALUE)",
  "title": "ui.inputActions.cannon.lift.title",
  "desc": "ui.inputActions.cannon.lift.description",
  "isCentered": true
}

VALUE is replaced by the current input value before the code runs.

Use:

• onDown for toggles and one-shot actions.
• onChange for levers, sliders, analog inputs, and held controls.
• onUp for release behavior.

Relationship with triggers2

triggers2 defines clickable trigger volumes on a vehicle.

triggerEventLinks2 connects those trigger volumes to input actions.

Example:

"triggerEventLinks2": [
  ["triggerId:triggers2", "triggerInput", "inputAction"],
  ["door_R", "action0", "door_FR"]
]

This means:

Common triggerInput values:

inputAction usually points to an action in a *.interaction.json file.

Common actions

The common interaction file:

vehicles/common/common_default.interaction.json

defines many shared actions, such as door, hood, trunk, latch, lightbar, coupling, trailer, hydraulic, and container actions.

Vehicle parts can reference these actions from triggerEventLinks2.

When a common: prefix is used in a trigger link, the action is resolved from the common action map / common action set rather than only the current vehicle’s interaction map.

Example:

["door_R", "action0", "common:door_FR"]

Use common actions when the behavior is already provided and matches your part.

actionsEnabled

Interaction actions can be hidden or disabled from the UI until the vehicle part declares that they are available.

Use the JBeam actionsEnabled section:

"actionsEnabled": [
  ["id"],
  ["tiltUp"],
  ["tiltDown"],
  ["extend"],
  ["retract"]
]

This is useful for vehicles with many optional parts. Only actions for installed parts should be shown to the player.

Interaction map vs input_actions.json

For new clickable vehicle interactions, prefer:

triggers2 + triggerEventLinks2 + *.interaction.json

Use input_actions*.json for normal vehicle controls that do not belong to a clickable interaction map.

Legacy triggers and events

Older trigger setups use:

triggers
triggerEventLinks
events

In that system, events defines the action code directly inside the JBeam part.

Newer triggers2 setups use:

triggers2
triggerEventLinks2
*.interaction.json
actionsEnabled

The action code moves out of JBeam events and into an interaction map.

Default bindings

Interaction actions can have normal input bindings.

Default binding files live in:

vehicles/<vehicleName>/inputmaps/

Example:

vehicles/cannon/inputmaps/keyboard.json
vehicles/cannon/inputmaps/xidevice.json

Use the Controls menu to create bindings, then move/rename the generated .diff files into the vehicle’s inputmaps folder as default .json files when appropriate.

Use a unique suffix for mod-provided binding files:

vehicles/my_vehicle/inputmaps/keyboard_my_mod.json

Minimal example

Interaction map:

{
  "fileversion": 2,
  "actions": {
    "open_toolbox": {
      "order": 10,
      "onDown": "controller.getControllerSafe('toolboxLatch').toggleGroup()",
      "title": "vehicle.interaction.toolbox.open.title",
      "desc": "vehicle.interaction.toolbox.open.desc"
    }
  }
}

JBeam link:

"actionsEnabled": [
  ["id"],
  ["open_toolbox"]
],

"triggerEventLinks2": [
  ["triggerId:triggers2", "triggerInput", "inputAction"],
  ["toolbox_handle", "action0", "open_toolbox"]
]

The toolbox_handle trigger calls the open_toolbox action from the interaction map.

Tool notes

For tools that generate or modify interactions:

• Preserve fileversion.
• Preserve action ids referenced by triggerEventLinks2 and actionsEnabled.
• Preserve unknown action fields.
• Keep action ids unique within the vehicle.
• Do not move action code back into legacy events unless intentionally converting to the old trigger system.
• Validate every inputAction reference in triggerEventLinks2.
• Validate every actionsEnabled entry against available actions.

Common issues

Clickable trigger does nothing

Possible causes:

• triggerEventLinks2.inputAction does not match an action id.
• The interaction map file is missing or invalid.
• Action code calls a missing controller.
• The trigger uses the wrong triggerInput.

Binding legend does not show the action

Possible causes:

• Action is not listed in actionsEnabled.
• The action is not usable for the currently installed part.
• No binding exists for the action.

Action works from keyboard but not from clicking the trigger

Possible causes:

• Keyboard binding points to the action, but triggerEventLinks2 points to a different id.
• Trigger volume is misplaced.
• Trigger action input (action0, action1, action2) is wrong.

Validation criteria

• Interaction JSON parses correctly.
• Every triggerEventLinks2 action resolves.
• Every displayed interaction is listed in actionsEnabled.
• Clickable triggers activate the intended action.
• Keyboard/gamepad bindings still work if default inputmaps are provided.
• Missing optional parts do not show irrelevant actions.

See also: Actions , Bindings , Vehicle-Specific Bindings , Triggers2 .