@adatechnology/game-destruction-three 0.4.0 → 0.5.0

package/README.md

@@ -5,7 +5,7 @@ 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`.
 
@@ -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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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';
 
 /**
  * Public types of @adatechnology/game-destruction-three.
@@ -35,8 +36,15 @@ interface RendererOptions {
     onPiece?: (piece: Piece) => void;
     /** Called when a sound should play; the host maps keys to audio (e.g. `impact_metal`, `shatter_glass`, `ignite`, `explode`). */
     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 +93,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 +119,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 +187,7 @@ 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';
+/** 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 { type BindOptions, type DestructionRenderer, type ExplodeOptions, 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 };