@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../../shade/renderer/animation/Skin.js").Skin} Skin
+ */
 /**
  * # Building a proxy for a garment that is already rigged
  *
@@ -31,6 +35,14 @@
  * simulate in and no single fixed set — that is two garments, and nothing stops
  * a caller building two proxies.
  *
+ * ## 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.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -46,16 +58,19 @@
  * step 8) and they do not survive: what comes back holds indices into
  * `skin.joints`.
  *
- * @param {Skin} skin the instance's skin, or the asset's — the joint *order* is
+ * @param {Prefab} prefab the compiled model whose hierarchy the joints are nodes of
+ * @param {Skin} skin one of the prefab's skins — joints as node indices. The joint *order* is
  *   what is read, and instantiation preserves it
  * @param {string[]} joint_names the garment's own joints, in any order
  * @param {object} [options]
  * @param {string} [options.name]
  * @returns {ClothProxyBuildResult}
  */
-export function cloth_proxy_from_joints(skin: Skin, joint_names: string[], { name }?: {
+export function cloth_proxy_from_joints(prefab: Prefab, skin: Skin, joint_names: string[], { 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 = {
     /**
      * `null` when the build refused

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,iEALW,MAAM,EAAE;IAES,IAAI,GAArB,MAAM;IACJ,qBAAqB,CAyLjC;;;;;WAzMa,UAAU,GAAC,IAAI;;;;WACf,MAAM;;2BA1CO,iBAAiB"}
+{"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"}

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

@@ -1,256 +1,284 @@
-import {
-    TRANSFORM64_ROTATION_OFFSET,
-    TRANSFORM64_TRANSLATION_OFFSET
-} from "../../../ecs/transform/Transform64.js";
-import { ClothProxy } from "./ClothProxy.js";
-
-/**
- * # 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.
- *
- * 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.
- *
- * ## The fixed set 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.
- *
- * 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.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * @typedef {object} ClothProxyBuildResult
- * @property {ClothProxy|null} proxy `null` when the build refused
- * @property {string} error empty when it did not
- */
-
-/**
- * Build a proxy from the joints of a skin, named.
- *
- * The names are the only place a name appears anywhere in the system (§11.3
- * step 8) and they do not survive: what comes back holds indices into
- * `skin.joints`.
- *
- * @param {Skin} skin the instance's skin, or the asset's — the joint *order* is
- *   what is read, and instantiation preserves it
- * @param {string[]} joint_names the garment's own joints, in any order
- * @param {object} [options]
- * @param {string} [options.name]
- * @returns {ClothProxyBuildResult}
- */
-export function cloth_proxy_from_joints(skin, joint_names, { name = "" } = {}) {
-    if (skin === undefined || skin === null) {
-        return refuse(`${name}: no skin`);
-    }
-
-    const joints = skin.joints;
-
-    /** @type {Map<Node3D, number>} node → index in `skin.joints` */
-    const index_of = new Map();
-
-    for (let i = 0; i < joints.length; i++) {
-        index_of.set(joints[i], i);
-    }
-
-    /** @type {Map<string, Node3D>} */
-    const by_name = new Map();
-
-    for (let i = 0; i < joints.length; i++) {
-        const joint = joints[i];
-
-        if (joint.name !== "" && !by_name.has(joint.name)) {
-            by_name.set(joint.name, joint);
-        }
-    }
-
-    /** @type {Set<Node3D>} the garment's own joints */
-    const members = new Set();
-
-    for (const joint_name of joint_names) {
-        const node = by_name.get(joint_name);
-
-        if (node === undefined) {
-            return refuse(`${name}: the skin has no joint named "${joint_name}"`);
-        }
-
-        if (members.has(node)) {
-            return refuse(`${name}: "${joint_name}" is named twice`);
-        }
-
-        members.add(node);
-    }
-
-    if (members.size === 0) {
-        return refuse(`${name}: no joints`);
-    }
-
-    // Roots: members whose parent is not a member. They all have to hang from
-    // the same bone, and that bone is the anchor.
-    /** @type {Node3D[]} */
-    const roots = [];
-
-    for (const node of members) {
-        if (node.parent === null || !members.has(node.parent)) {
-            roots.push(node);
-        }
-    }
-
-    const anchor_node = roots[0].parent;
-
-    if (anchor_node === null) {
-        return refuse(`${name}: "${roots[0].name}" has no parent, so the garment has nothing to hang from`);
-    }
-
-    for (const root of roots) {
-        if (root.parent !== anchor_node) {
-            return refuse(
-                `${name}: "${roots[0].name}" hangs from "${anchor_node.name}" and "${root.name}" hangs`
-                + ` from "${root.parent === null ? 'nothing' : root.parent.name}" — a garment hangs from one`
-                + ` anchor, and chains from different bones are two garments`
-            );
-        }
-    }
-
-    const anchor = index_of.get(anchor_node);
-
-    if (anchor === undefined) {
-        return refuse(
-            `${name}: "${roots[0].name}" hangs from "${anchor_node.name}", which is not a joint of this skin`
-        );
-    }
-
-    // Parents before children, so one forward pass composes the chain.
-    /** @type {Node3D[]} */
-    const ordered = [];
-
-    /** @type {Map<Node3D, number>} */
-    const position = new Map();
-
-    // Breadth-first from every root at once, which keeps parents before
-    // children across the whole forest rather than only within one chain.
-    const queue = roots.slice();
-
-    while (queue.length > 0) {
-        const node = queue.shift();
-
-        position.set(node, ordered.length);
-        ordered.push(node);
-
-        for (const child of node.children) {
-            if (members.has(child)) {
-                queue.push(child);
-            }
-        }
-    }
-
-    if (ordered.length !== members.size) {
-        const stranded = [];
-
-        for (const node of members) {
-            if (!position.has(node)) {
-                stranded.push(node.name);
-            }
-        }
-
-        return refuse(
-            `${name}: ${stranded.length} joints are unreachable from the anchor (${stranded.join(', ')})`
-        );
-    }
-
-    const joint_count = ordered.length;
-
-    const joint = new Int32Array(joint_count);
-    const joint_parent = new Int32Array(joint_count);
-
-    const rest_position = new Float32Array(joint_count * 3);
-    const rest_rotation = new Float32Array(joint_count * 4);
-
-    const joint_name = [];
-
-    for (let i = 0; i < joint_count; i++) {
-        const node = ordered[i];
-
-        const resolved = index_of.get(node);
-
-        if (resolved === undefined) {
-            return refuse(`${name}: "${node.name}" is not a joint of this skin`);
-        }
-
-        joint[i] = resolved;
-        joint_parent[i] = members.has(node.parent) ? position.get(node.parent) : -1;
-
-        joint_name.push(node.name);
-
-        const local = node.transform_local;
-
-        rest_position[i * 3] = local[TRANSFORM64_TRANSLATION_OFFSET];
-        rest_position[i * 3 + 1] = local[TRANSFORM64_TRANSLATION_OFFSET + 1];
-        rest_position[i * 3 + 2] = local[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-        rest_rotation[i * 4] = local[TRANSFORM64_ROTATION_OFFSET];
-        rest_rotation[i * 4 + 1] = local[TRANSFORM64_ROTATION_OFFSET + 1];
-        rest_rotation[i * 4 + 2] = local[TRANSFORM64_ROTATION_OFFSET + 2];
-        rest_rotation[i * 4 + 3] = local[TRANSFORM64_ROTATION_OFFSET + 3];
-
-        // A joint at no distance from its parent is a zero-length link, which
-        // has no direction for a stretch row's gradient and no rest length for
-        // it to hold. §7 P8 rejects it at build time rather than tolerating it
-        // at runtime, which is what "build-time validation, not runtime
-        // tolerance" means. The root is included: its parent is the anchor.
-        const length = Math.hypot(
-            rest_position[i * 3], rest_position[i * 3 + 1], rest_position[i * 3 + 2]
-        );
-
-        if (length <= 0) {
-            return refuse(
-                `${name}: "${node.name}" sits exactly on its parent, so the link between them`
-                + ` has no length and no direction`
-            );
-        }
-    }
-
-    return {
-        proxy: ClothProxy.from({
-            name,
-            joint,
-            joint_parent,
-            anchor,
-            rest_position,
-            rest_rotation,
-            joint_name
-        }),
-        error: ""
-    };
-}
-
-/**
- * @param {string} error
- * @returns {ClothProxyBuildResult}
- * @private
- */
-function refuse(error) {
-    return { proxy: null, error };
-}
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../../ecs/transform/Transform64.js";
+import { ClothProxy } from "./ClothProxy.js";
+
+/**
+ * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../../shade/renderer/animation/Skin.js").Skin} Skin
+ */
+
+/**
+ * # 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.
+ *
+ * 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.
+ *
+ * ## The fixed set 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.
+ *
+ * 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 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.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @typedef {object} ClothProxyBuildResult
+ * @property {ClothProxy|null} proxy `null` when the build refused
+ * @property {string} error empty when it did not
+ */
+
+/**
+ * Build a proxy from the joints of a skin, named.
+ *
+ * The names are the only place a name appears anywhere in the system (§11.3
+ * step 8) and they do not survive: what comes back holds indices into
+ * `skin.joints`.
+ *
+ * @param {Prefab} prefab the compiled model whose hierarchy the joints are nodes of
+ * @param {Skin} skin one of the prefab's skins — joints as node indices. The joint *order* is
+ *   what is read, and instantiation preserves it
+ * @param {string[]} joint_names the garment's own joints, in any order
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {ClothProxyBuildResult}
+ */
+export function cloth_proxy_from_joints(prefab, skin, joint_names, { 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();
+
+    for (let i = 0; i < joints.length; i++) {
+        index_of.set(joints[i], i);
+    }
+
+    /**
+     * @type {Map<string, number>} name → node index, first of the skin's joints to carry it
+     */
+    const by_name = new Map();
+
+    for (let i = 0; i < joints.length; i++) {
+        const joint = joints[i];
+        const joint_name = name_of[joint];
+
+        if (joint_name !== "" && !by_name.has(joint_name)) {
+            by_name.set(joint_name, joint);
+        }
+    }
+
+    /**
+     * @type {Set<number>} node indices
+     */
+    const members = new Set();
+
+    for (const joint_name of joint_names) {
+        const node = by_name.get(joint_name);
+
+        if (node === undefined) {
+            return refuse(`${name}: the skin has no joint named "${joint_name}"`);
+        }
+
+        if (members.has(node)) {
+            return refuse(`${name}: "${joint_name}" is named twice`);
+        }
+
+        members.add(node);
+    }
+
+    if (members.size === 0) {
+        return refuse(`${name}: no joints`);
+    }
+
+    // Roots: members whose parent is not a member. They all have to hang from
+    // the same bone, and that bone is the anchor.
+    const roots = [];
+
+    for (const node of members) {
+        if (parent_of[node] < 0 || !members.has(parent_of[node])) {
+            roots.push(node);
+        }
+    }
+
+    const anchor_node = parent_of[roots[0]];
+
+    // Node 0 is the prefab's own root — the placement an instance stands at, never a bone of the
+    // skin — so a garment whose first joint sits directly under it has no bone above it.
+    if (anchor_node <= 0) {
+        return refuse(`${name}: "${name_of[roots[0]]}" has no bone above it, so the garment has nothing to hang from`);
+    }
+
+    for (const root of roots) {
+        if (parent_of[root] !== anchor_node) {
+            return refuse(
+                `${name}: "${name_of[roots[0]]}" hangs from "${name_of[anchor_node]}" and "${name_of[root]}" hangs`
+                + ` from "${parent_of[root] < 0 ? 'nothing' : name_of[parent_of[root]]}" — a garment hangs from one`
+                + ` anchor, and chains from different bones are two garments`
+            );
+        }
+    }
+
+    const anchor = index_of.get(anchor_node);
+
+    if (anchor === undefined) {
+        return refuse(
+            `${name}: "${name_of[roots[0]]}" hangs from "${name_of[anchor_node]}", which is not a joint of this skin`
+        );
+    }
+
+    // Parents before children, so one forward pass composes the chain.
+    const ordered = [];
+
+    /**
+     * @type {Map<number, number>} node index → position in `ordered`
+     */
+    const position = new Map();
+
+    // Breadth-first from every root at once, which keeps parents before
+    // children across the whole forest rather than only within one chain.
+    const queue = roots.slice();
+
+    while (queue.length > 0) {
+        const node = queue.shift();
+
+        position.set(node, ordered.length);
+        ordered.push(node);
+
+        for (const child of members) {
+            if (parent_of[child] === node) {
+                queue.push(child);
+            }
+        }
+    }
+
+    if (ordered.length !== members.size) {
+        const stranded = [];
+
+        for (const node of members) {
+            if (!position.has(node)) {
+                stranded.push(name_of[node]);
+            }
+        }
+
+        return refuse(
+            `${name}: ${stranded.length} joints are unreachable from the anchor (${stranded.join(', ')})`
+        );
+    }
+
+    const joint_count = ordered.length;
+
+    const joint = new Int32Array(joint_count);
+    const joint_parent = new Int32Array(joint_count);
+
+    const rest_position = new Float32Array(joint_count * 3);
+    const rest_rotation = new Float32Array(joint_count * 4);
+
+    const joint_name = [];
+
+    for (let i = 0; i < joint_count; i++) {
+        const node = ordered[i];
+
+        const resolved = index_of.get(node);
+
+        if (resolved === undefined) {
+            return refuse(`${name}: "${name_of[node]}" is not a joint of this skin`);
+        }
+
+        joint[i] = resolved;
+        joint_parent[i] = members.has(parent_of[node]) ? position.get(parent_of[node]) : -1;
+
+        joint_name.push(name_of[node]);
+
+        const local = prefab.local[node];
+
+        rest_position[i * 3] = local[TRANSFORM64_TRANSLATION_OFFSET];
+        rest_position[i * 3 + 1] = local[TRANSFORM64_TRANSLATION_OFFSET + 1];
+        rest_position[i * 3 + 2] = local[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+        rest_rotation[i * 4] = local[TRANSFORM64_ROTATION_OFFSET];
+        rest_rotation[i * 4 + 1] = local[TRANSFORM64_ROTATION_OFFSET + 1];
+        rest_rotation[i * 4 + 2] = local[TRANSFORM64_ROTATION_OFFSET + 2];
+        rest_rotation[i * 4 + 3] = local[TRANSFORM64_ROTATION_OFFSET + 3];
+
+        // A joint at no distance from its parent is a zero-length link, which
+        // has no direction for a stretch row's gradient and no rest length for
+        // it to hold. §7 P8 rejects it at build time rather than tolerating it
+        // at runtime, which is what "build-time validation, not runtime
+        // tolerance" means. The root is included: its parent is the anchor.
+        const length = Math.hypot(
+            rest_position[i * 3], rest_position[i * 3 + 1], rest_position[i * 3 + 2]
+        );
+
+        if (length <= 0) {
+            return refuse(
+                `${name}: "${name_of[node]}" sits exactly on its parent, so the link between them`
+                + ` has no length and no direction`
+            );
+        }
+    }
+
+    return {
+        proxy: ClothProxy.from({
+            name,
+            joint,
+            joint_parent,
+            anchor,
+            rest_position,
+            rest_rotation,
+            joint_name
+        }),
+        error: ""
+    };
+}
+
+/**
+ * @param {string} error
+ * @returns {ClothProxyBuildResult}
+ */
+function refuse(error) {
+    return { proxy: null, error };
+}