reze-engine 0.57.6 → 0.58.1

package/dist/engine.js

@@ -41,7 +41,7 @@ import { boneOverlay, boneMarkerPositions, buildOverlayShapes, jointOverlay, lin
 import { BLOOM_BLIT_SHADER_WGSL, BLOOM_DOWNSAMPLE_SHADER_WGSL, BLOOM_UPSAMPLE_SHADER_WGSL, } from "./shaders/passes/bloom";
 import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut";
 import { buildCompositeShader, EFFECT_SCENE_API, buildFieldShader, EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES, } from "./shaders/passes/composite";
-import { buildParticleComputeShader, buildParticleRenderShader, particleEntryPoints, PARTICLE_STRIDE, } from "./shaders/passes/particles";
+import { buildParticleComputeShader, buildParticleRenderShader, PARTICLE_LIGHT_BINDING, particleEntryPoints, PARTICLE_STRIDE, } from "./shaders/passes/particles";
 import { SIM_FORMAT, GRID_MAX, buildSimShader, gridEntryPoint, } from "./shaders/passes/grid";
 import { buildCastResolveShader, buildCastSeedShader, buildCastStepShader, castDistanceUsed, CAST_COVERAGE_FORMAT, CAST_DIST_FORMAT, CAST_FIELD_DIV, CAST_SEED_FORMAT, } from "./shaders/passes/cast-distance";
 import { buildTrailShader, trailEntryPoints, TRAIL_SUBDIVISIONS } from "./shaders/passes/trails";
@@ -1305,6 +1305,13 @@ export class Engine {
         /** The ground's uniform block, kept so the caster sphere can be refreshed in
          *  it every frame rather than rebuilding the buffer (addGround allocates). */
         this.groundMaterialData = null;
+        /** What addGround was given, so an effect's `#ground` can be lifted again
+         *  without rebuilding the floor. */
+        this.groundBaseColor = new Vec3(1, 1, 1);
+        this.groundBaseNoise = 0;
+        /** The caster sphere as last written after the cascade matrices; NaN so the
+         *  first frame always writes. */
+        this.shadowCastersWritten = new Float32Array([NaN, NaN, NaN, NaN]);
         /** Set by the first getGpuTimings() call. See it for why asking is the switch. */
         this.timestampsWanted = false;
         this.groundMirrorPipeline = null;
@@ -3034,9 +3041,9 @@ export class Engine {
         for (const e of this.effects) {
             if (e.particles) {
                 const b = e.particles.rebind();
-                e.particles.computeBind = b.computeBind;
-                e.particles.renderBind = b.renderBind;
-                e.particles.mirrorRenderBind = b.mirrorRenderBind;
+                e.particles.computeBinds = b.computeBinds;
+                e.particles.renderBinds = b.renderBinds;
+                e.particles.mirrorRenderBinds = b.mirrorRenderBinds;
             }
             if (e.grid)
                 e.grid.binds = [this.gridBindGroup(e.grid, 0), this.gridBindGroup(e.grid, 1)];
@@ -3567,18 +3574,21 @@ export class Engine {
             trails?.uniform.destroy();
             return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration, readsCast: false };
         };
-        if (wantsParticles) {
-            const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor);
-            if (!built.ok)
-                return abandon(built.diagnostics);
-            particles = built.state;
-        }
+        // THE GRID FIRST. Particles and ribbons READ it — a blade of grass reads the
+        // bend a foot left there — so the textures have to exist before their bind
+        // groups are built. Nothing reads them back, so the grid depends on neither.
         if (gridEntryPoint(wgsl)) {
             const built = await this.buildSim(wgsl, d, anchors, alias, paramsFor);
             if (!built.ok)
                 return abandon(built.diagnostics);
             grid = built.state;
         }
+        if (wantsParticles) {
+            const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor, grid);
+            if (!built.ok)
+                return abandon(built.diagnostics);
+            particles = built.state;
+        }
         if (wantsTrails) {
             // Only anchors that asked for `trail` have a path to draw; a ribbon on a
             // bone recorded without one would read zeroes and paint a line to the origin.
@@ -3586,7 +3596,7 @@ export class Engine {
             if (trailSlots === 0) {
                 return abandon(["a ribbon effect needs at least one #anchor <bone> trail"]);
             }
-            const built = await this.buildTrails(wgsl, d, anchors, alias, paramsFor);
+            const built = await this.buildTrails(wgsl, d, anchors, alias, paramsFor, grid);
             if (!built.ok)
                 return abandon(built.diagnostics);
             trails = built.state;
@@ -3665,6 +3675,7 @@ export class Engine {
             simStep: 0,
             simReset: false,
             dissolve: d.dissolve ? dissolveConstants(authored) : null,
+            ground: d.ground ? { color: new Vec3(...d.ground.color), noise: d.ground.noise } : null,
             // Its OWN resolution, no longer the scene's: an effect that never asked
             // for full res is not promoted because a neighbour did.
             // FULL RESOLUTION UNLESS TOLD OTHERWISE.
@@ -3895,11 +3906,23 @@ export class Engine {
     alias, 
     /** The effect's declared dials. Spliced into both stages and bound at 7,
      *  the same binding the composite gives them. */
-    params) {
+    params, 
+    /** This effect's own grid, already built, or null when it declared none.
+     *  Read-only here: the pool samples it, the grid pass owns it. */
+    grid) {
         // No pragma means "some": an author who wrote the trio clearly wants
         // particles, and failing over a missing comment would be pedantry.
         const count = Math.min(d.particles || 1024, Engine.MAX_PARTICLES);
-        const src = { wgsl, count, blend: d.particleBlend, bloom: d.bloom, paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING) };
+        const src = {
+            wgsl,
+            count,
+            blend: d.particleBlend,
+            bloom: d.bloom,
+            paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING),
+            gridSize: grid?.size ?? 0,
+            cover: particleEntryPoints(wgsl).cover,
+        };
+        const prepass = src.blend === "cutout" && src.cover;
         // Sparks want to spawn where a trail is, so the particle stages see the same
         // cast buffer the trail draw reads.
         const cast = {
@@ -3952,7 +3975,7 @@ export class Engine {
         // Declaring one set of flags for both layouts is what made the pipeline
         // layout invalid, and the error surfaces later and unhelpfully as "invalid
         // due to a previous error".
-        const layoutFor = (storage, visibility) => this.device.createBindGroupLayout({
+        const layoutFor = (storage, visibility, shadow) => this.device.createBindGroupLayout({
             entries: [
                 { binding: 0, visibility, buffer: { type: storage } },
                 { binding: 1, visibility, buffer: { type: "uniform" } },
@@ -3966,9 +3989,30 @@ export class Engine {
                 // Only when the effect declared any: WGSL has no empty struct, so a
                 // param-less effect must not carry the decl OR the binding.
                 ...(params.buffer ? [{ binding: 7, visibility, buffer: { type: "uniform" } }] : []),
+                // The grid, ALWAYS — the accessor is compiled in unconditionally, and a
+                // binding the shader declares must exist in the layout whether the
+                // author calls it or not. With no grid it is the 1x1 of zeroes.
+                { binding: 8, visibility, texture: { sampleType: "float" } },
+                { binding: 9, visibility, sampler: { type: "filtering" } },
+                // The scene's light, for rzShadow and rzWorldAmbient — the shading
+                // stage only; the compute module compiles the stubs. See
+                // scene-light-api.ts.
+                ...(shadow
+                    ? [
+                        { binding: PARTICLE_LIGHT_BINDING, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                        { binding: PARTICLE_LIGHT_BINDING + 1, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                        { binding: PARTICLE_LIGHT_BINDING + 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "depth" } },
+                        { binding: PARTICLE_LIGHT_BINDING + 3, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "depth" } },
+                        { binding: PARTICLE_LIGHT_BINDING + 4, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "comparison" } },
+                    ]
+                    : []),
             ],
         });
-        const bindFor = (layout, camera) => this.device.createBindGroup({
+        /** One per GRID PARITY, for the reason rebuildFieldBindGroup gives: the grid
+         *  alternates which texture is current, and rebuilding a single group every
+         *  frame is waste for a change that only ever toggles between two known
+         *  states. Both entries are the same view when there is no grid. */
+        const bindFor = (layout, camera, shadow) => [0, 1].map((parity) => this.device.createBindGroup({
             layout,
             entries: [
                 { binding: 0, resource: { buffer } },
@@ -3979,15 +4023,31 @@ export class Engine {
                 { binding: 5, resource: { buffer: this.midiBuffer } },
                 { binding: 6, resource: { buffer: this.lyricsBuffer } },
                 ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
+                { binding: 8, resource: grid ? grid.read[parity] : this.simFallbackView },
+                { binding: 9, resource: this.simSampler },
+                ...(shadow
+                    ? [
+                        { binding: PARTICLE_LIGHT_BINDING, resource: { buffer: this.lightUniformBuffer } },
+                        { binding: PARTICLE_LIGHT_BINDING + 1, resource: { buffer: this.shadowLightVPBuffer } },
+                        { binding: PARTICLE_LIGHT_BINDING + 2, resource: this.shadowMapDepthViews[0] },
+                        { binding: PARTICLE_LIGHT_BINDING + 3, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
+                        { binding: PARTICLE_LIGHT_BINDING + 4, resource: this.shadowComparisonSampler },
+                    ]
+                    : []),
             ],
-        });
-        const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE);
-        const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT);
+        }));
+        const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE, false);
+        const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, true);
         // Additive keeps the destination and adds to it, and leaves alpha alone, so
         // a glow does not claim coverage it never occluded. The MASK sums with it —
         // otherwise an additive effect could never reach the bloom gate. Both live
         // in scene-contract as the "particle-additive" class.
+        //
+        // Cutout blends exactly like alpha and differs only in depth and coverage,
+        // below — so it shares alpha's targets rather than adding a class whose
+        // blends would be a copy.
         const targets = sceneTargetsFor(src.blend === "additive" ? "particle-additive" : "particle", this.sceneFormats);
+        const cutout = src.blend === "cutout";
         this.device.pushErrorScope("validation");
         try {
             const compute = await this.device.createComputePipelineAsync({
@@ -3995,15 +4055,41 @@ export class Engine {
                 layout: this.device.createPipelineLayout({ bindGroupLayouts: [computeLayout] }),
                 compute: { module: computeModule, entryPoint: "main" },
             });
+            const renderLayoutObj = this.device.createPipelineLayout({ bindGroupLayouts: [renderLayout] });
+            // The prepass, when the effect gave the cutout a cheap shape: coverage to
+            // depth, colour targets at writeMask 0 (the depth-prepass class), and
+            // the shading pass below then tests EQUAL and writes no depth.
+            const depth = prepass
+                ? await this.device.createRenderPipelineAsync({
+                    label: "particle depth prepass pipeline",
+                    layout: renderLayoutObj,
+                    vertex: { module: renderModule, entryPoint: "vs" },
+                    fragment: { module: renderModule, entryPoint: "fsDepth", targets: sceneTargetsFor("depth-prepass", this.sceneFormats) },
+                    primitive: { topology: "triangle-list", cullMode: "none" },
+                    depthStencil: { format: this.depthFormat, depthWriteEnabled: true, depthCompare: this.depthAhead },
+                    multisample: { count: Engine.MULTISAMPLE_COUNT },
+                })
+                : null;
             const render = await this.device.createRenderPipelineAsync({
                 label: "particle render pipeline",
-                layout: this.device.createPipelineLayout({ bindGroupLayouts: [renderLayout] }),
+                layout: renderLayoutObj,
                 vertex: { module: renderModule, entryPoint: "vs" },
                 fragment: { module: renderModule, entryPoint: "fs", targets },
                 primitive: { topology: "triangle-list", cullMode: "none" },
                 // Tested but not WRITTEN: particles are transparent, so writing depth
                 // would make whichever quad drew first occlude the ones behind it.
-                depthStencil: { format: this.depthFormat, depthWriteEnabled: false, depthCompare: this.depthAhead },
+                //
+                // Except a CUTOUT, which is opaque where it is drawn at all. Its alpha
+                // becomes per-sample coverage (in the shader — see FSOut.samples, the
+                // HDR target has no alpha for the hardware path), so its edges stay
+                // antialiased under MSAA while its depth is real — and a blade behind
+                // another blade is then rejected at the depth test rather than shaded
+                // and blended under it.
+                // For a lawn stacked ten blades deep that is the difference between
+                // shading ten layers and shading about three.
+                depthStencil: prepass
+                    ? { format: this.depthFormat, depthWriteEnabled: false, depthCompare: "equal" }
+                    : { format: this.depthFormat, depthWriteEnabled: cutout, depthCompare: this.depthAhead },
                 multisample: { count: Engine.MULTISAMPLE_COUNT },
             });
             const scoped = await this.device.popErrorScope();
@@ -4025,15 +4111,16 @@ export class Engine {
                     counts: uniformView.uints,
                     compute,
                     computeLayout,
-                    computeBind: bindFor(computeLayout, this.cameraUniformBuffer),
+                    computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false),
+                    depth,
                     render,
                     renderLayout,
-                    renderBind: bindFor(renderLayout, this.cameraUniformBuffer),
-                    mirrorRenderBind: bindFor(renderLayout, this.mirrorCameraBuffer),
+                    renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true),
+                    mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true),
                     rebind: () => ({
-                        computeBind: bindFor(computeLayout, this.cameraUniformBuffer),
-                        renderBind: bindFor(renderLayout, this.cameraUniformBuffer),
-                        mirrorRenderBind: bindFor(renderLayout, this.mirrorCameraBuffer),
+                        computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false),
+                        renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true),
+                        mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true),
                     }),
                 },
             };
@@ -4226,7 +4313,7 @@ export class Engine {
             this.device.queue.writeBuffer(p.uniform, 0, p.data.buffer);
             const cp = encoder.beginComputePass({ label: "particles" });
             cp.setPipeline(p.compute);
-            cp.setBindGroup(0, p.computeBind);
+            cp.setBindGroup(0, p.computeBinds[e.grid?.parity ?? 0]);
             cp.dispatchWorkgroups(Math.ceil(p.count / 64));
             cp.end();
         }
@@ -4237,8 +4324,15 @@ export class Engine {
             const p = e.particles;
             if (!p || e.weight === 0)
                 continue;
+            const parity = e.grid?.parity ?? 0;
+            const bind = view === "mirror" ? p.mirrorRenderBinds[parity] : p.renderBinds[parity];
+            if (p.depth) {
+                pass.setPipeline(p.depth);
+                pass.setBindGroup(0, bind);
+                pass.draw(6, p.count);
+            }
             pass.setPipeline(p.render);
-            pass.setBindGroup(0, view === "mirror" ? p.mirrorRenderBind : p.renderBind);
+            pass.setBindGroup(0, bind);
             pass.draw(6, p.count);
         }
     }
@@ -4260,7 +4354,10 @@ export class Engine {
      *  describes the effect that is still on screen. */
     alias, 
     /** The effect's declared dials, spliced and bound at 7 as everywhere else. */
-    params) {
+    params, 
+    /** This effect's own grid, already built, or null. Ribbons read it; the grid
+     *  pass owns it. */
+    grid) {
         // `slots` here is how many RIBBONS to draw — one per trailed anchor — which
         // is a different number from the anchor ADDRESS SPACE the accessors index
         // by. Conflating the two is what made a trail declared after a bare anchor
@@ -4270,7 +4367,15 @@ export class Engine {
         // nothing before: ribbon i was read as anchor slot i.
         const ribbonSlots = anchors.map((a, i) => (a.trail ? i : -1)).filter((i) => i >= 0);
         const slots = ribbonSlots.length;
-        const src = { wgsl, slots, ribbonSlots, blend: d.particleBlend, bloom: d.bloom, paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING) };
+        const src = {
+            wgsl,
+            slots,
+            ribbonSlots,
+            blend: (d.particleBlend === "additive" ? "additive" : "alpha"),
+            bloom: d.bloom,
+            paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING),
+            gridSize: grid?.size ?? 0,
+        };
         const code = buildTrailShader(src, {
             subjects: MAX_EFFECT_SUBJECTS,
             samples: TRAIL_SAMPLES,
@@ -4318,6 +4423,13 @@ export class Engine {
                 ...(params.buffer
                     ? [{ binding: 7, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }]
                     : []),
+                // The grid, always — compiled in whether the author calls it or not.
+                {
+                    binding: 8,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    texture: { sampleType: "float" },
+                },
+                { binding: 9, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
             ],
         });
         // TWO targets, the scene pass's own: HDR colour and the aux (bloom mask,
@@ -4363,30 +4475,8 @@ export class Engine {
                     data: new Float32Array(4),
                     pipeline,
                     layout,
-                    bind: this.device.createBindGroup({
-                        layout,
-                        entries: [
-                            { binding: 0, resource: { buffer: this.castBuffer } },
-                            { binding: 1, resource: { buffer: uniform } },
-                            { binding: 2, resource: { buffer: this.cameraUniformBuffer } },
-                            { binding: 4, resource: { buffer: this.audioBuffer } },
-                            { binding: 5, resource: { buffer: this.midiBuffer } },
-                            { binding: 6, resource: { buffer: this.lyricsBuffer } },
-                            ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
-                        ],
-                    }),
-                    mirrorBind: this.device.createBindGroup({
-                        layout,
-                        entries: [
-                            { binding: 0, resource: { buffer: this.castBuffer } },
-                            { binding: 1, resource: { buffer: uniform } },
-                            { binding: 2, resource: { buffer: this.mirrorCameraBuffer } },
-                            { binding: 4, resource: { buffer: this.audioBuffer } },
-                            { binding: 5, resource: { buffer: this.midiBuffer } },
-                            { binding: 6, resource: { buffer: this.lyricsBuffer } },
-                            ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
-                        ],
-                    }),
+                    binds: this.trailBindGroups(layout, uniform, params.buffer, this.cameraUniformBuffer, grid),
+                    mirrorBinds: this.trailBindGroups(layout, uniform, params.buffer, this.mirrorCameraBuffer, grid),
                 },
             };
         }
@@ -4447,7 +4537,8 @@ export class Engine {
                 this.device.queue.writeBuffer(t.uniform, 0, t.data.buffer);
             }
             pass.setPipeline(t.pipeline);
-            pass.setBindGroup(0, view === "mirror" ? t.mirrorBind : t.bind);
+            const parity = e.grid?.parity ?? 0;
+            pass.setBindGroup(0, view === "mirror" ? t.mirrorBinds[parity] : t.binds[parity]);
             pass.draw(6, t.slots * live * (TRAIL_SAMPLES - 1) * TRAIL_SUBDIVISIONS);
         }
     }
@@ -4575,33 +4666,35 @@ export class Engine {
             // one, so it has to be part of every group built against that layout —
             // including this one. Omitting it here is not a missing uniform, it is a
             // group WebGPU refuses outright, which takes the whole frame down.
-            const paramsEntry = t.params ? [{ binding: EFFECT_PARAMS_BINDING, resource: { buffer: t.params } }] : [];
-            t.bind = this.device.createBindGroup({
-                layout: t.layout,
-                entries: [
-                    { binding: 0, resource: { buffer: this.castBuffer } },
-                    { binding: 1, resource: { buffer: t.uniform } },
-                    { binding: 2, resource: { buffer: this.cameraUniformBuffer } },
-                    { binding: 4, resource: { buffer: this.audioBuffer } },
-                    { binding: 5, resource: { buffer: this.midiBuffer } },
-                    { binding: 6, resource: { buffer: this.lyricsBuffer } },
-                    ...paramsEntry,
-                ],
-            });
-            t.mirrorBind = this.device.createBindGroup({
-                layout: t.layout,
-                entries: [
-                    { binding: 0, resource: { buffer: this.castBuffer } },
-                    { binding: 1, resource: { buffer: t.uniform } },
-                    { binding: 2, resource: { buffer: this.mirrorCameraBuffer } },
-                    { binding: 4, resource: { buffer: this.audioBuffer } },
-                    { binding: 5, resource: { buffer: this.midiBuffer } },
-                    { binding: 6, resource: { buffer: this.lyricsBuffer } },
-                    ...paramsEntry,
-                ],
-            });
+            t.binds = this.trailBindGroups(t.layout, t.uniform, t.params, this.cameraUniformBuffer, e.grid);
+            t.mirrorBinds = this.trailBindGroups(t.layout, t.uniform, t.params, this.mirrorCameraBuffer, e.grid);
         }
     }
+    /**
+     * A ribbon's bind group, ONE PER GRID PARITY.
+     *
+     * One author for both the build and the rebind, because they drifted once
+     * already: the params binding is part of the LAYOUT whenever the effect
+     * declared one, so it has to be part of every group built against that
+     * layout, and a group missing it is not a missing uniform but one WebGPU
+     * refuses outright, taking the whole frame down.
+     */
+    trailBindGroups(layout, uniform, params, camera, grid) {
+        return [0, 1].map((parity) => this.device.createBindGroup({
+            layout,
+            entries: [
+                { binding: 0, resource: { buffer: this.castBuffer } },
+                { binding: 1, resource: { buffer: uniform } },
+                { binding: 2, resource: { buffer: camera } },
+                { binding: 4, resource: { buffer: this.audioBuffer } },
+                { binding: 5, resource: { buffer: this.midiBuffer } },
+                { binding: 6, resource: { buffer: this.lyricsBuffer } },
+                ...(params ? [{ binding: EFFECT_PARAMS_BINDING, resource: { buffer: params } }] : []),
+                { binding: 8, resource: grid ? grid.read[parity] : this.simFallbackView },
+                { binding: 9, resource: this.simSampler },
+            ],
+        }));
+    }
     releaseParticles() {
         for (const e of this.effects) {
             e.particles?.buffer.destroy();
@@ -5896,8 +5989,10 @@ export class Engine {
                 targets: sceneTargetsFor("depth-prepass", this.sceneFormats),
             },
         });
+        // The matrices, then one vec4: the caster sphere, which effects' rzShadow
+        // tests before any tap. The materials and the ground bind the matrices only.
         this.shadowLightVPBuffer = this.device.createBuffer({
-            size: 64 * SHADOW_CASCADES.length,
+            size: 64 * SHADOW_CASCADES.length + 16,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         this.shadowCascadeVPBuffers = SHADOW_CASCADES.map((_, i) => this.device.createBuffer({
@@ -10435,6 +10530,51 @@ export class Engine {
         out[2] = cz;
         out[3] = any ? r : 0;
     }
+    /**
+     * Dress the floor in whatever the installed effects ask for.
+     *
+     * The LAST effect declaring `#ground` wins, faded by its own weight so a
+     * scheduled lawn brings its soil in with it and takes it away again. Three
+     * floats at the top of the ground block, written only when they change —
+     * the same bargain writeGroundCasterSphere strikes, for the same reason.
+     */
+    writeGroundDress() {
+        const gb = this.groundMaterialData;
+        if (!gb || !this.groundShadowMaterialBuffer)
+            return;
+        let want = this.groundBaseColor;
+        let noise = this.groundBaseNoise;
+        for (const e of this.effects) {
+            if (!e.ground || e.weight <= 0)
+                continue;
+            const w = e.weight;
+            want = new Vec3(want.x + (e.ground.color.x - want.x) * w, want.y + (e.ground.color.y - want.y) * w, want.z + (e.ground.color.z - want.z) * w);
+            noise += (e.ground.noise - noise) * w;
+        }
+        if (gb[0] === want.x && gb[1] === want.y && gb[2] === want.z && gb[10] === noise)
+            return;
+        gb[0] = want.x;
+        gb[1] = want.y;
+        gb[2] = want.z;
+        gb[10] = noise;
+        // Two writes rather than one over the span: the seven floats between hold
+        // the fades and the shadow strength, and this is not the place that owns
+        // them.
+        this.device.queue.writeBuffer(this.groundShadowMaterialBuffer, 0, gb.subarray(0, 3));
+        this.device.queue.writeBuffer(this.groundShadowMaterialBuffer, 40, gb.subarray(10, 11));
+    }
+    /**
+     * The same sphere, into the cascade block after its matrices — rzShadow's
+     * copy. There whether or not a ground exists: a lawn is often the only floor.
+     */
+    writeShadowCasters() {
+        const w = this.shadowCastersWritten;
+        const c = this.casterSphere;
+        if (w[0] === c[0] && w[1] === c[1] && w[2] === c[2] && w[3] === c[3])
+            return;
+        w.set(c);
+        this.device.queue.writeBuffer(this.shadowLightVPBuffer, 64 * SHADOW_CASCADES.length, c);
+    }
     /**
      * Push this frame's caster sphere into the ground's uniform.
      *
@@ -11307,6 +11447,8 @@ export class Engine {
         // keeping the uniform vec4-aligned.
         const gb = new Float32Array(24);
         this.groundMaterialData = gb;
+        this.groundBaseColor = new Vec3(diffuseColor.x, diffuseColor.y, diffuseColor.z);
+        this.groundBaseNoise = noiseStrength;
         gb[0] = diffuseColor.x;
         gb[1] = diffuseColor.y;
         gb[2] = diffuseColor.z;
@@ -13006,6 +13148,8 @@ export class Engine {
             this.dispatchCull(encoder);
         // After the cull, which is what recomputes the spheres it unions.
         this.writeGroundCasterSphere();
+        this.writeShadowCasters();
+        this.writeGroundDress();
         // After the cull, because a rebuild there can reallocate the argument
         // buffers and a bundle captures the buffer it recorded against.
         if (this.bundlesDirty)
@@ -14843,7 +14987,12 @@ Engine.JIGGLE_DAMPING_SCALE = 0.5;
  * prefix sum and readback a compacted draw list would need every frame.
  */
 /** Ceiling for `#particles`. Past this an author is asking for a stall. */
-Engine.MAX_PARTICLES = 65536;
+// Raised for the lawn: 65536 blades at real density is a 40-unit patch and
+// an 80-unit one wants four hundred thousand. A cutout pool's cost is
+// bounded by the pixels it covers, not by the count — the step is one
+// compute invocation per slot, the pool buffer is 48 bytes each (24 MB at
+// the cap), and a culled blade is a degenerate quad the rasteriser drops.
+Engine.MAX_PARTICLES = 524288;
 /**
  * The field layer: user background/foreground mounts, ONE TARGET PAIR PER
  * RESOLUTION. Index 0 is full, index 1 is half — coarsest last, so the

package/dist/shaders/directives.d.ts

@@ -20,13 +20,30 @@ export type EffectDirectives = {
     /** The field layer composites additively rather than over. */
     additiveLayer: boolean;
     /** Particle blend, which is a different axis from the field layer's. */
-    particleBlend: "alpha" | "additive";
+    /** `cutout` is alpha WITH DEPTH: the pipeline writes depth and turns the
+     *  fragment's alpha into MSAA sample coverage, so a blade of grass behind
+     *  another is rejected by the depth test instead of blended under it. What
+     *  every real grass renderer does, and the only thing that bounds a dense
+     *  lawn's cost by the pixels it covers rather than by how deep it stacks. */
+    particleBlend: "alpha" | "additive" | "cutout";
     particles: number;
     lights: number;
     grid: number;
     bloom: boolean;
     /** This effect takes the cast apart — the host reads the timing. */
     dissolve: boolean;
+    /** `#ground #rrggbb [noise]`: how this effect DRESSES THE FLOOR while it is
+     *  installed — a colour as linear RGB, and the strength of the ground's own
+     *  grain (0 flat, 1 strong), which is what keeps soil from being a swatch.
+     *  A lawn wants earth under it, and the earth has to be the engine's own
+     *  ground rather than a layer painted over the frame: the ground is geometry
+     *  in the scene pass, so a shadow lands on it and it tone-maps with
+     *  everything else. The scene's own floor returns when the effect goes.
+     *  Null when the file declares none. */
+    ground: {
+        color: [number, number, number];
+        noise: number;
+    } | null;
     /**
      * This effect IS a mirror: a plane in the scene showing a true reflection of
      * it, folded and re-rendered by the engine.

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

@@ -1 +1 @@
-{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/shaders/directives.ts"],"names":[],"mappings":"AA8BA,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE,aAAa,EAAE,OAAO,GAAG,UAAU,CAAA;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAkBD;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,QAAmC,CAAA;AAG9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAmBzD,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhF,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAyJ7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/shaders/directives.ts"],"names":[],"mappings":"AA8BA,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE;;;;iFAI6E;IAC7E,aAAa,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;4CAOwC;IACxC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACjE;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAmBD;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,QAAmC,CAAA;AAG9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAmBzD,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhF,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CA2K7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/shaders/directives.js

@@ -41,6 +41,7 @@ const SPEC = {
     dissolve: 0,
     mirror: 0,
     duration: 1,
+    ground: "rest",
 };
 /** A line that declares something, and what it declares. Exported because an
  *  editor highlights by the same rule the parser reads by — a highlighter with
@@ -89,6 +90,7 @@ export function parseDirectives(wgsl) {
         grid: 0,
         bloom: false,
         dissolve: false,
+        ground: null,
         mirror: false,
         duration: 0,
     };
@@ -173,15 +175,32 @@ export function parseDirectives(wgsl) {
                 d.additiveLayer = true;
                 return;
             case "blend":
-                if (args[0] !== "additive") {
-                    errors.push(`${at}: #blend takes "additive" — alpha is the default`);
+                if (args[0] !== "additive" && args[0] !== "cutout") {
+                    errors.push(`${at}: #blend takes "additive" or "cutout" — alpha is the default`);
                     return;
                 }
-                d.particleBlend = "additive";
+                d.particleBlend = args[0];
                 return;
             case "bloom":
                 d.bloom = true;
                 return;
+            case "ground": {
+                const m = /^#([0-9a-fA-F]{6})$/.exec(args[0] ?? "");
+                const noise = args[1] === undefined ? 0 : num(args[1]);
+                if (!m || args.length > 2 || noise === null) {
+                    errors.push(`${at}: #ground takes a colour like #4b4026 and optionally a grain strength 0..1`);
+                    return;
+                }
+                const v = parseInt(m[1], 16);
+                // sRGB in the file, linear in the uniform — the same transfer the
+                // ground's own colour goes through on the way in.
+                const lin = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+                d.ground = {
+                    color: [lin(((v >> 16) & 255) / 255), lin(((v >> 8) & 255) / 255), lin((v & 255) / 255)],
+                    noise: Math.min(Math.max(noise, 0), 1),
+                };
+                return;
+            }
             case "dissolve":
                 d.dissolve = true;
                 return;

package/dist/shaders/lights.d.ts

@@ -33,16 +33,8 @@ export declare const LIGHTS_FLOATS: number;
  * write, which is the same trap the grid's step-only half documents.
  */
 export declare const RZ_LIGHT_STRUCT_WGSL = "\n/** What an effect returns for one of its lights. */\nstruct RzLight {\n  pos: vec3f,\n  color: vec3f,\n  intensity: f32,\n  radius: f32,\n}\n";
-/**
- * The world's light at a surface facing n — the flat colour, or the installed
- * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
- * ibl.ts for the folding; the shader is a plain polynomial in the normal).
- *
- * One string included by every module that declares LightUniforms with the sh
- * block — the hosted-api lesson: a helper defined in some modules and not
- * others is a compile error waiting for the first file that crosses them.
- */
-export declare const WORLD_AMBIENT_WGSL = "\nfn rzWorldAmbient(n: vec3f) -> vec3f {\n  if (light.sh[0].w < 0.5) { return light.ambientColor.xyz; }\n  let x = n.x;\n  let y = n.y;\n  let z = n.z;\n  let c = light.sh[0].xyz\n    + light.sh[1].xyz * y + light.sh[2].xyz * z + light.sh[3].xyz * x\n    + light.sh[4].xyz * (x * y) + light.sh[5].xyz * (y * z)\n    + light.sh[6].xyz * (3.0 * z * z - 1.0) + light.sh[7].xyz * (x * z)\n    + light.sh[8].xyz * (x * x - y * y);\n  return max(c, vec3f(0.0));\n}\n";
+/** rzWorldAmbient against the materials' and the ground's `light` uniform. */
+export declare const WORLD_AMBIENT_WGSL: string;
 /** Does this source define the emit mount? */
 export declare function hasLightEmit(wgsl: string): boolean;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../src/shaders/lights.ts"],"names":[],"mappings":"AAyCA;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,CAoGR;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":"AA0CA;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,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,QAA4B,CAAA;AAE3D,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,CAoGR;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA0FhE"}