RP412/docs/DAMAGE-MODEL.md

# Red Planet — the damage model, end to end

How a hit becomes lost armor, lost SCORE, and a burning VTV. Unlike BT,
this analysis reads the AUTHENTIC surviving game source (`RP/` in this
tree — VTV.cpp, WEAPSYS.cpp, RIVET.cpp, DEMOPACK.cpp, RPPLAYER.cpp) on top
of the shared MUNGA engine. The BT companion doc is
`TeslaRel410/restoration/source410/BT/DAMAGE-MODEL.md`; the engine layers
(Damage record, DamageZone, Entity message routing) are identical and only
summarized here.

The headline difference: **RP's damage model is a physics + score economy,
not a subsystem-failure simulation**. There are no critical tables, no
per-zone cascade, no equipment destruction. Damage is dominated by KINETIC
events (ramming, walls, crushing doors), armor is calibrated from the
vehicle's physics constants, and every point of damage is simultaneously a
score transaction between players — Martian football, not a mech duel.

```
laser raycast / rivet impact / demo-pack blast / collision bounce
        │
        ▼
 TakeDamageMessage (zone 0 — the hull)
        │
        ▼
 VTV::TakeDamageMessageHandler
   ├─ collision?  recompute damage locally via DynamicBounce (+ knockback)
   ├─ otherwise   apply damageForce/mass to velocity (knockback impulse)
   └─ chain to Entity → damageZones[0]->TakeDamage
        │
        ▼
 VTV__DamageZone::TakeDamage
   ├─ engine armor model: level += amount × scale[type], 1.0 = dead
   ├─ level ≥ 1.0 → VTV::BurningState (+ VehicleDead to the player)
   └─ EVERY hit forwarded to the linked RPPlayer
        │
        ▼
 RPPlayer::TakeDamageMessageHandler
   ├─ victim loses damageAmount as SCORE (collision × deathConstant)
   └─ top attacker in the 2-second revenge window GAINS the same
```

## 1. Shared engine layers (identical to BT)

The `Damage` record (`MUNGA/DAMAGE.HPP`): 5 types (Collision, Ballistic,
Explosive, Laser, Energy), `damageAmount`, `damageForce`, `surfaceNormal`,
`impactPoint`, `burstCount`. `DamageZone::TakeDamage` integrates
`damageLevel += amount × damageScale[type]`, clamps [0,1], 1.0 = Burning +
Destroyed graphic. `Entity::TakeDamageMessageHandler` routes
`damageZones[zone]->TakeDamage` and DROPS zone −1.

RP never needs the −1 path in combat: **every producer passes zone 0**.
The VTV streams its zone array from the type-20 resource like any entity
(multiple zones can exist for graphics), but combat, collision, suicide and
out-of-world damage all land on zone 0 — the hull is one armor pool. There
is no RP analog of BT's cylinder hit-location table, no aimed-zone fire,
and no criticals: `VTVSubsystem` adds only controls plumbing (compare BT's
`MechSubsystem`, which owns a private armored zone per equipment piece).

## 2. Producers — where Damage records are born

**LaserGun** (`WEAPSYS.cpp`, front + rear lasers): a RAYCAST along the
vehicle ±Z axis (`FindBoxedSolidHitBy`), explosion entity spawned at the
beam end, `TakeDamageMessage` (zone 0) at the struck entity. Authored
`DamageAmount` is per-second; the ctor pre-multiplies by the firing cycle
(`laserDuration + pulseDuration`) so each completed cycle delivers one
quantum. Charge drains per cycle; type Laser.

**RivetGun** (`RIVET.cpp`): a real projectile entity. On striking a MOVER
the authored amount is scaled **kinetically**:
`amount ×= (|v_closing|/350)²` — rear-ending a fleeing VTV tickles, a
head-on rivet hurts. Static world hits use the authored amount. Explosion
spawned at impact; zone 0.

**DemoPack** (`DEMOPACK.cpp`): deployed charge. On detonation every entity
within `blastRadius` takes the FULL authored amount (no falloff), type
Explosive, `damageForce` = normalized blast direction × `concussiveForce`
(the knockback shove). Compare the engine's generic `Explosion` splash
(EXPLODE.CPP), which decays `burstCount/r^1.2` — the demo pack is a flat
binary yes/no blast.

**Collisions — the star of the show** (`VTV.cpp` MoveVTV +
`MUNGA/MOVER.CPP`): the per-frame integrator collides the hull volume
(ray-cast ahead when moving faster than one hull diameter per frame).
- **Static world** (walls/terrain): `StaticBounce` computes the energy
  loss = the damage amount; a keel-angle grace applies — surface normals
  within 45° of the keel (`collisionNormal.y > 0.7`) take
  `bottomArmorScale` (authored, default **0.1×**) — belly scrapes are
  cheap, wall slams are not.
- **VTV-on-VTV ram**: the RAMMER computes `DynamicBounce` damage locally,
  applies it to itself, and dispatches the same record at the victim. The
  victim's handler does NOT trust the amount: it re-runs `DynamicBounce`
  from its own frame (relative velocity vs the rammer, its own
  elasticity), ignores the message if the relative motion doesn't oppose
  the passed normal, and applies its own bounce physics. Both sides also
  enter each other's revenge queue.
- **Doors**: velocity is adjusted by the door's motion; caught between
  both doors = CRUSH (the closing-door instant-kill).
- **Out of world**: leaving the arena volume = instant full Explosive
  budget (`1/scale`) + a random tumble.
- **Suicide**: the Kavorkian button (authentic name) applies exactly the
  full Explosive budget to zone 0.

**Knockback**: non-collision damage applies `damageForce / moverMass` to
the victim's velocity — lasers, rivets and demo packs physically shove the
target. While BURNING, collision forces convert to torque (the death
tumble, clamped ±20).

## 3. Armor calibration — physics, not points

The authored `.dmg` per-type points stream in as in BT, but the VTV zone
ctor **overwrites the Collision scale from the vehicle's physics**:

    scale[Collision] = 2000 / (mass × (maxImpactSpeed/3.6)² × (1 − e²))

i.e. the hull is calibrated so a full-speed impact (authored
`MaxImpactSpeed`, km/h → m/s) spends exactly the whole budget — armor is
defined in impact-speed terms, matched to what `StaticBounce`/
`DynamicBounce` return (kinetic energy with the elastic fraction
restituted). The companion constant

    deathConstant = 2000 × deathScoreLoss / ((1 − e²) × deathSpeed² × mass)

converts collision damage to SCORE at the same exchange rate: dying at
`DeathSpeed` costs exactly `DeathScoreLoss` points.

## 4. The victim — `VTV::TakeDamageMessageHandler` + zone override

Handler order: (1) look up the inflicting entity's player and push an
`OffensivePlayer{player, damageType, timestamp}` onto OUR revenge queue;
(2) Collision → local `DynamicBounce` recompute (see above), else →
knockback impulse; (3) chain to the Entity base → zone 0.

`VTV__DamageZone::TakeDamage` then:
1. Runs the engine armor model.
2. `damageLevel ≥ 1.0` → `VTV::BurningState` — the vehicle is DEAD but
   keeps tumbling physically (burn + torque) until reset.
3. On the ALIVE→BURNING transition, sends `VehicleDeadMessage` to the
   linked player.
4. Forwards a COPY of every damage record to the linked `RPPlayer` — the
   score pipe. Damage and score are the same event in RP.

## 5. The score economy — `RPPlayer::TakeDamageMessageHandler`

- Victim: `score_loss = damageAmount` (Collision × `deathConstant`),
  posted as `DamageScoreLossPointType` — **damage is score loss**.
- The revenge queue (`offensivePlayerList`, entries expire after **2.0 s**)
  is consulted: the TOP attacker — most recent player to damage us — gains
  the same amount as `DamageBonusPointType` (sign-flipped by the
  team/`deathBonus` rules; negatives become drop-zone-hit penalties), and
  the arcade console is notified (`ConsolePlayerVTVDamagedMessage`).
- On vehicle death the same queue decides KILL credit
  (`VehicleDeadMessageHandler`), then the VTV runs `DeathShutdown`
  (`FootballReset` for Crusher/Blocker roles, `RegularReset` otherwise)
  and respawns via the DropZone machinery.
- Role twists (Martian football): the Runner carries a `scoreMultiplier`
  that DOUBLES per score-zone pass (reset to 1 on death) — damage taken
  during the drop-zone penalty window is scored differently; Crusher and
  Blocker are RPPlayer roles, not weapons — crushing is done with the
  hull, priced by the collision physics above.

## 6. RP vs BT — the design fork from one engine

| | Red Planet | BattleTech 4.10 |
|---|---|---|
| hull zones in combat | one pool (zone 0) | many, vital/leg flags, LOD shells |
| unaimed hit resolve | none needed | cylinder height×angle table |
| criticals / equipment | none | per-zone crit tables → subsystem kill |
| collision armor | derived from physics constants | authored points (halved scales for legs) |
| ram damage | victim recomputes locally | inflictor-authoritative message |
| knockback | damageForce/mass on every hit | none (gyro shake only) |
| death | zone 0 full → Burning + tumble | vital/leg zone full → mech kill |
| meaning of damage | score transaction (2 s revenge window) | armor attrition + equipment failure |