@woosh/meep-engine 3.43.0 → 3.44.0

package/src/engine/physics/cloth/build/cloth_proxy_from_mesh.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../../shade/renderer/animation/Skin.js").Skin} Skin
+ * @typedef {import("./cloth_proxy_from_joints.js").ClothProxyBuildResult} ClothProxyBuildResult
+ */
+/**
+ * # Building a proxy for a sheet: one joint per vertex, and the triangles between them
+ *
+ * A sheet — a flag, a banner, a curtain, a cloth dropped on a sphere — is a
+ * triangle mesh, and what drives its render mesh is a skin with **one joint per
+ * vertex**: each vertex weighted wholly to its own joint, every joint hanging
+ * straight off one root joint. That skin is ordinary; the engine draws it the way
+ * it draws any skinned model, and cloth moves its joints the way it moves a
+ * cape's. This builds the proxy for it — §11.3's steps 4, 6 and 10 over a mesh
+ * that is already welded and already a particle set:
+ *
+ * - **a hard stretch row per edge**, every edge of every triangle once;
+ * - **a hinge per interior edge** — the shared edge, then the wing opposite it in
+ *   each triangle, which is `cloth_bend_row`'s stencil order. The stencil is built
+ *   here rather than read through `bt_edge_read_diamond`, whose quad puts the
+ *   shared edge in the middle;
+ * - the bind pose of every joint in the root joint's, and the root joint as the
+ *   frame the sheet is simulated in.
+ *
+ * **Nothing is pinned.** Which vertices are held is the scene's business — a pole
+ * holding a flag's hoist, a hook holding a ribbon's top — and a `ClothPin` names
+ * them by particle, which is their position in `joint_names`.
+ *
+ * ## What is refused, and why at build
+ *
+ * §7 P8: a triangle with no area (no normal, no stencil), an edge three triangles
+ * share (no single hinge across it), joints that do not all hang from the same
+ * root, and a name the skin does not have. Each is an authoring mistake, and each
+ * comes back as a message naming it rather than as a sheet that misbehaves.
+ *
+ * ## The rest shape is assumed flat where it bends
+ *
+ * The hinge is §6's quadratic stencil, which annihilates a planar rest shape and
+ * every affine image of it and reads a curved rest as already bent (§18). A flag,
+ * a sheet and a circle skirt cut flat are what this serves; a tube is not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Build a proxy from the joints of a sheet's skin and the triangles over them.
+ *
+ * @param {Prefab} prefab the compiled model the joints are nodes of
+ * @param {Skin} skin one of the prefab's skins — joints as node indices
+ * @param {string[]} joint_names one joint per vertex; particle `i` is `joint_names[i]`
+ * @param {Int32Array|number[]} triangles indices into `joint_names`, 3 per triangle
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {ClothProxyBuildResult}
+ */
+export function cloth_proxy_from_mesh(prefab: Prefab, skin: Skin, joint_names: string[], triangles: Int32Array | number[], { name }?: {
+    name?: string;
+}): ClothProxyBuildResult;
+export type Prefab = import("../../../graphics3/prefab/Prefab.js").Prefab;
+export type Skin = import("../../../../shade/renderer/animation/Skin.js").Skin;
+export type ClothProxyBuildResult = import("./cloth_proxy_from_joints.js").ClothProxyBuildResult;
+//# sourceMappingURL=cloth_proxy_from_mesh.d.ts.map

package/src/engine/physics/cloth/build/cloth_proxy_from_mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_proxy_from_mesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_mesh.js"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;GAUG;AACH,8CARW,MAAM,QACN,IAAI,eACJ,MAAM,EAAE,aACR,UAAU,GAAC,MAAM,EAAE;IAEF,IAAI,GAArB,MAAM;IACJ,qBAAqB,CA8LjC;qBApPY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;oCAC3D,OAAO,8BAA8B,EAAE,qBAAqB"}

package/src/engine/physics/cloth/build/cloth_proxy_from_mesh.js

@@ -0,0 +1,280 @@
+import { ClothProxy } from "./ClothProxy.js";
+import { cloth_bind_in_frame } from "./cloth_bind_in_frame.js";
+
+/**
+ * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../../shade/renderer/animation/Skin.js").Skin} Skin
+ * @typedef {import("./cloth_proxy_from_joints.js").ClothProxyBuildResult} ClothProxyBuildResult
+ */
+
+/**
+ * # Building a proxy for a sheet: one joint per vertex, and the triangles between them
+ *
+ * A sheet — a flag, a banner, a curtain, a cloth dropped on a sphere — is a
+ * triangle mesh, and what drives its render mesh is a skin with **one joint per
+ * vertex**: each vertex weighted wholly to its own joint, every joint hanging
+ * straight off one root joint. That skin is ordinary; the engine draws it the way
+ * it draws any skinned model, and cloth moves its joints the way it moves a
+ * cape's. This builds the proxy for it — §11.3's steps 4, 6 and 10 over a mesh
+ * that is already welded and already a particle set:
+ *
+ * - **a hard stretch row per edge**, every edge of every triangle once;
+ * - **a hinge per interior edge** — the shared edge, then the wing opposite it in
+ *   each triangle, which is `cloth_bend_row`'s stencil order. The stencil is built
+ *   here rather than read through `bt_edge_read_diamond`, whose quad puts the
+ *   shared edge in the middle;
+ * - the bind pose of every joint in the root joint's, and the root joint as the
+ *   frame the sheet is simulated in.
+ *
+ * **Nothing is pinned.** Which vertices are held is the scene's business — a pole
+ * holding a flag's hoist, a hook holding a ribbon's top — and a `ClothPin` names
+ * them by particle, which is their position in `joint_names`.
+ *
+ * ## What is refused, and why at build
+ *
+ * §7 P8: a triangle with no area (no normal, no stencil), an edge three triangles
+ * share (no single hinge across it), joints that do not all hang from the same
+ * root, and a name the skin does not have. Each is an authoring mistake, and each
+ * comes back as a message naming it rather than as a sheet that misbehaves.
+ *
+ * ## The rest shape is assumed flat where it bends
+ *
+ * The hinge is §6's quadratic stencil, which annihilates a planar rest shape and
+ * every affine image of it and reads a curved rest as already bent (§18). A flag,
+ * a sheet and a circle skirt cut flat are what this serves; a tube is not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Build a proxy from the joints of a sheet's skin and the triangles over them.
+ *
+ * @param {Prefab} prefab the compiled model the joints are nodes of
+ * @param {Skin} skin one of the prefab's skins — joints as node indices
+ * @param {string[]} joint_names one joint per vertex; particle `i` is `joint_names[i]`
+ * @param {Int32Array|number[]} triangles indices into `joint_names`, 3 per triangle
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {ClothProxyBuildResult}
+ */
+export function cloth_proxy_from_mesh(prefab, skin, joint_names, triangles, { name = "" } = {}) {
+    if (prefab === undefined || prefab === null || prefab.isPrefab !== true) {
+        return refuse(`${name}: no prefab`);
+    }
+
+    if (skin === undefined || skin === null) {
+        return refuse(`${name}: no skin`);
+    }
+
+    const joints = skin.joints;
+    const parent_of = prefab.parent;
+    const name_of = prefab.name;
+
+    /**
+     * @type {Map<number, number>} node index → position in the skin's joints
+     */
+    const index_of = new Map();
+
+    /**
+     * @type {Map<string, number>}
+     */
+    const by_name = new Map();
+
+    for (let i = 0; i < joints.length; i++) {
+        index_of.set(joints[i], i);
+
+        const joint_name = name_of[joints[i]];
+
+        if (joint_name !== "" && !by_name.has(joint_name)) {
+            by_name.set(joint_name, joints[i]);
+        }
+    }
+
+    const particle_count = joint_names.length;
+
+    if (particle_count === 0) {
+        return refuse(`${name}: no joints`);
+    }
+
+    const node = new Int32Array(particle_count);
+
+    const seen = new Set();
+
+    for (let i = 0; i < particle_count; i++) {
+        const found = by_name.get(joint_names[i]);
+
+        if (found === undefined) {
+            return refuse(`${name}: the skin has no joint named "${joint_names[i]}"`);
+        }
+
+        if (seen.has(found)) {
+            return refuse(`${name}: "${joint_names[i]}" is named twice`);
+        }
+
+        seen.add(found);
+
+        node[i] = found;
+    }
+
+    // One root for every vertex joint: the frame, and what the write-back
+    // expresses each joint against.
+    const frame_node = parent_of[node[0]];
+
+    for (let i = 1; i < particle_count; i++) {
+        if (parent_of[node[i]] !== frame_node) {
+            return refuse(
+                `${name}: "${joint_names[0]}" hangs from "${name_of[frame_node] ?? 'nothing'}" and "${joint_names[i]}"`
+                + ` from "${name_of[parent_of[node[i]]] ?? 'nothing'}" — a sheet's joints hang from one root joint`
+            );
+        }
+    }
+
+    if (frame_node < 0 || !index_of.has(frame_node)) {
+        return refuse(`${name}: the sheet's joints hang from "${name_of[frame_node] ?? 'nothing'}", which is not a joint of this skin`);
+    }
+
+    const triangle_count = Math.floor(triangles.length / 3);
+
+    if (triangle_count * 3 !== triangles.length) {
+        return refuse(`${name}: ${triangles.length} triangle indices is not a whole number of triangles`);
+    }
+
+    const pose = cloth_bind_in_frame(prefab, frame_node);
+
+    const rest_position = new Float32Array(particle_count * 3);
+    const rest_rotation = new Float32Array(particle_count * 4);
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = pose(node[i]);
+
+        rest_position[i * 3] = p[0];
+        rest_position[i * 3 + 1] = p[1];
+        rest_position[i * 3 + 2] = p[2];
+
+        rest_rotation[i * 4] = p[3];
+        rest_rotation[i * 4 + 1] = p[4];
+        rest_rotation[i * 4 + 2] = p[5];
+        rest_rotation[i * 4 + 3] = p[6];
+    }
+
+    /**
+     * Every edge once, keyed by its two particles, with the wing opposite it in
+     * each triangle that has it.
+     * @type {Map<number, {a: number, b: number, wings: number[]}>}
+     */
+    const edges = new Map();
+
+    for (let t = 0; t < triangle_count; t++) {
+        const i0 = triangles[t * 3];
+        const i1 = triangles[t * 3 + 1];
+        const i2 = triangles[t * 3 + 2];
+
+        for (const index of [i0, i1, i2]) {
+            if (!(index >= 0 && index < particle_count)) {
+                return refuse(`${name}: triangle ${t} names particle ${index} of ${particle_count}`);
+            }
+        }
+
+        if (twice_area(rest_position, i0, i1, i2) <= 0) {
+            return refuse(
+                `${name}: triangle ${t} ("${joint_names[i0]}", "${joint_names[i1]}", "${joint_names[i2]}") has no area,`
+                + ` so no normal and no hinge across it`
+            );
+        }
+
+        const corners = [i0, i1, i2];
+
+        for (let k = 0; k < 3; k++) {
+            const a = corners[k];
+            const b = corners[(k + 1) % 3];
+            const wing = corners[(k + 2) % 3];
+
+            const lo = a < b ? a : b;
+            const hi = a < b ? b : a;
+
+            const key = lo * particle_count + hi;
+
+            let edge = edges.get(key);
+
+            if (edge === undefined) {
+                edge = { a: lo, b: hi, wings: [] };
+
+                edges.set(key, edge);
+            }
+
+            edge.wings.push(wing);
+
+            if (edge.wings.length > 2) {
+                return refuse(
+                    `${name}: the edge "${joint_names[lo]}"–"${joint_names[hi]}" is shared by more than two triangles,`
+                    + ` so there is no one hinge across it`
+                );
+            }
+        }
+    }
+
+    const edge = [];
+    const hinge = [];
+
+    for (const { a, b, wings } of edges.values()) {
+        edge.push(a, b);
+
+        if (wings.length === 2) {
+            hinge.push(a, b, wings[0], wings[1]);
+        }
+    }
+
+    const particle_name = joint_names.slice();
+
+    return {
+        proxy: ClothProxy.from({
+            name,
+            joint: Array.from(node, n => index_of.get(n)),
+            output: new Uint8Array(particle_count).fill(1),
+            // every joint hangs straight off the frame
+            parent: new Int32Array(particle_count).fill(-1),
+            edge,
+            skip: [],
+            hinge,
+            triangle: Int32Array.from(triangles),
+            frame: index_of.get(frame_node),
+            rest_position,
+            rest_rotation,
+            particle_name
+        }),
+        groups: [],
+        error: ""
+    };
+}
+
+/**
+ * Twice the area of a triangle of the rest pose.
+ *
+ * @param {Float32Array} position
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number}
+ * @private
+ */
+function twice_area(position, a, b, c) {
+    const ux = position[b * 3] - position[a * 3];
+    const uy = position[b * 3 + 1] - position[a * 3 + 1];
+    const uz = position[b * 3 + 2] - position[a * 3 + 2];
+
+    const vx = position[c * 3] - position[a * 3];
+    const vy = position[c * 3 + 1] - position[a * 3 + 1];
+    const vz = position[c * 3 + 2] - position[a * 3 + 2];
+
+    return Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx);
+}
+
+/**
+ * @param {string} error
+ * @returns {ClothProxyBuildResult}
+ * @private
+ */
+function refuse(error) {
+    return { proxy: null, groups: [], error };
+}

package/src/engine/physics/cloth/collider/cloth_collider_sdf.d.ts

@@ -36,7 +36,7 @@
  * The rotation is an `nlerp` rather than a `slerp`: it is not constant angular
  * velocity, and over the fraction of a fixed step it is indistinguishable from
  * one — the two differ by under a thousandth of a degree at the half-radian per
- * step `CLOTH_ANCHOR_ROTATION_LIMIT` already treats as a spin.
+ * step `CLOTH_FRAME_ROTATION_LIMIT` already treats as a spin.
  *
  * @param {Float32Array|Float64Array} table
  * @param {number} count records in `table`

package/src/engine/physics/cloth/collider/cloth_collider_sdf.js

@@ -72,7 +72,7 @@ import { ClothColliderKind } from "./ClothColliderKind.js";
  * The rotation is an `nlerp` rather than a `slerp`: it is not constant angular
  * velocity, and over the fraction of a fixed step it is indistinguishable from
  * one — the two differ by under a thousandth of a degree at the half-radian per
- * step `CLOTH_ANCHOR_ROTATION_LIMIT` already treats as a spin.
+ * step `CLOTH_FRAME_ROTATION_LIMIT` already treats as a spin.
  *
  * @param {Float32Array|Float64Array} table
  * @param {number} count records in `table`

package/src/engine/physics/cloth/ecs/Cloth.d.ts

@@ -6,22 +6,30 @@
  *
  * ```js
  * rope_top.add(Cloth.from(ClothDynamics.ROPE));
+ * rope_top.add(ClothPin.from({ cloth: rope_top, particles: [0] }));
  * ```
  *
- * **The anchor is the entity the component is on**, and nothing names anything.
- * The particle set is that entity's own transform subtree, walked through
- * `TransformAttachmentSystem#findChildrenOf` — the parent-to-children index the
- * engine already maintains. Put `Cloth` on the top link of a rope and you get
- * the rope; put it on a node with several chains under it and you get all of
- * them in **one coupled solve**, which is what makes self-collision between
- * them work when it arrives.
+ * **The entity the component is on is the cloth's frame**, and nothing names
+ * anything. The particle set is that entity and its transform subtree, walked
+ * through `TransformAttachmentSystem#findChildrenOf` — the parent-to-children
+ * index the engine already maintains — with the entity itself as particle 0.
+ * Put `Cloth` on the top link of a rope and you get the rope; put it on a node
+ * with several chains under it and you get all of them in **one coupled
+ * solve**, which is what makes self-collision between them work.
+ *
+ * **What holds it is a separate question**, answered by {@link ClothPin}s: any
+ * number of them, on any entities, holding any particles, added and removed
+ * while it runs. The rope above is held at its top by its own entity; a rope
+ * bridge is that plus a post holding its last link; a rope nothing holds falls.
+ * The frame is only what the cloth is simulated in and what §7 P7's inertia is
+ * measured against — the entity the cloth rides, which cloth reads and never
+ * writes.
  *
  * Two rules keep the walk unambiguous:
  *
  * - **A nested `Cloth` claims its own subtree.** The walk stops when it meets
  *   another `Cloth`, so independent hanging parts of one prop partition
- *   naturally. The two solves are ordered by hierarchy depth, so the outer one
- *   has written the inner one's anchor before the inner one reads it.
+ *   naturally, each read one fixed step after the cloth above it wrote it.
  * - **{@link ClothExclude}** prunes a subtree from the walk, for the rig with a
  *   non-simulated attachment point in the middle of a chain.
  *

package/src/engine/physics/cloth/ecs/Cloth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cloth.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/Cloth.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAkDI;;;;;;;;;OASG;IACH,uBATW,aAAa;QAGC,KAAK,GAAnB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACQ,IAAI,GAAlB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACJ,KAAK,CA6BjB;IArFD;;;;;;;OAOG;IACH,UAFU,aAAa,CAEQ;IAE/B;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,cAHW,MAAM,GAAC,UAAU,GACf,OAAO,CAInB;IAyCD;;;OAGG;IACH,cAHW,KAAK,GACH,OAAO,CAgBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAUlB;IAED;;;;;;;;;;;;;;;;;MAQC;IAED;;OAEG;IACH,kDAFW,MAAM,QAehB;IAED,mBAEC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;;;;8BAxM6B,oBAAoB;2BACvB,iBAAiB"}
+{"version":3,"file":"Cloth.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/Cloth.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IAkDI;;;;;;;;;OASG;IACH,uBATW,aAAa;QAGC,KAAK,GAAnB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACQ,IAAI,GAAlB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACJ,KAAK,CA6BjB;IArFD;;;;;;;OAOG;IACH,UAFU,aAAa,CAEQ;IAE/B;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,cAHW,MAAM,GAAC,UAAU,GACf,OAAO,CAInB;IAyCD;;;OAGG;IACH,cAHW,KAAK,GACH,OAAO,CAgBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAUlB;IAED;;;;;;;;;;;;;;;;;MAQC;IAED;;OAEG;IACH,kDAFW,MAAM,QAehB;IAED,mBAEC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;;;;8BAhN6B,oBAAoB;2BACvB,iBAAiB"}