Vehicle damage (vehicle.damage) #

Part of the vehicle family: see the vehicles guide 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 #

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 #

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.

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 #

{ "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 #

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.