Crash Detection

Reference for gameplay_util_crashDetection, which tracks vehicle damage in real-time to detect crashes and individual impacts. Provides event hooks for crash start/end and impact start/end, with acceleration-based damage thresholds.

Module Exports (M)

Vehicle Tracking

Debug

Extension Lifecycle

Hooks Fired

Internals

Crash Settings

Detection Pipeline (per frame)

1. updateAccelData - Tracks two points (front/rear) on the vehicle, computing smoothed acceleration and jerk
2. logicDuringCrash - Increments crash timer if crashing or might-be-crashing
3. managedImpactAndDetectImpacts - Compares damage to acceleration-scaled threshold:
   • Below threshold → preImpactData (stored in case it becomes a real impact)
   • Above threshold → currentImpactData (confirmed impact)
4. checkIfPreImpactEnded - Clears pre-impact data if vehicle moved away
5. checkIfImpactEnded - Finalizes impact when vehicle distance exceeds groupImpactsDist or velocity drops
6. checkIfCrashEnded - Ends crash if stopCrashDelay (1.8s) elapsed since last impact or velocity too low

Impact Data Structure

{
  frameDamages = {
    {time, newDamage, newDamageSum, vehPos, speed, touchedVehIds, isAboveDamageThreshold},
    ...
  },
  touchedVehIds = {[id] = {name = "pickup"}},
  averagePos = vec3,
  totalDamage = number,
  impactSpeed = number,
  startingDamageState = table,  -- if enableImpactLocationData
  damageStateDiff = table       -- textual damage locations
}

Crash End Data

{
  vehId = number,
  impacts = { impact1, impact2, ... },
  sanitizedData = {
    touchedVehIds = {[id] = {name = "..."}},
    initialImpactPos = vec3,
    initialImpactSpeed = number,
  },
  totalDamage = number,
}

How It Works

The system uses a dynamic threshold that scales with jerk (rate of acceleration change). High jerk → lower damage threshold → more sensitive impact detection. This prevents road bumps from triggering false crashes while still catching real collisions.

Impacts are grouped spatially - if the vehicle stays within groupImpactsDist of the last frame damage, it's part of the same impact. Multiple impacts form a crash, which ends after 1.8s of no new impacts.

Usage Example

-- Start tracking player vehicle
local vehId = be:getPlayerVehicleID(0)
gameplay_util_crashDetection.addTrackedVehicleById(vehId, {
  maxDamage = 3000,
  enableImpactLocationData = true,
}, "myMod")

-- Listen for crash events
local function onVehicleCrashEnded(data)
  log("I", "", string.format("Crash! %d damage, %d impacts", data.totalDamage, #data.impacts))
end

-- Check if crashing right now
if gameplay_util_crashDetection.isVehCrashing(vehId) then
  -- vehicle is mid-crash
end

See Also

• gameplay/util/damageAssessment - Vehicle Damage Location Assessment - Related reference
• gameplay/util/groundContact - Ground Contact Detection - Related reference
• gameplay/util/sortedList - Sorted Object List Container - Related reference
• Gameplay Systems Guide - Guide