@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/playground/collide_main.js

@@ -0,0 +1,720 @@
+import {
+    CCR_FRICTION,
+    CCR_INFLATION,
+    CCR_INTERP_QW,
+    CCR_INTERP_QX,
+    CCR_INTERP_QY,
+    CCR_INTERP_QZ,
+    CCR_INTERP_TX,
+    CCR_INTERP_TY,
+    CCR_INTERP_TZ,
+    CCR_STRIDE
+} from "../collider/ClothColliderRecord.js";
+import { ClothColliderKind } from "../collider/ClothColliderKind.js";
+import {
+    cloth_collider_pose_at,
+    cloth_collider_signed_distance
+} from "../collider/cloth_collider_sdf.js";
+import { cloth_contact_find } from "../solver/cloth_contact_find.js";
+import { CLOTH_SOLVER_TUNING } from "../solver/cloth_solver_constants.js";
+import { cloth_step } from "../solver/cloth_step.js";
+import { CLOTH_CONTACT_SLOTS } from "../solver/constraint/cloth_contact_row.js";
+import { find_non_finite_cloth_state } from "../solver/find_non_finite_cloth_state.js";
+import { build_cloth_playground_scene } from "./cloth_playground_build.js";
+import { COLLIDER_SCENES, unsweep } from "./collide_build.js";
+import { draw_cloth, PlaygroundCamera, project } from "./cloth_playground_draw.js";
+
+/**
+ * # Cloth collision playground — M2
+ *
+ * `npm run dev --workspace @woosh/meep-engine`, then
+ * <http://localhost:5173/src/engine/physics/cloth/playground/collide.html>.
+ *
+ * The solver page (`index.html`) is `cloth_step` with a canvas attached; this
+ * is the same thing with a **packed collider table** in the argument list. No
+ * `EntityManager`, no `ClothColliderIndex`, no `ClothColliderSystem` — the
+ * scenes below hand the solver exactly what `cloth_gather_colliders` would, in
+ * the cloth's own frame, which is the layer M2's findings live in.
+ *
+ * Two of those findings are things to *watch* rather than read:
+ *
+ * - **the sweep**, which is not really about tunnelling. Turn it off on the
+ *   swept-capsule scene and the capsule stops being *noticed*: the discovery
+ *   pass evaluates at the end-of-step pose, where a fast collider has already
+ *   gone by, so no row is ever created. The contact readout goes to zero while
+ *   the capsule visibly passes through the sheet.
+ * - **the penalty floor**, which decides how hard a new contact hits. Drag
+ *   `k_min ÷ k_max` to 1 on the ground scene and watch the cape slap; drag it
+ *   back to 1/32 and it lands.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Display rate the fixed step is driven at. */
+const FIXED_STEP = 1 / 60;
+
+/** §17's target, for the budget bar. */
+const BUDGET_MS = 2;
+
+/** How many recent step timings the readout keeps. */
+const TIMING_WINDOW = 120;
+
+const element = (id) => document.getElementById(id);
+
+const canvas = element('view');
+const context = canvas.getContext('2d');
+
+const camera = new PlaygroundCamera();
+
+camera.target[1] = -0.35;
+camera.distance = 1.5;
+
+/**
+ * Everything the page can change. `scene`, `size` and `spacing` rebuild; the
+ * rest are read afresh every step.
+ */
+const control = {
+    scene: 'sphere',
+    size: 22,
+    spacing: 0.03,
+    thickness: 0.006,
+    friction: 0.4,
+    inflation: 0,
+    substeps: 2,
+    iterations: 4,
+    k_floor: 1 / 32,
+    beta: CLOTH_SOLVER_TUNING.beta,
+    swept: true,
+    animate: true,
+    running: true
+};
+
+/** @type {{state: ClothState, triangle: number[]}} */
+let cloth = null;
+
+/** @type {import("./collide_build.js").ColliderScene} */
+let colliders = null;
+
+let time = 0;
+
+let worst_penetration = 0;
+let contact_rows = 0;
+
+const timings = [];
+
+const GRADIENT = new Float64Array(3);
+
+// ------------------------------------------------------------------ build
+
+function rebuild() {
+    cloth = build_cloth_playground_scene({
+        shape: 'sheet',
+        width: control.size,
+        height: control.size,
+        spacing: control.spacing,
+        mass: 0.4,
+        stretch_stiffness: Infinity,
+        bend_modulus: 1e-4,
+        pinned: 'top',
+        flat: false
+    });
+
+    cloth.state.contact_radius = control.thickness;
+
+    colliders = COLLIDER_SCENES[control.scene].build();
+
+    element('scene_blurb').textContent = COLLIDER_SCENES[control.scene].blurb;
+
+    time = 0;
+    worst_penetration = 0;
+    contact_rows = 0;
+
+    timings.length = 0;
+}
+
+// ------------------------------------------------------------------- step
+
+function step_once() {
+    const state = cloth.state;
+
+    state.contact_radius = control.thickness;
+
+    for (let record = 0; record < colliders.count; record++) {
+        const r = record * CCR_STRIDE;
+
+        colliders.table[r + CCR_FRICTION] = control.friction;
+        colliders.table[r + CCR_INFLATION] = control.inflation;
+    }
+
+    if (control.animate && colliders.animate !== undefined) {
+        time += FIXED_STEP;
+
+        for (let record = 0; record < colliders.count; record++) {
+            colliders.animate(record, time);
+        }
+    }
+
+    if (!control.swept) {
+        // The previous pose becomes the current one, so there is nothing to
+        // interpolate and no travel to widen the discovery margin with.
+        for (let record = 0; record < colliders.count; record++) {
+            unsweep(colliders, record);
+        }
+    }
+
+    const tuning = {
+        alpha: CLOTH_SOLVER_TUNING.alpha,
+        beta: control.beta,
+        gamma: CLOTH_SOLVER_TUNING.gamma,
+        k_min_ratio: CLOTH_SOLVER_TUNING.k_max_ratio,
+        k_max_ratio: CLOTH_SOLVER_TUNING.k_max_ratio
+    };
+
+    const started = performance.now();
+
+    contact_rows = cloth_contact_find(state, colliders.table, colliders.keys, colliders.count);
+
+    cloth_step(
+        state, FIXED_STEP, 0, -9.81, 0,
+        control.substeps, control.iterations,
+        colliders.table, colliders.count,
+        { ...tuning, k_min_ratio: tuning.k_max_ratio * control.k_floor }
+    );
+
+    const elapsed = performance.now() - started;
+
+    timings.push(elapsed);
+
+    if (timings.length > TIMING_WINDOW) {
+        timings.shift();
+    }
+
+    const depth = penetration();
+
+    if (depth > worst_penetration) {
+        worst_penetration = depth;
+    }
+}
+
+/**
+ * @returns {number} how far inside any collider any particle is, right now
+ */
+function penetration() {
+    const state = cloth.state;
+
+    cloth_collider_pose_at(colliders.table, colliders.count, 1);
+
+    let worst = 0;
+
+    for (let i = 0; i < state.particle_count; i++) {
+        const p = i * 3;
+
+        for (let record = 0; record < colliders.count; record++) {
+            const distance = cloth_collider_signed_distance(
+                GRADIENT, 0, colliders.table, record,
+                state.position[p], state.position[p + 1], state.position[p + 2]
+            );
+
+            const offset = state.contact_radius + colliders.table[record * CCR_STRIDE + CCR_INFLATION];
+
+            if (offset - distance > worst) {
+                worst = offset - distance;
+            }
+        }
+    }
+
+    return worst;
+}
+
+/**
+ * @returns {number} kinetic energy, J
+ */
+function kinetic() {
+    const state = cloth.state;
+
+    let total = 0;
+
+    for (let i = 0; i < state.particle_count; i++) {
+        const w = state.mass_inverse[i];
+
+        if (w === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        total += 0.5 * (
+            state.velocity[p] * state.velocity[p] +
+            state.velocity[p + 1] * state.velocity[p + 1] +
+            state.velocity[p + 2] * state.velocity[p + 2]
+        ) / w;
+    }
+
+    return total;
+}
+
+// ------------------------------------------------------------------- draw
+
+/**
+ * Colliders as wireframes over the cloth. Each is drawn from its own
+ * *interpolated* pose, so the swept toggle is visible rather than merely
+ * described: with the sweep on, the outline is where the substeps saw it.
+ *
+ * There is **no depth test**: the outline is painted over the cloth whether it
+ * is in front of it or behind. That is a property of the drawing rather than of
+ * the simulation, and it is worth knowing before reading a screenshot — a
+ * sphere behind a draped cape looks like a sphere poking through one. The
+ * readout's *resting penetration* is the number that says which it is.
+ */
+function draw_colliders() {
+    const width = canvas.width;
+    const height = canvas.height;
+
+    context.save();
+    context.strokeStyle = '#e5b54a';
+    context.globalAlpha = 0.4;
+    context.setLineDash([5, 4]);
+    context.lineWidth = Math.max(1, width / 900);
+
+    const projected = new Float64Array(2);
+
+    for (let record = 0; record < colliders.count; record++) {
+        const r = record * CCR_STRIDE;
+
+        const kind = colliders.table[r + CCR_KIND_SLOT];
+
+        const outline = outline_of(record);
+
+        for (const loop of outline) {
+            context.beginPath();
+
+            for (let i = 0; i < loop.length; i += 3) {
+                to_world(WORLD, r, loop[i], loop[i + 1], loop[i + 2]);
+
+                project(projected, camera, WORLD[0], WORLD[1], WORLD[2], width, height);
+
+                if (i === 0) {
+                    context.moveTo(projected[0], projected[1]);
+                } else {
+                    context.lineTo(projected[0], projected[1]);
+                }
+            }
+
+            if (kind !== ClothColliderKind.Plane) {
+                context.closePath();
+            }
+
+            context.stroke();
+        }
+    }
+
+    context.restore();
+}
+
+/** The kind slot, named here so the drawing does not import the whole record. */
+const CCR_KIND_SLOT = 0;
+
+const WORLD = new Float64Array(3);
+
+/**
+ * @param {Float64Array} out
+ * @param {number} r record slot offset
+ * @param {number} x local
+ * @param {number} y local
+ * @param {number} z local
+ */
+function to_world(out, r, x, y, z) {
+    const qx = colliders.table[r + CCR_INTERP_QX];
+    const qy = colliders.table[r + CCR_INTERP_QY];
+    const qz = colliders.table[r + CCR_INTERP_QZ];
+    const qw = colliders.table[r + CCR_INTERP_QW];
+
+    const tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+
+    out[0] = x + qw * tx + (qy * tz - qz * ty) + colliders.table[r + CCR_INTERP_TX];
+    out[1] = y + qw * ty + (qz * tx - qx * tz) + colliders.table[r + CCR_INTERP_TY];
+    out[2] = z + qw * tz + (qx * ty - qy * tx) + colliders.table[r + CCR_INTERP_TZ];
+}
+
+/**
+ * Line loops in the collider's own local frame, one flat `[x, y, z, ...]` array
+ * each. Drawn rather than triangulated because the point is to see the cloth
+ * through the collider.
+ *
+ * @param {number} record
+ * @returns {number[][]}
+ */
+function outline_of(record) {
+    const shape = colliders.shape[record];
+
+    const table = colliders.table;
+    const r = record * CCR_STRIDE;
+
+    const kind = table[r + CCR_KIND_SLOT];
+
+    if (kind === ClothColliderKind.Sphere) {
+        return [ring(shape.radius, 0, 1), ring(shape.radius, 0, 2), ring(shape.radius, 1, 2)];
+    }
+
+    if (kind === ClothColliderKind.Capsule || kind === ClothColliderKind.Cylinder) {
+        const half = shape.height * 0.5;
+        const radius = shape.radius;
+
+        const loops = [
+            ring(radius, 0, 2, half),
+            ring(radius, 0, 2, -half)
+        ];
+
+        // Two side lines, plus the caps for a capsule.
+        loops.push([radius, half, 0, radius, -half, 0]);
+        loops.push([-radius, half, 0, -radius, -half, 0]);
+
+        if (kind === ClothColliderKind.Capsule) {
+            loops.push(arc(radius, half, 0, Math.PI));
+            loops.push(arc(radius, -half, Math.PI, Math.PI * 2));
+        }
+
+        return loops;
+    }
+
+    if (kind === ClothColliderKind.Box) {
+        const h = shape.half_extents;
+
+        return [
+            [-h.x, -h.y, -h.z, h.x, -h.y, -h.z, h.x, h.y, -h.z, -h.x, h.y, -h.z],
+            [-h.x, -h.y, h.z, h.x, -h.y, h.z, h.x, h.y, h.z, -h.x, h.y, h.z],
+            [-h.x, -h.y, -h.z, -h.x, -h.y, h.z],
+            [h.x, -h.y, -h.z, h.x, -h.y, h.z],
+            [h.x, h.y, -h.z, h.x, h.y, h.z],
+            [-h.x, h.y, -h.z, -h.x, h.y, h.z]
+        ];
+    }
+
+    // A plane: a grid on its own surface, which is all of it anyone can see.
+    const loops = [];
+
+    const extent = 1.2;
+
+    for (let i = -4; i <= 4; i++) {
+        const t = i * extent / 4;
+
+        loops.push([t, 0, -extent, t, 0, extent]);
+        loops.push([-extent, 0, t, extent, 0, t]);
+    }
+
+    return loops;
+}
+
+/**
+ * @param {number} radius
+ * @param {number} axis_a 0, 1 or 2
+ * @param {number} axis_b
+ * @param {number} [offset] along the remaining axis
+ * @returns {number[]}
+ */
+function ring(radius, axis_a, axis_b, offset = 0) {
+    const out = [];
+
+    const other = 3 - axis_a - axis_b;
+
+    for (let i = 0; i < 24; i++) {
+        const angle = i / 24 * Math.PI * 2;
+
+        const point = [0, 0, 0];
+
+        point[axis_a] = Math.cos(angle) * radius;
+        point[axis_b] = Math.sin(angle) * radius;
+        point[other] = offset;
+
+        out.push(point[0], point[1], point[2]);
+    }
+
+    return out;
+}
+
+/**
+ * A cap arc in the XY plane, offset along Y.
+ * @param {number} radius
+ * @param {number} y
+ * @param {number} from radians
+ * @param {number} to
+ * @returns {number[]}
+ */
+function arc(radius, y, from, to) {
+    const out = [];
+
+    for (let i = 0; i <= 12; i++) {
+        const angle = from + (to - from) * i / 12;
+
+        out.push(Math.cos(angle) * radius, y + Math.sin(angle) * radius, 0);
+    }
+
+    return out;
+}
+
+// ---------------------------------------------------------------- readout
+
+function refresh_readout() {
+    const best = timings.length === 0 ? 0 : Math.min(...timings);
+
+    element('r_step').textContent = `${best.toFixed(3)} ms`;
+    element('r_contacts').textContent = String(contact_rows);
+    element('r_pen').textContent = `${(worst_penetration * 1000).toFixed(2)} mm`;
+    element('r_rest').textContent = `${(penetration() * 1000).toFixed(2)} mm`;
+    element('r_energy').textContent = kinetic().toExponential(2);
+
+    const offender = find_non_finite_cloth_state(cloth.state);
+
+    const finite = element('r_finite');
+
+    finite.textContent = offender === "" ? 'ok' : offender;
+    finite.className = offender === "" ? 'good' : 'bad';
+
+    if (offender !== "") {
+        control.running = false;
+        element('pause').textContent = 'resume';
+    }
+
+    const budget = element('budget');
+
+    budget.classList.toggle('over', best > BUDGET_MS);
+    budget.firstElementChild.style.width = `${Math.min(100, best / BUDGET_MS * 100)}%`;
+}
+
+// ------------------------------------------------------------------ frame
+
+function frame() {
+    if (control.running) {
+        step_once();
+    }
+
+    draw_cloth(context, camera, cloth.state, cloth.triangle, {
+        view: 'shaded',
+        colour_of_particle: null,
+        grabbed: -1
+    });
+
+    draw_colliders();
+
+    refresh_readout();
+
+    requestAnimationFrame(frame);
+}
+
+// --------------------------------------------------------------- controls
+
+const scene_select = element('scene');
+
+for (const [name, entry] of Object.entries(COLLIDER_SCENES)) {
+    const option = document.createElement('option');
+
+    option.value = name;
+    option.textContent = entry.label;
+
+    scene_select.append(option);
+}
+
+scene_select.value = control.scene;
+
+scene_select.addEventListener('change', () => {
+    control.scene = scene_select.value;
+
+    rebuild();
+});
+
+/**
+ * @param {string} id
+ * @param {string} key
+ * @param {function(number): string} format
+ * @param {boolean} rebuilds
+ */
+function slider(id, key, format, rebuilds = false) {
+    const input = element(id);
+    const output = element(`${id}_out`);
+
+    input.value = String(control[key]);
+    output.textContent = format(control[key]);
+
+    input.addEventListener('input', () => {
+        control[key] = Number(input.value);
+
+        output.textContent = format(control[key]);
+
+        if (rebuilds) {
+            rebuild();
+        }
+    });
+
+    return input;
+}
+
+slider('size', 'size', (v) => `${v}²`, true);
+slider('spacing', 'spacing', (v) => `${(v * 100).toFixed(1)} cm`, true);
+slider('thickness', 'thickness', (v) => `${(v * 1000).toFixed(0)} mm`);
+slider('friction', 'friction', (v) => v.toFixed(2));
+slider('inflation', 'inflation', (v) => `${(v * 1000).toFixed(0)} mm`);
+slider('substeps', 'substeps', (v) => String(v));
+slider('iterations', 'iterations', (v) => String(v));
+
+// Both band controls are logarithmic: the interesting range spans decades.
+const floor_input = element('k_floor');
+const floor_output = element('k_floor_out');
+
+floor_input.value = String(Math.log2(control.k_floor));
+floor_output.textContent = `1/${Math.round(1 / control.k_floor)}`;
+
+floor_input.addEventListener('input', () => {
+    control.k_floor = Math.pow(2, Number(floor_input.value));
+
+    floor_output.textContent = control.k_floor >= 1
+        ? control.k_floor.toFixed(2)
+        : `1/${(1 / control.k_floor).toFixed(1)}`;
+});
+
+const beta_input = element('beta');
+const beta_output = element('beta_out');
+
+beta_input.value = String(Math.log10(control.beta));
+beta_output.textContent = control.beta.toExponential(0);
+
+beta_input.addEventListener('input', () => {
+    control.beta = Math.pow(10, Number(beta_input.value));
+
+    beta_output.textContent = control.beta.toExponential(0);
+});
+
+element('defaults').addEventListener('click', () => {
+    control.k_floor = 1 / 32;
+    control.beta = CLOTH_SOLVER_TUNING.beta;
+
+    floor_input.value = String(Math.log2(control.k_floor));
+    floor_output.textContent = '1/32';
+
+    beta_input.value = String(Math.log10(control.beta));
+    beta_output.textContent = control.beta.toExponential(0);
+});
+
+const sweep_button = element('sweep');
+const unswept_button = element('unswept');
+
+sweep_button.addEventListener('click', () => {
+    control.swept = true;
+
+    sweep_button.classList.add('on');
+    unswept_button.classList.remove('on');
+});
+
+unswept_button.addEventListener('click', () => {
+    control.swept = false;
+
+    sweep_button.classList.remove('on');
+    unswept_button.classList.add('on');
+});
+
+element('pause').addEventListener('click', (event) => {
+    control.running = !control.running;
+
+    event.target.textContent = control.running ? 'pause' : 'resume';
+});
+
+element('single').addEventListener('click', step_once);
+element('reset').addEventListener('click', rebuild);
+
+element('animate').addEventListener('click', (event) => {
+    control.animate = !control.animate;
+
+    event.target.classList.toggle('on', control.animate);
+});
+
+// ----------------------------------------------------------------- camera
+
+let drag = null;
+
+canvas.addEventListener('pointerdown', (event) => {
+    canvas.setPointerCapture(event.pointerId);
+    canvas.classList.add('grabbing');
+
+    drag = {
+        x: event.clientX,
+        y: event.clientY,
+        pan: event.shiftKey || event.button === 2
+    };
+});
+
+canvas.addEventListener('pointermove', (event) => {
+    if (drag === null) {
+        return;
+    }
+
+    const dx = event.clientX - drag.x;
+    const dy = event.clientY - drag.y;
+
+    drag.x = event.clientX;
+    drag.y = event.clientY;
+
+    if (!drag.pan) {
+        camera.yaw -= dx * 0.006;
+        camera.pitch = Math.max(-1.4, Math.min(1.4, camera.pitch + dy * 0.006));
+
+        return;
+    }
+
+    const scale = camera.distance * 0.0016;
+
+    camera.target[0] -= dx * Math.cos(camera.yaw) * scale;
+    camera.target[2] += dx * Math.sin(camera.yaw) * scale;
+    camera.target[1] += dy * scale;
+});
+
+function release(event) {
+    drag = null;
+
+    canvas.classList.remove('grabbing');
+
+    if (event !== undefined && canvas.hasPointerCapture(event.pointerId)) {
+        canvas.releasePointerCapture(event.pointerId);
+    }
+}
+
+canvas.addEventListener('pointerup', release);
+canvas.addEventListener('pointercancel', release);
+canvas.addEventListener('contextmenu', (event) => event.preventDefault());
+
+canvas.addEventListener('wheel', (event) => {
+    event.preventDefault();
+
+    camera.distance = Math.max(0.1, Math.min(20, camera.distance * Math.exp(event.deltaY * 0.0012)));
+}, { passive: false });
+
+// ------------------------------------------------------------------ start
+
+function resize() {
+    const ratio = Math.min(2, window.devicePixelRatio || 1);
+
+    canvas.width = Math.round(canvas.clientWidth * ratio);
+    canvas.height = Math.round(canvas.clientHeight * ratio);
+}
+
+window.addEventListener('resize', resize);
+
+resize();
+rebuild();
+
+requestAnimationFrame(frame);
+
+// A handle for a driver script — `requestAnimationFrame` does not fire while
+// the pane is hidden, so a driver steps the page itself.
+globalThis.cloth_collide_playground = {
+    control,
+    camera,
+    rebuild,
+    step_once,
+    penetration,
+    get cloth() { return cloth; },
+    get colliders() { return colliders; },
+    get contacts() { return contact_rows; },
+    slots: CLOTH_CONTACT_SLOTS
+};