@woosh/meep-engine 3.42.0 → 3.44.0

package/src/engine/physics/cloth/ecs/cloth_holds.js

@@ -0,0 +1,608 @@
+import { quat3_multiply, quat3_multiply_array } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { v3_quaternion_apply_array } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse_array } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import { CLOTH_PARTICLE_MASS, CLOTH_SLACK_REACH } from "./cloth_build_rows.js";
+import { cloth_geodesic_field } from "./cloth_geodesic.js";
+
+/**
+ * # What holding a particle does to a cloth
+ *
+ * A {@link ClothPin} holds particles, and that one fact decides four things the
+ * rows depend on. This module is where they are decided, once per change in
+ * what is held ({@link cloth_apply_holds}) and once per step
+ * ({@link cloth_hold_step}):
+ *
+ * - **Who is kinematic.** A held particle has inverse mass zero and follows its
+ *   holder: the solver carries it through the step towards
+ *   `ClothState#kinematic_target`.
+ * - **What each free particle hangs from.** Its nearest held particle, along the
+ *   fabric — one multi-source Dijkstra over the stretch edges, every held
+ *   particle a source, so a path never runs through one held particle to reach
+ *   another. Nothing held in reach means nothing to hang from.
+ * - **The tether and the slack**, §6's two leash rows, both measured from that
+ *   particle (`ClothState#leash_source`), so that they follow it through the step
+ *   rather than lag a step behind it. One tether per particle, to the nearest
+ *   hold only: two hard tethers to two holders pulled apart are two bounds no
+ *   position satisfies, and the fabric between them already says everything a
+ *   second tether could.
+ * - **The animated pose**, which is the rest pose hung from that particle and
+ *   turned by its holder — see `ClothInstance#animated_position`.
+ *
+ * A particle nothing held reaches gets a tether and a slack row of radius
+ * `Infinity`, which say nothing, and a cloth nothing holds is all such
+ * particles: there is no case here for it.
+ *
+ * ## The tether never pulls
+ *
+ * A hold that begins mid-run — a hand closing on a falling ribbon — begins
+ * wherever the fabric is, and a free configuration is routinely further from
+ * the new hold than the geodesic, because the fabric stretches and the tether
+ * only binds when something pulls. A tether switched on at its full tightness
+ * would snap the cloth onto the hold inside one step. So a tether's radius
+ * starts at the larger of `d_geo` and where the particle is, and each step comes
+ * down to wherever the particle has since come to, never below `d_geo`: it
+ * stops a particle going further than it has been since the hold began, and
+ * it never drags one in. A cloth seeded at rest is inside `d_geo` everywhere,
+ * so its tethers are `d_geo` from the first step, which is what they always
+ * were — and only a tether that began loose is looked at again, so a cloth
+ * whose holds have not changed pays nothing for it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Take a hold's offsets: each of its particles relative to the holder, in the
+ * holder's own frame, from where the particle is now.
+ *
+ * Done in world terms, because the particles are in the frame they were last
+ * stepped in and the holder is where it is this step; the two meet in the
+ * world. The holder's turn is then measured from its pose in this step's frame,
+ * {@link ClothHold#pose}, so a hold begins unturned.
+ *
+ * @param {ClothInstance} instance
+ * @param {ClothHold} hold with {@link ClothHold#world} and {@link ClothHold#pose}
+ *   this step's
+ * @param {Float64Array} frame_translation the frame the particle positions are in
+ * @param {Float64Array} frame_rotation
+ * @returns {void}
+ */
+export function cloth_capture_hold(instance, hold, frame_translation, frame_rotation) {
+    const particles = hold.pin.particles;
+    const count = particles.length;
+
+    const state = instance.state;
+    const position = state.position;
+    const particle_of_node = instance.particle_of_node;
+    const node_count = instance.node_count;
+
+    const offset = new Float64Array(count * 3);
+
+    const world = hold.world;
+
+    for (let k = 0; k < count; k++) {
+        const node = particles[k];
+
+        if (node < 0 || node >= node_count) {
+            continue;
+        }
+
+        const p = particle_of_node[node] * 3;
+
+        // the particle in the world
+        v3_quaternion_apply_array(SCRATCH, 0, position, p, frame_rotation, 0);
+
+        SCRATCH[0] += frame_translation[0] - world[0];
+        SCRATCH[1] += frame_translation[1] - world[1];
+        SCRATCH[2] += frame_translation[2] - world[2];
+
+        // relative to the holder, in its frame
+        v3_quaternion_apply_inverse_array(offset, k * 3, SCRATCH, 0, world, 3);
+    }
+
+    hold.offset = offset;
+
+    const pose = hold.pose;
+
+    hold.rotation_at_hold[0] = pose[3];
+    hold.rotation_at_hold[1] = pose[4];
+    hold.rotation_at_hold[2] = pose[5];
+    hold.rotation_at_hold[3] = pose[6];
+
+    hold.captured = true;
+}
+
+/**
+ * Re-derive everything that depends on what is held: who is kinematic, what
+ * each free particle hangs from, the leash rows, and `reach`.
+ *
+ * Called once a seed and once per change in the set of holds — never per step.
+ * Writes into the instance's existing `ClothState`; nothing is re-built, so a
+ * worker that holds the buffer sees it on the next step without a second
+ * registration.
+ *
+ * @param {ClothInstance} instance
+ * @returns {void}
+ */
+export function cloth_apply_holds(instance) {
+    const node_count = instance.node_count;
+
+    const state = instance.state;
+    const particle_of_node = instance.particle_of_node;
+
+    const node_hold = instance.node_hold;
+    const node_hold_slot = instance.node_hold_slot;
+
+    node_hold.fill(-1);
+    node_hold_slot.fill(-1);
+
+    const holds = instance.holds;
+
+    const sources = [];
+
+    // In holder order, so a particle two pins name goes to the lower holder,
+    // every time — `ClothWorld` sorts them and says so once.
+    for (let h = 0; h < holds.length; h++) {
+        const hold = holds[h];
+
+        if (!hold.captured) {
+            continue;
+        }
+
+        const particles = hold.pin.particles;
+
+        for (let k = 0; k < particles.length; k++) {
+            const node = particles[k];
+
+            if (node < 0 || node >= node_count || node_hold[node] !== -1) {
+                continue;
+            }
+
+            node_hold[node] = h;
+            node_hold_slot[node] = k;
+
+            sources.push(node);
+        }
+    }
+
+    const mass_inverse = state.mass_inverse;
+
+    for (let node = 0; node < node_count; node++) {
+        mass_inverse[particle_of_node[node]] = node_hold[node] === -1 ? 1 / CLOTH_PARTICLE_MASS : 0;
+    }
+
+    const distance = SCRATCH_DISTANCE.length >= node_count ? SCRATCH_DISTANCE : (SCRATCH_DISTANCE = new Float64Array(node_count));
+
+    const nearest = instance.tether_source;
+
+    cloth_geodesic_field(
+        distance, nearest,
+        node_count, instance.edge, instance.edge_length, instance.edge_incidence,
+        sources, sources.length,
+        null
+    );
+
+    const geodesic = instance.geodesic;
+
+    let reach = 0;
+
+    const rest = instance.rest_position;
+
+    for (let node = 0; node < node_count; node++) {
+        const d = distance[node];
+
+        geodesic[node] = d;
+
+        // what this node hangs from: its hold, or — nothing reaching it — the frame
+        const hang = d < Infinity
+            ? d
+            : Math.hypot(rest[node * 3], rest[node * 3 + 1], rest[node * 3 + 2]);
+
+        if (hang > reach) {
+            reach = hang;
+        }
+    }
+
+    instance.reach = reach;
+
+    // The one length a cloth with no rows carries.
+    if (!(instance.shortest_row < Infinity)) {
+        instance.shortest_row = reach;
+    }
+
+    const slack_scale = CLOTH_SLACK_REACH * clamp01(instance.cloth.dynamics.slack);
+
+    const position = state.position;
+
+    const leash_source = state.leash_source;
+    const leash_offset = state.leash_offset;
+    const leash_radius = state.leash_radius;
+    const leash_lambda = state.leash_lambda;
+
+    const loose = instance.tether_loose;
+
+    loose.fill(0);
+
+    let loose_count = 0;
+
+    for (let node = 0; node < node_count; node++) {
+        const tether = instance.tether_row[node];
+        const slack = instance.slack_row[node];
+
+        const source = node_hold[node] === -1 ? nearest[node] : -1;
+
+        const d = geodesic[node];
+
+        // A multiplier describes a force towards whatever the row was measured
+        // from, and that may have just changed.
+        leash_lambda[tether] = 0;
+
+        if (slack >= 0) {
+            leash_lambda[slack] = 0;
+        }
+
+        if (source < 0) {
+            leash_source[tether] = -1;
+            leash_radius[tether] = Infinity;
+
+            if (slack >= 0) {
+                leash_source[slack] = -1;
+                leash_radius[slack] = Infinity;
+            }
+
+            continue;
+        }
+
+        const p = particle_of_node[node] * 3;
+        const q = particle_of_node[source] * 3;
+
+        leash_source[tether] = particle_of_node[source];
+        leash_offset[tether * 3] = 0;
+        leash_offset[tether * 3 + 1] = 0;
+        leash_offset[tether * 3 + 2] = 0;
+
+        // §7 P2's bound, from wherever the particle is if that is further — see
+        // the module docblock.
+        const current = Math.hypot(
+            position[p] - position[q],
+            position[p + 1] - position[q + 1],
+            position[p + 2] - position[q + 2]
+        );
+
+        if (current > d) {
+            leash_radius[tether] = current;
+
+            loose[node] = 1;
+            loose_count++;
+        } else {
+            leash_radius[tether] = d;
+        }
+
+        if (slack >= 0) {
+            leash_source[slack] = particle_of_node[source];
+            leash_radius[slack] = slack_scale * d;
+        }
+    }
+
+    instance.tether_loose_count = loose_count;
+
+    // everything the per-step pass derives is stale now
+    instance.holds_dirty = true;
+
+    if (instance.hold_turn.length < holds.length * 4) {
+        instance.hold_turn = new Float64Array(holds.length * 4);
+    }
+}
+
+/**
+ * Everything a hold changes per step: where each held particle is to be, the
+ * animated pose hung from them, the leash centres and the tethers' ratchet.
+ *
+ * Reads each hold's {@link ClothHold#pose} — the holder in this step's frame —
+ * and the particle positions as the frame carry left them.
+ *
+ * **Nothing is recomputed that cannot have changed.** Every quantity here
+ * except the ratchet is a function of the holds' poses in the frame, and a
+ * holder riding the frame — a rope's own top, a cape's shoulder in a cape riding
+ * that shoulder — has the same pose in it every step however the frame moves.
+ * So when no hold has moved in the frame since the last step, and nothing has
+ * rewritten the particles since ({@link ClothInstance#holds_dirty}), the
+ * targets, the animated pose and the leash offsets are left as they are: the
+ * question is a fact the step already has, not a kind of cloth.
+ *
+ * @param {ClothInstance} instance
+ * @returns {void}
+ */
+export function cloth_hold_step(instance) {
+    if (!instance.holds_dirty && holds_still(instance.holds)) {
+        // Every held particle arrived on its target at the end of the last step
+        // and nothing has moved it since, so none travels this one.
+        instance.kinematic_travel = 0;
+
+        cloth_tether_ratchet(instance);
+
+        return;
+    }
+
+    instance.holds_dirty = false;
+
+    const node_count = instance.node_count;
+
+    const state = instance.state;
+    const position = state.position;
+    const particle_of_node = instance.particle_of_node;
+
+    const holds = instance.holds;
+    const node_hold = instance.node_hold;
+    const node_hold_slot = instance.node_hold_slot;
+
+    const turn = instance.hold_turn;
+
+    // Each holder's turn since its hold began, once per hold.
+    for (let h = 0; h < holds.length; h++) {
+        const hold = holds[h];
+        const at = hold.rotation_at_hold;
+        const pose = hold.pose;
+
+        quat3_multiply(
+            turn, h * 4,
+            pose[3], pose[4], pose[5], pose[6],
+            -at[0], -at[1], -at[2], at[3]
+        );
+    }
+
+    const target = instance.held_target;
+    const kinematic = state.kinematic_target;
+
+    let travel = 0;
+
+    for (let node = 0; node < node_count; node++) {
+        const h = node_hold[node];
+
+        if (h === -1) {
+            continue;
+        }
+
+        const hold = holds[h];
+        const pose = hold.pose;
+
+        const n = node * 3;
+
+        v3_quaternion_apply_array(target, n, hold.offset, node_hold_slot[node] * 3, pose, 3);
+
+        target[n] += pose[0];
+        target[n + 1] += pose[1];
+        target[n + 2] += pose[2];
+
+        const p = particle_of_node[node] * 3;
+
+        kinematic[p] = target[n];
+        kinematic[p + 1] = target[n + 1];
+        kinematic[p + 2] = target[n + 2];
+
+        const moved = Math.hypot(target[n] - position[p], target[n + 1] - position[p + 1], target[n + 2] - position[p + 2]);
+
+        if (moved > travel) {
+            travel = moved;
+        }
+    }
+
+    instance.kinematic_travel = travel;
+
+    const rest = instance.rest_position;
+    const rest_rotation = instance.rest_rotation;
+
+    const animated = instance.animated_position;
+    const animated_rotation = instance.animated_rotation;
+
+    const source = instance.tether_source;
+
+    for (let node = 0; node < node_count; node++) {
+        const n = node * 3;
+        const r = node * 4;
+
+        const h = node_hold[node];
+
+        if (h !== -1) {
+            animated[n] = target[n];
+            animated[n + 1] = target[n + 1];
+            animated[n + 2] = target[n + 2];
+
+            quat3_multiply_array(animated_rotation, r, turn, h * 4, rest_rotation, r);
+
+            continue;
+        }
+
+        const s = source[node];
+
+        if (s === -1) {
+            animated[n] = rest[n];
+            animated[n + 1] = rest[n + 1];
+            animated[n + 2] = rest[n + 2];
+
+            animated_rotation[r] = rest_rotation[r];
+            animated_rotation[r + 1] = rest_rotation[r + 1];
+            animated_rotation[r + 2] = rest_rotation[r + 2];
+            animated_rotation[r + 3] = rest_rotation[r + 3];
+
+            continue;
+        }
+
+        // hung from its nearest held node, turned with that node's holder
+        const t = node_hold[s] * 4;
+
+        const m = s * 3;
+
+        SCRATCH[0] = rest[n] - rest[m];
+        SCRATCH[1] = rest[n + 1] - rest[m + 1];
+        SCRATCH[2] = rest[n + 2] - rest[m + 2];
+
+        v3_quaternion_apply_array(animated, n, SCRATCH, 0, turn, t);
+
+        animated[n] += target[m];
+        animated[n + 1] += target[m + 1];
+        animated[n + 2] += target[m + 2];
+
+        quat3_multiply_array(animated_rotation, r, turn, t, rest_rotation, r);
+    }
+
+    const leash_target = state.leash_target;
+    const leash_offset = state.leash_offset;
+
+    for (let node = 0; node < node_count; node++) {
+        const tether = instance.tether_row[node];
+        const slack = instance.slack_row[node];
+
+        const n = node * 3;
+
+        const s = node_hold[node] === -1 ? source[node] : -1;
+
+        if (s === -1) {
+            // Unbounded rows, measured from somewhere finite.
+            leash_target[tether * 3] = animated[n];
+            leash_target[tether * 3 + 1] = animated[n + 1];
+            leash_target[tether * 3 + 2] = animated[n + 2];
+
+            if (slack >= 0) {
+                leash_target[slack * 3] = animated[n];
+                leash_target[slack * 3 + 1] = animated[n + 1];
+                leash_target[slack * 3 + 2] = animated[n + 2];
+            }
+
+            continue;
+        }
+
+        const m = s * 3;
+
+        if (slack >= 0) {
+            leash_offset[slack * 3] = animated[n] - target[m];
+            leash_offset[slack * 3 + 1] = animated[n + 1] - target[m + 1];
+            leash_offset[slack * 3 + 2] = animated[n + 2] - target[m + 2];
+        }
+    }
+
+    cloth_tether_ratchet(instance);
+}
+
+/**
+ * Whether every hold is where it was in the frame a step ago.
+ *
+ * @param {ClothHold[]} holds
+ * @returns {boolean}
+ * @private
+ */
+function holds_still(holds) {
+    for (let h = 0; h < holds.length; h++) {
+        const hold = holds[h];
+
+        if (!hold.has_previous) {
+            return false;
+        }
+
+        const pose = hold.pose;
+        const before = hold.pose_previous;
+
+        for (let i = 0; i < 7; i++) {
+            if (pose[i] !== before[i]) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Bring every tether that began loose down to wherever its particle has come
+ * to, never below `d_geo` and never up — see the module docblock. A cloth with
+ * none loose pays for the test and nothing else.
+ *
+ * @param {ClothInstance} instance
+ * @private
+ */
+function cloth_tether_ratchet(instance) {
+    if (instance.tether_loose_count === 0) {
+        return;
+    }
+
+    const node_count = instance.node_count;
+
+    const state = instance.state;
+    const position = state.position;
+    const leash_radius = state.leash_radius;
+
+    const particle_of_node = instance.particle_of_node;
+    const node_hold = instance.node_hold;
+    const source = instance.tether_source;
+    const geodesic = instance.geodesic;
+    const loose = instance.tether_loose;
+
+    for (let node = 0; node < node_count; node++) {
+        if (loose[node] === 0) {
+            continue;
+        }
+
+        const s = node_hold[node] === -1 ? source[node] : -1;
+
+        if (s === -1) {
+            // held since, or cut off from every hold: nothing to bring in
+            loose[node] = 0;
+
+            instance.tether_loose_count--;
+
+            continue;
+        }
+
+        const tether = instance.tether_row[node];
+
+        // The ratchet: down to wherever the particle has come to, never below
+        // d_geo, never up.
+        const p = particle_of_node[node] * 3;
+        const q = particle_of_node[s] * 3;
+
+        const current = Math.hypot(
+            position[p] - position[q],
+            position[p + 1] - position[q + 1],
+            position[p + 2] - position[q + 2]
+        );
+
+        const d = geodesic[node];
+
+        const radius = leash_radius[tether];
+
+        const tightened = current < radius ? current : radius;
+
+        if (tightened > d) {
+            leash_radius[tether] = tightened;
+        } else {
+            leash_radius[tether] = d;
+
+            loose[node] = 0;
+
+            instance.tether_loose_count--;
+        }
+    }
+}
+
+/**
+ * @param {number} v
+ * @returns {number}
+ * @private
+ */
+function clamp01(v) {
+    return v < 0 ? 0 : (v > 1 ? 1 : v);
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const SCRATCH = new Float64Array(3);
+
+
+/**
+ * The geodesic field's distances, in double, grown to the largest cloth seen.
+ * @type {Float64Array}
+ * @private
+ */
+let SCRATCH_DISTANCE = new Float64Array(0);

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

@@ -3,8 +3,8 @@
  *
  * Both are in the **cloth's own frame**: the position is the particle lerped
  * towards its animated one by `Cloth#blend`, and the rotation is the swing
- * composed onto the animated orientation. Node 0 — the anchor — is the origin of
- * that frame, so its rotation is the identity rather than anything read off it.
+ * composed onto the animated orientation. A root of the seeder's tree has no
+ * link above it and takes its children's swing alone.
  *
  * @param {ClothInstance} instance
  * @returns {void}

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_reconstruct_pose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_reconstruct_pose.js"],"names":[],"mappings":"AA6DA;;;;;;;;;;GAUG;AACH,iEAFa,IAAI,CA+DhB"}
+{"version":3,"file":"cloth_reconstruct_pose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_reconstruct_pose.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;GAUG;AACH,iEAFa,IAAI,CAyEhB"}