Freeroam Special Triggers

Event-driven system for toggling scene objects (statics, lights) when vehicles enter/exit BeamNGTriggers or site zones. Supports delayed activation, random ordering, nested SimGroups, and Lua command

Event-driven system for toggling scene objects (statics, lights) when vehicles enter/exit BeamNGTriggers or site zones. Supports delayed activation, random ordering, nested SimGroups, and Lua command execution.

State Fields

Field	Type	Default	Description
`M.active`	`boolean`	`true`	Global enable/disable flag for all trigger processing
`M.debugMode`	`boolean`	`false`	Enables debug logging for trigger events

Public API

Function	Signature	Returns	Description
`M.loadTriggers`	`(filePath?)`	`nil`	Loads triggers from JSON; defaults to level's `triggers.json`
`M.setupTriggers`	`(data)`	`nil`	Programmatically sets up triggers from a data table
`M.addTrigger`	`(key, data)`	`nil`	Adds a single trigger definition
`M.removeTrigger`	`(key, useOrigState?)`	`nil`	Removes a trigger; optionally restores original states
`M.getTriggers`	`()`	`table`	Returns all trigger definitions
`M.setTriggerActive`	`(tName, active, instant?)`	`nil`	Manually activates/deactivates a trigger
`M.reset`	`(useOrigState?)`	`nil`	Clears all triggers
`M.onClientStartMission`	`()`	`nil`	Auto-loads level triggers on mission start
`M.onBeamNGTrigger`	`(data)`	`nil`	Handles BeamNGTrigger enter/exit events for vehicle detection
`M.onVehicleSwitched`	`(oldId, newId)`	-
`M.onVehicleDestroyed`	`(vehId)`	-
`M.onVehicleActiveChanged`	`(vehId, active)`	-
`M.onClientEndMission`	`()`	-
`M.onUpdate`	`(dt, dtSim)`	-
`M.onSerialize`	`()`	-
`M.onDeserialized`	`(data)`	-

Trigger Definition

{
  type = "trigger",          -- "trigger" or "zone"
  triggers = {"t1", "t2"},   -- optional grouped trigger names
  subjectType = "player",    -- "player", "notPlayer", "all"
  subjectIds = {id1, id2},   -- optional specific vehicle IDs
  enterCommand = "lua code", -- GE Lua on enter
  exitCommand = "lua code",  -- GE Lua on exit
  enterVehCommand = "cmd",   -- Vehicle Lua on enter
  exitVehCommand = "cmd",    -- Vehicle Lua on exit
  objects = {
    ["SimGroupName"] = {
      enterDelay = 0.5,
      exitDelay = 1.0,
      enterRandomMin = 0.1,
      enterRandomMax = 0.3,
      randomOrder = true
    }
  }
}

How It Works

Loading: Auto-loads triggers.json from level root on onClientStartMission
Detection: BeamNGTrigger events fire onBeamNGTrigger; zone detection runs on a 0.25s tick
State Change: When a valid vehicle enters/exits, toggles linked objects from their original state
Delayed Toggle: Objects can have enter/exit delays; SimGroup children toggle sequentially with random timing
Nested Groups: If a SimGroup contains only child SimGroups, all children are processed in parallel at each index step
Original State: First access stores each object's original hidden/enabled state for proper reset

Object Types

TSStatic / other: Toggles hidden field
PointLight / SpotLight: Toggles isEnabled field

Subject Filtering

player: Only player vehicle triggers
notPlayer: Only non-player vehicles
all: Any vehicle
subjectIds: Specific vehicle ID whitelist

Usage Examples

-- Load level triggers
freeroam_specialTriggers.loadTriggers()

-- Add a custom trigger
freeroam_specialTriggers.addTrigger("myTrigger", {
  subjectType = "player",
  enterCommand = "print('entered!')",
  objects = { ["lightGroup"] = { enterDelay = 0.5 } }
})

-- Manually toggle
freeroam_specialTriggers.setTriggerActive("myTrigger", true, true)

Notes

Grouped triggers (via triggers array) create aliases; exit only fires when all grouped triggers are inactive
Multiple vehicles tracked independently per trigger
Zone-based triggers require gameplay_city sites data
M.active and M.debugMode flags control global behavior

State Fields

Field	Type	Default	Description
`M.active`	`boolean`	`true`	Global enable/disable flag for all trigger processing
`M.debugMode`	`boolean`	`false`	Enables debug logging for trigger events

Public API

Function	Signature	Returns	Description
`M.loadTriggers`	`(filePath?)`	`nil`	Loads triggers from JSON; defaults to level's `triggers.json`
`M.setupTriggers`	`(data)`	`nil`	Programmatically sets up triggers from a data table
`M.addTrigger`	`(key, data)`	`nil`	Adds a single trigger definition
`M.removeTrigger`	`(key, useOrigState?)`	`nil`	Removes a trigger; optionally restores original states
`M.getTriggers`	`()`	`table`	Returns all trigger definitions
`M.setTriggerActive`	`(tName, active, instant?)`	`nil`	Manually activates/deactivates a trigger
`M.reset`	`(useOrigState?)`	`nil`	Clears all triggers
`M.onClientStartMission`	`()`	`nil`	Auto-loads level triggers on mission start
`M.onBeamNGTrigger`	`(data)`	`nil`	Handles BeamNGTrigger enter/exit events for vehicle detection
`M.onVehicleSwitched`	`(oldId, newId)`	-
`M.onVehicleDestroyed`	`(vehId)`	-
`M.onVehicleActiveChanged`	`(vehId, active)`	-
`M.onClientEndMission`	`()`	-
`M.onUpdate`	`(dt, dtSim)`	-
`M.onSerialize`	`()`	-
`M.onDeserialized`	`(data)`	-

Trigger Definition

{
  type = "trigger",          -- "trigger" or "zone"
  triggers = {"t1", "t2"},   -- optional grouped trigger names
  subjectType = "player",    -- "player", "notPlayer", "all"
  subjectIds = {id1, id2},   -- optional specific vehicle IDs
  enterCommand = "lua code", -- GE Lua on enter
  exitCommand = "lua code",  -- GE Lua on exit
  enterVehCommand = "cmd",   -- Vehicle Lua on enter
  exitVehCommand = "cmd",    -- Vehicle Lua on exit
  objects = {
    ["SimGroupName"] = {
      enterDelay = 0.5,
      exitDelay = 1.0,
      enterRandomMin = 0.1,
      enterRandomMax = 0.3,
      randomOrder = true
    }
  }
}

How It Works

Loading: Auto-loads triggers.json from level root on onClientStartMission
Detection: BeamNGTrigger events fire onBeamNGTrigger; zone detection runs on a 0.25s tick
State Change: When a valid vehicle enters/exits, toggles linked objects from their original state
Delayed Toggle: Objects can have enter/exit delays; SimGroup children toggle sequentially with random timing
Nested Groups: If a SimGroup contains only child SimGroups, all children are processed in parallel at each index step
Original State: First access stores each object's original hidden/enabled state for proper reset

Object Types

TSStatic / other: Toggles hidden field
PointLight / SpotLight: Toggles isEnabled field

Subject Filtering

player: Only player vehicle triggers
notPlayer: Only non-player vehicles
all: Any vehicle
subjectIds: Specific vehicle ID whitelist

Usage Examples

-- Load level triggers
freeroam_specialTriggers.loadTriggers()

-- Add a custom trigger
freeroam_specialTriggers.addTrigger("myTrigger", {
  subjectType = "player",
  enterCommand = "print('entered!')",
  objects = { ["lightGroup"] = { enterDelay = 0.5 } }
})

-- Manually toggle
freeroam_specialTriggers.setTriggerActive("myTrigger", true, true)

Notes

Grouped triggers (via triggers array) create aliases; exit only fires when all grouped triggers are inactive
Multiple vehicles tracked independently per trigger
Zone-based triggers require gameplay_city sites data
M.active and M.debugMode flags control global behavior

Freeroam Special Triggers

State Fields

Public API

Trigger Definition

How It Works

Object Types

Subject Filtering

Usage Examples

Notes

See Also

On this page

Freeroam Special Triggers

State Fields

Public API

Trigger Definition

How It Works

Object Types

Subject Filtering

Usage Examples

Notes

See Also

On this page