@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -0,0 +1,107 @@
+import { pose3_compose_array } from "../../../../core/geom/3d/pose/pose3_compose_array.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../../ecs/transform/Transform64.js";
+
+/**
+ * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
+ */
+
+/**
+ * Each node's bind pose relative to the frame node's, composed from the
+ * prefab's local rest poses down from the frame, `[tx, ty, tz, qx, qy, qz, qw]`.
+ * Every node asked about hangs below the frame.
+ *
+ * Both proxy builders bake their rest pose this way — in the frame joint's own
+ * bind pose — so that a re-seed reads what was authored rather than what the
+ * solver left on the joints.
+ *
+ * Rigid, as every pose cloth holds is: a local scale is not applied. That is
+ * not a convention this can opt out of alone — the write-back is rigid too,
+ * and the GPU applies a parent's scale on top of what cloth writes, so a
+ * scaled bake would draw a scaled link twice over. A builder refuses a rig
+ * where it would matter, with {@link cloth_bind_scaled_above}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ *
+ * @param {Prefab} prefab
+ * @param {number} frame
+ * @returns {function(number): Float64Array}
+ */
+export function cloth_bind_in_frame(prefab, frame) {
+    /**
+     * @type {Map<number, Float64Array>}
+     */
+    const known = new Map();
+
+    known.set(frame, Float64Array.from([0, 0, 0, 0, 0, 0, 1]));
+
+    const pose = node => {
+        let answer = known.get(node);
+
+        if (answer !== undefined) {
+            return answer;
+        }
+
+        const above = pose(prefab.parent[node]);
+        const local = prefab.local[node];
+
+        answer = new Float64Array(7);
+
+        pose3_compose_array(
+            answer, 0,
+            answer, 3,
+            above, 0,
+            above, 3,
+            local, TRANSFORM64_TRANSLATION_OFFSET,
+            local, TRANSFORM64_ROTATION_OFFSET
+        );
+
+        known.set(node, answer);
+
+        return answer;
+    };
+
+    return pose;
+}
+
+/**
+ * How far a rest scale may be from one before it is a scale: the tolerance
+ * `prefab_normalize_skin_frames` holds a skin's frame to, for the same reason.
+ * @type {number}
+ */
+const SCALE_TOLERANCE = 1e-4;
+
+/**
+ * The nearest node above `node`, up to and including the prefab's root, whose
+ * rest scale is not one; or -1.
+ *
+ * Cloth simulates and writes back rigid poses, and everything under a scaled
+ * node is drawn scaled: a link below one is simulated at its authored length and
+ * drawn at that times the scale, and a scale above the frame draws the whole
+ * garment at another size than the one its colliders meet. Measured, a 10 cm
+ * chain under a joint scaled by 2: simulated links 0.1, drawn 0.2. A node's own
+ * scale moves nothing cloth places, so it is not asked about.
+ *
+ * @param {Prefab} prefab
+ * @param {number} node
+ * @returns {number}
+ */
+export function cloth_bind_scaled_above(prefab, node) {
+    const parent = prefab.parent;
+
+    for (let above = parent[node]; above >= 0; above = parent[above]) {
+        const local = prefab.local[above];
+
+        if (Math.abs(local[TRANSFORM64_SCALE_OFFSET] - 1) > SCALE_TOLERANCE
+            || Math.abs(local[TRANSFORM64_SCALE_OFFSET + 1] - 1) > SCALE_TOLERANCE
+            || Math.abs(local[TRANSFORM64_SCALE_OFFSET + 2] - 1) > SCALE_TOLERANCE) {
+            return above;
+        }
+    }
+
+    return -1;
+}

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

@@ -6,49 +6,45 @@
  * # Building a proxy for a garment that is already rigged
  *
  * §11.3 lists ten steps and says that for a rigged garment "only steps 5–8 run,
- * over the joint graph rather than a mesh". This is those steps: derive the
- * fixed set, bake the bind pose, resolve names to indices, and validate. Steps
- * 1–4 are mesh work a rigged garment does not need — the artist's joints *are*
- * the particle set and the artist's skin *is* the binding — and steps 9 and 10's
- * mesh half belong to the unrigged path.
+ * over the joint graph rather than a mesh". This is those steps: find what the
+ * garment hangs from, bake the bind pose, resolve names to indices, and
+ * validate. Steps 1–4 are mesh work a rigged garment does not need — the
+ * artist's joints *are* the particle set and the artist's skin *is* the binding.
  *
  * The colouring step (7) is absent for a reason rather than an omission: the
- * cloth's own row builder colours the particle graph inside
- * `ClothState.from`, and it does that for the entity path too. Baking a
- * permutation into the proxy would be a second answer to a question that
- * already has one, and it would have to agree with `cloth_color_particles`
- * exactly or the rows would name the wrong particles.
+ * cloth's own row builder colours the particle graph inside `ClothState.from`.
  *
- * ## The fixed set falls out of the topology
+ * ## What the garment hangs from falls out of the topology
  *
- * A joint whose parent is outside the named set is a joint the garment hangs
- * from, and **every one of them must hang from the same bone** — that bone is
- * the anchor. §11.3 step 5 derives the fixed set from *skin weights* instead,
- * which is the right rule for the unrigged path, where the particles are mesh
- * vertices and there is no joint tree to read. For a rigged garment the tree is
- * the answer and the weights are not needed.
+ * A joint whose parent is outside the named set is a root of the garment, and
+ * its parent is a bone the garment hangs from. Every such bone becomes a
+ * particle cloth reads and never writes, with the links to its roots the first
+ * links of the fabric — so a cape hanging from one shoulder bone is the cape it
+ * always was, and one hanging from both shoulders and the spine is three such
+ * particles rather than a refusal. What holds them is a `ClothPin` on each bone,
+ * and the build hands back exactly the pins to add, as {@link ClothProxyGroup}s:
+ * the topology answers the question, the scene does the holding.
  *
- * Several chains from one bone are one garment and are the point: §3.1's "put
- * `Cloth` on a node with several chains under it and you get all of them in one
- * coupled solve" is exactly a cape's four strips off one shoulder. Chains from
- * *different* bones are refused, because there is then no single frame to
- * simulate in and no single fixed set — that is two garments, and nothing stops
- * a caller building two proxies.
+ * ## The frame is the nearest joint above all of them
  *
- * ## The joint graph is the prefab's
- *
- * A model's hierarchy is its compiled prefab: parent indices, names and rest
- * poses per node, fixed for every placement. The skin handed in is one of the
- * prefab's — joints as node indices — and what comes back holds indices into
- * that skin's joints, which is what a placement's own skin (joints as entities)
- * is indexed by too. Built once per model, like the prefab.
+ * A garment is simulated in the frame of the joint it rides, whose motion §7 P7
+ * softens. For a garment hanging from one bone that is the bone; for one hanging
+ * from several it is the nearest skin joint above all of them, so that a garment
+ * across both shoulders rides the chest between them.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
+/**
+ * One pin to add: a bone the garment hangs from, and its particle.
+ * @typedef {object} ClothProxyGroup
+ * @property {number} joint index into `Skin#joints` of the bone
+ * @property {Int32Array} particles the proxy particles that bone holds
+ */
 /**
  * @typedef {object} ClothProxyBuildResult
  * @property {ClothProxy|null} proxy `null` when the build refused
+ * @property {ClothProxyGroup[]} groups one per bone the garment hangs from; empty when it refused
  * @property {string} error empty when it did not
  */
 /**
@@ -71,11 +67,28 @@ export function cloth_proxy_from_joints(prefab: Prefab, skin: Skin, joint_names:
 }): ClothProxyBuildResult;
 export type Prefab = import("../../../graphics3/prefab/Prefab.js").Prefab;
 export type Skin = import("../../../../shade/renderer/animation/Skin.js").Skin;
+/**
+ * One pin to add: a bone the garment hangs from, and its particle.
+ */
+export type ClothProxyGroup = {
+    /**
+     * index into `Skin#joints` of the bone
+     */
+    joint: number;
+    /**
+     * the proxy particles that bone holds
+     */
+    particles: Int32Array;
+};
 export type ClothProxyBuildResult = {
     /**
      * `null` when the build refused
      */
     proxy: ClothProxy | null;
+    /**
+     * one per bone the garment hangs from; empty when it refused
+     */
+    groups: ClothProxyGroup[];
     /**
      * empty when it did not
      */

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_proxy_from_joints.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_joints.js"],"names":[],"mappings":"AAMA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AACH,gDARW,MAAM,QACN,IAAI,eAEJ,MAAM,EAAE;IAES,IAAI,GAArB,MAAM;IACJ,qBAAqB,CAwMjC;qBA5QY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;;;;;WAkD1D,UAAU,GAAC,IAAI;;;;WACf,MAAM;;2BAvDO,iBAAiB"}
+{"version":3,"file":"cloth_proxy_from_joints.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_joints.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,gDARW,MAAM,QACN,IAAI,eAEJ,MAAM,EAAE;IAES,IAAI,GAArB,MAAM;IACJ,qBAAqB,CA6QjC;qBA9UY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;;;;;;;;WAwC1D,MAAM;;;;eACN,UAAU;;;;;;WAKV,UAAU,GAAC,IAAI;;;;YACf,eAAe,EAAE;;;;WACjB,MAAM;;2BAtDO,iBAAiB"}