@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,284 +1,371 @@
-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 };
-}
+import { ClothProxy } from "./ClothProxy.js";
+import { cloth_bind_in_frame, cloth_bind_scaled_above } from "./cloth_bind_in_frame.js";
+import { number_compare_ascending } from "../../../../core/primitives/numbers/number_compare_ascending.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: 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`.
+ *
+ * ## What the garment hangs from falls out of the topology
+ *
+ * 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.
+ *
+ * ## The frame is the nearest joint above all of them
+ *
+ * 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
+ */
+
+/**
+ * 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. Their parents are what the
+    // garment hangs from.
+    const roots = [];
+
+    /**
+     * @type {number[]} node indices, ascending
+     */
+    const hung_from = [];
+
+    for (const node of members) {
+        const parent = parent_of[node];
+
+        if (parent >= 0 && members.has(parent)) {
+            continue;
+        }
+
+        // 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 (parent <= 0) {
+            return refuse(`${name}: "${name_of[node]}" has no bone above it, so the garment has nothing to hang from`);
+        }
+
+        if (!index_of.has(parent)) {
+            return refuse(`${name}: "${name_of[node]}" hangs from "${name_of[parent]}", which is not a joint of this skin`);
+        }
+
+        roots.push(node);
+
+        if (hung_from.indexOf(parent) === -1) {
+            hung_from.push(parent);
+        }
+    }
+
+    hung_from.sort(number_compare_ascending);
+
+    // The frame: the nearest skin joint above every bone the garment hangs from
+    // — for one bone, the bone itself.
+    let frame_node = hung_from[0];
+
+    for (let i = 1; i < hung_from.length; i++) {
+        frame_node = common_ancestor(parent_of, frame_node, hung_from[i]);
+    }
+
+    while (frame_node > 0 && !index_of.has(frame_node)) {
+        frame_node = parent_of[frame_node];
+    }
+
+    if (frame_node <= 0) {
+        return refuse(
+            `${name}: nothing in the skin is above all of ${hung_from.map(n => `"${name_of[n]}"`).join(', ')},`
+            + ` so the garment has no joint to ride`
+        );
+    }
+
+    // Particle order: the bones the garment hangs from, then the garment
+    // breadth-first from every root at once, which keeps parents before
+    // children across the whole forest.
+    const ordered = hung_from.slice();
+
+    /**
+     * @type {Map<number, number>} node index → particle
+     */
+    const particle_of = new Map();
+
+    for (let i = 0; i < ordered.length; i++) {
+        particle_of.set(ordered[i], i);
+    }
+
+    const queue = roots.slice();
+
+    while (queue.length > 0) {
+        const node = queue.shift();
+
+        particle_of.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 + hung_from.length) {
+        const stranded = [];
+
+        for (const node of members) {
+            if (!particle_of.has(node)) {
+                stranded.push(name_of[node]);
+            }
+        }
+
+        return refuse(
+            `${name}: ${stranded.length} joints are unreachable from what the garment hangs from (${stranded.join(', ')})`
+        );
+    }
+
+    const particle_count = ordered.length;
+
+    const joint = new Int32Array(particle_count);
+    const output = new Uint8Array(particle_count);
+    const parent = new Int32Array(particle_count);
+
+    const rest_position = new Float32Array(particle_count * 3);
+    const rest_rotation = new Float32Array(particle_count * 4);
+
+    const particle_name = [];
+
+    for (let i = 0; i < particle_count; i++) {
+        const scaled = cloth_bind_scaled_above(prefab, ordered[i]);
+
+        if (scaled >= 0) {
+            const local = prefab.local[scaled];
+
+            return refuse(
+                `${name}: "${name_of[scaled]}", above "${name_of[ordered[i]]}", is scaled by (${local.scale_x}, ${local.scale_y}, ${local.scale_z}) at rest;`
+                + ` cloth poses its joints rigidly, so it would simulate a different garment from the one drawn`
+            );
+        }
+    }
+
+    const pose = cloth_bind_in_frame(prefab, frame_node);
+
+    for (let i = 0; i < particle_count; i++) {
+        const node = ordered[i];
+
+        joint[i] = index_of.get(node);
+
+        const is_garment = members.has(node);
+
+        output[i] = is_garment ? 1 : 0;
+        parent[i] = is_garment ? particle_of.get(parent_of[node]) : -1;
+
+        particle_name.push(name_of[node]);
+
+        const p = pose(node);
+
+        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];
+
+        if (!is_garment) {
+            continue;
+        }
+
+        // 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. A root is included: its parent is the bone it
+        // hangs from.
+        const q = pose(parent_of[node]);
+
+        if (Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]) <= 0) {
+            return refuse(
+                `${name}: "${name_of[node]}" sits exactly on its parent, so the link between them`
+                + ` has no length and no direction`
+            );
+        }
+    }
+
+    const groups = hung_from.map((node, i) => ({
+        joint: index_of.get(node),
+        particles: Int32Array.from([i])
+    }));
+
+    // A chain's fabric runs along its links, and it bends through the pair two
+    // links apart.
+    const edge = [];
+    const skip = [];
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = parent[i];
+
+        if (p < 0) {
+            continue;
+        }
+
+        edge.push(p, i);
+
+        if (parent[p] >= 0) {
+            skip.push(parent[p], i);
+        }
+    }
+
+    return {
+        proxy: ClothProxy.from({
+            name,
+            joint,
+            output,
+            parent,
+            edge,
+            skip,
+            hinge: [],
+            triangle: [],
+            frame: index_of.get(frame_node),
+            rest_position,
+            rest_rotation,
+            particle_name
+        }),
+        groups,
+        error: ""
+    };
+}
+
+/**
+ * @param {Int32Array} parent_of
+ * @param {number} a node
+ * @param {number} b node
+ * @returns {number} the deepest node both hang from, or themselves
+ * @private
+ */
+function common_ancestor(parent_of, a, b) {
+    const above_a = new Set();
+
+    for (let n = a; n >= 0; n = parent_of[n]) {
+        above_a.add(n);
+    }
+
+    for (let n = b; n >= 0; n = parent_of[n]) {
+        if (above_a.has(n)) {
+            return n;
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * @param {string} error
+ * @returns {ClothProxyBuildResult}
+ */
+function refuse(error) {
+    return { proxy: null, groups: [], error };
+}