Understanding Vehicle Damage Systems

BeamNG has three separate but interconnected damage systems. Using the wrong one for your task means either missing damage events or getting data that's too low-level to be useful. This guide helps you pick the right one.

1. Physical Structure (beamstate)

Use for: Physics-based damage, structural integrity, and crash detection.

• Module: beamstate
• Key Metric: beamstate.damage - Total dissipated energy (in Joules) from beam deformation and breakage.
• Functions:
  • beamstate.getPartDamageData(): Returns normalized damage (0-1) for physical parts (e.g., "front_bumper").
  • beamstate.onBeamBroke(id, energy): Hook triggered when a beam breaks.
  • beamstate.onBeamDeformed(id, ratio): Hook triggered when a beam permanently deforms.

2. High-Level Components (damageTracker)

Use for: UI alerts, gameplay logic, and checking if a major system (engine, tires) is broken.

• Module: damageTracker
• Logic: Aggregates physical damage into logical groups.
• Functions:
  • damageTracker.getDamage(group, name): Returns true/false or a value (0-1) for a component.
  • damageTracker.setDamage(group, name, value, notifyUI): Reports damage to the tracker.
• Common Groups/Names:
  • "body", "FL" (Front Left), "FR", "ML", "MR", "RL", "RR"
  • "wheels", "tireFL", "tireFR", etc.
  • "engine", "engineBlock", "radiator", "oilPan"

3. Maintenance & Integrity (partCondition)

Use for: Long-term wear, part replacement logic, and odometer-based aging.

• Module: partCondition
• Logic: Tracks the "health" of parts across resets/saves.
• Key Metric: integrityValue (1.0 = New, 0.0 = Destroyed).
• Functions:
  • partCondition.getConditions(): Returns a full map of all parts and their current health/visual state.

Summary Table: Which one do I use?

---

See Also

• Beamstate - Structural/beam damage
• DamageTracker - High-level logical damage
• PartCondition - Persistent part integrity
• VE Recipes & Patterns - Comprehensive vehicle scripting reference