@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -49,10 +49,26 @@
  * for **transient** rows — a contact that should arrive soft and stiffen rather
  * than shock the mesh on its first frame — and M0 has none.
  *
- * **`β` could not be chosen from M0 data.** Above about 1e4 every M0 scenario
- * gives an identical answer, and with the band collapsed it has no effect at
- * all. The value below is a placeholder that M2 must replace with a
- * measurement against real contacts.
+ * **`β` is M2's, and it is 1e3 rather than M0's 1e5 placeholder.** M0 could not
+ * choose it: above about 1e4 every M0 scenario gave an identical answer, and
+ * with the band collapsed it had no effect at all. M2's contacts are the first
+ * transient rows in the system and the ramp is finally live. Measured on a
+ * 400-particle sheet landing on the ground, both ends of the range are worse
+ * than the middle: **no ramp at all** leaves a fast arrival's penalty at the
+ * floor and the multiplier alone to carry it, which settles at 1.95 J of
+ * residual kinetic energy against 0.12 J at 1e3; a **fast** ramp reaches the
+ * ceiling on violations of a millimetre and gives up most of what the low floor
+ * bought, settling three orders of magnitude worse on a gentle landing
+ * (6.4e-5 J against 3.2e-8 J). `MEASUREMENTS.md` §17.
+ *
+ * The scale-dependence the paragraph above warns of is real and is stated
+ * rather than removed: `β` has units of N/m², so it is a stiffness *per metre
+ * of violation*, and 1e3 against a ceiling of `8·(m/h²)` means the ramp is
+ * inert for a millimetre of penetration and reaches the ceiling within a step
+ * for a decimetre of it. That shape — gentle where the contact is grazing,
+ * immediate where it is a real interpenetration — is what the measurement
+ * picked, and a ratio-valued `β` that removed the dependence would have to
+ * choose the reference length that shape is built out of.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -65,10 +81,11 @@
 export const CLOTH_ALPHA = 0.25;
 
 /**
- * Penalty ramp.
+ * Penalty ramp, N/m². See the module docblock — measured at M2, against the
+ * first transient rows the system has.
  * @type {number}
  */
-export const CLOTH_BETA = 1e5;
+export const CLOTH_BETA = 1e3;
 
 /**
  * Dual decay, `[0, 1)`.
@@ -88,6 +105,100 @@ export const CLOTH_K_MIN_RATIO = 8;
  */
 export const CLOTH_K_MAX_RATIO = 8;
 
+/**
+ * Penalty floor for a **contact** row, as a multiple of the row's `m/h²`.
+ *
+ * Separate from {@link CLOTH_K_MIN_RATIO}, which is pinned to the ceiling,
+ * because a contact is the one row kind that *arrives*: a persistent row has
+ * been converging since the cloth was seeded and wants the stiffest penalty the
+ * step is stable at, and a contact that starts there shocks the mesh on its
+ * first frame.
+ *
+ * **A thirty-second of the ceiling**, measured. The floor is what decides how
+ * hard a new contact hits, and the measurement is unambiguous about the
+ * direction: on a sheet landing at 3 m/s, the peak contact force falls from
+ * 18.9 N at the ceiling to 0.16 N at an eighth of it and the settled kinetic
+ * energy falls by six orders of magnitude, while the penetration *improves*
+ * from 1.6 cm to 1.1 cm. Below about an eighth the numbers stop moving — every
+ * floor from ×1/8 down to ×1/128 gives the same penetration to three figures —
+ * so the value is a margin decision the same way `α·γ` was, and ×1/32 sits in
+ * the middle of the flat region with two decades of ramp above it.
+ *
+ * The reason the floor matters so little to the *residual* is the augmented
+ * Lagrangian working as designed: the multiplier carries the load and the
+ * penalty only has to be large enough to generate one. See MEASUREMENTS §17.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_K_MIN_RATIO = 0.25;
+
+/**
+ * Penalty stiffness for a **self-collision** row, as a multiple of the row's
+ * own `m_eff/h²`.
+ *
+ * It is a plain penalty rather than a hard row because the load it carries is
+ * cloth against cloth. `MEASUREMENTS.md` §18 measured why a *collider* contact
+ * cannot be soft — 376 N for a sheet arriving at 8 m/s against the 4.6 N a soft
+ * row inside M0's dissipative band can deliver — and a self-collision row never
+ * sees anything of the kind: what it holds apart weighs grams and is moving at
+ * the speed cloth moves relative to itself.
+ *
+ * **Eight, and the dissipative band is not the reason.** Eight is where M0's
+ * band tops out and it would be natural to read this as the same ceiling, but
+ * `MEASUREMENTS.md` §32 swept the ratio from 1 to 64 and found no energy growth
+ * anywhere: the band was measured on rows that are *on every step*, and a
+ * one-sided row that vanishes the instant it is satisfied has no standing spring
+ * to pump. What picks eight is the crossing count — it is the joint minimum of
+ * the mean, and a stiffer row makes the *worst* case steadily worse by throwing
+ * a particle hard enough to put the sheet through itself elsewhere.
+ *
+ * The consequence is a row with no multiplier, no warm start and no identity
+ * across steps, which is what makes rebuilding the pair list from scratch every
+ * step affordable. `MEASUREMENTS.md` §33.
+ * @type {number}
+ */
+export const CLOTH_SELF_RATIO = 8;
+
+/**
+ * Smallest radius a self-collision row is written at, as a multiple of the
+ * cloth's shortest row — so the row's **diameter** is one particle spacing.
+ *
+ * `ClothState#self_radius` carries why the radius is a property of the proxy
+ * rather than of the fabric, and `MEASUREMENTS.md` §31 is the sweep: at the
+ * fabric's own thickness the row removes 21% of a folding sheet's
+ * self-intersections and here it removes 82%.
+ * @type {number}
+ */
+export const CLOTH_SELF_RADIUS_MIN_RATIO = 0.5;
+
+/**
+ * Largest radius a self-collision row is written at, as a fraction of the
+ * closest two particles get **with no row between them** in the bind pose —
+ * `ClothInstance#closest_free_pair`. Two fifths of it, so the row's diameter is
+ * four fifths of the nearest thing it could touch and a cloth at rest is never
+ * in contact with itself.
+ *
+ * **A ceiling is needed because the floor is not always reachable.** A thick
+ * fabric on a coarse proxy takes its thickness rather than
+ * {@link CLOTH_SELF_RADIUS_MIN_RATIO}, and a diameter that reaches the nearest
+ * ungoverned pair puts a cloth that is not folded at all in permanent contact
+ * with itself — leather, 20 mm thick on a 20 mm proxy, found 1,398 pairs a step
+ * across 576 particles standing still. `MEASUREMENTS.md` §36.
+ *
+ * **And it is measured rather than derived, because a garment is not a sheet.**
+ * On a triangulated sheet the closest ungoverned pair is exactly two hops, so
+ * this comes out at four fifths of the shortest row and the analytic answer
+ * would have done — checked at two spacings, to the precision the proxy's
+ * Float32 positions carry. A rigged
+ * garment's proxy is *strips* with nothing joining one to the next, so every
+ * pair across the gap is ungoverned at whatever distance the artist put the
+ * joints, which the shortest row knows nothing about: the playground's cape has
+ * 8 cm links and 8.5 cm gaps, half what a sheet would imply. Derived from the
+ * link length the ceiling left that cape with three pairs permanently in
+ * contact at rest; measured, it has none. `MEASUREMENTS.md` §37.
+ * @type {number}
+ */
+export const CLOTH_SELF_RADIUS_MAX_RATIO = 0.4;
+
 /**
  * The five constants as one frozen object, which is what {@link cloth_step}
  * takes. A sweep passes its own; nothing else should.

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

@@ -15,10 +15,29 @@
  *                                  k ← min(k + β·|C|, min(k_max, stiffness))
  *     integrate    v  = (x − x_prev)/h
  *
- * The three row kinds — stretch, bend and leash — 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.
+ * 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
  *
@@ -50,9 +69,17 @@
  *
  * ## What is deliberately not here
  *
- * *Chebyshev acceleration* (§5.2) is off by default and gated on a particle
- * not being in contact this step; contacts arrive at M2 and there is nothing
- * in M0 for it to be measured against, so it lands with them.
+ * *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
@@ -79,13 +106,17 @@
  * @param {number} acceleration_z
  * @param {number} substeps
  * @param {number} iterations descent iterations per substep
- * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number}} [tuning]
+ * @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: ClothState, dt: number, acceleration_x: number, acceleration_y: number, acceleration_z: number, substeps: number, iterations: number, tuning?: {
+export function cloth_step(state: ClothState, dt: number, acceleration_x: number, acceleration_y: number, acceleration_z: number, substeps: number, iterations: number, collider_table?: Float32Array | Float64Array | null, collider_count?: number, tuning?: {
     alpha: number;
     beta: number;
     gamma: number;
     k_min_ratio: number;
     k_max_ratio: number;
+    self_ratio?: number;
 }): void;
 //# sourceMappingURL=cloth_step.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH;;;;;;;;;;;GAWG;AACH,kDARW,MAAM,kBACN,MAAM,kBACN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,QAsDhG"}
+{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH;;;;;;;;;;;;;;GAcG;AACH,kDAXW,MAAM,kBACN,MAAM,kBACN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,QA2FrH"}

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

@@ -1,10 +1,24 @@
 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_SOLVER_TUNING } from "./cloth_solver_constants.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
@@ -32,10 +46,29 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *                                  k ← min(k + β·|C|, min(k_max, stiffness))
  *     integrate    v  = (x − x_prev)/h
  *
- * The three row kinds — stretch, bend and leash — 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.
+ * 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
  *
@@ -67,9 +100,17 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *
  * ## What is deliberately not here
  *
- * *Chebyshev acceleration* (§5.2) is off by default and gated on a particle
- * not being in contact this step; contacts arrive at M2 and there is nothing
- * in M0 for it to be measured against, so it lands with them.
+ * *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
@@ -97,7 +138,10 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  * @param {number} acceleration_z
  * @param {number} substeps
  * @param {number} iterations descent iterations per substep
- * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number}} [tuning]
+ * @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,
@@ -105,6 +149,8 @@ export function cloth_step(
     acceleration_x, acceleration_y, acceleration_z,
     substeps,
     iterations,
+    collider_table = null,
+    collider_count = 0,
     tuning = CLOTH_SOLVER_TUNING
 ) {
     assert.isPositiveInteger(substeps, 'substeps');
@@ -120,28 +166,63 @@ export function cloth_step(
     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);
+                    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);
@@ -153,6 +234,37 @@ export function cloth_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.

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"}