@adatechnology/game-destruction-three 0.1.1 → 0.2.0

package/README.md

@@ -71,6 +71,27 @@ 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`.
 
+### 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] }`,
+end exclusive; a part value can also be an array mixing meshes and ranges):
+
+```js
+renderer.bind(houseId, houseRoot, { parts: {
+  wall_north: { mesh: merged, range: [0, 1280] },
+  wall_south: { mesh: merged, range: [1280, 2610] },
+  door: doorMesh,                      // plain meshes still work
+} })
+```
+
+For indexed geometry the faces whose three vertices all lie in the range belong to the part; for non-indexed geometry the range is the part's
+triangles. Dents move only the range's vertices; char and heat go to the range's vertex colours (the mesh gets a `color` attribute, and a cloned
+material with `vertexColors`, when it has none); hole and crack decals stay on the part; melt squashes and widens only the range. When the part
+detaches or collapses (`detach` and `collapse` events), its faces are copied, with their dents and colours and the merged mesh's transform and
+material, into a new mesh that becomes the loose piece, and the range is collapsed to a point in the merged mesh so it vanishes there. A broken,
+melted or burnt-out part vanishes the same way. `restore` and `clear` put the merged mesh's original geometry and material back and remove the
+loose meshes. An invalid range (outside the geometry or empty) throws from `bind`.
+
 ## What each event draws
 
 | Event | Visual | Sound key |

package/dist/index.d.ts

@@ -43,13 +43,29 @@ interface RendererOptions {
      */
     pointScale?: number;
 }
+/**
+ * A part drawn by a range of the vertices of a mesh it shares with other parts (a merged house, a baked car body). `range` is `[v0, v1)`: vertex
+ * indices of the mesh's geometry, the end exclusive. For indexed geometry the faces whose three vertices all lie in the range belong to the part;
+ * for non-indexed geometry the range is the part's triangles (three vertices each).
+ *
+ * Dents, char and heat colours (through vertex colours: the mesh gets a `color` attribute and its material `vertexColors` when it has none) and
+ * melt change only that range, and hole and crack decals are attached to the part. When the part detaches or collapses, its faces are copied
+ * into a new mesh with the merged mesh's transform and material (a loose piece) and the range is collapsed to a point in the merged mesh, so it
+ * disappears from there. A broken, melted or burnt-out part collapses too. `restore` and `clear` give the merged mesh its original geometry and
+ * material back and remove the loose meshes.
+ */
+interface MeshRange {
+    mesh: Mesh;
+    /** Vertex index range `[v0, v1)` of `mesh.geometry`. */
+    range: [number, number];
+}
 /** Options of `bind`. */
 interface BindOptions {
     /**
-     * Part id -> meshes that draw it. When omitted, every Mesh under the root with `userData.destructionPart` (or whose name equals a part id) is
+     * Part id -> meshes that draw it (a mesh or group, a list of them, a `MeshRange`, or a list mixing both). When omitted, every Mesh under the root with `userData.destructionPart` (or whose name equals a part id) is
      * used; meshes with neither are matched to the part whose box contains the mesh's bounding-box centre.
      */
-    parts?: Record<string, Object3D | Object3D[]>;
+    parts?: Record<string, Object3D | MeshRange | Array<Object3D | MeshRange>>;
     /** Keep the world transform in sync from the root's matrixWorld every update (default true). */
     syncTransform?: boolean;
 }
@@ -149,4 +165,4 @@ declare function heatColor(temperatureC: number): number;
 /** Every particle kind the renderer can emit. */
 type ParticleKind = DebrisKind | 'fire' | 'flash' | 'foam';
 
-export { type BindOptions, type DestructionRenderer, type Mesh, 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 Mesh, type MeshRange, type Object3D, type PartHint, type ParticleKind, type Piece, type Quality, type RendererOptions, type SpecFromObjectOptions, type SpecFromObjectResult, type ThreeNamespace, createDestructionRenderer, heatColor, specFromObject3D };