@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,204 @@
+/**
+ * # Solver constants, measured
+ *
+ * `α`, `β`, `γ`, `k_min` and `k_max` are the augmented Lagrangian's tuning.
+ * They are solver internals, they are global, and they are deliberately **not**
+ * on `ClothDynamics` — they are not a property of a fabric, and an author who
+ * has to reach for one of them has been handed the wrong knob.
+ *
+ * Nothing here was copied. The reference AVBD implementation is 2D and
+ * rigid-body-focused: mass terms `m/h²` in the hundreds against handfuls of
+ * hard rows, where cloth has single digits — a 0.3 kg cape across 600
+ * particles is half a gram each — against thousands of soft rows and a few
+ * hard ones. The values below come from
+ * `__fixtures__/cloth_constants_sweep.mjs`; run it to reproduce the tables, and
+ * see `MEASUREMENTS.md` beside `PLAN.md` for the full grids and the four things
+ * the sweep established that §5.2 did not anticipate.
+ *
+ * ## The band is a ratio, not a stiffness
+ *
+ * `k_min` and `k_max` are **multiples of the row's own inertial scale**
+ * `m_eff/h²`, not stiffnesses in N/m. The sweep held a 20-link hard chain at a
+ * fixed ratio while moving the particle mass across five decades and got the
+ * same residual column every time; held at a fixed *stiffness* it got a
+ * different answer for every mass. A stiffness in N/m is therefore not a
+ * constant at all, and the ratio is. §5.2's own reasoning agrees —
+ * `k_max/(m/h²)` is named there as the condition number the 3×3 solve has to
+ * survive — it just stops one step short of making the ratio the parameter.
+ *
+ * ## What each one does, and what the sweep found
+ *
+ * **`α` and `γ` act only through their product.** `α·γ` is how much of a hard
+ * row's multiplier survives a substep, and it is the one number that decides
+ * whether the solver converges or detonates: at `α·γ ≤ 0.3` a 20-link hard
+ * chain settles to rest with kinetic energy at 1e-9 J, at 0.5 it jitters, and
+ * at 0.6 it diverges. Residual improves monotonically towards that cliff, so
+ * the value is a margin decision rather than an optimum: **0.25, a factor of
+ * two clear of divergence.** γ is left at 1 because its second job — decaying
+ * the penalty — has nothing to do while the band is a single point, so putting
+ * the whole decay in α, whose only job is the multiplier, is the truthful
+ * placement. When M2's contacts make the band real again, γ becomes live and
+ * has to be re-measured.
+ *
+ * **`k_min` and `k_max` are equal, which disables the ramp.** Pinning the
+ * penalty at the top of the band measured as good as or better than every
+ * ramped alternative for M0's persistent rows, and it removes a
+ * scale-dependence that a ramp reintroduces: the ramp's speed is set by `β`,
+ * whose useful magnitude tracks `m/h²` the way `k` does, so a live ramp would
+ * make a heavy garment behave differently from a light one. The ramp exists
+ * for **transient** rows — a contact that should arrive soft and stiffen rather
+ * than shock the mesh on its first frame — and M0 has none.
+ *
+ * **`β` 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
+ */
+/**
+ * Multiplier regularisation, `[0, 1]`.
+ * @type {number}
+ */
+export const CLOTH_ALPHA: number;
+/**
+ * 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: number;
+/**
+ * Dual decay, `[0, 1)`.
+ * @type {number}
+ */
+export const CLOTH_GAMMA: number;
+/**
+ * Penalty floor, as a multiple of the row's `m/h²`.
+ * @type {number}
+ */
+export const CLOTH_K_MIN_RATIO: number;
+/**
+ * Penalty ceiling, as a multiple of the row's `m/h²`.
+ * @type {number}
+ */
+export const CLOTH_K_MAX_RATIO: number;
+/**
+ * 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: number;
+/**
+ * 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: number;
+/**
+ * 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: number;
+/**
+ * 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: number;
+/**
+ * The five constants as one frozen object, which is what {@link cloth_step}
+ * takes. A sweep passes its own; nothing else should.
+ * @type {Readonly<{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number}>}
+ */
+export const CLOTH_SOLVER_TUNING: Readonly<{
+    alpha: number;
+    beta: number;
+    gamma: number;
+    k_min_ratio: number;
+    k_max_ratio: number;
+}>;
+//# sourceMappingURL=cloth_solver_constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;GAIG;AACH,yBAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,kCAFU,SAAS;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,CAAC,CAQvG"}

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

@@ -0,0 +1,213 @@
+/**
+ * # Solver constants, measured
+ *
+ * `α`, `β`, `γ`, `k_min` and `k_max` are the augmented Lagrangian's tuning.
+ * They are solver internals, they are global, and they are deliberately **not**
+ * on `ClothDynamics` — they are not a property of a fabric, and an author who
+ * has to reach for one of them has been handed the wrong knob.
+ *
+ * Nothing here was copied. The reference AVBD implementation is 2D and
+ * rigid-body-focused: mass terms `m/h²` in the hundreds against handfuls of
+ * hard rows, where cloth has single digits — a 0.3 kg cape across 600
+ * particles is half a gram each — against thousands of soft rows and a few
+ * hard ones. The values below come from
+ * `__fixtures__/cloth_constants_sweep.mjs`; run it to reproduce the tables, and
+ * see `MEASUREMENTS.md` beside `PLAN.md` for the full grids and the four things
+ * the sweep established that §5.2 did not anticipate.
+ *
+ * ## The band is a ratio, not a stiffness
+ *
+ * `k_min` and `k_max` are **multiples of the row's own inertial scale**
+ * `m_eff/h²`, not stiffnesses in N/m. The sweep held a 20-link hard chain at a
+ * fixed ratio while moving the particle mass across five decades and got the
+ * same residual column every time; held at a fixed *stiffness* it got a
+ * different answer for every mass. A stiffness in N/m is therefore not a
+ * constant at all, and the ratio is. §5.2's own reasoning agrees —
+ * `k_max/(m/h²)` is named there as the condition number the 3×3 solve has to
+ * survive — it just stops one step short of making the ratio the parameter.
+ *
+ * ## What each one does, and what the sweep found
+ *
+ * **`α` and `γ` act only through their product.** `α·γ` is how much of a hard
+ * row's multiplier survives a substep, and it is the one number that decides
+ * whether the solver converges or detonates: at `α·γ ≤ 0.3` a 20-link hard
+ * chain settles to rest with kinetic energy at 1e-9 J, at 0.5 it jitters, and
+ * at 0.6 it diverges. Residual improves monotonically towards that cliff, so
+ * the value is a margin decision rather than an optimum: **0.25, a factor of
+ * two clear of divergence.** γ is left at 1 because its second job — decaying
+ * the penalty — has nothing to do while the band is a single point, so putting
+ * the whole decay in α, whose only job is the multiplier, is the truthful
+ * placement. When M2's contacts make the band real again, γ becomes live and
+ * has to be re-measured.
+ *
+ * **`k_min` and `k_max` are equal, which disables the ramp.** Pinning the
+ * penalty at the top of the band measured as good as or better than every
+ * ramped alternative for M0's persistent rows, and it removes a
+ * scale-dependence that a ramp reintroduces: the ramp's speed is set by `β`,
+ * whose useful magnitude tracks `m/h²` the way `k` does, so a live ramp would
+ * make a heavy garment behave differently from a light one. The ramp exists
+ * for **transient** rows — a contact that should arrive soft and stiffen rather
+ * than shock the mesh on its first frame — and M0 has none.
+ *
+ * **`β` 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
+ */
+
+/**
+ * Multiplier regularisation, `[0, 1]`.
+ * @type {number}
+ */
+export const CLOTH_ALPHA = 0.25;
+
+/**
+ * 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 = 1e3;
+
+/**
+ * Dual decay, `[0, 1)`.
+ * @type {number}
+ */
+export const CLOTH_GAMMA = 1;
+
+/**
+ * Penalty floor, as a multiple of the row's `m/h²`.
+ * @type {number}
+ */
+export const CLOTH_K_MIN_RATIO = 8;
+
+/**
+ * Penalty ceiling, as a multiple of the row's `m/h²`.
+ * @type {number}
+ */
+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.
+ * @type {Readonly<{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number}>}
+ */
+export const CLOTH_SOLVER_TUNING = Object.freeze({
+    alpha: CLOTH_ALPHA,
+    beta: CLOTH_BETA,
+    gamma: CLOTH_GAMMA,
+    k_min_ratio: CLOTH_K_MIN_RATIO,
+    k_max_ratio: CLOTH_K_MAX_RATIO
+});

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

@@ -0,0 +1,122 @@
+/**
+ * # 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: 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

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