@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,3 +1,5 @@
+import { clamp01 } from "../../../../core/math/clamp01.js";
+
 /**
  * # Normalised coordinates → row parameters
  *
@@ -129,9 +131,10 @@ export const CLOTH_VELOCITY_CORRECTION_MARGIN = 4;
 export const CLOTH_DAMPING_RATE = 20;
 
 /**
- * How far a cloth's anchor may carry it in one fixed step, as a multiple of the
+ * How far a cloth's frame may carry it in one fixed step, as a multiple of the
  * cloth's own reach. Motion above this is felt as though it were exactly this,
- * which is what "anchor speed limit" means in §7 P7.
+ * which is what "anchor speed limit" means in §7 P7 — the frame being what the
+ * cloth rides.
  *
  * Expressing it as a fraction of reach rather than in metres per second is what
  * makes it work for a 3 cm pendant and a 30 m mooring line at the same time: a
@@ -142,10 +145,10 @@ export const CLOTH_DAMPING_RATE = 20;
  * badly-keyed cut does exceed.
  * @type {number}
  */
-export const CLOTH_ANCHOR_TRAVEL_REACH = 0.5;
+export const CLOTH_FRAME_TRAVEL_REACH = 0.5;
 
 /**
- * How far a cloth's anchor may rotate in one fixed step, radians. Rotation
+ * How far a cloth's frame may rotate in one fixed step, radians. Rotation
  * above this is felt as though it were exactly this.
  *
  * Unlike the travel limit this has no length scale to hang off — an angle is
@@ -153,11 +156,12 @@ export const CLOTH_ANCHOR_TRAVEL_REACH = 0.5;
  * about 1,700 degrees a second, which is a spin rather than a turn.
  * @type {number}
  */
-export const CLOTH_ANCHOR_ROTATION_LIMIT = 0.5;
+export const CLOTH_FRAME_ROTATION_LIMIT = 0.5;
 
 /**
- * Anchor displacement in one fixed step, as a multiple of the cloth's reach,
- * above which the motion is a **teleport** rather than locomotion (§7 P6).
+ * Displacement of the frame, or of a holder in the frame, in one fixed step, as
+ * a multiple of the cloth's reach, above which the motion is a **teleport**
+ * rather than locomotion (§7 P6).
  *
  * Four reaches in one step is 240 reaches a second: for a 1 m rope that is
  * 240 m/s, well past anything the world moves at and well short of the values a
@@ -267,9 +271,7 @@ export const CLOTH_SLEEP_STEPS = 30;
  * @returns {number} strain, `L_max = L₀·(1 + ε)`
  */
 export function cloth_strain_allowance(stretch) {
-    const t = stretch < 0 ? 0 : (stretch > 1 ? 1 : stretch);
-
-    return CLOTH_STRAIN_MAX * Math.pow(CLOTH_STRAIN_MIN / CLOTH_STRAIN_MAX, t);
+    return CLOTH_STRAIN_MAX * Math.pow(CLOTH_STRAIN_MIN / CLOTH_STRAIN_MAX, clamp01(stretch));
 }
 
 /**

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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qFAHW,MAAM,GACJ,MAAM,CAsBlB;AAyJD;;;;;;GAMG;AACH,kGAHW,MAAM,GACJ,MAAM,CAmBlB;AAwFD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,2FAFa,OAAO,CAkBnB;AAED;;;;;;;;GAQG;AACH,yEAHW,MAAM,GACJ,IAAI,CAgBhB"}
+{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qFAHW,MAAM,GACJ,MAAM,CAsBlB;AA2HD;;;;;;GAMG;AACH,kGAHW,MAAM,GACJ,MAAM,CAmBlB;AA2ED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,2FAFa,OAAO,CAkBnB;AAED;;;;;;;;GAQG;AACH,yEAHW,MAAM,GACJ,IAAI,CAgBhB"}

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

@@ -1,6 +1,6 @@
-import { 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 { aabb3_from_v3_array } from "../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
+import { aabb3_transform_oriented_array } from "../../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { pose3_to_local_array } from "../../../../core/geom/3d/pose/pose3_to_local_array.js";
 import {
     CCR_AABB_MAX_X,
     CCR_AABB_MAX_Y,
@@ -16,17 +16,11 @@ import {
     CCR_PARAM_1,
     CCR_PARAM_2,
     CCR_PARAM_3,
-    CCR_PREV_QW,
     CCR_PREV_QX,
-    CCR_PREV_QY,
-    CCR_PREV_QZ,
     CCR_PREV_TX,
     CCR_PREV_TY,
     CCR_PREV_TZ,
-    CCR_QW,
     CCR_QX,
-    CCR_QY,
-    CCR_QZ,
     CCR_STRIDE,
     CCR_TX,
     CCR_TY,
@@ -47,17 +41,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
@@ -167,46 +161,33 @@ function query_colliders(instance, index, reach) {
     const particle_count = state.particle_count;
     const position = state.position;
 
-    let min_x = Infinity;
-    let min_y = Infinity;
-    let min_z = Infinity;
-    let max_x = -Infinity;
-    let max_y = -Infinity;
-    let max_z = -Infinity;
-
-    for (let i = 0; i < particle_count; i++) {
-        const p = i * 3;
-
-        const x = position[p];
-        const y = position[p + 1];
-        const z = position[p + 2];
-
-        if (x < min_x) { min_x = x; }
-        if (y < min_y) { min_y = y; }
-        if (z < min_z) { min_z = z; }
-        if (x > max_x) { max_x = x; }
-        if (y > max_y) { max_y = y; }
-        if (z > max_z) { max_z = z; }
-    }
-
     if (particle_count === 0) {
         return 0;
     }
 
-    // The anchor pose the particles were carried into this step, not the live
+    aabb3_from_v3_array(LOCAL_BOX, position, particle_count * 3);
+
+    let min_x = LOCAL_BOX[0];
+    let min_y = LOCAL_BOX[1];
+    let min_z = LOCAL_BOX[2];
+    let max_x = LOCAL_BOX[3];
+    let max_y = LOCAL_BOX[4];
+    let max_z = LOCAL_BOX[5];
+
+    // 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;
@@ -216,46 +197,29 @@ function query_colliders(instance, index, reach) {
     max_y += margin;
     max_z += margin;
 
-    // The local box's eight corners, in world. A rotated box is not a box, so
-    // the world query volume is the bounds of the rotated one rather than the
-    // rotation of the bounds.
-    let world_min_x = Infinity;
-    let world_min_y = Infinity;
-    let world_min_z = Infinity;
-    let world_max_x = -Infinity;
-    let world_max_y = -Infinity;
-    let world_max_z = -Infinity;
-
-    for (let corner = 0; corner < 8; corner++) {
-        // The corner and the rotation go in as arrays: handed over as seven numbers, each was boxed
-        // wherever the call was not inlined, eight times a cloth a step.
-        CORNER[0] = (corner & 1) === 0 ? min_x : max_x;
-        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);
-
-        const x = CORNER[0] + anchor_x;
-        const y = CORNER[1] + anchor_y;
-        const z = CORNER[2] + anchor_z;
-
-        if (x < world_min_x) { world_min_x = x; }
-        if (y < world_min_y) { world_min_y = y; }
-        if (z < world_min_z) { world_min_z = z; }
-        if (x > world_max_x) { world_max_x = x; }
-        if (y > world_max_y) { world_max_y = y; }
-        if (z > world_max_z) { world_max_z = z; }
-    }
+    LOCAL_BOX[0] = min_x;
+    LOCAL_BOX[1] = min_y;
+    LOCAL_BOX[2] = min_z;
+    LOCAL_BOX[3] = max_x;
+    LOCAL_BOX[4] = max_y;
+    LOCAL_BOX[5] = max_z;
+
+    // The frame pose as the seven contiguous numbers the transform reads,
+    // translation then rotation; the instance keeps the two apart.
+    FRAME_POSE[0] = frame_x;
+    FRAME_POSE[1] = frame_y;
+    FRAME_POSE[2] = frame_z;
+    FRAME_POSE[3] = frame_rotation[0];
+    FRAME_POSE[4] = frame_rotation[1];
+    FRAME_POSE[5] = frame_rotation[2];
+    FRAME_POSE[6] = frame_rotation[3];
+
+    // A rotated box is not a box, so the world query volume is the bounds of
+    // the rotated one rather than the rotation of the bounds.
+    aabb3_transform_oriented_array(QUERY_BOX, 0, LOCAL_BOX, 0, FRAME_POSE, 0);
 
     const cloth = instance.cloth;
 
-    QUERY_BOX[0] = world_min_x;
-    QUERY_BOX[1] = world_min_y;
-    QUERY_BOX[2] = world_min_z;
-    QUERY_BOX[3] = world_max_x;
-    QUERY_BOX[4] = world_max_y;
-    QUERY_BOX[5] = world_max_z;
-
     const candidates = index.queryArray(HANDLES, QUERY_BOX, 0, cloth.layer, cloth.mask, true);
 
     // A half-space has no bounded world-space conversion allowance, so the
@@ -339,8 +303,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 +320,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,36 +346,23 @@ 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];
-
-    v3_quaternion_apply_inverse_array(LOCAL_TRANSLATION, 0, LOCAL_TRANSLATION, 0, anchor_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];
-
-    quat3_multiply_array(LOCAL_ROTATION, 0, ANCHOR_CONJUGATE, 0, source, source_rotation_slot);
-
-    table[rotation_slot] = LOCAL_ROTATION[0];
-    table[rotation_slot + 1] = LOCAL_ROTATION[1];
-    table[rotation_slot + 2] = LOCAL_ROTATION[2];
-    table[rotation_slot + 3] = LOCAL_ROTATION[3];
+    pose3_to_local_array(
+        table, translation_slot,
+        table, rotation_slot,
+        frame_translation, 0,
+        frame_rotation, 0,
+        source, source_translation_slot,
+        source, source_rotation_slot
+    );
 }
 
 /**
@@ -495,29 +446,18 @@ const HANDLES = [];
 const PLANE_RECORD = new Float32Array(CCR_STRIDE);
 
 /**
+ * The cloth's particle bounds, then the same fattened by the query margin, in its local frame.
  * @type {Float64Array}
  * @private
  */
-const CORNER = new Float64Array(3);
-
-/**
- * @type {Float64Array}
- * @private
- */
-const LOCAL_TRANSLATION = new Float64Array(3);
-
-/**
- * @type {Float64Array}
- * @private
- */
-const LOCAL_ROTATION = new Float64Array(4);
+const LOCAL_BOX = new Float64Array(6);
 
 /**
- * The anchor's rotation conjugated, `[-x, -y, -z, w]`: {@link localise}'s left operand.
+ * The cloth's frame pose, `[px, py, pz, qx, qy, qz, qw]`, for {@link aabb3_transform_oriented_array}.
  * @type {Float64Array}
  * @private
  */
-const ANCHOR_CONJUGATE = new Float64Array(4);
+const FRAME_POSE = new Float64Array(7);
 
 /**
  * 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":"AAuCA;;;;;;;GAOG;AACH,iDALW,MAAM,QACN,UAAU,GACR;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,CAiBlD;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,135 @@
+import { Uint32Heap } from "../../../../core/collection/heap/Uint32Heap.js";
+import { csr_build_incidence } from "../../../../core/graph/csr/csr_build_incidence.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);
+    const incident = new Int32Array(edge_count * 2);
+
+    csr_build_incidence(offset, incident, edge, edge_count * 2, node_count);
+
+    // an endpoint's flat index `e·2 + k` to its edge `e`
+    for (let i = 0; i < edge_count * 2; i++) {
+        incident[i] >>= 1;
+    }
+
+    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":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,gGAJW,YAAY,kBACZ,YAAY,GACV,IAAI,CAyChB;AAED;;;;;;;;;;;GAWG;AACH,4DAFa,IAAI,CA0KhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,0DAFa,IAAI,CA+JhB"}