@woosh/meep-engine 3.21.0 → 3.22.0

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

@@ -0,0 +1,271 @@
+/**
+ * # 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 = 0.25;
+
+/**
+ * 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 = 1e-3;
+
+/**
+ * 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 = 8;
+
+/**
+ * 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 = 1e-3;
+
+/**
+ * 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 = 4;
+
+/**
+ * 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 = 20;
+
+/**
+ * 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 = 0.5;
+
+/**
+ * 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 = 0.5;
+
+/**
+ * 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 = 4;
+
+/**
+ * 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 = 2;
+
+/**
+ * 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 = 20;
+
+/**
+ * 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 = 1e-3;
+
+/**
+ * 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 = 30;
+
+/**
+ * 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) {
+    const t = stretch < 0 ? 0 : (stretch > 1 ? 1 : stretch);
+
+    return CLOTH_STRAIN_MAX * Math.pow(CLOTH_STRAIN_MIN / CLOTH_STRAIN_MAX, t);
+}
+
+/**
+ * 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) {
+    if (bend <= 0) {
+        return 0;
+    }
+
+    const t = bend > 1 ? 1 : bend;
+
+    return CLOTH_BEND_RATIO_MIN * Math.pow(CLOTH_BEND_RATIO_MAX / CLOTH_BEND_RATIO_MIN, t);
+}
+
+/**
+ * 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, substeps, iterations, dt) {
+    return CLOTH_VELOCITY_CORRECTION_MARGIN * shortest_row * substeps * iterations / dt;
+}
+
+/**
+ * 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, dt) {
+    if (damping <= 0) {
+        return 1;
+    }
+
+    return Math.exp(-CLOTH_DAMPING_RATE * (damping > 1 ? 1 : damping) * dt);
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Walk the subtree and build everything {@link ClothSystem} needs to step it.
+ *
+ * @param {ClothInstance} instance seeded in place
+ * @param {EntityComponentDataset} ecd
+ * @param {TransformAttachmentSystem} attachments
+ * @param {number} dt fixed step, seconds — the bend row's scale is a ratio of
+ *   `m/dt²`, so the step length is part of the rest data
+ * @returns {void}
+ */
+export function cloth_seed_subtree(instance: ClothInstance, ecd: EntityComponentDataset, attachments: TransformAttachmentSystem, dt: number): void;
+/**
+ * Re-parameterise the rows of an already-seeded cloth from its current
+ * {@link ClothDynamics}, without walking the subtree again.
+ *
+ * This is what makes `cloth.dynamics.slack = 0.2` work live: the topology, the
+ * rest lengths and the geodesics are properties of the authored pose and do not
+ * move, and everything that does move is a number in a row table.
+ *
+ * The multipliers are **not** reset. A row whose radius has just changed is
+ * carrying a force appropriate to the radius it had, and it is one warm start
+ * away from carrying the right one; zeroing them would put a visible jolt into
+ * every parameter change instead.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} dt
+ * @returns {void}
+ */
+export function cloth_reparameterise(instance: ClothInstance, dt: number): void;
+/**
+ * Whether a dynamics change needs the subtree walked again rather than merely
+ * re-parameterised.
+ *
+ * Two fields do: turning the strain limit on or off adds or removes rows, and
+ * so does moving `slack` across the bound at which its row is provably
+ * inactive. Everything else is a number in a table that already exists.
+ *
+ * @param {ClothDynamics} before
+ * @param {ClothDynamics} after
+ * @returns {boolean}
+ */
+export function cloth_dynamics_change_needs_reseed(before: ClothDynamics, after: ClothDynamics): boolean;
+/**
+ * # Seeding a cloth from an entity subtree — §11.1
+ *
+ * One particle per entity in the transform subtree of the entity the
+ * {@link Cloth} is on, walked breadth-first through
+ * `TransformAttachmentSystem#findChildrenOf`, stopping at a nested `Cloth` or a
+ * {@link ClothExclude}. Stretch rows along the parent-child links, a bending
+ * model along each chain, and the anchor itself as the fixed set — so `d_geo`
+ * is distance along the chain from the anchor and every derived quantity in
+ * §3.4 works unchanged.
+ *
+ * ## What "bend rows along each chain" turned out to mean
+ *
+ * §11.1 asks for bend rows and the row model has one — the quadratic hinge of
+ * §6, four particles across the diamond either side of a shared edge. **A chain
+ * has no diamond.** `bt_edge_read_diamond` declines a wire edge for exactly
+ * that reason, and it is right to: the stencil is a discrete mean curvature over
+ * a surface and a rope is not one.
+ *
+ * The bending model here is instead a **skip row** — an ordinary stretch row
+ * between a node and its grandparent, at whatever distance the authored pose
+ * puts them. It is §6's own doctrine applied once more ("one row model,
+ * parameterised by mode"), it costs no new row kind, and it has the two
+ * properties §6 wanted from quadratic bending: there is no normal, no angle and
+ * no sign, so nothing degenerates at 0° or 180°, and a fold is high energy
+ * rather than a singular configuration. It also does something the quadratic
+ * stencil explicitly cannot (§18): because its rest length is read from the
+ * authored pose rather than assumed flat, **it holds a curved rest shape**.
+ *
+ * The row is soft, so its stiffness has to stay inside the dissipative band
+ * M0 measured; `cloth_dynamics_map.js` is where that is arranged and why.
+ *
+ * ## Mass is uniform, and the answer does not depend on it
+ *
+ * {@link ClothDynamics} carries no mass or density, and it does not need to.
+ * Every row scale in this system is a **ratio** of the row's own `m/h²` — the
+ * hard rows through the penalty band (`MEASUREMENTS.md` §4 held a chain at a
+ * fixed ratio across five decades of particle mass and got the same residual
+ * column every time), the soft ones through `cloth_bend_ratio` — and gravity is
+ * an acceleration. So the constant below is arbitrary in the strict sense that
+ * changing it changes no trajectory, and what matters about it is only that it
+ * is the same for every particle.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Mass of one particle, kg. Arbitrary and uniform — see the module docblock for
+ * why "arbitrary" is a statement about the solver rather than a shrug.
+ * @type {number}
+ */
+export const CLOTH_PARTICLE_MASS: number;
+/**
+ * Slack radius at `ClothDynamics#slack = 1`, as a multiple of `d_geo`.
+ *
+ * It is **2**, and that is a derivation rather than a taste. The tether row
+ * already holds every particle within `d_geo` of the anchor, and the animated
+ * position it is leashed to is itself within `d_geo` of the anchor — a chord is
+ * never longer than the arc it subtends. By the triangle inequality the two can
+ * therefore never be more than `2·d_geo` apart, so a slack radius of `2·d_geo`
+ * is **provably inactive** and `slack = 1` means exactly "no leash" with no
+ * sentinel value and no discontinuity to code around.
+ *
+ * §3.4 writes `r_i = slack · d_geo,i`, which makes `slack = 1` a real and
+ * fairly tight constraint instead: a rope hanging straight down cannot swing
+ * through 90°, because its tip would move `√2·d_geo` to get there. That is a
+ * bound nobody asked for at the setting that is supposed to ask for none.
+ * @type {number}
+ */
+export const CLOTH_SLACK_REACH: number;
+import { ClothInstance } from "./ClothInstance.js";
+//# sourceMappingURL=cloth_seed_subtree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_seed_subtree.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_subtree.js"],"names":[],"mappings":"AAyFA;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAkGhB;AAgXD;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,aAAa,MACb,MAAM,GACJ,IAAI,CAoChB;AAED;;;;;;;;;;;GAWG;AACH,iGAFa,OAAO,CAkBnB;AApnBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;GAIG;AACH,kCAFU,MAAM,CAEwB;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,gCAFU,MAAM,CAEmB;8BA1EL,oBAAoB"}