@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/solver/constraint/cloth_contact_row.js

@@ -0,0 +1,501 @@
+import {
+    CCR_FEATURE,
+    CCR_FRICTION,
+    CCR_INFLATION,
+    CCR_STRIDE
+} from "../../collider/ClothColliderRecord.js";
+import {
+    cloth_collider_from_local,
+    cloth_collider_signed_distance,
+    cloth_collider_to_local
+} from "../../collider/cloth_collider_sdf.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_TRUST
+} from "../cloth_vertex_accumulator.js";
+
+/**
+ * # Contact — the collision row and its friction row, which are one contact
+ *
+ * §6's table has them as two rows and they are, but they are two rows of the
+ * *same thing*: friction's clamp is the collision row's own force, so a module
+ * that carried only one of them would have to reach into the other, and a
+ * contact that carried its normal multiplier in one table and its tangential
+ * one in another would have to keep two lifetimes in step. One module, one pair
+ * of slots, one lifetime.
+ *
+ *     collision   C = (r + inflation) − sdf_c(x)        [0, +∞)     hard
+ *                 g = −∇sdf_c(x)
+ *
+ *     friction    C = ‖P_t(x − a)‖                      [0, μ·f_n)  hard
+ *                 g = P_t(x − a)/‖P_t(x − a)‖
+ *
+ * where `a` is where the particle stuck to the collider, carried in the
+ * collider's own frame, and `P_t = I − n nᵀ` projects onto the contact's
+ * tangent plane.
+ *
+ * ## The collision row is hard, which §6's table does not say
+ *
+ * §6 gives it a stiffness `k_contact` and friction a `k_friction`, and M0's own
+ * rule — "a row is **hard** exactly when its stiffness is `Infinity`" — makes
+ * that a statement that both are soft penalties. They cannot be. A soft row
+ * above about `8·(m/h²)` makes the step *add* energy (`MEASUREMENTS.md` §6),
+ * and a contact soft enough to stay under that boundary is a contact cloth
+ * sinks through: measured at 2.3 cm of penetration into a 25 cm sphere for a
+ * cape that is 4 mm thick. Both rows are therefore hard, with the multiplier
+ * carrying the load and the penalty living in the measured band — and that is
+ * also what finally gives `β` something to do, because these are the first rows
+ * in the system that arrive and leave. `MEASUREMENTS.md` §17.
+ *
+ * ## The friction clamp is one-sided because `C` is a magnitude
+ *
+ * §6 writes friction's clamps as `±μ·f_n`, which is the *signed-slip*
+ * formulation — a row whose `C` is a displacement along a chosen tangent. This
+ * one measures the magnitude of the slip in the tangent plane and points its
+ * gradient along it, so `C ≥ 0` always and the negative half of that clamp
+ * names a force that pulls the particle further from where it stuck. The row is
+ * `[0, μ·f_n]`, which is the same physics: static friction while the force it
+ * needs is under the cap, sliding at exactly the cap once it is not.
+ *
+ * Writing it as a magnitude is what removes the tangent basis. A signed row
+ * needs two of them, chosen per contact, and any choice that is continuous
+ * frame to frame is a choice with state in it — which is exactly what §7 P4(a)
+ * exists to keep out of this system.
+ *
+ * ## Which force the friction cap reads
+ *
+ * The *current iteration's* normal force, not the previous iteration's
+ * multiplier. VBD uses the multiplier, which is one iteration stale and
+ * therefore exactly zero on a contact's first iteration — so at the one
+ * iteration per substep §5.1 says the solver must be usable at, friction would
+ * 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.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Contact rows per particle.
+ *
+ * Four, because a particle in a garment's worst corner — an armpit, between two
+ * fingers — is inside three or four collider bounds at once and inside more
+ * than that only when a rig has redundant colliders, where the fifth is a
+ * duplicate of one of the first four. Slots are filled nearest-first, so the
+ * ones dropped are the ones furthest from binding.
+ *
+ * It is a compile-time constant rather than a field because it is a stride: the
+ * accumulation is a counted loop over `CLOTH_CONTACT_SLOTS` adjacent entries,
+ * and a per-cloth capacity would put a load and a multiply in the inner loop to
+ * buy a garment nothing.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_SLOTS = 4;
+
+/**
+ * Below this a tangential slip is treated as zero and the friction row is
+ * skipped: `‖·‖` is not differentiable there, and a particle that has not moved
+ * relative to the surface has nothing for friction to resist.
+ * @type {number}
+ */
+export const CLOTH_FRICTION_EPSILON = 1e-7;
+
+/**
+ * Add every contact touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ * @param {Float32Array|Float64Array} table packed colliders, cloth-local, posed
+ *   at the substep in progress
+ */
+export function cloth_contact_accumulate(accumulator, state, particle, table) {
+    const collider = state.contact_collider;
+
+    const base = particle * CLOTH_CONTACT_SLOTS;
+
+    const position = state.position;
+
+    const self = particle * 3;
+
+    const x = position[self];
+    const y = position[self + 1];
+    const z = position[self + 2];
+
+    const radius = state.contact_radius;
+
+    const lambda = state.contact_lambda;
+    const penalty = state.contact_penalty;
+    const friction_lambda = state.contact_friction_lambda;
+    const friction_penalty = state.contact_friction_penalty;
+    const anchor = state.contact_anchor;
+
+    let f_x = accumulator[CVA_F_X];
+    let f_y = accumulator[CVA_F_Y];
+    let f_z = accumulator[CVA_F_Z];
+
+    let h_xx = accumulator[CVA_H_XX];
+    let h_yy = accumulator[CVA_H_YY];
+    let h_zz = accumulator[CVA_H_ZZ];
+    let h_xy = accumulator[CVA_H_XY];
+    let h_xz = accumulator[CVA_H_XZ];
+    let h_yz = accumulator[CVA_H_YZ];
+
+    let trust = accumulator[CVA_TRUST];
+
+    for (let s = 0; s < CLOTH_CONTACT_SLOTS; s++) {
+        const slot = base + s;
+
+        const record = collider[slot];
+
+        if (record < 0) {
+            continue;
+        }
+
+        const r = record * CCR_STRIDE;
+
+        const distance = cloth_collider_signed_distance(NORMAL, 0, table, record, x, y, z);
+
+        const offset = radius + table[r + CCR_INFLATION];
+
+        const k = penalty[slot];
+
+        const force = k * (offset - distance) + lambda[slot];
+
+        if (force <= 0) {
+            // Not touching, and carrying no accumulated force. The row is
+            // clamped out — and while it is, the friction anchor follows the
+            // particle, so that when it *does* touch it sticks where it landed
+            // rather than being dragged back to wherever it last was.
+            cloth_collider_to_local(anchor, slot * 3, table, record, x, y, z);
+
+            friction_lambda[slot] = 0;
+
+            continue;
+        }
+
+        const nx = NORMAL[0];
+        const ny = NORMAL[1];
+        const nz = NORMAL[2];
+
+        // `g = −n`, so `f -= fc·g` is `f += fc·n` — out of the collider.
+        f_x += force * nx;
+        f_y += force * ny;
+        f_z += force * nz;
+
+        // The row is active whenever it is not clamped out, and the clamp is
+        // one-sided at zero, so reaching here *is* `fc == fu` and the penalty
+        // curvature always goes in.
+        h_xx += k * nx * nx;
+        h_yy += k * ny * ny;
+        h_zz += k * nz * nz;
+        h_xy += k * nx * ny;
+        h_xz += k * nx * nz;
+        h_yz += k * ny * nz;
+
+        // Geometric stiffness, and there is none to keep. For a convex
+        // primitive `∇²sdf` is positive semidefinite outside the shape, so
+        // `fc·∂²C/∂x² = −fc·∇²sdf` is *negative* semidefinite — the half §5.3
+        // drops. A distance row's geometric term is the opposite sign because
+        // its `C` is written the opposite way round, which is the same trap §6's
+        // clamp gloss set for M1.
+
+        // The trust region, from the collider rather than from a constant: a
+        // surface normal describes a surface over the surface's own curvature
+        // radius and no further.
+        const feature = table[r + CCR_FEATURE];
+
+        if (feature < trust) {
+            trust = feature;
+        }
+
+        const friction = table[r + CCR_FRICTION];
+
+        if (friction <= 0) {
+            continue;
+        }
+
+        cloth_collider_from_local(
+            ANCHOR_WORLD, 0, table, record,
+            anchor[slot * 3], anchor[slot * 3 + 1], anchor[slot * 3 + 2]
+        );
+
+        const dx = x - ANCHOR_WORLD[0];
+        const dy = y - ANCHOR_WORLD[1];
+        const dz = z - ANCHOR_WORLD[2];
+
+        const along = dx * nx + dy * ny + dz * nz;
+
+        const tx = dx - along * nx;
+        const ty = dy - along * ny;
+        const tz = dz - along * nz;
+
+        const slip = Math.sqrt(tx * tx + ty * ty + tz * tz);
+
+        if (slip < CLOTH_FRICTION_EPSILON) {
+            continue;
+        }
+
+        const kf = friction_penalty[slot];
+
+        const unclamped = kf * slip + friction_lambda[slot];
+
+        const cap = friction * force;
+
+        const tangential = unclamped < cap ? unclamped : cap;
+
+        const inverse = 1 / slip;
+
+        const gx = tx * inverse;
+        const gy = ty * inverse;
+        const gz = tz * inverse;
+
+        f_x -= tangential * gx;
+        f_y -= tangential * gy;
+        f_z -= tangential * gz;
+
+        if (unclamped <= cap) {
+            h_xx += kf * gx * gx;
+            h_yy += kf * gy * gy;
+            h_zz += kf * gz * gz;
+            h_xy += kf * gx * gy;
+            h_xz += kf * gx * gz;
+            h_yz += kf * gy * gz;
+        }
+
+        // Geometric stiffness, `(fc/L)·(P − g gᵀ)` with `P = I − n nᵀ`. `g` lies
+        // in the tangent plane, so `P − g gᵀ` is the rank-one projector onto the
+        // other tangent direction — positive semidefinite, and kept whether or
+        // not the row is clamped, because a saturated row still swings as the
+        // slip direction rotates.
+        const scale = tangential * inverse;
+
+        h_xx += scale * (1 - nx * nx - gx * gx);
+        h_yy += scale * (1 - ny * ny - gy * gy);
+        h_zz += scale * (1 - nz * nz - gz * gz);
+        h_xy -= scale * (nx * ny + gx * gy);
+        h_xz -= scale * (nx * nz + gx * gz);
+        h_yz -= scale * (ny * nz + gy * gz);
+    }
+
+    accumulator[CVA_F_X] = f_x;
+    accumulator[CVA_F_Y] = f_y;
+    accumulator[CVA_F_Z] = f_z;
+
+    accumulator[CVA_H_XX] = h_xx;
+    accumulator[CVA_H_YY] = h_yy;
+    accumulator[CVA_H_ZZ] = h_zz;
+    accumulator[CVA_H_XY] = h_xy;
+    accumulator[CVA_H_XZ] = h_xz;
+    accumulator[CVA_H_YZ] = h_yz;
+
+    accumulator[CVA_TRUST] = trust;
+}
+
+/**
+ * Warm start every occupied contact slot for a substep.
+ *
+ * A contact is where `β` finally means something. M0 chose `k_min = k_max`,
+ * which disables the ramp, and measured that it was as good as any ramped
+ * alternative — for *persistent* rows, which is all M0 and M1 had. A contact
+ * arrives: on the first substep it exists, its penalty starts at `k_min` and
+ * climbs by `β·|C|` per iteration, so a cape meeting a shoulder is pushed out
+ * over a few iterations instead of being shot off it in one.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha
+ * @param {number} gamma
+ * @param {number} k_min_ratio
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+    const particle_count = state.particle_count;
+
+    const collider = state.contact_collider;
+    const mass_inverse = state.mass_inverse;
+    const lambda = state.contact_lambda;
+    const penalty = state.contact_penalty;
+    const friction_lambda = state.contact_friction_lambda;
+    const friction_penalty = state.contact_friction_penalty;
+
+    const decay = alpha * gamma;
+
+    for (let particle = 0; particle < particle_count; particle++) {
+        const compliance = mass_inverse[particle];
+
+        if (compliance === 0) {
+            continue;
+        }
+
+        const scale = inverse_h_squared / compliance;
+
+        const lo = k_min_ratio * scale;
+        const hi = k_max_ratio * scale;
+
+        const base = particle * CLOTH_CONTACT_SLOTS;
+
+        for (let s = 0; s < CLOTH_CONTACT_SLOTS; s++) {
+            const slot = base + s;
+
+            if (collider[slot] < 0) {
+                continue;
+            }
+
+            lambda[slot] *= decay;
+            friction_lambda[slot] *= decay;
+
+            penalty[slot] = clamp_band(penalty[slot] * gamma, lo, hi);
+            friction_penalty[slot] = clamp_band(friction_penalty[slot] * gamma, lo, hi);
+        }
+    }
+}
+
+/**
+ * Dual update for every occupied contact slot.
+ *
+ * The constraint is re-evaluated here rather than cached from the accumulation,
+ * for the same reason every other row kind re-evaluates: the accumulation's `C`
+ * is measured *before* the vertex update it feeds, and a multiplier absorbing a
+ * violation that has already been corrected is a multiplier that overshoots on
+ * the next iteration. It costs a second field evaluation per contact per
+ * iteration and it is what makes the multiplier converge within the step.
+ *
+ * @param {ClothState} state
+ * @param {Float32Array|Float64Array} table
+ * @param {number} beta
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inverse_h_squared) {
+    const particle_count = state.particle_count;
+
+    const collider = state.contact_collider;
+    const mass_inverse = state.mass_inverse;
+    const position = state.position;
+    const lambda = state.contact_lambda;
+    const penalty = state.contact_penalty;
+    const friction_lambda = state.contact_friction_lambda;
+    const friction_penalty = state.contact_friction_penalty;
+    const anchor = state.contact_anchor;
+
+    const radius = state.contact_radius;
+
+    for (let particle = 0; particle < particle_count; particle++) {
+        const compliance = mass_inverse[particle];
+
+        if (compliance === 0) {
+            continue;
+        }
+
+        const base = particle * CLOTH_CONTACT_SLOTS;
+
+        const self = particle * 3;
+
+        const x = position[self];
+        const y = position[self + 1];
+        const z = position[self + 2];
+
+        const k_max = k_max_ratio * inverse_h_squared / compliance;
+
+        for (let s = 0; s < CLOTH_CONTACT_SLOTS; s++) {
+            const slot = base + s;
+
+            const record = collider[slot];
+
+            if (record < 0) {
+                continue;
+            }
+
+            const r = record * CCR_STRIDE;
+
+            const distance = cloth_collider_signed_distance(NORMAL, 0, table, record, x, y, z);
+
+            const c = radius + table[r + CCR_INFLATION] - distance;
+
+            const k = penalty[slot];
+
+            const next = k * c + lambda[slot];
+
+            const normal_force = next > 0 ? next : 0;
+
+            lambda[slot] = normal_force;
+
+            const ramped = k + beta * Math.abs(c);
+
+            penalty[slot] = ramped < k_max ? ramped : k_max;
+
+            const friction = table[r + CCR_FRICTION];
+
+            if (friction <= 0 || normal_force <= 0) {
+                friction_lambda[slot] = 0;
+
+                continue;
+            }
+
+            cloth_collider_from_local(
+                ANCHOR_WORLD, 0, table, record,
+                anchor[slot * 3], anchor[slot * 3 + 1], anchor[slot * 3 + 2]
+            );
+
+            const dx = x - ANCHOR_WORLD[0];
+            const dy = y - ANCHOR_WORLD[1];
+            const dz = z - ANCHOR_WORLD[2];
+
+            const along = dx * NORMAL[0] + dy * NORMAL[1] + dz * NORMAL[2];
+
+            const tx = dx - along * NORMAL[0];
+            const ty = dy - along * NORMAL[1];
+            const tz = dz - along * NORMAL[2];
+
+            const slip = Math.sqrt(tx * tx + ty * ty + tz * tz);
+
+            const kf = friction_penalty[slot];
+
+            const cap = friction * normal_force;
+
+            const unclamped = kf * slip + friction_lambda[slot];
+
+            friction_lambda[slot] = unclamped < cap ? (unclamped > 0 ? unclamped : 0) : cap;
+
+            const ramped_friction = kf + beta * slip;
+
+            friction_penalty[slot] = ramped_friction < k_max ? ramped_friction : k_max;
+        }
+    }
+}
+
+/**
+ * @param {number} value
+ * @param {number} lo
+ * @param {number} hi
+ * @returns {number}
+ * @private
+ */
+function clamp_band(value, lo, hi) {
+    if (value < lo) {
+        return lo;
+    }
+
+    return value > hi ? hi : value;
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const NORMAL = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const ANCHOR_WORLD = new Float64Array(3);

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

@@ -0,0 +1,75 @@
+/**
+ * Rebuild the per-particle Jacobi scratch from the pair list.
+ *
+ * Called once per iteration, before the colour sweep, from the positions the
+ * previous iteration left. Every pair contributes to both of its particles.
+ *
+ * @param {ClothState} state
+ * @param {number} stiffness penalty, N/m — the same for every pair, because
+ *   every pair has the same two free ends and therefore the same inertial scale
+ * @returns {number} how many pairs were in contact
+ */
+export function cloth_self_accumulate_scratch(state: ClothState, stiffness: number): number;
+/**
+ * Add one particle's share of the Jacobi scratch into its vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_self_accumulate(accumulator: Float64Array, state: ClothState, particle: number): void;
+/**
+ * # Self-collision — the row that keeps cloth off itself
+ *
+ *     C(x) = ‖x_i − x_j‖ − (r_i + r_j)
+ *     ∂C/∂x_i = (x_i − x_j)/‖x_i − x_j‖ = n
+ *     ∂C/∂x_j = −n
+ *     clamp (−∞, 0]
+ *
+ * **That clamp is right and it is the one place in §6's table where the negative
+ * half is the live one.** The rule is that `[0, +∞)` admits only forces that
+ * *reduce* `C` and `(−∞, 0]` only forces that *increase* it; this row is violated
+ * when the two particles are closer than their radii, which is `C < 0`, so what
+ * it needs is `C` increased. Under the solver's `f -= fc·g`, a negative `fc`
+ * pushes `i` along `+n` and `j` along `−n` — apart. Every distance row above it
+ * in the table bounds a distance from *above* and therefore takes the other
+ * half; this one bounds from below.
+ *
+ * ## It is applied Jacobi-style, and this is where §5.4 was right
+ *
+ * A collider contact is unary and needs none of §5.4's machinery (`MEASUREMENTS.md`
+ * §18). A self-collision row is a **pair**, and pairs are exactly what the
+ * colouring cannot pre-partition: two particles of the same colour can be
+ * neighbours in space and would then both move against each other inside one
+ * sweep, in an order that depends on how the sweep was split. So the pairs are
+ * accumulated once per iteration into a per-particle `(f, H)` scratch, from the
+ * positions at the start of that iteration, and every vertex update adds its own
+ * entry. The result is a step that is the same whatever order the colours were
+ * swept in, which is what §12's bit-parity gate is going to be held to.
+ *
+ * ## The row is soft, which the collision row could not be
+ *
+ * `MEASUREMENTS.md` §18 measured that a collider contact cannot be a soft
+ * penalty: the force it has to produce is an *arrested impact*, 376 N for a
+ * sheet arriving at 8 m/s, against the 4.6 N a soft row inside M0's dissipative
+ * band can deliver at one thickness of penetration.
+ *
+ * A self-collision row carries nothing of the kind. What it holds apart is cloth
+ * against cloth — grams, moving at the speed cloth moves relative to itself — and
+ * a penalty at the top of the band produces newtons per millimetre against a
+ * load of fractions of a newton. So it is a plain penalty with no multiplier, no
+ * warm start and no identity across steps, which is also what makes a pair list
+ * that is rebuilt from scratch every step affordable: there is nothing on a pair
+ * worth carrying. `MEASUREMENTS.md` §33.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Below this a separation is treated as zero and the row is skipped: `‖·‖` is
+ * not differentiable there, and two particles at exactly the same place have no
+ * direction to be pushed apart along.
+ * @type {number}
+ */
+export const CLOTH_SELF_EPSILON: number;
+//# sourceMappingURL=cloth_self_row.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_self_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_self_row.js"],"names":[],"mappings":"AAoEA;;;;;;;;;;GAUG;AACH,4EAJW,MAAM,GAEJ,MAAM,CA4FlB;AAED;;;;;;GAMG;AACH,mDAJW,YAAY,+BAEZ,MAAM,QAyBhB;AA7LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;;GAKG;AACH,iCAFU,MAAM,CAEuB"}