@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -8,17 +8,17 @@
  * step, the colliders that could touch it are queried out of the index and
  * rewritten into its frame.
  *
- * ## Both poses go into the *current* anchor frame
+ * ## Both poses go into the cloth's *current* frame
  *
  * A record carries where the collider was and where it is. Both are converted
- * using the anchor's pose **now**, not each with the anchor pose of its own
+ * using the frame's pose **now**, not each with the frame pose of its own
  * step, so what the sweep interpolates is the collider's motion *relative to
  * the cloth's frame*. That is the motion the particles actually see: the frame
  * change has already been applied to them by `move_local_frame`, scaled by
  * `ClothDynamics#inertia`, before the step begins.
  *
  * The alternative — converting each pose in its own frame — would make a
- * collider appear to move whenever the anchor did, so a character running past
+ * collider appear to move whenever the frame did, so a character running past
  * a static wall would sweep the wall through their own cape.
  *
  * ## The query box

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

@@ -47,17 +47,17 @@ import { CLOTH_COLLIDER_SLOTS } from "../solver/cloth_solver_constants.js";
  * step, the colliders that could touch it are queried out of the index and
  * rewritten into its frame.
  *
- * ## Both poses go into the *current* anchor frame
+ * ## Both poses go into the cloth's *current* frame
  *
  * A record carries where the collider was and where it is. Both are converted
- * using the anchor's pose **now**, not each with the anchor pose of its own
+ * using the frame's pose **now**, not each with the frame pose of its own
  * step, so what the sweep interpolates is the collider's motion *relative to
  * the cloth's frame*. That is the motion the particles actually see: the frame
  * change has already been applied to them by `move_local_frame`, scaled by
  * `ClothDynamics#inertia`, before the step begins.
  *
  * The alternative — converting each pose in its own frame — would make a
- * collider appear to move whenever the anchor did, so a character running past
+ * collider appear to move whenever the frame did, so a character running past
  * a static wall would sweep the wall through their own cape.
  *
  * ## The query box
@@ -193,20 +193,20 @@ function query_colliders(instance, index, reach) {
         return 0;
     }
 
-    // The anchor pose the particles were carried into this step, not the live
+    // The frame pose the particles were carried into this step, not the live
     // component — those are the same value by the time this runs, and the
     // cached pair is the one `move_local_frame` used.
-    const anchor_x = instance.anchor_translation[0];
-    const anchor_y = instance.anchor_translation[1];
-    const anchor_z = instance.anchor_translation[2];
+    const frame_x = instance.frame_translation[0];
+    const frame_y = instance.frame_translation[1];
+    const frame_z = instance.frame_translation[2];
 
-    const anchor_rotation = instance.anchor_rotation;
+    const frame_rotation = instance.frame_rotation;
 
     const contact_reach = reach + state.contact_radius * (1 + CLOTH_CONTACT_MARGIN);
     const local_scale = Math.max(Math.abs(min_x), Math.abs(max_x))
         + Math.max(Math.abs(min_y), Math.abs(max_y))
         + Math.max(Math.abs(min_z), Math.abs(max_z)) + contact_reach;
-    const world_scale = local_scale + Math.abs(anchor_x) + Math.abs(anchor_y) + Math.abs(anchor_z);
+    const world_scale = local_scale + Math.abs(frame_x) + Math.abs(frame_y) + Math.abs(frame_z);
     const margin = contact_reach + cloth_contact_rounding(local_scale, world_scale);
 
     min_x -= margin;
@@ -233,11 +233,11 @@ function query_colliders(instance, index, reach) {
         CORNER[1] = (corner & 2) === 0 ? min_y : max_y;
         CORNER[2] = (corner & 4) === 0 ? min_z : max_z;
 
-        v3_quaternion_apply_array(CORNER, 0, CORNER, 0, anchor_rotation, 0);
+        v3_quaternion_apply_array(CORNER, 0, CORNER, 0, frame_rotation, 0);
 
-        const x = CORNER[0] + anchor_x;
-        const y = CORNER[1] + anchor_y;
-        const z = CORNER[2] + anchor_z;
+        const x = CORNER[0] + frame_x;
+        const y = CORNER[1] + frame_y;
+        const z = CORNER[2] + frame_z;
 
         if (x < world_min_x) { world_min_x = x; }
         if (y < world_min_y) { world_min_y = y; }
@@ -339,8 +339,8 @@ export function cloth_gather_colliders(instance, index, reach) {
  * @private
  */
 function localise_record(table, record, source, handle, instance) {
-    const anchor_translation = instance.anchor_translation;
-    const anchor_rotation = instance.anchor_rotation;
+    const frame_translation = instance.frame_translation;
+    const frame_rotation = instance.frame_rotation;
     const from = handle * CCR_STRIDE;
     const to = record * CCR_STRIDE;
 
@@ -356,13 +356,13 @@ function localise_record(table, record, source, handle, instance) {
     localise(
         table, to + CCR_TX, to + CCR_QX,
         source, from + CCR_TX, from + CCR_QX,
-        anchor_translation, anchor_rotation
+        frame_translation, frame_rotation
     );
 
     localise(
         table, to + CCR_PREV_TX, to + CCR_PREV_QX,
         source, from + CCR_PREV_TX, from + CCR_PREV_QX,
-        anchor_translation, anchor_rotation
+        frame_translation, frame_rotation
     );
 
     cloth_collider_refit_bounds(table, record, CCR_STRIDE);
@@ -382,31 +382,31 @@ function localise_record(table, record, source, handle, instance) {
  * @param {Float32Array|Float64Array} source the world pose's record table
  * @param {number} source_translation_slot `[x, y, z]`
  * @param {number} source_rotation_slot `[x, y, z, w]`
- * @param {Float64Array} anchor_translation `[x, y, z]`
- * @param {Float64Array} anchor_rotation `[x, y, z, w]`
+ * @param {Float64Array} frame_translation `[x, y, z]`
+ * @param {Float64Array} frame_rotation `[x, y, z, w]`
  * @private
  */
 function localise(
     table, translation_slot, rotation_slot,
     source, source_translation_slot, source_rotation_slot,
-    anchor_translation, anchor_rotation
+    frame_translation, frame_rotation
 ) {
-    LOCAL_TRANSLATION[0] = source[source_translation_slot] - anchor_translation[0];
-    LOCAL_TRANSLATION[1] = source[source_translation_slot + 1] - anchor_translation[1];
-    LOCAL_TRANSLATION[2] = source[source_translation_slot + 2] - anchor_translation[2];
+    LOCAL_TRANSLATION[0] = source[source_translation_slot] - frame_translation[0];
+    LOCAL_TRANSLATION[1] = source[source_translation_slot + 1] - frame_translation[1];
+    LOCAL_TRANSLATION[2] = source[source_translation_slot + 2] - frame_translation[2];
 
-    v3_quaternion_apply_inverse_array(LOCAL_TRANSLATION, 0, LOCAL_TRANSLATION, 0, anchor_rotation, 0);
+    v3_quaternion_apply_inverse_array(LOCAL_TRANSLATION, 0, LOCAL_TRANSLATION, 0, frame_rotation, 0);
 
     table[translation_slot] = LOCAL_TRANSLATION[0];
     table[translation_slot + 1] = LOCAL_TRANSLATION[1];
     table[translation_slot + 2] = LOCAL_TRANSLATION[2];
 
-    ANCHOR_CONJUGATE[0] = -anchor_rotation[0];
-    ANCHOR_CONJUGATE[1] = -anchor_rotation[1];
-    ANCHOR_CONJUGATE[2] = -anchor_rotation[2];
-    ANCHOR_CONJUGATE[3] = anchor_rotation[3];
+    FRAME_CONJUGATE[0] = -frame_rotation[0];
+    FRAME_CONJUGATE[1] = -frame_rotation[1];
+    FRAME_CONJUGATE[2] = -frame_rotation[2];
+    FRAME_CONJUGATE[3] = frame_rotation[3];
 
-    quat3_multiply_array(LOCAL_ROTATION, 0, ANCHOR_CONJUGATE, 0, source, source_rotation_slot);
+    quat3_multiply_array(LOCAL_ROTATION, 0, FRAME_CONJUGATE, 0, source, source_rotation_slot);
 
     table[rotation_slot] = LOCAL_ROTATION[0];
     table[rotation_slot + 1] = LOCAL_ROTATION[1];
@@ -517,7 +517,7 @@ const LOCAL_ROTATION = new Float64Array(4);
  * @type {Float64Array}
  * @private
  */
-const ANCHOR_CONJUGATE = new Float64Array(4);
+const FRAME_CONJUGATE = new Float64Array(4);
 
 /**
  * The world box {@link query_colliders} asks the index about, `[min_x, min_y, min_z, max_x, max_y,

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

@@ -0,0 +1,37 @@
+/**
+ * Edges incident on each node, CSR, from an edge list.
+ *
+ * @param {number} node_count
+ * @param {Int32Array} edge node pairs, 2 per edge
+ * @returns {{offset: Int32Array, edge: Int32Array}} `edge[offset[n] .. offset[n + 1]]` are the
+ *   edges touching `n`
+ */
+export function cloth_edge_incidence(node_count: number, edge: Int32Array): {
+    offset: Int32Array;
+    edge: Int32Array;
+};
+/**
+ * Distance from every node to the nearest of a set of source nodes, along the
+ * edges, and which source that is.
+ *
+ * A node marked in `blocked` can be reached but is never passed through. That is
+ * Chaos Cloth's rule for its long-range attachments (`ClothTetherData.cpp`):
+ * a path from one island of held particles does not run through another, because
+ * the far side of another island is that island's business.
+ *
+ * @param {Float64Array} out_distance per node; `Infinity` where no source reaches
+ * @param {Int32Array} out_nearest per node, the source it is nearest; `−1` where none reaches
+ * @param {number} node_count
+ * @param {Int32Array} edge node pairs, 2 per edge
+ * @param {Float64Array} edge_length rest length per edge
+ * @param {{offset: Int32Array, edge: Int32Array}} incidence from {@link cloth_edge_incidence}
+ * @param {Int32Array|number[]} source
+ * @param {number} source_count
+ * @param {Uint8Array|null} blocked per node, non-zero for a node no path may pass through;
+ *   `null` for none
+ */
+export function cloth_geodesic_field(out_distance: Float64Array, out_nearest: Int32Array, node_count: number, edge: Int32Array, edge_length: Float64Array, incidence: {
+    offset: Int32Array;
+    edge: Int32Array;
+}, source: Int32Array | number[], source_count: number, blocked: Uint8Array | null): void;
+//# sourceMappingURL=cloth_geodesic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_geodesic.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_geodesic.js"],"names":[],"mappings":"AAsCA;;;;;;;GAOG;AACH,iDALW,MAAM,QACN,UAAU,GACR;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,CAyBlD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,mDAXW,YAAY,eACZ,UAAU,cACV,MAAM,QACN,UAAU,eACV,YAAY,aACZ;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,UACtC,UAAU,GAAC,MAAM,EAAE,gBACnB,MAAM,WACN,UAAU,GAAC,IAAI,QAsDzB"}

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

@@ -0,0 +1,142 @@
+import { Uint32Heap } from "../../../../core/collection/heap/Uint32Heap.js";
+
+/**
+ * # How far each particle is from a set of particles, along the fabric
+ *
+ * The tether row (§6, §7 P2) bounds a particle's distance from a held one by
+ * the length of fabric between them, so it needs that length: the shortest path
+ * through the cloth's stretch edges, each weighted by its rest length. A chain
+ * has one path and the answer is a sum; a sheet has many and the answer is
+ * Dijkstra's.
+ *
+ * A path along edges is never shorter than the surface geodesic it follows, and
+ * that is never shorter than the straight line, so in the rest pose a tether
+ * built from it is never taut. That is the property the tether needs; how much
+ * longer a grid path is than the true geodesic is how much slack the bound
+ * carries, and it is the price of a bound that costs nothing at runtime.
+ *
+ * ## In double, and label-correcting
+ *
+ * The distances are accumulated in `Float64` from `Float64` edge lengths. The
+ * open set is a {@link Uint32Heap}, whose scores are `Float32`, so two
+ * candidates closer together than a single-precision step can pop in the wrong
+ * order; a node is therefore never closed, and a shorter path arriving after it
+ * popped is relaxed through again. The answer is the exact shortest path
+ * whatever the heap's rounding, and on the graphs this sees the extra pops are
+ * a handful.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The open set. Module-level: a search runs start to finish synchronously, and
+ * it runs when a cloth is seeded or its held set changes, never per step.
+ * @type {Uint32Heap}
+ */
+const OPEN = new Uint32Heap();
+
+/**
+ * Edges incident on each node, CSR, from an edge list.
+ *
+ * @param {number} node_count
+ * @param {Int32Array} edge node pairs, 2 per edge
+ * @returns {{offset: Int32Array, edge: Int32Array}} `edge[offset[n] .. offset[n + 1]]` are the
+ *   edges touching `n`
+ */
+export function cloth_edge_incidence(node_count, edge) {
+    const edge_count = edge.length >> 1;
+
+    const offset = new Int32Array(node_count + 1);
+
+    for (let i = 0; i < edge_count * 2; i++) {
+        offset[edge[i] + 1]++;
+    }
+
+    for (let n = 0; n < node_count; n++) {
+        offset[n + 1] += offset[n];
+    }
+
+    const incident = new Int32Array(edge_count * 2);
+    const cursor = offset.slice(0, node_count);
+
+    for (let e = 0; e < edge_count; e++) {
+        incident[cursor[edge[e * 2]]++] = e;
+        incident[cursor[edge[e * 2 + 1]]++] = e;
+    }
+
+    return { offset, edge: incident };
+}
+
+/**
+ * Distance from every node to the nearest of a set of source nodes, along the
+ * edges, and which source that is.
+ *
+ * A node marked in `blocked` can be reached but is never passed through. That is
+ * Chaos Cloth's rule for its long-range attachments (`ClothTetherData.cpp`):
+ * a path from one island of held particles does not run through another, because
+ * the far side of another island is that island's business.
+ *
+ * @param {Float64Array} out_distance per node; `Infinity` where no source reaches
+ * @param {Int32Array} out_nearest per node, the source it is nearest; `−1` where none reaches
+ * @param {number} node_count
+ * @param {Int32Array} edge node pairs, 2 per edge
+ * @param {Float64Array} edge_length rest length per edge
+ * @param {{offset: Int32Array, edge: Int32Array}} incidence from {@link cloth_edge_incidence}
+ * @param {Int32Array|number[]} source
+ * @param {number} source_count
+ * @param {Uint8Array|null} blocked per node, non-zero for a node no path may pass through;
+ *   `null` for none
+ */
+export function cloth_geodesic_field(
+    out_distance, out_nearest,
+    node_count, edge, edge_length, incidence,
+    source, source_count,
+    blocked
+) {
+    out_distance.fill(Infinity, 0, node_count);
+    out_nearest.fill(-1, 0, node_count);
+
+    OPEN.clear();
+
+    for (let i = 0; i < source_count; i++) {
+        const s = source[i];
+
+        out_distance[s] = 0;
+        out_nearest[s] = s;
+
+        OPEN.insert(s, 0);
+    }
+
+    const offset = incidence.offset;
+    const incident = incidence.edge;
+
+    while (!OPEN.is_empty()) {
+        const u = OPEN.pop_min();
+
+        const d = out_distance[u];
+
+        if (d > 0 && blocked !== null && blocked[u] !== 0) {
+            // Reached, and that is where the path stops.
+            continue;
+        }
+
+        const nearest = out_nearest[u];
+
+        for (let k = offset[u]; k < offset[u + 1]; k++) {
+            const e = incident[k];
+
+            const a = edge[e * 2];
+            const v = a === u ? edge[e * 2 + 1] : a;
+
+            const candidate = d + edge_length[e];
+
+            if (candidate < out_distance[v]) {
+                out_distance[v] = candidate;
+                out_nearest[v] = nearest;
+
+                OPEN.insert(v, candidate);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,97 @@
+/**
+ * # 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: ClothInstance, hold: ClothHold, frame_translation: Float64Array, frame_rotation: Float64Array): void;
+/**
+ * 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: ClothInstance): void;
+/**
+ * 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: ClothInstance): void;
+//# sourceMappingURL=cloth_holds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_holds.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_holds.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,gGAJW,YAAY,kBACZ,YAAY,GACV,IAAI,CA6ChB;AAED;;;;;;;;;;;GAWG;AACH,4DAFa,IAAI,CA0KhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,0DAFa,IAAI,CA2KhB"}