@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -0,0 +1,362 @@
+import { cloth_backstop_accumulate } from "./constraint/cloth_backstop_row.js";
+import { cloth_contact_accumulate } from "./constraint/cloth_contact_row.js";
+import { cloth_leash_accumulate } from "./constraint/cloth_leash_row.js";
+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_STRIDE,
+    CVA_TRUST
+} from "./cloth_vertex_accumulator.js";
+
+/**
+ * # The turn about a hold line — one more block of the descent
+ *
+ * VBD is block coordinate descent on the step's energy, one 3×3 block per
+ * particle. A cloth whose held particles lie on one line has a motion no such
+ * block can make: turning the whole cloth about that line as a rigid body. Every
+ * internal row is unchanged by it — its ends turn together, or one of them is on
+ * the axis — so the only parts of the energy that see the turn are the inertial
+ * term and the rows measured from outside the cloth. When the line is vertical
+ * nothing outside restores it either, because gravity is parallel to the axis.
+ *
+ * A vertex update moves one particle, so every update adds `x_i × m·Δx_i` of
+ * angular momentum about the line, and the step stopped at a fabric's iteration
+ * count leaves a residual whose moment about it is not zero. The warm start keeps
+ * a quarter of each hard multiplier (§5.2), so a cloth at rest re-solves three
+ * quarters of its weight every substep, is never a fixed point, and leaves that
+ * residual every substep. A flag on a pole turned at ten degrees a second for as
+ * long as it was run (PLAN §18, `MEASUREMENTS.md` §63).
+ *
+ * So the turn gets a block of its own: **one Newton step of the substep's energy
+ * along the rotation about the hold line**, then every free particle turned by
+ * the angle it gives. It is a descent step on the same energy as the vertex
+ * updates, so §5.3 is untouched, and it changes no row, multiplier or constant.
+ *
+ * ## What enters
+ *
+ * With `a` the line's unit direction, `r_i` a particle's offset from the line's
+ * origin and `t_i = a × r_i` its velocity under a unit turn, along the path
+ * `x_i(θ) = o + R(θ)·r_i`:
+ *
+ *     g = dE/dθ   = Σ t_i·∇E_i
+ *     H = d²E/dθ² = Σ t_iᵀ·H_i·t_i + Σ ∇E_i·(a(a·r_i) − r_i)
+ *     θ = −g/H
+ *
+ * - `∇E_i` and `H_i` are the vertex update's own assembly with the internal rows
+ *   left out: the inertial term `(m/h²)(x − y)`, the leash rows, the backstop
+ *   rows and the contacts. Stretch, bend and self-collision rows are invariant
+ *   under the turn: a row's energy does not change along the path, so its share
+ *   of `g` is zero and its two shares of `H` cancel, and leaving it out is
+ *   leaving out a zero. A tether is invariant too, since it is measured from a
+ *   held particle and that is on the axis, but it shares its accumulation with
+ *   the slack row, which is not. It enters, and it can only shorten the step.
+ * - The last sum is the path's own curvature, `d²x/dθ² = −r⊥`. About a vertical
+ *   axis gravity has no part in it and what is left is close to zero; about a
+ *   horizontal one it is the pendulum's gravity stiffness. It is added only where
+ *   it is positive, which keeps `H` at least the first sum, positive definite
+ *   through the mass term: a step no longer than the one without it.
+ *
+ * ## When it runs
+ *
+ * When the held particles lie on one line **at this substep**, at two or more
+ * distinct points — a fact about the holds the predict already has in hand,
+ * since it carries every held particle. A single held point has three free turns
+ * and a cloth nothing holds has six; this block is the line's, and neither of
+ * those is handled here. It runs on a line gravity restores too, a horizontal
+ * one included, and there it has slowed some sleeps and kept one cloth awake
+ * (PLAN §18).
+ *
+ * It runs once a substep, in the **last** iteration, after the sweep and before
+ * that iteration's dual update. Run in every iteration it measured no better on
+ * a flag and cost 9–19% of a step rather than 3–9% (`MEASUREMENTS.md` §66).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * How far a held particle may sit off the line and still be on it, as a
+ * fraction of the largest coordinate among the held particles.
+ *
+ * Relative, because what it separates is rounding from geometry, and rounding is
+ * a proportion of magnitude. Held positions are `Float32` and are carried through
+ * the step in double and stored again at each substep. A flag turned off every
+ * axis, whose hoist is straight in exact arithmetic, measured at most 6.3e-8 of
+ * its largest coordinate off its own line — half a unit in the last place —
+ * from the origin out to four kilometres. This is 240 times that, and 15 µm at a
+ * metre. `MEASUREMENTS.md` §66.
+ *
+ * @type {number}
+ */
+export const CLOTH_HOLD_LINE_TOLERANCE = 2 ** -16;
+
+/**
+ * Words of a hold line: the origin, then the unit direction.
+ * @type {number}
+ */
+export const CLOTH_HOLD_LINE_WORDS = 6;
+
+/**
+ * Whether the held particles lie on one line, and which: written to `line` as
+ * the origin then the unit direction.
+ *
+ * The origin is the first held particle and the direction runs to the one
+ * furthest from it, which spans at least half of the set. Every held particle is
+ * then measured off that line.
+ *
+ * @param {Float64Array} line out, {@link CLOTH_HOLD_LINE_WORDS}
+ * @param {Float32Array} position
+ * @param {Int32Array} held particle indices
+ * @param {number} held_count
+ * @returns {boolean} `false` when there are fewer than two distinct held points
+ *   or they are not on one line; `line` is then not written
+ */
+export function cloth_hold_line_fit(line, position, held, held_count) {
+    if (held_count < 2) {
+        return false;
+    }
+
+    const o = held[0] * 3;
+
+    const ox = position[o];
+    const oy = position[o + 1];
+    const oz = position[o + 2];
+
+    let scale = Math.max(Math.abs(ox), Math.abs(oy), Math.abs(oz));
+
+    let far = o;
+    let far_squared = 0;
+
+    for (let k = 1; k < held_count; k++) {
+        const p = held[k] * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        const size_x = Math.abs(x);
+        const size_y = Math.abs(y);
+        const size_z = Math.abs(z);
+
+        if (size_x > scale) {
+            scale = size_x;
+        }
+
+        if (size_y > scale) {
+            scale = size_y;
+        }
+
+        if (size_z > scale) {
+            scale = size_z;
+        }
+
+        const dx = x - ox;
+        const dy = y - oy;
+        const dz = z - oz;
+
+        const d_squared = dx * dx + dy * dy + dz * dz;
+
+        if (d_squared > far_squared) {
+            far_squared = d_squared;
+            far = p;
+        }
+    }
+
+    const tolerance = CLOTH_HOLD_LINE_TOLERANCE * scale;
+
+    const far_distance = Math.sqrt(far_squared);
+
+    if (!(far_distance > tolerance)) {
+        // One point, however many particles are held at it.
+        return false;
+    }
+
+    const inverse = 1 / far_distance;
+
+    const ax = (position[far] - ox) * inverse;
+    const ay = (position[far + 1] - oy) * inverse;
+    const az = (position[far + 2] - oz) * inverse;
+
+    const tolerance_squared = tolerance * tolerance;
+
+    for (let k = 1; k < held_count; k++) {
+        const p = held[k] * 3;
+
+        const rx = position[p] - ox;
+        const ry = position[p + 1] - oy;
+        const rz = position[p + 2] - oz;
+
+        const along = rx * ax + ry * ay + rz * az;
+
+        const qx = rx - along * ax;
+        const qy = ry - along * ay;
+        const qz = rz - along * az;
+
+        if (qx * qx + qy * qy + qz * qz > tolerance_squared) {
+            return false;
+        }
+    }
+
+    line[0] = ox;
+    line[1] = oy;
+    line[2] = oz;
+    line[3] = ax;
+    line[4] = ay;
+    line[5] = az;
+
+    return true;
+}
+
+/**
+ * Take one Newton step of the substep's energy along the turn about `line`, and
+ * turn every free particle by the angle it gives — see the module docblock.
+ *
+ * @param {ClothState} state
+ * @param {Float64Array} line from {@link cloth_hold_line_fit}
+ * @param {number} inverse_h_squared `1/h²` for the substep in progress
+ * @param {Float32Array|Float64Array|null} collider_table as the vertex update
+ *   takes it; `null` skips the contact rows
+ * @returns {number} the angle turned, radians; `0` when there is nothing to turn
+ */
+export function cloth_hold_line_turn(state, line, inverse_h_squared, collider_table) {
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const inertial = state.inertial;
+    const mass_inverse = state.mass_inverse;
+
+    const ox = line[0];
+    const oy = line[1];
+    const oz = line[2];
+    const ax = line[3];
+    const ay = line[4];
+    const az = line[5];
+
+    const accumulator = ACCUMULATOR;
+
+    let gradient = 0;
+    let curvature = 0;
+    let path = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const inverse_mass = mass_inverse[i];
+
+        if (inverse_mass === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        const rx = x - ox;
+        const ry = y - oy;
+        const rz = z - oz;
+
+        const tx = ay * rz - az * ry;
+        const ty = az * rx - ax * rz;
+        const tz = ax * ry - ay * rx;
+
+        // The vertex update's assembly, seeded the same way, with only the rows
+        // the turn can see.
+        const mass_over_h_squared = inverse_h_squared / inverse_mass;
+
+        accumulator[CVA_F_X] = -mass_over_h_squared * (x - inertial[p]);
+        accumulator[CVA_F_Y] = -mass_over_h_squared * (y - inertial[p + 1]);
+        accumulator[CVA_F_Z] = -mass_over_h_squared * (z - inertial[p + 2]);
+
+        accumulator[CVA_H_XX] = mass_over_h_squared;
+        accumulator[CVA_H_YY] = mass_over_h_squared;
+        accumulator[CVA_H_ZZ] = mass_over_h_squared;
+        accumulator[CVA_H_XY] = 0;
+        accumulator[CVA_H_XZ] = 0;
+        accumulator[CVA_H_YZ] = 0;
+        accumulator[CVA_TRUST] = Infinity;
+
+        cloth_leash_accumulate(accumulator, state, i);
+        cloth_backstop_accumulate(accumulator, state, i);
+
+        if (collider_table !== null) {
+            cloth_contact_accumulate(accumulator, state, i, collider_table);
+        }
+
+        // `f = −∇E_i`
+        const fx = accumulator[CVA_F_X];
+        const fy = accumulator[CVA_F_Y];
+        const fz = accumulator[CVA_F_Z];
+
+        gradient -= tx * fx + ty * fy + tz * fz;
+
+        const h_xx = accumulator[CVA_H_XX];
+        const h_yy = accumulator[CVA_H_YY];
+        const h_zz = accumulator[CVA_H_ZZ];
+        const h_xy = accumulator[CVA_H_XY];
+        const h_xz = accumulator[CVA_H_XZ];
+        const h_yz = accumulator[CVA_H_YZ];
+
+        curvature += tx * (h_xx * tx + h_xy * ty + h_xz * tz)
+            + ty * (h_xy * tx + h_yy * ty + h_yz * tz)
+            + tz * (h_xz * tx + h_yz * ty + h_zz * tz);
+
+        // `∇E_i·(a(a·r) − r)`, which is `f·r⊥`
+        const along = ax * rx + ay * ry + az * rz;
+
+        path += fx * (rx - along * ax) + fy * (ry - along * ay) + fz * (rz - along * az);
+    }
+
+    if (path > 0) {
+        curvature += path;
+    }
+
+    if (!(curvature > 0)) {
+        // Every free particle is on the axis: there is no turn to take.
+        return 0;
+    }
+
+    const theta = -gradient / curvature;
+
+    if (theta === 0) {
+        return 0;
+    }
+
+    // Rodrigues, about the line through `o`.
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const versine = 1 - cos;
+
+    for (let i = 0; i < particle_count; i++) {
+        if (mass_inverse[i] === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        const rx = position[p] - ox;
+        const ry = position[p + 1] - oy;
+        const rz = position[p + 2] - oz;
+
+        const along = (ax * rx + ay * ry + az * rz) * versine;
+
+        position[p] = ox + rx * cos + (ay * rz - az * ry) * sin + ax * along;
+        position[p + 1] = oy + ry * cos + (az * rx - ax * rz) * sin + ay * along;
+        position[p + 2] = oz + rz * cos + (ax * ry - ay * rx) * sin + az * along;
+    }
+
+    return theta;
+}
+
+/**
+ * The `(f, H)` scratch, laid out as the vertex update's. Module-level and reused.
+ * @type {Float64Array}
+ * @private
+ */
+const ACCUMULATOR = new Float64Array(CVA_STRIDE);

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

@@ -28,8 +28,12 @@ export function cloth_self_exclusions(state: ClothState): {
  * measured left the settled cape with three permanently active pairs.
  * `MEASUREMENTS.md` §37.
  *
- * Pinned particles are skipped, exactly as {@link cloth_self_find} skips them,
- * so this measures the pairs the row can actually act on and nothing else.
+ * **Every particle is measured, held or not.** Which particles are held changes
+ * while a cloth runs — a hand lets go, a hook catches — and this is measured
+ * once, when the rows are built; a ceiling that left out the particles held at
+ * that moment would be too generous for the cloth once they were let go, which
+ * is §36's permanently active pair. {@link cloth_self_find} pairs a held
+ * particle with a free one for the same reason.
  *
  * @param {ClothState} state
  * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CA0DrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAoHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AA1aD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}
+{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CA0DrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAgHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AA1aD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}

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

@@ -142,8 +142,12 @@ export function cloth_self_exclusions(state) {
  * measured left the settled cape with three permanently active pairs.
  * `MEASUREMENTS.md` §37.
  *
- * Pinned particles are skipped, exactly as {@link cloth_self_find} skips them,
- * so this measures the pairs the row can actually act on and nothing else.
+ * **Every particle is measured, held or not.** Which particles are held changes
+ * while a cloth runs — a hand lets go, a hook catches — and this is measured
+ * once, when the rows are built; a ceiling that left out the particles held at
+ * that moment would be too generous for the cloth once they were let go, which
+ * is §36's permanently active pair. {@link cloth_self_find} pairs a held
+ * particle with a free one for the same reason.
  *
  * @param {ClothState} state
  * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}
@@ -179,10 +183,6 @@ export function cloth_self_closest_free_pair(state, exclusions, search) {
     let closest_squared = search * search;
 
     for (let i = 0; i < particle_count; i++) {
-        if (mass_inverse[i] === 0) {
-            continue;
-        }
-
         const a = i * 3;
 
         const x = position[a];
@@ -224,7 +224,7 @@ export function cloth_self_closest_free_pair(state, exclusions, search) {
                     for (let at = grid_offset[bucket]; at < end; at++) {
                         const j = grid_point[at];
 
-                        if (j <= i || mass_inverse[j] === 0) {
+                        if (j <= i) {
                             continue;
                         }
 
@@ -308,11 +308,11 @@ export function cloth_self_find(state, exclusions) {
     const radius_squared = radius * radius;
 
     for (let i = 0; i < particle_count; i++) {
-        if (mass_inverse[i] === 0) {
-            // A pinned particle cannot be pushed, so a pair on it is a force
-            // assembled and thrown away for one end and doubled for the other.
-            continue;
-        }
+        // A held particle is paired with free ones and not with another held
+        // one: it cannot be pushed, but it can be carried through the fabric —
+        // a grabbed corner swept across the sheet — and the free end of the
+        // pair is what has to get out of its way.
+        const i_held = mass_inverse[i] === 0;
 
         const a = i * 3;
 
@@ -365,7 +365,7 @@ export function cloth_self_find(state, exclusions) {
                             continue;
                         }
 
-                        if (mass_inverse[j] === 0) {
+                        if (i_held && mass_inverse[j] === 0) {
                             continue;
                         }
 

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

@@ -145,18 +145,30 @@ export const CLOTH_CONTACT_K_MIN_RATIO: number;
  * 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.
+ * **Two: the stiffest ratio at which cloth resting on itself comes to rest.**
+ * The ratio trades two measured things against each other.
+ *
+ * - **A stiffer row passes through itself less while the cloth moves.** On
+ *   §32's folding sheet, over 48 gusts, silk, cotton, hair and a sheet with no
+ *   bending average 2.09 crossings a sample at 8, 2.98 at 2 and 3.74 at 1,
+ *   against 9.17 with no row. That is why §32 shipped 8.
+ * - **A pair that carries weight is a spring that is on every step**, which is
+ *   the case M0's dissipative band was measured on. §32's sheet never had one,
+ *   because its contacts come and go, so its "no energy growth anywhere" held
+ *   only for that sheet. A fold resting on a fold has one. At 8, piles of
+ *   ribbons, a sheet draped on a sphere and a skirt after a twirl never sleep,
+ *   and piles reach 3.8 times the speed their drop could give them (§64).
+ *
+ * At 2 all three sleep. Of 225 ribbon piles in three fabrics, 135 land without
+ * passing through themselves and 134 of those come to rest. At 4, five of 38
+ * clean silk piles never do. The draped sheet sleeps by step 386 at every
+ * ratio up to 2.25 and is erratic above it, never sleeping at 5 or 8. Below 2
+ * the folding sheet only gets worse, and more piles land through themselves.
+ * The library bench cannot tell 2 from 8. `MEASUREMENTS.md` §65.
+ *
+ * It stays a plain penalty: 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;

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,mCAFU,MAAM,CAEuB;AAEvC;;;;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"}
+{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,mCAFU,MAAM,CAEuB;AAEvC;;;;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

@@ -152,21 +152,33 @@ export const CLOTH_CONTACT_K_MIN_RATIO = 0.25;
  * 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.
+ * **Two: the stiffest ratio at which cloth resting on itself comes to rest.**
+ * The ratio trades two measured things against each other.
  *
- * 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.
+ * - **A stiffer row passes through itself less while the cloth moves.** On
+ *   §32's folding sheet, over 48 gusts, silk, cotton, hair and a sheet with no
+ *   bending average 2.09 crossings a sample at 8, 2.98 at 2 and 3.74 at 1,
+ *   against 9.17 with no row. That is why §32 shipped 8.
+ * - **A pair that carries weight is a spring that is on every step**, which is
+ *   the case M0's dissipative band was measured on. §32's sheet never had one,
+ *   because its contacts come and go, so its "no energy growth anywhere" held
+ *   only for that sheet. A fold resting on a fold has one. At 8, piles of
+ *   ribbons, a sheet draped on a sphere and a skirt after a twirl never sleep,
+ *   and piles reach 3.8 times the speed their drop could give them (§64).
+ *
+ * At 2 all three sleep. Of 225 ribbon piles in three fabrics, 135 land without
+ * passing through themselves and 134 of those come to rest. At 4, five of 38
+ * clean silk piles never do. The draped sheet sleeps by step 386 at every
+ * ratio up to 2.25 and is erratic above it, never sleeping at 5 or 8. Below 2
+ * the folding sheet only gets worse, and more piles land through themselves.
+ * The library bench cannot tell 2 from 8. `MEASUREMENTS.md` §65.
+ *
+ * It stays a plain penalty: 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;
+export const CLOTH_SELF_RATIO = 2;
 
 /**
  * Smallest radius a self-collision row is written at, as a multiple of the

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

@@ -11,6 +11,7 @@
  *     warm start   λ ← λ·α·γ ;  k ← clamp(k·γ, k_min, k_max)      (hard rows only)
  *     iterate      × iterations:
  *                    for each colour: for each particle: vertex update
+ *                    last iteration, held particles on one line: turn about it
  *                    dual update:  λ ← clamp(k·C + λ, f_min, f_max)
  *                                  k ← min(k + β·|C|, min(k_max, stiffness))
  *     integrate    v  = (x − x_prev)/h
@@ -54,6 +55,21 @@
  * which is what makes "no wind produces the bytes M5 measured" a fact about the
  * code rather than a claim about floating point.
  *
+ * ## One more block when the holds are a line
+ *
+ * Every vertex update is a 3×3 block of the descent, and a cloth held along one
+ * line has a motion no such block can make: turning about the line as a rigid
+ * body. About a vertical line nothing restores that turn, and the step stopped
+ * at a fabric's iteration count left a moment about it every substep — a flag
+ * turned on its pole for as long as it was run. So the turn is a block of its
+ * own, `cloth_hold_line.js`: one Newton step along it, in the last iteration,
+ * after the sweep and before the dual update.
+ *
+ * Whether the held particles are on a line is decided at every substep, from
+ * where the predict has just carried them. The predict lists them as it goes,
+ * so the question costs a pass over the held particles rather than over the
+ * cloth.
+ *
  * ## What each piece is for
  *
  * **Warm start** carries the multipliers into the next substep so a hard row

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":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,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,aAC3G,YAAY,GAAC,IAAI,QAsG3B"}
+{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,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,aAC3G,YAAY,GAAC,IAAI,QAkI3B"}