reze-engine 0.56.11 → 0.56.13

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";
@@ -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. */
@@ -7866,6 +8012,7 @@ export class Engine {
         this.hasGround = true;
         this.groundDrawCall = {
             type: "ground",
+            baseType: "ground",
             count: 6,
             firstIndex: 0,
             bindGroup: this.groundShadowBindGroup,
@@ -7953,7 +8100,9 @@ export class Engine {
             this.lightsData[b + 14] = 0;
             this.lightsData[b + 15] = 0;
         }
-        if (list.length) {
+        // 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 —
@@ -9835,6 +9984,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
@@ -10500,6 +10678,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({
@@ -11176,6 +11355,7 @@ export class Engine {
             const type = inst.isPlane ? "opaque" : isTransparent ? "transparent" : "opaque";
             inst.drawCalls.push({
                 type,
+                baseType: type,
                 count: indexCount,
                 firstIndex: currentIndexOffset,
                 bindGroup,
@@ -12353,6 +12533,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.
@@ -13274,6 +13465,19 @@ export class Engine {
             const groupId = install ? wantId : null;
             if (groupId)
                 inst.materialToGroup.set(dc.materialName, groupId);
+            // A HASHED GROUP DRAWS IN THE OPAQUE PHASE. Alpha-to-coverage is the
+            // transparency technique built for that phase — it is why a card already
+            // takes this route — and it is what a cutout wants: crisp edges, depth
+            // written, correct occlusion between layers.
+            //
+            // Foliage is the case that needs it. A leaf card's antialiased edges put
+            // its translucentFrac over the 2% bar, so the whole shrub lands in the
+            // alpha-blend bucket and is drawn in author order: soft haloed leaves
+            // that do not occlude each other, and haze wherever cards overlap. The
+            // game it came from alpha-tests exactly these materials.
+            const type = install?.alphaMode === "hashed" ? "opaque" : dc.baseType;
+            if (dc.type !== type)
+                dc.type = type;
             if (dc.groupId === groupId)
                 continue;
             dc.groupId = groupId;

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,CAyoBlD,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

@@ -601,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/shaders/lights.d.ts

@@ -4,13 +4,23 @@ export declare const LIGHT_HEADER = 4;
 /** Floats per light — see the layout above. */
 export declare const LIGHT_STRIDE = 16;
 /**
- * The cap. The loop below runs per fragment over the lights a scene has, so
- * this bounds the worst case rather than the ordinary one — and it has to clear
- * a game stage: a Unity rip of one arrives with thirty-odd point lights, which
- * the old ceiling of sixteen cut in half. Past this the extras are dropped.
- * Clustering is what replaces it when a scene wants hundreds.
+ * The cap. The loop below runs per fragment over the lights a scene HAS, so
+ * this bounds the worst case rather than the ordinary one, and the buffer is
+ * storage rather than uniform — 128 records is 8 KiB, which costs nothing to
+ * declare and is paid for only by the scenes that fill it.
+ *
+ * Sized against the work, not against a round number: a Unity stage arrives
+ * with a lamp per fixture. One rip of a resort brought thirty-three, a lit
+ * interior brings a hundred or more, and the ceilings of sixteen and then
+ * forty-eight each cut a real scene in half. Past this the extras are dropped.
+ *
+ * What it does NOT buy: a scene that genuinely lights a fragment from a hundred
+ * lamps pays for a hundred iterations of the loop. The distance test below
+ * rejects most of them in a few instructions, which is what makes a rig of this
+ * size affordable at all; clustering is what replaces the linear walk when a
+ * scene wants every one of them close enough to matter.
  */
-export declare const MAX_LIGHTS = 48;
+export declare const MAX_LIGHTS = 128;
 /** Floats in the whole buffer. */
 export declare const LIGHTS_FLOATS: number;
 /**

package/dist/shaders/lights.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../src/shaders/lights.ts"],"names":[],"mappings":"AAwCA;yEACyE;AACzE,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,+CAA+C;AAC/C,eAAO,MAAM,YAAY,KAAK,CAAA;AAC9B;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,kCAAkC;AAClC,eAAO,MAAM,aAAa,QAA2C,CAAA;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,qJAQhC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,idAa9B,CAAA;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5B,UAAU,SAAK,GACd,MAAM,CAiGR;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA0FhE"}
+{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../src/shaders/lights.ts"],"names":[],"mappings":"AAwCA;yEACyE;AACzE,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,+CAA+C;AAC/C,eAAO,MAAM,YAAY,KAAK,CAAA;AAC9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,MAAM,CAAA;AAC7B,kCAAkC;AAClC,eAAO,MAAM,aAAa,QAA2C,CAAA;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,qJAQhC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,idAa9B,CAAA;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5B,UAAU,SAAK,GACd,MAAM,CAiGR;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA0FhE"}