@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -39,16 +39,24 @@
  * the whole decay in α, whose only job is the multiplier, is the truthful
  * placement.
  *
- * **γ is the one unmeasured constant in this file, and that is now a decision.**
- * The sentence above used to end "when M2's contacts make the band real again, γ
- * becomes live and has to be re-measured". M2 made the band real — a contact's
- * floor is {@link CLOTH_CONTACT_K_MIN_RATIO} and its ceiling is
- * {@link CLOTH_K_MAX_RATIO} — and the sweep was never run. Nothing measured
- * since has asked for a decaying penalty; what a `γ < 1` *would* reach is the
- * one thing PLAN §18 records as a coupling rather than a bug, which is that a
- * contact's penalty ramps to the ceiling and never comes back down. Sweeping it
- * means re-measuring every hard row in the system against `α·γ`, because the two
- * act only through their product and `α` is the one that was measured.
+ * **γ stays 1 for the persistent rows, and a contact now has a penalty decay
+ * of its own.** The paragraph that stood here called γ the one unmeasured
+ * constant, and named what a `γ < 1` would reach: PLAN §18's coupling, that a
+ * contact's penalty ramps to the ceiling and never comes back down. The ratio
+ * ramp made that live. A row violated by millimetres while a pile lands is at
+ * the ceiling for good, and at the ceiling §53's limit cycle is too large for
+ * silk to sleep: a ribbon pile never came to rest, a twirled skirt settled 17 mm
+ * from where it hung, a draped sheet was carried 4° less. So
+ * {@link CLOTH_CONTACT_GAMMA} decays a contact's two penalties per substep, the
+ * multiplier's `α·γ` untouched; a quiet row sinks back to the floor in a few
+ * steps and a violated one re-climbs within an iteration. Measured at 0.8, and
+ * the friction penalty has to decay with the normal one: decaying the normal
+ * penalty alone left the resting rope's sleep erratic (never at 0.8 and 0.75
+ * with friction, never at 0.7 without), decaying both sleeps every scene from
+ * 0.5 to 0.95. What it costs is static friction's exactness: a sheet on a slope
+ * it should stick to creeps 0.2–0.3 mm in four seconds, and the marginal case,
+ * μ a tenth over the tangent, slides 0.55 m where the shipped ramp slid 0.19.
+ * `MEASUREMENTS.md` §67.
  *
  * **`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
@@ -71,14 +79,23 @@
  * 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.
+ * **The contact's normal ramp is a ratio now, and `β` no longer runs it.** The
+ * paragraph that stood here said the scale-dependence of a ramp in N/m² was
+ * "stated rather than removed", because a ratio-valued ramp "would have to
+ * choose the reference length that shape is built out of". The cloth-skirt
+ * example chose it: a thigh advancing 17 mm a substep into a hanging skirt
+ * sat at the penalty floor for the whole of its arrival, because 1e3 N/m²
+ * against that cloth's band of 72 to 2,300 N/m is **0.003 of the band per
+ * contact offset of violation**, and the row's multiplier — rebuilt from a
+ * quarter every substep — could not carry a limb's push in four iterations.
+ * Twelve per cent of the dance had a thigh showing through, up to 13 mm, and
+ * four times the iteration budget made it zero. The reference length is the
+ * contact offset itself: {@link CLOTH_CONTACT_RAMP_RATIO} is how much of the
+ * band a contact gains per offset of violation per iteration, and the shape
+ * the M2 measurement picked — gentle grazing, immediate interpenetration — is
+ * kept, in the units the contact is defined in. `β` still ramps the friction
+ * row, which is unmeasured, and the persistent rows, where `k_min = k_max`
+ * makes it inert. `MEASUREMENTS.md` §67.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -134,6 +151,58 @@ export const CLOTH_K_MAX_RATIO: number;
  * @type {number}
  */
 export const CLOTH_CONTACT_K_MIN_RATIO: number;
+/**
+ * How fast a **contact** row's normal penalty climbs, as the fraction of the
+ * band `[floor, k_max]` it gains per contact offset of violation per iteration:
+ *
+ *     k ← min(k + ratio · k_max · |C| / (thickness + inflation), k_max)
+ *
+ * **A tenth, measured on both sides.** On the cloth-skirt example the thigh
+ * penetration is on a plateau from 0.05 up (12.7% of steps → 0.1%, the
+ * deepest shortfall of the offset 18.6 → 7.7 mm); below it a sweeping limb
+ * still gets through (0.03: 0.5%). On the other side a rope **resting** on a
+ * floor with friction — §53's limit cycle — sleeps at 0.2 and never at 0.25,
+ * because every speculative row round the resting particles is at the
+ * ceiling before it is touched. A tenth is a factor of two clear of each.
+ * It is also at least as good as the ramp it replaces on the scene that
+ * chose that ramp: M2's sheet landing at 3 m/s reads 0.68 mm of penetration
+ * against 1.10, with its settled kinetic energy eight times lower and the
+ * peak contact force 9% higher, and M2 §6's capsule swept through a hanging
+ * sheet at 2 m/s reads 1.8 mm against 17. The tunnelling threshold does not
+ * move — that bound is the substep count. `MEASUREMENTS.md` §67.
+ *
+ * **It ramps whether or not the row is active**, as before. Ramping only
+ * active rows — the reference implementation's form — leaves a sweeping limb
+ * through more often (1.0% of the skirt's steps against 0.1%) and takes the
+ * speed a thrown particle is still stopped at from 6 to 4 m/s at two
+ * substeps, which is §54's one-sided-ramp finding again: the pre-stiffening
+ * of speculative rows is what a fast arrival hits.
+ *
+ * A contact offset of zero is not a contact `ClothDynamics` allows, and a
+ * division by it climbs straight to `k_max` rather than anywhere worse.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_RAMP_RATIO: number;
+/**
+ * How much of a **contact** row's penalties — the normal row's and the friction
+ * row's — survives a substep's warm start. The multiplier decays by `α·γ` as
+ * every hard row's does; this is the band's own decay, which the persistent
+ * rows do not have because their band is a single point.
+ *
+ * **0.8, for cloth that rests on something to sleep.** Without it the ratio
+ * ramp leaves every row that was ever violated by millimetres at the ceiling,
+ * where a resting pile's limit cycle (§53) is too large to pass the sleep test:
+ * §64's ribbon pile never slept in 2,400 steps. At 0.8 a row's penalty halves
+ * in three substeps and is back at the floor from the ceiling in eight steps at
+ * two substeps, the multiplier carries the resting load, and the pile sleeps as
+ * it did; the twirled skirt settles where it hung and the draped sheet is
+ * carried as far. The sleep is erratic at 0.7 and slow at 0.5. Both penalties
+ * decay, because decaying the normal one alone made the resting rope's sleep a
+ * coin toss. The price is in the module docblock: static friction creeps a
+ * fraction of a millimetre in seconds where it was exact. `MEASUREMENTS.md` §67.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_GAMMA: number;
 /**
  * Penalty stiffness for a **self-collision** row, as a multiple of the row's
  * own `m_eff/h²`.
@@ -174,19 +243,23 @@ export const CLOTH_CONTACT_K_MIN_RATIO: 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.
+ * **particle's own** shortest row — so the row's **diameter** is one particle
+ * spacing, at that particle.
  *
  * `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%.
+ * self-intersections and here it removes 82%. It was a multiple of the
+ * *cloth's* shortest row until a circle skirt's hem, whose rows are five times
+ * the waistband's, got the waistband's radius and passed through itself
+ * (§67, §68); `cloth_self_radius_update` applies it per particle.
  * @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
+ * closest **that particle** gets to one no row joins it to, in the bind pose —
+ * `ClothState#self_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.
  *
@@ -245,9 +318,9 @@ export const CLOTH_SELF_RADIUS_MAX_RATIO: number;
  */
 export const CLOTH_COLLIDER_SLOTS: number;
 /**
- * The five constants as one frozen object, which is what {@link cloth_step}
+ * The 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}>}
+ * @type {Readonly<{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, contact_ramp_ratio: number, contact_gamma: number}>}
  */
 export const CLOTH_SOLVER_TUNING: Readonly<{
     alpha: number;
@@ -255,5 +328,7 @@ export const CLOTH_SOLVER_TUNING: Readonly<{
     gamma: number;
     k_min_ratio: number;
     k_max_ratio: number;
+    contact_ramp_ratio: number;
+    contact_gamma: number;
 }>;
 //# sourceMappingURL=cloth_solver_constants.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,uCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,kCAFU,MAAM,CAEuB;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;;;;;GAaG;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,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC,CAAC,CAU1J"}

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

@@ -39,16 +39,24 @@
  * the whole decay in α, whose only job is the multiplier, is the truthful
  * placement.
  *
- * **γ is the one unmeasured constant in this file, and that is now a decision.**
- * The sentence above used to end "when M2's contacts make the band real again, γ
- * becomes live and has to be re-measured". M2 made the band real — a contact's
- * floor is {@link CLOTH_CONTACT_K_MIN_RATIO} and its ceiling is
- * {@link CLOTH_K_MAX_RATIO} — and the sweep was never run. Nothing measured
- * since has asked for a decaying penalty; what a `γ < 1` *would* reach is the
- * one thing PLAN §18 records as a coupling rather than a bug, which is that a
- * contact's penalty ramps to the ceiling and never comes back down. Sweeping it
- * means re-measuring every hard row in the system against `α·γ`, because the two
- * act only through their product and `α` is the one that was measured.
+ * **γ stays 1 for the persistent rows, and a contact now has a penalty decay
+ * of its own.** The paragraph that stood here called γ the one unmeasured
+ * constant, and named what a `γ < 1` would reach: PLAN §18's coupling, that a
+ * contact's penalty ramps to the ceiling and never comes back down. The ratio
+ * ramp made that live. A row violated by millimetres while a pile lands is at
+ * the ceiling for good, and at the ceiling §53's limit cycle is too large for
+ * silk to sleep: a ribbon pile never came to rest, a twirled skirt settled 17 mm
+ * from where it hung, a draped sheet was carried 4° less. So
+ * {@link CLOTH_CONTACT_GAMMA} decays a contact's two penalties per substep, the
+ * multiplier's `α·γ` untouched; a quiet row sinks back to the floor in a few
+ * steps and a violated one re-climbs within an iteration. Measured at 0.8, and
+ * the friction penalty has to decay with the normal one: decaying the normal
+ * penalty alone left the resting rope's sleep erratic (never at 0.8 and 0.75
+ * with friction, never at 0.7 without), decaying both sleeps every scene from
+ * 0.5 to 0.95. What it costs is static friction's exactness: a sheet on a slope
+ * it should stick to creeps 0.2–0.3 mm in four seconds, and the marginal case,
+ * μ a tenth over the tangent, slides 0.55 m where the shipped ramp slid 0.19.
+ * `MEASUREMENTS.md` §67.
  *
  * **`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
@@ -71,14 +79,23 @@
  * 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.
+ * **The contact's normal ramp is a ratio now, and `β` no longer runs it.** The
+ * paragraph that stood here said the scale-dependence of a ramp in N/m² was
+ * "stated rather than removed", because a ratio-valued ramp "would have to
+ * choose the reference length that shape is built out of". The cloth-skirt
+ * example chose it: a thigh advancing 17 mm a substep into a hanging skirt
+ * sat at the penalty floor for the whole of its arrival, because 1e3 N/m²
+ * against that cloth's band of 72 to 2,300 N/m is **0.003 of the band per
+ * contact offset of violation**, and the row's multiplier — rebuilt from a
+ * quarter every substep — could not carry a limb's push in four iterations.
+ * Twelve per cent of the dance had a thigh showing through, up to 13 mm, and
+ * four times the iteration budget made it zero. The reference length is the
+ * contact offset itself: {@link CLOTH_CONTACT_RAMP_RATIO} is how much of the
+ * band a contact gains per offset of violation per iteration, and the shape
+ * the M2 measurement picked — gentle grazing, immediate interpenetration — is
+ * kept, in the units the contact is defined in. `β` still ramps the friction
+ * row, which is unmeasured, and the persistent rows, where `k_min = k_max`
+ * makes it inert. `MEASUREMENTS.md` §67.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -141,6 +158,60 @@ export const CLOTH_K_MAX_RATIO = 8;
  */
 export const CLOTH_CONTACT_K_MIN_RATIO = 0.25;
 
+/**
+ * How fast a **contact** row's normal penalty climbs, as the fraction of the
+ * band `[floor, k_max]` it gains per contact offset of violation per iteration:
+ *
+ *     k ← min(k + ratio · k_max · |C| / (thickness + inflation), k_max)
+ *
+ * **A tenth, measured on both sides.** On the cloth-skirt example the thigh
+ * penetration is on a plateau from 0.05 up (12.7% of steps → 0.1%, the
+ * deepest shortfall of the offset 18.6 → 7.7 mm); below it a sweeping limb
+ * still gets through (0.03: 0.5%). On the other side a rope **resting** on a
+ * floor with friction — §53's limit cycle — sleeps at 0.2 and never at 0.25,
+ * because every speculative row round the resting particles is at the
+ * ceiling before it is touched. A tenth is a factor of two clear of each.
+ * It is also at least as good as the ramp it replaces on the scene that
+ * chose that ramp: M2's sheet landing at 3 m/s reads 0.68 mm of penetration
+ * against 1.10, with its settled kinetic energy eight times lower and the
+ * peak contact force 9% higher, and M2 §6's capsule swept through a hanging
+ * sheet at 2 m/s reads 1.8 mm against 17. The tunnelling threshold does not
+ * move — that bound is the substep count. `MEASUREMENTS.md` §67.
+ *
+ * **It ramps whether or not the row is active**, as before. Ramping only
+ * active rows — the reference implementation's form — leaves a sweeping limb
+ * through more often (1.0% of the skirt's steps against 0.1%) and takes the
+ * speed a thrown particle is still stopped at from 6 to 4 m/s at two
+ * substeps, which is §54's one-sided-ramp finding again: the pre-stiffening
+ * of speculative rows is what a fast arrival hits.
+ *
+ * A contact offset of zero is not a contact `ClothDynamics` allows, and a
+ * division by it climbs straight to `k_max` rather than anywhere worse.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_RAMP_RATIO = 0.1;
+
+/**
+ * How much of a **contact** row's penalties — the normal row's and the friction
+ * row's — survives a substep's warm start. The multiplier decays by `α·γ` as
+ * every hard row's does; this is the band's own decay, which the persistent
+ * rows do not have because their band is a single point.
+ *
+ * **0.8, for cloth that rests on something to sleep.** Without it the ratio
+ * ramp leaves every row that was ever violated by millimetres at the ceiling,
+ * where a resting pile's limit cycle (§53) is too large to pass the sleep test:
+ * §64's ribbon pile never slept in 2,400 steps. At 0.8 a row's penalty halves
+ * in three substeps and is back at the floor from the ceiling in eight steps at
+ * two substeps, the multiplier carries the resting load, and the pile sleeps as
+ * it did; the twirled skirt settles where it hung and the draped sheet is
+ * carried as far. The sleep is erratic at 0.7 and slow at 0.5. Both penalties
+ * decay, because decaying the normal one alone made the resting rope's sleep a
+ * coin toss. The price is in the module docblock: static friction creeps a
+ * fraction of a millimetre in seconds where it was exact. `MEASUREMENTS.md` §67.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_GAMMA = 0.8;
+
 /**
  * Penalty stiffness for a **self-collision** row, as a multiple of the row's
  * own `m_eff/h²`.
@@ -182,20 +253,24 @@ export const CLOTH_SELF_RATIO = 2;
 
 /**
  * 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.
+ * **particle's own** shortest row — so the row's **diameter** is one particle
+ * spacing, at that particle.
  *
  * `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%.
+ * self-intersections and here it removes 82%. It was a multiple of the
+ * *cloth's* shortest row until a circle skirt's hem, whose rows are five times
+ * the waistband's, got the waistband's radius and passed through itself
+ * (§67, §68); `cloth_self_radius_update` applies it per particle.
  * @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
+ * closest **that particle** gets to one no row joins it to, in the bind pose —
+ * `ClothState#self_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.
  *
@@ -256,14 +331,16 @@ export const CLOTH_SELF_RADIUS_MAX_RATIO = 0.4;
 export const CLOTH_COLLIDER_SLOTS = 64;
 
 /**
- * The five constants as one frozen object, which is what {@link cloth_step}
+ * The 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}>}
+ * @type {Readonly<{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, contact_ramp_ratio: number, contact_gamma: 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
+    k_max_ratio: CLOTH_K_MAX_RATIO,
+    contact_ramp_ratio: CLOTH_CONTACT_RAMP_RATIO,
+    contact_gamma: CLOTH_CONTACT_GAMMA
 });

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

@@ -9,11 +9,13 @@
  *     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)
+ *                  (a contact's penalties: k ← clamp(k·γ_c, k_min, k_max))
  *     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))
+ *                                  (a contact: k ← min(k + ρ·k_max·|C|/offset, k_max))
  *     integrate    v  = (x − x_prev)/h
  *
  * Six row kinds — stretch, bend, leash, backstop, contact and self-collision —
@@ -141,7 +143,7 @@
  * @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]
+ * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, self_ratio?: number, contact_ramp_ratio?: number, contact_gamma?: number}} [tuning]
  * @param {Float32Array|null} [external] per-particle external acceleration,
  *   cloth-local, 3 each — §10's wind, already carrying gravity. `null` takes the
  *   uniform path above, which is what a scene with no air in it runs.
@@ -153,5 +155,7 @@ export function cloth_step(state: ClothState, dt: number, acceleration_x: number
     k_min_ratio: number;
     k_max_ratio: number;
     self_ratio?: number;
+    contact_ramp_ratio?: number;
+    contact_gamma?: number;
 }, external?: Float32Array | null): 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":"AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;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,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAC,aAChK,YAAY,GAAC,IAAI,QAwI3B"}

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

@@ -5,7 +5,9 @@ import { cloth_collider_pose_at } from "../collider/cloth_collider_sdf.js";
 import { CLOTH_HOLD_LINE_WORDS, cloth_hold_line_fit, cloth_hold_line_turn } from "./cloth_hold_line.js";
 import { cloth_solve_vertex } from "./cloth_solve_vertex.js";
 import {
+    CLOTH_CONTACT_GAMMA,
     CLOTH_CONTACT_K_MIN_RATIO,
+    CLOTH_CONTACT_RAMP_RATIO,
     CLOTH_SELF_RATIO,
     CLOTH_SOLVER_TUNING
 } from "./cloth_solver_constants.js";
@@ -43,11 +45,13 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  *     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)
+ *                  (a contact's penalties: k ← clamp(k·γ_c, k_min, k_max))
  *     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))
+ *                                  (a contact: k ← min(k + ρ·k_max·|C|/offset, k_max))
  *     integrate    v  = (x − x_prev)/h
  *
  * Six row kinds — stretch, bend, leash, backstop, contact and self-collision —
@@ -176,7 +180,7 @@ import { find_non_finite_cloth_state } from "./find_non_finite_cloth_state.js";
  * @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]
+ * @param {{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number, self_ratio?: number, contact_ramp_ratio?: number, contact_gamma?: number}} [tuning]
  * @param {Float32Array|null} [external] per-particle external acceleration,
  *   cloth-local, 3 each — §10's wind, already carrying gravity. `null` takes the
  *   uniform path above, which is what a scene with no air in it runs.
@@ -201,6 +205,11 @@ export function cloth_step(
     const k_min_ratio = tuning.k_min_ratio;
     const k_max_ratio = tuning.k_max_ratio;
 
+    // A sweep's tuning from before the contact had a ramp ratio and a decay of its own names neither,
+    // and gets the shipped ones.
+    const contact_ramp_ratio = tuning.contact_ramp_ratio ?? CLOTH_CONTACT_RAMP_RATIO;
+    const contact_gamma = tuning.contact_gamma ?? CLOTH_CONTACT_GAMMA;
+
     const h = dt / substeps;
     const inverse_h = 1 / h;
     const inverse_h_squared = inverse_h * inverse_h;
@@ -265,7 +274,8 @@ export function cloth_step(
         if (contacts !== null) {
             cloth_contact_warm_start(
                 state, alpha, gamma,
-                CLOTH_CONTACT_K_MIN_RATIO, k_max_ratio, inverse_h_squared
+                CLOTH_CONTACT_K_MIN_RATIO, k_max_ratio, inverse_h_squared,
+                contact_gamma
             );
         }
 
@@ -292,7 +302,7 @@ export function cloth_step(
             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_contact_dual_update(state, contacts, beta, k_max_ratio, inverse_h_squared, contact_ramp_ratio);
             }
         }
 

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

@@ -27,7 +27,6 @@ export namespace ClothStepParam {
     let RETENTION: number;
     let VELOCITY_LIMIT: number;
     let CONTACT_RADIUS: number;
-    let SELF_RADIUS: number;
     let COLLIDER_COUNT: number;
     let SELF_COLLISION: number;
     let DRAG_RESPONSE: number;

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AA6IA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA6DhB;;;;6BAtJS,MAAM;;;;;;;;;;;;;;;;;;AA2EhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}
+{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AAyIA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA+DhB;;;;6BAnJS,MAAM;;;;;;;;;;;;;;;;;AAsEhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}

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

@@ -1,6 +1,7 @@
 import { vector_scale_offset } from "../../../../core/geom/vec/vector_scale_offset.js";
 import { cloth_contact_find } from "./cloth_contact_find.js";
 import { cloth_self_find } from "./cloth_self_find.js";
+import { cloth_self_radius_update } from "./cloth_self_radius.js";
 import { cloth_step } from "./cloth_step.js";
 import { cloth_wind_accelerate } from "./cloth_wind_accelerate.js";
 import { ClothStepResult } from "./ClothState.js";
@@ -96,24 +97,19 @@ export const ClothStepParam = {
      */
     VELOCITY_LIMIT: 8,
     /**
-     * `ClothDynamics#thickness`, metres.
+     * `ClothDynamics#thickness`, metres — the contact offset, and what each
+     * particle's self-collision radius is built from per step
+     * (`cloth_self_radius_update`).
      */
     CONTACT_RADIUS: 9,
-    /**
-     * The self-collision row's radius, metres. Read only when
-     * {@link ClothStepParam.SELF_COLLISION} is set — a cloth with the flag
-     * clear keeps whatever radius it last had, because the row that would read
-     * it does not run.
-     */
-    SELF_RADIUS: 10,
     /**
      * Live records in the state's collider table, as the gather left it.
      */
-    COLLIDER_COUNT: 11,
+    COLLIDER_COUNT: 10,
     /**
      * Non-zero when `ClothDynamicsFlags.SelfCollision` is set.
      */
-    SELF_COLLISION: 12,
+    SELF_COLLISION: 11,
     /**
      * §10's aerodynamic coupling, as the **per-step response**
      * `(1 − e^(−rate·dt))/dt` in 1/s rather than as a rate — see
@@ -124,20 +120,20 @@ export const ClothStepParam = {
      * takes `cloth_step`'s uniform-gravity path, which is the path M0 through
      * M5 measured.
      */
-    DRAG_RESPONSE: 13,
+    DRAG_RESPONSE: 12,
     /**
      * The furthest any held particle is carried this step, metres — how far a
      * cloth its holders are dragging moves without a velocity to show for it.
      * Contact discovery reaches this much further for every free particle.
      */
-    KINEMATIC_TRAVEL: 14
+    KINEMATIC_TRAVEL: 13
 };
 
 /**
  * `Float64` words one cloth's parameter block occupies.
  * @type {number}
  */
-export const CLOTH_STEP_PARAM_STRIDE = 15;
+export const CLOTH_STEP_PARAM_STRIDE = 14;
 
 /**
  * Step one cloth.
@@ -173,7 +169,9 @@ export function cloth_step_instance(state, self_exclusions, params, offset) {
     let self_pairs = 0;
 
     if (params[offset + ClothStepParam.SELF_COLLISION] !== 0) {
-        state.self_radius = params[offset + ClothStepParam.SELF_RADIUS];
+        // Each particle's radius from its own two lengths and this step's thickness,
+        // here so both threads derive it from the same words.
+        cloth_self_radius_update(state, params[offset + ClothStepParam.CONTACT_RADIUS]);
 
         self_pairs = cloth_self_find(state, self_exclusions);
     } else {

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

@@ -20,12 +20,14 @@ export function cloth_contact_accumulate(accumulator: Float64Array, state: Cloth
  *
  * @param {ClothState} state
  * @param {number} alpha
- * @param {number} gamma
+ * @param {number} gamma the multiplier's decay, with `alpha`
  * @param {number} k_min_ratio
  * @param {number} k_max_ratio
  * @param {number} inverse_h_squared
+ * @param {number} [penalty_gamma] the contact's own decay of both penalties per
+ *   substep — {@link CLOTH_CONTACT_GAMMA}, and why a contact has one
  */
-export function cloth_contact_warm_start(state: ClothState, alpha: number, gamma: number, k_min_ratio: number, k_max_ratio: number, inverse_h_squared: number): void;
+export function cloth_contact_warm_start(state: ClothState, alpha: number, gamma: number, k_min_ratio: number, k_max_ratio: number, inverse_h_squared: number, penalty_gamma?: number): void;
 /**
  * Dual update for every occupied contact slot.
  *
@@ -38,11 +40,13 @@ export function cloth_contact_warm_start(state: ClothState, alpha: number, gamma
  *
  * @param {ClothState} state
  * @param {Float32Array|Float64Array} table
- * @param {number} beta
+ * @param {number} beta the friction row's ramp, N/m²
  * @param {number} k_max_ratio
  * @param {number} inverse_h_squared
+ * @param {number} [ramp_ratio] the normal row's ramp, as the fraction of the
+ *   band gained per contact offset of violation per iteration
  */
-export function cloth_contact_dual_update(state: ClothState, table: Float32Array | Float64Array, beta: number, k_max_ratio: number, inverse_h_squared: number): void;
+export function cloth_contact_dual_update(state: ClothState, table: Float32Array | Float64Array, beta: number, k_max_ratio: number, inverse_h_squared: number, ramp_ratio?: number): void;
 /**
  * # Contact — the collision row and its friction row, which are one contact
  *
@@ -100,6 +104,21 @@ export function cloth_contact_dual_update(state: ClothState, table: Float32Array
  * never act at all. The current force is already computed, already
  * non-negative, and makes a cloth land on a slope and stay there at 1×1.
  *
+ * ## The normal penalty ramps in the contact's own units
+ *
+ * `k ← min(k + ratio·k_max·|C|/offset, k_max)`, `offset = thickness + inflation`:
+ * the penalty gains {@link CLOTH_CONTACT_RAMP_RATIO} of its band per contact
+ * offset of violation per iteration, rather than `β·|C|` newtons per metre.
+ * A contact against a **sweeping** collider — a thigh into a skirt — has to
+ * produce an arresting force within the iteration budget, and a ramp in N/m²
+ * that was gentle on a landing sheet was, on a 20 g particle at two substeps,
+ * 0.003 of the band per offset: the row sat at the floor while its multiplier
+ * was rebuilt from a quarter every substep, and the limb showed through. The
+ * ratio keeps the measured shape — a grazing contact ramps gently, a real
+ * interpenetration is at the ceiling within an iteration — and it keeps it
+ * for every mass, substep count and thickness. `β` still ramps friction.
+ * `MEASUREMENTS.md` §67.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_contact_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_contact_row.js"],"names":[],"mappings":"AAwHA;;;;;;;;GAQG;AACH,sDANW,YAAY,+BAEZ,MAAM,SACN,YAAY,GAAC,YAAY,QA+LnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,mEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QA8ChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,oEALW,YAAY,GAAC,YAAY,QACzB,MAAM,eACN,MAAM,qBACN,MAAM,QAqGhB;AAxdD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,qCAFU,MAAM,CAE2B"}
+{"version":3,"file":"cloth_contact_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_contact_row.js"],"names":[],"mappings":"AAwIA;;;;;;;;GAQG;AACH,sDANW,YAAY,+BAEZ,MAAM,SACN,YAAY,GAAC,YAAY,QA+LnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,mEARW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,kBACN,MAAM,QAkDhB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,oEAPW,YAAY,GAAC,YAAY,QACzB,MAAM,eACN,MAAM,qBACN,MAAM,eACN,MAAM,QA2GhB;AAnfD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,qCAFU,MAAM,CAE2B"}