@woosh/meep-engine 3.1.0 → 3.2.0

package/src/shade/playground/gltf_skinned_prototype.js

@@ -1,560 +1,560 @@
-import Vector3 from "../../core/geom/Vector3.js";
-import { Transform } from "../../engine/ecs/transform/Transform.js";
-import { AnimationClipFlags } from "../renderer/animation/AnimationClipFlags.js";
-import { ShadeAnimationChannel } from "../renderer/animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../renderer/animation/ShadeAnimationClip.js";
-import { BoxGeometry, PlaneGeometry } from "../renderer/geometry/BoxGeometry.js";
-import { make_sunlight } from "../renderer/light/make_sunlight.js";
-import { load_default_environment } from "./load_default_environment.js";
-import { load_gltf } from "../renderer/loader/gltf/load_gltf.js";
-import { ShadeDrawSide } from "../renderer/material/ShadeDrawSide.js";
-import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
-import { Node3D } from "../renderer/scene/Node3D.js";
-
-/**
- * Diagnostic toggles. With both `false`, the SkinnedMesh routes
- * through a geometry clone whose vertices stay at the source's
- * bind-pose values (since no skinning binding is registered) — so we
- * can see whether the mesh shows up at all before animation logic
- * enters the picture.
- *
- *   ENABLE_SKIN_REGISTRATION = false: skip register_skin, mesh stays
- *       unbound in the skinning context, clone shows bind pose only.
- *   ENABLE_CLIP_PLAYBACK = false: register skin but don't register
- *       or start clips; joints sit at initial TRS, skin matrices
- *       resolve to bind-pose identities, mesh appears in bind pose
- *       with active skinning math.
- *
- * Run order during diagnosis: (false, false) → mesh visible? If yes,
- * geometry/clone routing works. (true, false) → mesh still visible?
- * If yes, skin matrix prep works. (true, true) → animated pose.
- */
-const ENABLE_SKIN_REGISTRATION = true;
-const ENABLE_CLIP_PLAYBACK = true;
-
-/**
- * Build a "skeleton only" visualization of a skin: clone the joint
- * hierarchy as a fresh set of Node3Ds, attach a small cube mesh to
- * each cloned joint, and produce a parallel {@link ShadeAnimationClip}
- * whose channels target the *clones* instead of the originals (so
- * registering and starting it drives the cube hierarchy in lockstep
- * with the source clip on the original skin).
- *
- * The point is to isolate skinning from animation: if the skinned
- * dancer glitches but the cube-skeleton next to it stays smooth,
- * the bug is in the skinning chain; if both glitch in lockstep, the
- * bug is in the animation chain (apply / propagate / clip state).
- *
- * The cloned hierarchy preserves the original parent chain among
- * joint↔joint edges. The topmost joint(s) — whose original parent
- * isn't itself in the skin — get reparented to a fresh wrapper that
- * mirrors that original parent's local transform (so e.g. Mixamo's
- * "Character" 0.01 scale + axis rotation is reproduced on the
- * clone hierarchy). The wrapper is then placed at `offset` so the
- * visualization renders next to the original.
- *
- * @param {{
- *     skin: Skin,
- *     clip: ShadeAnimationClip,
- *     cube_size_local: number,
- *     cube_material: ShadeMaterial,
- *     offset: Vector3,
- * }} args
- * @returns {{ root: Node3D, clip: ShadeAnimationClip }}
- */
-function build_skeleton_visualization({
-    skin,
-    clip,
-    cube_size_local,
-    cube_material,
-    offset,
-}) {
-    const old_joints = skin.joints;
-
-    // Find the joint hierarchy's topmost parent (e.g. Mixamo's
-    // "Character") — the first parent that isn't itself one of the
-    // skin's joints. This is the node whose transform sets the
-    // skeleton's overall scale + orientation.
-    let outer_parent = null;
-    for (let i = 0; i < old_joints.length; i++) {
-        const j = old_joints[i];
-        if (j.parent !== null && old_joints.indexOf(j.parent) === -1) {
-            outer_parent = j.parent;
-            break;
-        }
-    }
-
-    // Clone each joint as a bare Node3D with the same local TRS.
-    // A Map<original, clone> lets us re-wire parent pointers below.
-    const old_to_new = new Map();
-    const new_joints = new Array(old_joints.length);
-    for (let i = 0; i < old_joints.length; i++) {
-        const original = old_joints[i];
-        const clone = new Node3D();
-        clone.name = `${original.name}_skel`;
-        clone.transform_local.copy(original.transform_local);
-        old_to_new.set(original, clone);
-        new_joints[i] = clone;
-    }
-
-    // Wrapper that mirrors the original outer parent's local transform
-    // — keeps the cm→m scale and any axis rotation intact so the
-    // clone hierarchy ends up at the right size / orientation.
-    const outer_clone = new Node3D();
-    outer_clone.name = "Character_skel";
-    if (outer_parent !== null) {
-        outer_clone.transform_local.copy(outer_parent.transform_local);
-    }
-
-    // Re-wire the cloned hierarchy. Joints whose original parent is
-    // also a joint get parented to the matching clone. Joints whose
-    // original parent is the outer_parent get parented to outer_clone.
-    for (let i = 0; i < old_joints.length; i++) {
-        const original = old_joints[i];
-        const clone = new_joints[i];
-        const parent_clone = old_to_new.get(original.parent);
-        if (parent_clone !== undefined) {
-            parent_clone.addChild(clone);
-        } else {
-            outer_clone.addChild(clone);
-        }
-    }
-
-    // Shared cube geometry — built once, reused across all bones.
-    if (SKELETON_CUBE_GEOMETRY === null) {
-        SKELETON_CUBE_GEOMETRY = new BoxGeometry(1, 1, 1);
-        SKELETON_CUBE_GEOMETRY.name = "SkeletonBoneCube";
-    }
-
-    // Attach a small cube to each cloned joint as a child. The cube's
-    // local size is scaled up to compensate for the outer wrapper's
-    // small scale (e.g. Mixamo's 0.01) — the multiplication leaves a
-    // sensible world-space size.
-    for (let i = 0; i < new_joints.length; i++) {
-        const cube = new Mesh();
-        cube.geometry = SKELETON_CUBE_GEOMETRY;
-        cube.material = cube_material;
-        cube.name = `${old_joints[i].name}_bone_cube`;
-        cube.transform_local.setScale(cube_size_local, cube_size_local, cube_size_local);
-        new_joints[i].addChild(cube);
-    }
-
-    // Final root carries the comparison offset. Putting it on the
-    // root (rather than baking into outer_clone) keeps outer_clone
-    // a faithful copy of the original parent's transform.
-    const root = new Node3D();
-    root.name = "skeleton_visualization_root";
-    root.transform_local.setTranslation(offset.x, offset.y, offset.z);
-    root.addChild(outer_clone);
-
-    // Build the parallel clip — same curves, channels retargeted to
-    // the cloned joints. Curves can be shared across the two clips
-    // (`register_clip` uploads them independently and the GPU side
-    // doesn't care about identity), so no need to deep-clone the
-    // AnimationCurve instances.
-    const new_channels = [];
-    for (let c = 0; c < clip.channels.length; c++) {
-        const ch = clip.channels[c];
-        const new_target = old_to_new.get(ch.target);
-        if (new_target === undefined) continue;
-        new_channels.push(ShadeAnimationChannel.from({
-            target: new_target,
-            property: ch.property,
-            curves: ch.curves,
-        }));
-    }
-
-    const skel_clip = ShadeAnimationClip.from({
-        name: `${clip.name}_skeleton`,
-        channels: new_channels,
-    });
-
-    return { root, clip: skel_clip };
-}
-
-/**
- * Shared cube geometry for skeleton-bone visualizations. Lazily
- * built on first {@link build_skeleton_visualization} call.
- *
- * @type {BoxGeometry|null}
- */
-let SKELETON_CUBE_GEOMETRY = null;
-
-/**
- * GPU-driven skinning end-to-end demo. Loads a skinned glTF asset
- * (Michelle, the dancing model — the three.js community's go-to
- * skinning test rig), registers the resulting {@link Skin} and
- * {@link ShadeAnimationClip} via {@link GPUAnimationManager}'s
- * high-level API, and lets the GPU drive playback through
- * {@link shader_animation_tick}.
- *
- * Per-frame work in the host is intentionally minimal once setup is
- * done: push the current `dt` into a transient uniform, dispatch the
- * tick / apply / skin-matrix-prep / skinning-apply chain, done. CPU
- * doesn't write `clip.time` after `start()` returns.
- *
- * Expects `public/Michelle.glb` to exist (Michelle is the rigged
- * three.js sample dancer). Add it to `public/` before running.
- *
- * @param {object} args
- * @param {Renderer} args.renderer
- * @param {Scene} args.scene
- * @param {OrbitalCameraController} args.controller
- */
-export function gltf_skinned_prototype({ renderer, scene, controller }) {
-
-    // ── Lighting & environment ──────────────────────────────────
-    scene.lights.add(make_sunlight({
-        intensity: 3,
-        direction: new Vector3(-0.4, -1, -0.3),
-    }));
-
-    load_default_environment(scene);
-
-    // ── Ground plane ────────────────────────────────────────────
-    const plane_material = new StandardShadeMaterial();
-    plane_material.diffuse_color.parse("#b5b5b5");
-    plane_material.roughness_factor = 1;
-    plane_material.metallic_factor = 0;
-
-    const plane_transform = Transform.fromJSON({ position: { x: 0, y: 0, z: 0 } });
-    plane_transform.lookAt(Vector3.up);
-
-    const plane = Mesh.from(
-        new PlaneGeometry(20, 20, 1, 1),
-        plane_material,
-        plane_transform.matrix,
-    );
-    plane.name = "Ground";
-    scene.add(plane);
-
-    // ── Camera framing for Michelle ─────────────────────────────
-    // Michelle is roughly 1.7m tall, standing on Y=0. Camera framed
-    // to catch the whole dancer with a bit of headroom.
-    {
-        const camera_position = new Vector3(2.5, 1.4, 3.5);
-        const look_at = new Vector3(0, 1.0, 0);
-        controller.look(camera_position, look_at);
-        controller.camera.near = 0.05;
-        controller.camera.far = 50;
-    }
-
-    const gpu_scene = renderer.scenes.obtain(scene);
-    const animation_manager = gpu_scene.animation_manager;
-
-    /**
-     * Set by the load promise; consumed in the next per-frame hook
-     * to wire the asset into the scene + animation manager.
-     *
-     * @type {SceneBundle|null}
-     */
-    let pending_bundle = null;
-    let setup_complete = false;
-    /** @type {number[]} */
-    const registered_clip_ids = [];
-
-    // Kick off load. The promise resolves to a SceneBundle — we
-    // can't add it to the scene until the renderer's frame loop is
-    // running (Scene.add invalidates the GPU scene; that's fine, but
-    // we want to make sure we're in the same async tick as the
-    // per-frame callback, not the bootstrap path).
-    load_gltf('public/Michelle.glb').then(bundle => {
-        pending_bundle = bundle;
-        console.log(
-            `[gltf-skinning] loaded Michelle: ${bundle.scenes.length} scene(s), ` +
-            `${bundle.skins.length} skin(s), ${bundle.clips.length} clip(s)`
-        );
-    }).catch(e => {
-        console.error("[gltf-skinning] failed to load Michelle.glb", e);
-    });
-
-    // For debugging from the console.
-    window.animation_manager = animation_manager;
-    window.gpu_scene = gpu_scene;
-
-    let dump_frame_counter = 0;
-    let dump_done = false;
-
-    /**
-     * Wait a few frames after setup completes so GPU writes have
-     * settled (transforms uploaded, clones flushed, first apply +
-     * skin-matrix-prep run if enabled), then read back the rows of
-     * interest from each table and log them. One-shot — fires once
-     * per session.
-     */
-    function dump_gpu_state() {
-        const skinned_mesh = pending_bundle.skins[0]?.meshes[0];
-        const skinned_node_row = skinned_mesh
-            ? gpu_scene.id_mapping.get(skinned_mesh.id)
-            : -1;
-        const static_copy_node_row = window.static_copy
-            ? gpu_scene.id_mapping.get(window.static_copy.id)
-            : -1;
-
-        const promises = [];
-
-        // SkinnedMesh's row in meshes (row 2 if Plane is 0/1 and
-        // SkinnedMesh is the second instance). Use id_mapping for
-        // the *node* row, but the *mesh* row is harder to look up
-        // — dump rows [0..5] to cover Plane + SkinnedMesh + static
-        // copy and any neighbours.
-        for (let i = 0; i < 6; i++) {
-            promises.push(
-                gpu_scene.scene_database
-                    .debug_table_read_element('meshes', i)
-                    .then(r => ({ kind: 'mesh', row: i, record: r }))
-            );
-        }
-
-        if (skinned_node_row !== -1) {
-            promises.push(
-                gpu_scene.scene_database
-                    .debug_table_read_element('transforms', skinned_node_row)
-                    .then(r => ({ kind: 'transform-skinned', row: skinned_node_row, record: r }))
-            );
-        }
-        if (static_copy_node_row !== -1) {
-            promises.push(
-                gpu_scene.scene_database
-                    .debug_table_read_element('transforms', static_copy_node_row)
-                    .then(r => ({ kind: 'transform-static', row: static_copy_node_row, record: r }))
-            );
-        }
-
-        // Dump joint 0 of the skin (head of the joint chain — usually
-        // the hip/root) so we can sanity-check the global transform.
-        const first_joint = pending_bundle.skins[0]?.joints[0];
-        if (first_joint !== undefined) {
-            const joint_row = gpu_scene.id_mapping.get(first_joint.id);
-            if (joint_row !== undefined) {
-                promises.push(
-                    gpu_scene.scene_database
-                        .debug_table_read_element('transforms', joint_row)
-                        .then(r => ({ kind: 'transform-joint0', row: joint_row, record: r, joint_name: first_joint.name }))
-                );
-            }
-        }
-
-        // Animation tables — only meaningful when clips registered.
-        if (registered_clip_ids.length > 0) {
-            promises.push(
-                animation_manager.database
-                    .debug_table_read_element('animation_clips', registered_clip_ids[0])
-                    .then(r => ({ kind: 'clip', row: registered_clip_ids[0], record: r }))
-            );
-            promises.push(
-                animation_manager.database
-                    .debug_table_read_element('animation_skins', 0)
-                    .then(r => ({ kind: 'skin', row: 0, record: r }))
-            );
-        }
-
-        Promise.all(promises).then(results => {
-            console.group('[gltf-skinning] GPU state dump');
-            for (const r of results) {
-                console.log(r.kind, 'row=' + r.row, r.record);
-            }
-            console.groupEnd();
-        }).catch(e => {
-            console.error('[gltf-skinning] dump failed:', e);
-        });
-    }
-
-    renderer.onFrameFinished.add(() => {
-
-        // One-shot setup once the bundle has loaded. Eventual-
-        // consistency registration means we can scene.add + register
-        // in the same callback — the joint-block / bindings chains
-        // get patched in by animation_manager.update()'s drain pass
-        // once scene.build has populated id_mapping.
-        if (pending_bundle !== null && !setup_complete) {
-            const bundle = pending_bundle;
-
-            scene.add(bundle.scenes);
-
-            // Static side-by-side clone — same MeshletGeometry +
-            // material as the SkinnedMesh, but rendered as a regular
-            // Mesh with no skinning routing. If this one shows up but
-            // the SkinnedMesh doesn't, the bug is in the geometry
-            // clone / skinning context, not in geometry/material/
-            // transform shared with the source.
-            if (bundle.skins.length > 0 && bundle.skins[0].meshes.length > 0) {
-                const src = bundle.skins[0].meshes[0];
-                const static_copy = new Mesh();
-                static_copy.geometry = src.geometry;
-                static_copy.material = src.material;
-                static_copy.name = `${src.name}_static_copy`;
-                // Place 1.5m to the right of the skinned mesh so both
-                // are in frame.
-                static_copy.transform_local.setTranslation(1.5, 0, 0);
-                static_copy.updateMatrices();
-                scene.add(static_copy);
-                window.static_copy = static_copy;
-                console.log(
-                    `[gltf-skinning] added static (non-skinned) sibling at x=1.5 ` +
-                    `for comparison: name='${static_copy.name}'`
-                );
-            }
-
-            // Skeleton-only visualization — clones the joint
-            // hierarchy and attaches a cube per bone. Driven by a
-            // parallel clip registered immediately below.
-            let skel_clip_for_registration = null;
-            if (
-                ENABLE_CLIP_PLAYBACK
-                && bundle.skins.length > 0
-                && bundle.clips.length > 0
-            ) {
-                const main_clip = bundle.clips.find(c => c.duration > 0.1);
-                if (main_clip !== undefined) {
-                    // Plain opaque material with bright diffuse only —
-                    // no emissive_factor (which would route into the
-                    // emissive G-buffer slot and might engage a
-                    // different rasterization bucket than the static
-                    // copy / Michelle; rule that out by matching the
-                    // material shape).
-                    //
-                    // Force draw_side = Double so we can't be eaten
-                    // by backface culling if the BoxGeometry's winding
-                    // happens to face away from camera for whatever
-                    // reason (e.g. an inverted-handedness combine in
-                    // the joint chain producing negative-determinant
-                    // transforms).
-                    const cube_material = new StandardShadeMaterial();
-                    cube_material.diffuse_color.parse("#ffcc00");
-                    cube_material.roughness_factor = 0.6;
-                    cube_material.metallic_factor = 0;
-                    cube_material.draw_side = ShadeDrawSide.Double;
-
-                    const { root: skel_root, clip: skel_clip } =
-                        build_skeleton_visualization({
-                            skin: bundle.skins[0],
-                            clip: main_clip,
-                            // 15 units in joint-local space — after
-                            // the outer Mixamo 0.01 scale, ~15 cm in
-                            // world. Smaller than the prior 30 unit
-                            // value per visual feedback.
-                            cube_size_local: 15,
-                            cube_material,
-                            offset: new Vector3(-1.5, 0, 0),
-                        });
-
-                    // Walk the hierarchy to compose transform_global
-                    // and (importantly) compute mesh.bounding_box /
-                    // bounding_sphere via updateBoundsBasic on every
-                    // cube. Without this, the cubes' CPU bounds
-                    // default to zeros (Float32Array init), scene.build
-                    // uploads those zeros into the meshes_table, and
-                    // the camera-frustum sphere/AABB culler rejects
-                    // every cube — invisible in the main view even
-                    // though the shadow pass (which uses the light
-                    // volume sphere, not the mesh bounds) still
-                    // rasterizes them.
-                    skel_root.updateMatrices();
-
-                    scene.add(skel_root);
-                    skel_clip_for_registration = skel_clip;
-                    console.log(
-                        `[gltf-skinning] added skeleton-only viz at x=-1.5 ` +
-                        `(${skel_clip.channels.length} cloned channels)`
-                    );
-                }
-            }
-
-            // Diagnostic logging of the first skinned mesh.
-            if (bundle.skins.length > 0 && bundle.skins[0].meshes.length > 0) {
-                const m = bundle.skins[0].meshes[0];
-                const g = m.geometry;
-                console.log(
-                    `[gltf-skinning] first skinned mesh: name='${m.name}' ` +
-                    `parent='${m.parent?.name ?? '<none>'}'`
-                );
-                console.log(
-                    `[gltf-skinning]  geometry.bounding_box=`, g.bounding_box,
-                    ` sphere=`, g.bounding_sphere
-                );
-                console.log(
-                    `[gltf-skinning]  mesh.bounding_box=`, m.bounding_box,
-                    ` sphere=`, m.bounding_sphere
-                );
-                console.log(
-                    `[gltf-skinning]  mesh.transform_global.matrix=`,
-                    Array.from(m.transform_global.matrix)
-                );
-                console.log(
-                    `[gltf-skinning]  material draw_side=${m.material.draw_side} ` +
-                    `transparency_mode=${m.material.transparency_mode}`
-                );
-            }
-
-            if (ENABLE_SKIN_REGISTRATION) {
-                for (let i = 0; i < bundle.skins.length; i++) {
-                    const skin = bundle.skins[i];
-                    const skin_id = animation_manager.register_skin(skin);
-                    console.log(
-                        `[gltf-skinning] registered skin '${skin.name}' ` +
-                        `(id=${skin_id}, joints=${skin.joints.length}, meshes=${skin.meshes.length})`
-                    );
-                }
-            } else {
-                console.log('[gltf-skinning] SKIN REGISTRATION DISABLED — mesh stays unbound');
-            }
-
-            if (ENABLE_CLIP_PLAYBACK) {
-                // Drop near-zero-duration clips (rest poses) — they'd
-                // fight the real animation when both have Playing+Loop set.
-                const usable_clips = bundle.clips.filter(c => c.duration > 0.1);
-                console.log(
-                    `[gltf-skinning] selecting ${usable_clips.length}/${bundle.clips.length} ` +
-                    `clip(s) with duration > 0.1s`
-                );
-
-                for (let i = 0; i < usable_clips.length; i++) {
-                    const clip = usable_clips[i];
-                    const clip_id = animation_manager.register_clip(clip);
-
-                    animation_manager.set_flags(clip_id, AnimationClipFlags.Loop);
-                    animation_manager.start(clip_id);
-
-                    registered_clip_ids.push(clip_id);
-                    console.log(
-                        `[gltf-skinning] registered clip '${clip.name}' ` +
-                        `(id=${clip_id}, ${clip.channels.length} channels, ` +
-                        `duration=${clip.duration.toFixed(3)}s)`
-                    );
-                }
-
-                if (skel_clip_for_registration !== null) {
-                    const skel_clip_id = animation_manager.register_clip(skel_clip_for_registration);
-                    animation_manager.set_flags(skel_clip_id, AnimationClipFlags.Loop);
-                    animation_manager.start(skel_clip_id);
-                    registered_clip_ids.push(skel_clip_id);
-                    console.log(
-                        `[gltf-skinning] registered skeleton clip '${skel_clip_for_registration.name}' ` +
-                        `(id=${skel_clip_id}, ${skel_clip_for_registration.channels.length} channels)`
-                    );
-                }
-            } else {
-                console.log('[gltf-skinning] CLIP PLAYBACK DISABLED — joints stay at bind TRS');
-            }
-
-            setup_complete = true;
-        }
-
-        if (!setup_complete) {
-            return;
-        }
-
-        // One-shot GPU state dump a few frames into the stable
-        // regime. Wait for all the upload + first-frame passes to
-        // have settled before reading back.
-        if (!dump_done) {
-            dump_frame_counter++;
-            if (dump_frame_counter > 5) {
-                dump_done = true;
-                dump_gpu_state();
-            }
-        }
-    });
-}
+import Vector3 from "../../core/geom/Vector3.js";
+import { Transform } from "../../engine/ecs/transform/Transform.js";
+import { AnimationClipFlags } from "../renderer/animation/AnimationClipFlags.js";
+import { ShadeAnimationChannel } from "../renderer/animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../renderer/animation/ShadeAnimationClip.js";
+import { BoxGeometry, PlaneGeometry } from "../renderer/geometry/BoxGeometry.js";
+import { make_sunlight } from "../renderer/light/make_sunlight.js";
+import { load_default_environment } from "./load_default_environment.js";
+import { load_gltf } from "../renderer/loader/gltf/load_gltf.js";
+import { ShadeDrawSide } from "../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../renderer/scene/Mesh.js";
+import { Node3D } from "../renderer/scene/Node3D.js";
+
+/**
+ * Diagnostic toggles. With both `false`, the SkinnedMesh routes
+ * through a geometry clone whose vertices stay at the source's
+ * bind-pose values (since no skinning binding is registered) — so we
+ * can see whether the mesh shows up at all before animation logic
+ * enters the picture.
+ *
+ *   ENABLE_SKIN_REGISTRATION = false: skip register_skin, mesh stays
+ *       unbound in the skinning context, clone shows bind pose only.
+ *   ENABLE_CLIP_PLAYBACK = false: register skin but don't register
+ *       or start clips; joints sit at initial TRS, skin matrices
+ *       resolve to bind-pose identities, mesh appears in bind pose
+ *       with active skinning math.
+ *
+ * Run order during diagnosis: (false, false) → mesh visible? If yes,
+ * geometry/clone routing works. (true, false) → mesh still visible?
+ * If yes, skin matrix prep works. (true, true) → animated pose.
+ */
+const ENABLE_SKIN_REGISTRATION = true;
+const ENABLE_CLIP_PLAYBACK = true;
+
+/**
+ * Build a "skeleton only" visualization of a skin: clone the joint
+ * hierarchy as a fresh set of Node3Ds, attach a small cube mesh to
+ * each cloned joint, and produce a parallel {@link ShadeAnimationClip}
+ * whose channels target the *clones* instead of the originals (so
+ * registering and starting it drives the cube hierarchy in lockstep
+ * with the source clip on the original skin).
+ *
+ * The point is to isolate skinning from animation: if the skinned
+ * dancer glitches but the cube-skeleton next to it stays smooth,
+ * the bug is in the skinning chain; if both glitch in lockstep, the
+ * bug is in the animation chain (apply / propagate / clip state).
+ *
+ * The cloned hierarchy preserves the original parent chain among
+ * joint↔joint edges. The topmost joint(s) — whose original parent
+ * isn't itself in the skin — get reparented to a fresh wrapper that
+ * mirrors that original parent's local transform (so e.g. Mixamo's
+ * "Character" 0.01 scale + axis rotation is reproduced on the
+ * clone hierarchy). The wrapper is then placed at `offset` so the
+ * visualization renders next to the original.
+ *
+ * @param {{
+ *     skin: Skin,
+ *     clip: ShadeAnimationClip,
+ *     cube_size_local: number,
+ *     cube_material: ShadeMaterial,
+ *     offset: Vector3,
+ * }} args
+ * @returns {{ root: Node3D, clip: ShadeAnimationClip }}
+ */
+function build_skeleton_visualization({
+    skin,
+    clip,
+    cube_size_local,
+    cube_material,
+    offset,
+}) {
+    const old_joints = skin.joints;
+
+    // Find the joint hierarchy's topmost parent (e.g. Mixamo's
+    // "Character") — the first parent that isn't itself one of the
+    // skin's joints. This is the node whose transform sets the
+    // skeleton's overall scale + orientation.
+    let outer_parent = null;
+    for (let i = 0; i < old_joints.length; i++) {
+        const j = old_joints[i];
+        if (j.parent !== null && old_joints.indexOf(j.parent) === -1) {
+            outer_parent = j.parent;
+            break;
+        }
+    }
+
+    // Clone each joint as a bare Node3D with the same local TRS.
+    // A Map<original, clone> lets us re-wire parent pointers below.
+    const old_to_new = new Map();
+    const new_joints = new Array(old_joints.length);
+    for (let i = 0; i < old_joints.length; i++) {
+        const original = old_joints[i];
+        const clone = new Node3D();
+        clone.name = `${original.name}_skel`;
+        clone.transform_local.copy(original.transform_local);
+        old_to_new.set(original, clone);
+        new_joints[i] = clone;
+    }
+
+    // Wrapper that mirrors the original outer parent's local transform
+    // — keeps the cm→m scale and any axis rotation intact so the
+    // clone hierarchy ends up at the right size / orientation.
+    const outer_clone = new Node3D();
+    outer_clone.name = "Character_skel";
+    if (outer_parent !== null) {
+        outer_clone.transform_local.copy(outer_parent.transform_local);
+    }
+
+    // Re-wire the cloned hierarchy. Joints whose original parent is
+    // also a joint get parented to the matching clone. Joints whose
+    // original parent is the outer_parent get parented to outer_clone.
+    for (let i = 0; i < old_joints.length; i++) {
+        const original = old_joints[i];
+        const clone = new_joints[i];
+        const parent_clone = old_to_new.get(original.parent);
+        if (parent_clone !== undefined) {
+            parent_clone.addChild(clone);
+        } else {
+            outer_clone.addChild(clone);
+        }
+    }
+
+    // Shared cube geometry — built once, reused across all bones.
+    if (SKELETON_CUBE_GEOMETRY === null) {
+        SKELETON_CUBE_GEOMETRY = new BoxGeometry(1, 1, 1);
+        SKELETON_CUBE_GEOMETRY.name = "SkeletonBoneCube";
+    }
+
+    // Attach a small cube to each cloned joint as a child. The cube's
+    // local size is scaled up to compensate for the outer wrapper's
+    // small scale (e.g. Mixamo's 0.01) — the multiplication leaves a
+    // sensible world-space size.
+    for (let i = 0; i < new_joints.length; i++) {
+        const cube = new Mesh();
+        cube.geometry = SKELETON_CUBE_GEOMETRY;
+        cube.material = cube_material;
+        cube.name = `${old_joints[i].name}_bone_cube`;
+        cube.transform_local.setScale(cube_size_local, cube_size_local, cube_size_local);
+        new_joints[i].addChild(cube);
+    }
+
+    // Final root carries the comparison offset. Putting it on the
+    // root (rather than baking into outer_clone) keeps outer_clone
+    // a faithful copy of the original parent's transform.
+    const root = new Node3D();
+    root.name = "skeleton_visualization_root";
+    root.transform_local.setTranslation(offset.x, offset.y, offset.z);
+    root.addChild(outer_clone);
+
+    // Build the parallel clip — same curves, channels retargeted to
+    // the cloned joints. Curves can be shared across the two clips
+    // (`register_clip` uploads them independently and the GPU side
+    // doesn't care about identity), so no need to deep-clone the
+    // AnimationCurve instances.
+    const new_channels = [];
+    for (let c = 0; c < clip.channels.length; c++) {
+        const ch = clip.channels[c];
+        const new_target = old_to_new.get(ch.target);
+        if (new_target === undefined) continue;
+        new_channels.push(ShadeAnimationChannel.from({
+            target: new_target,
+            property: ch.property,
+            curves: ch.curves,
+        }));
+    }
+
+    const skel_clip = ShadeAnimationClip.from({
+        name: `${clip.name}_skeleton`,
+        channels: new_channels,
+    });
+
+    return { root, clip: skel_clip };
+}
+
+/**
+ * Shared cube geometry for skeleton-bone visualizations. Lazily
+ * built on first {@link build_skeleton_visualization} call.
+ *
+ * @type {BoxGeometry|null}
+ */
+let SKELETON_CUBE_GEOMETRY = null;
+
+/**
+ * GPU-driven skinning end-to-end demo. Loads a skinned glTF asset
+ * (Michelle, the dancing model — the three.js community's go-to
+ * skinning test rig), registers the resulting {@link Skin} and
+ * {@link ShadeAnimationClip} via {@link GPUAnimationManager}'s
+ * high-level API, and lets the GPU drive playback through
+ * {@link shader_animation_tick}.
+ *
+ * Per-frame work in the host is intentionally minimal once setup is
+ * done: push the current `dt` into a transient uniform, dispatch the
+ * tick / apply / skin-matrix-prep / skinning-apply chain, done. CPU
+ * doesn't write `clip.time` after `start()` returns.
+ *
+ * Expects `public/Michelle.glb` to exist (Michelle is the rigged
+ * three.js sample dancer). Add it to `public/` before running.
+ *
+ * @param {object} args
+ * @param {Renderer} args.renderer
+ * @param {Scene} args.scene
+ * @param {OrbitalCameraController} args.controller
+ */
+export function gltf_skinned_prototype({ renderer, scene, controller }) {
+
+    // ── Lighting & environment ──────────────────────────────────
+    scene.lights.add(make_sunlight({
+        intensity: 3,
+        direction: new Vector3(-0.4, -1, -0.3),
+    }));
+
+    load_default_environment(scene);
+
+    // ── Ground plane ────────────────────────────────────────────
+    const plane_material = new StandardShadeMaterial();
+    plane_material.diffuse_color.parse("#b5b5b5");
+    plane_material.roughness_factor = 1;
+    plane_material.metallic_factor = 0;
+
+    const plane_transform = Transform.fromJSON({ position: { x: 0, y: 0, z: 0 } });
+    plane_transform.lookAt(Vector3.up);
+
+    const plane = Mesh.from(
+        new PlaneGeometry(20, 20, 1, 1),
+        plane_material,
+        plane_transform.matrix,
+    );
+    plane.name = "Ground";
+    scene.add(plane);
+
+    // ── Camera framing for Michelle ─────────────────────────────
+    // Michelle is roughly 1.7m tall, standing on Y=0. Camera framed
+    // to catch the whole dancer with a bit of headroom.
+    {
+        const camera_position = new Vector3(2.5, 1.4, 3.5);
+        const look_at = new Vector3(0, 1.0, 0);
+        controller.look(camera_position, look_at);
+        controller.camera.near = 0.05;
+        controller.camera.far = 50;
+    }
+
+    const gpu_scene = renderer.scenes.obtain(scene);
+    const animation_manager = gpu_scene.animation_manager;
+
+    /**
+     * Set by the load promise; consumed in the next per-frame hook
+     * to wire the asset into the scene + animation manager.
+     *
+     * @type {SceneBundle|null}
+     */
+    let pending_bundle = null;
+    let setup_complete = false;
+    /** @type {number[]} */
+    const registered_clip_ids = [];
+
+    // Kick off load. The promise resolves to a SceneBundle — we
+    // can't add it to the scene until the renderer's frame loop is
+    // running (Scene.add invalidates the GPU scene; that's fine, but
+    // we want to make sure we're in the same async tick as the
+    // per-frame callback, not the bootstrap path).
+    load_gltf('public/Michelle.glb').then(bundle => {
+        pending_bundle = bundle;
+        console.log(
+            `[gltf-skinning] loaded Michelle: ${bundle.scenes.length} scene(s), ` +
+            `${bundle.skins.length} skin(s), ${bundle.clips.length} clip(s)`
+        );
+    }).catch(e => {
+        console.error("[gltf-skinning] failed to load Michelle.glb", e);
+    });
+
+    // For debugging from the console.
+    window.animation_manager = animation_manager;
+    window.gpu_scene = gpu_scene;
+
+    let dump_frame_counter = 0;
+    let dump_done = false;
+
+    /**
+     * Wait a few frames after setup completes so GPU writes have
+     * settled (transforms uploaded, clones flushed, first apply +
+     * skin-matrix-prep run if enabled), then read back the rows of
+     * interest from each table and log them. One-shot — fires once
+     * per session.
+     */
+    function dump_gpu_state() {
+        const skinned_mesh = pending_bundle.skins[0]?.meshes[0];
+        const skinned_node_row = skinned_mesh
+            ? gpu_scene.id_mapping.get(skinned_mesh.id)
+            : -1;
+        const static_copy_node_row = window.static_copy
+            ? gpu_scene.id_mapping.get(window.static_copy.id)
+            : -1;
+
+        const promises = [];
+
+        // SkinnedMesh's row in meshes (row 2 if Plane is 0/1 and
+        // SkinnedMesh is the second instance). Use id_mapping for
+        // the *node* row, but the *mesh* row is harder to look up
+        // — dump rows [0..5] to cover Plane + SkinnedMesh + static
+        // copy and any neighbours.
+        for (let i = 0; i < 6; i++) {
+            promises.push(
+                gpu_scene.scene_database
+                    .debug_table_read_element('meshes', i)
+                    .then(r => ({ kind: 'mesh', row: i, record: r }))
+            );
+        }
+
+        if (skinned_node_row !== -1) {
+            promises.push(
+                gpu_scene.scene_database
+                    .debug_table_read_element('transforms', skinned_node_row)
+                    .then(r => ({ kind: 'transform-skinned', row: skinned_node_row, record: r }))
+            );
+        }
+        if (static_copy_node_row !== -1) {
+            promises.push(
+                gpu_scene.scene_database
+                    .debug_table_read_element('transforms', static_copy_node_row)
+                    .then(r => ({ kind: 'transform-static', row: static_copy_node_row, record: r }))
+            );
+        }
+
+        // Dump joint 0 of the skin (head of the joint chain — usually
+        // the hip/root) so we can sanity-check the global transform.
+        const first_joint = pending_bundle.skins[0]?.joints[0];
+        if (first_joint !== undefined) {
+            const joint_row = gpu_scene.id_mapping.get(first_joint.id);
+            if (joint_row !== undefined) {
+                promises.push(
+                    gpu_scene.scene_database
+                        .debug_table_read_element('transforms', joint_row)
+                        .then(r => ({ kind: 'transform-joint0', row: joint_row, record: r, joint_name: first_joint.name }))
+                );
+            }
+        }
+
+        // Animation tables — only meaningful when clips registered.
+        if (registered_clip_ids.length > 0) {
+            promises.push(
+                animation_manager.database
+                    .debug_table_read_element('animation_clips', registered_clip_ids[0])
+                    .then(r => ({ kind: 'clip', row: registered_clip_ids[0], record: r }))
+            );
+            promises.push(
+                animation_manager.database
+                    .debug_table_read_element('animation_skins', 0)
+                    .then(r => ({ kind: 'skin', row: 0, record: r }))
+            );
+        }
+
+        Promise.all(promises).then(results => {
+            console.group('[gltf-skinning] GPU state dump');
+            for (const r of results) {
+                console.log(r.kind, 'row=' + r.row, r.record);
+            }
+            console.groupEnd();
+        }).catch(e => {
+            console.error('[gltf-skinning] dump failed:', e);
+        });
+    }
+
+    renderer.onFrameFinished.add(() => {
+
+        // One-shot setup once the bundle has loaded. Eventual-
+        // consistency registration means we can scene.add + register
+        // in the same callback — the joint-block / bindings chains
+        // get patched in by animation_manager.update()'s drain pass
+        // once scene.build has populated id_mapping.
+        if (pending_bundle !== null && !setup_complete) {
+            const bundle = pending_bundle;
+
+            scene.add(bundle.scenes);
+
+            // Static side-by-side clone — same MeshletGeometry +
+            // material as the SkinnedMesh, but rendered as a regular
+            // Mesh with no skinning routing. If this one shows up but
+            // the SkinnedMesh doesn't, the bug is in the geometry
+            // clone / skinning context, not in geometry/material/
+            // transform shared with the source.
+            if (bundle.skins.length > 0 && bundle.skins[0].meshes.length > 0) {
+                const src = bundle.skins[0].meshes[0];
+                const static_copy = new Mesh();
+                static_copy.geometry = src.geometry;
+                static_copy.material = src.material;
+                static_copy.name = `${src.name}_static_copy`;
+                // Place 1.5m to the right of the skinned mesh so both
+                // are in frame.
+                static_copy.transform_local.setTranslation(1.5, 0, 0);
+                static_copy.updateMatrices();
+                scene.add(static_copy);
+                window.static_copy = static_copy;
+                console.log(
+                    `[gltf-skinning] added static (non-skinned) sibling at x=1.5 ` +
+                    `for comparison: name='${static_copy.name}'`
+                );
+            }
+
+            // Skeleton-only visualization — clones the joint
+            // hierarchy and attaches a cube per bone. Driven by a
+            // parallel clip registered immediately below.
+            let skel_clip_for_registration = null;
+            if (
+                ENABLE_CLIP_PLAYBACK
+                && bundle.skins.length > 0
+                && bundle.clips.length > 0
+            ) {
+                const main_clip = bundle.clips.find(c => c.duration > 0.1);
+                if (main_clip !== undefined) {
+                    // Plain opaque material with bright diffuse only —
+                    // no emissive_factor (which would route into the
+                    // emissive G-buffer slot and might engage a
+                    // different rasterization bucket than the static
+                    // copy / Michelle; rule that out by matching the
+                    // material shape).
+                    //
+                    // Force draw_side = Double so we can't be eaten
+                    // by backface culling if the BoxGeometry's winding
+                    // happens to face away from camera for whatever
+                    // reason (e.g. an inverted-handedness combine in
+                    // the joint chain producing negative-determinant
+                    // transforms).
+                    const cube_material = new StandardShadeMaterial();
+                    cube_material.diffuse_color.parse("#ffcc00");
+                    cube_material.roughness_factor = 0.6;
+                    cube_material.metallic_factor = 0;
+                    cube_material.draw_side = ShadeDrawSide.Double;
+
+                    const { root: skel_root, clip: skel_clip } =
+                        build_skeleton_visualization({
+                            skin: bundle.skins[0],
+                            clip: main_clip,
+                            // 15 units in joint-local space — after
+                            // the outer Mixamo 0.01 scale, ~15 cm in
+                            // world. Smaller than the prior 30 unit
+                            // value per visual feedback.
+                            cube_size_local: 15,
+                            cube_material,
+                            offset: new Vector3(-1.5, 0, 0),
+                        });
+
+                    // Walk the hierarchy to compose transform_global
+                    // and (importantly) compute mesh.bounding_box /
+                    // bounding_sphere via updateBoundsBasic on every
+                    // cube. Without this, the cubes' CPU bounds
+                    // default to zeros (Float32Array init), scene.build
+                    // uploads those zeros into the meshes_table, and
+                    // the camera-frustum sphere/AABB culler rejects
+                    // every cube — invisible in the main view even
+                    // though the shadow pass (which uses the light
+                    // volume sphere, not the mesh bounds) still
+                    // rasterizes them.
+                    skel_root.updateMatrices();
+
+                    scene.add(skel_root);
+                    skel_clip_for_registration = skel_clip;
+                    console.log(
+                        `[gltf-skinning] added skeleton-only viz at x=-1.5 ` +
+                        `(${skel_clip.channels.length} cloned channels)`
+                    );
+                }
+            }
+
+            // Diagnostic logging of the first skinned mesh.
+            if (bundle.skins.length > 0 && bundle.skins[0].meshes.length > 0) {
+                const m = bundle.skins[0].meshes[0];
+                const g = m.geometry;
+                console.log(
+                    `[gltf-skinning] first skinned mesh: name='${m.name}' ` +
+                    `parent='${m.parent?.name ?? '<none>'}'`
+                );
+                console.log(
+                    `[gltf-skinning]  geometry.bounding_box=`, g.bounding_box,
+                    ` sphere=`, g.bounding_sphere
+                );
+                console.log(
+                    `[gltf-skinning]  mesh.bounding_box=`, m.bounding_box,
+                    ` sphere=`, m.bounding_sphere
+                );
+                console.log(
+                    `[gltf-skinning]  mesh.transform_global.matrix=`,
+                    Array.from(m.transform_global.matrix)
+                );
+                console.log(
+                    `[gltf-skinning]  material draw_side=${m.material.draw_side} ` +
+                    `transparency_mode=${m.material.transparency_mode}`
+                );
+            }
+
+            if (ENABLE_SKIN_REGISTRATION) {
+                for (let i = 0; i < bundle.skins.length; i++) {
+                    const skin = bundle.skins[i];
+                    const skin_id = animation_manager.register_skin(skin);
+                    console.log(
+                        `[gltf-skinning] registered skin '${skin.name}' ` +
+                        `(id=${skin_id}, joints=${skin.joints.length}, meshes=${skin.meshes.length})`
+                    );
+                }
+            } else {
+                console.log('[gltf-skinning] SKIN REGISTRATION DISABLED — mesh stays unbound');
+            }
+
+            if (ENABLE_CLIP_PLAYBACK) {
+                // Drop near-zero-duration clips (rest poses) — they'd
+                // fight the real animation when both have Playing+Loop set.
+                const usable_clips = bundle.clips.filter(c => c.duration > 0.1);
+                console.log(
+                    `[gltf-skinning] selecting ${usable_clips.length}/${bundle.clips.length} ` +
+                    `clip(s) with duration > 0.1s`
+                );
+
+                for (let i = 0; i < usable_clips.length; i++) {
+                    const clip = usable_clips[i];
+                    const clip_id = animation_manager.register_clip(clip);
+
+                    animation_manager.set_flags(clip_id, AnimationClipFlags.Loop);
+                    animation_manager.start(clip_id);
+
+                    registered_clip_ids.push(clip_id);
+                    console.log(
+                        `[gltf-skinning] registered clip '${clip.name}' ` +
+                        `(id=${clip_id}, ${clip.channels.length} channels, ` +
+                        `duration=${clip.duration.toFixed(3)}s)`
+                    );
+                }
+
+                if (skel_clip_for_registration !== null) {
+                    const skel_clip_id = animation_manager.register_clip(skel_clip_for_registration);
+                    animation_manager.set_flags(skel_clip_id, AnimationClipFlags.Loop);
+                    animation_manager.start(skel_clip_id);
+                    registered_clip_ids.push(skel_clip_id);
+                    console.log(
+                        `[gltf-skinning] registered skeleton clip '${skel_clip_for_registration.name}' ` +
+                        `(id=${skel_clip_id}, ${skel_clip_for_registration.channels.length} channels)`
+                    );
+                }
+            } else {
+                console.log('[gltf-skinning] CLIP PLAYBACK DISABLED — joints stay at bind TRS');
+            }
+
+            setup_complete = true;
+        }
+
+        if (!setup_complete) {
+            return;
+        }
+
+        // One-shot GPU state dump a few frames into the stable
+        // regime. Wait for all the upload + first-frame passes to
+        // have settled before reading back.
+        if (!dump_done) {
+            dump_frame_counter++;
+            if (dump_frame_counter > 5) {
+                dump_done = true;
+                dump_gpu_state();
+            }
+        }
+    });
+}