Rollover Detection

Reference for gameplay_statisticModules_watchRollover, a statistic submodule that detects vehicle rollovers (flipping upside-down and back upright).

Module Exports (M)

Hooks (Event Handlers)

Internals

Detection Algorithm

The module tracks the vehicle's up-vector Z component through a state machine:

1. Upright - Vehicle's up-vector Z > 0.7 (roughly right-side-up). Records the upright timestamp
2. Roof - Vehicle's up-vector Z < -0.7 (upside-down) AND moving more sideways than forward (|dir·vel| < |right·vel|). Enters triggered state
3. Completion - When upright again after being on the roof, checks that roof was within 4s and upright was within 8s. If both pass → rollover counted
4. Timeout - If conditions aren't met within timeouts, the attempt resets

Constants

Metric Recorded

On successful rollover detection:

gameplay_statistic.metricAdd("vehicle/rollover", 1)

How It Works

1. The workload function is registered with gameplay_statistic.addSchedule() during module load
2. Each frame (round-robin), computes the vehicle's up, direction, velocity, and right vectors
3. Tracks transitions between upright → roof → upright within time windows
4. The sideways velocity check prevents false positives from driving on steep slopes
5. Vehicle resets and switches cancel any in-progress detection

Usage Example

-- This module is auto-loaded by gameplay_statistic
-- To check rollover count:
local rollData = gameplay_statistic.metricGet("vehicle/rollover", true)
if rollData then
  log("I", "", "Rollovers: " .. rollData.value)
end

See Also

• gameplay/statisticModules/watchJturn - J-Turn Detection - Related reference
• Gameplay Systems Guide - Guide