@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,401 @@
+import { assert } from "../../../../core/assert.js";
+import { cloth_collider_pose_at } from "../collider/cloth_collider_sdf.js";
+import { cloth_solve_vertex } from "./cloth_solve_vertex.js";
+import {
+    CLOTH_CONTACT_K_MIN_RATIO,
+    CLOTH_SELF_RATIO,
+    CLOTH_SOLVER_TUNING
+} from "./cloth_solver_constants.js";
+import {
+    cloth_backstop_dual_update,
+    cloth_backstop_warm_start
+} from "./constraint/cloth_backstop_row.js";
+import {
+    cloth_bend_dual_update,
+    cloth_bend_warm_start
+} from "./constraint/cloth_bend_row.js";
+import {
+    cloth_contact_dual_update,
+    cloth_contact_warm_start
+} from "./constraint/cloth_contact_row.js";
+import { cloth_self_accumulate_scratch } from "./constraint/cloth_self_row.js";
+import {
+    cloth_leash_dual_update,
+    cloth_leash_warm_start
+} from "./constraint/cloth_leash_row.js";
+import {
+    cloth_stretch_dual_update,
+    cloth_stretch_warm_start
+} from "./constraint/cloth_stretch_row.js";
+import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
+
+/**
+ * # The fixed step
+ *
+ * Augmented Vertex Block Descent (Giles, Diaz & Yuksel, SIGGRAPH 2025): VBD's
+ * per-vertex Gauss-Seidel block coordinate descent on the implicit-Euler
+ * variational energy, with an augmented Lagrangian in place of pure penalties.
+ * §5.2 in prose; this is that pseudocode, one substep at a time:
+ *
+ *     predict      y  = x + h·v + h²·a
+ *                  x ← x + h·v + h²·ã          (adaptive initialisation)
+ *     warm start   λ ← λ·α·γ ;  k ← clamp(k·γ, k_min, k_max)      (hard rows only)
+ *     iterate      × iterations:
+ *                    for each colour: for each particle: vertex update
+ *                    dual update:  λ ← clamp(k·C + λ, f_min, f_max)
+ *                                  k ← min(k + β·|C|, min(k_max, stiffness))
+ *     integrate    v  = (x − x_prev)/h
+ *
+ * Six row kinds — stretch, bend, leash, backstop, contact and self-collision —
+ * each contribute a warm start, an accumulate and a dual update, and this
+ * function knows nothing else about them. A new row kind is a new module and
+ * three more calls; §6 is the whole of what they have in common.
+ *
+ * Self-collision is the one that does not fit that shape, and §5.4 is why: it is
+ * a **pair**, so it is accumulated into a per-particle scratch once per
+ * iteration and read by the vertex updates rather than visited from them. It has
+ * no warm start and no dual update because it is a plain penalty
+ * (`cloth_self_row.js`).
+ *
+ * ## The colliders move within the step
+ *
+ * §8.2's swept collision is one call per substep: the packed collider table is
+ * re-posed at the substep's fraction of the way from the previous step's pose to
+ * this one's, and every contact row then evaluates against where the collider
+ * *is at that moment* rather than where it ended up. The contact **set** is
+ * fixed for the step (`cloth_contact_find.js` and its speculative margin); only
+ * the poses move.
+ *
+ * The fraction is the end of each substep rather than its start — with one
+ * substep that is the collider's final pose, which is the one a particle must
+ * not be inside when the step is over.
+ *
+ * ## What each piece is for
+ *
+ * **Warm start** carries the multipliers into the next substep so a hard row
+ * does not have to rediscover its force from scratch, and decays them by `γ`
+ * so a resting configuration bleeds off accumulated force instead of ringing
+ * (§7 P5). `α` regularises how much of the multiplier survives at all: with
+ * `α·γ` near 1 a row behaves hard, near 0 it degenerates to a pure penalty of
+ * stiffness `k`. Both are solver internals and global — they are not a
+ * property of a fabric, and they are not on `ClothDynamics`.
+ *
+ * **Adaptive initialisation** is VBD's: seed the iteration at `x + h·v + h²·ã`
+ * where `ã` interpolates between zero and the full external acceleration
+ * according to whether the previous step looked like free fall or like resting
+ * contact. Without it, a low iteration count over-stretches under gravity on
+ * the first iteration and the rest of the budget goes on pulling it back. The
+ * inertial *target* `y` always carries the full acceleration; only the
+ * starting guess is blended.
+ *
+ * **The dual update runs once per iteration**, after every colour has been
+ * swept — that is what makes the multiplier converge within the step rather
+ * than across steps, and it is why a hard row is enforced almost exactly at
+ * one iteration per substep.
+ *
+ * **Integration is implicit by construction.** Velocity is not integrated
+ * forward; it is read back out of the positions the descent produced. Every
+ * position constraint is therefore a velocity constraint for free, and there
+ * is no separate velocity pass to disagree with the position pass.
+ *
+ * ## What is deliberately not here
+ *
+ * *Chebyshev acceleration* (§5.2), which M2 built, measured and removed. It is
+ * gated on a particle not being in contact, so M2 was the first milestone that
+ * could evaluate it at all — and it lost on every axis: on a sheet landing at
+ * 3 m/s it left the penetration inside the run-to-run spread and made the
+ * settled kinetic energy 1.5× worse; on a hanging cape it traded a third off the
+ * penetration for ten times the residual energy; and past `ρ = 0.9` it
+ * diverges, with `ρ = 0.99` reaching a non-positive-definite Hessian inside a
+ * second. A mechanism that costs 2–5%, does not help, and detonates at the top
+ * of its own parameter range is worse than its absence. `MEASUREMENTS.md` §21
+ * carries the grid, so a future attempt starts from the numbers rather than
+ * from the idea.
+ *
+ * *The velocity clamp* named in §7 P1 is derived from `ClothDynamics#thickness`
+ * and belongs with the component that carries it — `ClothSystem` applies it
+ * either side of this function, per fixed step, so that the fuzz here still
+ * measures the bare update. It is deliberately not what makes the solver
+ * stable.
+ *
+ * *Damping* is the same story and the same placement. It is a property of a
+ * fabric rather than of the descent, it is applied to the velocities between
+ * fixed steps, and — per `MEASUREMENTS.md` §6 — it is the only thing that
+ * reaches a soft row that will not settle, because the multiplier decay this
+ * function performs has no multiplier to decay on one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Advance a cloth by one fixed step.
+ *
+ * @param {ClothState} state
+ * @param {number} dt fixed step length, seconds — divided into `substeps`
+ * @param {number} acceleration_x external acceleration, cloth-local, m/s²
+ * @param {number} acceleration_y
+ * @param {number} acceleration_z
+ * @param {number} substeps
+ * @param {number} iterations descent iterations per substep
+ * @param {Float32Array|Float64Array|null} [collider_table] packed colliders in the
+ *   cloth's own frame, with their contact rows already found
+ * @param {number} [collider_count]
+ * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, self_ratio?: number}} [tuning]
+ */
+export function cloth_step(
+    state,
+    dt,
+    acceleration_x, acceleration_y, acceleration_z,
+    substeps,
+    iterations,
+    collider_table = null,
+    collider_count = 0,
+    tuning = CLOTH_SOLVER_TUNING
+) {
+    assert.isPositiveInteger(substeps, 'substeps');
+    assert.isPositiveInteger(iterations, 'iterations');
+
+    const alpha = tuning.alpha;
+    const beta = tuning.beta;
+    const gamma = tuning.gamma;
+    const k_min_ratio = tuning.k_min_ratio;
+    const k_max_ratio = tuning.k_max_ratio;
+
+    const h = dt / substeps;
+    const inverse_h = 1 / h;
+    const inverse_h_squared = inverse_h * inverse_h;
+
+    // Both ends of a self-collision pair are free, so the row's effective
+    // inertia along the constraint is half a particle's — the same reasoning the
+    // stretch table uses for an interior row. `CLOTH_SELF_RATIO` is a multiple
+    // of that.
+    //
+    // Behind the pair count, because `max_inverse_mass` is a scan over every
+    // particle and a cloth with the flag clear should not pay for a feature it
+    // does not have.
+    const self_stiffness = state.self_count > 0 && state.particle_count > 0
+        ? (tuning.self_ratio ?? CLOTH_SELF_RATIO) * inverse_h_squared * 0.5 / max_inverse_mass(state)
+        : 0;
+
+    const colour_count = state.colour_count;
+    const colour_offset = state.colour_offset;
+
+    const contacts = collider_table !== null && collider_count > 0 ? collider_table : null;
+
+    for (let substep = 0; substep < substeps; substep++) {
+        cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z);
+
+        if (contacts !== null) {
+            cloth_collider_pose_at(contacts, collider_count, (substep + 1) / substeps);
+        }
+
+        cloth_stretch_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared);
+        cloth_bend_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared);
+        cloth_leash_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared);
+        cloth_backstop_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared);
+
+        if (contacts !== null) {
+            cloth_contact_warm_start(
+                state, alpha, gamma,
+                CLOTH_CONTACT_K_MIN_RATIO, k_max_ratio, inverse_h_squared
+            );
+        }
+
+        for (let iteration = 0; iteration < iterations; iteration++) {
+            if (state.self_count > 0) {
+                cloth_self_accumulate_scratch(state, self_stiffness);
+            }
+
+            for (let colour = 0; colour < colour_count; colour++) {
+                const end = colour_offset[colour + 1];
+
+                for (let particle = colour_offset[colour]; particle < end; particle++) {
+                    cloth_solve_vertex(state, particle, 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);
+            cloth_backstop_dual_update(state, beta, k_max_ratio, inverse_h_squared);
+
+            if (contacts !== null) {
+                cloth_contact_dual_update(state, contacts, beta, k_max_ratio, inverse_h_squared);
+            }
+        }
+
+        cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, acceleration_z);
+    }
+
+    assert.equal(
+        find_non_finite_cloth_state(state), "",
+        'cloth state went non-finite during the step'
+    );
+}
+
+/**
+ * The largest inverse mass in the cloth — the lightest particle, which is the
+ * one a shared penalty has to be safe for.
+ *
+ * A self-collision pair's stiffness is one number for the whole cloth rather
+ * than one per pair, because every pair has the same two free ends and cloth's
+ * particles are uniform (`cloth_build_rows.js` says why a mass is arbitrary
+ * here). This is what makes that true even for a state a caller built by hand
+ * with mixed masses: the band is measured against the *lightest* particle, so no
+ * pair is above it.
+ *
+ * @param {ClothState} state
+ * @returns {number}
+ * @private
+ */
+function max_inverse_mass(state) {
+    const mass_inverse = state.mass_inverse;
+
+    let worst = 0;
+
+    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
+    // any finite value is as good as another.
+    return worst > 0 ? worst : 1;
+}
+
+/**
+ * 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.
+ *
+ * @param {ClothState} state
+ * @param {number} h
+ * @param {number} acceleration_x
+ * @param {number} acceleration_y
+ * @param {number} acceleration_z
+ * @private
+ */
+function cloth_predict(state, h, acceleration_x, acceleration_y, acceleration_z) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const position_previous = state.position_previous;
+    const velocity = state.velocity;
+    const inertial = state.inertial;
+    const mass_inverse = state.mass_inverse;
+    const inertia_blend = state.inertia_blend;
+
+    const h_squared = h * h;
+
+    const gravity_x = h_squared * acceleration_x;
+    const gravity_y = h_squared * acceleration_y;
+    const gravity_z = h_squared * acceleration_z;
+
+    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];
+
+        position_previous[p] = x;
+        position_previous[p + 1] = y;
+        position_previous[p + 2] = z;
+
+        if (mass_inverse[i] === 0) {
+            inertial[p] = x;
+            inertial[p + 1] = y;
+            inertial[p + 2] = z;
+
+            continue;
+        }
+
+        const drift_x = h * velocity[p];
+        const drift_y = h * velocity[p + 1];
+        const drift_z = h * velocity[p + 2];
+
+        inertial[p] = x + drift_x + gravity_x;
+        inertial[p + 1] = y + drift_y + gravity_y;
+        inertial[p + 2] = z + drift_z + gravity_z;
+
+        const blend = inertia_blend[i];
+
+        position[p] = x + drift_x + blend * gravity_x;
+        position[p + 1] = y + drift_y + blend * gravity_y;
+        position[p + 2] = z + drift_z + blend * gravity_z;
+    }
+}
+
+/**
+ * Integrate: read velocity back out of the positions the descent produced, and
+ * record how much of the resulting acceleration was the external one so the
+ * next substep can seed itself accordingly.
+ *
+ * The blend is VBD's: project the realised acceleration onto the external one
+ * and clamp to `[0, 1]`. A particle in free fall realises exactly `a_ext` and
+ * scores 1; a particle held by a taut tether realises nothing along `a_ext`
+ * and scores 0; a particle being decelerated scores 0 rather than a negative
+ * number, because seeding *against* the external acceleration is a worse guess
+ * than not seeding at all.
+ *
+ * @param {ClothState} state
+ * @param {number} inverse_h
+ * @param {number} acceleration_x
+ * @param {number} acceleration_y
+ * @param {number} acceleration_z
+ * @private
+ */
+function cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, acceleration_z) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const position_previous = state.position_previous;
+    const velocity = state.velocity;
+    const mass_inverse = state.mass_inverse;
+    const inertia_blend = state.inertia_blend;
+
+    const acceleration_squared =
+        acceleration_x * acceleration_x +
+        acceleration_y * acceleration_y +
+        acceleration_z * acceleration_z;
+
+    // With no external acceleration there is no direction to project onto and
+    // nothing to seed; the blend is meaningless rather than zero-or-one.
+    const inverse_acceleration_squared = acceleration_squared > 0 ? 1 / acceleration_squared : 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        if (mass_inverse[i] === 0) {
+            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;
+
+        const realised =
+            (next_x - velocity[p]) * acceleration_x +
+            (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;
+
+        velocity[p] = next_x;
+        velocity[p + 1] = next_y;
+        velocity[p + 2] = next_z;
+    }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * # The per-vertex `(f, H)` accumulator
+ *
+ * A vertex update (§5.2) builds a 3-vector force and a symmetric 3×3 Hessian
+ * by summing over the rows that touch one particle, then solves `H·Δ = f`.
+ * Every row kind contributes to the same pair, so the pair needs a layout the
+ * row modules and the solve agree on without importing each other.
+ *
+ * Nine `Float64` slots: the force, then the Hessian's diagonal, then its three
+ * distinct off-diagonal entries. `H` is symmetric by construction — it is
+ * `(m/h²)·I` plus a sum of `k·ggᵀ` rank-one terms — so storing six of its nine
+ * entries is not a compression, it is the whole matrix.
+ *
+ * `Float64` rather than the `Float32` of {@link ClothState}: the accumulation
+ * is where the arithmetic happens, and JavaScript does it in double anyway.
+ * Rounding once, when the resulting position is stored, is the only narrowing
+ * the design asks for.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/** Force, x. */
+export const CVA_F_X: 0;
+/** Force, y. */
+export const CVA_F_Y: 1;
+/** Force, z. */
+export const CVA_F_Z: 2;
+/** Hessian `H[0][0]`. */
+export const CVA_H_XX: 3;
+/** Hessian `H[1][1]`. */
+export const CVA_H_YY: 4;
+/** Hessian `H[2][2]`. */
+export const CVA_H_ZZ: 5;
+/** Hessian `H[0][1] = H[1][0]`. */
+export const CVA_H_XY: 6;
+/** Hessian `H[0][2] = H[2][0]`. */
+export const CVA_H_XZ: 7;
+/** Hessian `H[1][2] = H[2][1]`. */
+export const CVA_H_YZ: 8;
+/**
+ * Trust radius, metres: the shortest row the particle sits on at its current
+ * position. Seeded at `Infinity` and lowered by each row kind that has a length
+ * scale to offer.
+ *
+ * The vertex update is a Newton step on a model that is only a model, and for a
+ * distance row the model's `g` is the direction to a neighbour — meaningful
+ * over distances small compared to how far away that neighbour is, and
+ * meaningless beyond. This is that distance, and it is measured rather than
+ * configured.
+ */
+export const CVA_TRUST: 9;
+/** Slots in one accumulator. */
+export const CVA_STRIDE: 10;
+//# sourceMappingURL=cloth_vertex_accumulator.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,56 @@
+/**
+ * # The per-vertex `(f, H)` accumulator
+ *
+ * A vertex update (§5.2) builds a 3-vector force and a symmetric 3×3 Hessian
+ * by summing over the rows that touch one particle, then solves `H·Δ = f`.
+ * Every row kind contributes to the same pair, so the pair needs a layout the
+ * row modules and the solve agree on without importing each other.
+ *
+ * Nine `Float64` slots: the force, then the Hessian's diagonal, then its three
+ * distinct off-diagonal entries. `H` is symmetric by construction — it is
+ * `(m/h²)·I` plus a sum of `k·ggᵀ` rank-one terms — so storing six of its nine
+ * entries is not a compression, it is the whole matrix.
+ *
+ * `Float64` rather than the `Float32` of {@link ClothState}: the accumulation
+ * is where the arithmetic happens, and JavaScript does it in double anyway.
+ * Rounding once, when the resulting position is stored, is the only narrowing
+ * the design asks for.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Force, x. */
+export const CVA_F_X = 0;
+/** Force, y. */
+export const CVA_F_Y = 1;
+/** Force, z. */
+export const CVA_F_Z = 2;
+/** Hessian `H[0][0]`. */
+export const CVA_H_XX = 3;
+/** Hessian `H[1][1]`. */
+export const CVA_H_YY = 4;
+/** Hessian `H[2][2]`. */
+export const CVA_H_ZZ = 5;
+/** Hessian `H[0][1] = H[1][0]`. */
+export const CVA_H_XY = 6;
+/** Hessian `H[0][2] = H[2][0]`. */
+export const CVA_H_XZ = 7;
+/** Hessian `H[1][2] = H[2][1]`. */
+export const CVA_H_YZ = 8;
+
+/**
+ * Trust radius, metres: the shortest row the particle sits on at its current
+ * position. Seeded at `Infinity` and lowered by each row kind that has a length
+ * scale to offer.
+ *
+ * The vertex update is a Newton step on a model that is only a model, and for a
+ * distance row the model's `g` is the direction to a neighbour — meaningful
+ * over distances small compared to how far away that neighbour is, and
+ * meaningless beyond. This is that distance, and it is measured rather than
+ * configured.
+ */
+export const CVA_TRUST = 9;
+
+/** Slots in one accumulator. */
+export const CVA_STRIDE = 10;

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

@@ -0,0 +1,95 @@
+/**
+ * # Backstop — the half-space row
+ *
+ *     C(x) = r_b − (x_i − b_i)·n_i
+ *     ∂C/∂x_i = −n_i
+ *
+ * §6's row, verbatim: a particle is held at least `r_b` along its own normal
+ * from a point `b` just inside the body. `[0, +∞)` admits only forces that
+ * *reduce* `C`, which for this `C` means increasing `(x − b)·n` — pushing the
+ * particle out along its normal, which is what "never inside the body" means.
+ *
+ * ## What it is for, and why it is not a collider
+ *
+ * A cape's collider set approximates a torso with a handful of capsules, and
+ * between them is a gap the cloth can settle into. A backstop closes that gap
+ * without adding geometry: the plane is anchored to the particle's own
+ * *animated* position and its own surface normal, both of which the garment
+ * already knows, so it is a bound the mesh carries with it rather than a shape
+ * somebody has to author. Chaos Cloth ships the same thing under the same name
+ * and for the same reason (§15), and §7 P3 leans on it as one of the three
+ * layers that stop a garment tunnelling through a character.
+ *
+ * It is deliberately **not** a substitute for collision. A backstop is a plane
+ * per particle: it knows which way is out and nothing about what is actually
+ * there, so it cannot resolve a limb crossing the garment. The two rows answer
+ * different halves and a cape wants both.
+ *
+ * ## Where the plane comes from
+ *
+ * The caller writes it, per step, into {@link ClothState#backstop_plane} — the
+ * same contract {@link ClothState#leash_target} carries, and for the same
+ * reason: `b` and `n` are anchored to the animated pose, which moves, and are
+ * not properties of the rest shape.
+ *
+ * **M2 builds the row and does not author it.** The natural source is the
+ * garment's own skinned surface — `b` a short way inside along the vertex
+ * normal, `r_b` that distance again — and a skinned garment is M3. M2's entity
+ * path has a chain rather than a surface, so it has no normal to offer: a rope
+ * has no inside. So the row ships with storage, a spec and a playground demo
+ * driving it directly, and `cloth_proxy_build` is what will fill it.
+ *
+ * ## No trust region, and no geometric stiffness
+ *
+ * `C` is **linear** in `x`, so its second derivative is exactly zero — there is
+ * no geometric term to keep or drop — and its gradient is a constant unit
+ * vector, so there is no distance beyond which the linearisation stops
+ * describing it. A backstop is the one row in the system whose model is not a
+ * model.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Evaluate one backstop row's constraint value and its gradient.
+ *
+ * The definition the accumulation 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`
+ * @param {number} gradient_offset
+ * @param {ClothState} state
+ * @param {number} row
+ * @returns {number} `C`
+ */
+export function cloth_backstop_evaluate(gradient: Float64Array | number[], gradient_offset: number, state: ClothState, row: number): number;
+/**
+ * Add every backstop row touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_backstop_accumulate(accumulator: Float64Array, state: ClothState, particle: number): void;
+/**
+ * Warm start every backstop row for a substep. Every one is hard, so — as with
+ * the leash table — there is no soft branch.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha
+ * @param {number} gamma
+ * @param {number} k_min_ratio
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_backstop_warm_start(state: ClothState, alpha: number, gamma: number, k_min_ratio: number, k_max_ratio: number, inverse_h_squared: number): void;
+/**
+ * Dual update for every backstop row.
+ *
+ * @param {ClothState} state
+ * @param {number} beta
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_backstop_dual_update(state: ClothState, beta: number, k_max_ratio: number, inverse_h_squared: number): void;
+//# sourceMappingURL=cloth_backstop_row.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_backstop_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_backstop_row.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;;;;;;;GAWG;AACH,kDANW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,GACJ,MAAM,CAuBlB;AAED;;;;;;GAMG;AACH,uDAJW,YAAY,+BAEZ,MAAM,QA8EhB;AAED;;;;;;;;;;GAUG;AACH,oEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QAuChB;AAED;;;;;;;GAOG;AACH,oEAJW,MAAM,eACN,MAAM,qBACN,MAAM,QA2ChB"}