BeamNGTrigger

BeamNGTrigger is a gameplay trigger volume. It calls Lua when vehicles or other triggerable objects enter, leave, overlap, or are contained by the trigger volume.

It is commonly used for bus stops, speed traps, red-light cameras, garage/dealership logic, mission helpers, and other scripted level interactions.

Basic example

{
  "class": "BeamNGTrigger",
  "name": "speedTrapTrigger_01",
  "__parent": "speedCamera_001",
  "position": [100, 200, 5],
  "rotationMatrix": [1, 0, 0, 0, 1, 0, 0, 0, 1],
  "scale": [10, 8, 5],
  "luaFunction": "onBeamNGTrigger",
  "TriggerType": "Box",
  "TriggerMode": "Center",
  "TriggerTestType": "Race corners"
}

Important fields

Field	Type	Description
`class`	string	Must be `"BeamNGTrigger"`.
`name`	string	Scene object name.
`__parent`	string	Parent group.
`position`	array[3]	Trigger center position.
`rotationMatrix`	array[9]	Trigger orientation.
`scale`	array[3]	Trigger volume size.
`TriggerType`	enum/string	Trigger shape, usually `"Box"` or `"Sphere"`.
`TriggerMode`	enum/string	Trigger condition: `"Center"`, `"Contains"`, or `"Overlaps"`.
`TriggerTestType`	enum/string	Test type, commonly `"Race corners"` or `"Bounding box"`.
`luaFunction`	string	Lua function to call. Empty falls back to `onBeamNGTrigger`.
`tickPeriod`	integer	Tick period in milliseconds when ticking is enabled.
`ticking`	bool	Enables repeated trigger tick calls.
`debug`	bool	Draws trigger debug visualization.
`debugInEditor`	bool	Draws trigger debug visualization in the editor.
`triggerColor`	color	Debug draw color.
`cameraOnEnter`	string	Camera to switch to on enter.
`defaultOnLeave`	bool	Returns to normal camera on exit.

Trigger modes

Value	Meaning
`Center`	Tests whether the object center is inside the trigger.
`Contains`	Tests whether the object is fully contained.
`Overlaps`	Tests whether the object overlaps the trigger volume.

Use Center for most gameplay volumes. Use Overlaps or Contains when the size of the vehicle or object should matter.

Lua function

luaFunction selects the Lua callback:

"luaFunction": "onBeamNGTrigger"

If empty, the trigger uses the default callback name:

onBeamNGTrigger

Level scripts and gameplay systems can also read extra dynamic fields saved on the object, such as speed trap or bus-stop metadata.

Fields such as speedLimit, speedTrapType, trafficSignalId, or custom bus-stop data are dynamic fields used by gameplay scripts. Preserve them even if they are not core BeamNGTrigger fields.

Tool notes

For tools that generate triggers:

Preserve dynamic fields used by gameplay scripts.
Keep trigger names stable if scripts or data files reference them.
Use scale to define the trigger volume.
Keep luaFunction consistent with the gameplay system that consumes the trigger.
Use debugInEditor while authoring, then disable it if the trigger should not draw normally.

Common issues

Trigger does nothing because luaFunction is wrong or missing.
Trigger fires too early or too late because the scale or mode is wrong.
Vehicle does not trigger because the test type does not match the intended object bounds.
Generated triggers lose custom gameplay fields.

Validation criteria

Trigger volume covers the intended gameplay area.
Lua callback exists and receives the expected trigger events.
Dynamic fields required by the owning gameplay system are present.
Debug draw confirms placement and size in the editor.

BeamNGTrigger

Basic example

Important fields

Trigger modes

Lua function

Tool notes

Common issues

Validation criteria

On this page:

Any further questions?