@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,343 @@
+import {
+    CCR_AABB_MAX_X,
+    CCR_AABB_MAX_Y,
+    CCR_AABB_MAX_Z,
+    CCR_AABB_MIN_X,
+    CCR_AABB_MIN_Y,
+    CCR_AABB_MIN_Z,
+    CCR_INFLATION,
+    CCR_PREV_TX,
+    CCR_PREV_TY,
+    CCR_PREV_TZ,
+    CCR_STRIDE,
+    CCR_TX,
+    CCR_TY,
+    CCR_TZ
+} from "../collider/ClothColliderRecord.js";
+import {
+    cloth_collider_pose_at,
+    cloth_collider_signed_distance,
+    cloth_collider_to_local
+} from "../collider/cloth_collider_sdf.js";
+import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
+
+/**
+ * # Finding the contacts, once per step
+ *
+ * Which particles are in contact with which colliders is decided **once per
+ * fixed step**, not per substep and not per iteration, and that is a design
+ * commitment rather than an optimisation. Three things fall out of it:
+ *
+ * - **The step is deterministic.** The set is built by one pass in a fixed
+ *   order over a fixed table, so the same inputs produce the same rows in the
+ *   same order — which is what §12's bit-parity gate between the main thread
+ *   and the worker is going to be held to.
+ * - **A multiplier has something to be warm-started against.** A row that
+ *   appeared and vanished within a step would have no history to carry, and a
+ *   contact whose multiplier starts at zero every iteration is a contact that
+ *   never becomes hard.
+ * - **The cost is bounded and known.** One broadphase pass per particle per
+ *   step, against a table that has already been narrowed to the colliders
+ *   overlapping this cloth.
+ *
+ * ## Speculative contacts, and the collider's own travel
+ *
+ * A row is created while the particle is still {@link CLOTH_CONTACT_MARGIN}
+ * radii clear of the surface, and stays inactive — clamped out, costing a field
+ * evaluation and nothing else — until it is actually touching. That is what
+ * makes a contact decided once per step safe: a particle approaching at speed
+ * has a row waiting for it, rather than arriving inside a collider that nothing
+ * is watching. Without the margin the discovery pass would have to run per
+ * substep, which is the cost this structure exists to avoid.
+ *
+ * **The margin has to include how far the collider moved**, and M2 got this
+ * wrong before it got it right. Discovery evaluates the field at the end-of-step
+ * pose; a collider that crossed the cloth *within* the step is nowhere near it
+ * by then, so a fixed margin finds nothing and the swept poses of §8.2 have no
+ * rows to act through. Measured on a capsule driven through a hanging sheet: at
+ * 20 m/s the pass produced **zero contact rows**, and the sheet was untouched —
+ * not tunnelled through so much as never noticed. Adding the collider's travel
+ * to the reach costs one subtraction per record per step and makes the whole
+ * range from 2 to 40 m/s behave the same way. `MEASUREMENTS.md` §20.
+ *
+ * That is also the honest boundary of P3's "swept collision": the *set* is
+ * swept by this margin, and the *poses* are swept by `cloth_collider_pose_at`.
+ * Both are translation-first — a collider spinning fast enough that a point on
+ * its surface travels more than its own radius within one substep is still
+ * missed, and more substeps is the answer to that.
+ *
+ * ## Warm-starting across the rebuild
+ *
+ * Slots are keyed on the collider's **handle in the index**, which is stable
+ * across a rebuild in a way the record index in the per-cloth table is not — the
+ * table is whatever this step's broadphase returned, in whatever order. A slot
+ * whose key survives keeps its multipliers and its friction anchor; one that
+ * does not starts cold. A collider that leaves the index takes its contacts
+ * with it, which is correct: the surface the multiplier described is gone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * How far clear of a surface a contact row is still created, as a multiple of
+ * the contact offset (`thickness + inflation`).
+ *
+ * One, so a row exists from twice the offset inwards. At a garment's 8 mm that
+ * is 8 mm of warning, which at 60 Hz covers half a metre a second of approach
+ * before a substep can carry a particle past the discovery — and a cloth moving
+ * faster than that relative to a collider is one the velocity clamp of §7 P1 is
+ * already the bound on.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_MARGIN = 1;
+
+/**
+ * Rebuild every particle's contact slots against the packed collider table.
+ *
+ * The table is expected to be posed at the **end** of the step —
+ * {@link cloth_collider_pose_at} at `t = 1` — because that is where the
+ * colliders will be when the last substep runs, and a contact discovered
+ * against where a collider *was* is a contact behind the thing it is meant to
+ * stop. This function poses it there itself, so the caller cannot get it wrong,
+ * and leaves it there for the first substep to overwrite.
+ *
+ * @param {ClothState} state
+ * @param {Float32Array|Float64Array} table packed colliders, cloth-local
+ * @param {Int32Array} keys index handle per record in `table`
+ * @param {number} count records in `table`
+ * @returns {number} how many contact rows were created
+ */
+export function cloth_contact_find(state, table, keys, count) {
+    const particle_count = state.particle_count;
+
+    const collider = state.contact_collider;
+    const key = state.contact_key;
+    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 position = state.position;
+    const mass_inverse = state.mass_inverse;
+
+    const radius = state.contact_radius;
+
+    if (count > TRAVEL.length) {
+        TRAVEL = new Float64Array(count);
+    }
+
+    if (count === 0) {
+        // Nothing to collide against. Clearing is still necessary — last step's
+        // slots name records in a table that no longer exists.
+        collider.fill(-1);
+        key.fill(-1);
+
+        return 0;
+    }
+
+    cloth_collider_pose_at(table, count, 1);
+
+    // How far each collider moved this step. A particle within this of the
+    // end-of-step surface is one the collider could have crossed on the way,
+    // and it needs a row before the substeps replay that crossing.
+    for (let record = 0; record < count; record++) {
+        const r = record * CCR_STRIDE;
+
+        TRAVEL[record] = Math.hypot(
+            table[r + CCR_TX] - table[r + CCR_PREV_TX],
+            table[r + CCR_TY] - table[r + CCR_PREV_TY],
+            table[r + CCR_TZ] - table[r + CCR_PREV_TZ]
+        );
+    }
+
+    let created = 0;
+
+    for (let particle = 0; particle < particle_count; particle++) {
+        const base = particle * CLOTH_CONTACT_SLOTS;
+
+        // Remember what this particle had, then clear. The carry-over is a
+        // linear scan over at most four entries, which is why the slot count is
+        // small enough to make a scan the right structure.
+        for (let s = 0; s < CLOTH_CONTACT_SLOTS; s++) {
+            const slot = base + s;
+
+            PREVIOUS_KEY[s] = key[slot];
+            PREVIOUS_LAMBDA[s] = lambda[slot];
+            PREVIOUS_PENALTY[s] = penalty[slot];
+            PREVIOUS_FRICTION_LAMBDA[s] = friction_lambda[slot];
+            PREVIOUS_FRICTION_PENALTY[s] = friction_penalty[slot];
+            PREVIOUS_ANCHOR[s * 3] = anchor[slot * 3];
+            PREVIOUS_ANCHOR[s * 3 + 1] = anchor[slot * 3 + 1];
+            PREVIOUS_ANCHOR[s * 3 + 2] = anchor[slot * 3 + 2];
+
+            collider[slot] = -1;
+            key[slot] = -1;
+        }
+
+        if (mass_inverse[particle] === 0) {
+            // A pinned particle cannot be pushed anywhere, so a contact on it
+            // would be a row that assembles a force and throws it away.
+            continue;
+        }
+
+        const p = particle * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        let found = 0;
+
+        for (let record = 0; record < count; record++) {
+            const r = record * CCR_STRIDE;
+
+            const reach = (radius + table[r + CCR_INFLATION]) * (1 + CLOTH_CONTACT_MARGIN) + TRAVEL[record];
+
+            if (x + reach < table[r + CCR_AABB_MIN_X] || x - reach > table[r + CCR_AABB_MAX_X]) {
+                continue;
+            }
+
+            if (y + reach < table[r + CCR_AABB_MIN_Y] || y - reach > table[r + CCR_AABB_MAX_Y]) {
+                continue;
+            }
+
+            if (z + reach < table[r + CCR_AABB_MIN_Z] || z - reach > table[r + CCR_AABB_MAX_Z]) {
+                continue;
+            }
+
+            const distance = cloth_collider_signed_distance(NORMAL, 0, table, record, x, y, z);
+
+            if (distance > reach) {
+                continue;
+            }
+
+            // Insert, nearest first, into a list of at most CLOTH_CONTACT_SLOTS.
+            // The ones that fall off the end are the furthest from binding.
+            let at = found < CLOTH_CONTACT_SLOTS ? found : CLOTH_CONTACT_SLOTS - 1;
+
+            if (found === CLOTH_CONTACT_SLOTS && distance >= CANDIDATE_DISTANCE[at]) {
+                continue;
+            }
+
+            while (at > 0 && CANDIDATE_DISTANCE[at - 1] > distance) {
+                CANDIDATE_DISTANCE[at] = CANDIDATE_DISTANCE[at - 1];
+                CANDIDATE_RECORD[at] = CANDIDATE_RECORD[at - 1];
+
+                at--;
+            }
+
+            CANDIDATE_DISTANCE[at] = distance;
+            CANDIDATE_RECORD[at] = record;
+
+            if (found < CLOTH_CONTACT_SLOTS) {
+                found++;
+            }
+        }
+
+        for (let s = 0; s < found; s++) {
+            const slot = base + s;
+
+            const record = CANDIDATE_RECORD[s];
+            const handle = keys[record];
+
+            collider[slot] = record;
+            key[slot] = handle;
+
+            let carried = -1;
+
+            for (let q = 0; q < CLOTH_CONTACT_SLOTS; q++) {
+                if (PREVIOUS_KEY[q] === handle) {
+                    carried = q;
+
+                    break;
+                }
+            }
+
+            if (carried >= 0) {
+                lambda[slot] = PREVIOUS_LAMBDA[carried];
+                penalty[slot] = PREVIOUS_PENALTY[carried];
+                friction_lambda[slot] = PREVIOUS_FRICTION_LAMBDA[carried];
+                friction_penalty[slot] = PREVIOUS_FRICTION_PENALTY[carried];
+                anchor[slot * 3] = PREVIOUS_ANCHOR[carried * 3];
+                anchor[slot * 3 + 1] = PREVIOUS_ANCHOR[carried * 3 + 1];
+                anchor[slot * 3 + 2] = PREVIOUS_ANCHOR[carried * 3 + 2];
+            } else {
+                lambda[slot] = 0;
+                penalty[slot] = 0;
+                friction_lambda[slot] = 0;
+                friction_penalty[slot] = 0;
+
+                // A new contact sticks where the particle is now.
+                cloth_collider_to_local(anchor, slot * 3, table, record, x, y, z);
+            }
+
+            created++;
+        }
+    }
+
+    return created;
+}
+
+/**
+ * How far each collider moved this step, in the frame the table is expressed
+ * in. Grown and never shrunk; only `[0, count)` is meaningful.
+ * @type {Float64Array}
+ * @private
+ */
+let TRAVEL = new Float64Array(0);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const NORMAL = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const CANDIDATE_DISTANCE = new Float64Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Int32Array}
+ * @private
+ */
+const CANDIDATE_RECORD = new Int32Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Int32Array}
+ * @private
+ */
+const PREVIOUS_KEY = new Int32Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Float32Array}
+ * @private
+ */
+const PREVIOUS_LAMBDA = new Float32Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Float32Array}
+ * @private
+ */
+const PREVIOUS_PENALTY = new Float32Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Float32Array}
+ * @private
+ */
+const PREVIOUS_FRICTION_LAMBDA = new Float32Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Float32Array}
+ * @private
+ */
+const PREVIOUS_FRICTION_PENALTY = new Float32Array(CLOTH_CONTACT_SLOTS);
+
+/**
+ * @type {Float32Array}
+ * @private
+ */
+const PREVIOUS_ANCHOR = new Float32Array(CLOTH_CONTACT_SLOTS * 3);

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

@@ -0,0 +1,112 @@
+/**
+ * Build the exclusion lists from a state's persistent rows.
+ *
+ * @param {ClothState} state
+ * @returns {{offset: Int32Array, partner: Int32Array}} CSR, sorted within each particle
+ */
+export function cloth_self_exclusions(state: ClothState): {
+    offset: Int32Array;
+    partner: Int32Array;
+};
+/**
+ * The closest two particles get **without a row between them**, in whatever pose
+ * the state is in.
+
+ * This is the length that decides how wide a self-collision row may be written,
+ * and it has to be measured rather than assumed. On a triangulated sheet it is
+ * two hops — one hop is a stretch row, the mesh diagonal is a stretch row, and
+ * the two vertices across a diagonal are a bend stencil — so it comes out at
+ * twice the shortest row and the analytic answer and this one agree.
+ *
+ * **A rigged garment is not a sheet and the two do not agree.** Its proxy is a
+ * set of *strips*, and nothing connects one strip to the next: every pair across
+ * the gap between two strips is ungoverned, at whatever distance the artist
+ * placed the joints. That distance has nothing to do with the link length along
+ * a strip, which is what `shortest_row` measures. On the playground's cape they
+ * differ by a factor of two — 8.5 cm across the gap against the 16 cm a sheet's
+ * topology would predict — and a ceiling derived from the link length instead of
+ * measured left the settled cape with three permanently active pairs.
+ * `MEASUREMENTS.md` §37.
+ *
+ * Pinned particles are skipped, exactly as {@link cloth_self_find} skips them,
+ * so this measures the pairs the row can actually act on and nothing else.
+ *
+ * @param {ClothState} state
+ * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}
+ * @param {number} search only pairs closer than this are looked for; the walk is
+ *   bounded by it, and a proxy with nothing that close gets `Infinity` — which is
+ *   the right answer, because then no radius inside the bound can touch anything
+ * @returns {number} metres, or `Infinity`
+ */
+export function cloth_self_closest_free_pair(state: ClothState, exclusions: {
+    offset: Int32Array;
+    partner: Int32Array;
+}, search: number): number;
+/**
+ * Rebuild the pair list.
+ *
+ * @param {ClothState} state pairs written into `self_pair`, count into `self_count`
+ * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}
+ * @returns {number} how many pairs were found
+ */
+export function cloth_self_find(state: ClothState, exclusions: {
+    offset: Int32Array;
+    partner: Int32Array;
+}): number;
+/**
+ * # Finding the self-collision pairs, once per step
+ *
+ * A uniform hash grid over the particles in the cloth's own frame, then for each
+ * particle the ones near it that are not already governed by a row. Rebuilt
+ * whole every step, exactly like the contact set (`cloth_contact_find.js`) and
+ * for the same reasons: one pass in a fixed order, so the step is deterministic.
+ *
+ * ## Adjacent pairs are excluded, and "adjacent" means "shares a row"
+ *
+ * §9: "Pairs sharing a triangle or an edge are excluded, since they are already
+ * governed by stretch and bend rows and would otherwise fight them." The exact
+ * form of that here is **sharing any row at all** — a stretch row, a bend
+ * stencil, or a chain's skip row, which is a stretch row too. Two particles a
+ * stretch row already holds at 5 cm do not also need a repulsion telling them to
+ * be 8 mm apart, and a bend stencil's four particles are a fold the bend row is
+ * the model of.
+ *
+ * The exclusion set is built **once, at seed**, from the row tables the state
+ * already carries: `cloth_self_exclusions` walks them and produces a sorted CSR
+ * list per particle. Testing a candidate is then a short scan over a handful of
+ * neighbours, which at typical garment topology is 16.8 entries a particle
+ * (`MEASUREMENTS.md` §8) — small enough that a scan beats a hash.
+ *
+ * ## The cell is the row's own diameter, and that fixes the neighbourhood
+ *
+ * Two particles interact when they are closer than `2·self_radius`, so a cell of
+ * exactly that makes the 27-cell walk necessary and sufficient. A larger cell
+ * would visit more candidates for nothing; a smaller one would need a wider
+ * walk, which is the same candidates through more buckets.
+ *
+ * **That radius is the proxy's resolution rather than the fabric's thickness**,
+ * and `ClothState#self_radius` carries why.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Pairs one particle may **originate**, before the rest are dropped.
+ *
+ * A particle in a fold has a few neighbours across the fold and a few along it;
+ * eight is generous for a garment and is what bounds the pair list so a cloth
+ * that crumples into a ball cannot allocate its way out of a frame budget. A
+ * particle at the limit keeps the eight it found first in grid order, which is
+ * arbitrary among equals — and they are equals, because every one of them is
+ * inside the same radius.
+ *
+ * **"Originate", not "is in".** The search emits a pair once, from its lower
+ * index, so this caps how many pairs a particle starts and not how many it ends
+ * up in: a particle can be the *higher* index of any number of them. What the
+ * cap does bound exactly — and the only thing `ClothState` needs it to — is the
+ * length of the whole list, at this many per particle, because every pair is
+ * charged to exactly one of its two ends.
+ * @type {number}
+ */
+export const CLOTH_SELF_PAIRS_PER_PARTICLE: number;
+//# sourceMappingURL=cloth_self_find.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CA0DrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAoHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AA1aD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}