@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/sand/src/particles.js

@@ -0,0 +1,163 @@
+// ============================================================================
+// ParticleSystem — fixed-pool particle system for explosion visuals.
+//
+// Particles are simulated on the CPU (in the worker) and transferred to the
+// renderer via the SharedArrayBuffer. The renderer draws them as a point-list
+// or instanced quad pipeline on top of the grid layers.
+//
+// The pool is fixed-size (no per-frame allocation). Dead particles are marked
+// inactive and their slots are reused. This keeps memory stable and avoids
+// GC pressure in the hot loop.
+// ============================================================================
+export const PARTICLE_TYPES = {
+    PROJECTILE: 0, // flying debris — moves with velocity, leaves trail
+    CIRCLE: 1, // expanding blast ring — grows in size, fades
+    SLUG: 2, // slow-moving glowing ember
+};
+// Particle data layout (for SAB transfer). Each particle = 8 floats (32 bytes):
+//   [x, y, vx, vy, color, size, life/maxLife, type+active]
+export const PARTICLE_FLOATS = 8;
+export const PARTICLE_BYTES = PARTICLE_FLOATS * 4;
+export class ParticleSystem {
+    particles;
+    count = 0; // active count
+    maxParticles;
+    constructor(max = 512) {
+        this.maxParticles = max;
+        this.particles = new Array(max);
+        for (let i = 0; i < max; i++) {
+            this.particles[i] = {
+                x: 0, y: 0, vx: 0, vy: 0,
+                color: 0, size: 0, life: 0, maxLife: 0,
+                type: 0, active: false,
+            };
+        }
+    }
+    /** Current active particle count. */
+    get activeCount() {
+        return this.count;
+    }
+    /**
+     * Spawn a particle. If the pool is full, the oldest particle is replaced.
+     */
+    spawn(x, y, type, color, size, vx, vy, maxLife) {
+        // Find an inactive slot
+        let slot = -1;
+        for (let i = 0; i < this.maxParticles; i++) {
+            if (!this.particles[i].active) {
+                slot = i;
+                break;
+            }
+        }
+        if (slot < 0) {
+            // Pool full — replace the oldest active particle
+            let oldestLife = Infinity;
+            for (let i = 0; i < this.maxParticles; i++) {
+                const p = this.particles[i];
+                if (p.life > oldestLife) {
+                    oldestLife = p.life;
+                    slot = i;
+                }
+            }
+            if (slot < 0)
+                slot = 0; // shouldn't happen but safety
+        }
+        const p = this.particles[slot];
+        p.x = x;
+        p.y = y;
+        p.vx = vx;
+        p.vy = vy;
+        p.color = color;
+        p.size = size;
+        p.life = 0;
+        p.maxLife = maxLife;
+        p.type = type;
+        p.active = true;
+        this.count++;
+    }
+    /**
+     * Advance particle physics and cull dead particles.
+     * Called once per frame after the main simulation step.
+     */
+    update() {
+        let active = 0;
+        for (let i = 0; i < this.maxParticles; i++) {
+            const p = this.particles[i];
+            if (!p.active)
+                continue;
+            // Advance physics
+            p.x += p.vx;
+            p.y += p.vy;
+            // Type-specific behavior
+            switch (p.type) {
+                case PARTICLE_TYPES.PROJECTILE:
+                    // Decelerate (air resistance)
+                    p.vx *= 0.92;
+                    p.vy *= 0.92;
+                    // Gravity pulls projectiles down
+                    p.vy += 0.15;
+                    break;
+                case PARTICLE_TYPES.CIRCLE:
+                    // Expanding ring — grow size, no velocity decay
+                    p.size += 0.3;
+                    p.vx *= 0.95;
+                    p.vy *= 0.95;
+                    break;
+                case PARTICLE_TYPES.SLUG:
+                    // Slow ember — gentle deceleration
+                    p.vx *= 0.96;
+                    p.vy *= 0.96;
+                    p.vy -= 0.05; // slight upward drift (hot)
+                    break;
+            }
+            // Age
+            p.life++;
+            if (p.life >= p.maxLife) {
+                p.active = false;
+            }
+            else {
+                active++;
+            }
+        }
+        this.count = active;
+    }
+    /**
+     * Write particle data to a Float32Array for SAB transfer.
+     * Returns the number of particles written.
+     */
+    writeToBuffer(buf, offset) {
+        let written = 0;
+        let fi = offset;
+        for (let i = 0; i < this.maxParticles; i++) {
+            const p = this.particles[i];
+            if (!p.active)
+                continue;
+            buf[fi++] = p.x;
+            buf[fi++] = p.y;
+            buf[fi++] = p.vx;
+            buf[fi++] = p.vy;
+            buf[fi++] = p.color;
+            buf[fi++] = p.size;
+            buf[fi++] = p.life / p.maxLife; // normalized life (0→1)
+            buf[fi++] = p.type;
+            written++;
+            if (written >= this.maxParticles)
+                break;
+        }
+        return written;
+    }
+    /** Clear all particles. */
+    clear() {
+        for (let i = 0; i < this.maxParticles; i++) {
+            this.particles[i].active = false;
+        }
+        this.count = 0;
+    }
+    /** Get a particle by index (for testing). */
+    getParticle(i) {
+        if (i < 0 || i >= this.maxParticles)
+            return null;
+        const p = this.particles[i];
+        return p.active ? p : null;
+    }
+}

package/dist/libraries/sand/src/render/sand-grid-pass.js

@@ -0,0 +1,377 @@
+// ============================================================================
+// SandGridPass — shared render pass for sand-grid games.
+//
+// Generalized from the three per-game copies (falling-sand, mining-rpg,
+// sandjongg). Renders one or more r32uint grid textures to the canvas using
+// the material palette + props textures.
+//
+// Configurable features:
+//   - numLayers > 1: per-layer grid textures + offscreen reflection targets
+//     (layer i's offscreen target is sampled by layer i+1 — falling-sand)
+//   - camera: adds a camera uniform (offset/zoom/canvas/depth) at binding 5
+//     (mining-rpg)
+//   - extraTextures: extra float textures bound after the camera binding
+//     (light accumulation / volumetric — mining-rpg)
+//
+// The fragment shader is game-provided — each game's sand-render.wgsl
+// declares the bindings it uses.
+// ============================================================================
+import { createValidatedShaderModule, FULLSCREEN_VS } from "@downdraft/engine";
+import { buildMaterialProps, buildPalette, PALETTE_SIZE, SHADES_PER_MATERIAL } from "../palette.js";
+// Scatter-update compute shader: writes a packed (cellIndex, value) list into
+// the grid storage texture. Used when only a small fraction of cells changed —
+// uploading ~8B/cell beats re-uploading the whole grid through writeTexture.
+const SCATTER_CS = /* wgsl */ `
+@group(0) @binding(0) var gridTex: texture_storage_2d<r32uint, write>;
+@group(0) @binding(1) var<storage, read> cells: array<u32>;
+@group(0) @binding(2) var<uniform> uinfo: vec4<u32>; // x=count, y=gridW
+
+@compute @workgroup_size(64)
+fn cs_main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= uinfo.x) { return; }
+  let cell = cells[id.x * 2u];
+  let val = cells[id.x * 2u + 1u];
+  textureStore(gridTex, vec2<i32>(i32(cell % uinfo.y), i32(cell / uinfo.y)), vec4<u32>(val));
+}
+`;
+/** Max cells per scatter update; beyond this callers fall back to updateGrid(). */
+export const MAX_SCATTER_CELLS = 16384;
+const EXTRA_TEXTURE_BASE = 6; // bindings 0-5: grid/palette/props/behind/uniform/camera
+export class SandGridPass {
+    device;
+    format;
+    fragmentShader;
+    cameraEnabled;
+    extraTextureCount;
+    pipeline = null;
+    bindGroupLayout = null;
+    bindGroups = [];
+    uniformBuffer = null;
+    cameraBuffer = null;
+    gridTextures = [];
+    gridViews = [];
+    paletteTexture = null;
+    paletteView = null;
+    propsTexture = null;
+    propsView = null;
+    // Offscreen targets: one per layer (except the frontmost).
+    // Layer i's offscreen target is sampled by layer i+1 for reflections.
+    offscreenTargets = [];
+    offscreenViews = [];
+    // 1×1 dummy texture for unbound slots (backmost layer's behind, extra textures)
+    dummyTexture = null;
+    dummyView = null;
+    // Extra texture views (light accumulation, volumetric, ...) set per frame.
+    extraViews = [];
+    uniformBuf = new Float32Array(4);
+    // Scatter-update path (created lazily on first queueCellUpdate).
+    scatterPipeline = null;
+    scatterBindGroups = [];
+    cellsBuffer = null;
+    scatterMetaBuffer = null;
+    pendingCellCount = 0;
+    pendingCellLayer = 0;
+    gridW;
+    gridH;
+    numLayers;
+    constructor(config) {
+        this.device = config.device;
+        this.format = config.format;
+        this.fragmentShader = config.fragmentShader;
+        this.gridW = config.gridW;
+        this.gridH = config.gridH;
+        this.numLayers = config.numLayers ?? 1;
+        this.cameraEnabled = config.camera ?? false;
+        this.extraTextureCount = config.extraTextures ?? 0;
+        this.bindGroups = new Array(this.numLayers).fill(null);
+        this.gridTextures = new Array(this.numLayers).fill(null);
+        this.gridViews = new Array(this.numLayers).fill(null);
+        this.offscreenTargets = new Array(this.numLayers).fill(null);
+        this.offscreenViews = new Array(this.numLayers).fill(null);
+        this.extraViews = new Array(this.extraTextureCount).fill(null);
+    }
+    init(canvasW = 1, canvasH = 1) {
+        this.uniformBuffer = this.device.createBuffer({
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        if (this.cameraEnabled) {
+            // 32 bytes = 8 floats (WebGPU requires 16-byte alignment)
+            this.cameraBuffer = this.device.createBuffer({
+                size: 32,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+        }
+        // 1×1 dummy texture for unbound texture slots
+        this.dummyTexture = this.device.createTexture({
+            size: [1, 1],
+            format: this.format,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        this.dummyView = this.dummyTexture.createView();
+        // Clear it to black
+        this.device.queue.writeTexture({ texture: this.dummyTexture }, new Uint8Array([0, 0, 0, 0]), { bytesPerRow: 4, rowsPerImage: 1 }, [1, 1]);
+        for (let i = 0; i < this.numLayers; i++) {
+            this.createGridTexture(i);
+            // Only create offscreen targets for layers that will be reflected (all but the frontmost)
+            if (i < this.numLayers - 1) {
+                this.createOffscreenTarget(i, canvasW, canvasH);
+            }
+        }
+        const pal = buildPalette();
+        const palW = PALETTE_SIZE * SHADES_PER_MATERIAL;
+        this.paletteTexture = this.device.createTexture({
+            size: [palW, 1],
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        this.paletteView = this.paletteTexture.createView();
+        this.device.queue.writeTexture({ texture: this.paletteTexture }, pal, { bytesPerRow: palW * 4, rowsPerImage: 1 }, [palW, 1]);
+        const props = buildMaterialProps();
+        this.propsTexture = this.device.createTexture({
+            size: [PALETTE_SIZE, 1],
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        this.propsView = this.propsTexture.createView();
+        this.device.queue.writeTexture({ texture: this.propsTexture }, props, { bytesPerRow: PALETTE_SIZE * 4, rowsPerImage: 1 }, [PALETTE_SIZE, 1]);
+        const entries = [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "uint" } },
+            { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+            { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+            { binding: 3, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+            { binding: 4, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        ];
+        if (this.cameraEnabled) {
+            entries.push({ binding: 5, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } });
+        }
+        for (let i = 0; i < this.extraTextureCount; i++) {
+            entries.push({
+                binding: EXTRA_TEXTURE_BASE + i,
+                visibility: GPUShaderStage.FRAGMENT,
+                texture: { sampleType: "float" },
+            });
+        }
+        this.bindGroupLayout = this.device.createBindGroupLayout({ entries });
+        const shader = createValidatedShaderModule(this.device, { code: FULLSCREEN_VS + "\n" + this.fragmentShader, label: "SandGridPass" });
+        const pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout],
+        });
+        this.pipeline = this.device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: { module: shader, entryPoint: "vs_main" },
+            fragment: {
+                module: shader,
+                entryPoint: "fs_main",
+                targets: [{
+                        format: this.format,
+                        blend: {
+                            color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    }],
+            },
+            primitive: { topology: "triangle-list" },
+        });
+        for (let i = 0; i < this.numLayers; i++) {
+            this.createBindGroup(i);
+        }
+        this.updateUniforms();
+        if (this.cameraEnabled) {
+            this.updateCamera(0, 0, 4, canvasW, canvasH);
+        }
+    }
+    createGridTexture(layer) {
+        this.gridTextures[layer]?.destroy();
+        const tex = this.device.createTexture({
+            size: [this.gridW, this.gridH],
+            format: "r32uint",
+            // STORAGE_BINDING enables the scatter-update path (queueCellUpdate) to
+            // write changed cells directly instead of re-uploading the whole grid.
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.STORAGE_BINDING,
+        });
+        this.gridTextures[layer] = tex;
+        this.gridViews[layer] = tex.createView();
+    }
+    createOffscreenTarget(layer, w, h) {
+        this.offscreenTargets[layer]?.destroy();
+        const tex = this.device.createTexture({
+            size: [w, h],
+            format: this.format,
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.offscreenTargets[layer] = tex;
+        this.offscreenViews[layer] = tex.createView();
+    }
+    createBindGroup(layer) {
+        if (!this.bindGroupLayout || !this.gridViews[layer] || !this.paletteView || !this.propsView || !this.uniformBuffer)
+            return;
+        // Layer 0 uses the 1×1 dummy; layer i uses layer i-1's offscreen target
+        const behindView = layer > 0 ? (this.offscreenViews[layer - 1] ?? this.dummyView) : this.dummyView;
+        const entries = [
+            { binding: 0, resource: this.gridViews[layer] },
+            { binding: 1, resource: this.paletteView },
+            { binding: 2, resource: this.propsView },
+            { binding: 3, resource: behindView },
+            { binding: 4, resource: { buffer: this.uniformBuffer } },
+        ];
+        if (this.cameraEnabled) {
+            entries.push({ binding: 5, resource: { buffer: this.cameraBuffer } });
+        }
+        for (let i = 0; i < this.extraTextureCount; i++) {
+            entries.push({
+                binding: EXTRA_TEXTURE_BASE + i,
+                resource: this.extraViews[i] ?? this.dummyView,
+            });
+        }
+        this.bindGroups[layer] = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries,
+        });
+    }
+    /** Get the grid texture view for a layer (e.g. shared with compute passes). */
+    getGridView(layer = 0) {
+        return this.gridViews[layer] ?? null;
+    }
+    /** Set an extra texture view (light accumulation, volumetric, ...). */
+    setExtraTexture(slot, view) {
+        if (slot < 0 || slot >= this.extraTextureCount)
+            return;
+        if (this.extraViews[slot] === view)
+            return;
+        this.extraViews[slot] = view;
+        for (let i = 0; i < this.numLayers; i++)
+            this.createBindGroup(i);
+    }
+    /** Recreate grid textures (+ offscreen targets when canvas dims are given). */
+    resize(gridW, gridH, canvasW, canvasH) {
+        this.gridW = gridW;
+        this.gridH = gridH;
+        this.pendingCellCount = 0;
+        this.scatterBindGroups.fill(null); // grid views change → rebind on next use
+        for (let i = 0; i < this.numLayers; i++) {
+            this.createGridTexture(i);
+            if (canvasW !== undefined && canvasH !== undefined && i < this.numLayers - 1) {
+                this.createOffscreenTarget(i, canvasW, canvasH);
+            }
+            this.createBindGroup(i);
+        }
+    }
+    updateGrid(grid, layer = 0) {
+        if (!this.gridTextures[layer])
+            return;
+        this.device.queue.writeTexture({ texture: this.gridTextures[layer] }, grid.buffer, { offset: grid.byteOffset, bytesPerRow: this.gridW * 4, rowsPerImage: this.gridH }, [this.gridW, this.gridH]);
+    }
+    /**
+     * Stage a sparse grid update. `cells` holds packed [cellIndex, value] u32
+     * pairs; `count` is the number of pairs. Returns false when `count` exceeds
+     * the scatter capacity — the caller should fall back to updateGrid().
+     * The actual compute dispatch happens in encodeCellUpdate().
+     */
+    queueCellUpdate(cells, count, layer = 0) {
+        if (count <= 0) {
+            this.pendingCellCount = 0;
+            return true;
+        }
+        if (count > MAX_SCATTER_CELLS || !this.gridTextures[layer])
+            return false;
+        this.ensureScatterResources(layer);
+        if (!this.scatterPipeline)
+            return false;
+        this.device.queue.writeBuffer(this.cellsBuffer, 0, cells.subarray(0, count * 2));
+        this.device.queue.writeBuffer(this.scatterMetaBuffer, 0, new Uint32Array([count, this.gridW, 0, 0]));
+        this.pendingCellCount = count;
+        this.pendingCellLayer = layer;
+        return true;
+    }
+    /**
+     * Emit the pending scatter dispatch into `encoder`. Must be called on the
+     * frame's command encoder BEFORE the render pass that samples the grid, so
+     * writes are visible to the draw.
+     */
+    encodeCellUpdate(encoder) {
+        if (this.pendingCellCount === 0 || !this.scatterPipeline)
+            return;
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(this.scatterPipeline);
+        pass.setBindGroup(0, this.scatterBindGroups[this.pendingCellLayer]);
+        pass.dispatchWorkgroups(Math.ceil(this.pendingCellCount / 64));
+        pass.end();
+        this.pendingCellCount = 0;
+    }
+    ensureScatterResources(layer) {
+        if (!this.cellsBuffer) {
+            this.cellsBuffer = this.device.createBuffer({
+                size: MAX_SCATTER_CELLS * 8,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            this.scatterMetaBuffer = this.device.createBuffer({
+                size: 16,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+        }
+        if (this.scatterPipeline && this.scatterBindGroups[layer])
+            return;
+        if (!this.scatterPipeline) {
+            const layout = this.device.createBindGroupLayout({
+                entries: [
+                    { binding: 0, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: "write-only", format: "r32uint" } },
+                    { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                    { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                ],
+            });
+            const shader = createValidatedShaderModule(this.device, { code: SCATTER_CS, label: "SandGridScatter" });
+            this.scatterPipeline = this.device.createComputePipeline({
+                layout: this.device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+                compute: { module: shader, entryPoint: "cs_main" },
+            });
+            this.scatterBindGroups = new Array(this.numLayers).fill(null);
+        }
+        this.scatterBindGroups[layer] = this.device.createBindGroup({
+            layout: this.scatterPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: this.gridViews[layer] },
+                { binding: 1, resource: { buffer: this.cellsBuffer } },
+                { binding: 2, resource: { buffer: this.scatterMetaBuffer } },
+            ],
+        });
+    }
+    updateUniforms() {
+        this.uniformBuf[0] = this.gridW;
+        this.uniformBuf[1] = this.gridH;
+        this.uniformBuf[2] = performance.now() / 1000;
+        this.uniformBuf[3] = 1.0;
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, this.uniformBuf);
+    }
+    /** Camera uniforms — only when `camera: true`. */
+    updateCamera(camX, camY, zoom, canvasW, canvasH, depth = 0) {
+        if (!this.cameraBuffer)
+            return;
+        const u = new Float32Array([camX, camY, zoom, canvasW, canvasH, depth, 0, 0]);
+        this.device.queue.writeBuffer(this.cameraBuffer, 0, u);
+    }
+    /** A layer's offscreen reflection target view (multi-layer configs only). */
+    getOffscreenView(layer) {
+        return this.offscreenViews[layer];
+    }
+    render(pass, layer = 0) {
+        if (!this.pipeline || !this.bindGroups[layer])
+            return;
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, this.bindGroups[layer]);
+        pass.draw(3);
+    }
+    destroy() {
+        this.gridTextures.forEach((t) => { t?.destroy(); ; });
+        this.offscreenTargets.forEach((t) => { t?.destroy(); ; });
+        this.paletteTexture?.destroy();
+        this.propsTexture?.destroy();
+        this.dummyTexture?.destroy();
+        this.uniformBuffer?.destroy();
+        this.cameraBuffer?.destroy();
+        this.cellsBuffer?.destroy();
+        this.scatterMetaBuffer?.destroy();
+        this.pipeline = null;
+        this.bindGroups.fill(null);
+    }
+}

package/dist/libraries/sand/src/rng.js

@@ -0,0 +1,44 @@
+// ============================================================================
+// SandRNG — fast xorshift32 PRNG for the sand simulation.
+//
+// Replaces Math.random() in hot loops. Math.random() is ~10x slower than
+// xorshift32 in V8 because it draws from a cryptographic-quality entropy
+// source. The sand simulation calls the PRNG dozens of times per active cell
+// per frame, so this is a measurable speedup.
+//
+// State is per-SandWorld instance (not global) so multiple worlds don't
+// correlate. reseed() enables deterministic test mode.
+// ============================================================================
+export class SandRNG {
+    state;
+    constructor(seed = 0x9e3779b9) {
+        // xorshift32 requires non-zero state; default to a golden-ratio constant
+        this.state = (seed >>> 0) || 0x12345678;
+    }
+    /** Re-seed the PRNG (for deterministic test mode). */
+    reseed(seed) {
+        this.state = (seed >>> 0) || 0x12345678;
+    }
+    /** Draw a u32 from the xorshift32 sequence. */
+    nextU32() {
+        let x = this.state;
+        x ^= x << 13;
+        x ^= x >>> 17;
+        x ^= x << 5;
+        this.state = x >>> 0;
+        return this.state;
+    }
+    /** Draw a float in [0, 1) — drop-in replacement for Math.random(). */
+    random() {
+        // 24-bit mantissa for a clean [0,1) range
+        return (this.nextU32() >>> 8) * (1.0 / 16777216.0);
+    }
+    /** Random shade index 0-3 — drop-in replacement for randomShade(). */
+    randomShade() {
+        return this.nextU32() & 3;
+    }
+    /** Random integer in [0, max). */
+    randomInt(max) {
+        return (this.nextU32() >>> 0) % max;
+    }
+}