@woosh/meep-engine 3.40.0 → 3.42.0

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

@@ -0,0 +1,154 @@
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { EntityManager } from "../../../engine/ecs/EntityManager.js";
+import { Entity } from "../../../engine/ecs/Entity.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Light } from "../../../engine/graphics/ecs/light/Light.js";
+import { GraphicsEngine } from "../../../engine/graphics3/GraphicsEngine.js";
+import { LightSystem } from "../../../engine/graphics3/LightSystem.js";
+import { ShadedGeometrySystem } from "../../../engine/graphics3/ShadedGeometrySystem.js";
+import { WaterSystem } from "../../../engine/graphics3/WaterSystem.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
+import { sgpt_read_capture } from "../../device/timing/profile/sgpt_read_capture.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import { build_world } from "./world.js";
+
+const element = id => document.getElementById(id);
+const number = id => Number(element(id).value);
+
+/** Where each stop looks from, its near and far planes, and the splash and raindrop radii there. */
+const STOPS = {
+    cup: { body: 'cup', eye: [0.16, 0.98, 0.16], target: [0, 0.83, 0], near: 0.003, far: 400, splash: 0.005, drop: 0.002 },
+    puddle: { body: 'puddle', eye: [5.0, 0.9, 2.3], target: [4, 0, 1], near: 0.02, far: 2000, splash: 0.03, drop: 0.004 },
+    lake: { body: 'lake', eye: [22, 4, 188], target: [0, -1, 166], near: 0.1, far: 6000, splash: 0.3, drop: 0.01 },
+    ocean: { body: 'ocean', eye: [0, 9, 5000 + 150], target: [25, 0, 5000 + 230], near: 0.2, far: 12000, splash: 3, drop: 0.02 },
+    aerial: { body: 'ocean', eye: [700, 320, 4300], target: [0, 0, 5000], near: 0.5, far: 12000, splash: 3, drop: 0.02 },
+};
+
+async function main() {
+    const viewport = element("viewport"), graphics = new GraphicsEngine(), scene = new Scene();
+    viewport.appendChild(graphics.viewport.el);
+    const dataset = new EntityComponentDataset(), entities = new EntityManager();
+    const water_system = new WaterSystem(graphics, scene);
+    entities.addSystem(new ShadedGeometrySystem(graphics, scene));
+    entities.addSystem(new LightSystem(graphics, scene));
+    entities.addSystem(water_system);
+    entities.attachDataset(dataset);
+    await new Promise((resolve, reject) => entities.startup(resolve, reject));
+    const world = await build_world(dataset);
+    load_default_environment(scene);
+
+    const sun = new Light(); sun.intensity.set(2.4);
+    const sun_pose = new Transform64(), rotation = new Quaternion();
+    // low and ahead of the views, so its glitter path shows the slopes
+    rotation.fromUnitVectors(Vector3.forward, new Vector3(-0.15, -0.3, -0.94).normalize());
+    sun_pose.setRotation(rotation.x, rotation.y, rotation.z, rotation.w); sun_pose.updateMatrix();
+    new Entity().add(sun).add(sun_pose).build(dataset);
+
+    const camera = graphics.camera.camera, controller = new OrbitalCameraController(camera, viewport);
+    camera.fov = Math.PI / 3;
+    let stop = STOPS.cup;
+    function go(name) {
+        stop = STOPS[name];
+        camera.near = stop.near; camera.far = stop.far;
+        controller.look(new Vector3(...stop.eye), new Vector3(...stop.target));
+        for (const button of document.querySelectorAll("button.stop")) { button.style.borderColor = button.dataset.stop === name ? "#8dd3db" : ""; }
+    }
+    function configure() {
+        const lines = [];
+        for (const [name, body] of Object.entries(world.bodies)) {
+            body.waves.windSpeed.set(body.base_wind * number("wind"));
+            body.waves.windDirection.set(number("direction") * Math.PI / 180);
+            lines.push(`${name.padEnd(7)} ${(body.base_wind * number("wind")).toFixed(1)} m/s${body.waves.upwindFetch.getValue() > 0 ? `, ${body.waves.upwindFetch.getValue() / 1000} km of sea upwind` : ''}`);
+        }
+        element("winds").textContent = lines.join("\n");
+    }
+    const report = message => { element("status").textContent = message; };
+    for (const id of ["wind", "direction"]) { element(id).addEventListener("input", configure); }
+    for (const button of document.querySelectorAll("button.stop")) { button.onclick = () => go(button.dataset.stop); }
+    configure(); go("cup");
+
+    // a click splashes where its ray meets the stop's body at rest
+    const inverse = new Float64Array(16);
+    function splash_at(u, v, radius) {
+        const body = world.bodies[stop.body];
+        if (!m4_invert(inverse, camera.view_projection_matrix)) { return; }
+        const unproject = z => {
+            const x = 2 * u - 1, y = 1 - 2 * v;
+            const w = inverse[3] * x + inverse[7] * y + inverse[11] * z + inverse[15];
+            return [0, 1, 2].map(i => (inverse[i] * x + inverse[4 + i] * y + inverse[8 + i] * z + inverse[12 + i]) / w);
+        };
+        const near = unproject(1), far = unproject(0.5);
+        const direction = far.map((value, i) => value - near[i]);
+        if (Math.abs(direction[1]) < 1e-9) { return; }
+        const t = (body.level - near[1]) / direction[1];
+        if (!(t > 0)) { return; }
+        water_system.splash(body.entity, near.map((value, i) => value + direction[i] * t), radius, number("kick"));
+    }
+    viewport.addEventListener("click", event => {
+        const rect = viewport.getBoundingClientRect();
+        splash_at((event.clientX - rect.left) / rect.width, (event.clientY - rect.top) / rect.height, stop.splash);
+    });
+
+    let paused = false, ready = false, rain_debt = 0;
+    element("pause").onclick = () => { paused = !paused; element("pause").textContent = paused ? "Resume" : "Pause"; };
+    graphics.on.contextFailed.add(error => report(error.message));
+    graphics.on.contextLost.add(error => { ready = false; report(`GPU device lost · ${error.message}`); });
+    await graphics.start();
+    const renderer = graphics.renderer;
+    renderer.graphics.device.addEventListener("uncapturederror", event => { ready = false; report(event.error.message); console.error(event.error.message); });
+    const profile = install_profile_hotkey({ renderer, name: "water_surface", status: element("status"), target: viewport,
+        settings: () => [stop.body, `wind × ${number("wind")}`, element("rain").checked ? `rain ${number("rate")}/s` : 'no rain'] });
+    element("profile").onclick = () => profile.toggle().catch(error => report(error.message));
+
+    element("measure").onclick = async () => {
+        element("report").textContent = "recording…";
+        const session = new GPUProfileSession({ level: GPUProfileLevel.WORKLOAD, note: 'water_surface measure' });
+        renderer.profile_session = session; session.start();
+        await new Promise(resolve => setTimeout(resolve, 2500));
+        renderer.profile_session = null;
+        const bytes = await session.stop();
+        const capture = sgpt_read_capture(bytes instanceof ArrayBuffer ? bytes : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+        const sums = new Map();
+        let frames = 0, total = 0;
+        for (const frame of capture.frames) {
+            if (!frame.spans || frame.spans.length === 0) { continue; }
+            frames++;
+            for (const span of frame.spans) {
+                total += span.duration_ns;
+                if (!/^Water \/ (spectrum|waves|particles|classify)/.test(span.label)) { continue; }
+                sums.set(span.label, (sums.get(span.label) ?? 0) + span.duration_ns);
+            }
+        }
+        const rows = [...sums.entries()].sort((a, b) => b[1] - a[1]);
+        const surface = rows.reduce((sum, [, ns]) => sum + ns, 0);
+        element("report").textContent = [`${frames} frames · every pass ${(total / frames / 1000).toFixed(0)} µs · surface ${(surface / frames / 1000).toFixed(1)} µs`,
+            ...rows.map(([label, ns]) => `${(ns / frames / 1000).toFixed(1).padStart(7)}  ${label.replace('Water / ', '')}`)].join("\n");
+    };
+
+    ready = true; report("Ready · click the water to splash");
+    Object.assign(globalThis, { graphics, scene, dataset, entities, world, water_system, camera, controller,
+        water_surface_playground: { go, splash_at, get ready() { return ready; } } });
+
+    create_frame_loop(raw_dt => {
+        if (!ready) { return; }
+        const dt = paused ? 0 : Math.min(raw_dt, 0.05);
+        if (element("rain").checked && dt > 0) {
+            rain_debt += number("rate") * dt;
+            for (; rain_debt >= 1; rain_debt--) { splash_at(Math.random(), 0.3 + 0.7 * Math.random(), stop.drop); }
+        }
+        graphics.viewport.size.set(Math.max(1, viewport.clientWidth), Math.max(1, viewport.clientHeight));
+        controller.update();
+        entities.update(dt);
+        graphics.render(dt);
+    }, 60);
+}
+
+main().catch(error => { console.error(error); element("status").textContent = error.message; });

package/src/shade/playground/water_surface/world.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Four bodies of water, from a cup to an ocean, each a `Water` + `WaterWaves` entity whose mesh authors
+ * only its outline: the surface's detail comes from the waves, at any scale.
+ */
+export function build_world(dataset: any): Promise<{
+    bodies: {
+        cup: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+        puddle: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+        lake: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+        ocean: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+    };
+}>;
+import Water from "../../../engine/graphics/ecs/water/Water.js";
+import WaterWaves from "../../../engine/graphics/ecs/water/WaterWaves.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+//# sourceMappingURL=world.d.ts.map

package/src/shade/playground/water_surface/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_surface/world.js"],"names":[],"mappings":"AAsGA;;;GAGG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDC;kBA3JiB,6CAA6C;uBACxC,kDAAkD;4BAH7C,8CAA8C"}

package/src/shade/playground/water_surface/world.js

@@ -0,0 +1,160 @@
+import { Color } from "../../../core/color/Color.js";
+import { Entity } from "../../../engine/ecs/Entity.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import Water from "../../../engine/graphics/ecs/water/Water.js";
+import WaterWaves from "../../../engine/graphics/ecs/water/WaterWaves.js";
+import { Attribute } from "../../renderer/geometry/Attribute.js";
+import { Geometry } from "../../renderer/geometry/Geometry.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
+import { make_box_geometry } from "../../renderer/geometry/primitives/make_box_geometry.js";
+import { make_cylinder_geometry } from "../../renderer/geometry/primitives/make_cylinder_geometry.js";
+import { StandardAttributes } from "../../renderer/geometry/StandardAttributes.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { water_medium_preset } from "../../renderer/medium/water/water_presets.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { ColorSpace } from "../../renderer/texture/ColorSpace.js";
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
+
+function pose(x, y, z) {
+    const transform = new Transform64();
+    transform.setTranslation(x, y, z);
+    transform.updateMatrix();
+    return transform;
+}
+
+let checker_texture = null;
+/** Sharp light and dark squares, one per UV unit: what refraction bends shows the slopes without a sky. */
+function checker() {
+    if (checker_texture !== null) { return checker_texture; }
+    const size = 512, data = Sampler2D.uint8(4, size, size);
+    for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+        const bright = ((x >> 8) + (y >> 8)) % 2 === 0;
+        data.data.set(bright ? [215, 220, 200, 255] : [42, 66, 84, 255], (y * size + x) * 4);
+    }
+    const image = ShadeImage.fromSampler2D(data); image.color_space = ColorSpace.SRGB;
+    return checker_texture = ShadeTexture.from(image);
+}
+
+function material(rgb, roughness = 0.8, textured = false) {
+    const m = new StandardShadeMaterial();
+    m.diffuse_color.copy(new Color(...rgb, 1));
+    m.metallic_factor = 0; m.roughness_factor = roughness; m.draw_side = ShadeDrawSide.Double;
+    if (textured) { m.texture_albedo = checker(); }
+    return m;
+}
+
+function meshlets(geometry) {
+    const result = new MeshletGeometry();
+    meshlet_geometry_build_from_geometry(geometry, result);
+    return result;
+}
+
+/**
+ * A polar mesh in local xz, wound to face +y: rings of `segments` vertices at radii `radius(theta, t)` for
+ * t from 0 to 1, at heights `height(theta, t)`. A disk has a centre vertex for t = 0; with `hole`, t = 0 is a
+ * ring, and the mesh an annulus. Texture coordinates are local xz over `texel` metres: two checker squares.
+ */
+function polar_geometry({ segments, rings, radius, height = () => 0, hole = false, texel = 1 }) {
+    const positions = [], normals = [], uvs = [], index = [];
+    const centre = !hole;
+    if (centre) { positions.push(0, height(0, 0), 0); normals.push(0, 1, 0); uvs.push(0, 0); }
+    const first = centre ? 1 : 0;
+    const ring_count = centre ? rings : rings + 1;
+    for (let r = 0; r < ring_count; r++) {
+        const t = centre ? (r + 1) / rings : r / rings;
+        for (let s = 0; s < segments; s++) {
+            const theta = 2 * Math.PI * s / segments;
+            const rho = radius(theta, t);
+            positions.push(Math.cos(theta) * rho, height(theta, t), Math.sin(theta) * rho);
+            normals.push(0, 1, 0);
+            uvs.push(Math.cos(theta) * rho / texel, Math.sin(theta) * rho / texel);
+        }
+    }
+    const vertex = (r, s) => first + r * segments + (s % segments);
+    const triangle = (a, b, c) => {
+        const p = i => [positions[3 * i], positions[3 * i + 1], positions[3 * i + 2]];
+        const [pa, pb, pc] = [p(a), p(b), p(c)];
+        const ny = (pb[2] - pa[2]) * (pc[0] - pa[0]) - (pb[0] - pa[0]) * (pc[2] - pa[2]);
+        if (ny >= 0) { index.push(a, b, c); } else { index.push(a, c, b); }
+    };
+    if (centre) { for (let s = 0; s < segments; s++) { triangle(0, vertex(0, s), vertex(0, s + 1)); } }
+    for (let r = 0; r + 1 < ring_count; r++) {
+        for (let s = 0; s < segments; s++) {
+            triangle(vertex(r, s), vertex(r + 1, s), vertex(r + 1, s + 1));
+            triangle(vertex(r, s), vertex(r + 1, s + 1), vertex(r, s + 1));
+        }
+    }
+    const geometry = new Geometry();
+    geometry.index = Attribute.from(new Uint32Array(index), 1, 'index');
+    geometry.addAttribute(Attribute.from(new Float32Array(positions), 3, StandardAttributes.Position));
+    geometry.addAttribute(Attribute.from(new Float32Array(normals), 3, StandardAttributes.Normal));
+    geometry.addAttribute(Attribute.from(new Float32Array(uvs), 2, StandardAttributes.TextureCoordinates0));
+    return geometry;
+}
+
+/** A wobbly outline of mean radius one, the same for the water and the ground around it. */
+const wobble = (seed, amount) => theta => 1 + amount * (0.6 * Math.sin(3 * theta + seed) + 0.4 * Math.sin(5 * theta + 2 * seed));
+
+/**
+ * Four bodies of water, from a cup to an ocean, each a `Water` + `WaterWaves` entity whose mesh authors
+ * only its outline: the surface's detail comes from the waves, at any scale.
+ */
+export async function build_world(dataset) {
+    await MeshoptClusterizer.ready;
+    const build = builder => { builder.build(dataset); return builder.id; };
+    const solid = (geometry, m, x, y, z) => {
+        const shaded = new ShadedGeometry(); shaded.geometry = meshlets(geometry); shaded.material = m;
+        return build(new Entity().add(pose(x, y, z)).add(shaded));
+    };
+    const water_body = ({ geometry, x, y, z, preset, wind, upwind = 0, reflection = 0.5, roughness = 0.02 }) => {
+        const water = new Water();
+        water.medium = water_medium_preset({ preset });
+        water.roughness.set(roughness);
+        const waves = new WaterWaves();
+        waves.windSpeed.set(wind); waves.upwindFetch.set(upwind); waves.shoreReflection.set(reflection);
+        const transform = pose(x, y, z);
+        const entity = build(new Entity().add(water).add(waves).add(meshlets(geometry)).add(transform));
+        return { entity, water, waves, transform, level: y, base_wind: wind };
+    };
+
+    // a floor for the cup's table and the puddle
+    solid(polar_geometry({ segments: 48, rings: 6, radius: (theta, t) => 40 * t, texel: 0.5 }), material([1, 1, 1], 0.8, true), 0, 0, 0);
+
+    // a cup of tea on a table: 4 cm across, 7 cm deep
+    solid(make_box_geometry(1.2, 0.75, 0.8), material([0.45, 0.28, 0.16], 0.5), 0, 0.375, 0);
+    solid(make_cylinder_geometry(0.045, 0.04, 0.095, 32, 1, true), material([0.92, 0.92, 0.9], 0.3), 0, 0.75 + 0.0475, 0);
+    solid(polar_geometry({ segments: 32, rings: 1, radius: (theta, t) => 0.04 * t, texel: 0.02 }), material([1, 1, 1], 0.3, true), 0, 0.751, 0);
+    const cup = water_body({ geometry: polar_geometry({ segments: 32, rings: 2, radius: (theta, t) => 0.0435 * t }),
+        x: 0, y: 0.83, z: 0, preset: 'swimming_pool', wind: 2, reflection: 0.9 });
+
+    // a puddle on the floor: a centimetre deep, two metres across
+    const puddle_outline = wobble(1.3, 0.25);
+    const puddle = water_body({ geometry: polar_geometry({ segments: 64, rings: 3, radius: (theta, t) => 1.0 * t * puddle_outline(theta) }),
+        x: 4, y: 0.01, z: 1, preset: 'swimming_pool', wind: 4, reflection: 0.2 });
+
+    // a mountain lake, 120 × 60 m, in a basin whose shore is its outline
+    const lake_outline = wobble(0.4, 0.15);
+    const lake_radius = (theta, t) => t * lake_outline(theta) * (60 - 30 * Math.sin(theta) ** 2);
+    const lake = water_body({ geometry: polar_geometry({ segments: 96, rings: 6, radius: lake_radius }),
+        x: 0, y: 0, z: 160, preset: 'tropical_lagoon', wind: 6, reflection: 0.3 });
+    solid(polar_geometry({ segments: 96, rings: 24, radius: (theta, t) => lake_radius(theta, 3 * t),
+        height: (theta, t) => { const f = 3 * t; return f < 1 ? -4 * (1 - f * f) : 18 * ((f - 1) / 2) ** 2; }, texel: 4 }),
+        material([0.75, 0.85, 0.65], 0.8, true), 0, 0, 160);
+
+    // an open ocean disk, 5 km across, around an island the mesh leaves a hole for; the sea runs on for 200 km upwind
+    const ocean_x = 0, ocean_z = 5000;
+    const island = wobble(2.1, 0.12);
+    const ocean = water_body({ geometry: polar_geometry({ segments: 128, rings: 24, hole: true,
+        radius: (theta, t) => { const rim = 130 * island(theta); return rim * (2500 / rim) ** t; } }),
+        x: ocean_x, y: 0, z: ocean_z, preset: 'clear_ocean', wind: 10, upwind: 200000, reflection: 0.6 });
+    solid(polar_geometry({ segments: 128, rings: 48, radius: (theta, t) => 2600 * t * t,
+        height: (theta, t) => { const r = 2600 * t * t / (220 * island(theta)); return r < 1 ? 60 - 100 * r ** 1.2 : -40; }, texel: 16 }),
+        material([0.95, 0.9, 0.75], 0.8, true), ocean_x, 0, ocean_z);
+
+    return { bodies: { cup, puddle, lake, ocean } };
+}

package/src/shade/renderer/animation/ANIMATION_TRACK_BINDING_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ANIMATION_TRACK_BINDING_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_TRACK_BINDING_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,0DA0B4B;6BApCC,gCAAgC"}
+{"version":3,"file":"ANIMATION_TRACK_BINDING_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_TRACK_BINDING_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,0DAmC4B;6BA7CC,gCAAgC"}

package/src/shade/renderer/animation/ANIMATION_TRACK_BINDING_STRUCT.js

@@ -1,4 +1,4 @@
-import { u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { u32, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
 
 /**
@@ -35,4 +35,13 @@ export const ANIMATION_TRACK_BINDING_STRUCT = WebGPUStruct.from({
      * apply pass reads the time and weight to evaluate the track at.
      */
     clip: u32,
+
+    /**
+     * The rotation the target rests at, `(x, y, z, w)`: what a Node3D target's rotation resolves to
+     * when every rotation contributed to it in a frame sums to nothing — every clip that rotates it
+     * playing at weight zero. The row cannot answer that itself: once a clip has written it, it
+     * holds that clip's pose, not the rest. Read only by a Node3D rotation binding, and the same on
+     * every binding of one target, since all of them are written from the target's rest.
+     */
+    rest_rotation: vec4f,
 }, "AnimationTrackBinding");

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -93,9 +93,10 @@ export class GPUAnimationManager {
      * by the per-frame dispatch driver after `scene.build` has
      * stabilised the transforms-table size for the frame.
      *
-     * Grow destroys the previous GPU buffer; resolve always leaves the
-     * accumulator zeroed at the end of each frame, so there's nothing
-     * to copy across the realloc.
+     * Grow destroys the previous GPU buffer; resolve drains every sum
+     * and dirty mask at the end of each frame, and a slot's rest
+     * rotation is stored afresh by every frame that reads it, so there's
+     * nothing to copy across the realloc.
      *
      * @param {number} row_count
      */
@@ -180,11 +181,15 @@ export class GPUAnimationManager {
      * playing, not looping). The clip is inert at creation — call
      * {@link start} to begin GPU-side time advancement.
      *
+     * Each binding states its target's `rest_rotation`, `[x, y, z, w]`: what a Node3D target's
+     * rotation resolves to in a frame where every rotation contributed to it sums to nothing. Only
+     * a Node3D rotation binding reads it; {@link register_clip} takes it from the target entity.
+     *
      * @param {{
      *     time?: number,
      *     time_start?: number,
      *     time_end?: number,
-     *     bindings: Array<{ track: number, instance: number, property: number }>,
+     *     bindings: Array<{ track: number, instance: number, property: number, rest_rotation: ArrayLike<number> }>,
      * }} clip
      * @returns {number} clip id (index into the `animation_clips` table)
      */
@@ -196,6 +201,7 @@ export class GPUAnimationManager {
             track: number;
             instance: number;
             property: number;
+            rest_rotation: ArrayLike<number>;
         }>;
     }): number;
     /**

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}