ShipDamageFX

Craters where rounds land, and wings that physically come off.

What it does

Hits and part losses have always been events; nothing drew them. ShipDamageFX: {} on the world entity gives a dogfight the two marks that make it read.

Wreckage inherits the dying ship's velocity, plus a random separation kick, a slight upward bias so pieces clear the hull, and per-piece tumble. Fling debris off at its own speed instead and it separates unnaturally, like a decal peeling away; a piece that keeps its orientation reads as a prop rather than as debris.

Two routing decisions are worth knowing:

• A hit reported on part 'debris' goes to the nearest piece of wreckage, not to a hull. Debris has no entity mesh, and marking the ship it came off would put the crater where nothing was hit.
• Asteroids and oil blobs are skipped. A rock is not a hull — shooting one throws off chips, and a scorched puncture in stone looks wrong.

Setup

The engine work ships with the component. Register it once at bootstrap, before the scene loads:

import { registerShipDamageFXExtension } from '@babylonjsmarket/…/ShipDamageFX/adapter/register';

const adapter = new BabylonAdapter();
registerShipDamageFXExtension(adapter);
const game = new ArcadeGame(adapter, { … });

Without it, damage leaves no marks and the System warns once.

Use it in a scene

{
  "World": {
    "tags": ["world"],
    "components": {
      "ShipDamageFX": { "holeDiameter": 0.22, "maxHolesPerPart": 12 }
    }
  }
}

Props

• spread (number, default 6) — peak random separation kick for shed pieces, units/sec.
• lift (number, default 1.5) — upward bias, units/sec.
• tumble (number, default 8) — peak spin, rad/sec.
• debrisLifetimeMin / debrisLifetimeMax (number, defaults 5 / 7) — seconds before a piece is disposed.
• holeDiameter (number, default 0.22) — base crater size; each varies up to half again.
• maxHolesPerPart (number, default 12) — craters kept per part before the oldest is recycled.
• seed (number, default 20260729) — fixes wreck trajectories.
• holes (boolean, default true) — draw craters at all.
• shedding (boolean, default true) — shed parts at all.

Events

• listens for spaceshooter.part.destroyed, bullet.hit, spaceshooter.player.blownapart.
• emits nothing.

Dependencies

Parts (so a hit's part name resolves to mesh suffixes) and Velocity6DOF (so wreckage inherits motion). Neither is required for the component to run — a ship with no part breakdown gets craters anywhere on its hull.

Notes

• The player is cloned, not stripped. The player survives to respawn, so its own primitives must stay where they are; taking them is how a player ends up permanently invisible after their first death. This is also why the kill path deliberately skips the part-detach loop for the player and emits blownapart instead.
• On a GLB ship the primitives are hidden — the model is what you see, and the primitives are the collision proxy. A shed piece has to be revealed or the wing comes off invisibly.
• Detaching preserves world transform, so a part breaks off in place rather than snapping to the world origin.
• Craters are capped per part, or a long firefight mints them without limit.
• Wreckage is advanced from the ECS update, not the render loop, so the debris clock freezes with a paused world. Debris drifting on under a pause menu is a bug — which is why this System is pauseable, unlike the HUD and the explosion FX.
• Trajectories are seeded and offset per event, so two kills in a run differ while the run itself reproduces exactly.