@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -0,0 +1,633 @@
+import { Cloth } from "../ecs/Cloth.js";
+import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
+import { PlaygroundCamera, project } from "./cloth_playground_draw.js";
+import { GARMENT_PRESETS, build_garment, garment_sync_colliders } from "./garment_build.js";
+
+/**
+ * # Skinned garments playground — M3
+ *
+ * `npm run dev --workspace @woosh/meep-engine`, then
+ * <http://localhost:5173/src/engine/physics/cloth/playground/garment.html>.
+ *
+ * The rig page (`rig.html`) is a `Cloth` over an entity subtree; this is a
+ * `Cloth` + a `ClothRig` over a skinned model's **joints**. Every point on
+ * screen is a `Node3D.transform_global` — a joint of a `Skin`, not an entity —
+ * and it is where it is because the solver wrote its `transform_local` and this
+ * page composed the chain.
+ *
+ * What it exists to show, because these are claims about a hierarchy rather
+ * than about an array:
+ *
+ * - **the two paths are the same solver.** Change the fabric and the garment
+ *   behaves exactly as the same entry does on the rig page. The rows, the
+ *   geodesics, the leashes and the colouring all come from
+ *   `cloth_build_rows.js`, which both seeders call.
+ * - **the anchor is a bone.** Drive the character and the garment follows the
+ *   chest it hangs from, evaluated on the CPU from the clips rather than read
+ *   back from the GPU — the same evaluator a socket on the same shoulder gets.
+ * - **`blend = 0` is the bind pose**, carried by the animated bone. Not the
+ *   pose the solver left behind, which is what a proxy's baked rest data buys
+ *   over reading the joints at seed time.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const FIXED_STEP = 1 / 60;
+
+const element = (id) => document.getElementById(id);
+
+const canvas = element('view');
+const context = canvas.getContext('2d');
+
+const camera = new PlaygroundCamera();
+
+camera.target[1] = 0.95;
+camera.distance = 3.2;
+camera.yaw = 0.9;
+camera.pitch = 0.12;
+
+const control = {
+    preset: 'cape',
+    dynamics: 'SILK',
+    links: 7,
+    spacing: 0.08,
+    motion: 'still',
+    collide: true,
+    self_collision: true,
+    blend: 1,
+    bind: true,
+    frames: false,
+    body: true,
+    running: true
+};
+
+/** @type {import("./garment_build.js").GarmentScene|null} */
+let scene = null;
+
+let time = 0;
+let sprint_z = 0;
+let step_ms = 0;
+
+const SCREEN = new Float64Array(2);
+const OTHER = new Float64Array(2);
+
+// ------------------------------------------------------------------ build
+
+async function rebuild() {
+    const entry = GARMENT_PRESETS.find(p => p.id === control.preset) ?? GARMENT_PRESETS[0];
+
+    element('preset_blurb').textContent = entry.blurb;
+
+    scene = await build_garment({
+        preset: control.preset,
+        dynamics: control.dynamics,
+        links: control.links,
+        spacing: control.spacing,
+        collide: control.collide,
+        self_collision: control.self_collision
+    });
+
+    time = 0;
+    sprint_z = 0;
+}
+
+// ------------------------------------------------------------------- step
+
+function step_once() {
+    if (scene === null) {
+        return;
+    }
+
+    time += FIXED_STEP;
+
+    drive_character();
+
+    garment_sync_colliders(scene);
+
+    const cloth = scene.ecd.getComponent(scene.entity, Cloth);
+
+    cloth.blend = control.blend;
+
+    const started = performance.now();
+
+    scene.cloth.fixedUpdate(FIXED_STEP);
+
+    step_ms = performance.now() - started;
+}
+
+/**
+ * Move the character's own bones, and nothing else. The garment's joints belong
+ * to the solver — that is the authority claim, and driving them here would be
+ * the race it exists to prevent.
+ */
+function drive_character() {
+    const root = scene.root;
+    const pelvis = scene.pelvis;
+
+    if (control.motion === 'still') {
+        root.transform_local.setTranslation(0, 0, 0);
+        root.transform_local.setRotation(0, 0, 0, 1);
+        pelvis.transform_local.setTranslation(0, 0.95, 0);
+    } else if (control.motion === 'walk') {
+        root.transform_local.setTranslation(0, 0, Math.sin(time * 1.6) * 0.9);
+        root.transform_local.setRotation(0, 0, 0, 1);
+        pelvis.transform_local.setTranslation(0, 0.95 + Math.sin(time * 6.4) * 0.02, 0);
+    } else if (control.motion === 'turn') {
+        const angle = time * 1.9;
+
+        root.transform_local.setTranslation(0, 0, 0);
+        root.transform_local.setRotation(0, Math.sin(angle * 0.5), 0, Math.cos(angle * 0.5));
+        pelvis.transform_local.setTranslation(0, 0.95, 0);
+    } else {
+        // §7 P7's own profile: a **square wave in velocity**, integrated rather
+        // than written as a position — a position that resets is a nine-metre
+        // discontinuity, which is a teleport (§7 P6) wearing a sprint's clothes.
+        sprint_z += (Math.floor(time) % 2 === 0 ? 9 : -9) * FIXED_STEP;
+
+        root.transform_local.setTranslation(0, 0, sprint_z);
+        root.transform_local.setRotation(0, 0, 0, 1);
+        pelvis.transform_local.setTranslation(0, 0.95, 0);
+    }
+
+    root.updateMatrices();
+}
+
+// ------------------------------------------------------------------- draw
+
+function draw() {
+    const width = canvas.width;
+    const height = canvas.height;
+
+    context.clearRect(0, 0, width, height);
+
+    if (scene === null) {
+        return;
+    }
+
+    draw_ground(width, height);
+
+    if (control.body) {
+        draw_body(width, height);
+    }
+
+    if (control.bind) {
+        draw_bind(width, height);
+    }
+
+    draw_garment(width, height);
+
+    if (control.frames) {
+        draw_frames(width, height);
+    }
+}
+
+/**
+ * @param {Node3D} node
+ * @param {Float64Array} out
+ * @param {number} width
+ * @param {number} height
+ * @returns {number} depth
+ */
+function project_node(node, out, width, height) {
+    const t = node.transform_global.translation;
+
+    return project(out, camera, t[0], t[1], t[2], width, height);
+}
+
+function draw_ground(width, height) {
+    context.save();
+    context.strokeStyle = '#1d222a';
+    context.lineWidth = 1;
+
+    for (let i = -6; i <= 6; i++) {
+        const t = i * 0.3;
+
+        context.beginPath();
+        project(SCREEN, camera, t, 0, -1.8, width, height);
+        context.moveTo(SCREEN[0], SCREEN[1]);
+        project(SCREEN, camera, t, 0, 1.8, width, height);
+        context.lineTo(SCREEN[0], SCREEN[1]);
+        context.stroke();
+
+        context.beginPath();
+        project(SCREEN, camera, -1.8, 0, t, width, height);
+        context.moveTo(SCREEN[0], SCREEN[1]);
+        project(SCREEN, camera, 1.8, 0, t, width, height);
+        context.lineTo(SCREEN[0], SCREEN[1]);
+        context.stroke();
+    }
+
+    context.restore();
+}
+
+function draw_body(width, height) {
+    context.save();
+    context.strokeStyle = '#4b5666';
+    context.lineWidth = Math.max(2, width / 500);
+
+    for (const node of scene.bone) {
+        if (node.parent === null) {
+            continue;
+        }
+
+        project_node(node.parent, SCREEN, width, height);
+        project_node(node, OTHER, width, height);
+
+        context.beginPath();
+        context.moveTo(SCREEN[0], SCREEN[1]);
+        context.lineTo(OTHER[0], OTHER[1]);
+        context.stroke();
+    }
+
+    context.restore();
+}
+
+function draw_bind(width, height) {
+    context.save();
+    context.strokeStyle = '#3a5480';
+    context.globalAlpha = 0.55;
+    context.setLineDash([3, 3]);
+    context.lineWidth = 1;
+
+    // The bind pose was captured at build, in the character's rest pose, so it
+    // is drawn where it was rather than where the character now is — which is
+    // the point: it is what `blend = 0` returns *to*, carried by the bone.
+    const bind = scene.bind;
+    const joint = scene.joint;
+
+    for (let i = 0; i < joint.length; i++) {
+        const node = joint[i];
+
+        const parent_index = joint.indexOf(node.parent);
+
+        const from = parent_index >= 0
+            ? bind[parent_index]
+            : [
+                node.parent.transform_global.translation[0],
+                node.parent.transform_global.translation[1],
+                node.parent.transform_global.translation[2]
+            ];
+
+        project(SCREEN, camera, from[0], from[1], from[2], width, height);
+        project(OTHER, camera, bind[i][0], bind[i][1], bind[i][2], width, height);
+
+        context.beginPath();
+        context.moveTo(SCREEN[0], SCREEN[1]);
+        context.lineTo(OTHER[0], OTHER[1]);
+        context.stroke();
+    }
+
+    context.restore();
+}
+
+function draw_garment(width, height) {
+    context.save();
+    context.strokeStyle = '#7aa2f7';
+    context.lineWidth = Math.max(1.5, width / 700);
+
+    for (const node of scene.joint) {
+        project_node(node.parent, SCREEN, width, height);
+        project_node(node, OTHER, width, height);
+
+        context.beginPath();
+        context.moveTo(SCREEN[0], SCREEN[1]);
+        context.lineTo(OTHER[0], OTHER[1]);
+        context.stroke();
+    }
+
+    context.fillStyle = '#9db8ff';
+
+    for (const node of scene.joint) {
+        project_node(node, SCREEN, width, height);
+
+        context.beginPath();
+        context.arc(SCREEN[0], SCREEN[1], Math.max(1.5, width / 700), 0, Math.PI * 2);
+        context.fill();
+    }
+
+    context.restore();
+}
+
+/**
+ * Each joint's reconstructed orientation, as an axis triple. A particle has no
+ * orientation, so this is §11.1's swing — the minimal rotation from the link's
+ * bind direction to its simulated one, and the reason the rig path can write a
+ * `transform_local` at all.
+ */
+function draw_frames(width, height) {
+    const axes = [
+        ['#e5533d', 1, 0, 0],
+        ['#5ad19a', 0, 1, 0],
+        ['#6b8afd', 0, 0, 1]
+    ];
+
+    const length = control.spacing * 0.4;
+
+    context.save();
+    context.lineWidth = 1;
+
+    for (const node of scene.joint) {
+        const t = node.transform_global;
+
+        project(SCREEN, camera, t.translation[0], t.translation[1], t.translation[2], width, height);
+
+        for (const [colour, x, y, z] of axes) {
+            const qx = t.rotation[0];
+            const qy = t.rotation[1];
+            const qz = t.rotation[2];
+            const qw = t.rotation[3];
+
+            const tx = 2 * (qy * z - qz * y);
+            const ty = 2 * (qz * x - qx * z);
+            const tz = 2 * (qx * y - qy * x);
+
+            const dx = x + qw * tx + (qy * tz - qz * ty);
+            const dy = y + qw * ty + (qz * tx - qx * tz);
+            const dz = z + qw * tz + (qx * ty - qy * tx);
+
+            project(
+                OTHER, camera,
+                t.translation[0] + dx * length,
+                t.translation[1] + dy * length,
+                t.translation[2] + dz * length,
+                width, height
+            );
+
+            context.strokeStyle = colour;
+            context.beginPath();
+            context.moveTo(SCREEN[0], SCREEN[1]);
+            context.lineTo(OTHER[0], OTHER[1]);
+            context.stroke();
+        }
+    }
+
+    context.restore();
+}
+
+// ---------------------------------------------------------------- readout
+
+function refresh_readout() {
+    if (scene === null) {
+        return;
+    }
+
+    const instance = scene.cloth.instanceOf(scene.entity);
+
+    if (instance === undefined || !instance.seeded) {
+        return;
+    }
+
+    const state = instance.state;
+
+    element('r_joints').textContent = String(scene.proxy.joint_count);
+    element('r_particles').textContent = String(state.particle_count);
+    element('r_rows').textContent = `${state.stretch_count} / ${state.leash_count}`;
+    element('r_contacts').textContent = String(instance.contact_count);
+    element('r_self').textContent = String(instance.self_pairs);
+    element('r_step').textContent = `${step_ms.toFixed(3)} ms`;
+
+    let worst = 0;
+
+    const anchor = instance.particle_of_node[0] * 3;
+
+    for (let node = 1; node < instance.node_count; node++) {
+        const p = instance.particle_of_node[node] * 3;
+
+        const distance = Math.hypot(
+            state.position[p] - state.position[anchor],
+            state.position[p + 1] - state.position[anchor + 1],
+            state.position[p + 2] - state.position[anchor + 2]
+        );
+
+        const ratio = distance / instance.geodesic[node];
+
+        if (ratio > worst) {
+            worst = ratio;
+        }
+    }
+
+    const reach = element('r_reach');
+
+    reach.textContent = worst.toFixed(4);
+    reach.className = worst > 1.05 ? 'bad' : 'good';
+}
+
+// ------------------------------------------------------------------ frame
+
+function frame() {
+    if (control.running) {
+        step_once();
+    }
+
+    draw();
+    refresh_readout();
+
+    requestAnimationFrame(frame);
+}
+
+// --------------------------------------------------------------- controls
+
+const preset_select = element('preset');
+
+for (const entry of GARMENT_PRESETS) {
+    const option = document.createElement('option');
+
+    option.value = entry.id;
+    option.textContent = entry.label;
+
+    preset_select.append(option);
+}
+
+preset_select.value = control.preset;
+
+preset_select.addEventListener('change', () => {
+    control.preset = preset_select.value;
+
+    const entry = GARMENT_PRESETS.find(p => p.id === control.preset);
+
+    control.links = entry.links;
+    control.dynamics = entry.dynamics;
+
+    element('links').value = String(control.links);
+    element('links_out').textContent = String(control.links);
+    element('dynamics').value = control.dynamics;
+
+    rebuild();
+});
+
+const dynamics_select = element('dynamics');
+
+for (const name of Object.keys(CLOTH_DYNAMICS_BY_NAME)) {
+    const option = document.createElement('option');
+
+    option.value = name;
+    option.textContent = name.toLowerCase();
+
+    dynamics_select.append(option);
+}
+
+dynamics_select.value = control.dynamics;
+
+dynamics_select.addEventListener('change', () => {
+    control.dynamics = dynamics_select.value;
+
+    rebuild();
+});
+
+/**
+ * @param {string} id
+ * @param {string} key
+ * @param {function(number): string} format
+ * @param {boolean} rebuilds
+ */
+function slider(id, key, format, rebuilds) {
+    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();
+        }
+    });
+}
+
+slider('links', 'links', (v) => String(v), true);
+slider('spacing', 'spacing', (v) => `${(v * 100).toFixed(1)} cm`, true);
+slider('blend', 'blend', (v) => v.toFixed(2), false);
+
+for (const motion of ['still', 'walk', 'turn', 'sprint']) {
+    element(`motion_${motion}`).addEventListener('click', () => {
+        control.motion = motion;
+
+        for (const other of ['still', 'walk', 'turn', 'sprint']) {
+            element(`motion_${other}`).classList.toggle('on', other === motion);
+        }
+    });
+}
+
+element('collide').addEventListener('click', (event) => {
+    control.collide = !control.collide;
+
+    event.target.classList.toggle('on', control.collide);
+
+    rebuild();
+});
+
+element('self_collision').addEventListener('click', (event) => {
+    control.self_collision = !control.self_collision;
+
+    event.target.classList.toggle('on', control.self_collision);
+
+    rebuild();
+});
+
+for (const [id, key] of [['view_bind', 'bind'], ['view_frames', 'frames'], ['view_body', 'body']]) {
+    element(id).addEventListener('click', (event) => {
+        control[key] = !control[key];
+
+        event.target.classList.toggle('on', control[key]);
+    });
+}
+
+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);
+
+// ----------------------------------------------------------------- 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.3, 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();
+
+const ready = rebuild();
+
+requestAnimationFrame(frame);
+
+// A handle for a driver script. `rebuild` returns a promise, because
+// `EntityManager#startup` does and an entity created before it resolves is
+// never linked.
+globalThis.cloth_garment_playground = {
+    control,
+    camera,
+    ready,
+    rebuild,
+    step_once,
+    draw,
+    get scene() { return scene; }
+};