reze-engine 0.56.10 → 0.56.12

package/dist/engine.js

@@ -26,7 +26,7 @@ import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades";
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera, planeFromPointNormal } from "./reflection";
 import { MIRROR_MASK_DOWNSAMPLE_WGSL, MIRROR_MAT_BYTES, mirrorShaderWgsl, mirrorShadowWgsl } from "./shaders/passes/mirror";
 import { packHalf } from "./hdr";
-import { evalIrradianceSH, projectIrradianceSH } from "./ibl";
+import { evalIrradianceSH, projectIrradianceSH, gradientIrradianceSH } from "./ibl";
 import { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, LYRICS_FLOATS, packLyrics } from "./shaders/lyrics-api";
 import { sceneTargets as sceneTargetsFor, sceneColorFormats, setMrtIds, mrtIdsEnabled, SCENE_ID_FORMAT, } from "./shaders/passes/scene-contract";
 import { LIGHT_HEADER, LIGHT_STRIDE, LIGHTS_FLOATS, MAX_LIGHTS, buildLightEmitShader, hasLightEmit, } from "./shaders/lights";
@@ -703,7 +703,7 @@ export class Engine {
         return this.effects[0] ?? null;
     }
     constructor(canvas, options) {
-        this.cameraMatrixData = new Float32Array(36);
+        this.cameraMatrixData = new Float32Array(40);
         // ambient vec4 (4) + 4 lights x 2 vec4 (32) + 9 irradiance-SH vec4s (36),
         // padded to 80. sh[0].w is the IBL flag: 0 = flat world colour, 1 = the sky.
         this.lightData = new Float32Array(80);
@@ -1011,6 +1011,9 @@ export class Engine {
         this.worldEquirectTexture = null;
         this.worldEquirectView = null;
         this.worldStrength = 1;
+        /** A three-colour sky's irradiance SH, when the world is a gradient rather
+         *  than a picture. An HDRI outranks it — see writeWorld. */
+        this.worldGradientSH = null;
         /** The installed HDRI's folded irradiance SH (27 floats), or null. */
         this.worldSH = null;
         // The scene's user WGSL effect (setEffect). ONE per scene, mounted under the
@@ -1175,6 +1178,37 @@ export class Engine {
         /** A pose pushed in from outside — see setCameraPose. Reapplied every frame,
          *  so it outranks the orbit AND a loaded track for as long as it is set. */
         this.cameraPoseOverride = null;
+        /**
+         * The per-frame bind groups, the camera's and the mirror's.
+         *
+         * A METHOD rather than two literals at init, because one of their resources
+         * changes after it: the world's sky texture is swapped whenever an HDRI is
+         * installed or cleared, and a bind group holds the view it was built with.
+         * The mirror's is identical but for the camera — a reflection is the same
+         * scene lit the same way, seen from a reflected eye.
+         */
+        /**
+         * Skies this engine has replaced, kept alive rather than destroyed.
+         *
+         * NOT DESTROYED AT ALL, after three attempts that each deferred it further:
+         * one frame, then three, then "once both bind groups have rebuilt". Every one
+         * still produced "destroyed texture used in a submit" somewhere — a command
+         * buffer encoded before the swap, a rebuild that bailed on half-built
+         * resources, an engine torn down by a hot reload whose last frame is still in
+         * flight. The engine cannot see all of those, and each attempt to enumerate
+         * them found another.
+         *
+         * So the trade is taken explicitly: a replaced sky is a megabyte or two held
+         * until the page goes away, against a validation error every frame. A scene
+         * swaps its world a handful of times in a session, and the GPU frees all of
+         * it when the device does.
+         */
+        this.retiredSkies = [];
+        /** A world was installed or cleared and the bind groups that name its texture
+         *  may not have been rebuilt yet — both rebuilds bail when their own
+         *  resources are half-built, which is exactly the moment a host swaps a sky.
+         *  Retried at the top of a frame until one of them takes. */
+        this.worldBindingsDirty = false;
         /** Per cascade: does its map currently hold nothing but the cleared far plane?
          *  Set by the cascade loop, which skips a cascade that is unwanted and already
          *  cleared rather than re-clearing it every frame. */
@@ -1215,6 +1249,9 @@ export class Engine {
         this.cpuRenderMs = 0;
         this.frameAnimMsRaw = 0;
         this.framePhysicsMsRaw = 0;
+        /** How far the loaded scene reaches from the origin, in world units — the
+         *  largest any model has ever needed. */
+        this.sceneExtent = 0;
         /** Every shadow caster in one sphere: (x, y, z, radius). radius 0 = nothing
          *  casts, -1 = do not use (a rigid caster has no sphere). See updateCasterSphere. */
         /** A card's own texture, by model key — see setPlaneFrame. */
@@ -2406,11 +2443,14 @@ export class Engine {
             errors: [...this.gpuErrors].map(([message, count]) => ({ message, count })),
         };
     }
+    /** Returns whether it actually rebuilt: a caller retrying after a resource
+     *  swap has to know, because a bail leaves the previous group — and the
+     *  previous group names the texture the swap replaced. */
     rebuildCompositeBindGroup() {
         if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView || !this.depthReadView)
-            return;
+            return false;
         if (!this.castBuffer)
-            return;
+            return false;
         // BEFORE the entries below, not after: they ask fieldPairUsed which effects
         // draw, and that answer includes whether an effect has its field bind group
         // yet. Building the composite first and the field groups second would bind
@@ -2445,6 +2485,7 @@ export class Engine {
                 { binding: 21, resource: this.fieldLayerView(this.fieldFgViews[1], 1) },
             ],
         });
+        return true;
     }
     /**
      * Does any installed effect draw into field pair `layer`?
@@ -2887,7 +2928,14 @@ export class Engine {
      * coefficients, so what lights her is what you see.
      */
     setWorldEquirect(source, options) {
-        this.worldEquirectTexture?.destroy();
+        // RETIRED, NOT DESTROYED. A frame already encoded against the old sky can
+        // still be in flight — the bind groups that name it are rebuilt below, but
+        // the command buffer holding the previous ones is submitted at the end of
+        // the frame this call landed in the middle of. Destroying here is what
+        // produces "Destroyed texture used in a submit"; the next frame's start is
+        // the first moment nothing can be pointing at it.
+        if (this.worldEquirectTexture)
+            this.retiredSkies.push(this.worldEquirectTexture);
         this.worldEquirectTexture = null;
         this.worldEquirectView = null;
         this.worldStrength = Math.max(options?.strength ?? 1, 0);
@@ -2897,13 +2945,49 @@ export class Engine {
             // Scene-linear radiance in rgba16float. The composite treats it as light
             // rather than wallpaper (mode 3) — a sun in it rolls off like a sun,
             // through the same exposure and view transform as the scene.
+            // MIPPED, and the chain is the prefilter a reflection reads: level n is a
+            // box average of the sky over twice the solid angle of n-1, which is what
+            // lets rzWorldSpecular answer a rough surface without a blur pass per
+            // level. Built on the CPU because the source is already float data in
+            // memory and the alternative is a render pipeline per mip.
+            const levels = Math.floor(Math.log2(Math.max(source.width, source.height))) + 1;
             const tex = this.device.createTexture({
                 label: "world equirect (HDR)",
                 size: [source.width, source.height],
                 format: "rgba16float",
+                mipLevelCount: levels,
                 usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
             });
-            this.device.queue.writeTexture({ texture: tex }, packHalf(source.data), { bytesPerRow: source.width * 8, rowsPerImage: source.height }, [source.width, source.height]);
+            let data = source.data;
+            let w = source.width;
+            let h = source.height;
+            for (let level = 0; level < levels; level++) {
+                if (level > 0) {
+                    const nw = Math.max(1, w >> 1);
+                    const nh = Math.max(1, h >> 1);
+                    const down = new Float32Array(nw * nh * 4);
+                    for (let y = 0; y < nh; y++) {
+                        for (let x = 0; x < nw; x++) {
+                            const x0 = Math.min(x * 2, w - 1);
+                            const x1 = Math.min(x * 2 + 1, w - 1);
+                            const y0 = Math.min(y * 2, h - 1);
+                            const y1 = Math.min(y * 2 + 1, h - 1);
+                            for (let c = 0; c < 4; c++) {
+                                down[(y * nw + x) * 4 + c] =
+                                    (data[(y0 * w + x0) * 4 + c] +
+                                        data[(y0 * w + x1) * 4 + c] +
+                                        data[(y1 * w + x0) * 4 + c] +
+                                        data[(y1 * w + x1) * 4 + c]) *
+                                        0.25;
+                            }
+                        }
+                    }
+                    data = down;
+                    w = nw;
+                    h = nh;
+                }
+                this.device.queue.writeTexture({ texture: tex, mipLevel: level }, packHalf(data), { bytesPerRow: w * 8, rowsPerImage: h }, [w, h]);
+            }
             this.worldEquirectTexture = tex;
             this.worldEquirectView = tex.createView();
             // The sky lights the scene, not only backs it. The sun keeps the toon
@@ -2917,6 +3001,12 @@ export class Engine {
         }
         if (this.worldSH || hadSH)
             this.writeWorld();
+        // The MATERIAL groups too, not only the composite's: a surface that
+        // reflects the sky samples this very texture, so a world swapped after
+        // init would otherwise keep reflecting the one it replaced. Marked as well,
+        // because either rebuild may bail on resources that are not up yet.
+        this.worldBindingsDirty = true;
+        this.rebuildPerFrameBindGroups();
         this.rebuildCompositeBindGroup();
         if (this.device && this.compositeUniformBuffer)
             this.writeCompositeViewUniforms();
@@ -3890,6 +3980,13 @@ export class Engine {
      * uniform, so nothing recompiles.
      */
     allocateLightSlots() {
+        // BEFORE INIT IS A REAL CALLER. A host sets a scene's lamps from an effect
+        // that runs as soon as its state exists, which on a hot reload is before
+        // the engine has a device — and every public setter here has to survive
+        // that, the way setWorldEquirect does. The buffers are written from the
+        // engine's own state at init, so nothing is lost by returning.
+        if (!this.device)
+            return;
         let next = this.docLightCount;
         for (const e of this.effects) {
             if (!e.lights)
@@ -5423,8 +5520,11 @@ export class Engine {
                 // The positional lights. Always bound, empty or not, so every material
                 // pipeline shares one layout whether or not the scene has any.
                 { binding: 6, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
-                // The far cascade's shadow map. 8 stays free; 9 is the BRDF LUT.
+                // The far cascade's shadow map, then the world's sky (8) and the BRDF
+                // LUT (9). The sky is always bound — the 1x1 fallback when the scene
+                // has none — so every material pipeline keeps sharing one layout.
                 { binding: 7, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "depth" } },
+                { binding: 8, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
                 { binding: 9, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
             ],
         });
@@ -5658,6 +5758,18 @@ export class Engine {
             usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
         });
         this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightsData);
+        // BEFORE the per-frame groups, which bind it. The composite needs this 1x1
+        // stand-in too, and it used to be created with the composite's own
+        // resources further down — far enough down that a material group built up
+        // here had nothing to put on its sky binding, and every draw went out with
+        // no bind group at index 0.
+        this.fallbackEquirectTexture = this.device.createTexture({
+            label: "equirect fallback",
+            size: [1, 1],
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        this.fallbackEquirectView = this.fallbackEquirectTexture.createView();
         // Zero-filled = zero lines, which every accessor answers gracefully.
         this.lyricsBuffer = this.device.createBuffer({
             label: "lyrics",
@@ -5674,39 +5786,7 @@ export class Engine {
         });
         this.lyricsTextureView = this.lyricsTexture.createView();
         // Now that shadow resources exist, create the main per-frame bind group
-        this.perFrameBindGroup = this.device.createBindGroup({
-            label: "main per-frame bind group",
-            layout: this.mainPerFrameBindGroupLayout,
-            entries: [
-                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
-                { binding: 1, resource: { buffer: this.lightUniformBuffer } },
-                { binding: 2, resource: this.materialSampler },
-                { binding: 3, resource: this.shadowMapDepthViews[0] },
-                { binding: 4, resource: this.shadowComparisonSampler },
-                { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
-                { binding: 6, resource: { buffer: this.lightsBuffer } },
-                { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
-                { binding: 9, resource: this.brdfLutView },
-            ],
-        });
-        // The mirror's, identical but for the camera — same lights, same shadow
-        // maps, because a reflection is the same scene lit the same way, seen from
-        // a reflected eye.
-        this.mirrorPerFrameBindGroup = this.device.createBindGroup({
-            label: "mirror per-frame bind group",
-            layout: this.mainPerFrameBindGroupLayout,
-            entries: [
-                { binding: 0, resource: { buffer: this.mirrorCameraBuffer } },
-                { binding: 1, resource: { buffer: this.lightUniformBuffer } },
-                { binding: 2, resource: this.materialSampler },
-                { binding: 3, resource: this.shadowMapDepthViews[0] },
-                { binding: 4, resource: this.shadowComparisonSampler },
-                { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
-                { binding: 6, resource: { buffer: this.lightsBuffer } },
-                { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
-                { binding: 9, resource: this.brdfLutView },
-            ],
-        });
+        this.rebuildPerFrameBindGroups();
         this.groundShadowBindGroupLayout = this.device.createBindGroupLayout({
             label: "ground shadow layout",
             entries: [
@@ -6091,13 +6171,6 @@ export class Engine {
                 { binding: 21, visibility: GPUShaderStage.FRAGMENT, texture: {} },
             ],
         });
-        this.fallbackEquirectTexture = this.device.createTexture({
-            label: "equirect fallback",
-            size: [1, 1],
-            format: "rgba8unorm",
-            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
-        });
-        this.fallbackEquirectView = this.fallbackEquirectTexture.createView();
         this.compositePipelineLayout = this.device.createPipelineLayout({
             bindGroupLayouts: [this.compositeBindGroupLayout],
         });
@@ -7756,6 +7829,67 @@ export class Engine {
         this.writeWorld();
         this.writeSun(0);
     }
+    /** Returns whether it actually rebuilt — see rebuildCompositeBindGroup. */
+    rebuildPerFrameBindGroups() {
+        // EVERY resource, not just the layout. This runs twice: once at init, where
+        // the order is known, and again whenever a world is installed — which the
+        // host may do before init has finished, and a bind group built around an
+        // undefined buffer is a validation error at creation rather than a missing
+        // picture later.
+        if (!this.device ||
+            !this.mainPerFrameBindGroupLayout ||
+            !this.shadowMapDepthViews?.length ||
+            !this.cameraUniformBuffer ||
+            !this.mirrorCameraBuffer ||
+            !this.lightUniformBuffer ||
+            !this.lightsBuffer ||
+            !this.shadowLightVPBuffer ||
+            !this.materialSampler ||
+            !this.shadowComparisonSampler ||
+            !this.brdfLutView ||
+            !(this.worldEquirectView ?? this.fallbackEquirectView)) {
+            return false;
+        }
+        // BOTH ENTRY LISTS ARE WRITTEN OUT, rather than shared through a helper.
+        // tests/bindings.test.mjs reads this file and checks statically that every
+        // bind group covers exactly its layout — it cannot see through a function,
+        // and a missing binding is a validation error at draw time rather than a
+        // compile error here. The duplication is the price of that check.
+        const env = this.worldEquirectView ?? this.fallbackEquirectView;
+        this.perFrameBindGroup = this.device.createBindGroup({
+            label: "main per-frame bind group",
+            layout: this.mainPerFrameBindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+                { binding: 1, resource: { buffer: this.lightUniformBuffer } },
+                { binding: 2, resource: this.materialSampler },
+                { binding: 3, resource: this.shadowMapDepthViews[0] },
+                { binding: 4, resource: this.shadowComparisonSampler },
+                { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
+                { binding: 6, resource: { buffer: this.lightsBuffer } },
+                { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
+                { binding: 8, resource: env },
+                { binding: 9, resource: this.brdfLutView },
+            ],
+        });
+        this.mirrorPerFrameBindGroup = this.device.createBindGroup({
+            label: "mirror per-frame bind group",
+            layout: this.mainPerFrameBindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.mirrorCameraBuffer } },
+                { binding: 1, resource: { buffer: this.lightUniformBuffer } },
+                { binding: 2, resource: this.materialSampler },
+                { binding: 3, resource: this.shadowMapDepthViews[0] },
+                { binding: 4, resource: this.shadowComparisonSampler },
+                { binding: 5, resource: { buffer: this.shadowLightVPBuffer } },
+                { binding: 6, resource: { buffer: this.lightsBuffer } },
+                { binding: 7, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
+                { binding: 8, resource: env },
+                { binding: 9, resource: this.brdfLutView },
+            ],
+        });
+        return true;
+    }
     /**
      * Write world ambient. For a uniform-radiance world, hemispherical irradiance
      * is E = π·L and a Lambertian BRDF reflects (albedo/π)·E = albedo·L, so the
@@ -7766,17 +7900,22 @@ export class Engine {
         this.lightData[0] = this.world.color.x * s;
         this.lightData[1] = this.world.color.y * s;
         this.lightData[2] = this.world.color.z * s;
-        this.lightData[3] = 0;
+        // The spare in the ambient vec4, which rzWorldSpecular multiplies its sky
+        // sample by: the SH carries strength already, the texture cannot.
+        this.lightData[3] = this.world.strength;
         // The sky's irradiance, when an HDRI world is installed — the world
         // STRENGTH dial keeps its meaning by scaling it, and the world COLOUR is
         // simply unread while the flag is up (Blender's own semantics: the image
         // replaces the colour, strength applies to either).
+        // An HDRI outranks a gradient outranks the flat colour, which is the order
+        // of how much each one knows about the sky.
+        const sh = this.worldSH ?? this.worldGradientSH;
         for (let i = 0; i < 9; i++) {
             const b = 36 + i * 4;
-            if (this.worldSH) {
-                this.lightData[b] = this.worldSH[i * 3] * s;
-                this.lightData[b + 1] = this.worldSH[i * 3 + 1] * s;
-                this.lightData[b + 2] = this.worldSH[i * 3 + 2] * s;
+            if (sh) {
+                this.lightData[b] = sh[i * 3] * s;
+                this.lightData[b + 1] = sh[i * 3 + 1] * s;
+                this.lightData[b + 2] = sh[i * 3 + 2] * s;
             }
             else {
                 this.lightData[b] = 0;
@@ -7785,7 +7924,11 @@ export class Engine {
             }
             this.lightData[b + 3] = 0;
         }
-        this.lightData[39] = this.worldSH ? 1 : 0;
+        // WHICH KIND of sky, not merely whether there is one: 2 is a picture a
+        // reflection can be sampled from, 1 is a gradient it can only be fitted to,
+        // 0 is a flat colour. rzWorldSpecular reads this to decide whether to touch
+        // the equirect texture at all.
+        this.lightData[39] = this.worldSH ? 2 : this.worldGradientSH ? 1 : 0;
         this.updateLightBuffer();
     }
     /** Write sun lamp into light slot `index` (0..3). Layout mirrors the WGSL struct. */
@@ -7812,6 +7955,9 @@ export class Engine {
             this.world.color = options.color;
         if (options.strength !== undefined)
             this.world.strength = options.strength;
+        if (options.gradient !== undefined) {
+            this.worldGradientSH = options.gradient ? gradientIrradianceSH(options.gradient) : null;
+        }
         this.writeWorld();
     }
     /** Update the sun lamp (Blender: Light > Sun). Direction change marks shadow VP dirty. */
@@ -7897,6 +8043,11 @@ export class Engine {
      * keep the meaning the caller gave them, which is the same rule the anchor
      * table follows. Passing none (or an empty list) turns the layer off and the
      * scene renders exactly as it did before lights existed.
+     *
+     * A light with an `aim` is a SPOT: it reaches only inside `angle`, full
+     * inside `innerAngle`, and the two are degrees from the axis the way every
+     * tool states a cone. Without one it is a point light, which the shading
+     * spells as a cone that covers everything rather than as a second case.
      */
     setLights(
     /** Structural {x,y,z} rather than the Vec3 class, the same choice effect
@@ -7928,9 +8079,29 @@ export class Engine {
             this.lightsData[b + 4] = Math.max(l.color.x * k, 0);
             this.lightsData[b + 5] = Math.max(l.color.y * k, 0);
             this.lightsData[b + 6] = Math.max(l.color.z * k, 0);
-            // [b + 7] is `type`, reserved: every light is a point light today.
-        }
-        if (list.length) {
+            // A spot only where an aim was given AND it points somewhere: a zero
+            // vector cannot be normalised, and a cone around nothing would light
+            // nothing at all — a light that vanishes because its aim was left at the
+            // default is worse than one that shines everywhere.
+            const len = l.aim ? Math.hypot(l.aim.x, l.aim.y, l.aim.z) : 0;
+            this.lightsData[b + 7] = len > 0 ? 1 : 0;
+            this.lightsData[b + 8] = len > 0 ? l.aim.x / len : 0;
+            this.lightsData[b + 9] = len > 0 ? l.aim.y / len : 0;
+            this.lightsData[b + 10] = len > 0 ? l.aim.z / len : 0;
+            // Half-angles in degrees, as cosines. Ordered so the outer edge is never
+            // inside the inner one — a cone written the other way round would divide
+            // by a negative span and light its own rim instead of its middle.
+            const outer = len > 0 ? Math.cos((Math.min(Math.max(l.angle ?? 45, 0), 179) / 2) * (Math.PI / 180)) : -1;
+            const inner = len > 0 ? Math.cos((Math.min(Math.max(l.innerAngle ?? (l.angle ?? 45) * 0.8, 0), 179) / 2) * (Math.PI / 180)) : -1;
+            this.lightsData[b + 11] = outer;
+            this.lightsData[b + 12] = Math.max(inner, outer);
+            this.lightsData[b + 13] = 0;
+            this.lightsData[b + 14] = 0;
+            this.lightsData[b + 15] = 0;
+        }
+        // The CPU copy is written either way; only the upload needs a device. A
+        // scene whose lamps arrive before init keeps them, and init uploads them.
+        if (list.length && this.device && this.lightsBuffer) {
             this.device.queue.writeBuffer(this.lightsBuffer, LIGHT_HEADER * 4, this.lightsData.buffer, LIGHT_HEADER * 4, list.length * LIGHT_STRIDE * 4);
         }
         // The effects' bases move when the document's count does; the header —
@@ -9812,6 +9983,35 @@ export class Engine {
         this.cullReadback?.shadow.destroy();
         this.cullReadback = null;
     }
+    /**
+     * Tell the camera how big the scene is, so its far plane can cover it.
+     *
+     * MEASURED ON LOAD, from the model's own vertices, and only ever raised. A
+     * stage is the case that matters: framed from ten units away, a sky dome a
+     * thousand units out sits well beyond a far plane derived from the orbit, and
+     * the part of it past that plane is simply not drawn — which looks like a
+     * polygon of background colour that follows the camera, not like clipping.
+     *
+     * Never lowered when a model leaves: the cost of a far plane that is too
+     * generous is depth precision, and the cost of one that is too near is
+     * geometry that vanishes. One of those is a bug report.
+     */
+    noteSceneExtent(model) {
+        const { positions } = model.getGeometry();
+        let most = 0;
+        // Every 16th vertex: an extent is a bound, not a measurement, and a stage
+        // has a quarter of a million of them.
+        for (let i = 0; i + 2 < positions.length; i += 48) {
+            const d = positions[i] * positions[i] + positions[i + 1] * positions[i + 1] + positions[i + 2] * positions[i + 2];
+            if (d > most)
+                most = d;
+        }
+        const extent = Math.sqrt(most);
+        if (extent <= this.sceneExtent)
+            return;
+        this.sceneExtent = extent;
+        this.camera?.setSceneExtent(extent);
+    }
     /**
      * One record per model: the rigid transform its per-material boxes live under,
      * or the world sphere that bounds it in any pose. Written every frame, because
@@ -10477,6 +10677,7 @@ export class Engine {
         const vertices = model.getVertices();
         const skinning = model.getSkinning();
         const skeleton = model.getSkeleton();
+        this.noteSceneExtent(model);
         const boneCount = skeleton.bones.length;
         const matrixSize = boneCount * 16 * 4;
         const vertexBuffer = this.device.createBuffer({
@@ -12330,6 +12531,17 @@ export class Engine {
         this.renderWithDelta(deltaSeconds);
     }
     renderWithDelta(deltaTime) {
+        // The bind groups first, then the textures they used to name. A retired
+        // texture is freed only once a frame has been rebuilt without it — freeing
+        // it while a group still points at it is what "destroyed texture used in a
+        // submit" means, and it repeats every frame because the stale group stays.
+        if (this.worldBindingsDirty) {
+            // Both have to take: either one bailing leaves a group naming the sky
+            // that was replaced, which is a frame drawn against the wrong one.
+            const perFrame = this.rebuildPerFrameBindGroups();
+            const composite = this.rebuildCompositeBindGroup();
+            this.worldBindingsDirty = !(perFrame && composite);
+        }
         // The scene clock, and the only clock a trail may sample on: renderFrame()
         // drives offline export with an exact per-frame delta, so a path recorded
         // against this is reproducible where one recorded against wall time is not.
@@ -13690,6 +13902,11 @@ export class Engine {
         // shader derives the full viewport (width via projection aspect) for its
         // babylon-mmd constant-pixel edge extrusion.
         this.cameraMatrixData[35] = this.canvas.height;
+        // The SCENE clock, which is what a material may animate on: it pauses with
+        // the transport and an export steps it exactly, so a ripple is in the same
+        // place in the file as it was on screen. Wall time would drift between the
+        // two. The buffer was already allocated at 40 floats; this is one of them.
+        this.cameraMatrixData[36] = this.sceneClock;
         this.device.queue.writeBuffer(this.cameraUniformBuffer, 0, this.cameraMatrixData);
         // 360 backdrop: the composite reconstructs each pixel's view ray from the
         // camera basis — refresh it every frame the skybox is active. The view matrix

package/dist/graph/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/graph/registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEzD,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC9B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAA;IAC/C,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC,CAAA;AAYD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,CAoBhE;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAIpE;AAMD,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAM1D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpE;AAyCD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA+nBlD,CAAA"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/graph/registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEzD,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC9B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAA;IAC/C,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC,CAAA;AAYD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,CAoBhE;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAIpE;AAMD,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAM1D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpE;AAyCD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA8pBlD,CAAA"}

package/dist/graph/registry.js

@@ -113,6 +113,15 @@ export const NODE_REGISTRY = {
         outputs: { color: "color", alpha: "float" },
         contextOutputs: { color: "tex_color", alpha: "tex_s.a" },
     },
+    // The scene clock, in seconds. A material is otherwise a function of position
+    // alone — this is what lets one SCROLL: ripples on water, a conveyor, a sign.
+    // It is the same clock the effects read, so a paused scene holds still and an
+    // export steps it frame by frame.
+    time: {
+        inputs: {},
+        outputs: { value: "float" },
+        contextOutputs: { value: "camera.time" },
+    },
     geometry: {
         inputs: {},
         outputs: {
@@ -592,6 +601,26 @@ export const NODE_REGISTRY = {
         outputs: { value: "float" },
         emit: (a) => `layer_weight_facing(${a.blend}, n, v)`,
     },
+    /**
+     * The world's radiance from a direction — Blender's Environment Texture, read
+     * off the scene's own sky rather than off an image a material carries.
+     *
+     * ITS DEFAULT VECTOR IS THE REFLECTION, which is the whole point: wire
+     * nothing and it answers what this surface reflects. The roughness input
+     * picks how blurred the answer is; at 0 it is a mirror.
+     *
+     * A scene with no HDRI has no sky to reflect, and this returns the flat world
+     * colour — the same value the ambient already carries, so such a scene looks
+     * exactly as it did.
+     */
+    environment: {
+        inputs: {
+            vector: { type: "vector", contextDefault: "reflect(-v, n)" },
+            roughness: F(0),
+        },
+        outputs: { color: "color" },
+        emit: (a) => `rzWorldSpecular(${a.vector}, ${a.roughness})`,
+    },
     // ── Lighting capture ──
     /**
      * Shader → RGB on a white diffuse closure, reduced to a scalar.

package/dist/ibl.d.ts

@@ -16,4 +16,32 @@ export declare function evalIrradianceSH(sh: Float32Array, n: {
     y: number;
     z: number;
 }): [number, number, number];
+/**
+ * A three-colour sky as irradiance SH — the same nine coefficients an HDRI
+ * gives, so nothing downstream has to know which kind of world it is looking at.
+ *
+ * The gradient is Unity's trilight and every other engine's "ambient gradient":
+ * one colour straight up, one at the horizon, one straight down, interpolated
+ * by the direction's height. It is what lights a game stage that has no baked
+ * lighting, and it is not a decoration — the fill on a wall facing the sky and
+ * the fill under a roof differ by the whole span between sky and ground.
+ *
+ * Built by SAMPLING IT INTO A SMALL EQUIRECT and projecting that, rather than by
+ * integrating the basis functions in closed form. The analytic route is a page
+ * of coefficients that has to be rederived if the interpolation ever changes;
+ * this is six lines that reuse the projector the HDRI path is already trusted
+ * to get right, and at 64x32 the fit is exact to well under a percent because
+ * the function has no detail finer than the harmonics can hold anyway.
+ */
+type Rgb = {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare function gradientIrradianceSH(g: {
+    sky: Rgb;
+    equator: Rgb;
+    ground: Rgb;
+}): Float32Array;
+export {};
 //# sourceMappingURL=ibl.d.ts.map

package/dist/ibl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ibl.d.ts","sourceRoot":"","sources":["../src/ibl.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAErC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,SAAI,GAAG,YAAY,CA0E3E;AAED;qEACqE;AACrE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAQnH"}
+{"version":3,"file":"ibl.d.ts","sourceRoot":"","sources":["../src/ibl.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAErC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,SAAI,GAAG,YAAY,CA0E3E;AAED;qEACqE;AACrE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAQnH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,KAAK,GAAG,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9C,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAAG,YAAY,CAoB7F"}

package/dist/ibl.js

@@ -111,3 +111,24 @@ export function evalIrradianceSH(sh, n) {
     }
     return out;
 }
+export function gradientIrradianceSH(g) {
+    const w = 64;
+    const h = 32;
+    const data = new Float32Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        // The same parameterisation projectIrradianceSH reads: v runs top to bottom
+        // and the direction's height is cos(pi v).
+        const ny = Math.cos(Math.PI * ((y + 0.5) / h));
+        const t = Math.abs(ny);
+        const a = ny >= 0 ? g.sky : g.ground;
+        const c = [g.equator.x + (a.x - g.equator.x) * t, g.equator.y + (a.y - g.equator.y) * t, g.equator.z + (a.z - g.equator.z) * t];
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            data[i] = c[0];
+            data[i + 1] = c[1];
+            data[i + 2] = c[2];
+            data[i + 3] = 1;
+        }
+    }
+    return projectIrradianceSH({ width: w, height: h, data }, 1);
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_DEPTH_OF_FIELD_OPTIONS, DEFAULT_VIEW_TRANSFORM, DEFAULT_COLOR_GRADING, type ColorGradingOptions, type EngineStats, type EngineOptions, type BloomOptions, type DepthOfFieldOptions, type ViewTransformOptions, type LoadModelFromFilesOptions, type MaterialPreset, type MaterialPresetMap, type ModelTransform, type ModelAttachment, type GizmoDragEvent, type GizmoDragCallback, type GizmoDragKind, type DissolveCycle, type EffectParamValue, type EffectResult, type CullDiagnostics, type MidiNote, } from "./engine";
+export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_DEPTH_OF_FIELD_OPTIONS, DEFAULT_VIEW_TRANSFORM, DEFAULT_COLOR_GRADING, type ColorGradingOptions, type EngineStats, type EngineOptions, type BloomOptions, type DepthOfFieldOptions, type ViewTransformOptions, type LoadModelFromFilesOptions, type MaterialPreset, type MaterialPresetMap, type ModelTransform, type SceneLight, type ModelAttachment, type GizmoDragEvent, type GizmoDragCallback, type GizmoDragKind, type DissolveCycle, type EffectParamValue, type EffectResult, type CullDiagnostics, type MidiNote, } from "./engine";
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload";
 export { parseMidi } from "./midi-loader";
 export { parseHDR, type HdrImage } from "./hdr";