@downdraft/engine 0.0.0 → 0.1.1

package/libraries/sand/src/particles.ts

@@ -0,0 +1,185 @@
+// ============================================================================
+// 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
+} as const;
+
+// 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 interface Particle {
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  color: number;   // packed RGBA u32
+  size: number;    // radius in cells
+  life: number;    // current life in frames
+  maxLife: number; // max life in frames
+  type: number;    // PARTICLE_TYPES
+  active: boolean;
+}
+
+export class ParticleSystem {
+  private particles: Particle[];
+  private count = 0; // active count
+  readonly maxParticles: number;
+
+  constructor(max: number = 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(): number {
+    return this.count;
+  }
+
+  /**
+   * Spawn a particle. If the pool is full, the oldest particle is replaced.
+   */
+  spawn(
+    x: number, y: number,
+    type: number,
+    color: number,
+    size: number,
+    vx: number, vy: number,
+    maxLife: number,
+  ): void {
+    // 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(): void {
+    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: Float32Array, offset: number): number {
+    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(): void {
+    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: number): Particle | null {
+    if (i < 0 || i >= this.maxParticles) return null;
+    const p = this.particles[i];
+    return p.active ? p : null;
+  }
+}

package/libraries/sand/src/render/sand-grid-pass.ts

@@ -0,0 +1,430 @@
+// ============================================================================
+// 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";
+
+// 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;
+
+export interface SandGridPassConfig {
+  device: GPUDevice;
+  /** Canvas/present texture format. */
+  format: GPUTextureFormat;
+  gridW: number;
+  gridH: number;
+  /** Fragment shader WGSL — appended after FULLSCREEN_VS. */
+  fragmentShader: string;
+  /** Grid layers. >1 creates offscreen reflection targets. Default: 1. */
+  numLayers?: number;
+  /** Adds a 32B camera uniform at binding 5 + updateCamera(). Default: false. */
+  camera?: boolean;
+  /** Extra float-sample textures after the camera binding (or binding 5 when
+   *  camera is off). Set per-frame via setExtraTexture(). Default: 0. */
+  extraTextures?: number;
+}
+
+const EXTRA_TEXTURE_BASE = 6; // bindings 0-5: grid/palette/props/behind/uniform/camera
+
+export class SandGridPass {
+  private device: GPUDevice;
+  private format: GPUTextureFormat;
+  private fragmentShader: string;
+  private readonly cameraEnabled: boolean;
+  private readonly extraTextureCount: number;
+  private pipeline: GPURenderPipeline | null = null;
+  private bindGroupLayout: GPUBindGroupLayout | null = null;
+  private bindGroups: (GPUBindGroup | null)[] = [];
+  private uniformBuffer: GPUBuffer | null = null;
+  private cameraBuffer: GPUBuffer | null = null;
+  private gridTextures: (GPUTexture | null)[] = [];
+  private gridViews: (GPUTextureView | null)[] = [];
+  private paletteTexture: GPUTexture | null = null;
+  private paletteView: GPUTextureView | null = null;
+  private propsTexture: GPUTexture | null = null;
+  private propsView: GPUTextureView | null = null;
+  // Offscreen targets: one per layer (except the frontmost).
+  // Layer i's offscreen target is sampled by layer i+1 for reflections.
+  private offscreenTargets: (GPUTexture | null)[] = [];
+  private offscreenViews: (GPUTextureView | null)[] = [];
+  // 1×1 dummy texture for unbound slots (backmost layer's behind, extra textures)
+  private dummyTexture: GPUTexture | null = null;
+  private dummyView: GPUTextureView | null = null;
+  // Extra texture views (light accumulation, volumetric, ...) set per frame.
+  private extraViews: (GPUTextureView | null)[] = [];
+  private uniformBuf: Float32Array = new Float32Array(4);
+  // Scatter-update path (created lazily on first queueCellUpdate).
+  private scatterPipeline: GPUComputePipeline | null = null;
+  private scatterBindGroups: (GPUBindGroup | null)[] = [];
+  private cellsBuffer: GPUBuffer | null = null;
+  private scatterMetaBuffer: GPUBuffer | null = null;
+  private pendingCellCount = 0;
+  private pendingCellLayer = 0;
+  gridW: number;
+  gridH: number;
+  numLayers: number;
+
+  constructor(config: SandGridPassConfig) {
+    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): void {
+    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 as unknown as BufferSource,
+      { 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 as unknown as BufferSource,
+      { bytesPerRow: PALETTE_SIZE * 4, rowsPerImage: 1 },
+      [PALETTE_SIZE, 1],
+    );
+
+    const entries: GPUBindGroupLayoutEntry[] = [
+      { 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);
+    }
+  }
+
+  private createGridTexture(layer: number): void {
+    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();
+  }
+
+  private createOffscreenTarget(layer: number, w: number, h: number): void {
+    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();
+  }
+
+  private createBindGroup(layer: number): void {
+    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: GPUBindGroupEntry[] = [
+      { 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): GPUTextureView | null {
+    return this.gridViews[layer] ?? null;
+  }
+
+  /** Set an extra texture view (light accumulation, volumetric, ...). */
+  setExtraTexture(slot: number, view: GPUTextureView | null): void {
+    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: number, gridH: number, canvasW?: number, canvasH?: number): void {
+    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: Uint32Array, layer = 0): void {
+    if (!this.gridTextures[layer]) return;
+    this.device.queue.writeTexture(
+      { texture: this.gridTextures[layer]! },
+      grid.buffer as BufferSource,
+      { 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: Uint32Array, count: number, layer = 0): boolean {
+    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) as unknown as BufferSource);
+    this.device.queue.writeBuffer(this.scatterMetaBuffer!, 0, new Uint32Array([count, this.gridW, 0, 0]) as unknown as BufferSource);
+    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: GPUCommandEncoder): void {
+    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;
+  }
+
+  private ensureScatterResources(layer: number): void {
+    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(): void {
+    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 as unknown as BufferSource);
+  }
+
+  /** Camera uniforms — only when `camera: true`. */
+  updateCamera(camX: number, camY: number, zoom: number, canvasW: number, canvasH: number, depth: number = 0): void {
+    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: number): GPUTextureView | null {
+    return this.offscreenViews[layer];
+  }
+
+  render(pass: GPURenderPassEncoder, layer = 0): void {
+    if (!this.pipeline || !this.bindGroups[layer]) return;
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.bindGroups[layer]);
+    pass.draw(3);
+  }
+
+  destroy(): void {
+    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/libraries/sand/src/rng.ts

@@ -0,0 +1,51 @@
+// ============================================================================
+// 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 {
+  private state: number;
+
+  constructor(seed: number = 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: number): void {
+    this.state = (seed >>> 0) || 0x12345678;
+  }
+
+  /** Draw a u32 from the xorshift32 sequence. */
+  nextU32(): number {
+    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(): number {
+    // 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(): number {
+    return this.nextU32() & 3;
+  }
+
+  /** Random integer in [0, max). */
+  randomInt(max: number): number {
+    return (this.nextU32() >>> 0) % max;
+  }
+}