@woosh/meep-engine 3.21.0 → 3.23.0

package/src/engine/physics/cloth/solver/constraint/cloth_stretch_row.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Evaluate one stretch row's constraint value and its gradient with respect to
+ * one of its two particles.
+ *
+ * This is the definition the accumulation loop below inlines, and the one the
+ * finite-difference spec checks — there is no second copy of the arithmetic.
+ *
+ * @param {Float64Array|number[]} gradient out, `∂C/∂x_slot`
+ * @param {number} gradient_offset
+ * @param {ClothState} state
+ * @param {number} row
+ * @param {number} slot 0 or 1
+ * @returns {number} `C`
+ */
+export function cloth_stretch_evaluate(gradient: Float64Array | number[], gradient_offset: number, state: ClothState, row: number, slot: number): number;
+/**
+ * Add every stretch row touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_stretch_accumulate(accumulator: Float64Array, state: ClothState, particle: number): void;
+/**
+ * Warm start every stretch row for a substep: regularise the carried
+ * multiplier and decay the penalty back towards its floor. §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha multiplier regularisation, `[0, 1]`
+ * @param {number} gamma dual decay, `[0, 1)`
+ * @param {number} k_min
+ * @param {number} k_max
+ */
+export function cloth_stretch_warm_start(state: ClothState, alpha: number, gamma: number, k_min_ratio: any, k_max_ratio: any, inverse_h_squared: any): void;
+/**
+ * Dual update for every stretch row: absorb this iteration's violation into
+ * the multiplier and ramp the penalty towards the row's material stiffness.
+ * §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} beta penalty ramp
+ * @param {number} k_max
+ */
+export function cloth_stretch_dual_update(state: ClothState, beta: number, k_max_ratio: any, inverse_h_squared: any): void;
+/**
+ * # Stretch — the distance row
+ *
+ *     C(x) = ‖x_i − x_j‖ − L₀
+ *     ∂C/∂x_i = (x_i − x_j)/‖x_i − x_j‖ = n,   ∂C/∂x_j = −n
+ *
+ * The fabric row of §6, and — with a different rest length and a one-sided
+ * force clamp — its strain limit as well. `f_min = −∞, f_max = +∞` is the
+ * bilateral spring that resists stretching *and* compression; `f_max = 0` with
+ * `L₀ = L_max` makes it pull-only, so it does nothing until the edge is longer
+ * than the cap and then holds it hard. One row model, parameterised by mode,
+ * exactly as `physics/constraint/solve_constraints.js` does for its 6-DOF
+ * joints at the velocity level.
+ *
+ * ## The gradient is the same expression at both ends
+ *
+ * `∂C/∂x_i` is the unit vector from the *other* particle to *this* one, for
+ * whichever end this is: at slot 0 that is `(x_i − x_j)/L`, at slot 1 it is
+ * `(x_j − x_i)/L`. So the slot picks which particle is "the other one" and the
+ * arithmetic that follows is identical — no sign flip, no branch.
+ *
+ * ## The clamp gates the Hessian, not just the force
+ *
+ * `fu = k·C + λ` is the row's unclamped force; `fc = clamp(fu, f_min, f_max)`
+ * is what it actually applies. When the clamp binds, the applied force is
+ * *constant* with respect to position, so its second derivative is zero and
+ * the row contributes nothing to `H` — adding `k·ggᵀ` anyway would make an
+ * inactive unilateral row resist motion it has no business touching. §5.2.
+ *
+ * ## Coincident particles
+ *
+ * `‖x_i − x_j‖` is not differentiable at zero. Below
+ * {@link CLOTH_STRETCH_EPSILON} the row writes a zero gradient, which makes
+ * both its force and its Hessian contribution vanish without a special case
+ * downstream. Two particles exactly on top of each other is a measure-zero
+ * configuration that any perturbation leaves; a build that produces one is
+ * rejected by the welding pass (§7 P8) long before the solver sees it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Separation below which the distance gradient is treated as zero, metres.
+ * A nanometre is six orders of magnitude below the thinnest fabric this
+ * simulates and comfortably above where `Float32` positions stop resolving a
+ * difference at all.
+ * @type {number}
+ */
+export const CLOTH_STRETCH_EPSILON: number;
+//# sourceMappingURL=cloth_stretch_row.d.ts.map

package/src/engine/physics/cloth/solver/constraint/cloth_stretch_row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_stretch_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_stretch_row.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;GAaG;AACH,iDAPW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,QACN,MAAM,GACJ,MAAM,CA8BlB;AAED;;;;;;GAMG;AACH,sDAJW,YAAY,+BAEZ,MAAM,QAoIhB;AAED;;;;;;;;;GASG;AACH,mEALW,MAAM,SACN,MAAM,oEA8DhB;AAED;;;;;;;;GAQG;AACH,mEAHW,MAAM,kDA2DhB;AAjXD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;GAMG;AACH,oCAFU,MAAM,CAE0B"}

package/src/engine/physics/cloth/solver/constraint/cloth_stretch_row.js

@@ -0,0 +1,383 @@
+import {
+    CVA_F_X,
+    CVA_F_Y,
+    CVA_F_Z,
+    CVA_H_XX,
+    CVA_H_XY,
+    CVA_H_XZ,
+    CVA_H_YY,
+    CVA_H_YZ,
+    CVA_H_ZZ,
+    CVA_TRUST
+} from "../cloth_vertex_accumulator.js";
+
+/**
+ * # Stretch — the distance row
+ *
+ *     C(x) = ‖x_i − x_j‖ − L₀
+ *     ∂C/∂x_i = (x_i − x_j)/‖x_i − x_j‖ = n,   ∂C/∂x_j = −n
+ *
+ * The fabric row of §6, and — with a different rest length and a one-sided
+ * force clamp — its strain limit as well. `f_min = −∞, f_max = +∞` is the
+ * bilateral spring that resists stretching *and* compression; `f_max = 0` with
+ * `L₀ = L_max` makes it pull-only, so it does nothing until the edge is longer
+ * than the cap and then holds it hard. One row model, parameterised by mode,
+ * exactly as `physics/constraint/solve_constraints.js` does for its 6-DOF
+ * joints at the velocity level.
+ *
+ * ## The gradient is the same expression at both ends
+ *
+ * `∂C/∂x_i` is the unit vector from the *other* particle to *this* one, for
+ * whichever end this is: at slot 0 that is `(x_i − x_j)/L`, at slot 1 it is
+ * `(x_j − x_i)/L`. So the slot picks which particle is "the other one" and the
+ * arithmetic that follows is identical — no sign flip, no branch.
+ *
+ * ## The clamp gates the Hessian, not just the force
+ *
+ * `fu = k·C + λ` is the row's unclamped force; `fc = clamp(fu, f_min, f_max)`
+ * is what it actually applies. When the clamp binds, the applied force is
+ * *constant* with respect to position, so its second derivative is zero and
+ * the row contributes nothing to `H` — adding `k·ggᵀ` anyway would make an
+ * inactive unilateral row resist motion it has no business touching. §5.2.
+ *
+ * ## Coincident particles
+ *
+ * `‖x_i − x_j‖` is not differentiable at zero. Below
+ * {@link CLOTH_STRETCH_EPSILON} the row writes a zero gradient, which makes
+ * both its force and its Hessian contribution vanish without a special case
+ * downstream. Two particles exactly on top of each other is a measure-zero
+ * configuration that any perturbation leaves; a build that produces one is
+ * rejected by the welding pass (§7 P8) long before the solver sees it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Separation below which the distance gradient is treated as zero, metres.
+ * A nanometre is six orders of magnitude below the thinnest fabric this
+ * simulates and comfortably above where `Float32` positions stop resolving a
+ * difference at all.
+ * @type {number}
+ */
+export const CLOTH_STRETCH_EPSILON = 1e-9;
+
+/**
+ * Evaluate one stretch row's constraint value and its gradient with respect to
+ * one of its two particles.
+ *
+ * This is the definition the accumulation loop below inlines, and the one the
+ * finite-difference spec checks — there is no second copy of the arithmetic.
+ *
+ * @param {Float64Array|number[]} gradient out, `∂C/∂x_slot`
+ * @param {number} gradient_offset
+ * @param {ClothState} state
+ * @param {number} row
+ * @param {number} slot 0 or 1
+ * @returns {number} `C`
+ */
+export function cloth_stretch_evaluate(gradient, gradient_offset, state, row, slot) {
+    const particle = state.stretch_particle;
+    const position = state.position;
+
+    const self = particle[row * 2 + slot] * 3;
+    const other = particle[row * 2 + (slot ^ 1)] * 3;
+
+    const dx = position[self] - position[other];
+    const dy = position[self + 1] - position[other + 1];
+    const dz = position[self + 2] - position[other + 2];
+
+    const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (length < CLOTH_STRETCH_EPSILON) {
+        gradient[gradient_offset] = 0;
+        gradient[gradient_offset + 1] = 0;
+        gradient[gradient_offset + 2] = 0;
+
+        return length - state.stretch_rest[row];
+    }
+
+    const inverse = 1 / length;
+
+    gradient[gradient_offset] = dx * inverse;
+    gradient[gradient_offset + 1] = dy * inverse;
+    gradient[gradient_offset + 2] = dz * inverse;
+
+    return length - state.stretch_rest[row];
+}
+
+/**
+ * Add every stretch row touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_stretch_accumulate(accumulator, state, particle) {
+    const offset = state.stretch_adjacency_offset;
+
+    const start = offset[particle];
+    const end = offset[particle + 1];
+
+    if (start === end) {
+        return;
+    }
+
+    const adjacency = state.stretch_adjacency;
+    const row_particle = state.stretch_particle;
+    const rest = state.stretch_rest;
+    const force_min = state.stretch_force_min;
+    const force_max = state.stretch_force_max;
+    const lambda = state.stretch_lambda;
+    const penalty = state.stretch_penalty;
+    const position = state.position;
+
+    const self = particle * 3;
+
+    const x = position[self];
+    const y = position[self + 1];
+    const z = position[self + 2];
+
+    let f_x = accumulator[CVA_F_X];
+    let f_y = accumulator[CVA_F_Y];
+    let f_z = accumulator[CVA_F_Z];
+
+    let h_xx = accumulator[CVA_H_XX];
+    let h_yy = accumulator[CVA_H_YY];
+    let h_zz = accumulator[CVA_H_ZZ];
+    let h_xy = accumulator[CVA_H_XY];
+    let h_xz = accumulator[CVA_H_XZ];
+    let h_yz = accumulator[CVA_H_YZ];
+
+    let trust = accumulator[CVA_TRUST];
+
+    for (let i = start; i < end; i++) {
+        const packed = adjacency[i];
+
+        const row = packed >> 1;
+
+        // The other end is this row's remaining slot.
+        const other = row_particle[(row << 1) | ((packed & 1) ^ 1)] * 3;
+
+        const dx = x - position[other];
+        const dy = y - position[other + 1];
+        const dz = z - position[other + 2];
+
+        const length_squared = dx * dx + dy * dy + dz * dz;
+
+        if (length_squared < CLOTH_STRETCH_EPSILON * CLOTH_STRETCH_EPSILON) {
+            continue;
+        }
+
+        const length = Math.sqrt(length_squared);
+        const inverse = 1 / length;
+
+        if (length < trust) {
+            trust = length;
+        }
+
+        const g_x = dx * inverse;
+        const g_y = dy * inverse;
+        const g_z = dz * inverse;
+
+        const k = penalty[row];
+
+        const unclamped = k * (length - rest[row]) + lambda[row];
+
+        let clamped = unclamped;
+
+        const lo = force_min[row];
+        const hi = force_max[row];
+
+        if (clamped < lo) {
+            clamped = lo;
+        } else if (clamped > hi) {
+            clamped = hi;
+        }
+
+        f_x -= clamped * g_x;
+        f_y -= clamped * g_y;
+        f_z -= clamped * g_z;
+
+        if (clamped > 0) {
+            // Geometric stiffness, positive part only: `∂²C/∂x² = (I − ggᵀ)/L`
+            // for a distance row, so this term is `(fc/L)·(I − ggᵀ)`, which is
+            // positive semidefinite exactly when the row is in tension. It is
+            // the curvature of the *direction* the force points in, and
+            // dropping it makes the update overshoot sideways once `fc/L`
+            // passes `m/h²`. See the module docblock.
+            const s = clamped * inverse;
+
+            h_xx += s * (1 - g_x * g_x);
+            h_yy += s * (1 - g_y * g_y);
+            h_zz += s * (1 - g_z * g_z);
+            h_xy -= s * g_x * g_y;
+            h_xz -= s * g_x * g_z;
+            h_yz -= s * g_y * g_z;
+        }
+
+        if (clamped !== unclamped) {
+            // At a clamp the applied force no longer varies with `C`, so the
+            // penalty's own curvature is gone — but the geometric term above
+            // stays, because the force still swings with the direction. §5.2.
+            continue;
+        }
+
+        h_xx += k * g_x * g_x;
+        h_yy += k * g_y * g_y;
+        h_zz += k * g_z * g_z;
+        h_xy += k * g_x * g_y;
+        h_xz += k * g_x * g_z;
+        h_yz += k * g_y * g_z;
+    }
+
+    accumulator[CVA_F_X] = f_x;
+    accumulator[CVA_F_Y] = f_y;
+    accumulator[CVA_F_Z] = f_z;
+
+    accumulator[CVA_H_XX] = h_xx;
+    accumulator[CVA_H_YY] = h_yy;
+    accumulator[CVA_H_ZZ] = h_zz;
+    accumulator[CVA_H_XY] = h_xy;
+    accumulator[CVA_H_XZ] = h_xz;
+    accumulator[CVA_H_YZ] = h_yz;
+
+    accumulator[CVA_TRUST] = trust;
+}
+
+/**
+ * Warm start every stretch row for a substep: regularise the carried
+ * multiplier and decay the penalty back towards its floor. §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha multiplier regularisation, `[0, 1]`
+ * @param {number} gamma dual decay, `[0, 1)`
+ * @param {number} k_min
+ * @param {number} k_max
+ */
+export function cloth_stretch_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+    const count = state.stretch_count;
+
+    const row_particle = state.stretch_particle;
+    const mass_inverse = state.mass_inverse;
+    const stiffness = state.stretch_stiffness;
+    const lambda = state.stretch_lambda;
+    const penalty = state.stretch_penalty;
+
+    const decay = alpha * gamma;
+
+    for (let row = 0; row < count; row++) {
+        const material = stiffness[row];
+
+        if (material < Infinity) {
+            // Soft: a penalty at the material stiffness *is* the material law,
+            // and there is nothing for a multiplier to add. See the dual
+            // update for why carrying one anyway is not a small error.
+            penalty[row] = material;
+            lambda[row] = 0;
+
+            continue;
+        }
+
+        const compliance = mass_inverse[row_particle[row * 2]] + mass_inverse[row_particle[row * 2 + 1]];
+
+        if (compliance === 0) {
+            // Every end pinned: the row cannot move anything, and the band it
+            // would otherwise be clamped into is unbounded. Zero the penalty so
+            // no non-finite value is left sitting in live state.
+            penalty[row] = 0;
+            lambda[row] = 0;
+
+            continue;
+        }
+
+        // The penalty band is a multiple of the row's own inertial scale — the
+        // effective `m/h²` seen along the constraint. See
+        // `cloth_solver_constants.js`: the useful band tracks that scale across
+        // five decades of particle mass, so a stiffness in N/m is not a
+        // constant at all and a ratio is.
+        const scale = inverse_h_squared / compliance;
+
+        const lo = k_min_ratio * scale;
+        const hi = k_max_ratio * scale;
+
+        lambda[row] *= decay;
+
+        let k = penalty[row] * gamma;
+
+        if (k < lo) {
+            k = lo;
+        } else if (k > hi) {
+            k = hi;
+        }
+
+        penalty[row] = k;
+    }
+}
+
+/**
+ * Dual update for every stretch row: absorb this iteration's violation into
+ * the multiplier and ramp the penalty towards the row's material stiffness.
+ * §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} beta penalty ramp
+ * @param {number} k_max
+ */
+export function cloth_stretch_dual_update(state, beta, k_max_ratio, inverse_h_squared) {
+    const count = state.stretch_count;
+
+    const row_particle = state.stretch_particle;
+    const mass_inverse = state.mass_inverse;
+    const position = state.position;
+    const rest = state.stretch_rest;
+    const stiffness = state.stretch_stiffness;
+    const force_min = state.stretch_force_min;
+    const force_max = state.stretch_force_max;
+    const lambda = state.stretch_lambda;
+    const penalty = state.stretch_penalty;
+
+    for (let row = 0; row < count; row++) {
+        if (stiffness[row] < Infinity) {
+            // Soft row: no multiplier, no ramp. The warm start already pinned
+            // the penalty at the material stiffness.
+            continue;
+        }
+
+        const compliance = mass_inverse[row_particle[row * 2]] + mass_inverse[row_particle[row * 2 + 1]];
+
+        if (compliance === 0) {
+            continue;
+        }
+
+        const k_max = k_max_ratio * inverse_h_squared / compliance;
+
+        const a = row_particle[row * 2] * 3;
+        const b = row_particle[row * 2 + 1] * 3;
+
+        const dx = position[a] - position[b];
+        const dy = position[a + 1] - position[b + 1];
+        const dz = position[a + 2] - position[b + 2];
+
+        const c = Math.sqrt(dx * dx + dy * dy + dz * dz) - rest[row];
+
+        const k = penalty[row];
+
+        let next = k * c + lambda[row];
+
+        const lo = force_min[row];
+        const hi = force_max[row];
+
+        if (next < lo) {
+            next = lo;
+        } else if (next > hi) {
+            next = hi;
+        }
+
+        lambda[row] = next;
+
+        const ramped = k + beta * Math.abs(c);
+
+        penalty[row] = ramped < k_max ? ramped : k_max;
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Dev-build tripwire: scan post-step cloth state for non-finite values
+ * (NaN / ±Infinity) and describe the first offender, or return "" when clean.
+ *
+ * Called from {@link cloth_step} behind an `assert.*` call, so the O(particles
+ * + rows) sweep compiles out of consumer bundles — the engine ships raw source
+ * and a check moved out of `assert.*` stops being strippable.
+ *
+ * It exists for the same reason `find_non_finite_physics_state` does: a NaN
+ * that enters the pipeline is self-concealing. NaN fails every comparison, so
+ * it survives clamps (`if (v < lo)` and `if (v > hi)` are both false), it
+ * never trips a sleep threshold, and it spreads through a stencil to every
+ * particle that shares a row with it before anything notices. Naming the first
+ * one names the cause.
+ *
+ * Duals are covered as well as positions, because the augmented Lagrangian
+ * carries state across steps: a multiplier that goes non-finite poisons every
+ * subsequent step even after the positions that produced it have been reset.
+ *
+ * @param {ClothState} state
+ * @returns {string} "" when clean, else a description of the first non-finite value
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function find_non_finite_cloth_state(state: ClothState): string;
+//# sourceMappingURL=find_non_finite_cloth_state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"find_non_finite_cloth_state.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/find_non_finite_cloth_state.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,gEALa,MAAM,CAmFlB"}

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

@@ -0,0 +1,104 @@
+/**
+ * Dev-build tripwire: scan post-step cloth state for non-finite values
+ * (NaN / ±Infinity) and describe the first offender, or return "" when clean.
+ *
+ * Called from {@link cloth_step} behind an `assert.*` call, so the O(particles
+ * + rows) sweep compiles out of consumer bundles — the engine ships raw source
+ * and a check moved out of `assert.*` stops being strippable.
+ *
+ * It exists for the same reason `find_non_finite_physics_state` does: a NaN
+ * that enters the pipeline is self-concealing. NaN fails every comparison, so
+ * it survives clamps (`if (v < lo)` and `if (v > hi)` are both false), it
+ * never trips a sleep threshold, and it spreads through a stencil to every
+ * particle that shares a row with it before anything notices. Naming the first
+ * one names the cause.
+ *
+ * Duals are covered as well as positions, because the augmented Lagrangian
+ * carries state across steps: a multiplier that goes non-finite poisons every
+ * subsequent step even after the positions that produced it have been reset.
+ *
+ * @param {ClothState} state
+ * @returns {string} "" when clean, else a description of the first non-finite value
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function find_non_finite_cloth_state(state) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const velocity = state.velocity;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        if (!Number.isFinite(position[p] + position[p + 1] + position[p + 2])) {
+            return `particle[${i}].position = (${position[p]}, ${position[p + 1]}, ${position[p + 2]})`;
+        }
+
+        if (!Number.isFinite(velocity[p] + velocity[p + 1] + velocity[p + 2])) {
+            return `particle[${i}].velocity = (${velocity[p]}, ${velocity[p + 1]}, ${velocity[p + 2]})`;
+        }
+    }
+
+    const stretch_count = state.stretch_count;
+
+    const stretch_lambda = state.stretch_lambda;
+    const stretch_penalty = state.stretch_penalty;
+
+    for (let row = 0; row < stretch_count; row++) {
+        if (!Number.isFinite(stretch_lambda[row])) {
+            return `stretch[${row}].lambda = ${stretch_lambda[row]}`;
+        }
+
+        if (!Number.isFinite(stretch_penalty[row])) {
+            return `stretch[${row}].penalty = ${stretch_penalty[row]}`;
+        }
+    }
+
+    const bend_count = state.bend_count;
+
+    const bend_lambda = state.bend_lambda;
+    const bend_penalty = state.bend_penalty;
+
+    for (let row = 0; row < bend_count; row++) {
+        const dual = row * 3;
+
+        if (!Number.isFinite(bend_lambda[dual] + bend_lambda[dual + 1] + bend_lambda[dual + 2])) {
+            return `bend[${row}].lambda = (${bend_lambda[dual]}, ${bend_lambda[dual + 1]}, ${bend_lambda[dual + 2]})`;
+        }
+
+        if (!Number.isFinite(bend_penalty[row])) {
+            return `bend[${row}].penalty = ${bend_penalty[row]}`;
+        }
+    }
+
+    const leash_count = state.leash_count;
+
+    const leash_lambda = state.leash_lambda;
+    const leash_penalty = state.leash_penalty;
+    const leash_target = state.leash_target;
+
+    for (let row = 0; row < leash_count; row++) {
+        if (!Number.isFinite(leash_lambda[row])) {
+            return `leash[${row}].lambda = ${leash_lambda[row]}`;
+        }
+
+        if (!Number.isFinite(leash_penalty[row])) {
+            return `leash[${row}].penalty = ${leash_penalty[row]}`;
+        }
+
+        // The centre is written from outside the solver every step - by
+        // the system that knows where the animation put this particle -
+        // so unlike every other array here it can arrive non-finite
+        // rather than become so, and naming it names a caller rather
+        // than a solve.
+        const target = row * 3;
+
+        if (!Number.isFinite(leash_target[target] + leash_target[target + 1] + leash_target[target + 2])) {
+            return `leash[${row}].target = (${leash_target[target]}, ${leash_target[target + 1]}, ${leash_target[target + 2]})`;
+        }
+    }
+
+    return "";
+}

package/src/engine/physics/ecs/PhysicsSystem.d.ts

@@ -606,17 +606,15 @@ export class PhysicsSystem extends System<any> {
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {AbstractShape3D} shape
-     * @param {{x:number,y:number,z:number,w:number}} rotation
+     * @param {ArrayLike<number>} rotation fixed orientation of the swept shape
+     *   as `[x, y, z, w]`, a unit quaternion — which a Transform64's `rotation`
+     *   already is. Read by index, so an `{x, y, z, w}` object silently misses
+     *   everything rather than throwing
      * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
      * @param {(entity:number, collider:Collider)=>boolean} [filter]
      * @returns {boolean}
      */
-    shapeCast(ray: Ray3, shape: AbstractShape3D, rotation: {
-        x: number;
-        y: number;
-        z: number;
-        w: number;
-    }, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;
+    shapeCast(ray: Ray3, shape: AbstractShape3D, rotation: ArrayLike<number>, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;
     /**
      * Find every body whose collider overlaps the given convex shape at the
      * given world pose, without mutating the simulation. Intended for

package/src/engine/physics/ecs/PhysicsSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"PhysicsSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsSystem.js"],"names":[],"mappings":"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"}

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -1388,7 +1388,10 @@ export class PhysicsSystem extends System {
      *
      * @param {Ray3} ray  origin + unit direction + `tMax`
      * @param {AbstractShape3D} shape
-     * @param {{x:number,y:number,z:number,w:number}} rotation
+     * @param {ArrayLike<number>} rotation fixed orientation of the swept shape
+     *   as `[x, y, z, w]`, a unit quaternion — which a Transform64's `rotation`
+     *   already is. Read by index, so an `{x, y, z, w}` object silently misses
+     *   everything rather than throwing
      * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
      * @param {(entity:number, collider:Collider)=>boolean} [filter]
      * @returns {boolean}