@woosh/meep-engine 3.14.3 → 3.14.5

package/src/shade/playground/skinned_mesh_soup/main.js

@@ -0,0 +1,567 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import ConcurrentExecutor from "../../../core/process/executor/ConcurrentExecutor.js";
+import { AssetManager } from "../../../engine/asset/AssetManager.js";
+import { GameAssetType } from "../../../engine/asset/GameAssetType.js";
+import { ArrayBufferLoader } from "../../../engine/asset/loaders/ArrayBufferLoader.js";
+import {
+    GLTFSceneBundleAssetLoader
+} from "../../../engine/asset/loaders/GLTFSceneBundleAssetLoader.js";
+import { ImageBitmapAssetLoader } from "../../../engine/asset/loaders/image/ImageBitmapAssetLoader.js";
+import { load_model_scene_bundle } from "../../../engine/asset/load_model_scene_bundle.js";
+import { instantiate_scene_bundle } from "../../../engine/graphics3/instantiate_scene_bundle.js";
+import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
+import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Node3D } from "../../renderer/scene/Node3D.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+
+/**
+ * A skinned character, loaded the way the game loads one, with the pieces that could be making soup
+ * put on switches.
+ *
+ * ## Why this page exists next to `skinned_blas_refit`
+ *
+ * That page renders the same character and answers a sharp question about the BLAS — does the tree
+ * follow the mesh — with `verify()`. It answers that question *numerically*, by holding the tree's
+ * root box against the bounds chain's box over the same deformed vertices, and both of those are
+ * derived from the clone's vertex region. **Vertices that are wrong in the same way agree with each
+ * other perfectly.** So a refit can be correct, `verify()` green, every internal node exactly its
+ * children's union — and the picture still soup, because the thing the tree faithfully bounds is
+ * itself wrong.
+ *
+ * This page is that other question, and it is built to bisect it rather than to look good:
+ *
+ * - **`?skin=off`** — no skin registered. A {@link SkinnedMesh} still gets a vertex clone (see
+ *   {@link GPUMeshSkinningContext#obtain_geometry_index}), but nothing ever deforms it, so what is
+ *   drawn is the memcpy of the source: the rest pose, under the mesh node's own transform. For a
+ *   Mixamo character that transform carries the file's centimetre scale and its up-axis rotation,
+ *   so a *correct* result here is a 1.7 cm figure lying on its side. Soup here is the geometry
+ *   upload — the meshlet copy or its address patch — and has nothing to do with skinning.
+ * - **`?skin=bind`** — the skin registered, no clip. The skinning pass runs every frame over a pose
+ *   that never changes, and the answer it should write is one the CPU knows exactly. `diagnose()`
+ *   in the console reads the clone's vertices back and says which of them are wrong and in what
+ *   pattern — see {@link verify_clone_vertices}. Soup here is the skinning machinery.
+ * - **`?skin=animated`** — the dance, as `skinned_blas_refit` runs it. Soup only here is the pose:
+ *   the joint matrices, their range, or the order the skin's joints were resolved in.
+ *
+ * ## What the bisect found, and what was done
+ *
+ * `chunk_skin_blend_mesh_local` folds `inverse(mesh.transform_global)` into each joint matrix and
+ * converts the product to a dual quaternion, which can only carry a rigid motion. Michelle's
+ * positions and inverse-bind matrices are authored in the already-scaled space, so
+ * `joint.global × inverse_bind` is the *identity* and the fold was a bare 100×.
+ * `dual_quat_from_m4` reads `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms of `1 + 100·(…)`, clamps
+ * whichever go negative and normalizes the rest, so the rotation it extracted was wrong — and wrong
+ * differently per joint, which is what tore the mesh apart. `?skin=bind` was the right character at
+ * 1/100 size (one shared matrix, one shared error) and `?skin=animated` was soup.
+ *
+ * The frame is now the engine's rather than the asset's: `register_skin` puts each skinned mesh on
+ * its skin's own bind transform, so the fold is the identity at bind and a rigid displacement under
+ * a clip, for every shape a glTF file arrives in. See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * All of which was established without a device — `__soup_blend_probe.spec.js` runs the shader's own
+ * blend over this character's own matrices, and the emulator tier in
+ * `chunk_skin_blend_mesh_local.spec.js` runs the real WGSL over both shapes. This page is where that
+ * is confirmed against pixels, which by then is a formality.
+ *
+ * ## Why through the asset framework
+ *
+ * `skinned_blas_refit` calls `load_gltf` directly and parses the file once per character.
+ * {@link GLTFSceneBundleAssetLoader} is what the game and the editor register, and it hands **the
+ * same bundle** to every caller — so a second character is not a second parse, it is
+ * {@link instantiate_scene_bundle}: its own node tree, its own skins bound to that tree's joints,
+ * its own clips retargeted onto it, sharing the geometry and the inverse-bind matrices. That is a
+ * materially different path into the renderer, and running the repro on it means a fix found here
+ * is a fix for the engine rather than for one prototype page.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Served by the dev server out of `test_assets/`, which is gitignored and unpublished. See
+ * `test_assets/README.md`.
+ *
+ * @type {string}
+ */
+const CHARACTER_URL = '/test_assets/Michelle.glb';
+
+/**
+ * How far apart characters stand, in character heights.
+ *
+ * @type {number}
+ */
+const SPACING = 1.1;
+
+/**
+ * How the skin is driven. The page's whole point is that these are three different questions.
+ *
+ * @enum {string}
+ */
+const SkinMode = {
+    /** no skin registered — the clone is never deformed */
+    Off: 'off',
+    /** skin registered, no clip — the pose the CPU can predict */
+    Bind: 'bind',
+    /** skin registered, the file's dance bound and playing */
+    Animated: 'animated',
+};
+
+/**
+ * The manager a model load needs, registered the way the game's graphics profile registers it.
+ *
+ * Not {@link make_playground_asset_manager}: that one is the two-loader subset `load_gltf` needs
+ * when a page calls it by hand. Going through {@link load_model_scene_bundle} means the *model* is
+ * an asset too, which is the thing this page wants to be on.
+ *
+ * @returns {Promise<AssetManager>}
+ */
+async function make_asset_manager() {
+    const manager = new AssetManager({
+        context: {},
+        executor: new ConcurrentExecutor(),
+    });
+
+    // One instance for both glTF types, as `addModelLoaders` does — the loader holds no per-type
+    // state, and the two types are `.glb` and `.gltf` telling themselves apart.
+    const models = new GLTFSceneBundleAssetLoader();
+
+    await manager.registerLoader(GameAssetType.ModelGLTF, models);
+    await manager.registerLoader(GameAssetType.ModelGLTF_JSON, models);
+
+    // the container's `.bin` buffers, and its images — `load_gltf` asks for both back through the
+    // manager rather than fetching them itself
+    await manager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
+    await manager.registerLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());
+
+    manager.startup();
+
+    return manager;
+}
+
+/**
+ * Where the `index`-th of `count` characters stands: a square-ish grid centred on the origin.
+ *
+ * @param {number} index
+ * @param {number} count
+ * @param {number} spacing
+ * @returns {{x: number, z: number}}
+ */
+function grid_position(index, count, spacing) {
+    const columns = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / columns);
+
+    return {
+        x: ((index % columns) - (columns - 1) / 2) * spacing,
+        z: (Math.floor(index / columns) - (rows - 1) / 2) * spacing,
+    };
+}
+
+/**
+ * Stand one instantiated character at `(x, 0, z)`.
+ *
+ * The offset goes on a fresh parent above the model's own roots, and on that parent's **local**
+ * transform. Both halves of that matter and neither is obvious; `place_character` in
+ * `skinned_blas_refit` carries the full argument, which is worth reading once. The short form: a
+ * skinned mesh's own node transform cancels exactly out of the vertex the renderer draws, so a
+ * skinned character is placed by its *joints* and only an ancestor the joints actually sit under
+ * moves them — and `transform_global` is derived, so a placement written there is discarded by the
+ * next walk that recomputes it.
+ *
+ * @param {Scene} scene
+ * @param {Node3D[]} roots the instance's roots, not yet parented
+ * @param {number} x
+ * @param {number} z
+ * @returns {Node3D} the placement node
+ */
+function place_roots(scene, roots, x, z) {
+    const placement = new Node3D();
+
+    placement.name = `placement(${x}, ${z})`;
+
+    // `Transform64` keeps its matrix by hand: the write is only real after `updateMatrix`.
+    placement.transform_local.setTranslation(x, 0, z);
+    placement.transform_local.updateMatrix();
+
+    placement.addChildren(roots);
+
+    placement.updateMatrices();
+
+    // `updateMatrices` walks pre-order and a glTF character's joint root is the mesh node's
+    // sibling, so the bounds a SkinnedMesh refreshes mid-walk read joints the walk has not reached.
+    // This second pass reads a settled skeleton.
+    placement.traverse(node => {
+        if (node.isMesh === true) {
+            node.updateBoundsBasic();
+        }
+    });
+
+    scene.add(placement);
+
+    return placement;
+}
+
+/**
+ * Every {@link SkinnedMesh} an instance's skins deform.
+ *
+ * Off the skins rather than by walking the roots: a skin already lists exactly the meshes that bind
+ * to it, which is what `register_skin` uses.
+ *
+ * @param {SceneBundleInstance} instance
+ * @returns {SkinnedMesh[]}
+ */
+function skinned_meshes_of(instance) {
+    const meshes = new Set();
+
+    for (const skin of instance.skins) {
+        for (const mesh of skin.meshes) {
+            meshes.add(mesh);
+        }
+    }
+
+    return [...meshes];
+}
+
+/**
+ * The world-space box the renderer culls and traces this mesh by — the `meshes` table row, which
+ * the skinning pass's bounds-refresh chain rewrites every frame from the vertices it just moved.
+ *
+ * Not `mesh.bounding_box`: that is the CPU box of the *source* geometry under the mesh transform,
+ * and for a character whose node carries a centimetre scale it is a box a couple of centimetres
+ * across. Framing a camera on that puts the camera inside the character.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {Mesh} mesh
+ * @returns {Promise<{low: Vector3, high: Vector3}>}
+ */
+async function world_bounds_of(scene_context, mesh) {
+    const row = scene_context.mesh_row_of(mesh);
+
+    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+
+    const box = record.bounding_box;
+
+    return {
+        low: new Vector3(box[0], box[1], box[2]),
+        high: new Vector3(box[3], box[4], box[5]),
+    };
+}
+
+/**
+ * Stand the page up.
+ *
+ * @returns {Promise<void>}
+ */
+export async function start() {
+
+    const element = id => document.getElementById(id);
+
+    const status_element = element('status');
+    const stats_element = element('stats');
+
+    /**
+     * @param {string} text
+     * @param {string} [kind]
+     */
+    function set_status(text, kind = '') {
+        status_element.textContent = text;
+        status_element.className = kind;
+    }
+
+    const canvas = element('view');
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        set_status(
+            'no WebGPU context — this browser has none, or the page is not a secure context',
+            'fail'
+        );
+        return;
+    }
+
+    // ---- what the url asks for ------------------------------------------------------------------
+
+    const parameters = new URLSearchParams(location.search);
+
+    const count = Math.min(64, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
+
+    const skin_mode = Object.values(SkinMode).includes(parameters.get('skin'))
+        ? parameters.get('skin')
+        : SkinMode.Animated;
+
+    const tracing = parameters.get('trace') === '1';
+
+    element('character_count').value = String(count);
+    element('skin_mode').value = skin_mode;
+    element('path_tracing').checked = tracing;
+
+    // A Scene has no teardown, so changing any of these reloads the page rather than emptying one
+    // in place. Every switch is in the url for the same reason a repro is a url: it can be sent.
+    function reload_with(changes) {
+        const next = new URLSearchParams(location.search);
+
+        for (const [key, value] of Object.entries(changes)) {
+            next.set(key, value);
+        }
+
+        location.search = next.toString();
+    }
+
+    element('respawn').addEventListener('click', () => reload_with({
+        count: element('character_count').value,
+        skin: element('skin_mode').value,
+    }));
+
+    element('skin_mode').addEventListener('change', () => reload_with({
+        skin: element('skin_mode').value,
+    }));
+
+    // ---- the renderer ---------------------------------------------------------------------------
+
+    const renderer = new Renderer();
+
+    set_status('acquiring a device…');
+
+    await renderer.initialize({ context });
+
+    if (!renderer.graphics.device.features.has('subgroups')) {
+        set_status('device has no `subgroups`, which this engine takes as a baseline', 'warn');
+    }
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.01;
+    camera.far = 200;
+    camera.fov = 50 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element receives key events — body carries tabindex for exactly that.
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    // Rasterized by default. It is the simpler of the two readings — it reads the deformed vertices
+    // directly, with no tree in the way — so it is the one to establish the answer on first.
+    renderer.feature_path_tracing_enabled = tracing;
+    renderer.feature_taa_enabled = false;
+
+    element('path_tracing').addEventListener('change', event => {
+        renderer.feature_path_tracing_enabled = event.target.checked;
+        renderer.indicate_view_change();
+    });
+
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.controller = controller;
+
+    // ---- the cast -------------------------------------------------------------------------------
+
+    set_status(`loading ${CHARACTER_URL} …`);
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    /** @type {SkinnedMesh[]} */
+    const characters = [];
+
+    try {
+        const asset_manager = await make_asset_manager();
+
+        // One load, whatever the count: the asset hands out the model itself, and a placement's
+        // private copy is `instantiate_scene_bundle`.
+        const bundle = await load_model_scene_bundle(asset_manager, CHARACTER_URL);
+
+        const animations = scene_context.animation_manager;
+
+        for (let i = 0; i < count; i++) {
+            const instance = instantiate_scene_bundle(bundle);
+
+            const meshes = skinned_meshes_of(instance);
+
+            if (meshes.length === 0) {
+                throw new Error(`${CHARACTER_URL} has no skinned mesh`);
+            }
+
+            const { x, z } = grid_position(i, count, SPACING);
+
+            place_roots(scene, instance.roots, x, z);
+
+            if (skin_mode !== SkinMode.Off) {
+                for (const skin of instance.skins) {
+                    animations.register_skin(skin);
+                }
+            }
+
+            if (skin_mode === SkinMode.Animated) {
+                // One clip, looping, at full weight. The pose accumulator sums every *bound* clip
+                // whatever its weight, so binding the T-pose alongside the dance would blend the
+                // two — only what should play is registered.
+                const clip = instance.clips.find(candidate => /samba|dance/i.test(candidate.name ?? ''))
+                    ?? instance.clips[0];
+
+                if (clip !== undefined) {
+                    const clip_id = animations.register_clip(clip);
+
+                    animations.set_playback_weight(clip_id, 1);
+                    animations.set_flags(clip_id, AnimationClipFlags.Loop);
+                    animations.start(clip_id);
+                }
+            }
+
+            characters.push(...meshes);
+        }
+    } catch (error) {
+        set_status(
+            `could not load the character (${error.message}). Put it under test_assets/ — `
+            + `see test_assets/README.md.`,
+            'fail'
+        );
+        console.error(error);
+        return;
+    }
+
+    if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
+        // a glTF character carries no light of its own
+        scene.lights.add(make_sunlight({ intensity: 6 }));
+    }
+
+    // ---- frames enough for the box to be worth framing on ----------------------------------------
+
+    set_status('first frames — uploading clones and their trees …');
+
+    for (let i = 0; i < 8; i++) {
+        renderer.render(camera, scene, 1 / 60);
+
+        await renderer.graphics.device.queue.onSubmittedWorkDone();
+    }
+
+    let low = null;
+    let high = null;
+
+    for (const character of characters) {
+        const bounds = await world_bounds_of(scene_context, character);
+
+        low = low === null ? bounds.low : new Vector3(
+            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
+        );
+
+        high = high === null ? bounds.high : new Vector3(
+            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
+        );
+    }
+
+    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
+
+    const radius = Math.hypot(span.x, span.y, span.z) * 0.5;
+
+    camera_frame_sphere(
+        controller,
+        radius,
+        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
+    );
+
+    controller.movement_speed_scale = radius * 0.2;
+
+    camera.near = radius * 0.01;
+    camera.far = radius * 400;
+
+    console.log(
+        `published box: low=(${low.x.toFixed(4)}, ${low.y.toFixed(4)}, ${low.z.toFixed(4)}) `
+        + `high=(${high.x.toFixed(4)}, ${high.y.toFixed(4)}, ${high.z.toFixed(4)}) — `
+        + `span ${span.x.toFixed(4)} × ${span.y.toFixed(4)} × ${span.z.toFixed(4)} m`
+    );
+
+    load_default_environment(scene).then(applied => {
+        if (applied) {
+            renderer.indicate_view_change();
+        }
+    });
+
+    // the controller's keyboard device listens on body, and only a focused element gets key events
+    document.body.focus();
+
+    globalThis.characters = characters;
+
+    // ---- the console half ------------------------------------------------------------------------
+
+    let animating = skin_mode === SkinMode.Animated;
+
+    /**
+     * The clone's deformed vertices, against the answer the CPU knows for the bind pose.
+     *
+     * Only meaningful under `?skin=bind`: with a clip playing there is no CPU-side answer to compare
+     * against, and with no skin registered there is nothing deforming the clone. It runs in the
+     * other two modes anyway rather than refusing — under `?skin=off` a pass says the clone's copy
+     * and address patch are right, which is worth knowing on its own.
+     */
+    globalThis.diagnose = async () => {
+        const { verify_clone_vertices } = await import('./verify_clone_vertices.js');
+
+        const was_animating = animating;
+
+        animating = false;
+
+        try {
+            return await verify_clone_vertices({ renderer, scene, mesh: characters[0] });
+        } finally {
+            animating = was_animating;
+        }
+    };
+
+    set_status(
+        `loaded — ${count} × ${CHARACTER_URL}, skin=${skin_mode}. `
+        + `\`await diagnose()\` in the console.`,
+        'pass'
+    );
+
+    renderer.indicate_view_change();
+
+    // ---- frame loop --------------------------------------------------------------------------
+
+    element('animation').disabled = skin_mode !== SkinMode.Animated;
+
+    if (skin_mode !== SkinMode.Animated) {
+        // there is no clip to freeze; saying so beats a live-looking button that does nothing
+        element('animation').textContent = 'No clip playing';
+    }
+
+    element('animation').addEventListener('click', () => {
+        animating = !animating;
+
+        element('animation').textContent = animating ? 'Freeze pose' : 'Resume dance';
+
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    });
+
+    const FRAME_RATE_LIMIT = 60;
+
+    create_frame_loop(time_delta_s => {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+
+        // A frozen pose is a still scene, which is the only condition under which the tracer's
+        // accumulator converges — so time stops rather than the frame loop stopping.
+        renderer.render(camera, scene, animating ? time_delta_s : 0);
+
+        stats_element.textContent =
+            `${count} × skin=${skin_mode}`
+            + `${renderer.feature_path_tracing_enabled ? '  ·  path traced' : '  ·  rasterized'}`;
+    }, FRAME_RATE_LIMIT);
+}

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The clone's deformed vertices, against `inverse(mesh.global) × rest`.
+ *
+ * Reads the GPU's own answer to "where does this geometry id's data live" rather than reconstructing
+ * it from the host records: the geometry metadata row, then the clone's meshlet metadata rows, then
+ * the data those rows address. That is the same chain the rasterizer and the intersector walk, so a
+ * clone whose *addressing* is wrong is caught here rather than being read around.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh
+ * @param {number} [options.tolerance] in mesh-local units. Since `register_skin` puts the mesh on
+ *        the skin's bind transform, mesh-local *is* world scale — a metre is a metre here, and at
+ *        bind the clone should hold the source's own positions. `1e-4` is f32 headroom over a
+ *        chain — a matrix product, a quaternion conversion and a screw motion, all at single
+ *        precision — against a smallest real violation of `1.6`, so there are four orders between
+ *        the two. It was `5e-3` while `dual_quat_from_m4` amplified a near-identity matrix's error
+ *        by its square root; `SKINNING_FRAME_PLAN.md` §9 took that out, and the same measurement on
+ *        the CPU now reads zero at bind.
+ * @returns {Promise<object>}
+ */
+export function verify_clone_vertices({ renderer, scene, mesh, tolerance }: {
+    renderer: Renderer;
+    scene: Scene;
+    mesh: SkinnedMesh;
+    tolerance?: number;
+}): Promise<object>;
+//# sourceMappingURL=verify_clone_vertices.d.ts.map

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_clone_vertices.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js"],"names":[],"mappings":"AAyJA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAb6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IAQJ,QAAQ,MAAM,CAAC,CA8P3B"}