@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -0,0 +1,285 @@
+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
+} from "../cloth_vertex_accumulator.js";
+
+/**
+ * # Backstop — the half-space row
+ *
+ *     C(x) = r_b − (x_i − b_i)·n_i
+ *     ∂C/∂x_i = −n_i
+ *
+ * §6's row, verbatim: a particle is held at least `r_b` along its own normal
+ * from a point `b` just inside the body. `[0, +∞)` admits only forces that
+ * *reduce* `C`, which for this `C` means increasing `(x − b)·n` — pushing the
+ * particle out along its normal, which is what "never inside the body" means.
+ *
+ * ## What it is for, and why it is not a collider
+ *
+ * A cape's collider set approximates a torso with a handful of capsules, and
+ * between them is a gap the cloth can settle into. A backstop closes that gap
+ * without adding geometry: the plane is anchored to the particle's own
+ * *animated* position and its own surface normal, both of which the garment
+ * already knows, so it is a bound the mesh carries with it rather than a shape
+ * somebody has to author. Chaos Cloth ships the same thing under the same name
+ * and for the same reason (§15), and §7 P3 leans on it as one of the three
+ * layers that stop a garment tunnelling through a character.
+ *
+ * It is deliberately **not** a substitute for collision. A backstop is a plane
+ * per particle: it knows which way is out and nothing about what is actually
+ * there, so it cannot resolve a limb crossing the garment. The two rows answer
+ * different halves and a cape wants both.
+ *
+ * ## Where the plane comes from
+ *
+ * The caller writes it, per step, into {@link ClothState#backstop_plane} — the
+ * same contract {@link ClothState#leash_target} carries, and for the same
+ * reason: `b` and `n` are anchored to the animated pose, which moves, and are
+ * not properties of the rest shape.
+ *
+ * **M2 builds the row and does not author it.** The natural source is the
+ * garment's own skinned surface — `b` a short way inside along the vertex
+ * normal, `r_b` that distance again — and a skinned garment is M3. M2's entity
+ * path has a chain rather than a surface, so it has no normal to offer: a rope
+ * has no inside. So the row ships with storage, a spec and a playground demo
+ * driving it directly, and `cloth_proxy_build` is what will fill it.
+ *
+ * ## No trust region, and no geometric stiffness
+ *
+ * `C` is **linear** in `x`, so its second derivative is exactly zero — there is
+ * no geometric term to keep or drop — and its gradient is a constant unit
+ * vector, so there is no distance beyond which the linearisation stops
+ * describing it. A backstop is the one row in the system whose model is not a
+ * model.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Evaluate one backstop row's constraint value and its gradient.
+ *
+ * The definition the accumulation below inlines, and the one the
+ * finite-difference spec checks — there is no second copy of the arithmetic.
+ *
+ * @param {Float64Array|number[]} gradient out, `∂C/∂x`
+ * @param {number} gradient_offset
+ * @param {ClothState} state
+ * @param {number} row
+ * @returns {number} `C`
+ */
+export function cloth_backstop_evaluate(gradient, gradient_offset, state, row) {
+    const self = state.backstop_particle[row] * 3;
+
+    const plane = state.backstop_plane;
+    const position = state.position;
+
+    const p = row * 6;
+
+    const nx = plane[p + 3];
+    const ny = plane[p + 4];
+    const nz = plane[p + 5];
+
+    gradient[gradient_offset] = -nx;
+    gradient[gradient_offset + 1] = -ny;
+    gradient[gradient_offset + 2] = -nz;
+
+    const along = (position[self] - plane[p]) * nx
+        + (position[self + 1] - plane[p + 1]) * ny
+        + (position[self + 2] - plane[p + 2]) * nz;
+
+    return state.backstop_radius[row] - along;
+}
+
+/**
+ * Add every backstop row touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_backstop_accumulate(accumulator, state, particle) {
+    const offset = state.backstop_adjacency_offset;
+
+    const start = offset[particle];
+    const end = offset[particle + 1];
+
+    if (start === end) {
+        return;
+    }
+
+    const adjacency = state.backstop_adjacency;
+    const plane = state.backstop_plane;
+    const radius = state.backstop_radius;
+    const lambda = state.backstop_lambda;
+    const penalty = state.backstop_penalty;
+    const position = state.position;
+
+    const self = particle * 3;
+
+    const x = position[self];
+    const y = position[self + 1];
+    const z = position[self + 2];
+
+    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];
+
+    for (let i = start; i < end; i++) {
+        const row = adjacency[i];
+
+        const p = row * 6;
+
+        const nx = plane[p + 3];
+        const ny = plane[p + 4];
+        const nz = plane[p + 5];
+
+        const along = (x - plane[p]) * nx + (y - plane[p + 1]) * ny + (z - plane[p + 2]) * nz;
+
+        const k = penalty[row];
+
+        const force = k * (radius[row] - along) + lambda[row];
+
+        if (force <= 0) {
+            continue;
+        }
+
+        // `g = −n`, so `f -= fc·g` is `f += fc·n`.
+        f_x += force * nx;
+        f_y += force * ny;
+        f_z += force * nz;
+
+        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;
+    }
+
+    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;
+}
+
+/**
+ * Warm start every backstop row for a substep. Every one is hard, so — as with
+ * the leash table — there is no soft branch.
+ *
+ * @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_backstop_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+    const count = state.backstop_count;
+
+    const row_particle = state.backstop_particle;
+    const mass_inverse = state.mass_inverse;
+    const lambda = state.backstop_lambda;
+    const penalty = state.backstop_penalty;
+
+    const decay = alpha * gamma;
+
+    for (let row = 0; row < count; row++) {
+        const compliance = mass_inverse[row_particle[row]];
+
+        if (compliance === 0) {
+            penalty[row] = 0;
+            lambda[row] = 0;
+
+            continue;
+        }
+
+        const scale = inverse_h_squared / compliance;
+
+        const lo = k_min_ratio * scale;
+        const hi = k_max_ratio * scale;
+
+        lambda[row] *= decay;
+
+        let k = penalty[row] * gamma;
+
+        if (k < lo) {
+            k = lo;
+        } else if (k > hi) {
+            k = hi;
+        }
+
+        penalty[row] = k;
+    }
+}
+
+/**
+ * Dual update for every backstop row.
+ *
+ * @param {ClothState} state
+ * @param {number} beta
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_backstop_dual_update(state, beta, k_max_ratio, inverse_h_squared) {
+    const count = state.backstop_count;
+
+    const row_particle = state.backstop_particle;
+    const mass_inverse = state.mass_inverse;
+    const position = state.position;
+    const plane = state.backstop_plane;
+    const radius = state.backstop_radius;
+    const lambda = state.backstop_lambda;
+    const penalty = state.backstop_penalty;
+
+    for (let row = 0; row < count; row++) {
+        const particle = row_particle[row];
+
+        const compliance = mass_inverse[particle];
+
+        if (compliance === 0) {
+            continue;
+        }
+
+        const k_max = k_max_ratio * inverse_h_squared / compliance;
+
+        const self = particle * 3;
+        const p = row * 6;
+
+        const along = (position[self] - plane[p]) * plane[p + 3]
+            + (position[self + 1] - plane[p + 1]) * plane[p + 4]
+            + (position[self + 2] - plane[p + 2]) * plane[p + 5];
+
+        const c = radius[row] - along;
+
+        const k = penalty[row];
+
+        const next = k * c + lambda[row];
+
+        lambda[row] = next > 0 ? next : 0;
+
+        const ramped = k + beta * Math.abs(c);
+
+        penalty[row] = ramped < k_max ? ramped : k_max;
+    }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * 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: Float64Array, state: ClothState, particle: number, table: Float32Array | Float64Array): void;
+/**
+ * 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: ClothState, alpha: number, gamma: number, k_min_ratio: number, k_max_ratio: number, inverse_h_squared: number): void;
+/**
+ * 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: ClothState, table: Float32Array | Float64Array, beta: number, k_max_ratio: number, inverse_h_squared: number): void;
+/**
+ * # 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: number;
+/**
+ * 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: number;
+//# sourceMappingURL=cloth_contact_row.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_contact_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_contact_row.js"],"names":[],"mappings":"AA8GA;;;;;;;;GAQG;AACH,sDANW,YAAY,+BAEZ,MAAM,SACN,YAAY,GAAC,YAAY,QAwLnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,mEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QA0ChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,oEALW,YAAY,GAAC,YAAY,QACzB,MAAM,eACN,MAAM,qBACN,MAAM,QAkGhB;AAjcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH;;;;;;;;;;;;;;GAcG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,qCAFU,MAAM,CAE2B"}