@adatechnology/game-destruction-three 0.3.3 → 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`.
 
@@ -102,6 +102,9 @@ loose meshes. An invalid range (outside the geometry or empty) throws from `bind
 | `ricochet` | sparks along the reflected direction | `ricochet` |
 | `debris` | a burst of the requested kind (`sparks`, `dust`, `shards`, `splinters`, `chips`, `fibers`, `leaves`, `drips`, `ash`, `smoke`, `steam`) | |
 | `fracture` | part hidden; fragments (boxes, thin irregular prisms for shards) with gravity, ground bounce, settling, sleep and shrink-away; debris burst by style | `shatter_glass`, `crumble`, `splinter`, `impact_*` |
+| `spall` | opaque patch (disc decal) in the colour of the part's core material where a coat came off, under the holes; sits on the face of the mesh the point is nearest to (the thin axis of its world box) | |
+| `stage` (2, with `fragments`) | the unit-sized fragments of the breach fly out with the same physics as `fracture` fragments, the holes of `Fragment.marks` ride on them as dark discs, a dust burst; the part stays drawn (cutting the opening in its faces is left to the house renderer) | `crumble`, `impact_*` |
+| `expose` | the bars as instanced cylinders (radius 4 mm), one mesh per part, replaced by each new `expose`; empty `bars` removes the cage; `renderer.rebarCount()` | |
 | `detach` | with `autoSplit`, each loose group becomes its own `Group` (world transforms kept) and a `Piece` (`onPiece`) | `detach` |
 | `disassemble_progress` | | `unscrew` (throttled) |
 | `ignite` / `extinguish` / `burnout` | fire and smoke from the surface while `part.burning`; steam when put out; ash at burnout; char lerps the colour to the material `charColor`; status `ashes` hides the part and leaves an ash pile | `ignite`, `burn_loop`, `extinguish` |
@@ -142,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`). */
@@ -114,6 +135,8 @@ interface DestructionRenderer {
         pieces: number;
         decals: number;
     };
+    /** Bars of exposed rebar drawn now (`expose` events; one instanced mesh per part). */
+    rebarCount(): number;
     dispose(): void;
 }
 interface SpecFromObjectOptions {
@@ -164,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 };