@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/playground/gltf_skinned_stress_prototype.js

@@ -1,387 +1,387 @@
-import Vector3 from "../../core/geom/Vector3.js";
-import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
-import { seededRandom } from "../../core/math/random/seededRandom.js";
-import { Transform } from "../../engine/ecs/transform/Transform.js";
-import { ShadeAnimationChannel } from "../renderer/animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../renderer/animation/ShadeAnimationClip.js";
-import { AnimationClipFlags } from "../renderer/animation/AnimationClipFlags.js";
-import { Skin } from "../renderer/animation/Skin.js";
-import { 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 { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
-import { Node3D } from "../renderer/scene/Node3D.js";
-import { SkinnedMesh } from "../renderer/scene/SkinnedMesh.js";
-
-/**
- * Number of dancers per side of the grid; total dancer count is the
- * square of this. Each dancer is a full SkinnedMesh + a cloned joint
- * hierarchy + its own clip, so per-frame cost scales linearly with
- * dancer count for apply/propagate/skin-matrix-prep, and with
- * (joint_count × dancer_count) for the deformation pass.
- */
-const GRID_RESOLUTION = 50;
-
-/**
- * Centre-to-centre spacing between dancers in metres. Michelle is
- * roughly 0.7 m wide at the shoulders; 1.8 m keeps full-amplitude arm
- * swings from intersecting neighbours while still fitting a 3×3 grid
- * inside a single comfortable camera framing.
- */
-const GRID_SPACING = 1.8;
-
-/**
- * Seed for the per-dancer phase-offset RNG. With a fixed seed the
- * grid lays out the same dancers in the same poses on every reload,
- * which is what lets the timings (and any future regressions) be
- * compared between runs.
- */
-const RANDOM_SEED = 42;
-
-/**
- * Build one dancer instance from the loaded glTF bundle. Each call
- * produces:
- *
- *   - A fresh {@link SkinnedMesh} sharing the bundle's geometry +
- *     material. Identity world transform (the skin matrices alone
- *     place its vertices in world space — same convention as in
- *     `load_gltf`).
- *   - A cloned joint hierarchy under a fresh "instance root" Node3D
- *     translated to `position`. The cloned joints carry the same
- *     local TRS as the bundle's originals; an "outer clone" wrapper
- *     mirrors the bundle's outermost parent (e.g. Mixamo's
- *     `Character` node with its cm→m scale + axis rotation).
- *   - A {@link Skin} pointing at the cloned joints, sharing the
- *     bundle's inverse-bind matrices (bind-pose data is the same
- *     across instances).
- *   - A {@link ShadeAnimationClip} retargeted at the cloned joints,
- *     sharing the bundle's per-channel `AnimationCurve`s (curve
- *     data is read-only and instance-independent).
- *
- * Nothing in this routine touches the GPU — registration happens
- * later via `animation_manager.register_skin` / `register_clip`,
- * after the host's scene rebuild has populated `id_mapping` for the
- * cloned Node3Ds.
- *
- * @param {{ bundle: SceneBundle, position: Vector3 }} args
- * @returns {{ instance_root: Node3D, skin: Skin, clip: ShadeAnimationClip }}
- */
-function instantiate_dancer({ bundle, position }) {
-    const template_skin = bundle.skins[0];
-    const template_clip = bundle.clips.find(c => c.duration > 0.1);
-    const template_mesh = template_skin.meshes[0];
-    const template_joints = template_skin.joints;
-
-    // Find the joint hierarchy's outermost parent — the first parent
-    // that isn't itself a joint. For Mixamo glTF this is the
-    // `Character` node carrying the cm→m scale + axis rotation.
-    let outer_parent = null;
-    for (let i = 0; i < template_joints.length; i++) {
-        const j = template_joints[i];
-        if (j.parent !== null && template_joints.indexOf(j.parent) === -1) {
-            outer_parent = j.parent;
-            break;
-        }
-    }
-
-    // Clone the joint Node3Ds. Map<original, clone> lets us re-wire
-    // parent pointers afterwards.
-    const old_to_new = new Map();
-    const new_joints = new Array(template_joints.length);
-    for (let i = 0; i < template_joints.length; i++) {
-        const original = template_joints[i];
-        const clone = new Node3D();
-        clone.name = original.name;
-        clone.transform_local.copy(original.transform_local);
-        old_to_new.set(original, clone);
-        new_joints[i] = clone;
-    }
-
-    // Outer-parent clone — mirrors the bundle's Character transform.
-    // Without this, the cloned joints would be in cm-scale at the
-    // instance root, which doesn't match the bind-pose space the
-    // inverse-bind matrices encode.
-    const outer_clone = new Node3D();
-    outer_clone.name = "Character_inst";
-    if (outer_parent !== null) {
-        outer_clone.transform_local.copy(outer_parent.transform_local);
-    }
-
-    // Wire parent links among the clones. Joints whose original
-    // parent is another joint go under the matching clone; joints
-    // whose original parent is the outer_parent (or null) go under
-    // outer_clone.
-    for (let i = 0; i < template_joints.length; i++) {
-        const original = template_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);
-        }
-    }
-
-    // Instance root carries the grid-cell offset. Both the joint
-    // subtree and the SkinnedMesh hang under it, so the dancer's
-    // entire placement (translation + any future per-instance
-    // rotation/scale) lives on this one node.
-    const instance_root = new Node3D();
-    instance_root.name = "Dancer";
-    instance_root.transform_local.setTranslation(position.x, position.y, position.z);
-    instance_root.addChild(outer_clone);
-
-    // Fresh SkinnedMesh sharing geometry + material. Parented to
-    // `instance_root` with identity local transform — its
-    // `transform_global` ends up at the grid-cell translation
-    // (transitively, through `instance_root`), exactly where the
-    // skinned vertices actually live in world space. The skin-
-    // matrix prep shader applies the spec's
-    // `inverse(meshNode.worldMatrix)` factor (see
-    // GPUAnimationManager#register_skin) so the deformation stays
-    // correct regardless of where the mesh sits in the hierarchy.
-    const instance_mesh = new SkinnedMesh();
-    instance_mesh.geometry = template_mesh.geometry;
-    instance_mesh.material = template_mesh.material;
-    instance_mesh.name = `${template_mesh.name}_inst`;
-    instance_root.addChild(instance_mesh);
-
-    // Fresh Skin pointing at the cloned joints; inverse_bind_matrices
-    // are bind-pose data and instance-independent, so we share the
-    // bundle's array rather than copy it. `meshes` holds only this
-    // instance's SkinnedMesh, so register_skin's bind/stamp-id loop
-    // doesn't touch any other dancer.
-    const instance_skin = Skin.from({
-        name: template_skin.name,
-        joints: new_joints,
-        inverse_bind_matrices: template_skin.inverse_bind_matrices,
-        meshes: [instance_mesh],
-    });
-
-    // Retarget the template clip's channels onto the cloned joints.
-    // Curves are read-only animation data — sharing them across
-    // instances is intended (`register_clip` uploads them per call
-    // and the GPU side has no notion of identity).
-    const new_channels = [];
-    for (let i = 0; i < template_clip.channels.length; i++) {
-        const ch = template_clip.channels[i];
-        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 instance_clip = ShadeAnimationClip.from({
-        name: `${template_clip.name}_inst`,
-        channels: new_channels,
-    });
-
-    return {
-        instance_root,
-        skin: instance_skin,
-        clip: instance_clip,
-    };
-}
-
-/**
- * Stress variant of the single-dancer glTF skinning demo: a grid of
- * dancing Michelles, each with a random phase offset into the same
- * SambaDance clip.
- *
- * Per-frame work scales linearly in dancer count for apply /
- * propagate / skin-matrix-prep (one workgroup family each) and in
- * `dancer_count × joint_count × meshlet_count` for the skinning
- * deformation. Tick is a single dispatch over the clips table.
- *
- * Expects `public/Michelle.glb` — same asset as the single-dancer
- * prototype.
- *
- * @param {object} args
- * @param {Renderer} args.renderer
- * @param {Scene} args.scene
- * @param {OrbitalCameraController} args.controller
- */
-export function gltf_skinned_stress_prototype({ renderer, scene, controller }) {
-
-    scene.lights.add(make_sunlight({
-        intensity: 3,
-        direction: new Vector3(-0.4, -1, -0.3),
-    }));
-
-    load_default_environment(scene);
-
-    // Ground sized to fit the grid plus margin on every side. The
-    // dancers occupy a square of side `(GRID_RESOLUTION - 1) *
-    // GRID_SPACING` centred on the origin (corner-to-corner of joint
-    // origins). We add two extra cells of spacing (one per side) so
-    // each row/column has a half-cell of clean ground around it
-    // visually, plus a 4 m safety pad for limbs swinging outside the
-    // joint cell and shadows projecting past the grid. Scales
-    // automatically with `GRID_RESOLUTION` and `GRID_SPACING`.
-    const ground_extent = (GRID_RESOLUTION + 2) * GRID_SPACING + 8;
-    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(ground_extent, ground_extent, 1, 1),
-        plane_material,
-        plane_transform.matrix,
-    );
-    plane.name = "Ground";
-    scene.add(plane);
-
-    // Camera pulled back along +Z so the full grid fits in frame.
-    // The grid sits in the XZ plane, centred on the origin; Michelle
-    // stands ~1.7 m tall, so y ≈ 1 looks at the dancers' midpoints.
-    {
-        const grid_span = GRID_RESOLUTION * GRID_SPACING;
-        const camera_position = new Vector3(grid_span * 0.6, grid_span * 0.4, grid_span * 0.9);
-        const look_at = new Vector3(0, 1.0, 0);
-        controller.look(camera_position, look_at);
-        controller.camera.near = 0.05;
-        controller.camera.far = grid_span * 4 + 50;
-    }
-
-    const gpu_scene = renderer.scenes.obtain(scene);
-    const animation_manager = gpu_scene.animation_manager;
-    const random = seededRandom(RANDOM_SEED);
-
-    let setup_complete = false;
-    /** @type {number[]} */
-    const registered_clip_ids = [];
-
-    let pending_bundle = null;
-    load_gltf('public/Michelle.glb').then(bundle => {
-        pending_bundle = bundle;
-        console.log(
-            `[gltf-stress] loaded Michelle: ${bundle.scenes.length} scene(s), ` +
-            `${bundle.skins.length} skin(s), ${bundle.clips.length} clip(s)`
-        );
-    }).catch(e => {
-        console.error("[gltf-stress] failed to load Michelle.glb", e);
-    });
-
-    window.animation_manager = animation_manager;
-    window.gpu_scene = gpu_scene;
-
-    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 the manager's update() drain once
-        // scene.build has populated id_mapping for the cloned
-        // Node3Ds.
-        if (pending_bundle !== null && !setup_complete) {
-            const main_clip = pending_bundle.clips.find(c => c.duration > 0.1);
-            if (main_clip === undefined) {
-                console.error("[gltf-stress] no clip with duration > 0.1s — aborting");
-                setup_complete = true;
-                return;
-            }
-
-            // Grid layout centred on origin in the XZ plane.
-            const total_dancer_count = GRID_RESOLUTION * GRID_RESOLUTION;
-            const grid_start = -((GRID_RESOLUTION - 1) * GRID_SPACING) / 2;
-
-            // Pre-grow the meshlet manager to fit every clone's data +
-            // metadata up front. Without this, scene.build's per-
-            // instance clone allocations accumulate in the meshlet
-            // manager's pending-clones queue (each clone references
-            // offsets in the current data/metadata buffers); when one
-            // of those allocations triggers a buffer grow, the
-            // resulting rebuild asserts that the queue is empty
-            // (rebuild would migrate the source to a new buffer,
-            // stranding the pending clones' offset references).
-            //
-            // Calling `grow` here, before any clone gets queued, is
-            // free of that constraint. We also `add` the source
-            // geometry first so we can read its actual
-            // data_size / meshlet_count and size the pre-grow
-            // precisely — pessimistic over-allocation would work too
-            // but waste GPU memory at large grid resolutions.
-            {
-                const template_geometry =
-                    pending_bundle.skins[0].meshes[0].geometry;
-
-                gpu_scene.geometries.add(template_geometry);
-                const source_meta =
-                    gpu_scene.geometries.get_metadata(template_geometry);
-                const per_clone_data_words = source_meta.meshlets.data_size;
-                const per_clone_meshlets = source_meta.meshlets.meshlet_count;
-
-                gpu_scene.geometries.meshlets.grow(
-                    total_dancer_count * per_clone_data_words,
-                    total_dancer_count * per_clone_meshlets,
-                );
-
-                console.log(
-                    `[gltf-stress] pre-grew meshlet buffers for ` +
-                    `${total_dancer_count} clones: ` +
-                    `+${total_dancer_count * per_clone_data_words} words data, ` +
-                    `+${total_dancer_count * per_clone_meshlets} meshlets ` +
-                    `(per-clone: ${per_clone_data_words}w / ${per_clone_meshlets}m)`
-                );
-            }
-
-            for (let i = 0; i < total_dancer_count; i++) {
-                const gx = i % GRID_RESOLUTION;
-                const gz = Math.floor(i / GRID_RESOLUTION);
-                const position = new Vector3(
-                    grid_start + gx * GRID_SPACING,
-                    0,
-                    grid_start + gz * GRID_SPACING,
-                );
-
-                const { instance_root, skin, clip } =
-                    instantiate_dancer({ bundle: pending_bundle, position });
-
-                // SkinnedMesh + joint subtree are both children of
-                // instance_root. Adding the root covers everything,
-                // and the compose-globals call inside
-                // instantiate_dancer already populated each Node3D's
-                // transform_global (so mesh bounds compute correctly
-                // when scene.build reads them).
-                scene.add(instance_root);
-
-                // Register immediately — the manager defers the
-                // joint-block / bindings chain build until
-                // id_mapping is populated. State mutators (start /
-                // set_flags / set_time) take effect on the
-                // already-allocated clip row regardless of pending
-                // state.
-                animation_manager.register_skin(skin);
-
-                const clip_id = animation_manager.register_clip(clip);
-                animation_manager.set_flags(clip_id, AnimationClipFlags.Loop);
-                animation_manager.start(clip_id);
-                // Phase-offset each dancer's clock so the grid isn't
-                // a wall of mirror images.
-                animation_manager.set_time(
-                    clip_id,
-                    randomFloatBetween(random, 0, main_clip.duration)
-                );
-
-                registered_clip_ids.push(clip_id);
-            }
-
-            console.log(
-                `[gltf-stress] instantiated ${total_dancer_count} dancer(s) ` +
-                `on a ${GRID_RESOLUTION}×${GRID_RESOLUTION} grid (spacing=${GRID_SPACING}m), ` +
-                `registered ${registered_clip_ids.length} clip(s)`
-            );
-
-            setup_complete = true;
-        }
-    });
-}
+import Vector3 from "../../core/geom/Vector3.js";
+import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
+import { seededRandom } from "../../core/math/random/seededRandom.js";
+import { Transform } from "../../engine/ecs/transform/Transform.js";
+import { ShadeAnimationChannel } from "../renderer/animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../renderer/animation/ShadeAnimationClip.js";
+import { AnimationClipFlags } from "../renderer/animation/AnimationClipFlags.js";
+import { Skin } from "../renderer/animation/Skin.js";
+import { 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 { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../renderer/scene/Mesh.js";
+import { Node3D } from "../renderer/scene/Node3D.js";
+import { SkinnedMesh } from "../renderer/scene/SkinnedMesh.js";
+
+/**
+ * Number of dancers per side of the grid; total dancer count is the
+ * square of this. Each dancer is a full SkinnedMesh + a cloned joint
+ * hierarchy + its own clip, so per-frame cost scales linearly with
+ * dancer count for apply/propagate/skin-matrix-prep, and with
+ * (joint_count × dancer_count) for the deformation pass.
+ */
+const GRID_RESOLUTION = 50;
+
+/**
+ * Centre-to-centre spacing between dancers in metres. Michelle is
+ * roughly 0.7 m wide at the shoulders; 1.8 m keeps full-amplitude arm
+ * swings from intersecting neighbours while still fitting a 3×3 grid
+ * inside a single comfortable camera framing.
+ */
+const GRID_SPACING = 1.8;
+
+/**
+ * Seed for the per-dancer phase-offset RNG. With a fixed seed the
+ * grid lays out the same dancers in the same poses on every reload,
+ * which is what lets the timings (and any future regressions) be
+ * compared between runs.
+ */
+const RANDOM_SEED = 42;
+
+/**
+ * Build one dancer instance from the loaded glTF bundle. Each call
+ * produces:
+ *
+ *   - A fresh {@link SkinnedMesh} sharing the bundle's geometry +
+ *     material. Identity world transform (the skin matrices alone
+ *     place its vertices in world space — same convention as in
+ *     `load_gltf`).
+ *   - A cloned joint hierarchy under a fresh "instance root" Node3D
+ *     translated to `position`. The cloned joints carry the same
+ *     local TRS as the bundle's originals; an "outer clone" wrapper
+ *     mirrors the bundle's outermost parent (e.g. Mixamo's
+ *     `Character` node with its cm→m scale + axis rotation).
+ *   - A {@link Skin} pointing at the cloned joints, sharing the
+ *     bundle's inverse-bind matrices (bind-pose data is the same
+ *     across instances).
+ *   - A {@link ShadeAnimationClip} retargeted at the cloned joints,
+ *     sharing the bundle's per-channel `AnimationCurve`s (curve
+ *     data is read-only and instance-independent).
+ *
+ * Nothing in this routine touches the GPU — registration happens
+ * later via `animation_manager.register_skin` / `register_clip`,
+ * after the host's scene rebuild has populated `id_mapping` for the
+ * cloned Node3Ds.
+ *
+ * @param {{ bundle: SceneBundle, position: Vector3 }} args
+ * @returns {{ instance_root: Node3D, skin: Skin, clip: ShadeAnimationClip }}
+ */
+function instantiate_dancer({ bundle, position }) {
+    const template_skin = bundle.skins[0];
+    const template_clip = bundle.clips.find(c => c.duration > 0.1);
+    const template_mesh = template_skin.meshes[0];
+    const template_joints = template_skin.joints;
+
+    // Find the joint hierarchy's outermost parent — the first parent
+    // that isn't itself a joint. For Mixamo glTF this is the
+    // `Character` node carrying the cm→m scale + axis rotation.
+    let outer_parent = null;
+    for (let i = 0; i < template_joints.length; i++) {
+        const j = template_joints[i];
+        if (j.parent !== null && template_joints.indexOf(j.parent) === -1) {
+            outer_parent = j.parent;
+            break;
+        }
+    }
+
+    // Clone the joint Node3Ds. Map<original, clone> lets us re-wire
+    // parent pointers afterwards.
+    const old_to_new = new Map();
+    const new_joints = new Array(template_joints.length);
+    for (let i = 0; i < template_joints.length; i++) {
+        const original = template_joints[i];
+        const clone = new Node3D();
+        clone.name = original.name;
+        clone.transform_local.copy(original.transform_local);
+        old_to_new.set(original, clone);
+        new_joints[i] = clone;
+    }
+
+    // Outer-parent clone — mirrors the bundle's Character transform.
+    // Without this, the cloned joints would be in cm-scale at the
+    // instance root, which doesn't match the bind-pose space the
+    // inverse-bind matrices encode.
+    const outer_clone = new Node3D();
+    outer_clone.name = "Character_inst";
+    if (outer_parent !== null) {
+        outer_clone.transform_local.copy(outer_parent.transform_local);
+    }
+
+    // Wire parent links among the clones. Joints whose original
+    // parent is another joint go under the matching clone; joints
+    // whose original parent is the outer_parent (or null) go under
+    // outer_clone.
+    for (let i = 0; i < template_joints.length; i++) {
+        const original = template_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);
+        }
+    }
+
+    // Instance root carries the grid-cell offset. Both the joint
+    // subtree and the SkinnedMesh hang under it, so the dancer's
+    // entire placement (translation + any future per-instance
+    // rotation/scale) lives on this one node.
+    const instance_root = new Node3D();
+    instance_root.name = "Dancer";
+    instance_root.transform_local.setTranslation(position.x, position.y, position.z);
+    instance_root.addChild(outer_clone);
+
+    // Fresh SkinnedMesh sharing geometry + material. Parented to
+    // `instance_root` with identity local transform — its
+    // `transform_global` ends up at the grid-cell translation
+    // (transitively, through `instance_root`), exactly where the
+    // skinned vertices actually live in world space. The skin-
+    // matrix prep shader applies the spec's
+    // `inverse(meshNode.worldMatrix)` factor (see
+    // GPUAnimationManager#register_skin) so the deformation stays
+    // correct regardless of where the mesh sits in the hierarchy.
+    const instance_mesh = new SkinnedMesh();
+    instance_mesh.geometry = template_mesh.geometry;
+    instance_mesh.material = template_mesh.material;
+    instance_mesh.name = `${template_mesh.name}_inst`;
+    instance_root.addChild(instance_mesh);
+
+    // Fresh Skin pointing at the cloned joints; inverse_bind_matrices
+    // are bind-pose data and instance-independent, so we share the
+    // bundle's array rather than copy it. `meshes` holds only this
+    // instance's SkinnedMesh, so register_skin's bind/stamp-id loop
+    // doesn't touch any other dancer.
+    const instance_skin = Skin.from({
+        name: template_skin.name,
+        joints: new_joints,
+        inverse_bind_matrices: template_skin.inverse_bind_matrices,
+        meshes: [instance_mesh],
+    });
+
+    // Retarget the template clip's channels onto the cloned joints.
+    // Curves are read-only animation data — sharing them across
+    // instances is intended (`register_clip` uploads them per call
+    // and the GPU side has no notion of identity).
+    const new_channels = [];
+    for (let i = 0; i < template_clip.channels.length; i++) {
+        const ch = template_clip.channels[i];
+        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 instance_clip = ShadeAnimationClip.from({
+        name: `${template_clip.name}_inst`,
+        channels: new_channels,
+    });
+
+    return {
+        instance_root,
+        skin: instance_skin,
+        clip: instance_clip,
+    };
+}
+
+/**
+ * Stress variant of the single-dancer glTF skinning demo: a grid of
+ * dancing Michelles, each with a random phase offset into the same
+ * SambaDance clip.
+ *
+ * Per-frame work scales linearly in dancer count for apply /
+ * propagate / skin-matrix-prep (one workgroup family each) and in
+ * `dancer_count × joint_count × meshlet_count` for the skinning
+ * deformation. Tick is a single dispatch over the clips table.
+ *
+ * Expects `public/Michelle.glb` — same asset as the single-dancer
+ * prototype.
+ *
+ * @param {object} args
+ * @param {Renderer} args.renderer
+ * @param {Scene} args.scene
+ * @param {OrbitalCameraController} args.controller
+ */
+export function gltf_skinned_stress_prototype({ renderer, scene, controller }) {
+
+    scene.lights.add(make_sunlight({
+        intensity: 3,
+        direction: new Vector3(-0.4, -1, -0.3),
+    }));
+
+    load_default_environment(scene);
+
+    // Ground sized to fit the grid plus margin on every side. The
+    // dancers occupy a square of side `(GRID_RESOLUTION - 1) *
+    // GRID_SPACING` centred on the origin (corner-to-corner of joint
+    // origins). We add two extra cells of spacing (one per side) so
+    // each row/column has a half-cell of clean ground around it
+    // visually, plus a 4 m safety pad for limbs swinging outside the
+    // joint cell and shadows projecting past the grid. Scales
+    // automatically with `GRID_RESOLUTION` and `GRID_SPACING`.
+    const ground_extent = (GRID_RESOLUTION + 2) * GRID_SPACING + 8;
+    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(ground_extent, ground_extent, 1, 1),
+        plane_material,
+        plane_transform.matrix,
+    );
+    plane.name = "Ground";
+    scene.add(plane);
+
+    // Camera pulled back along +Z so the full grid fits in frame.
+    // The grid sits in the XZ plane, centred on the origin; Michelle
+    // stands ~1.7 m tall, so y ≈ 1 looks at the dancers' midpoints.
+    {
+        const grid_span = GRID_RESOLUTION * GRID_SPACING;
+        const camera_position = new Vector3(grid_span * 0.6, grid_span * 0.4, grid_span * 0.9);
+        const look_at = new Vector3(0, 1.0, 0);
+        controller.look(camera_position, look_at);
+        controller.camera.near = 0.05;
+        controller.camera.far = grid_span * 4 + 50;
+    }
+
+    const gpu_scene = renderer.scenes.obtain(scene);
+    const animation_manager = gpu_scene.animation_manager;
+    const random = seededRandom(RANDOM_SEED);
+
+    let setup_complete = false;
+    /** @type {number[]} */
+    const registered_clip_ids = [];
+
+    let pending_bundle = null;
+    load_gltf('public/Michelle.glb').then(bundle => {
+        pending_bundle = bundle;
+        console.log(
+            `[gltf-stress] loaded Michelle: ${bundle.scenes.length} scene(s), ` +
+            `${bundle.skins.length} skin(s), ${bundle.clips.length} clip(s)`
+        );
+    }).catch(e => {
+        console.error("[gltf-stress] failed to load Michelle.glb", e);
+    });
+
+    window.animation_manager = animation_manager;
+    window.gpu_scene = gpu_scene;
+
+    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 the manager's update() drain once
+        // scene.build has populated id_mapping for the cloned
+        // Node3Ds.
+        if (pending_bundle !== null && !setup_complete) {
+            const main_clip = pending_bundle.clips.find(c => c.duration > 0.1);
+            if (main_clip === undefined) {
+                console.error("[gltf-stress] no clip with duration > 0.1s — aborting");
+                setup_complete = true;
+                return;
+            }
+
+            // Grid layout centred on origin in the XZ plane.
+            const total_dancer_count = GRID_RESOLUTION * GRID_RESOLUTION;
+            const grid_start = -((GRID_RESOLUTION - 1) * GRID_SPACING) / 2;
+
+            // Pre-grow the meshlet manager to fit every clone's data +
+            // metadata up front. Without this, scene.build's per-
+            // instance clone allocations accumulate in the meshlet
+            // manager's pending-clones queue (each clone references
+            // offsets in the current data/metadata buffers); when one
+            // of those allocations triggers a buffer grow, the
+            // resulting rebuild asserts that the queue is empty
+            // (rebuild would migrate the source to a new buffer,
+            // stranding the pending clones' offset references).
+            //
+            // Calling `grow` here, before any clone gets queued, is
+            // free of that constraint. We also `add` the source
+            // geometry first so we can read its actual
+            // data_size / meshlet_count and size the pre-grow
+            // precisely — pessimistic over-allocation would work too
+            // but waste GPU memory at large grid resolutions.
+            {
+                const template_geometry =
+                    pending_bundle.skins[0].meshes[0].geometry;
+
+                gpu_scene.geometries.add(template_geometry);
+                const source_meta =
+                    gpu_scene.geometries.get_metadata(template_geometry);
+                const per_clone_data_words = source_meta.meshlets.data_size;
+                const per_clone_meshlets = source_meta.meshlets.meshlet_count;
+
+                gpu_scene.geometries.meshlets.grow(
+                    total_dancer_count * per_clone_data_words,
+                    total_dancer_count * per_clone_meshlets,
+                );
+
+                console.log(
+                    `[gltf-stress] pre-grew meshlet buffers for ` +
+                    `${total_dancer_count} clones: ` +
+                    `+${total_dancer_count * per_clone_data_words} words data, ` +
+                    `+${total_dancer_count * per_clone_meshlets} meshlets ` +
+                    `(per-clone: ${per_clone_data_words}w / ${per_clone_meshlets}m)`
+                );
+            }
+
+            for (let i = 0; i < total_dancer_count; i++) {
+                const gx = i % GRID_RESOLUTION;
+                const gz = Math.floor(i / GRID_RESOLUTION);
+                const position = new Vector3(
+                    grid_start + gx * GRID_SPACING,
+                    0,
+                    grid_start + gz * GRID_SPACING,
+                );
+
+                const { instance_root, skin, clip } =
+                    instantiate_dancer({ bundle: pending_bundle, position });
+
+                // SkinnedMesh + joint subtree are both children of
+                // instance_root. Adding the root covers everything,
+                // and the compose-globals call inside
+                // instantiate_dancer already populated each Node3D's
+                // transform_global (so mesh bounds compute correctly
+                // when scene.build reads them).
+                scene.add(instance_root);
+
+                // Register immediately — the manager defers the
+                // joint-block / bindings chain build until
+                // id_mapping is populated. State mutators (start /
+                // set_flags / set_time) take effect on the
+                // already-allocated clip row regardless of pending
+                // state.
+                animation_manager.register_skin(skin);
+
+                const clip_id = animation_manager.register_clip(clip);
+                animation_manager.set_flags(clip_id, AnimationClipFlags.Loop);
+                animation_manager.start(clip_id);
+                // Phase-offset each dancer's clock so the grid isn't
+                // a wall of mirror images.
+                animation_manager.set_time(
+                    clip_id,
+                    randomFloatBetween(random, 0, main_clip.duration)
+                );
+
+                registered_clip_ids.push(clip_id);
+            }
+
+            console.log(
+                `[gltf-stress] instantiated ${total_dancer_count} dancer(s) ` +
+                `on a ${GRID_RESOLUTION}×${GRID_RESOLUTION} grid (spacing=${GRID_SPACING}m), ` +
+                `registered ${registered_clip_ids.length} clip(s)`
+            );
+
+            setup_complete = true;
+        }
+    });
+}