feat: collision damage response - impact energy, component damage, no light-tap explosions

[MBarkerUK]

Summary

Collision, hitbox, and general game-issue improvement — the honest capability split. Geometry (collision LODs, hitbox shape) is baked into the P3D and unfixable by a mod (#128 finding). But the interaction surface is scriptable: hitpoint damage, HandleDamage response, and the collision-response behaviour (the #154 light-tap explosion complaint). This issue scopes what AEE can genuinely improve.

The Honest Split (verified)

BAKED — unfixable by a mod (document, don't claim)

• Collision geometry LODs — the P3D's geometry LOD defines the collision hull. No script, no config changes it. The feat: baked texture and per-component control - PBO override + anchor architecture #128 finding applies: models are baked.
• Hitbox shape — the per-selection hit areas are part of the geometry LOD. Same wall.
• Vehicle collision detection rate — the non-continuous collision check (max checks/sec, the fix: codebase-wide pattern audit - 6 recurring bug classes #154 "random explosion on light tap" complaint) is engine-internal.

SCRIPTABLE — the genuine AEE scope

• Hitpoint damage response — getHitPointDamage/setHitPointDamage/HandleDamage: how much damage a hitpoint takes and how the vehicle responds
• The damage→response link — the feat: vehicle armour and penetration overhaul (STANAG-aligned) #126 armour model + a hitpoint mapping: a light tap on a heavy vehicle should NOT explode it (the fix: codebase-wide pattern audit - 6 recurring bug classes #154 complaint), a penetrating hit should (the component-damage model)
• The collision-response behaviour — what a vehicle does when hit: the health-threshold explosion (unchanged since Operation Flashpoint, the research: player complaints landscape - what to fix, what to avoid #159 chore(deps): bump softprops/action-gh-release from 2 to 3 #1 vehicle complaint) replaced by a component-damage model

The Genuine Improvement Targets

1. The collision-damage response (the #154 light-tap fix)

The #159 complaint: "random explosions on light taps" — the engine's collision damage thresholds. What a mod CAN do:

• Scale collision damage by the REAL physics: impact energy = 0.5·m·v² at the impact (the HitPart data gives the collision). A gentle bump at 5 km/h is low-energy → low damage; a crash at 80 km/h is high → component damage, not guaranteed explosion
• The threshold fix: replace the binary explosion with the feat: vehicle armour and penetration overhaul (STANAG-aligned) #126 component-damage cascade — a light tap damages the bumper hitpoint, not the whole vehicle
• The HandleDamage guard: intercept HandleDamage for collision damage, scale it by the real impact energy, return the scaled value (the ACE3 double-count guard pattern from feat: vehicle armour and penetration overhaul (STANAG-aligned) #126)

2. Hitbox interaction refinement (scripted, not geometry)

• Per-selection damage sensitivity: the hitpoint armour multipliers (feat: real armour mapping - per-vehicle protection database #168) — a round to the glass hits differently than to the engine. The selection-based damage response is scriptable: HitGlass vs HitEngine handled differently
• The HitPart→hitpoint mapping: which selection was hit (the HitPart EH 9th param, research: command surface - geometry anchors, simulation physics, event hooks, AI #144 verified) → which hitpoint takes what damage → the component response

3. The general game-issue fixes (from the #159/#154 audits)

The #78 bugfix addon scope, validated by the complaint research:

• The collision-damage scale (this issue)
• The vehicle damage model (feat: vehicle armour and penetration overhaul (STANAG-aligned) #126 component damage, the research: player complaints landscape - what to fix, what to avoid #159 chore(deps): bump actions/setup-python from 5 to 7 #3 complaint)
• The stamina fix (feat: aee_bugfix addon patching vanilla engine issues #78, setUnitTrait StaminaDrainCoef, the research: player complaints landscape - what to fix, what to avoid #159 chore(deps): bump release-drafter/release-drafter from 6 to 7 #5 complaint)
• The view distance (feat: vision-driven view distance (realistic human vision) #138, the research: player complaints landscape - what to fix, what to avoid #159 chore(deps): bump softprops/action-gh-release from 2 to 3 #1 performance complaint)

The Architecture

HitPart EH (verified, #144) — the impact data: position, velocity, selection, surface
    │
    ▼
IMPACT MODEL (the physics)
    │  impact energy = 0.5·m·v² (real)
    │  the selection → the hitpoint (glass/engine/hull/tracks)
    │  the #126 penetration → does the round matter?
    ▼
DAMAGE RESPONSE (scriptable)
    │  HandleDamage scaled by the real impact energy
    │  component damage, not the binary explosion
    ▼
the #126 component cascade + the #168 armour interaction

The Honest Walls (documented)

• The collision hull shape: baked, no mod changes it
• The collision detection rate: engine-internal
• The ragdoll/vehicle-crash physical response: engine PhysX

Implementation

1. fnc_handleImpact.sqf — the HitPart collision handler: compute the real impact energy, scale HandleDamage
2. The damage-response guard (the ACE3 double-count pattern from feat: vehicle armour and penetration overhaul (STANAG-aligned) #126)
3. The selection→hitpoint mapping (glass vs engine vs hull)
4. The component cascade (from feat: vehicle armour and penetration overhaul (STANAG-aligned) #126) replaces the binary explosion for collision damage
5. Gate: the existing bugfix settings pattern (feat: aee_bugfix addon patching vanilla engine issues #78)

Test Vectors

• 5 km/h bump → minor hitpoint damage, no explosion
• 80 km/h crash → component damage, engine/tracks affected, no guaranteed explosion
• Round to the glass → glass hitpoint damage, driver risk; round to the hull → hull damage
• The HandleDamage guard returns the scaled value (ACE3-compatible)

Sources

• fix: codebase-wide pattern audit - 6 recurring bug classes #154 (the light-tap pattern), feat: vehicle armour and penetration overhaul (STANAG-aligned) #126 (component damage), research: player complaints landscape - what to fix, what to avoid #159 (the complaints verdict — vehicle damage is the chore(deps): bump actions/setup-python from 5 to 7 #3 target), research: command surface - geometry anchors, simulation physics, event hooks, AI #144 (HitPart EH), feat: baked texture and per-component control - PBO override + anchor architecture #128 (the baked-geometry finding)

Labels

core, P2-medium, effort/M, type/feat, phase/2-expansion, mobility, physics, infra