@adatechnology/game-destruction-three 0.12.1 → 0.14.0

package/README.md

@@ -7,7 +7,7 @@ physics, loose pieces after a part comes off, and pooled particles (fire, smoke,
 - Nothing is changed in place: geometry and materials are cloned on the first visual change of a mesh, and `restore` / `clear` give the originals back.
 - Blasts and the fires of burning parts are drawn by the effects world of [`@adatechnology/game-vfx`](../game-vfx) (an `explode` event plays `ev.effect ?? 'generic'`, scaled by the radius when it names none). Pass the world the host shares in `vfx`; without it the renderer makes its own world and its own `game-vfx-three` layer and steps them in `update`. Debris, sparks, drips and leaks still use two pooled `THREE.Points` (additive and normal blending), with a soft sprite computed in the shader (no texture asset); they move to the shared sprite pool when `game-vfx` gets one.
 - `three` is a peer dependency used for types only: you pass your own `THREE` instance at runtime.
-- The renderer plays nothing: you get keys (`impact_metal`, `shatter_glass`, `burn_loop`, `burn_end`, ...) through `onSound`. `createDestructionSound(engine)` is the sound bank for them on a [`@adatechnology/game-audio`](../game-audio) engine: the Cena de Arte's material sounds (clang, wood, glass, crumble, thud, boom...) and the game's explosion thump, a fire loop that follows how many parts burn, and a key table (`style: 'art_scene' | 'game'`, `keys` to replace) so a game changes what each key plays.
+- The renderer plays nothing: you get keys (`impact_metal`, `shatter_glass`, `burn_loop`, `burn_end`, ...) through `onSound`. `createDestructionSound(engine)` is the sound bank for them on a [`@adatechnology/game-audio`](../game-audio) engine: the Cena de Arte's material sounds (clang, wood, glass, crumble, thud, boom...) and the game's explosion thump, a fire loop that follows how many parts burn, and a key table (`style: 'art_scene' | 'game'`, `keys` to replace) so a game changes what each key plays. An impact, a break or a ricochet also sends `detail.keys`, the keys to try first, most specific first: `impact_<material>_<blow>`, `impact_<material>`, `impact_<family>_<blow>`, `impact_<family>` (`blow` is the hit's `DamageType`, carried by every destruction event as `blow`; the family comes from `impactFamily`: metal, glass, ceramic, soil, masonry, wood, plant, plastic, rubber, wax, soft). `IMPACT_SOUND_KEYS` gives a bullet, a blow and a blade their own sound on each family; a game replaces or silences any key in `keys`.
 
 Contracts live in [`@adatechnology/game-contracts`](../game-contracts); the types are re-exported here, so existing imports keep working.
 

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { Fragment, Vec3, DebrisKind, HitResult, DestructionWorld, MaterialId, DestructibleSpec, MaterialDef } from '@adatechnology/game-destruction';
+import { Fragment, Vec3, DebrisKind, HitResult, DestructionWorld, MaterialId, DestructibleSpec, MaterialDef, DamageType } from '@adatechnology/game-destruction';
 export { Quat, Vec3 } from '@adatechnology/game-destruction';
+import { DeferredQueue, WarmUpProbes, BlastShoveOptions, Vec3 as Vec3$1 } from '@adatechnology/game-contracts';
 import * as THREE_NS from 'three';
-import { WarmUpProbes, BlastShoveOptions, Vec3 as Vec3$1 } from '@adatechnology/game-contracts';
 import { VfxWorld, SpriteKind } from '@adatechnology/game-vfx';
-import { LoopRecipe, SoundBank, SoundRecipe, AudioEngine } from '@adatechnology/game-audio';
+import { LoopRecipe, SoundBank, SoundRecipe, Falloff, AudioEngine, SampleDefaults, SfxManifest } from '@adatechnology/game-audio';
 
 /** What a fragment's resting time can depend on: the fragment (its material, size, shape) and the id of the object it came from. */
 type FragmentLifeRule = (fragment: Fragment, objectId: string) => number;
@@ -20,6 +20,19 @@ type ThreeNamespace = typeof THREE_NS;
 type Object3D = THREE_NS.Object3D;
 type Mesh = THREE_NS.Mesh;
 type Quality = 'low' | 'medium' | 'high';
+/** What a sound key carries besides the point and the volume: the named explosion and its size, how enclosed it was, how long a leak lasts. */
+interface SoundDetail {
+    /** An impact or a break: the keys to try before the key itself, most specific first (material and blow, material, family and blow, family). */
+    readonly keys?: readonly string[];
+    /** `explode`: the named explosion (`explosions.json` of game-vfx: `m67`, `c4`, `propane_p13`...). */
+    readonly effect?: string;
+    /** `explode`: blast radius in metres. */
+    readonly radius?: number;
+    /** `explode`: how enclosed the blast was (1 in the open, more in a room; from the blast report). */
+    readonly confinement?: number;
+    /** `primed`: seconds until the vessel bursts (the gas leak lasts that long). */
+    readonly seconds?: number;
+}
 interface RendererOptions {
     /** Scene that receives fragments, loose pieces, decals and particles. */
     scene: THREE_NS.Scene;
@@ -60,8 +73,12 @@ interface RendererOptions {
     shoveable?: (objectId: string) => boolean;
     /** Called when the renderer made a bound object a piece on its own: a blast shoved it (`blast`, see `shoveable`), or furniture came apart and what stayed is loose too (`apart`). */
     onLoosened?: (objectId: string, piece: Piece, cause: 'blast' | 'apart') => void;
-    /** Called when a sound should play; the host maps keys to audio (e.g. `impact_metal`, `shatter_glass`, `ignite`, `explode`). `burn_loop` is sent when a part starts to burn and `burn_end` when it burns out or is put out. */
-    onSound?: (key: string, point: Vec3, volume: number) => void;
+    /**
+     * Called when a sound should play; the host maps keys to audio (e.g. `impact_metal`, `shatter_glass`, `ignite`, `explode`). `burn_loop` is sent when a part starts to burn and `burn_end` when it burns out or is put out.
+     * An impact or a break also sends `detail.keys`, the keys to try before `key`, most specific first (`impact_concrete_ballistic`, `impact_concrete`, `impact_masonry_ballistic`, `impact_masonry`).
+     * An explosion sends its named effect, radius and confinement; `primed` sends the seconds of its leak.
+     */
+    onSound?: (key: string, point: Vec3, volume: number, detail?: SoundDetail) => void;
     /**
      * The effects world that draws blasts and fires. Pass the one the host shares with the other renderers (and step it, through its
      * `VfxRenderer.update`, once per frame); without it the renderer makes its own world and its own three layer and steps them in `update`.
@@ -175,6 +192,11 @@ interface DestructionRenderer {
     impulse(objectId: string, impulse: Vec3, point?: Vec3): void;
     /** Integrate fragments, pieces and particles; apply pending visual changes. Call once per frame after `world.update`. */
     update(dt: number): void;
+    /**
+     * The waiting events and the presentation slices they left, as a `DeferredQueue` for a shared frame budget (id `destruction.events`). `budget.register`
+     * attaches it and `update` stops draining by itself; unregistering gives the draining back to `update` and `eventBudgetMs`. Asking for it changes nothing.
+     */
+    deferredQueue?(): DeferredQueue;
     /** Emit particles directly (muzzle flashes, extinguisher foam, tool sparks). */
     emit(kind: DebrisKind | 'fire' | 'flash' | 'foam', point: Vec3, normal: Vec3, count: number, speed?: number): void;
     /**
@@ -228,9 +250,14 @@ interface SpecFromObjectResult {
 
 /** Sound key for an impact on a material. */
 declare function impactKey(def: MaterialDef | undefined): string;
+/** Sound key (`shot_*`) of a round striking this material: sharper than a blow (a tink on steel, a crack on glass); a host without it plays the `impact_*`. */
+declare const shotKey: (def: MaterialDef | undefined) => string;
 /** Sound key (`drag_*`) of a base of this material dragged on a floor. */
 declare const dragSoundKey: (def: MaterialDef | undefined) => string;
-declare function createDestructionRenderer(THREE: ThreeNamespace, options: RendererOptions): DestructionRenderer;
+/** The renderer this package makes always has its `deferredQueue`; a third-party `DestructionRenderer` may leave it out. */
+declare function createDestructionRenderer(THREE: ThreeNamespace, options: RendererOptions): DestructionRenderer & {
+    deferredQueue(): DeferredQueue;
+};
 
 /** What `userData.destructionPart` says: a string (the part id) or an object `{ id, material?, parent?, kind? }`. */
 interface PartHint {
@@ -268,8 +295,66 @@ declare const EXPLOSION_BOOM: SoundRecipe;
 declare const BURN_LOOP: LoopRecipe;
 /** Something heavy dragged on a floor, by what its base is made of. */
 declare const DRAG_SOUNDS: readonly SoundRecipe[];
+/**
+ * A blow on a material, by what it is made of and what met it (`impactSoundKeys`): a bullet, a blunt blow (a punch, a kick, a fall), a blade. Each
+ * is drawn from how the real thing sounds (checklist 5.3): a bullet rings steel and goes "tchak" on concrete with pebbles after it, a fist on steel is a
+ * low "bong", a knife scrapes it; the ground is a dull "tuf", ceramic a dry "tic", plastic a hollow "toc", a sofa a "fump". Levels are matched so a
+ * bullet on concrete is as loud as on wood.
+ */
+declare const IMPACT_SOUNDS: readonly SoundRecipe[];
 declare const DESTRUCTION_SOUND_BANK: SoundBank;
 
+/**
+ * The sound family of a material, from its tags: what it sounds like when something meets it. Finer than the five keys of `impactKey` (which stay the
+ * last fallback): ceramic is not glass, the ground is not concrete, plastic and wax are not wood, leaves are not a sofa.
+ */
+type ImpactFamily = 'metal' | 'glass' | 'ceramic' | 'soil' | 'masonry' | 'wood' | 'plant' | 'plastic' | 'rubber' | 'wax' | 'soft';
+/** Tag → family, in the order they are tried (`green_wood` is `plant` and `wood`: wood wins; `gravel` is `soil` and `masonry`: soil wins). */
+declare const IMPACT_FAMILY_TAGS: readonly (readonly [tag: string, family: ImpactFamily])[];
+/** The family of a material, or `undefined` when none of its tags names one (the five legacy keys of `impactKey` then answer). */
+declare function impactFamily(def: MaterialDef | undefined): ImpactFamily | undefined;
+/** What an impact or a break sends with its key: the keys to try before it, most specific first (material and blow, material, family and blow, family). */
+type ImpactKeys = SoundDetail & {
+    readonly keys: readonly string[];
+};
+/**
+ * The impact keys for a blow on a material, most specific first: `impact_<material>_<blow>`, `impact_<material>`, `impact_<family>_<blow>`,
+ * `impact_<family>` (blow is the `DamageType`: `ballistic`, `blunt`, `slash`, `explosive`...). The legacy `impactKey` is the last fallback the caller sends as the key.
+ */
+declare function impactSoundKeys(material: string, def: MaterialDef | undefined, blow?: DamageType): ImpactKeys;
+/** The keys for a part of this material breaking, most specific first: `break_<material>_<blow>`, `break_<material>`, `break_<family>_<blow>`, `break_<family>`. */
+declare function breakSoundKeys(material: string, def: MaterialDef | undefined, blow?: DamageType): ImpactKeys;
+/** The keys for a round glancing off a part of this material: `ricochet_<material>`, `ricochet_<family>` (then the plain `ricochet`). */
+declare function ricochetSoundKeys(material: string, def: MaterialDef | undefined): ImpactKeys;
+
+/** A blast near the listener: loud for tens of metres; lowpass cutoffs fall with distance. */
+declare const BLAST_FALLOFF: Falloff;
+/** A blast far away (past `BLAST_FAR_DISTANCE`): heard for hundreds of metres. */
+declare const BLAST_FAR_FALLOFF: Falloff;
+/** Fire, ignition and crackles: a room-size sound. */
+declare const FIRE_FALLOFF: Falloff;
+/** Metres from the listener past which a blast plays its far version. */
+declare const BLAST_FAR_DISTANCE = 60;
+/** The explosion families, each with its own sound. */
+declare const BLAST_KINDS: readonly ["grenade", "big", "fuel", "car", "pipe_bomb", "rocket", "flashbang", "molotov"];
+type BlastKind = (typeof BLAST_KINDS)[number];
+/**
+ * Which family each named explosion of `@adatechnology/game-vfx` (`explosions.json`, the `effect` of an explosive part) belongs to. Data: a game adds
+ * or changes entries through `DestructionSoundOptions.blastKinds`. An explosion without a known effect is a grenade below `BIG_BLAST_RADIUS` and a big
+ * charge above it.
+ */
+declare const BLAST_KIND_OF: Readonly<Record<string, BlastKind>>;
+/** Blast radius (metres) from which an explosion with no known effect is a big charge. */
+declare const BIG_BLAST_RADIUS = 8;
+/** One sound per explosion family, the far and the indoor versions. */
+declare const BLAST_SOUNDS: readonly SoundRecipe[];
+/** Fire: ignition, gas leaking from a vessel about to burst, a fire put out, and the crackles that ride on the fire loop. */
+declare const FIRE_SOUNDS: readonly SoundRecipe[];
+/** The roar of the fires: low, soft noise; `createDestructionSound` raises it with every part that burns and sprinkles crackles on it. */
+declare const FIRE_LOOP: LoopRecipe;
+/** The sound of a blast family. */
+declare const BLAST_SOUND_OF: Readonly<Record<BlastKind, string>>;
+
 /**
  * What a sound key plays: the recipe, its params, a scale on the volume the renderer gives, and (optionally) a louder recipe above a volume
  * (a big blast gets the long boom).
@@ -282,8 +367,15 @@ type SoundKeyRule = {
         readonly volume: number;
         readonly sound: string;
     };
+    /** A sound of this bank played when the engine does not know `sound` (a vehicle door without the vehicle bank registered shuts like metal). */
+    readonly fallback?: string;
 };
 type DestructionSoundStyle = 'art_scene' | 'game';
+/**
+ * The keys of a blow on a material (`impactSoundKeys`, `breakSoundKeys`): `impact_<family>_<blow>`, `impact_<material>[_<blow>]`, `break_<...>`. The renderer
+ * sends them before its legacy family key, so the first one with a rule plays; a game replaces any of them in `keys`.
+ */
+declare const IMPACT_SOUND_KEYS: Readonly<Record<string, SoundKeyRule>>;
 /**
  * The keys `createDestructionRenderer` sends to `onSound`, mapped to the sounds the teams delivered. The Cena de Arte has a sound for every material
  * (clang, wood, glass, crumble, thud...); the game has four classes (impact, glass, wood, explosion) and its own explosion thump. Which team sound answers
@@ -293,7 +385,7 @@ declare const DESTRUCTION_SOUND_KEYS: Readonly<Record<DestructionSoundStyle, Rea
 type DestructionSoundOptions = {
     /** Which team answers the keys (default `art_scene`, the kit mix). `game` falls back to the art scene for the keys the game has no sound for. */
     readonly style?: DestructionSoundStyle;
-    /** Replaces or adds a key's rule; `null` silences it. */
+    /** Replaces or adds a key's rule; `null` silences it. A key without a rule that is the id of a registered sound (the foley bank's) plays that sound. */
     readonly keys?: Readonly<Record<string, SoundKeyRule | null>>;
     /** The fire loop: the volume each burning part adds and the most it reaches (the page never raises it, so these are the kit's). */
     readonly fire?: {
@@ -302,27 +394,82 @@ type DestructionSoundOptions = {
     };
     /** Burn loop on or off (default on). */
     readonly burnLoop?: boolean;
+    /** The fire loop played while something burns (default `fire_loop`; `burn_loop` is the art scene's bright one). */
+    readonly fireLoop?: string;
+    /** Crackles per second over the fire loop: `base + perSqrtFire × √(parts burning)`, at most `max` (default 2, 3, 14). `false` turns them off. */
+    readonly crackles?: false | {
+        readonly base?: number;
+        readonly perSqrtFire?: number;
+        readonly max?: number;
+        readonly volume?: number;
+    };
+    /** Adds to or changes `BLAST_KIND_OF`: which family a named explosion (`effect`) sounds like. */
+    readonly blastKinds?: Readonly<Record<string, BlastKind>>;
+    /** Metres past which a blast plays `explosion_far` instead of its own sound (default `BLAST_FAR_DISTANCE`). */
+    readonly blastFarDistance?: number;
+    /** `confinement` of a blast (from its report) from which the indoor tail plays too (default 1.3). */
+    readonly indoorConfinement?: number;
+    /** Seed of the crackle timing (default 1). */
+    readonly seed?: number;
 };
 type DestructionSound = {
     /** Pass to `createDestructionRenderer({ onSound })`. */
-    readonly onSound: (key: string, point: Vec3$1, volume: number) => void;
-    /** The rule a key resolves to, if any. */
-    rule(key: string): SoundKeyRule | undefined;
+    readonly onSound: (key: string, point: Vec3$1, volume: number, detail?: SoundDetail) => void;
+    /** Moves the fire crackles on; call once per frame with the frame time in seconds. */
+    update(dt: number): void;
+    /** The sound an explosion plays (`explode` with its detail), for a listener at the engine's listener position. */
+    blastSound(point: Vec3$1, volume: number, detail?: SoundDetail): string;
+    /** The rule a key resolves to, if any; with `detail`, the rule `onSound` would play (the first of `detail.keys` that has one, else `key`'s). */
+    rule(key: string, detail?: SoundDetail): SoundKeyRule | undefined;
     /** Parts burning now. */
     readonly burning: () => number;
     dispose(): void;
 };
 declare const DEFAULT_FIRE: {
-    readonly perFire: 0.05;
-    readonly max: 0.2;
+    readonly perFire: 0.08;
+    readonly max: 0.45;
+};
+declare const DEFAULT_CRACKLES: {
+    readonly base: 2;
+    readonly perSqrtFire: 3;
+    readonly max: 14;
+    readonly volume: 0.5;
 };
+declare const DEFAULT_INDOOR_CONFINEMENT = 1.3;
 /**
  * Plays the renderer's sound keys on a game-audio engine: the bank is registered in the engine, a key becomes a positional sound at the point, and
- * `burn_loop` / `burn_end` (a part starts to burn, a part burns out or is put out) drive one fire loop whose volume follows how many parts burn.
+ * `burn_loop` / `burn_end` (a part starts to burn, a part burns out or is put out) drive one fire loop whose volume follows how many parts burn, with
+ * crackles at the burning points (`update`). An explosion plays the sound of its family (`BLAST_KIND_OF` by its effect), the far rumble past
+ * `blastFarDistance` and the indoor tail when the blast was confined.
  */
 declare function createDestructionSound(engine: AudioEngine, options?: DestructionSoundOptions): DestructionSound;
 
+/** The numbers of one recorded sound, plus whether it loops (the fire's roar). */
+type BlastFireSampleDefaults = SampleDefaults & {
+    readonly loop?: boolean | {
+        readonly crossfade?: number;
+    };
+};
+/**
+ * The sounds of the blasts and the fire that have recorded takes, with their bus, level and distance curve (the recipes' own curves, so a file and its
+ * fallback fade alike with distance). Data: a game passes its own table to `blastFireSampleBank`.
+ */
+declare const BLAST_FIRE_SAMPLES: Readonly<Record<string, BlastFireSampleDefaults>>;
+type BlastFireSampleBankOptions = {
+    /** Bank id (default 'destruction-samples'). */
+    readonly id?: string;
+    /** Where the manifest's folder is served (`/sfx/`); default ''. */
+    readonly baseUrl?: string;
+    /** Numbers per id (default `BLAST_FIRE_SAMPLES`). */
+    readonly sounds?: Readonly<Record<string, BlastFireSampleDefaults>>;
+};
+/**
+ * A bank of the recorded blasts and fire from the kit's sound manifest. Register it with the engine next to `DESTRUCTION_SOUND_BANK`: each id plays
+ * its files once loaded and its synthesized recipe until then.
+ */
+declare function blastFireSampleBank(manifest: SfxManifest, options?: BlastFireSampleBankOptions): SoundBank;
+
 /** Every particle kind the renderer can emit (the game's sprite kinds, see `@adatechnology/game-vfx`). */
 type ParticleKind = SpriteKind;
 
-export { BURN_LOOP, type BindOptions, DEFAULT_FIRE, DESTRUCTION_SOUND_BANK, DESTRUCTION_SOUND_KEYS, DRAG_SOUNDS, type DestructionRenderer, type DestructionSound, type DestructionSoundOptions, type DestructionSoundStyle, EXPLOSION_BOOM, type ExplodeOptions, type FragmentLifeRule, type LooseBody, type Mesh, type MeshRange, type Object3D, type PartHint, type ParticleKind, type Piece, type Quality, type RendererOptions, SCENE_SOUNDS, type SolidBox, type SoundKeyRule, type SpecFromObjectOptions, type SpecFromObjectResult, type ThreeNamespace, createDestructionRenderer, createDestructionSound, dragSoundKey, heatColor, impactKey, specFromObject3D };
+export { BIG_BLAST_RADIUS, BLAST_FALLOFF, BLAST_FAR_DISTANCE, BLAST_FAR_FALLOFF, BLAST_FIRE_SAMPLES, BLAST_KINDS, BLAST_KIND_OF, BLAST_SOUNDS, BLAST_SOUND_OF, BURN_LOOP, type BindOptions, type BlastFireSampleBankOptions, type BlastFireSampleDefaults, type BlastKind, DEFAULT_CRACKLES, DEFAULT_FIRE, DEFAULT_INDOOR_CONFINEMENT, DESTRUCTION_SOUND_BANK, DESTRUCTION_SOUND_KEYS, DRAG_SOUNDS, type DestructionRenderer, type DestructionSound, type DestructionSoundOptions, type DestructionSoundStyle, EXPLOSION_BOOM, type ExplodeOptions, FIRE_FALLOFF, FIRE_LOOP, FIRE_SOUNDS, type FragmentLifeRule, IMPACT_FAMILY_TAGS, IMPACT_SOUNDS, IMPACT_SOUND_KEYS, type ImpactFamily, type ImpactKeys, type LooseBody, type Mesh, type MeshRange, type Object3D, type PartHint, type ParticleKind, type Piece, type Quality, type RendererOptions, SCENE_SOUNDS, type SolidBox, type SoundDetail, type SoundKeyRule, type SpecFromObjectOptions, type SpecFromObjectResult, type ThreeNamespace, blastFireSampleBank, breakSoundKeys, createDestructionRenderer, createDestructionSound, dragSoundKey, heatColor, impactFamily, impactKey, impactSoundKeys, ricochetSoundKeys, shotKey, specFromObject3D };