@woosh/meep-engine 3.21.0 → 3.23.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_gather_colliders.d.ts

@@ -0,0 +1,59 @@
+/**
+ * # Bringing the world's colliders into a cloth's frame
+ *
+ * The index holds every live cloth collider in **world** coordinates; the
+ * solver works in the cloth's own **local** frame (§12 — garment-sized
+ * coordinates are what makes `Float32` particle state ample, and the local
+ * frame is what makes §7 P7's inertia model natural). So once per cloth per
+ * step, the colliders that could touch it are queried out of the index and
+ * rewritten into its frame.
+ *
+ * ## Both poses go into the *current* anchor frame
+ *
+ * A record carries where the collider was and where it is. Both are converted
+ * using the anchor's pose **now**, not each with the anchor pose of its own
+ * step, so what the sweep interpolates is the collider's motion *relative to
+ * the cloth's frame*. That is the motion the particles actually see: the frame
+ * change has already been applied to them by `move_local_frame`, scaled by
+ * `ClothDynamics#inertia`, before the step begins.
+ *
+ * The alternative — converting each pose in its own frame — would make a
+ * collider appear to move whenever the anchor did, so a character running past
+ * a static wall would sweep the wall through their own cape.
+ *
+ * ## The query box
+ *
+ * The cloth's own particle bounds, fattened by how far a contact reaches, and
+ * then by how far the solver will let a particle travel in one step. The second
+ * term is what stops a fast cloth outrunning its own broadphase within the step
+ * it was gathered for; it is the velocity clamp of §7 P1 read as a distance,
+ * which is the quantity it was built out of.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Query the index and rewrite the overlapping colliders into the cloth's frame.
+ *
+ * @param {ClothInstance} instance filled in place — `collider_table`,
+ *   `collider_key` and `collider_count`
+ * @param {ClothColliderIndex} index
+ * @param {number} reach how far a particle may travel this step, metres
+ * @returns {number} how many colliders were gathered
+ */
+export function cloth_gather_colliders(instance: ClothInstance, index: ClothColliderIndex, reach: number): number;
+/**
+ * Whether any collider overlapping this cloth moved between the previous step
+ * and this one — §7 P5's "wake on collider motion", asked without waking.
+ *
+ * A sleeping cloth is not stepped and not written back, so something has to
+ * notice when the world it was resting against moves. This is that something,
+ * and it is a broadphase query plus a pose comparison: cheaper than a step by
+ * three orders of magnitude, which is what makes sleep worth having at all.
+ *
+ * @param {ClothInstance} instance
+ * @param {ClothColliderIndex} index
+ * @returns {boolean}
+ */
+export function cloth_colliders_moved(instance: ClothInstance, index: ClothColliderIndex): boolean;
+//# sourceMappingURL=cloth_gather_colliders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;GAQG;AACH,kGAHW,MAAM,GACJ,MAAM,CAsJlB;AAgDD;;;;;;;;;;;;GAYG;AACH,2FAFa,OAAO,CAsBnB"}

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

@@ -0,0 +1,328 @@
+import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import {
+    CCR_FEATURE,
+    CCR_FRICTION,
+    CCR_INFLATION,
+    CCR_KIND,
+    CCR_PARAM_0,
+    CCR_PARAM_1,
+    CCR_PARAM_2,
+    CCR_PARAM_3,
+    CCR_PREV_QW,
+    CCR_PREV_QX,
+    CCR_PREV_QY,
+    CCR_PREV_QZ,
+    CCR_PREV_TX,
+    CCR_PREV_TY,
+    CCR_PREV_TZ,
+    CCR_QW,
+    CCR_QX,
+    CCR_QY,
+    CCR_QZ,
+    CCR_STRIDE,
+    CCR_TX,
+    CCR_TY,
+    CCR_TZ
+} from "../collider/ClothColliderRecord.js";
+import { cloth_collider_refit_bounds } from "../collider/cloth_collider_bounds.js";
+
+/**
+ * # Bringing the world's colliders into a cloth's frame
+ *
+ * The index holds every live cloth collider in **world** coordinates; the
+ * solver works in the cloth's own **local** frame (§12 — garment-sized
+ * coordinates are what makes `Float32` particle state ample, and the local
+ * frame is what makes §7 P7's inertia model natural). So once per cloth per
+ * step, the colliders that could touch it are queried out of the index and
+ * rewritten into its frame.
+ *
+ * ## Both poses go into the *current* anchor frame
+ *
+ * A record carries where the collider was and where it is. Both are converted
+ * using the anchor's pose **now**, not each with the anchor pose of its own
+ * step, so what the sweep interpolates is the collider's motion *relative to
+ * the cloth's frame*. That is the motion the particles actually see: the frame
+ * change has already been applied to them by `move_local_frame`, scaled by
+ * `ClothDynamics#inertia`, before the step begins.
+ *
+ * The alternative — converting each pose in its own frame — would make a
+ * collider appear to move whenever the anchor did, so a character running past
+ * a static wall would sweep the wall through their own cape.
+ *
+ * ## The query box
+ *
+ * The cloth's own particle bounds, fattened by how far a contact reaches, and
+ * then by how far the solver will let a particle travel in one step. The second
+ * term is what stops a fast cloth outrunning its own broadphase within the step
+ * it was gathered for; it is the velocity clamp of §7 P1 read as a distance,
+ * which is the quantity it was built out of.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Query the index and rewrite the overlapping colliders into the cloth's frame.
+ *
+ * @param {ClothInstance} instance filled in place — `collider_table`,
+ *   `collider_key` and `collider_count`
+ * @param {ClothColliderIndex} index
+ * @param {number} reach how far a particle may travel this step, metres
+ * @returns {number} how many colliders were gathered
+ */
+export function cloth_gather_colliders(instance, index, reach) {
+    const state = instance.state;
+
+    const particle_count = state.particle_count;
+    const position = state.position;
+
+    let min_x = Infinity;
+    let min_y = Infinity;
+    let min_z = Infinity;
+    let max_x = -Infinity;
+    let max_y = -Infinity;
+    let max_z = -Infinity;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const x = position[p];
+        const y = position[p + 1];
+        const z = position[p + 2];
+
+        if (x < min_x) { min_x = x; }
+        if (y < min_y) { min_y = y; }
+        if (z < min_z) { min_z = z; }
+        if (x > max_x) { max_x = x; }
+        if (y > max_y) { max_y = y; }
+        if (z > max_z) { max_z = z; }
+    }
+
+    if (particle_count === 0) {
+        instance.collider_count = 0;
+
+        return 0;
+    }
+
+    const margin = reach + state.contact_radius * 2;
+
+    min_x -= margin;
+    min_y -= margin;
+    min_z -= margin;
+    max_x += margin;
+    max_y += margin;
+    max_z += margin;
+
+    // The anchor pose the particles were carried into this step, not the live
+    // component — those are the same value by the time this runs, and the
+    // cached pair is the one `move_local_frame` used.
+    const anchor_x = instance.anchor_translation[0];
+    const anchor_y = instance.anchor_translation[1];
+    const anchor_z = instance.anchor_translation[2];
+
+    const qx = instance.anchor_rotation[0];
+    const qy = instance.anchor_rotation[1];
+    const qz = instance.anchor_rotation[2];
+    const qw = instance.anchor_rotation[3];
+
+    // The local box's eight corners, in world. A rotated box is not a box, so
+    // the world query volume is the bounds of the rotated one rather than the
+    // rotation of the bounds.
+    let world_min_x = Infinity;
+    let world_min_y = Infinity;
+    let world_min_z = Infinity;
+    let world_max_x = -Infinity;
+    let world_max_y = -Infinity;
+    let world_max_z = -Infinity;
+
+    for (let corner = 0; corner < 8; corner++) {
+        v3_quaternion_apply(
+            CORNER, 0,
+            (corner & 1) === 0 ? min_x : max_x,
+            (corner & 2) === 0 ? min_y : max_y,
+            (corner & 4) === 0 ? min_z : max_z,
+            qx, qy, qz, qw
+        );
+
+        const x = CORNER[0] + anchor_x;
+        const y = CORNER[1] + anchor_y;
+        const z = CORNER[2] + anchor_z;
+
+        if (x < world_min_x) { world_min_x = x; }
+        if (y < world_min_y) { world_min_y = y; }
+        if (z < world_min_z) { world_min_z = z; }
+        if (x > world_max_x) { world_max_x = x; }
+        if (y > world_max_y) { world_max_y = y; }
+        if (z > world_max_z) { world_max_z = z; }
+    }
+
+    const cloth = instance.cloth;
+
+    const found = index.query(
+        HANDLES, world_min_x, world_min_y, world_min_z,
+        world_max_x, world_max_y, world_max_z,
+        cloth.layer, cloth.mask
+    );
+
+    if (instance.collider_table === null || instance.collider_table.length < found * CCR_STRIDE) {
+        let capacity = 8;
+
+        while (capacity < found) {
+            capacity *= 2;
+        }
+
+        instance.collider_table = new Float32Array(capacity * CCR_STRIDE);
+        instance.collider_key = new Int32Array(capacity);
+    }
+
+    const table = instance.collider_table;
+    const keys = instance.collider_key;
+
+    const source = index.table;
+
+    for (let i = 0; i < found; i++) {
+        const handle = HANDLES[i];
+
+        const from = handle * CCR_STRIDE;
+        const to = i * CCR_STRIDE;
+
+        keys[i] = handle;
+
+        table[to + CCR_KIND] = source[from + CCR_KIND];
+        table[to + CCR_PARAM_0] = source[from + CCR_PARAM_0];
+        table[to + CCR_PARAM_1] = source[from + CCR_PARAM_1];
+        table[to + CCR_PARAM_2] = source[from + CCR_PARAM_2];
+        table[to + CCR_PARAM_3] = source[from + CCR_PARAM_3];
+        table[to + CCR_FEATURE] = source[from + CCR_FEATURE];
+        table[to + CCR_FRICTION] = source[from + CCR_FRICTION];
+        table[to + CCR_INFLATION] = source[from + CCR_INFLATION];
+
+        localise(
+            table, to + CCR_TX, to + CCR_QX,
+            source[from + CCR_TX], source[from + CCR_TY], source[from + CCR_TZ],
+            source[from + CCR_QX], source[from + CCR_QY], source[from + CCR_QZ], source[from + CCR_QW],
+            anchor_x, anchor_y, anchor_z, qx, qy, qz, qw
+        );
+
+        localise(
+            table, to + CCR_PREV_TX, to + CCR_PREV_QX,
+            source[from + CCR_PREV_TX], source[from + CCR_PREV_TY], source[from + CCR_PREV_TZ],
+            source[from + CCR_PREV_QX], source[from + CCR_PREV_QY],
+            source[from + CCR_PREV_QZ], source[from + CCR_PREV_QW],
+            anchor_x, anchor_y, anchor_z, qx, qy, qz, qw
+        );
+
+        cloth_collider_refit_bounds(table, i, CCR_STRIDE);
+    }
+
+    instance.collider_count = found;
+
+    return found;
+}
+
+/**
+ * Write a world pose into a record's translation and rotation slots, expressed
+ * in the anchor's frame.
+ *
+ * @param {Float32Array} table
+ * @param {number} translation_slot
+ * @param {number} rotation_slot
+ * @param {number} tx
+ * @param {number} ty
+ * @param {number} tz
+ * @param {number} rx
+ * @param {number} ry
+ * @param {number} rz
+ * @param {number} rw
+ * @param {number} anchor_x
+ * @param {number} anchor_y
+ * @param {number} anchor_z
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @private
+ */
+function localise(
+    table, translation_slot, rotation_slot,
+    tx, ty, tz, rx, ry, rz, rw,
+    anchor_x, anchor_y, anchor_z, qx, qy, qz, qw
+) {
+    v3_quaternion_apply_inverse(
+        LOCAL_TRANSLATION, 0,
+        tx - anchor_x, ty - anchor_y, tz - anchor_z,
+        qx, qy, qz, qw
+    );
+
+    table[translation_slot] = LOCAL_TRANSLATION[0];
+    table[translation_slot + 1] = LOCAL_TRANSLATION[1];
+    table[translation_slot + 2] = LOCAL_TRANSLATION[2];
+
+    quat3_multiply(LOCAL_ROTATION, 0, -qx, -qy, -qz, qw, rx, ry, rz, rw);
+
+    table[rotation_slot] = LOCAL_ROTATION[0];
+    table[rotation_slot + 1] = LOCAL_ROTATION[1];
+    table[rotation_slot + 2] = LOCAL_ROTATION[2];
+    table[rotation_slot + 3] = LOCAL_ROTATION[3];
+}
+
+/**
+ * Whether any collider overlapping this cloth moved between the previous step
+ * and this one — §7 P5's "wake on collider motion", asked without waking.
+ *
+ * A sleeping cloth is not stepped and not written back, so something has to
+ * notice when the world it was resting against moves. This is that something,
+ * and it is a broadphase query plus a pose comparison: cheaper than a step by
+ * three orders of magnitude, which is what makes sleep worth having at all.
+ *
+ * @param {ClothInstance} instance
+ * @param {ClothColliderIndex} index
+ * @returns {boolean}
+ */
+export function cloth_colliders_moved(instance, index) {
+    const found = cloth_gather_colliders(instance, index, 0);
+
+    const table = instance.collider_table;
+
+    for (let i = 0; i < found; i++) {
+        const r = i * CCR_STRIDE;
+
+        if (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]
+            || table[r + CCR_QX] !== table[r + CCR_PREV_QX]
+            || table[r + CCR_QY] !== table[r + CCR_PREV_QY]
+            || table[r + CCR_QZ] !== table[r + CCR_PREV_QZ]
+            || table[r + CCR_QW] !== table[r + CCR_PREV_QW]) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * @type {number[]}
+ * @private
+ */
+const HANDLES = [];
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const CORNER = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const LOCAL_TRANSLATION = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const LOCAL_ROTATION = new Float64Array(4);

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

@@ -0,0 +1,13 @@
+/**
+ * Fill `blended_position` and `blended_rotation` from the solved particles.
+ *
+ * Both are in the **cloth's own frame**: the position is the particle lerped
+ * towards its animated one by `Cloth#blend`, and the rotation is the swing
+ * composed onto the animated orientation. Node 0 — the anchor — is the origin of
+ * that frame, so its rotation is the identity rather than anything read off it.
+ *
+ * @param {ClothInstance} instance
+ * @returns {void}
+ */
+export function cloth_reconstruct_pose(instance: ClothInstance): void;
+//# sourceMappingURL=cloth_reconstruct_pose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_reconstruct_pose.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_reconstruct_pose.js"],"names":[],"mappings":"AA6DA;;;;;;;;;;GAUG;AACH,iEAFa,IAAI,CAqEhB"}