@adatechnology/game-destruction-three 0.7.2 → 0.8.0

package/README.md

@@ -71,6 +71,12 @@ renderer.impulse(id, [0, 40, -120], [2, 0.6, -3])
 equals a part id, else by the part box that contains the mesh centre. `specFromObject3D` reads `userData.destructionMaterial`,
 `destructionPart` (a part id, or `{ id, material?, parent?, kind? }`: `parent` + `kind` attach the part to its parent with a joint of that kind), `destructionIgnore`, `destructionTags` and `hollow`.
 
+For picking, `bind` and the loose pieces write back to the meshes: every mesh of a part has `userData.destructionPart` (the part id) and
+`userData.destructionObject` (the id of the world object the part belongs to now; a loose piece made by `splitGroup` has an id of its own, the same one
+`renderer.piece(id)` and `world.state(id)` use), also on the mesh a vertex-range part gets when it leaves a merged mesh. A raycast hit goes to
+`world.hitPart(hit.object.userData.destructionObject, hit.object.userData.destructionPart, ...)`. Purely visual meshes (fracture fragments, decals, ground
+stains) have `userData.destructionDebris = true`: skip them when picking. Parts drawn by a range of a merged mesh share it, so the merged mesh itself carries no part id.
+
 ### Parts of a merged mesh
 
 A building or a baked model often has one merged mesh for many parts. Bind each part by the vertex range it occupies (`{ mesh, range: [v0, v1] }`,
@@ -114,6 +120,10 @@ loose meshes. An invalid range (outside the geometry or empty) throws from `bind
 | `leak` | stream of drops (or a faint puff for gas) from the hole while the part still has liters | |
 | `explode` | flash, fire, smoke, dust and sparks, a pooled `PointLight` pulse, impulses on pieces and fragments in range | `explode` |
 
+`settle` (an object with `DestructibleSpec.soil` settled or tilted): on the first one the renderer moves the children of the bound root under a group named
+`destruction-soil` and gives it `ObjectState.soil.offset`, updated every frame while the soil yields; the root keeps the host's pose, which is what
+`syncTransform` keeps sending to the world.
+
 `world.explode` emits no event of its own (only a part with `explodes` does), so a host that detonates a grenade or rocket calls `renderer.explode(point, energy, radius)` next to it to get the same flash, fire, smoke, light, sound and shove.
 
 Pieces report hard landings: above 3 m/s the renderer calls `world.hit(id, { type: 'blunt', energy: 0.5 m v^2, radius: 0.08, direction: [0, -1, 0], source: 'fall' })`

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as THREE_NS from 'three';
 import { Vec3, DebrisKind, HitResult, DestructionWorld, MaterialId, DestructibleSpec } from '@adatechnology/game-destruction';
 export { Quat, Vec3 } from '@adatechnology/game-destruction';
+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 { Vec3 as Vec3$1 } from '@adatechnology/game-contracts';
 
 /**
  * Public types of @adatechnology/game-destruction-three.
@@ -36,6 +36,18 @@ interface RendererOptions {
     autoSplit?: boolean;
     /** Called when a loose piece is created (the bench registers it as grabbable). */
     onPiece?: (piece: Piece) => void;
+    /**
+     * The numbers of the shove a blast gives to the pieces (`BlastShoveOptions` of game-contracts: how much of the energy becomes speed, the fastest throw, the lift, the falloff).
+     * The defaults give the pieces the speed the blast always gave them, with the cap lowered to 20 m/s.
+     */
+    blastShove?: BlastShoveOptions;
+    /**
+     * Bound objects that have no piece but that a blast may move anyway (a fridge, a table: heavy, so not grabbable, but not nailed down either): when this answers true for an object a blast
+     * reaches with enough speed, the renderer makes it a piece (`makePiece`) and shoves it, and tells `onLoosened`. Without it only the pieces move. Never answer true for a wall or a fixture.
+     */
+    shoveable?: (objectId: string) => boolean;
+    /** Called when a blast made a bound object a piece (see `shoveable`). */
+    onLoosened?: (objectId: string, piece: Piece) => 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;
     /**
@@ -142,6 +154,8 @@ interface DestructionRenderer {
         pieces: number;
         decals: number;
     };
+    /** Meshes that use the materials of the hole, patch and crack decals, to render once so that the first hit does not build their shader programs in the middle of a frame. */
+    warmUpProbes(): WarmUpProbes;
     /** Bars of exposed rebar drawn now (`expose` events; one instanced mesh per part). */
     rebarCount(): number;
     dispose(): void;
@@ -180,9 +194,11 @@ interface PartHint {
 }
 /**
  * Build a `DestructibleSpec` from a three.js object: one part per mesh (meshes sharing `userData.destructionPart` become one part), each an
- * axis-aligned box in the root's space (rotation omitted), with the material taken from `options.materialOf`, `userData.destructionMaterial`
+ * axis-aligned box in metres in the root's frame (its position and rotation removed, its world scale kept; rotation omitted), with the material taken from `options.materialOf`, `userData.destructionMaterial`
  * or a guess from the names. Tiny meshes are merged into the part they overlap most; joints are inferred from touching parts.
  *
+ * `userData.destructionContains` (`{ fluid, liters }`) makes the part a container: a hole through it leaks. `root.userData.destructionMass` (kg) fixes the total mass, split between the parts in proportion to their volume, density and fill.
+ * A mesh with `userData.destructionSkin` (a label, a coat) joins the part it overlaps most instead of becoming a part: it stays drawn and bound to that part (decals, dents) but never breaks off.
  * Meshes that are invisible or have `userData.destructionIgnore` (or sit under such an object) are skipped. The result also tells which meshes
  * became which part, ready to be passed to `bind`.
  */