@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/playground/animation_prototype.js

@@ -1,508 +1,508 @@
-import { Color } from "../../core/color/Color.js";
-import Vector3 from "../../core/geom/Vector3.js";
-import { AnimationCurve } from "../../engine/animation/curve/AnimationCurve.js";
-import { Keyframe } from "../../engine/animation/curve/Keyframe.js";
-import { Transform } from "../../engine/ecs/transform/Transform.js";
-import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
-import { shader_animation_apply, WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE } from "../renderer/animation/shader_animation_apply.js";
-import {
-    shader_animation_pose_resolve,
-    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
-} from "../renderer/animation/shader_animation_pose_resolve.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 { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
-import { MaterialProperty } from "../renderer/object_property/MaterialProperty.js";
-import { Node3DProperty } from "../renderer/object_property/Node3DProperty.js";
-import { ObjectType } from "../renderer/object_property/ObjectType.js";
-import { graph_scene_update_transform_hierarchy } from "../renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js";
-import { graph_import_buffer } from "../renderer/shader/graph/graph_import_buffer.js";
-
-/**
- * Length of one full clip cycle, in seconds. The bob and the rotation
- * share a single clip (so they're driven by one `time`); we pick a
- * common period and lay out both curves to loop cleanly within it.
- */
-const LOOP_DURATION_SECONDS = 3;
-
-/**
- * Min/max Y of the cube as it bobs.
- */
-const CUBE_Y_LOW = 0.6;
-const CUBE_Y_HIGH = 5.5;
-
-/**
- * Min / max scale factor for the child cube's pulsate animation.
- * Visible at runtime as the small cube growing and shrinking.
- */
-const PULSATE_SCALE_LOW = 0.4;
-const PULSATE_SCALE_HIGH = 1.6;
-
-/**
- * Build four curves (x, y, z, w) describing one full quaternion cycle for a
- * rotation around `axis`. Over `period_seconds`, the cube rotates by 4π
- * (two full visual revolutions) — this is the *quaternion* period: q(0)
- * and q(2π) differ by sign even though they represent the same rotation,
- * so a single visual rotation does not loop cleanly without going through
- * 4π and returning to the initial quaternion.
- *
- * Each channel is sampled at 9 evenly-spaced keyframes spanning the period
- * and given smoothed Catmull-Rom-like tangents. The resulting cubic Hermite
- * curves closely approximate the underlying sinusoidal trajectory; any
- * residual drift off the unit 4-sphere is corrected by the apply step's
- * `normalize`.
- *
- * @param {Vector3} axis Unit axis of rotation.
- * @param {number} period_seconds Duration of one full cycle.
- * @returns {{x: AnimationCurve, y: AnimationCurve, z: AnimationCurve, w: AnimationCurve}}
- */
-function make_rotation_curves(axis, period_seconds) {
-    const SAMPLES = 8; // segments — 9 keyframes total
-    const TWO_PI = Math.PI * 2;
-
-    const x_keys = [];
-    const y_keys = [];
-    const z_keys = [];
-    const w_keys = [];
-
-    for (let i = 0; i <= SAMPLES; i++) {
-        const t = (i / SAMPLES) * period_seconds;
-        // half-angle goes from 0 to 2π → full angle from 0 to 4π
-        const half_theta = (i / SAMPLES) * TWO_PI;
-        const s = Math.sin(half_theta);
-        const c = Math.cos(half_theta);
-
-        x_keys.push(Keyframe.from(t, axis.x * s));
-        y_keys.push(Keyframe.from(t, axis.y * s));
-        z_keys.push(Keyframe.from(t, axis.z * s));
-        w_keys.push(Keyframe.from(t, c));
-    }
-
-    const x = AnimationCurve.from(x_keys);
-    const y = AnimationCurve.from(y_keys);
-    const z = AnimationCurve.from(z_keys);
-    const w = AnimationCurve.from(w_keys);
-
-    x.alignAllTangents();
-    y.alignAllTangents();
-    z.alignAllTangents();
-    w.alignAllTangents();
-
-    return { x, y, z, w };
-}
-
-/**
- * Build a 3-channel (R/G/B) animation track from a list of `[Color, time]`
- * keyframes. Each colour stop becomes one keyframe per channel, with
- * smoothed tangents to give a continuous Hermite curve. The returned
- * track has its alpha channel masked off — `MaterialProperty.AlbedoColor`
- * will leave the existing alpha value untouched on apply.
- *
- * @param {GPUAnimationManager} manager
- * @param {Array<[Color, number]>} stops `[colour, timestamp]` pairs in
- *     chronological order. At least one pair required.
- * @returns {number} track id
- */
-function make_color_track(manager, stops) {
-    const r_keys = [];
-    const g_keys = [];
-    const b_keys = [];
-
-    for (let i = 0; i < stops.length; i++) {
-        const [colour, t] = stops[i];
-        r_keys.push(Keyframe.from(t, colour.r));
-        g_keys.push(Keyframe.from(t, colour.g));
-        b_keys.push(Keyframe.from(t, colour.b));
-    }
-
-    const r_curve_def = AnimationCurve.from(r_keys);
-    const g_curve_def = AnimationCurve.from(g_keys);
-    const b_curve_def = AnimationCurve.from(b_keys);
-
-    r_curve_def.alignAllTangents();
-    g_curve_def.alignAllTangents();
-    b_curve_def.alignAllTangents();
-
-    const r_curve = manager.add_curve(r_curve_def);
-    const g_curve = manager.add_curve(g_curve_def);
-    const b_curve = manager.add_curve(b_curve_def);
-
-    // Mask is derived from the named channels — alpha is omitted, so its
-    // bit stays clear and the apply step preserves the destination's alpha.
-    return manager.add_track({
-        x: r_curve,
-        y: g_curve,
-        z: b_curve,
-    });
-}
-
-/**
- * Build the animation prototype scene: a cube simultaneously bobbing up and
- * down, spinning around a tilted axis, and shifting through the rainbow,
- * above a flat plane and lit by a directional sun. Animation runs entirely
- * on the GPU; the only per-frame CPU work is to advance the clip's `time`.
- *
- * Two separate playbacks drive two separate tracks (one scalar Y, one
- * 4-channel quaternion) with different periods, exercising:
- *  - per-binding playback indirection (each binding picks its own `time`),
- *  - simultaneous evaluation of multiple curves on a single instance,
- *  - the `MeshRotation` apply path that writes a quaternion into the mesh
- *    transform's rotation 3×3.
- *
- * @param {object} args
- * @param {Renderer} args.renderer
- * @param {Scene} args.scene
- * @param {OrbitalCameraController} args.controller
- */
-export function animation_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";
-
-    // ── Cube (the animated instance) ────────────────────────────
-    const cube_material = new StandardShadeMaterial();
-    cube_material.diffuse_color.parse("#F2994A");
-    cube_material.roughness_factor = 0.6;
-    cube_material.metallic_factor = 0;
-
-    // Set the CPU position to the midpoint of the animation range so the
-    // CPU-side bounding box used for culling roughly covers where the cube
-    // will actually appear at runtime.
-    const cube_transform = Transform.fromJSON({
-        position: { x: 0, y: (CUBE_Y_LOW + CUBE_Y_HIGH) * 0.5, z: 0 },
-    });
-
-    const cube = Mesh.from(
-        new BoxGeometry(1, 1, 1),
-        cube_material,
-        cube_transform.matrix,
-    );
-    cube.name = "AnimatedCube";
-
-    // ── Child cube (pulsates, parented to the bobbing cube) ─────
-    //
-    // Sits offset along the parent's local +X axis so as the parent
-    // rotates the child sweeps around it; the child's own Scale
-    // animation grows and shrinks the box independently. The child's
-    // local matrix is in the *parent's* coordinate space — actual
-    // world placement falls out of the GPU scene-graph propagation
-    // pass that runs each frame after the animation/apply.
-    const cube_child_material = new StandardShadeMaterial();
-    cube_child_material.diffuse_color.parse("#56CCF2");
-    cube_child_material.roughness_factor = 0.4;
-    cube_child_material.metallic_factor = 0;
-
-    const cube_child_transform = Transform.fromJSON({
-        position: { x: 1.5, y: 0, z: 0 },
-    });
-
-    const cube_child = Mesh.from(
-        // Half the parent's footprint so it reads as a satellite, not
-        // another primary object.
-        new BoxGeometry(0.5, 0.5, 0.5),
-        cube_child_material,
-        cube_child_transform.matrix,
-    );
-    cube_child.name = "PulsatingChildCube";
-
-    // Hierarchy goes through Node3D's scene-graph machinery — sets
-    // parent/children pointers on both ends and refreshes the global
-    // matrix. GPUSceneContext.build picks the parent up via
-    // mesh.parent and writes it into the GPU NODE3D record.
-    cube.addChild(cube_child);
-    cube.updateMatrices();
-
-    // Order matters: each instance's index in the scene's GPU instance
-    // buffer is its position in the order added. The animation
-    // bindings below rely on these indices being stable.
-    // cube_child is added implicitly by Scene.add(cube) walking children —
-    // re-adding here would duplicate it in the InstanceBatch and shift
-    // the cube_child node id off CUBE_CHILD_INSTANCE_INDEX = 2.
-    scene.add(cube);
-    scene.add(plane);
-
-    // Node ids 1 and 2: meshes start at row 1 of the transforms table —
-    // row 0 is reserved for the scene root (NODE3D_SCENE_ID). Insertion
-    // order into `scene` decides which mesh gets which id.
-    const CUBE_INSTANCE_INDEX = 1;
-    const CUBE_CHILD_INSTANCE_INDEX = 2;
-
-    // ── Camera ──────────────────────────────────────────────────
-    {
-        const camera_position = new Vector3(3.5, 2.5, 4.5);
-        const cube_center = new Vector3(0, (CUBE_Y_LOW + CUBE_Y_HIGH) * 0.5, 0);
-        controller.look(camera_position, cube_center);
-        controller.camera.near = 0.05;
-        controller.camera.far = 50;
-    }
-
-    // ── Animation setup ─────────────────────────────────────────
-    // Animation manager is owned by the scene context — fetch it via
-    // the scene context, don't construct a separate one. Multiple
-    // animation managers per scene would each have their own database
-    // and skin-matrices buffer, which would defeat the skinning
-    // pipeline's assumption of a single source of truth.
-    const animation_manager = renderer.scenes.obtain(scene).animation_manager;
-
-    // Up-down bob: low → high → low across one full clip cycle. Smoothed
-    // tangents give an ease in/out feel.
-    const bob_curve_def = AnimationCurve.from([
-        Keyframe.from(0, CUBE_Y_LOW),
-        Keyframe.from(LOOP_DURATION_SECONDS * 0.5, CUBE_Y_HIGH),
-        Keyframe.from(LOOP_DURATION_SECONDS, CUBE_Y_LOW),
-    ]);
-    bob_curve_def.alignAllTangents();
-
-    const bob_curve = animation_manager.add_curve(bob_curve_def);
-    // Y-only translation track: mask is derived from the named channels,
-    // so this drives only the Y component and leaves X/Z untouched.
-    const bob_track = animation_manager.add_track({ y: bob_curve });
-
-    // Rotation around a tilted axis — picks a non-axis-aligned vector so
-    // every component of the quaternion gets engaged during the cycle.
-    // Period matches the bob so they share one clip / one `time`.
-    const rotation_axis = new Vector3(1, 1, 0.4);
-    rotation_axis.normalize();
-
-    const rotation_curves_def = make_rotation_curves(rotation_axis, LOOP_DURATION_SECONDS);
-
-    const rot_curve_x = animation_manager.add_curve(rotation_curves_def.x);
-    const rot_curve_y = animation_manager.add_curve(rotation_curves_def.y);
-    const rot_curve_z = animation_manager.add_curve(rotation_curves_def.z);
-    const rot_curve_w = animation_manager.add_curve(rotation_curves_def.w);
-
-    const rot_track = animation_manager.add_track({
-        x: rot_curve_x,
-        y: rot_curve_y,
-        z: rot_curve_z,
-        w: rot_curve_w,
-    });
-
-    // Rainbow scroll across the clip cycle. We sample fully-saturated
-    // hues at evenly-spaced timestamps and let make_color_track lay out
-    // a 3-channel (RGB) track — alpha is masked off so the material's
-    // existing alpha is preserved.
-    const RAINBOW_STOPS = 8;
-    const rainbow_keyframes = [];
-    for (let i = 0; i <= RAINBOW_STOPS; i++) {
-        const t = (i / RAINBOW_STOPS) * LOOP_DURATION_SECONDS;
-        // hue wraps at i = RAINBOW_STOPS so the loop closes on the same colour
-        const hue = i / RAINBOW_STOPS;
-        rainbow_keyframes.push([Color.fromHSV(hue, 1, 1), t]);
-    }
-    const color_track = make_color_track(animation_manager, rainbow_keyframes);
-
-    // Uniform pulsate: scale factor traces low → high → low across one
-    // clip cycle. Smoothed tangents give a breathing-out / breathing-in
-    // feel. A single curve drives all three of x/y/z so the cube grows
-    // and shrinks uniformly — see the Node3DProperty.Scale docs for
-    // the per-axis mask convention.
-    const pulsate_curve_def = AnimationCurve.from([
-        Keyframe.from(0,                              PULSATE_SCALE_LOW),
-        Keyframe.from(LOOP_DURATION_SECONDS * 0.5,    PULSATE_SCALE_HIGH),
-        Keyframe.from(LOOP_DURATION_SECONDS,          PULSATE_SCALE_LOW),
-    ]);
-    pulsate_curve_def.alignAllTangents();
-
-    const pulsate_curve = animation_manager.add_curve(pulsate_curve_def);
-    const pulsate_track = animation_manager.add_track({
-        x: pulsate_curve,
-        y: pulsate_curve,
-        z: pulsate_curve,
-    });
-
-    // One clip with four bound tracks. The clip's `time` drives all of
-    // them — exactly the situation an unbound clip-template would describe
-    // (e.g. a "run" clip with bound tracks for each bone of a skeleton).
-    //
-    // `instance` is a packed object handle. The Node3D handle has
-    // `ObjectType.Node3D = 0` in the upper 8 bits, so the bare node id
-    // is already the correct value — the *_INSTANCE_INDEX constants are
-    // direct node ids assigned by `GPUSceneContext.build` (scene at 0,
-    // meshes at 1, 2, …, in insertion order). The material handle needs
-    // the type bits set explicitly.
-    const cube_material_handle = (ObjectType.Material << 24) | cube_material.id;
-    const cube_clip = animation_manager.add_clip({
-        time: 0,
-        bindings: [
-            {
-                track: bob_track,
-                instance: CUBE_INSTANCE_INDEX,
-                property: Node3DProperty.Translation,
-            },
-            {
-                track: rot_track,
-                instance: CUBE_INSTANCE_INDEX,
-                property: Node3DProperty.Rotation,
-            },
-            {
-                track: color_track,
-                instance: cube_material_handle,
-                property: MaterialProperty.AlbedoColor,
-            },
-            {
-                track: pulsate_track,
-                instance: CUBE_CHILD_INSTANCE_INDEX,
-                property: Node3DProperty.Scale,
-            },
-        ],
-    });
-
-    // Expose for debugging from the console.
-    window.animation_manager = animation_manager;
-
-    // ── Per-frame: advance both `time`s, dispatch evaluation ────
-    //
-    // We fire on `onFrameFinished`, which is dispatched at the end of the
-    // renderer's frame. Our compute pass writes into the scene's instance
-    // buffer; the *next* frame's rasterization picks up the new transform.
-    // That introduces a one-frame lag versus `time`, which is fine for a
-    // visual prototype.
-    //
-    // Skipping while the scene's instance buffer is still empty: it gets
-    // its real allocation only on the first call to `GPUSceneContext.build()`,
-    // which happens during the first render.
-    const start_time_ms = performance.now();
-
-    renderer.onFrameFinished.add(() => {
-        const elapsed_s = (performance.now() - start_time_ms) * 1e-3;
-
-        animation_manager.set_time(cube_clip, elapsed_s % LOOP_DURATION_SECONDS);
-
-        const gpu_scene = renderer.scenes.obtain(scene);
-        const scene_database_buffer = gpu_scene.scene_database_buffer;
-
-        if (scene_database_buffer === undefined) {
-            // Scene hasn't been built yet — nothing to write into.
-            return;
-        }
-
-        const apply_dispatch_groups = animation_manager.database
-            .get('animation_bound_track_groups')
-            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
-        if (apply_dispatch_groups === 0) {
-            return;
-        }
-
-        // Size the pose accumulator to cover every allocated row of
-        // the transforms table — apply writes by absolute row index,
-        // resolve iterates the table via page iterator. Grow on
-        // demand; idempotent when capacity already suffices.
-        const transforms_table = gpu_scene.scene_database.get('transforms');
-        const resolve_dispatch_groups = transforms_table.dispatch_group_count(
-            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
-        );
-        const pose_accumulator_rows = transforms_table.dispatch_page_count
-            * transforms_table.descriptor.elements_per_page;
-        animation_manager.ensure_pose_accumulator_capacity(pose_accumulator_rows);
-
-        const cmd = ShadeGPUCommandContext.create(
-            renderer.graphics,
-            "AnimationPrototype/Tick"
-        );
-
-        // Direct dispatches — the database upload shaders need to run before
-        // the FrameGraph passes that read from the database. They share the
-        // same command context, so ordering across submits is preserved.
-        animation_manager.update(cmd);
-
-        const graph = new FrameGraph("AnimationPrototype/Tick");
-
-        // ── Imported existing resources ────────────────────────
-        const gr_animation_database = graph_import_buffer(
-            graph, animation_manager.database.buffer, "animation_database"
-        );
-        const gr_scene_database = graph_import_buffer(
-            graph, scene_database_buffer, "scene_database"
-        );
-        const gr_materials = graph_import_buffer(
-            graph, gpu_scene.materials.metadata_table.buffer, "materials"
-        );
-        const gr_pose_accumulator = graph_import_buffer(
-            graph, animation_manager.pose_accumulator_buffer, "pose_accumulator"
-        );
-
-        // ── Pass 1: animation apply ───────────────────────────
-        // Atomic-adds weighted per-binding values into the pose
-        // accumulator (Node3D properties) and writes material
-        // properties directly. Materials and the accumulator are
-        // both written here; the accumulator is drained by the
-        // resolve pass next.
-        const apply_data = {};
-        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
-            shader_animation_apply.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: apply_dispatch_groups,
-                bindings: {
-                    animation_database: resources.get(data.animation_database),
-                    pose_accumulator: resources.get(data.pose_accumulator),
-                    materials: resources.get(data.materials),
-                },
-            });
-        });
-
-        apply_data.animation_database = apply_pass.read(gr_animation_database);
-        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
-        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
-
-        // ── Pass 2: pose resolve ──────────────────────────────
-        // Drains the accumulator into transforms_table.local_*,
-        // normalizes rotation, and zeros the slot for next frame.
-        // One thread per transforms-table row via page iterator.
-        const resolve_data = {};
-        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
-            if (resolve_dispatch_groups === 0) {
-                return;
-            }
-            shader_animation_pose_resolve.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: resolve_dispatch_groups,
-                bindings: {
-                    scene_database: resources.get(data.scene_database),
-                    pose_accumulator: resources.get(data.pose_accumulator),
-                },
-            });
-        });
-
-        resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
-        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
-
-        // ── Pass 3: propagate node.local → node.global ─────────
-        // Rasterization reads node.global; this pass walks the scene
-        // graph and derives global from local + parent.global. Chain
-        // off `resolve_data.scene_database` so propagation sees the
-        // freshly-resolved locals.
-        graph_scene_update_transform_hierarchy({
-            graph,
-            scene: gpu_scene,
-            scene_database: resolve_data.scene_database,
-        });
-
-        cmd.encodeGraph(graph);
-        cmd.finish();
-    });
-}
+import { Color } from "../../core/color/Color.js";
+import Vector3 from "../../core/geom/Vector3.js";
+import { AnimationCurve } from "../../engine/animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../engine/animation/curve/Keyframe.js";
+import { Transform } from "../../engine/ecs/transform/Transform.js";
+import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
+import { shader_animation_apply, WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE } from "../renderer/animation/shader_animation_apply.js";
+import {
+    shader_animation_pose_resolve,
+    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
+} from "../renderer/animation/shader_animation_pose_resolve.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 { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../renderer/scene/Mesh.js";
+import { MaterialProperty } from "../renderer/object_property/MaterialProperty.js";
+import { Node3DProperty } from "../renderer/object_property/Node3DProperty.js";
+import { ObjectType } from "../renderer/object_property/ObjectType.js";
+import { graph_scene_update_transform_hierarchy } from "../renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js";
+import { graph_import_buffer } from "../renderer/shader/graph/graph_import_buffer.js";
+
+/**
+ * Length of one full clip cycle, in seconds. The bob and the rotation
+ * share a single clip (so they're driven by one `time`); we pick a
+ * common period and lay out both curves to loop cleanly within it.
+ */
+const LOOP_DURATION_SECONDS = 3;
+
+/**
+ * Min/max Y of the cube as it bobs.
+ */
+const CUBE_Y_LOW = 0.6;
+const CUBE_Y_HIGH = 5.5;
+
+/**
+ * Min / max scale factor for the child cube's pulsate animation.
+ * Visible at runtime as the small cube growing and shrinking.
+ */
+const PULSATE_SCALE_LOW = 0.4;
+const PULSATE_SCALE_HIGH = 1.6;
+
+/**
+ * Build four curves (x, y, z, w) describing one full quaternion cycle for a
+ * rotation around `axis`. Over `period_seconds`, the cube rotates by 4π
+ * (two full visual revolutions) — this is the *quaternion* period: q(0)
+ * and q(2π) differ by sign even though they represent the same rotation,
+ * so a single visual rotation does not loop cleanly without going through
+ * 4π and returning to the initial quaternion.
+ *
+ * Each channel is sampled at 9 evenly-spaced keyframes spanning the period
+ * and given smoothed Catmull-Rom-like tangents. The resulting cubic Hermite
+ * curves closely approximate the underlying sinusoidal trajectory; any
+ * residual drift off the unit 4-sphere is corrected by the apply step's
+ * `normalize`.
+ *
+ * @param {Vector3} axis Unit axis of rotation.
+ * @param {number} period_seconds Duration of one full cycle.
+ * @returns {{x: AnimationCurve, y: AnimationCurve, z: AnimationCurve, w: AnimationCurve}}
+ */
+function make_rotation_curves(axis, period_seconds) {
+    const SAMPLES = 8; // segments — 9 keyframes total
+    const TWO_PI = Math.PI * 2;
+
+    const x_keys = [];
+    const y_keys = [];
+    const z_keys = [];
+    const w_keys = [];
+
+    for (let i = 0; i <= SAMPLES; i++) {
+        const t = (i / SAMPLES) * period_seconds;
+        // half-angle goes from 0 to 2π → full angle from 0 to 4π
+        const half_theta = (i / SAMPLES) * TWO_PI;
+        const s = Math.sin(half_theta);
+        const c = Math.cos(half_theta);
+
+        x_keys.push(Keyframe.from(t, axis.x * s));
+        y_keys.push(Keyframe.from(t, axis.y * s));
+        z_keys.push(Keyframe.from(t, axis.z * s));
+        w_keys.push(Keyframe.from(t, c));
+    }
+
+    const x = AnimationCurve.from(x_keys);
+    const y = AnimationCurve.from(y_keys);
+    const z = AnimationCurve.from(z_keys);
+    const w = AnimationCurve.from(w_keys);
+
+    x.alignAllTangents();
+    y.alignAllTangents();
+    z.alignAllTangents();
+    w.alignAllTangents();
+
+    return { x, y, z, w };
+}
+
+/**
+ * Build a 3-channel (R/G/B) animation track from a list of `[Color, time]`
+ * keyframes. Each colour stop becomes one keyframe per channel, with
+ * smoothed tangents to give a continuous Hermite curve. The returned
+ * track has its alpha channel masked off — `MaterialProperty.AlbedoColor`
+ * will leave the existing alpha value untouched on apply.
+ *
+ * @param {GPUAnimationManager} manager
+ * @param {Array<[Color, number]>} stops `[colour, timestamp]` pairs in
+ *     chronological order. At least one pair required.
+ * @returns {number} track id
+ */
+function make_color_track(manager, stops) {
+    const r_keys = [];
+    const g_keys = [];
+    const b_keys = [];
+
+    for (let i = 0; i < stops.length; i++) {
+        const [colour, t] = stops[i];
+        r_keys.push(Keyframe.from(t, colour.r));
+        g_keys.push(Keyframe.from(t, colour.g));
+        b_keys.push(Keyframe.from(t, colour.b));
+    }
+
+    const r_curve_def = AnimationCurve.from(r_keys);
+    const g_curve_def = AnimationCurve.from(g_keys);
+    const b_curve_def = AnimationCurve.from(b_keys);
+
+    r_curve_def.alignAllTangents();
+    g_curve_def.alignAllTangents();
+    b_curve_def.alignAllTangents();
+
+    const r_curve = manager.add_curve(r_curve_def);
+    const g_curve = manager.add_curve(g_curve_def);
+    const b_curve = manager.add_curve(b_curve_def);
+
+    // Mask is derived from the named channels — alpha is omitted, so its
+    // bit stays clear and the apply step preserves the destination's alpha.
+    return manager.add_track({
+        x: r_curve,
+        y: g_curve,
+        z: b_curve,
+    });
+}
+
+/**
+ * Build the animation prototype scene: a cube simultaneously bobbing up and
+ * down, spinning around a tilted axis, and shifting through the rainbow,
+ * above a flat plane and lit by a directional sun. Animation runs entirely
+ * on the GPU; the only per-frame CPU work is to advance the clip's `time`.
+ *
+ * Two separate playbacks drive two separate tracks (one scalar Y, one
+ * 4-channel quaternion) with different periods, exercising:
+ *  - per-binding playback indirection (each binding picks its own `time`),
+ *  - simultaneous evaluation of multiple curves on a single instance,
+ *  - the `MeshRotation` apply path that writes a quaternion into the mesh
+ *    transform's rotation 3×3.
+ *
+ * @param {object} args
+ * @param {Renderer} args.renderer
+ * @param {Scene} args.scene
+ * @param {OrbitalCameraController} args.controller
+ */
+export function animation_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";
+
+    // ── Cube (the animated instance) ────────────────────────────
+    const cube_material = new StandardShadeMaterial();
+    cube_material.diffuse_color.parse("#F2994A");
+    cube_material.roughness_factor = 0.6;
+    cube_material.metallic_factor = 0;
+
+    // Set the CPU position to the midpoint of the animation range so the
+    // CPU-side bounding box used for culling roughly covers where the cube
+    // will actually appear at runtime.
+    const cube_transform = Transform.fromJSON({
+        position: { x: 0, y: (CUBE_Y_LOW + CUBE_Y_HIGH) * 0.5, z: 0 },
+    });
+
+    const cube = Mesh.from(
+        new BoxGeometry(1, 1, 1),
+        cube_material,
+        cube_transform.matrix,
+    );
+    cube.name = "AnimatedCube";
+
+    // ── Child cube (pulsates, parented to the bobbing cube) ─────
+    //
+    // Sits offset along the parent's local +X axis so as the parent
+    // rotates the child sweeps around it; the child's own Scale
+    // animation grows and shrinks the box independently. The child's
+    // local matrix is in the *parent's* coordinate space — actual
+    // world placement falls out of the GPU scene-graph propagation
+    // pass that runs each frame after the animation/apply.
+    const cube_child_material = new StandardShadeMaterial();
+    cube_child_material.diffuse_color.parse("#56CCF2");
+    cube_child_material.roughness_factor = 0.4;
+    cube_child_material.metallic_factor = 0;
+
+    const cube_child_transform = Transform.fromJSON({
+        position: { x: 1.5, y: 0, z: 0 },
+    });
+
+    const cube_child = Mesh.from(
+        // Half the parent's footprint so it reads as a satellite, not
+        // another primary object.
+        new BoxGeometry(0.5, 0.5, 0.5),
+        cube_child_material,
+        cube_child_transform.matrix,
+    );
+    cube_child.name = "PulsatingChildCube";
+
+    // Hierarchy goes through Node3D's scene-graph machinery — sets
+    // parent/children pointers on both ends and refreshes the global
+    // matrix. GPUSceneContext.build picks the parent up via
+    // mesh.parent and writes it into the GPU NODE3D record.
+    cube.addChild(cube_child);
+    cube.updateMatrices();
+
+    // Order matters: each instance's index in the scene's GPU instance
+    // buffer is its position in the order added. The animation
+    // bindings below rely on these indices being stable.
+    // cube_child is added implicitly by Scene.add(cube) walking children —
+    // re-adding here would duplicate it in the InstanceBatch and shift
+    // the cube_child node id off CUBE_CHILD_INSTANCE_INDEX = 2.
+    scene.add(cube);
+    scene.add(plane);
+
+    // Node ids 1 and 2: meshes start at row 1 of the transforms table —
+    // row 0 is reserved for the scene root (NODE3D_SCENE_ID). Insertion
+    // order into `scene` decides which mesh gets which id.
+    const CUBE_INSTANCE_INDEX = 1;
+    const CUBE_CHILD_INSTANCE_INDEX = 2;
+
+    // ── Camera ──────────────────────────────────────────────────
+    {
+        const camera_position = new Vector3(3.5, 2.5, 4.5);
+        const cube_center = new Vector3(0, (CUBE_Y_LOW + CUBE_Y_HIGH) * 0.5, 0);
+        controller.look(camera_position, cube_center);
+        controller.camera.near = 0.05;
+        controller.camera.far = 50;
+    }
+
+    // ── Animation setup ─────────────────────────────────────────
+    // Animation manager is owned by the scene context — fetch it via
+    // the scene context, don't construct a separate one. Multiple
+    // animation managers per scene would each have their own database
+    // and skin-matrices buffer, which would defeat the skinning
+    // pipeline's assumption of a single source of truth.
+    const animation_manager = renderer.scenes.obtain(scene).animation_manager;
+
+    // Up-down bob: low → high → low across one full clip cycle. Smoothed
+    // tangents give an ease in/out feel.
+    const bob_curve_def = AnimationCurve.from([
+        Keyframe.from(0, CUBE_Y_LOW),
+        Keyframe.from(LOOP_DURATION_SECONDS * 0.5, CUBE_Y_HIGH),
+        Keyframe.from(LOOP_DURATION_SECONDS, CUBE_Y_LOW),
+    ]);
+    bob_curve_def.alignAllTangents();
+
+    const bob_curve = animation_manager.add_curve(bob_curve_def);
+    // Y-only translation track: mask is derived from the named channels,
+    // so this drives only the Y component and leaves X/Z untouched.
+    const bob_track = animation_manager.add_track({ y: bob_curve });
+
+    // Rotation around a tilted axis — picks a non-axis-aligned vector so
+    // every component of the quaternion gets engaged during the cycle.
+    // Period matches the bob so they share one clip / one `time`.
+    const rotation_axis = new Vector3(1, 1, 0.4);
+    rotation_axis.normalize();
+
+    const rotation_curves_def = make_rotation_curves(rotation_axis, LOOP_DURATION_SECONDS);
+
+    const rot_curve_x = animation_manager.add_curve(rotation_curves_def.x);
+    const rot_curve_y = animation_manager.add_curve(rotation_curves_def.y);
+    const rot_curve_z = animation_manager.add_curve(rotation_curves_def.z);
+    const rot_curve_w = animation_manager.add_curve(rotation_curves_def.w);
+
+    const rot_track = animation_manager.add_track({
+        x: rot_curve_x,
+        y: rot_curve_y,
+        z: rot_curve_z,
+        w: rot_curve_w,
+    });
+
+    // Rainbow scroll across the clip cycle. We sample fully-saturated
+    // hues at evenly-spaced timestamps and let make_color_track lay out
+    // a 3-channel (RGB) track — alpha is masked off so the material's
+    // existing alpha is preserved.
+    const RAINBOW_STOPS = 8;
+    const rainbow_keyframes = [];
+    for (let i = 0; i <= RAINBOW_STOPS; i++) {
+        const t = (i / RAINBOW_STOPS) * LOOP_DURATION_SECONDS;
+        // hue wraps at i = RAINBOW_STOPS so the loop closes on the same colour
+        const hue = i / RAINBOW_STOPS;
+        rainbow_keyframes.push([Color.fromHSV(hue, 1, 1), t]);
+    }
+    const color_track = make_color_track(animation_manager, rainbow_keyframes);
+
+    // Uniform pulsate: scale factor traces low → high → low across one
+    // clip cycle. Smoothed tangents give a breathing-out / breathing-in
+    // feel. A single curve drives all three of x/y/z so the cube grows
+    // and shrinks uniformly — see the Node3DProperty.Scale docs for
+    // the per-axis mask convention.
+    const pulsate_curve_def = AnimationCurve.from([
+        Keyframe.from(0,                              PULSATE_SCALE_LOW),
+        Keyframe.from(LOOP_DURATION_SECONDS * 0.5,    PULSATE_SCALE_HIGH),
+        Keyframe.from(LOOP_DURATION_SECONDS,          PULSATE_SCALE_LOW),
+    ]);
+    pulsate_curve_def.alignAllTangents();
+
+    const pulsate_curve = animation_manager.add_curve(pulsate_curve_def);
+    const pulsate_track = animation_manager.add_track({
+        x: pulsate_curve,
+        y: pulsate_curve,
+        z: pulsate_curve,
+    });
+
+    // One clip with four bound tracks. The clip's `time` drives all of
+    // them — exactly the situation an unbound clip-template would describe
+    // (e.g. a "run" clip with bound tracks for each bone of a skeleton).
+    //
+    // `instance` is a packed object handle. The Node3D handle has
+    // `ObjectType.Node3D = 0` in the upper 8 bits, so the bare node id
+    // is already the correct value — the *_INSTANCE_INDEX constants are
+    // direct node ids assigned by `GPUSceneContext.build` (scene at 0,
+    // meshes at 1, 2, …, in insertion order). The material handle needs
+    // the type bits set explicitly.
+    const cube_material_handle = (ObjectType.Material << 24) | cube_material.id;
+    const cube_clip = animation_manager.add_clip({
+        time: 0,
+        bindings: [
+            {
+                track: bob_track,
+                instance: CUBE_INSTANCE_INDEX,
+                property: Node3DProperty.Translation,
+            },
+            {
+                track: rot_track,
+                instance: CUBE_INSTANCE_INDEX,
+                property: Node3DProperty.Rotation,
+            },
+            {
+                track: color_track,
+                instance: cube_material_handle,
+                property: MaterialProperty.AlbedoColor,
+            },
+            {
+                track: pulsate_track,
+                instance: CUBE_CHILD_INSTANCE_INDEX,
+                property: Node3DProperty.Scale,
+            },
+        ],
+    });
+
+    // Expose for debugging from the console.
+    window.animation_manager = animation_manager;
+
+    // ── Per-frame: advance both `time`s, dispatch evaluation ────
+    //
+    // We fire on `onFrameFinished`, which is dispatched at the end of the
+    // renderer's frame. Our compute pass writes into the scene's instance
+    // buffer; the *next* frame's rasterization picks up the new transform.
+    // That introduces a one-frame lag versus `time`, which is fine for a
+    // visual prototype.
+    //
+    // Skipping while the scene's instance buffer is still empty: it gets
+    // its real allocation only on the first call to `GPUSceneContext.build()`,
+    // which happens during the first render.
+    const start_time_ms = performance.now();
+
+    renderer.onFrameFinished.add(() => {
+        const elapsed_s = (performance.now() - start_time_ms) * 1e-3;
+
+        animation_manager.set_time(cube_clip, elapsed_s % LOOP_DURATION_SECONDS);
+
+        const gpu_scene = renderer.scenes.obtain(scene);
+        const scene_database_buffer = gpu_scene.scene_database_buffer;
+
+        if (scene_database_buffer === undefined) {
+            // Scene hasn't been built yet — nothing to write into.
+            return;
+        }
+
+        const apply_dispatch_groups = animation_manager.database
+            .get('animation_bound_track_groups')
+            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
+        if (apply_dispatch_groups === 0) {
+            return;
+        }
+
+        // Size the pose accumulator to cover every allocated row of
+        // the transforms table — apply writes by absolute row index,
+        // resolve iterates the table via page iterator. Grow on
+        // demand; idempotent when capacity already suffices.
+        const transforms_table = gpu_scene.scene_database.get('transforms');
+        const resolve_dispatch_groups = transforms_table.dispatch_group_count(
+            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
+        );
+        const pose_accumulator_rows = transforms_table.dispatch_page_count
+            * transforms_table.descriptor.elements_per_page;
+        animation_manager.ensure_pose_accumulator_capacity(pose_accumulator_rows);
+
+        const cmd = ShadeGPUCommandContext.create(
+            renderer.graphics,
+            "AnimationPrototype/Tick"
+        );
+
+        // Direct dispatches — the database upload shaders need to run before
+        // the FrameGraph passes that read from the database. They share the
+        // same command context, so ordering across submits is preserved.
+        animation_manager.update(cmd);
+
+        const graph = new FrameGraph("AnimationPrototype/Tick");
+
+        // ── Imported existing resources ────────────────────────
+        const gr_animation_database = graph_import_buffer(
+            graph, animation_manager.database.buffer, "animation_database"
+        );
+        const gr_scene_database = graph_import_buffer(
+            graph, scene_database_buffer, "scene_database"
+        );
+        const gr_materials = graph_import_buffer(
+            graph, gpu_scene.materials.metadata_table.buffer, "materials"
+        );
+        const gr_pose_accumulator = graph_import_buffer(
+            graph, animation_manager.pose_accumulator_buffer, "pose_accumulator"
+        );
+
+        // ── Pass 1: animation apply ───────────────────────────
+        // Atomic-adds weighted per-binding values into the pose
+        // accumulator (Node3D properties) and writes material
+        // properties directly. Materials and the accumulator are
+        // both written here; the accumulator is drained by the
+        // resolve pass next.
+        const apply_data = {};
+        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
+            shader_animation_apply.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: apply_dispatch_groups,
+                bindings: {
+                    animation_database: resources.get(data.animation_database),
+                    pose_accumulator: resources.get(data.pose_accumulator),
+                    materials: resources.get(data.materials),
+                },
+            });
+        });
+
+        apply_data.animation_database = apply_pass.read(gr_animation_database);
+        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
+        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
+
+        // ── Pass 2: pose resolve ──────────────────────────────
+        // Drains the accumulator into transforms_table.local_*,
+        // normalizes rotation, and zeros the slot for next frame.
+        // One thread per transforms-table row via page iterator.
+        const resolve_data = {};
+        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
+            if (resolve_dispatch_groups === 0) {
+                return;
+            }
+            shader_animation_pose_resolve.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: resolve_dispatch_groups,
+                bindings: {
+                    scene_database: resources.get(data.scene_database),
+                    pose_accumulator: resources.get(data.pose_accumulator),
+                },
+            });
+        });
+
+        resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
+        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
+
+        // ── Pass 3: propagate node.local → node.global ─────────
+        // Rasterization reads node.global; this pass walks the scene
+        // graph and derives global from local + parent.global. Chain
+        // off `resolve_data.scene_database` so propagation sees the
+        // freshly-resolved locals.
+        graph_scene_update_transform_hierarchy({
+            graph,
+            scene: gpu_scene,
+            scene_database: resolve_data.scene_database,
+        });
+
+        cmd.encodeGraph(graph);
+        cmd.finish();
+    });
+}