Damage Assessment

Reference for gameplay_util_damageAssessment, which provides spatial damage analysis by dividing a vehicle's bounding box into a 3×3×3 grid (27 sections) and determining which body regions sustained damage.

Module Exports (M)

Core Functions

Debug

Extension Lifecycle

Internals

Section Grid

The vehicle's oriented bounding box (OOBB) is divided into 27 sections (3×3×3 grid) using non-uniform cell sizes. Outer cells use a cutDepth calculated from the median axis, creating thinner edge cells and a larger center.

Each section provides:

{
  sectionBeamDamage = number,     -- deformation/beam damage
  sectionCollisionDamage = number -- collision force damage
}

Named Damage Locations

Damage Severity Levels

Damage Score Algorithm

For each named location, computes:

1. totalDamage - Sum of cell damage differences (new vs old)
2. maxCellDamage - Highest single cell damage
3. averageCellDamage - Mean across location's cells
4. damageVariation - Normalized standard deviation (concentrated vs spread)
5. intensity - totalDamage / (maxCellDamage × cell count)
6. damageScore - intensity × totalDamage × averageCellDamage / 1,000,000

The location with the highest damageScore is reported as mostDamagedLocation.

How It Works

1. getSectionsDamageInfoRaw() queries per-section beam and collision damage from the engine
2. getTextualCollisionDamageLocations(data) compares old vs new section state
3. For each named location, sums the damage difference across its cells
4. Computes statistical metrics (variation, intensity) to determine the most likely impact zone
5. Used by crashDetection to annotate impacts with spatial damage info

Usage Example

-- Get current damage sections
local sections = gameplay_util_damageAssessment.getSectionsDamageInfoRaw(vehId)

-- Get textual damage after a crash
local result = gameplay_util_damageAssessment.getTextualCollisionDamageLocations({
  vehId = vehId,
  oldSectionsDamageRaw = savedSections  -- from before crash
})
log("I", "", "Most damaged: " .. (result.mostDamagedLocation or "none"))

-- Quick severity check
local level = gameplay_util_damageAssessment.getOverallDamageLevel(vehId)
log("I", "", level.damageName) -- "Minor", "Moderate", "Severe"

See Also

• gameplay/util/crashDetection - Vehicle Crash Detection System - Related reference
• gameplay/util/groundContact - Ground Contact Detection - Related reference
• gameplay/util/sortedList - Sorted Object List Container - Related reference
• Gameplay Systems Guide - Guide