@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -0,0 +1,315 @@
+import { BoxShape3D } from "../../../../core/geom/3d/shape/BoxShape3D.js";
+import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
+import { CylinderShape3D } from "../../../../core/geom/3d/shape/CylinderShape3D.js";
+import { PlaneShape3D } from "../../../../core/geom/3d/shape/PlaneShape3D.js";
+import { SphereShape3D } from "../../../../core/geom/3d/shape/SphereShape3D.js";
+import {
+    CCR_FRICTION,
+    CCR_INFLATION,
+    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";
+import { cloth_collider_pack } from "../collider/cloth_collider_pack.js";
+
+/**
+ * # The collider scenes the M2 page collides against
+ *
+ * Packed tables built straight from shapes, already in the cloth's own frame —
+ * there is no `EntityManager` on this page, so `ClothColliderIndex` and
+ * `ClothColliderSystem` are not in the loop and everything below the gather is.
+ *
+ * Kept beside the page rather than in `__fixtures__` for the reason
+ * `cloth_playground_build.js` gives: `__fixtures__` is excluded from the
+ * published package and the playground is not, so importing across that line
+ * would ship a broken module.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @typedef {object} ColliderScene
+ * @property {string} label
+ * @property {string} blurb what the scene is for
+ * @property {Float32Array} table packed records, cloth-local
+ * @property {Int32Array} keys
+ * @property {number} count
+ * @property {AbstractShape3D[]} shape the shape behind each record, for drawing
+ * @property {function(number, number): void} [animate] `(record, time) => void`
+ */
+
+/**
+ * Every scene, by name.
+ * @type {Readonly<Object<string, {label: string, blurb: string, build: function}>>}
+ */
+export const COLLIDER_SCENES = Object.freeze({
+    sphere: {
+        label: 'sphere under a cape',
+        blurb: 'The simplest thing a contact row can be right about.',
+        build: () => scene([
+            { shape: SphereShape3D.from(0.18), at: [0, -0.4, -0.14] }
+        ])
+    },
+    primitives: {
+        label: 'every primitive',
+        blurb: 'Sphere, capsule, box, cylinder — the four analytic kinds §8.2 supports, '
+            + 'all evaluated by the same packed dispatch and the same free functions the shape classes now call.',
+        build: () => scene([
+            // Each sits behind the sheet and protrudes 25 mm through it, so what
+            // is on screen is four different fields answering the same question.
+            { shape: SphereShape3D.from(0.09), at: [-0.23, -0.2, -0.065] },
+            { shape: CapsuleShape3D.from(0.06, 0.16), at: [-0.08, -0.36, -0.035], rotation: axis_angle(0, 0, 1, Math.PI / 2) },
+            { shape: BoxShape3D.from(0.07, 0.07, 0.08), at: [0.09, -0.2, -0.055] },
+            { shape: CylinderShape3D.from(0.07, 0.16), at: [0.24, -0.36, -0.045], rotation: axis_angle(0, 0, 1, Math.PI / 2) }
+        ])
+    },
+    ground: {
+        label: 'the ground',
+        blurb: 'A PlaneShape3D, which §14.3 asked for and did not exist. A cape folding onto a floor '
+            + 'is what an infinite half-space is for, and it costs one dot product a particle.',
+        build: () => scene([
+            { shape: PlaneShape3D.GROUND, at: [0, -0.46, 0], friction: 0.4 }
+        ])
+    },
+    shoulder: {
+        label: 'a shoulder, animated',
+        blurb: 'Three capsules as an arm, swinging. §8.2\'s swept collision: the pose is interpolated '
+            + 'across the substeps, so a bone that crosses the cloth within a step is caught on the way.',
+        build: () => {
+            const built = scene([
+                { shape: CapsuleShape3D.from(0.1, 0.34), at: [0, -0.22, -0.08], rotation: axis_angle(0, 0, 1, Math.PI / 2) },
+                { shape: CapsuleShape3D.from(0.06, 0.22), at: [0.24, -0.36, -0.04] },
+                { shape: SphereShape3D.from(0.06), at: [0.24, -0.5, -0.04] }
+            ]);
+
+            built.animate = (record, time) => {
+                if (record === 0) {
+                    return;
+                }
+
+                const swing = Math.sin(time * 2.2) * 0.34;
+
+                const reach = record === 1 ? 0.17 : 0.33;
+
+                move(
+                    built, record,
+                    0.2 * Math.cos(swing),
+                    -0.22 - reach * Math.cos(swing * 0.6),
+                    -0.08 + reach * Math.sin(swing) * 0.9
+                );
+            };
+
+            return built;
+        }
+    },
+    sweep: {
+        label: 'a capsule swept through',
+        blurb: 'A capsule driven straight through the sheet at speed. Turn the sweep off and watch it '
+            + 'stop being noticed at all — the failure was never tunnelling so much as the discovery '
+            + 'pass evaluating at the end-of-step pose, where the collider has already gone past.',
+        build: () => {
+            const built = scene([
+                { shape: CapsuleShape3D.from(0.05, 0.3), at: [0, -0.3, -0.9] }
+            ]);
+
+            built.animate = (record, time) => {
+                // 0.6 s to cross 1.8 m — 3 m/s, which at 60 Hz is 5 cm a step
+                // against a 5 cm capsule. Fast enough that the discovery pass
+                // has to know the collider moved.
+                const period = 0.6;
+
+                const t = (time % period) / period;
+
+                move(built, record, 0, -0.3, -0.9 + t * 1.8);
+            };
+
+            return built;
+        }
+    },
+    spinner: {
+        label: 'a spinning bar',
+        blurb: 'A bar turning behind the cape and through its plane. The interpolated pose is a '
+            + 'translation and a quaternion rather than a lerp of two matrices, which at half a '
+            + 'radian a step would shrink the bar by twice a garment\'s thickness halfway through '
+            + 'every step. It is also the one scene that does not resolve: a rigid bar driven '
+            + 'through cloth that is pinned above it wraps rather than parts, and the readout\'s '
+            + '18 mm of resting penetration is the contact row bounding a case it cannot prevent.',
+        build: () => {
+            const built = scene([
+                { shape: BoxShape3D.from(0.025, 0.025, 0.17), at: [0, -0.4, -0.14], friction: 0.2 }
+            ]);
+
+            built.animate = (record, time) => {
+                const angle = time * 1.6;
+
+                turn(built, record, 0, -0.4, -0.14, axis_angle(0, 1, 0, angle));
+            };
+
+            return built;
+        }
+    }
+});
+
+/**
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} angle radians
+ * @returns {number[]} `[x, y, z, w]`
+ */
+export function axis_angle(x, y, z, angle) {
+    const half = angle * 0.5;
+    const s = Math.sin(half);
+
+    return [x * s, y * s, z * s, Math.cos(half)];
+}
+
+/**
+ * @param {{shape: AbstractShape3D, at?: number[], rotation?: number[], friction?: number, inflation?: number}[]} specs
+ * @returns {ColliderScene}
+ */
+function scene(specs) {
+    const count = specs.length;
+
+    const table = new Float32Array(count * CCR_STRIDE);
+    const keys = new Int32Array(count);
+
+    const shape = [];
+
+    for (let i = 0; i < count; i++) {
+        const spec = specs[i];
+
+        if (!cloth_collider_pack(table, i, spec.shape, CCR_STRIDE)) {
+            throw new Error(`cloth does not collide against ${spec.shape.constructor.name}`);
+        }
+
+        shape.push(spec.shape);
+
+        const at = spec.at ?? [0, 0, 0];
+        const rotation = spec.rotation ?? [0, 0, 0, 1];
+
+        const r = i * CCR_STRIDE;
+
+        table[r + CCR_TX] = at[0];
+        table[r + CCR_TY] = at[1];
+        table[r + CCR_TZ] = at[2];
+
+        table[r + CCR_QX] = rotation[0];
+        table[r + CCR_QY] = rotation[1];
+        table[r + CCR_QZ] = rotation[2];
+        table[r + CCR_QW] = rotation[3];
+
+        table[r + CCR_PREV_TX] = at[0];
+        table[r + CCR_PREV_TY] = at[1];
+        table[r + CCR_PREV_TZ] = at[2];
+
+        table[r + CCR_PREV_QX] = rotation[0];
+        table[r + CCR_PREV_QY] = rotation[1];
+        table[r + CCR_PREV_QZ] = rotation[2];
+        table[r + CCR_PREV_QW] = rotation[3];
+
+        table[r + CCR_FRICTION] = spec.friction ?? 0.3;
+        table[r + CCR_INFLATION] = spec.inflation ?? 0;
+
+        cloth_collider_refit_bounds(table, i, CCR_STRIDE);
+
+        keys[i] = i;
+    }
+
+    return { table, keys, count, shape, animate: undefined };
+}
+
+/**
+ * Move a record, carrying its current pose into its previous one — what a fixed
+ * step does to the index.
+ *
+ * @param {ColliderScene} built
+ * @param {number} record
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+export function move(built, record, x, y, z) {
+    const table = built.table;
+
+    const r = record * CCR_STRIDE;
+
+    carry(table, r);
+
+    table[r + CCR_TX] = x;
+    table[r + CCR_TY] = y;
+    table[r + CCR_TZ] = z;
+
+    cloth_collider_refit_bounds(table, record, CCR_STRIDE);
+}
+
+/**
+ * @param {ColliderScene} built
+ * @param {number} record
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number[]} rotation
+ */
+export function turn(built, record, x, y, z, rotation) {
+    const table = built.table;
+
+    const r = record * CCR_STRIDE;
+
+    carry(table, r);
+
+    table[r + CCR_TX] = x;
+    table[r + CCR_TY] = y;
+    table[r + CCR_TZ] = z;
+
+    table[r + CCR_QX] = rotation[0];
+    table[r + CCR_QY] = rotation[1];
+    table[r + CCR_QZ] = rotation[2];
+    table[r + CCR_QW] = rotation[3];
+
+    cloth_collider_refit_bounds(table, record, CCR_STRIDE);
+}
+
+/**
+ * Freeze a record's previous pose onto its current one, so the sweep has nothing
+ * to interpolate. This is the "sweep off" switch, and it is exactly what the
+ * design would be without §8.2.
+ *
+ * @param {ColliderScene} built
+ * @param {number} record
+ */
+export function unsweep(built, record) {
+    carry(built.table, record * CCR_STRIDE);
+
+    cloth_collider_refit_bounds(built.table, record, CCR_STRIDE);
+}
+
+/**
+ * @param {Float32Array} table
+ * @param {number} r
+ * @private
+ */
+function carry(table, r) {
+    table[r + CCR_PREV_TX] = table[r + CCR_TX];
+    table[r + CCR_PREV_TY] = table[r + CCR_TY];
+    table[r + CCR_PREV_TZ] = table[r + CCR_TZ];
+
+    table[r + CCR_PREV_QX] = table[r + CCR_QX];
+    table[r + CCR_PREV_QY] = table[r + CCR_QY];
+    table[r + CCR_PREV_QZ] = table[r + CCR_QZ];
+    table[r + CCR_PREV_QW] = table[r + CCR_QW];
+}

package/src/engine/physics/cloth/playground/collide_main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=collide_main.d.ts.map

package/src/engine/physics/cloth/playground/collide_main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collide_main.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/collide_main.js"],"names":[],"mappings":""}