# Vehicle damage (vehicle.damage)

Part of the vehicle family: see the [vehicles guide](guide:vehicles) for the cars themselves.

## What it is for

A dedicated damage model for the cars of `vehicle.driveable`. That kit still keeps the car (body, seat, health variable, ejecting the driver); this one decides how much damage a car takes and what happens as it falls apart: damage per zone, smoke then fire, burning wrecks that explode and hurt what stands near, and repair. While it is installed, `vehicle.driveable` stops pricing collisions itself. Remove it and the built-in health comes back.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.damage" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "vehicle.damage",
                              config: { "health": 150, "collisionScale": 0.8, "explosionRadius": 8 } }
```

It requires `vehicle.drive` and `game.engine`. Health stays in the vehicle state, so the HUD variable `vehicle.health` keeps working.

## First example

<!-- test: kits/game_engine/host/tests/vehicle_damage.rs::a_collision_costs_health_on_the_facing_zone_and_changes_the_stage -->
With `{ "health": 100, "collisionScale": 2 }`, car `a` hits car `b` ahead of it at 30 m/s: `vehicle.damaged` reports 60 damage on the `front` zone of `a`, which leaves 40 health and moves it to the `smoking` stage (`vehicle.stage`). A `combat.hit` of 10 on `b` from `a` costs `b` 10 on its `rear` zone. `model(a)` then returns `{ zones: { front: 60 }, stage: "smoking", burn: 0 }`.

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `health` | 100 | Maximum health of every car, 1 to 1000 |
| `collisionScale` | 1 | Damage per m/s of impact speed, 0 to 5 |
| `explode` | `true` | A wreck explodes |
| `explosionRadius` | 6 | Radius in metres of the area damage, 0 to 30 |
| `deformation` | `true` | Web: bounded cosmetic dents |
| `maxDent` | 0.18 | Web: largest dent in metres |
| `effects` | `true` | Web: smoke, fire and impact glow |

## Rules

- `vehicle.collided` costs `speed x collisionScale` on the zone facing the other entity (`front`, `rear`, `left`, `right`).
- `combat.hit` on a car costs its `damage` on the zone facing the shooter.
- Stages: `smoking` at 50 % health or less, `burning` at 25 % or less, `wrecked` at 0. A burning car loses 5 % of its maximum health per second (zone `fire`) until it wrecks.
- A wreck is destroyed through `vehicle.driveable` (seat freed, driver ejected). With `explode`, every other car within `explosionRadius` takes 60 at the centre, falling linearly to 0 at the edge (zone `explosion`), chain reactions in order. Entities with combat health take it through the combat damage pipeline.
- Health and the damage model are saved with the vehicle.

## Services, events, hooks

- `vehicle.damage` (service): `health(entity)`, `damage(entity, amount, source, zone)`, `repair(entity)`, `destroyed(entity)`, `model(entity)`, `stage(entity)`, `maxHealth()`.
- `vehicle.damaged` (event): `{ entity, amount, health, zone, source }`.
- `vehicle.destroyed` (event): `{ entity, driver }`, emitted through `vehicle.driveable`.
- `vehicle.exploded` (event): `{ entity, radius }`.
- `vehicle.stage` (event): `{ entity, stage }`.
- `vehicle.repaired` (event): `{ entity, health }`.
- Listens to `vehicle.collided`, `combat.hit` and `vehicle.spawned`.

| Hook | Payload | What a tap may do |
|---|---|---|
| `vehicle.damage` | `{ vehicle, amount, zone, health, source }` | change `amount` (0 or cancelled: no damage, no event); asked for every hit |
| `vehicle.destroy` | `{ vehicle, amount, zone, health, source }` | cancel: the car keeps 1 health point and is not wrecked |
| `vehicle.explode` | `{ vehicle, radius, damage }` | change `radius` (0 to 30) and `damage`, or cancel: no explosion |
| `vehicle.repair` | `{ vehicle, health, destroyed, restored }` | change `restored`, or cancel: nothing is repaired |

A car placed in a scene can carry the component `damage_model`: `{ health?, collisionScale?, explode? }` for its starting health and stage, its own toughness and whether its wreck explodes.

## Hooks and modding

```json
{ "id": "armoured_van", "hook": "vehicle.damage", "match": { "vehicle": "e12", "zone": "front" }, "mul": { "amount": 0.5 } }
```

Every setting is moddable. The slot `vehicle_fx` takes smoke and fire flipbooks; particles are procedural otherwise.

## Engines

The rules are the same Rust logic on the web and in the native player, and are delivered to Godot, Unity and Unreal. The dents, worn paint, smoke, fire and glow are web presentation options only.

## When it does not do what you expect

| Symptom | Cause and fix |
|---|---|
| Collisions cost nothing | `collisionScale` is 0, or the car has a `damage_model` with `collisionScale` 0 |
| A wreck does not explode | `explode` is `false`, `explosionRadius` is 0, or a tap cancelled `vehicle.explode` |
| A car never dies | a tap cancels `vehicle.destroy`: it stays at 1 health point |
| No dents | `deformation` is `false` or the engine is not the web player; wheels and rigged meshes are never dented |

## Limits

Dents are bounded cosmetic crushing, not soft-body physics. Presentation options are web-only.

## Versions

Kit 1.4.0: hooks `vehicle.damage`, `vehicle.destroy`, `vehicle.explode`, `vehicle.repair` and moddable settings; 1.3.0 added the `damage_model` component.