reze-engine 0.57.6 → 0.58.0

package/dist/engine.js

@@ -1305,6 +1305,10 @@ 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;
         /** Set by the first getGpuTimings() call. See it for why asking is the switch. */
         this.timestampsWanted = false;
         this.groundMirrorPipeline = null;
@@ -3034,9 +3038,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 +3571,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 +3593,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 +3672,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 +3903,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 = {
@@ -3966,9 +3986,18 @@ 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" } },
             ],
         });
-        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) => [0, 1].map((parity) => this.device.createBindGroup({
             layout,
             entries: [
                 { binding: 0, resource: { buffer } },
@@ -3979,15 +4008,22 @@ 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 },
             ],
-        });
+        }));
         const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE);
         const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT);
         // 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 +4031,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 +4087,16 @@ export class Engine {
                     counts: uniformView.uints,
                     compute,
                     computeLayout,
-                    computeBind: bindFor(computeLayout, this.cameraUniformBuffer),
+                    computeBinds: bindFor(computeLayout, this.cameraUniformBuffer),
+                    depth,
                     render,
                     renderLayout,
-                    renderBind: bindFor(renderLayout, this.cameraUniformBuffer),
-                    mirrorRenderBind: bindFor(renderLayout, this.mirrorCameraBuffer),
+                    renderBinds: bindFor(renderLayout, this.cameraUniformBuffer),
+                    mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer),
                     rebind: () => ({
-                        computeBind: bindFor(computeLayout, this.cameraUniformBuffer),
-                        renderBind: bindFor(renderLayout, this.cameraUniformBuffer),
-                        mirrorRenderBind: bindFor(renderLayout, this.mirrorCameraBuffer),
+                        computeBinds: bindFor(computeLayout, this.cameraUniformBuffer),
+                        renderBinds: bindFor(renderLayout, this.cameraUniformBuffer),
+                        mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer),
                     }),
                 },
             };
@@ -4226,7 +4289,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 +4300,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 +4330,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 +4343,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 +4399,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 +4451,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 +4513,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 +4642,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();
@@ -10435,6 +10504,39 @@ 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));
+    }
     /**
      * Push this frame's caster sphere into the ground's uniform.
      *
@@ -11307,6 +11409,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 +13110,7 @@ export class Engine {
             this.dispatchCull(encoder);
         // After the cull, which is what recomputes the spheres it unions.
         this.writeGroundCasterSphere();
+        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 +14948,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/passes/particles.d.ts

@@ -14,7 +14,9 @@ export type CastLayout = {
     alias: number[];
 };
 /** How the author's quads combine with the scene. */
-type ParticleBlend = "alpha" | "additive";
+/** `cutout` shades exactly like `alpha`; the difference is entirely in the
+ *  pipeline — depth write on, alpha-to-coverage on. See directives.ts. */
+type ParticleBlend = "alpha" | "additive" | "cutout";
 type ParticleSource = {
     /** The author's WGSL verbatim. */
     wgsl: string;
@@ -27,14 +29,28 @@ type ParticleSource = {
      *  rule reads the same dial the shading does, and rain's fall speed is used
      *  in the compute half. */
     paramsDecl: string;
+    /** The effect defines `particleCover(p, uv) -> f32`: the shape alone, cheap.
+     *  A cutout then draws TWICE — coverage to depth first, then the shading at
+     *  depthCompare equal — so the lighting runs only for the visible layer. A
+     *  discard forbids the hardware's own early rejection on a tile-based GPU,
+     *  where every stacked fragment is otherwise shaded in full; the prepass is
+     *  the shape of that rejection, done by hand and cheaply. */
+    cover: boolean;
+    /** The side of this effect's grid, or 0 when it declared none. Particles READ
+     *  the grid; the kernel that steps it lives in the grid pass. A blade of grass
+     *  bending where a foot pressed is the whole case: the bend has to persist and
+     *  recover, which is memory, and memory is what the grid is for. */
+    gridSize: number;
 };
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export declare const PARTICLE_STRIDE = 48;
-/** Does the source define the particle contract? All three are required together. */
+/** Does the source define the particle contract? All three are required
+ *  together; `cover` is optional and only means anything to a cutout. */
 export declare function particleEntryPoints(wgsl: string): {
     init: boolean;
     step: boolean;
     shade: boolean;
+    cover: boolean;
 };
 /**
  * Spawn, age, recycle.

package/dist/shaders/passes/particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AA4BA,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb;;mFAE+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB,CAAA;AAkCD,qDAAqD;AACrD,KAAK,aAAa,GAAG,OAAO,GAAG,UAAU,CAAA;AAEzC,KAAK,cAAc,GAAG;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd;;+BAE2B;IAC3B,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAA;AAwDjC,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAMlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA8CxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA6HvF"}
+{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AA6BA,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb;;mFAE+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB,CAAA;AAkCD,qDAAqD;AACrD;0EAC0E;AAC1E,KAAK,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEpD,KAAK,cAAc,GAAG;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd;;+BAE2B;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;iEAK6D;IAC7D,KAAK,EAAE,OAAO,CAAA;IACd;;;wEAGoE;IACpE,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAA;AAwDjC;yEACyE;AACzE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAOlH;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAmDxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAuLvF"}