@woosh/meep-engine 3.21.0 → 3.22.0

package/src/engine/physics/cloth/ecs/cloth_dynamics_library.d.ts

@@ -0,0 +1,157 @@
+/**
+ * # The library — points in the parameter space that are known to be good
+ *
+ * Seven frozen {@link ClothDynamics} instances. Assign one directly and it is
+ * shared, immutable and free; `.clone()` it and you own a copy to edit. They
+ * are a set of points rather than a mechanism: nothing here is computed, and
+ * nothing here is a preset system that has to be re-applied when a field
+ * changes.
+ *
+ * ```js
+ * rope_top.add(Cloth.from(CLOTH_ROPE));
+ *
+ * const wet = CLOTH_ROPE.clone();
+ * wet.damping = 0.4;
+ * ```
+ *
+ * ## Every entry is sized to the measured frame budget
+ *
+ * M0 measured the §17 workload — 1,024 particles at 2 substeps × 4 iterations —
+ * at 3.48 ms against a 2 ms target and priced three levers that each closed it
+ * on their own. **M1 changed that arithmetic**, because M1 added rows: a
+ * strain-limit row per link, a tether per particle, and a slack row per
+ * particle for any fabric that follows an animated pose. The same 1,024
+ * particles at 2×4 now cost **4.61 ms**, and no single lever reaches 2 ms from
+ * there — 1,024 at 2×2 is 2.38 ms and 484 at 2×4 is 2.53 ms, both still over.
+ * Every garment entry below therefore spends **two** levers, and the numbers
+ * are from `__fixtures__/cloth_library_bench.mjs`, which builds precisely the
+ * row set `cloth_seed_subtree` builds and runs precisely the budgets this file
+ * ships. `MEASUREMENTS.md` §10.
+ *
+ * The chains are two orders of magnitude cheaper and can afford the full
+ * budget and more; the garments are where the levers are spent.
+ *
+ * ## What `stretch` and `bend` mean here, and where `stretch` stops meaning it
+ *
+ * `stretch` is the strain the fabric may carry, log-mapped: `1` is a chain at a
+ * tenth of a per cent, `0` is a knit at a quarter of its length. `bend` is a
+ * ratio of the row's own inertial scale and **saturates at 1** — a soft row
+ * stiffer than the top of the dissipative band stops coming to rest at all, so
+ * leather is at the ceiling rather than above it. `cloth_dynamics_map.js`
+ * carries both derivations.
+ *
+ * `stretch` is also the weakest field in the set, and the entries say so by
+ * which of them set `ClothDynamicsFlags.StrainLimit`. Measured on a 24-link
+ * rope dropped through ninety degrees, the strain-limit row removes about a
+ * third of the peak over-stretch at every budget and **never reaches its own
+ * allowance** — at `stretch = 1` it asks for 0.1% and delivers 5.9% at 1×1,
+ * 2.2% at 2×2 and 0.9% at 2×4. It is a second hard row on an edge that already
+ * has one, so it competes for the same trust region and the same penalty band
+ * as the row it is backing up. That makes it worth its 13–15% of a garment
+ * frame where the residual is visible — a low iteration count — and not worth
+ * it where the residual is already around one per cent. The entries at 2×4
+ * clear the flag; the ones at 2×2, and the chains where it is free, keep it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Silk, chiffon, a light banner. Barely resists folding, extends almost not at
+ * all, and follows the animation loosely enough to flow.
+ *
+ * *Budget:* **400 particles at 2×4 — 1.49 ms.** Two levers: fewer particles,
+ * and no strain-limit row. A silk garment is the one that most wants substeps
+ * and iterations, so it keeps both and pays for them everywhere else; at 2×4
+ * the fabric row is inside 1.4% of strain unaided and the strain-limit row
+ * would buy half a per cent of that for 15% of the frame.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_SILK: Readonly<ClothDynamics>;
+/**
+ * Cotton, linen, a shirt. The default fabric, and the one every other entry is
+ * a deviation from.
+ *
+ * *Budget:* **400 particles at 2×4 — 1.49 ms.** Fewer particles, and no
+ * strain-limit row, for the same reason silk drops it.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_COTTON: Readonly<ClothDynamics>;
+/**
+ * Denim, canvas, a heavy coat. Stiff, quiet, and inclined to hold a fold.
+ *
+ * *Budget:* **576 particles at 2×2 — 1.28 ms.** Two levers: half the
+ * iterations, and fewer particles. A heavy garment is large, so it spends more
+ * of its allowance on particles than silk does and takes it back from the
+ * iteration count; §5.1's whole claim is that a lower iteration count converges
+ * less far towards the *same* answer rather than towards a different one, and a
+ * stiff fabric is where that is least visible. It keeps the strain-limit row,
+ * because at 2×2 the residual is 3.5% and the row takes a third of it.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_DENIM: Readonly<ClothDynamics>;
+/**
+ * Leather, oilcloth, armour skirting. The stiffest fabric this solver can hold
+ * and still come to rest — `bend` is at the ceiling of the dissipative band,
+ * not merely high.
+ *
+ * *Budget:* **576 particles at 2×2 — 1.28 ms**, as denim, and for the same
+ * reasons.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_LEATHER: Readonly<ClothDynamics>;
+/**
+ * Rope, cable, a mooring line. No meaningful animated pose to follow — a rope
+ * hangs where physics puts it — so `slack` is at 1, which by the derivation in
+ * `cloth_seed_subtree.js` means the leash row is provably inactive and is not
+ * built at all. The tether carries the inextensibility on its own.
+ *
+ * *Budget:* **40 links at the full 2×4 — 0.04 ms.** No lever at all: a chain
+ * wants more of both than a sheet does and can simply afford it, because the
+ * cost is close to linear in particles and a rope has two orders fewer. The
+ * strain-limit row is free at this size and `stretch` is a rope's most
+ * characteristic property, so it stays.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_ROPE: Readonly<ClothDynamics>;
+/**
+ * Chain, beads, a pull cord — links that barely extend and barely bend, but do
+ * not flow the way a rope does.
+ *
+ * *Budget:* **40 links at 2×6 — 0.06 ms.** Depth is how far a constraint force
+ * travels in one sweep, and a chain is the deepest thing this system simulates,
+ * so this is the one entry that spends *more* than the nominal budget rather
+ * than less. It can: at forty particles the whole step is a rounding error
+ * against the frame.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_CHAIN: Readonly<ClothDynamics>;
+/**
+ * Hair, a ponytail, a horse's tail. Many shallow strands rather than one deep
+ * one, which is why it is the only entry that asks for self-collision: strands
+ * that pass through each other read as wrong in a way a single chain never
+ * does.
+ *
+ * *Budget:* **400 particles across all strands at 2×4 — 1.49 ms**, the same
+ * two levers silk takes. `ClothDynamicsFlags.SelfCollision` is a claim about
+ * the fabric that M4 will have to re-price when it can honour it, and it is
+ * the reason this entry has the least headroom in the library.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_HAIR: Readonly<ClothDynamics>;
+/**
+ * Every entry, in one frozen array — for a tool that wants to show them all,
+ * and for the spec that holds the whole library to the value semantics and the
+ * budget.
+ * @type {ReadonlyArray<Readonly<ClothDynamics>>}
+ */
+export const CLOTH_DYNAMICS_LIBRARY: ReadonlyArray<Readonly<ClothDynamics>>;
+/**
+ * The library entries by name, for a tool, a serialiser or a playground that
+ * has a string and wants the entry.
+ * @type {Readonly<Object<string, Readonly<ClothDynamics>>>}
+ */
+export const CLOTH_DYNAMICS_BY_NAME: Readonly<{
+    [x: string]: Readonly<ClothDynamics>;
+}>;
+import { ClothDynamics } from "./ClothDynamics.js";
+//# sourceMappingURL=cloth_dynamics_library.d.ts.map

package/src/engine/physics/cloth/ecs/cloth_dynamics_library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_dynamics_library.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_dynamics_library.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;;;;;;;GAUG;AACH,yBAFU,SAAS,aAAa,CAAC,CAa7B;AAEJ;;;;;;;GAOG;AACH,2BAFU,SAAS,aAAa,CAAC,CAa7B;AAEJ;;;;;;;;;;;GAWG;AACH,0BAFU,SAAS,aAAa,CAAC,CAY7B;AAEJ;;;;;;;;GAQG;AACH,4BAFU,SAAS,aAAa,CAAC,CAY7B;AAEJ;;;;;;;;;;;;GAYG;AACH,yBAFU,SAAS,aAAa,CAAC,CAY7B;AAEJ;;;;;;;;;;GAUG;AACH,0BAFU,SAAS,aAAa,CAAC,CAY7B;AAEJ;;;;;;;;;;;GAWG;AACH,yBAFU,SAAS,aAAa,CAAC,CAa7B;AAEJ;;;;;GAKG;AACH,qCAFU,cAAc,SAAS,aAAa,CAAC,CAAC,CAU7C;AAEH;;;;GAIG;AACH,qCAFU;QAAgB,MAAM,GAAE,SAAS,aAAa,CAAC;EAAE,CAUxD;8BA7P2B,oBAAoB"}

package/src/engine/physics/cloth/ecs/cloth_dynamics_library.js

@@ -0,0 +1,254 @@
+import { ClothDynamics } from "./ClothDynamics.js";
+import { ClothDynamicsFlags } from "./ClothDynamicsFlags.js";
+
+/**
+ * # The library — points in the parameter space that are known to be good
+ *
+ * Seven frozen {@link ClothDynamics} instances. Assign one directly and it is
+ * shared, immutable and free; `.clone()` it and you own a copy to edit. They
+ * are a set of points rather than a mechanism: nothing here is computed, and
+ * nothing here is a preset system that has to be re-applied when a field
+ * changes.
+ *
+ * ```js
+ * rope_top.add(Cloth.from(CLOTH_ROPE));
+ *
+ * const wet = CLOTH_ROPE.clone();
+ * wet.damping = 0.4;
+ * ```
+ *
+ * ## Every entry is sized to the measured frame budget
+ *
+ * M0 measured the §17 workload — 1,024 particles at 2 substeps × 4 iterations —
+ * at 3.48 ms against a 2 ms target and priced three levers that each closed it
+ * on their own. **M1 changed that arithmetic**, because M1 added rows: a
+ * strain-limit row per link, a tether per particle, and a slack row per
+ * particle for any fabric that follows an animated pose. The same 1,024
+ * particles at 2×4 now cost **4.61 ms**, and no single lever reaches 2 ms from
+ * there — 1,024 at 2×2 is 2.38 ms and 484 at 2×4 is 2.53 ms, both still over.
+ * Every garment entry below therefore spends **two** levers, and the numbers
+ * are from `__fixtures__/cloth_library_bench.mjs`, which builds precisely the
+ * row set `cloth_seed_subtree` builds and runs precisely the budgets this file
+ * ships. `MEASUREMENTS.md` §10.
+ *
+ * The chains are two orders of magnitude cheaper and can afford the full
+ * budget and more; the garments are where the levers are spent.
+ *
+ * ## What `stretch` and `bend` mean here, and where `stretch` stops meaning it
+ *
+ * `stretch` is the strain the fabric may carry, log-mapped: `1` is a chain at a
+ * tenth of a per cent, `0` is a knit at a quarter of its length. `bend` is a
+ * ratio of the row's own inertial scale and **saturates at 1** — a soft row
+ * stiffer than the top of the dissipative band stops coming to rest at all, so
+ * leather is at the ceiling rather than above it. `cloth_dynamics_map.js`
+ * carries both derivations.
+ *
+ * `stretch` is also the weakest field in the set, and the entries say so by
+ * which of them set `ClothDynamicsFlags.StrainLimit`. Measured on a 24-link
+ * rope dropped through ninety degrees, the strain-limit row removes about a
+ * third of the peak over-stretch at every budget and **never reaches its own
+ * allowance** — at `stretch = 1` it asks for 0.1% and delivers 5.9% at 1×1,
+ * 2.2% at 2×2 and 0.9% at 2×4. It is a second hard row on an edge that already
+ * has one, so it competes for the same trust region and the same penalty band
+ * as the row it is backing up. That makes it worth its 13–15% of a garment
+ * frame where the residual is visible — a low iteration count — and not worth
+ * it where the residual is already around one per cent. The entries at 2×4
+ * clear the flag; the ones at 2×2, and the chains where it is free, keep it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Silk, chiffon, a light banner. Barely resists folding, extends almost not at
+ * all, and follows the animation loosely enough to flow.
+ *
+ * *Budget:* **400 particles at 2×4 — 1.49 ms.** Two levers: fewer particles,
+ * and no strain-limit row. A silk garment is the one that most wants substeps
+ * and iterations, so it keeps both and pays for them everywhere else; at 2×4
+ * the fabric row is inside 1.4% of strain unaided and the strain-limit row
+ * would buy half a per cent of that for 15% of the frame.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_SILK = Object.freeze(ClothDynamics.from({
+    stretch: 0.85,
+    bend: 0.04,
+    damping: 0.06,
+    slack: 0.75,
+    thickness: 0.004,
+    inertia: 1,
+    drag: 0.45,
+    substeps: 2,
+    iterations: 4,
+    flags: ClothDynamicsFlags.None
+}));
+
+/**
+ * Cotton, linen, a shirt. The default fabric, and the one every other entry is
+ * a deviation from.
+ *
+ * *Budget:* **400 particles at 2×4 — 1.49 ms.** Fewer particles, and no
+ * strain-limit row, for the same reason silk drops it.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_COTTON = Object.freeze(ClothDynamics.from({
+    stretch: 0.8,
+    bend: 0.25,
+    damping: 0.12,
+    slack: 0.6,
+    thickness: 0.008,
+    inertia: 1,
+    drag: 0.2,
+    substeps: 2,
+    iterations: 4,
+    flags: ClothDynamicsFlags.None
+}));
+
+/**
+ * Denim, canvas, a heavy coat. Stiff, quiet, and inclined to hold a fold.
+ *
+ * *Budget:* **576 particles at 2×2 — 1.28 ms.** Two levers: half the
+ * iterations, and fewer particles. A heavy garment is large, so it spends more
+ * of its allowance on particles than silk does and takes it back from the
+ * iteration count; §5.1's whole claim is that a lower iteration count converges
+ * less far towards the *same* answer rather than towards a different one, and a
+ * stiff fabric is where that is least visible. It keeps the strain-limit row,
+ * because at 2×2 the residual is 3.5% and the row takes a third of it.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_DENIM = Object.freeze(ClothDynamics.from({
+    stretch: 0.93,
+    bend: 0.62,
+    damping: 0.25,
+    slack: 0.4,
+    thickness: 0.014,
+    inertia: 1,
+    drag: 0.08,
+    substeps: 2,
+    iterations: 2
+}));
+
+/**
+ * Leather, oilcloth, armour skirting. The stiffest fabric this solver can hold
+ * and still come to rest — `bend` is at the ceiling of the dissipative band,
+ * not merely high.
+ *
+ * *Budget:* **576 particles at 2×2 — 1.28 ms**, as denim, and for the same
+ * reasons.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_LEATHER = Object.freeze(ClothDynamics.from({
+    stretch: 0.97,
+    bend: 1,
+    damping: 0.35,
+    slack: 0.3,
+    thickness: 0.02,
+    inertia: 1,
+    drag: 0.05,
+    substeps: 2,
+    iterations: 2
+}));
+
+/**
+ * Rope, cable, a mooring line. No meaningful animated pose to follow — a rope
+ * hangs where physics puts it — so `slack` is at 1, which by the derivation in
+ * `cloth_seed_subtree.js` means the leash row is provably inactive and is not
+ * built at all. The tether carries the inextensibility on its own.
+ *
+ * *Budget:* **40 links at the full 2×4 — 0.04 ms.** No lever at all: a chain
+ * wants more of both than a sheet does and can simply afford it, because the
+ * cost is close to linear in particles and a rope has two orders fewer. The
+ * strain-limit row is free at this size and `stretch` is a rope's most
+ * characteristic property, so it stays.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_ROPE = Object.freeze(ClothDynamics.from({
+    stretch: 0.98,
+    bend: 0.06,
+    damping: 0.1,
+    slack: 1,
+    thickness: 0.015,
+    inertia: 1,
+    drag: 0.12,
+    substeps: 2,
+    iterations: 4
+}));
+
+/**
+ * Chain, beads, a pull cord — links that barely extend and barely bend, but do
+ * not flow the way a rope does.
+ *
+ * *Budget:* **40 links at 2×6 — 0.06 ms.** Depth is how far a constraint force
+ * travels in one sweep, and a chain is the deepest thing this system simulates,
+ * so this is the one entry that spends *more* than the nominal budget rather
+ * than less. It can: at forty particles the whole step is a rounding error
+ * against the frame.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_CHAIN = Object.freeze(ClothDynamics.from({
+    stretch: 1,
+    bend: 0.15,
+    damping: 0.2,
+    slack: 1,
+    thickness: 0.012,
+    inertia: 1,
+    drag: 0.05,
+    substeps: 2,
+    iterations: 6
+}));
+
+/**
+ * Hair, a ponytail, a horse's tail. Many shallow strands rather than one deep
+ * one, which is why it is the only entry that asks for self-collision: strands
+ * that pass through each other read as wrong in a way a single chain never
+ * does.
+ *
+ * *Budget:* **400 particles across all strands at 2×4 — 1.49 ms**, the same
+ * two levers silk takes. `ClothDynamicsFlags.SelfCollision` is a claim about
+ * the fabric that M4 will have to re-price when it can honour it, and it is
+ * the reason this entry has the least headroom in the library.
+ * @type {Readonly<ClothDynamics>}
+ */
+export const CLOTH_HAIR = Object.freeze(ClothDynamics.from({
+    stretch: 0.95,
+    bend: 0.2,
+    damping: 0.18,
+    slack: 0.55,
+    thickness: 0.006,
+    inertia: 1,
+    drag: 0.3,
+    substeps: 2,
+    iterations: 4,
+    flags: ClothDynamicsFlags.SelfCollision
+}));
+
+/**
+ * Every entry, in one frozen array — for a tool that wants to show them all,
+ * and for the spec that holds the whole library to the value semantics and the
+ * budget.
+ * @type {ReadonlyArray<Readonly<ClothDynamics>>}
+ */
+export const CLOTH_DYNAMICS_LIBRARY = Object.freeze([
+    CLOTH_SILK,
+    CLOTH_COTTON,
+    CLOTH_DENIM,
+    CLOTH_LEATHER,
+    CLOTH_ROPE,
+    CLOTH_CHAIN,
+    CLOTH_HAIR
+]);
+
+/**
+ * The library entries by name, for a tool, a serialiser or a playground that
+ * has a string and wants the entry.
+ * @type {Readonly<Object<string, Readonly<ClothDynamics>>>}
+ */
+export const CLOTH_DYNAMICS_BY_NAME = Object.freeze({
+    SILK: CLOTH_SILK,
+    COTTON: CLOTH_COTTON,
+    DENIM: CLOTH_DENIM,
+    LEATHER: CLOTH_LEATHER,
+    ROPE: CLOTH_ROPE,
+    CHAIN: CLOTH_CHAIN,
+    HAIR: CLOTH_HAIR
+});

package/src/engine/physics/cloth/ecs/cloth_dynamics_map.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Fabric extension allowance for a normalised `stretch`, as a fraction of rest
+ * length. Log-mapped between {@link CLOTH_STRAIN_MAX} and
+ * {@link CLOTH_STRAIN_MIN}, so equal steps in `stretch` are equal ratios in
+ * strain and `0.9` is not four orders of magnitude away from `0.7`.
+ *
+ * @param {number} stretch `[0, 1]`
+ * @returns {number} strain, `L_max = L₀·(1 + ε)`
+ */
+export function cloth_strain_allowance(stretch: number): number;
+/**
+ * Bend row stiffness for a normalised `bend`, as a multiple of the row's own
+ * `m_eff/dt²`. Log-mapped, and **exactly zero at `bend = 0`** — a log map
+ * cannot reach zero, and "no bending resistance at all" is a state a chain is
+ * actually in rather than a limit it approaches.
+ *
+ * @param {number} bend `[0, 1]`
+ * @returns {number} ratio of `m_eff/dt²`
+ */
+export function cloth_bend_ratio(bend: number): number;
+/**
+ * Largest speed a particle may carry, metres per second. §7 P1, and see
+ * {@link CLOTH_VELOCITY_CORRECTION_MARGIN} for why this is built out of the
+ * mesh and the budget rather than out of `thickness`.
+ *
+ * @param {number} shortest_row metres — the shortest row in the cloth, which
+   is what the trust region caps a vertex update at
+ * @param {number} substeps
+ * @param {number} iterations
+ * @param {number} dt fixed step, seconds
+ * @returns {number}
+ */
+export function cloth_velocity_limit(shortest_row: number, substeps: number, iterations: number, dt: number): number;
+/**
+ * Fraction of a particle's velocity surviving one fixed step. §7 P5, and see
+ * {@link ClothDynamics#damping} for why this is a correctness mechanism rather
+ * than a taste control.
+ *
+ * @param {number} damping `[0, 1]`
+ * @param {number} dt fixed step, seconds
+ * @returns {number} `[0, 1]`
+ */
+export function cloth_velocity_retention(damping: number, dt: number): number;
+/**
+ * # Normalised coordinates → row parameters
+ *
+ * {@link ClothDynamics}' stiffnesses are coordinates in `[0, 1]`, and this is
+ * the whole of what they mean. It is one module rather than methods on the
+ * value object because the mapping is *measured* — every constant below has a
+ * number in `MEASUREMENTS.md` behind it — and a measured mapping deserves to be
+ * readable on its own and specced on its own.
+ *
+ * ## Why neither stiffness maps to newtons per metre
+ *
+ * M0's central finding: a **soft** row — a plain penalty — is dissipative only
+ * while its stiffness stays below about `8·(m/h²)`, and above that boundary the
+ * step *adds* energy and the cloth sustains a limit cycle forever. More
+ * iterations and more substeps shrink it; neither removes it
+ * (`MEASUREMENTS.md` §6). And that boundary is not a stiffness: it is a
+ * multiple of the row's own inertial scale, which moved across five decades of
+ * particle mass in §4's sweep without the answer changing.
+ *
+ * Two consequences, one for each stiffness:
+ *
+ * - **`stretch` cannot be a penalty at all.** Real fabric wants a stretch
+ *   stiffness far above that boundary — for a half-gram particle at 60 Hz × 2
+ *   substeps it sits near 60 N/m, a rubber band — so the stretch row is hard
+ *   (`Infinity`, augmented Lagrangian), and what `stretch` actually selects is
+ *   {@link cloth_strain_allowance}: how far the fabric may extend before the
+ *   strain-limit row of §6 stops it.
+ * - **`bend` maps to a ratio.** A bend row is soft and must stay inside the
+ *   dissipative band, so its stiffness is expressed as a multiple of
+ *   `m_eff/dt²` — the row's own inertial scale at the **fixed** step rather
+ *   than the substep. Two things fall out of that choice and both are wanted:
+ *   the fabric's look is invariant to how heavy the author made the particles
+ *   (which is what a normalised `[0, 1]` knob should mean), and the row is
+ *   inside the band at *any* substep count, since `k/(m/h²) = ratio/substeps²`
+ *   and `substeps ≥ 1`. A stiffness in newtons per metre has neither property.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Strain a fabric at `stretch = 0` may carry: a quarter of its own length, a
+ * loose knit. Chosen as the loosest thing that still reads as fabric rather
+ * than as elastic.
+ * @type {number}
+ */
+export const CLOTH_STRAIN_MAX: number;
+/**
+ * Strain a fabric at `stretch = 1` may carry: a tenth of a per cent, which is
+ * a chain. Below this the strain-limit row is asking for more precision than a
+ * `Float32` position over a garment-sized coordinate resolves.
+ * @type {number}
+ */
+export const CLOTH_STRAIN_MIN: number;
+/**
+ * Bend stiffness at `bend = 1`, as a multiple of the row's `m_eff/dt²`.
+ *
+ * It is 8 because that is the top of the dissipative band M0 measured
+ * (`MEASUREMENTS.md` §4 and §6) and a bend row is soft. The consequence, stated
+ * rather than hidden: **bending saturates**. A fabric stiffer than this cannot
+ * be expressed as a soft row that also comes to rest, and asking for one is
+ * asking for the limit cycle §7 P5 exists to prevent. If a garment ever needs
+ * more, the answer is a hard bend row with a multiplier, not a bigger number
+ * here.
+ * @type {number}
+ */
+export const CLOTH_BEND_RATIO_MAX: number;
+/**
+ * Bend stiffness just above `bend = 0`, as a multiple of `m_eff/dt²`. Four
+ * orders of magnitude below the ceiling, which is what makes the log map
+ * useful across the whole range instead of spending most of it near zero.
+ * @type {number}
+ */
+export const CLOTH_BEND_RATIO_MIN: number;
+/**
+ * How many times its own **correction authority** a particle may travel in one
+ * fixed step before the velocity clamp of §7 P1 catches it.
+ *
+ * ## Not `thickness`, and the measurement is why
+ *
+ * §7 P1 asks for a clamp "derived from `thickness` and `h`", and that turns out
+ * to be the wrong length scale for this job. `thickness` is a **contact**
+ * radius: a clamp built from it is a tunnelling bound, and a tunnelling bound
+ * sits *below* ordinary cloth speeds rather than above them. Silk is 4 mm
+ * thick, so at 60 Hz "a particle may not cross its own radius in a step" is
+ * 0.24 m/s — and M1 measured a rope behind a 9 m/s sprinter reaching 13 m/s
+ * (§7 P7). Any multiple large enough to stop the clamp being a *behaviour* for
+ * silk is large enough to make it meaningless for leather, because the two
+ * thicknesses differ by 5× and their speeds do not.
+ *
+ * ## What the scale actually is
+ *
+ * The solver has a measurable ability to pull a particle back, and it is not
+ * unlimited: the trust region caps each vertex update at the **shortest row
+ * incident on that particle** (§5.3), so one fixed step can move a particle at
+ * most `shortest_row · substeps · iterations`. M1 measured what happens past
+ * it — a 30-link chain kicked at 16 m/s at 1 substep × 1 iteration stretches to
+ * **17× its own reach** before recovering, against 1.02× when it is dropped
+ * under gravity, and 2.6× for the same kick at 2×4. The tether row is not what
+ * failed there; the tether row was never given a chance to act.
+ *
+ * So the clamp is a multiple of exactly that quantity, which makes it a bound
+ * on *the solver being asked to do more than it can*, and makes it scale with
+ * the budget the fabric bought and the mesh it is built on rather than with a
+ * contact radius it does not use until M2.
+ *
+ * Four, because one would bind: a coat on a sprinting character carries several
+ * metres a second of anchor-relative velocity, and a clamp that engages there
+ * is a behaviour rather than a backstop. Four leaves every library entry an
+ * order of magnitude of headroom over its measured peak and still bounds the
+ * absurd cases in a handful of steps.
+ * @type {number}
+ */
+export const CLOTH_VELOCITY_CORRECTION_MARGIN: number;
+/**
+ * Velocity decay rate at `damping = 1`, per second.
+ *
+ * `damping` maps to an exponential decay rather than a per-step multiplier so
+ * that the same value means the same thing at any fixed rate. At the default
+ * `damping = 0.15` the time constant is a third of a second, which is a cape
+ * that stops swinging without looking like it is under water.
+ * @type {number}
+ */
+export const CLOTH_DAMPING_RATE: number;
+/**
+ * How far a cloth's anchor may carry it in one fixed step, as a multiple of the
+ * cloth's own reach. Motion above this is felt as though it were exactly this,
+ * which is what "anchor speed limit" means in §7 P7.
+ *
+ * Expressing it as a fraction of reach rather than in metres per second is what
+ * makes it work for a 3 cm pendant and a 30 m mooring line at the same time: a
+ * cloth is whipped by motion large *compared to itself*, and the reach is the
+ * only length scale the cloth carries. Half a reach per step is 30 reaches a
+ * second at 60 Hz, which no character locomotion comes near — §7 P7's own
+ * profile peaks two orders below it — and which a lift, a lurching vehicle or a
+ * badly-keyed cut does exceed.
+ * @type {number}
+ */
+export const CLOTH_ANCHOR_TRAVEL_REACH: number;
+/**
+ * How far a cloth's anchor may rotate in one fixed step, radians. Rotation
+ * above this is felt as though it were exactly this.
+ *
+ * Unlike the travel limit this has no length scale to hang off — an angle is
+ * already dimensionless — so it is a plain number. Half a radian per step is
+ * about 1,700 degrees a second, which is a spin rather than a turn.
+ * @type {number}
+ */
+export const CLOTH_ANCHOR_ROTATION_LIMIT: number;
+/**
+ * Anchor displacement in one fixed step, as a multiple of the cloth's reach,
+ * above which the motion is a **teleport** rather than locomotion (§7 P6).
+ *
+ * Four reaches in one step is 240 reaches a second: for a 1 m rope that is
+ * 240 m/s, well past anything the world moves at and well short of the values a
+ * cut or a level load produces.
+ * @type {number}
+ */
+export const CLOTH_TELEPORT_REACH: number;
+/**
+ * Absolute floor on the teleport threshold, metres per fixed step.
+ *
+ * The reach multiple alone would make a small cloth absurdly twitchy — a 3 cm
+ * pendant would call 7 m/s a teleport, which is a brisk walk. This floor is
+ * 2 metres in a sixtieth of a second, so nothing under 120 m/s is a teleport
+ * whatever size the cloth is.
+ * @type {number}
+ */
+export const CLOTH_TELEPORT_FLOOR: number;
+/**
+ * Length of the stabilisation window after a teleport reset, in fixed steps.
+ *
+ * The velocity limit ramps linearly from zero back to its full value across it,
+ * so a re-seeded cloth cannot leave the animated pose faster than the window
+ * allows however wrong its first solve is. A third of a second at 60 Hz.
+ * @type {number}
+ */
+export const CLOTH_STABILISE_STEPS: number;
+/**
+ * Speed below which a particle counts as still, as a fraction of the cloth's
+ * reach per second. A metre-long rope sleeps once nothing on it is moving
+ * faster than a millimetre a second.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_SPEED_RATIO: number;
+/**
+ * How many consecutive still steps put a cloth to sleep (§7 P5). Half a second
+ * at 60 Hz, which is long enough that a cloth pausing at the top of a swing
+ * does not sleep through the way down.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_STEPS: number;
+//# sourceMappingURL=cloth_dynamics_map.d.ts.map

package/src/engine/physics/cloth/ecs/cloth_dynamics_map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_dynamics_map.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_dynamics_map.js"],"names":[],"mappings":"AA6MA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,uCAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;GAWG;AACH,mDAPW,MAAM,YAEN,MAAM,cACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,kDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;AA9QD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;GAWG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;GAKG;AACH,mCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,+CAFU,MAAM,CAEkC;AAElD;;;;;;;;GAQG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;GAKG;AACH,sCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB"}