@woosh/meep-engine 3.43.0 → 3.45.0

package/src/engine/physics/cloth/solver/cloth_step.js

@@ -1,5 +1,8 @@
 import { assert } from "../../../../core/assert.js";
+import { array_compute_max } from "../../../../core/collection/array/array_compute_max.js";
+import { clamp01 } from "../../../../core/math/clamp01.js";
 import { cloth_collider_pose_at } from "../collider/cloth_collider_sdf.js";
+import { CLOTH_HOLD_LINE_WORDS, cloth_hold_line_fit, cloth_hold_line_turn } from "./cloth_hold_line.js";
 import { cloth_solve_vertex } from "./cloth_solve_vertex.js";
 import {
     CLOTH_CONTACT_K_MIN_RATIO,
@@ -42,6 +45,7 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *     warm start   λ ← λ·α·γ ;  k ← clamp(k·γ, k_min, k_max)      (hard rows only)
  *     iterate      × iterations:
  *                    for each colour: for each particle: vertex update
+ *                    last iteration, held particles on one line: turn about it
  *                    dual update:  λ ← clamp(k·C + λ, f_min, f_max)
  *                                  k ← min(k + β·|C|, min(k_max, stiffness))
  *     integrate    v  = (x − x_prev)/h
@@ -85,6 +89,21 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  * which is what makes "no wind produces the bytes M5 measured" a fact about the
  * code rather than a claim about floating point.
  *
+ * ## One more block when the holds are a line
+ *
+ * Every vertex update is a 3×3 block of the descent, and a cloth held along one
+ * line has a motion no such block can make: turning about the line as a rigid
+ * body. About a vertical line nothing restores that turn, and the step stopped
+ * at a fabric's iteration count left a moment about it every substep — a flag
+ * turned on its pole for as long as it was run. So the turn is a block of its
+ * own, `cloth_hold_line.js`: one Newton step along it, in the last iteration,
+ * after the sweep and before the dual update.
+ *
+ * Whether the held particles are on a line is decided at every substep, from
+ * where the predict has just carried them. The predict lists them as it goes,
+ * so the question costs a pass over the held particles rather than over the
+ * cloth.
+ *
  * ## What each piece is for
  *
  * **Warm start** carries the multipliers into the next substep so a hard row
@@ -203,13 +222,37 @@ export function cloth_step(
 
     const contacts = collider_table !== null && collider_count > 0 ? collider_table : null;
 
+    if (HELD.length < state.particle_count) {
+        HELD = new Int32Array(state.particle_count);
+    }
+
+    const held = HELD;
+    const line = HOLD_LINE;
+
+    const last_iteration = iterations - 1;
+
     for (let substep = 0; substep < substeps; substep++) {
+        // How many substeps are left, this one included: a held particle covers
+        // an equal share of what remains of its way at each of them.
+        const remaining = substeps - substep;
+
+        let held_count;
+
         if (external === null) {
-            cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z);
+            held_count = cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z, remaining, held);
         } else {
-            cloth_predict_varying(state, h, external);
+            held_count = cloth_predict_varying(state, h, external, remaining, held);
         }
 
+        // Where the held particles are for the rest of the substep: nothing
+        // below moves one.
+        const turn = cloth_hold_line_fit(line, state.position, held, held_count);
+
+        // After the held particles have moved, so a centre measured from one
+        // sits where it is at this substep rather than where it was at the
+        // start of the step.
+        cloth_leash_follow(state);
+
         if (contacts !== null) {
             cloth_collider_pose_at(contacts, collider_count, (substep + 1) / substeps);
         }
@@ -239,6 +282,10 @@ export function cloth_step(
                 }
             }
 
+            if (turn && iteration === last_iteration) {
+                cloth_hold_line_turn(state, line, inverse_h_squared, contacts);
+            }
+
             cloth_stretch_dual_update(state, beta, k_max_ratio, inverse_h_squared);
             cloth_bend_dual_update(state, beta, k_max_ratio, inverse_h_squared);
             cloth_leash_dual_update(state, beta, k_max_ratio, inverse_h_squared);
@@ -262,6 +309,91 @@ export function cloth_step(
     );
 }
 
+/**
+ * Carry one held particle an equal share of the remaining way to its kinematic
+ * target, and make that its inertial target too.
+ *
+ * Equal shares of what *remains* rather than `(substep + 1)/substeps` of the
+ * whole: the particle is not moved by anything else in between, so the two put
+ * it in the same places, and this form needs no record of where the step began.
+ * It lands on the target exactly at the last substep, and a target equal to the
+ * position moves nothing by exactly nothing — which is what keeps a holder that
+ * rides the frame bit-identical to the fixed anchor it replaced.
+ *
+ * @param {ClothState} state
+ * @param {number} p particle index times three
+ * @param {number} remaining substeps left in the step, this one included
+ * @private
+ */
+function cloth_carry_held(state, p, remaining) {
+    const position = state.position;
+    const inertial = state.inertial;
+    const target = state.kinematic_target;
+
+    const x = position[p] + (target[p] - position[p]) / remaining;
+    const y = position[p + 1] + (target[p + 1] - position[p + 1]) / remaining;
+    const z = position[p + 2] + (target[p + 2] - position[p + 2]) / remaining;
+
+    position[p] = x;
+    position[p + 1] = y;
+    position[p + 2] = z;
+
+    inertial[p] = x;
+    inertial[p + 1] = y;
+    inertial[p + 2] = z;
+}
+
+/**
+ * Re-centre every leash row that is measured from a particle: `position[source]
+ * + offset`, at the substep's own positions.
+ *
+ * @param {ClothState} state
+ * @private
+ */
+function cloth_leash_follow(state) {
+    const count = state.leash_count;
+
+    const source = state.leash_source;
+    const offset = state.leash_offset;
+    const target = state.leash_target;
+    const position = state.position;
+
+    for (let row = 0; row < count; row++) {
+        const s = source[row];
+
+        if (s < 0) {
+            continue;
+        }
+
+        const r = row * 3;
+        const p = s * 3;
+
+        target[r] = position[p] + offset[r];
+        target[r + 1] = position[p + 1] + offset[r + 1];
+        target[r + 2] = position[p + 2] + offset[r + 2];
+    }
+}
+
+/**
+ * A held particle's velocity is the one its holder is moving it at. Nothing in
+ * the step reads it while the hold lasts — it has no inertia and no acceleration
+ * to seed — and it is exactly what the particle carries when it is let go.
+ *
+ * @param {ClothState} state
+ * @param {number} p particle index times three
+ * @param {number} inverse_h
+ * @private
+ */
+function cloth_held_velocity(state, p, inverse_h) {
+    const position = state.position;
+    const position_previous = state.position_previous;
+    const velocity = state.velocity;
+
+    velocity[p] = (position[p] - position_previous[p]) * inverse_h;
+    velocity[p + 1] = (position[p + 1] - position_previous[p + 1]) * inverse_h;
+    velocity[p + 2] = (position[p + 2] - position_previous[p + 2]) * inverse_h;
+}
+
 /**
  * The largest inverse mass in the cloth — the lightest particle, which is the
  * one a shared penalty has to be safe for.
@@ -278,17 +410,9 @@ export function cloth_step(
  * @private
  */
 function max_inverse_mass(state) {
-    const mass_inverse = state.mass_inverse;
-
-    let worst = 0;
+    const worst = array_compute_max(state.mass_inverse, 0, state.particle_count);
 
-    for (let i = 0; i < state.particle_count; i++) {
-        if (mass_inverse[i] > worst) {
-            worst = mass_inverse[i];
-        }
-    }
-
-    // Every particle pinned: nothing can move, so the stiffness is unused and
+    // Every particle pinned, or no particles at all: nothing can move, so the stiffness is unused and
     // any finite value is as good as another.
     return worst > 0 ? worst : 1;
 }
@@ -297,18 +421,22 @@ function max_inverse_mass(state) {
  * Predict: record where the substep started, build the inertial target every
  * vertex update pulls towards, and seed the descent.
  *
- * A pinned particle (zero inverse mass) is held exactly: it does not fall, it
- * does not carry velocity, and its inertial target is its own position, so a
- * row that reaches it sees a fixed anchor rather than a very heavy particle.
+ * A held particle (zero inverse mass) is kinematic: it does not fall, it is
+ * carried towards its {@link ClothState#kinematic_target} by an equal share of
+ * the remaining way, and its inertial target is wherever that puts it, so a row
+ * that reaches it sees a fixed anchor rather than a very heavy particle.
  *
  * @param {ClothState} state
  * @param {number} h
  * @param {number} acceleration_x
  * @param {number} acceleration_y
  * @param {number} acceleration_z
+ * @param {number} remaining substeps left in the step, this one included
+ * @param {Int32Array} held out, every held particle's index, in order
+ * @returns {number} how many particles are held
  * @private
  */
-function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z) {
+function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z, remaining, held) {
     const particle_count = state.particle_count;
 
     const position = state.position;
@@ -324,6 +452,8 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
     const gravity_y = h_squared * acceleration_y;
     const gravity_z = h_squared * acceleration_z;
 
+    let held_count = 0;
+
     for (let i = 0; i < particle_count; i++) {
         const p = i * 3;
 
@@ -336,9 +466,9 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
         position_previous[p + 2] = z;
 
         if (mass_inverse[i] === 0) {
-            inertial[p] = x;
-            inertial[p + 1] = y;
-            inertial[p + 2] = z;
+            cloth_carry_held(state, p, remaining);
+
+            held[held_count++] = i;
 
             continue;
         }
@@ -357,22 +487,26 @@ function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z)
         position[p + 1] = y + drift_y + blend * gravity_y;
         position[p + 2] = z + drift_z + blend * gravity_z;
     }
+
+    return held_count;
 }
 
 /**
  * {@link cloth_predict} with a per-particle external acceleration — §10's wind,
  * with gravity already folded in by `cloth_wind_accelerate`.
  *
- * Identical in every other respect, including the pinned-particle rule: a pin is
- * held exactly, so the air does not move it and its inertial target is its own
- * position.
+ * Identical in every other respect, including the held-particle rule: the air
+ * does not move a held particle, its holder does.
  *
  * @param {ClothState} state
  * @param {number} h
  * @param {Float32Array} external 3 per particle, cloth-local, m/s²
+ * @param {number} remaining substeps left in the step, this one included
+ * @param {Int32Array} held out, every held particle's index, in order
+ * @returns {number} how many particles are held
  * @private
  */
-function cloth_predict_varying(state, h, external) {
+function cloth_predict_varying(state, h, external, remaining, held) {
     const particle_count = state.particle_count;
 
     const position = state.position;
@@ -384,6 +518,8 @@ function cloth_predict_varying(state, h, external) {
 
     const h_squared = h * h;
 
+    let held_count = 0;
+
     for (let i = 0; i < particle_count; i++) {
         const p = i * 3;
 
@@ -396,9 +532,9 @@ function cloth_predict_varying(state, h, external) {
         position_previous[p + 2] = z;
 
         if (mass_inverse[i] === 0) {
-            inertial[p] = x;
-            inertial[p + 1] = y;
-            inertial[p + 2] = z;
+            cloth_carry_held(state, p, remaining);
+
+            held[held_count++] = i;
 
             continue;
         }
@@ -421,6 +557,8 @@ function cloth_predict_varying(state, h, external) {
         position[p + 1] = y + drift_y + blend * push_y;
         position[p + 2] = z + drift_z + blend * push_z;
     }
+
+    return held_count;
 }
 
 /**
@@ -461,12 +599,14 @@ function cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, accel
     const inverse_acceleration_squared = acceleration_squared > 0 ? 1 / acceleration_squared : 0;
 
     for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
         if (mass_inverse[i] === 0) {
+            cloth_held_velocity(state, p, inverse_h);
+
             continue;
         }
 
-        const p = i * 3;
-
         const next_x = (position[p] - position_previous[p]) * inverse_h;
         const next_y = (position[p + 1] - position_previous[p + 1]) * inverse_h;
         const next_z = (position[p + 2] - position_previous[p + 2]) * inverse_h;
@@ -476,15 +616,7 @@ function cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, accel
             (next_y - velocity[p + 1]) * acceleration_y +
             (next_z - velocity[p + 2]) * acceleration_z;
 
-        let blend = realised * inverse_h * inverse_acceleration_squared;
-
-        if (blend < 0) {
-            blend = 0;
-        } else if (blend > 1) {
-            blend = 1;
-        }
-
-        inertia_blend[i] = blend;
+        inertia_blend[i] = clamp01(realised * inverse_h * inverse_acceleration_squared);
 
         velocity[p] = next_x;
         velocity[p + 1] = next_y;
@@ -517,12 +649,14 @@ function cloth_integrate_varying(state, inverse_h, external) {
     const inertia_blend = state.inertia_blend;
 
     for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
         if (mass_inverse[i] === 0) {
+            cloth_held_velocity(state, p, inverse_h);
+
             continue;
         }
 
-        const p = i * 3;
-
         const acceleration_x = external[p];
         const acceleration_y = external[p + 1];
         const acceleration_z = external[p + 2];
@@ -546,15 +680,7 @@ function cloth_integrate_varying(state, inverse_h, external) {
             // {@link cloth_integrate} uses — the two differ in the last bit, and
             // a cloth whose external acceleration happens to be exactly gravity
             // should follow the same trajectory whichever loop stepped it.
-            let blend = realised * inverse_h * (1 / acceleration_squared);
-
-            if (blend < 0) {
-                blend = 0;
-            } else if (blend > 1) {
-                blend = 1;
-            }
-
-            inertia_blend[i] = blend;
+            inertia_blend[i] = clamp01(realised * inverse_h * (1 / acceleration_squared));
         } else {
             // No direction to project onto, so nothing to seed. The uniform
             // path reaches this for the whole cloth at once; here it is a
@@ -568,3 +694,18 @@ function cloth_integrate_varying(state, inverse_h, external) {
         velocity[p + 2] = next_z;
     }
 }
+
+/**
+ * The held particles' indices, as the predict carries them — grown to the
+ * largest cloth stepped, and only ever read up to the count the predict returns.
+ * @type {Int32Array}
+ * @private
+ */
+let HELD = new Int32Array(0);
+
+/**
+ * The hold line of the substep in progress, from `cloth_hold_line_fit`.
+ * @type {Float64Array}
+ * @private
+ */
+const HOLD_LINE = new Float64Array(CLOTH_HOLD_LINE_WORDS);

package/src/engine/physics/cloth/solver/cloth_step_instance.d.ts

@@ -31,6 +31,7 @@ export namespace ClothStepParam {
     let COLLIDER_COUNT: number;
     let SELF_COLLISION: number;
     let DRAG_RESPONSE: number;
+    let KINEMATIC_TRAVEL: number;
 }
 /**
  * `Float64` words one cloth's parameter block occupies.

package/src/engine/physics/cloth/solver/cloth_step_instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AAsIA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA4DhB;;;;6BA/IS,MAAM;;;;;;;;;;;;;;;;;AAqEhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}
+{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AA6IA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA6DhB;;;;6BAtJS,MAAM;;;;;;;;;;;;;;;;;;AA2EhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}

package/src/engine/physics/cloth/solver/cloth_step_instance.js

@@ -1,3 +1,4 @@
+import { vector_scale_offset } from "../../../../core/geom/vec/vector_scale_offset.js";
 import { cloth_contact_find } from "./cloth_contact_find.js";
 import { cloth_self_find } from "./cloth_self_find.js";
 import { cloth_step } from "./cloth_step.js";
@@ -123,14 +124,20 @@ export const ClothStepParam = {
      * takes `cloth_step`'s uniform-gravity path, which is the path M0 through
      * M5 measured.
      */
-    DRAG_RESPONSE: 13
+    DRAG_RESPONSE: 13,
+    /**
+     * The furthest any held particle is carried this step, metres — how far a
+     * cloth its holders are dragging moves without a velocity to show for it.
+     * Contact discovery reaches this much further for every free particle.
+     */
+    KINEMATIC_TRAVEL: 14
 };
 
 /**
  * `Float64` words one cloth's parameter block occupies.
  * @type {number}
  */
-export const CLOTH_STEP_PARAM_STRIDE = 14;
+export const CLOTH_STEP_PARAM_STRIDE = 15;
 
 /**
  * Step one cloth.
@@ -159,7 +166,8 @@ export function cloth_step_instance(state, self_exclusions, params, offset) {
     damp(state, params[offset + ClothStepParam.RETENTION]);
 
     const contact_count = cloth_contact_find(
-        state, state.collider_table, state.collider_key, collider_count, dt
+        state, state.collider_table, state.collider_key, collider_count, dt,
+        params[offset + ClothStepParam.KINEMATIC_TRAVEL]
     );
 
     let self_pairs = 0;
@@ -222,9 +230,7 @@ function damp(state, retention) {
 
     const velocity = state.velocity;
 
-    for (let i = 0; i < velocity.length; i++) {
-        velocity[i] *= retention;
-    }
+    vector_scale_offset(velocity, 0, velocity, 0, velocity.length, retention);
 }
 
 /**

package/src/engine/physics/cloth/solver/cloth_stretch_residual.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The worst relative error over a cloth's stretch rows, `max |C|/L₀` with
+ * `C = ‖x_a − x_b‖ − L₀` — §7 P2's rubber number. Zero when every row sits at
+ * its rest length; `0.1` when the worst one is ten percent off, long or short.
+ *
+ * A row of zero rest length has no relative error to speak of and is skipped,
+ * so a cloth with no rows, or only such rows, reads zero. A row with a NaN end
+ * reads NaN and so does the answer, whatever the other rows say: the callers
+ * gate on `Number.isFinite`, and a broken state must not read as converged.
+ *
+ * A diagnostic for specs, measurements and the playgrounds; nothing in the
+ * step reads it.
+ *
+ * @param {ClothState} state
+ * @returns {number} dimensionless
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_stretch_residual(state: ClothState): number;
+//# sourceMappingURL=cloth_stretch_residual.d.ts.map

package/src/engine/physics/cloth/solver/cloth_stretch_residual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_stretch_residual.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_stretch_residual.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2DALa,MAAM,CAoClB"}

package/src/engine/physics/cloth/solver/cloth_stretch_residual.js

@@ -0,0 +1,54 @@
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { max2_exact } from "../../../../core/math/max2_exact.js";
+
+/**
+ * The worst relative error over a cloth's stretch rows, `max |C|/L₀` with
+ * `C = ‖x_a − x_b‖ − L₀` — §7 P2's rubber number. Zero when every row sits at
+ * its rest length; `0.1` when the worst one is ten percent off, long or short.
+ *
+ * A row of zero rest length has no relative error to speak of and is skipped,
+ * so a cloth with no rows, or only such rows, reads zero. A row with a NaN end
+ * reads NaN and so does the answer, whatever the other rows say: the callers
+ * gate on `Number.isFinite`, and a broken state must not read as converged.
+ *
+ * A diagnostic for specs, measurements and the playgrounds; nothing in the
+ * step reads it.
+ *
+ * @param {ClothState} state
+ * @returns {number} dimensionless
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_stretch_residual(state) {
+    const stretch_count = state.stretch_count;
+
+    const stretch_particle = state.stretch_particle;
+    const stretch_rest = state.stretch_rest;
+    const position = state.position;
+
+    let worst = 0;
+
+    for (let row = 0; row < stretch_count; row++) {
+        const rest = stretch_rest[row];
+
+        if (!(rest > 0)) {
+            continue;
+        }
+
+        const a = stretch_particle[row * 2] * 3;
+        const b = stretch_particle[row * 2 + 1] * 3;
+
+        const length = v3_length(
+            position[a] - position[b],
+            position[a + 1] - position[b + 1],
+            position[a + 2] - position[b + 2]
+        );
+
+        const residual = Math.abs(length - rest) / rest;
+
+        worst = max2_exact(worst, residual);
+    }
+
+    return worst;
+}

package/src/engine/physics/cloth/solver/cloth_vertex_accumulator.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Seed an accumulator with the inertial term alone, before any row adds to it:
+ * the force `−(m/h²)(x − y)`, the Hessian `(m/h²)·I`, and no trust bound yet.
+ *
+ * `m/h²` is positive and finite whenever the particle has a mass at all, which
+ * is what makes the assembled `H` positive definite rather than merely
+ * semidefinite.
+ *
+ * @param {Float64Array} accumulator {@link CVA_STRIDE} slots, overwritten
+ * @param {Float32Array} position particle positions, 3 per particle
+ * @param {Float32Array} inertial predicted positions `y`, 3 per particle
+ * @param {number} p the particle's first component index, `particle · 3`
+ * @param {number} mass_over_h_squared `m/h²`
+ */
+export function cloth_vertex_accumulator_seed(accumulator: Float64Array, position: Float32Array, inertial: Float32Array, p: number, mass_over_h_squared: number): void;
 /**
  * # The per-vertex `(f, H)` accumulator
  *

package/src/engine/physics/cloth/solver/cloth_vertex_accumulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_vertex_accumulator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_vertex_accumulator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAE1B;;;;;;;;;;GAUG;AACH,0BAA2B;AAE3B,gCAAgC;AAChC,4BAA6B"}
+{"version":3,"file":"cloth_vertex_accumulator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_vertex_accumulator.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;;GAaG;AACH,2DANW,YAAY,YACZ,YAAY,YACZ,YAAY,KACZ,MAAM,uBACN,MAAM,QAchB;AAnFD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAE1B;;;;;;;;;;GAUG;AACH,0BAA2B;AAE3B,gCAAgC;AAChC,4BAA6B"}

package/src/engine/physics/cloth/solver/cloth_vertex_accumulator.js

@@ -54,3 +54,31 @@ export const CVA_TRUST = 9;
 
 /** Slots in one accumulator. */
 export const CVA_STRIDE = 10;
+
+/**
+ * Seed an accumulator with the inertial term alone, before any row adds to it:
+ * the force `−(m/h²)(x − y)`, the Hessian `(m/h²)·I`, and no trust bound yet.
+ *
+ * `m/h²` is positive and finite whenever the particle has a mass at all, which
+ * is what makes the assembled `H` positive definite rather than merely
+ * semidefinite.
+ *
+ * @param {Float64Array} accumulator {@link CVA_STRIDE} slots, overwritten
+ * @param {Float32Array} position particle positions, 3 per particle
+ * @param {Float32Array} inertial predicted positions `y`, 3 per particle
+ * @param {number} p the particle's first component index, `particle · 3`
+ * @param {number} mass_over_h_squared `m/h²`
+ */
+export function cloth_vertex_accumulator_seed(accumulator, position, inertial, p, mass_over_h_squared) {
+    accumulator[CVA_F_X] = -mass_over_h_squared * (position[p] - inertial[p]);
+    accumulator[CVA_F_Y] = -mass_over_h_squared * (position[p + 1] - inertial[p + 1]);
+    accumulator[CVA_F_Z] = -mass_over_h_squared * (position[p + 2] - inertial[p + 2]);
+
+    accumulator[CVA_H_XX] = mass_over_h_squared;
+    accumulator[CVA_H_YY] = mass_over_h_squared;
+    accumulator[CVA_H_ZZ] = mass_over_h_squared;
+    accumulator[CVA_H_XY] = 0;
+    accumulator[CVA_H_XZ] = 0;
+    accumulator[CVA_H_YZ] = 0;
+    accumulator[CVA_TRUST] = Infinity;
+}

package/src/engine/physics/cloth/solver/cloth_worst_tether_ratio.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How far the cloth has stretched away from its root, as the worst ratio over
+ * nodes of straight-line distance from node 0 to the fabric between them:
+ * `max ‖x_node − x_0‖ / d_geo(node)` over nodes `1 .. node_count − 1` — §7 P2's
+ * measure. At most 1 for a cloth that has not over-stretched anywhere, since no
+ * straight line is longer than the fabric it spans; `1.05` is a node five
+ * percent further out than the cloth reaches.
+ *
+ * Everything is measured from node 0, the root of the seeder's tree, which is
+ * where the rigs this was written for are held. A cloth held in several places
+ * wants each node measured from its own hold instead, and this is not that
+ * measure.
+ *
+ * A node at a NaN position reads NaN and so does the answer, whatever the other
+ * nodes say, so a broken state cannot pass for a well-behaved one.
+ *
+ * Takes the arrays rather than a `ClothInstance` so the solver side does not
+ * depend on the ECS one.
+ *
+ * @param {Float32Array|Float64Array} position 3 per particle
+ * @param {Int32Array|Uint32Array|number[]} particle_of_node particle index per node
+ * @param {Float32Array|Float64Array|number[]} geodesic fabric distance from node 0 per node, metres
+ * @param {number} node_count
+ * @returns {number} dimensionless; 0 for a cloth of fewer than two nodes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_worst_tether_ratio(position: Float32Array | Float64Array, particle_of_node: Int32Array | Uint32Array | number[], geodesic: Float32Array | Float64Array | number[], node_count: number): number;
+//# sourceMappingURL=cloth_worst_tether_ratio.d.ts.map

package/src/engine/physics/cloth/solver/cloth_worst_tether_ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_worst_tether_ratio.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_worst_tether_ratio.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mDATW,YAAY,GAAC,YAAY,oBACzB,UAAU,GAAC,WAAW,GAAC,MAAM,EAAE,YAC/B,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,GACJ,MAAM,CA6BlB"}