@adatechnology/game-destruction-three 0.4.0 → 0.6.0

package/README.md

@@ -5,9 +5,9 @@ package draws them on your meshes: vertex dents, bullet-hole and crack decals, c
 physics, loose pieces after a part comes off, and pooled particles (fire, smoke, sparks, dust, shards, splinters, ...).
 
 - 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.
-- Two pooled `THREE.Points` (additive and normal blending) draw every particle, with a soft sprite computed in the shader (no texture asset).
+- 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.
-- Sounds are not played: you get keys (`impact_metal`, `shatter_glass`, ...) through `onSound`.
+- 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.
 
 Contracts live in [`@adatechnology/game-contracts`](../game-contracts); the types are re-exported here, so existing imports keep working.
 
@@ -145,9 +145,9 @@ heatColor(temperatureC: number): number // 0xRRGGBB, 0 below ~450 C, dark red ~5
 ```
 
 `RendererOptions`: `scene`, `world`, `quality`, `maxFragments`, `maxParticles`, `fragmentLife`, `groundAt`, `gravity`, `autoSplit`, `onPiece`, `onSound`,
-`explosionLight`, `pointScale` (point size in pixels per metre at 1 m; about `viewportHeight / (2 tan(fov / 2))`, default 700).
+`vfx` (shared effects world), `camera` (of the own world, when `vfx` is not given), `pointScale` (point size in pixels per metre at 1 m; about `viewportHeight / (2 tan(fov / 2))`, default 700).
 
-`DestructionRenderer`: `bind`, `unbind`, `makePiece`, `pieces`, `piece`, `impulse`, `update`, `emit`, `explode`, `clear`, `restore`, `stats`, `dispose`.
+`DestructionRenderer`: `bind`, `unbind`, `makePiece`, `pieces`, `piece`, `impulse`, `update`, `emit`, `explode(point, energy, radius, { effect?, direction?, visual? })` (`visual: false` keeps only the shove and the sound, for a host that played the effect itself), `clear`, `restore`, `stats`, `dispose`.
 `clear()` removes fragments, decals, puddles and particles from the scene and restores every bound mesh; `dispose()` also unsubscribes from the world.
 
 ## Português
@@ -155,7 +155,7 @@ heatColor(temperatureC: number): number // 0xRRGGBB, 0 below ~450 C, dark red ~5
 Renderizador three.js para o `@adatechnology/game-destruction`. O núcleo decide o que cada golpe faz e devolve eventos; este pacote desenha: amassados
 nos vértices, furos de bala e rachaduras, carbonização e brilho de calor, derretimento e poças, fragmentos com física leve, peças soltas e partículas
 em pool (fogo, fumaça, faíscas, poeira, cacos, lascas). Geometria e materiais só são clonados na primeira mudança visual de uma malha, e `restore` /
-`clear` devolvem os originais. Os sons não são tocados: o jogo recebe chaves (`impact_metal`, `shatter_glass`, ...) em `onSound`.
+`clear` devolvem os originais. O renderer não toca nada: o jogo recebe chaves (`impact_metal`, `shatter_glass`, `burn_loop`, `burn_end`, ...) em `onSound`; `createDestructionSound(engine)` é o banco de sons delas no `game-audio` (sons dos materiais da Cena de Arte, o estouro do jogo, o laço de fogo e a tabela chave → som, trocável).
 
 Uso: `specFromObject3D(THREE, modelo)` gera a especificação e o mapa parte -> malhas; registre no mundo com `world.add(spec)`, ligue com
 `renderer.bind(id, modelo, { parts })` e chame `world.update(dt)` e `renderer.update(dt)` a cada quadro. Com `quality: 'low'` os orçamentos de

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import * as THREE_NS from 'three';
 import { Vec3, DebrisKind, DestructionWorld, MaterialId, DestructibleSpec } from '@adatechnology/game-destruction';
 export { Quat, Vec3 } from '@adatechnology/game-destruction';
+import { VfxWorld, SpriteKind } from '@adatechnology/game-vfx';
+import { LoopRecipe, SoundBank, SoundRecipe, AudioEngine } from '@adatechnology/game-audio';
+import { Vec3 as Vec3$1 } from '@adatechnology/game-contracts';
 
 /**
  * Public types of @adatechnology/game-destruction-three.
@@ -33,10 +36,17 @@ interface RendererOptions {
     autoSplit?: boolean;
     /** Called when a loose piece is created (the bench registers it as grabbable). */
     onPiece?: (piece: Piece) => void;
-    /** Called when a sound should play; the host maps keys to audio (e.g. `impact_metal`, `shatter_glass`, `ignite`, `explode`). */
+    /** 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;
-    /** A point light flashes on explosions (default true; costs one light). */
-    explosionLight?: boolean;
+    /**
+     * 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`.
+     */
+    vfx?: VfxWorld;
+    /** Which effect each destruction event plays (default `EVENT_EFFECTS_MAP` of `@adatechnology/game-vfx`): `spall`, `stage`, `expose`, `collapse`. Add, change or take out entries to tune it. */
+    eventEffects?: Readonly<Record<string, string | Readonly<Record<string, string>>>>;
+    /** Camera of the own effects world (distance LOD, shake); only read when `vfx` is not given. Default: a camera at the origin. */
+    camera?: THREE_NS.Camera;
     /**
      * Particle size scale in pixels per metre at one metre from the camera, roughly `viewportHeight / (2 * tan(fov / 2))` (default 700). Set it
      * when the viewport is much smaller or larger than about 720 px tall so smoke and fire keep their physical size.
@@ -85,6 +95,15 @@ interface Piece {
     /** While held by a player the renderer does not integrate it. */
     held: boolean;
 }
+/** Options of `DestructionRenderer.explode`. */
+interface ExplodeOptions {
+    /** Id of the effect to play (an explosive id of the effects catalogue). Default `generic`. */
+    readonly effect?: string;
+    /** Where the blast is aimed (a shaped charge). */
+    readonly direction?: Vec3;
+    /** `false`: the host drew the blast, only the shove and the sound are left. Default `true`. */
+    readonly visual?: boolean;
+}
 interface DestructionRenderer {
     /** Attach a world object to its three.js root. */
     bind(objectId: string, root: Object3D, options?: BindOptions): void;
@@ -102,8 +121,12 @@ interface DestructionRenderer {
     update(dt: number): void;
     /** Emit particles directly (muzzle flashes, extinguisher foam, tool sparks). */
     emit(kind: DebrisKind | 'fire' | 'flash' | 'foam', point: Vec3, normal: Vec3, count: number, speed?: number): void;
-    /** Draw a blast that has no exploding part (a grenade, a rocket): flash, fire, smoke, light, sound and a shove on pieces in range. Call it next to `world.explode`, which emits no event of its own. */
-    explode(point: Vec3, energy: number, radius: number): void;
+    /**
+     * Draw a blast that has no exploding part (a grenade, a rocket): the effect (`options.effect`, an id of the effects catalogue, else `generic`
+     * scaled by the radius), sound and a shove on pieces in range. Call it next to `world.explode`, which emits no event of its own. A host that
+     * already played the effect itself passes `visual: false` and keeps only the shove and the sound.
+     */
+    explode(point: Vec3, energy: number, radius: number, options?: ExplodeOptions): void;
     /** Remove every fragment, decal and particle, restore every bound mesh to its original geometry and colours. */
     clear(): void;
     /** Restore one object (after `world.reset`). */
@@ -166,7 +189,70 @@ declare function specFromObject3D(THREE: ThreeNamespace, root: Object3D, options
  */
 declare function heatColor(temperatureC: number): number;
 
-/** Every particle kind the renderer can emit. */
-type ParticleKind = DebrisKind | 'fire' | 'flash' | 'foam';
+/** The art scene's destruction sounds, each with the team name in its `sources`. */
+declare const SCENE_SOUNDS: readonly SoundRecipe[];
+/** The game's explosion thump: a sine from 70 to 28 Hz over 1.2 s, `1.4 / (1 + d² × 0.002)` (jogo L68278). */
+declare const EXPLOSION_BOOM: SoundRecipe;
+/**
+ * The fire loop of the art scene (cena L1316): noise through a 1800 Hz bandpass (Q 0.6) into a gain that starts at 0. The page never raises it, so it is
+ * silent there; here `createDestructionSound` raises it while something burns (the level is the kit's, in `fire`).
+ */
+declare const BURN_LOOP: LoopRecipe;
+declare const DESTRUCTION_SOUND_BANK: SoundBank;
+
+/**
+ * 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).
+ */
+type SoundKeyRule = {
+    readonly sound: string;
+    readonly params?: Readonly<Record<string, number>>;
+    readonly volumeScale?: number;
+    readonly above?: {
+        readonly volume: number;
+        readonly sound: string;
+    };
+};
+type DestructionSoundStyle = 'art_scene' | 'game';
+/**
+ * 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
+ * which key is the kit's choice (the teams call the sounds, not the renderer's keys), so it is data: `keys` replaces any entry.
+ */
+declare const DESTRUCTION_SOUND_KEYS: Readonly<Record<DestructionSoundStyle, Readonly<Record<string, SoundKeyRule>>>>;
+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. */
+    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?: {
+        readonly perFire?: number;
+        readonly max?: number;
+    };
+    /** Burn loop on or off (default on). */
+    readonly burnLoop?: boolean;
+};
+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;
+    /** Parts burning now. */
+    readonly burning: () => number;
+    dispose(): void;
+};
+declare const DEFAULT_FIRE: {
+    readonly perFire: 0.05;
+    readonly max: 0.2;
+};
+/**
+ * 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.
+ */
+declare function createDestructionSound(engine: AudioEngine, options?: DestructionSoundOptions): DestructionSound;
+
+/** Every particle kind the renderer can emit (the game's sprite kinds, see `@adatechnology/game-vfx`). */
+type ParticleKind = SpriteKind;
 
-export { type BindOptions, type DestructionRenderer, type Mesh, type MeshRange, type Object3D, type PartHint, type ParticleKind, type Piece, type Quality, type RendererOptions, type SpecFromObjectOptions, type SpecFromObjectResult, type ThreeNamespace, createDestructionRenderer, heatColor, specFromObject3D };
+export { BURN_LOOP, type BindOptions, DEFAULT_FIRE, DESTRUCTION_SOUND_BANK, DESTRUCTION_SOUND_KEYS, type DestructionRenderer, type DestructionSound, type DestructionSoundOptions, type DestructionSoundStyle, EXPLOSION_BOOM, type ExplodeOptions, type Mesh, type MeshRange, type Object3D, type PartHint, type ParticleKind, type Piece, type Quality, type RendererOptions, SCENE_SOUNDS, type SoundKeyRule, type SpecFromObjectOptions, type SpecFromObjectResult, type ThreeNamespace, createDestructionRenderer, createDestructionSound, heatColor, specFromObject3D };