@downdraft/engine 0.1.0 → 0.1.2-alpha.5

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

@@ -0,0 +1,27 @@
+// ============================================================================
+// Shared per-cell physics field layout.
+//
+// Each cell carries 4 field bytes alongside its packed material cell:
+//   [gravity:u8, temp:u8, reserved:u8, reserved:u8]
+//
+// Wind/velocity is no longer stored per-cell. It's handled by the coarse-grid
+// FluidGrid (fluid-grid.ts) at 1/4 resolution, which provides proper pressure
+// relaxation and sustained airflow. The reserved bytes are kept for SAB layout
+// compatibility (avoiding save migration) but are unused.
+//
+// These constants are shared between the sand simulation (sand-world.ts) and
+// any game-specific SharedArrayBuffer bridge (e.g. a game's sim-buffer.ts
+// or a game's chunk SAB). Games keep their own SAB layout but reference
+// these field offsets so the indexing stays consistent.
+// ============================================================================
+export const FIELD = {
+    GRAVITY: 0,
+    TEMP: 1,
+    // Bytes 2-3 are reserved (formerly WIND_X/WIND_Y, now handled by FluidGrid).
+    // Kept for SAB layout compatibility — do not repurpose without updating
+    // grid-sim-buffer.ts fieldCellBytes and all save files.
+    RESERVED_2: 2,
+    RESERVED_3: 3,
+};
+export const DEFAULT_GRAVITY = 128; // u8, 128 = 1.0x
+export const DEFAULT_TEMP = 128; // u8, 128 = 1.0

package/dist/libraries/sand/src/fluid-grid.js

@@ -0,0 +1,267 @@
+// ============================================================================
+// FluidGrid — coarse-grid pressure/velocity fluid simulation.
+//
+// Replaces the per-cell wind field system with a proper fluid dynamics
+// simulation at 1/4 resolution. Each coarse cell covers 4×4 fine cells.
+//
+// The simulation runs a simplified Navier-Stokes step each frame:
+//   1. Pressure relaxation — pressure diffuses to neighbors
+//   2. Velocity from pressure gradient — velX/velY derived from pressure diffs
+//   3. Velocity damping — velocities decay slightly each frame
+//
+// This enables sustained airflow (fans), pressure equalization (gas flows
+// from high to low pressure), and realistic explosion shockwaves.
+//
+// Per-cell wind is sampled from the coarse grid via bilinear interpolation
+// in tryMove(), replacing the old per-cell WIND_X/WIND_Y fields.
+//
+// Inspired by the Dan-Ball dust2.js fluid simulation, which uses a similar
+// coarse-grid pressure/velocity approach at 1/4 particle resolution.
+// ============================================================================
+const COARSE_SCALE = 4; // each coarse cell = 4×4 fine cells
+export class FluidGrid {
+    // Coarse grid dimensions
+    cw;
+    ch;
+    // Pressure + velocity fields (Float32Array for performance)
+    pressure;
+    velX;
+    velY;
+    // Double-buffered temp arrays for relaxation steps
+    pressureNext;
+    velXNext;
+    velYNext;
+    // Solid mask — coarse cells blocked by walls/stone don't participate.
+    // 1 = solid (blocked), 0 = fluid (participates).
+    solid;
+    // Dirty flag — skip the step() entirely when no impulses or pressure exists.
+    dirty = false;
+    constructor(fineW, fineH) {
+        this.cw = Math.ceil(fineW / COARSE_SCALE);
+        this.ch = Math.ceil(fineH / COARSE_SCALE);
+        const n = this.cw * this.ch;
+        this.pressure = new Float32Array(n);
+        this.velX = new Float32Array(n);
+        this.velY = new Float32Array(n);
+        this.pressureNext = new Float32Array(n);
+        this.velXNext = new Float32Array(n);
+        this.velYNext = new Float32Array(n);
+        this.solid = new Uint8Array(n);
+    }
+    /** Mark a fine-grid cell as solid (wall/stone). Blocks fluid flow. */
+    setSolid(fineX, fineY) {
+        const cx = (fineX / COARSE_SCALE) | 0;
+        const cy = (fineY / COARSE_SCALE) | 0;
+        if (cx >= 0 && cx < this.cw && cy >= 0 && cy < this.ch) {
+            this.solid[cy * this.cw + cx] = 1;
+        }
+    }
+    /** Clear the solid flag for a fine-grid cell. */
+    clearSolid(fineX, fineY) {
+        const cx = (fineX / COARSE_SCALE) | 0;
+        const cy = (fineY / COARSE_SCALE) | 0;
+        if (cx >= 0 && cx < this.cw && cy >= 0 && cy < this.ch) {
+            this.solid[cy * this.cw + cx] = 0;
+        }
+    }
+    /**
+     * Apply an impulse at a fine-grid position. Adds to the velocity field
+     * with linear falloff from the center. Used for explosions, fans, etc.
+     */
+    applyImpulse(fineX, fineY, radius, strengthX, strengthY) {
+        const ccx = (fineX / COARSE_SCALE) | 0;
+        const ccy = (fineY / COARSE_SCALE) | 0;
+        const cr = Math.ceil(radius / COARSE_SCALE);
+        const cr2 = cr * cr;
+        for (let dy = -cr; dy <= cr; dy++) {
+            const ny = ccy + dy;
+            if (ny < 0 || ny >= this.ch)
+                continue;
+            for (let dx = -cr; dx <= cr; dx++) {
+                const nx = ccx + dx;
+                if (nx < 0 || nx >= this.cw)
+                    continue;
+                const dist2 = dx * dx + dy * dy;
+                if (dist2 > cr2)
+                    continue;
+                const falloff = 1 - Math.sqrt(dist2) / (cr + 1);
+                const idx = ny * this.cw + nx;
+                if (this.solid[idx])
+                    continue;
+                this.velX[idx] += strengthX * falloff;
+                this.velY[idx] += strengthY * falloff;
+                // Pressure impulse for shockwave effect
+                this.pressure[idx] += Math.abs(strengthX + strengthY) * falloff * 0.3;
+            }
+        }
+        this.dirty = true;
+    }
+    /**
+     * Sample horizontal velocity at a fine-grid position using bilinear
+     * interpolation. Returns a velocity in cells/frame units.
+     *
+     * Fast-path: when the fluid grid is not dirty (no active impulses/pressure),
+     * all velocities are zero — skip the bilinear math entirely. This eliminates
+     * ~90% of calls in normal play (no explosions = no fluid activity), which
+     * was the #1 CPU hot spot in profiling (13.3% of total sampled time).
+     */
+    sampleVelX(fineX, fineY) {
+        if (!this.dirty)
+            return 0;
+        const fx = fineX / COARSE_SCALE - 0.5;
+        const fy = fineY / COARSE_SCALE - 0.5;
+        const x0 = Math.floor(fx);
+        const y0 = Math.floor(fy);
+        const tx = fx - x0;
+        const ty = fy - y0;
+        const x1 = x0 + 1;
+        const y1 = y0 + 1;
+        const v00 = this.safeVelX(x0, y0);
+        const v10 = this.safeVelX(x1, y0);
+        const v01 = this.safeVelX(x0, y1);
+        const v11 = this.safeVelX(x1, y1);
+        return (1 - tx) * (1 - ty) * v00 + tx * (1 - ty) * v10 +
+            (1 - tx) * ty * v01 + tx * ty * v11;
+    }
+    /** Sample vertical velocity at a fine-grid position. */
+    sampleVelY(fineX, fineY) {
+        if (!this.dirty)
+            return 0;
+        const fx = fineX / COARSE_SCALE - 0.5;
+        const fy = fineY / COARSE_SCALE - 0.5;
+        const x0 = Math.floor(fx);
+        const y0 = Math.floor(fy);
+        const tx = fx - x0;
+        const ty = fy - y0;
+        const x1 = x0 + 1;
+        const y1 = y0 + 1;
+        const v00 = this.safeVelY(x0, y0);
+        const v10 = this.safeVelY(x1, y0);
+        const v01 = this.safeVelY(x0, y1);
+        const v11 = this.safeVelY(x1, y1);
+        return (1 - tx) * (1 - ty) * v00 + tx * (1 - ty) * v10 +
+            (1 - tx) * ty * v01 + tx * ty * v11;
+    }
+    /** Get the raw velocity magnitude at a coarse cell (for debugging/visualization). */
+    getPressure(cx, cy) {
+        if (cx < 0 || cx >= this.cw || cy < 0 || cy >= this.ch)
+            return 0;
+        return this.pressure[cy * this.cw + cx];
+    }
+    /** Whether any fluid activity exists (for skipping the step when idle). */
+    isActive() {
+        return this.dirty;
+    }
+    /** Clear all fields (e.g. on world clear/resize). */
+    clear() {
+        this.pressure.fill(0);
+        this.velX.fill(0);
+        this.velY.fill(0);
+        this.pressureNext.fill(0);
+        this.velXNext.fill(0);
+        this.velYNext.fill(0);
+        this.solid.fill(0);
+        this.dirty = false;
+    }
+    /**
+     * Run one simulation step:
+     *   1. Pressure relaxation (diffuse to neighbors)
+     *   2. Velocity from pressure gradient
+     *   3. Velocity damping
+     *
+     * Skipped entirely when no impulses have been applied and all fields are
+     * near-zero (the dirty flag tracks this).
+     */
+    step() {
+        if (!this.dirty)
+            return;
+        const cw = this.cw, ch = this.ch;
+        const pressure = this.pressure;
+        const velX = this.velX, velY = this.velY;
+        const pressureNext = this.pressureNext;
+        const velXNext = this.velXNext, velYNext = this.velYNext;
+        const solid = this.solid;
+        // --- 1. Pressure relaxation (diffuse) ---
+        // Each cell's pressure moves toward the average of its neighbors.
+        // This is a single Jacobi iteration — enough for visual fluid flow.
+        for (let y = 0; y < ch; y++) {
+            for (let x = 0; x < cw; x++) {
+                const idx = y * cw + x;
+                if (solid[idx]) {
+                    pressureNext[idx] = 0;
+                    continue;
+                }
+                let sum = pressure[idx] * 2; // self-weight
+                let count = 2;
+                if (x > 0 && !solid[idx - 1]) {
+                    sum += pressure[idx - 1];
+                    count++;
+                }
+                if (x < cw - 1 && !solid[idx + 1]) {
+                    sum += pressure[idx + 1];
+                    count++;
+                }
+                if (y > 0 && !solid[idx - cw]) {
+                    sum += pressure[idx - cw];
+                    count++;
+                }
+                if (y < ch - 1 && !solid[idx + cw]) {
+                    sum += pressure[idx + cw];
+                    count++;
+                }
+                pressureNext[idx] = sum / count;
+            }
+        }
+        // --- 2. Velocity from pressure gradient ---
+        // velX -= (P[x+1] - P[x-1]) * dt
+        // velY -= (P[y+1] - P[y-1]) * dt
+        // Pressure naturally pushes flow from high to low.
+        const pressureGrad = 0.15;
+        for (let y = 0; y < ch; y++) {
+            for (let x = 0; x < cw; x++) {
+                const idx = y * cw + x;
+                if (solid[idx]) {
+                    velXNext[idx] = 0;
+                    velYNext[idx] = 0;
+                    continue;
+                }
+                const pL = x > 0 && !solid[idx - 1] ? pressureNext[idx - 1] : pressureNext[idx];
+                const pR = x < cw - 1 && !solid[idx + 1] ? pressureNext[idx + 1] : pressureNext[idx];
+                const pU = y > 0 && !solid[idx - cw] ? pressureNext[idx - cw] : pressureNext[idx];
+                const pD = y < ch - 1 && !solid[idx + cw] ? pressureNext[idx + cw] : pressureNext[idx];
+                velXNext[idx] = velX[idx] - (pR - pL) * pressureGrad;
+                velYNext[idx] = velY[idx] - (pD - pU) * pressureGrad;
+            }
+        }
+        // --- 3. Damping + pressure decay ---
+        // Velocities decay ~10% per frame. Pressure decays faster (it's a
+        // transient impulse, not a sustained field). This prevents impulses
+        // from persisting forever and keeps the sim stable.
+        const velDamping = 0.9;
+        const pressureDamping = 0.85;
+        let anyActive = false;
+        for (let i = 0; i < cw * ch; i++) {
+            velX[i] = velXNext[i] * velDamping;
+            velY[i] = velYNext[i] * velDamping;
+            pressure[i] = pressureNext[i] * pressureDamping;
+            if (Math.abs(velX[i]) > 0.01 || Math.abs(velY[i]) > 0.01 || Math.abs(pressure[i]) > 0.01) {
+                anyActive = true;
+            }
+        }
+        // Clear dirty flag if everything has decayed to near-zero.
+        this.dirty = anyActive;
+    }
+    // --- Internal helpers ---
+    safeVelX(cx, cy) {
+        if (cx < 0 || cx >= this.cw || cy < 0 || cy >= this.ch)
+            return 0;
+        const idx = cy * this.cw + cx;
+        return this.solid[idx] ? 0 : this.velX[idx];
+    }
+    safeVelY(cx, cy) {
+        if (cx < 0 || cx >= this.cw || cy < 0 || cy >= this.ch)
+            return 0;
+        const idx = cy * this.cw + cx;
+        return this.solid[idx] ? 0 : this.velY[idx];
+    }
+}

package/dist/libraries/sand/src/grid-dims.js

@@ -0,0 +1,47 @@
+// ============================================================================
+// computeGridDims — shared grid dimension calculator for sand/grid games
+// ============================================================================
+//
+// Both falling-sand and sandjongg (and any future grid-based sand game) need
+// to compute sand grid dimensions from canvas buffer pixels. The math is
+// identical except for the base cell size, max grid bounds, and optional
+// alignment. This shared utility eliminates the duplication.
+//
+/**
+ * Compute sand grid dimensions from canvas buffer dimensions (CSS × DPR).
+ *
+ * The grid is sized so that each cell covers `baseCellPx * dpr` canvas pixels,
+ * keeping cell density consistent across HiDPI displays. If the computed size
+ * exceeds `maxGridW`/`maxGridH`, both dimensions are scaled down proportionally
+ * to preserve the aspect ratio (guarantees square cells).
+ *
+ * @param canvasW  Canvas backing-store width (CSS width × DPR).
+ * @param canvasH  Canvas backing-store height (CSS height × DPR).
+ * @param options  Configuration (base cell size, max grid, alignment).
+ * @returns `{ w, h }` grid dimensions in cells.
+ */
+export function computeGridDims(canvasW, canvasH, options) {
+    const { baseCellPx, maxGridW, maxGridH } = options;
+    const minDim = options.minDim ?? 32;
+    const align = options.align ?? 1;
+    const dpr = typeof window !== "undefined" ? (window.devicePixelRatio || 1) : 1;
+    const cellPx = baseCellPx * dpr;
+    let w = Math.floor(canvasW / cellPx);
+    let h = Math.floor(canvasH / cellPx);
+    // Clamp to minimums.
+    w = Math.max(minDim, w);
+    h = Math.max(minDim, h);
+    // If either dimension exceeds the max, scale BOTH proportionally
+    // to preserve aspect ratio (guarantees 1:1 cells).
+    if (w > maxGridW || h > maxGridH) {
+        const scale = Math.min(maxGridW / w, maxGridH / h);
+        w = Math.max(minDim, Math.floor(w * scale));
+        h = Math.max(minDim, Math.floor(h * scale));
+    }
+    // Align to a multiple of `align` (e.g. 4 for Uint32Array row alignment).
+    if (align > 1) {
+        w = Math.floor(w / align) * align;
+        h = Math.floor(h / align) * align;
+    }
+    return { w, h };
+}

package/dist/libraries/sand/src/grid-sim-buffer.js

@@ -0,0 +1,184 @@
+// ============================================================================
+// GridSimBuffer — generic SharedArrayBuffer layout for grid-based games
+// ============================================================================
+//
+// Provides a configurable SAB layout for cellular automata / sand games that
+// need to transfer grid + field data between a sim worker and the renderer.
+//
+// Layout:
+//   [grid layer 0] [field layer 0] [grid layer 1] [field layer 1] ...
+//   [extra grid layers (e.g. background)]
+//   [input region] [stats region] [player region] [extra regions...]
+//
+// Games configure the layout via GridSimBufferLayout, then use GridSimBufferReader
+// and GridSimBufferWriter to access the SAB. Game-specific field offset constants
+// (INPUT, STATS, PLAYER) stay in the game — only the storage boilerplate is shared.
+/** Compute byte offsets for a grid SAB layout. */
+export function computeGridSimOffsets(layout) {
+    const gridCellBytes = layout.gridCellBytes ?? 4;
+    const fieldCellBytes = layout.fieldCellBytes ?? 4;
+    const inputBytes = layout.inputBytes ?? 128;
+    const statsBytes = layout.statsBytes ?? 16;
+    const playerBytes = layout.playerBytes ?? 0;
+    const gridBytes = layout.maxGridW * layout.maxGridH * gridCellBytes;
+    const fieldBytes = layout.maxGridW * layout.maxGridH * fieldCellBytes;
+    const layerBytes = gridBytes + fieldBytes;
+    const allLayersBytes = layerBytes * layout.numLayers;
+    const gridOffset = [];
+    const fieldOffset = [];
+    for (let i = 0; i < layout.numLayers; i++) {
+        gridOffset.push(i * layerBytes);
+        fieldOffset.push(i * layerBytes + gridBytes);
+    }
+    let cursor = allLayersBytes;
+    const extraGridOffset = {};
+    (layout.extraGrids ?? []).forEach((eg) => {
+        extraGridOffset[eg.name] = cursor;
+        cursor += layout.maxGridW * layout.maxGridH * eg.cellBytes;
+    });
+    const inputOffset = cursor;
+    cursor += inputBytes;
+    const statsOffset = cursor;
+    cursor += statsBytes;
+    const playerOffset = playerBytes > 0 ? cursor : 0;
+    if (playerBytes > 0)
+        cursor += playerBytes;
+    const extraRegionOffset = {};
+    (layout.extraRegions ?? []).forEach((er) => {
+        extraRegionOffset[er.name] = cursor;
+        cursor += er.bytes;
+    });
+    return {
+        gridOffset, fieldOffset, extraGridOffset,
+        inputOffset, statsOffset, playerOffset, extraRegionOffset,
+        totalBytes: cursor, layerBytes, gridBytes, fieldBytes,
+    };
+}
+/** Allocate a SharedArrayBuffer for the given layout. */
+export function allocateGridSimBuffer(layout) {
+    const offsets = computeGridSimOffsets(layout);
+    return new SharedArrayBuffer(offsets.totalBytes);
+}
+// --- Reader ---
+export class GridSimBufferReader {
+    u32;
+    buf;
+    u8;
+    f32;
+    offsets;
+    gridW;
+    gridH;
+    constructor(sab, offsets, gridW, gridH) {
+        this.u32 = new Uint32Array(sab);
+        this.buf = new Int32Array(sab);
+        this.u8 = new Uint8Array(sab);
+        this.f32 = new Float32Array(sab);
+        this.offsets = offsets;
+        this.gridW = gridW;
+        this.gridH = gridH;
+    }
+    setDims(w, h) {
+        this.gridW = w;
+        this.gridH = h;
+    }
+    getOffsets() {
+        return this.offsets;
+    }
+    /** Get a view of grid layer N (Uint32Array). */
+    getGrid(layer = 0) {
+        const off = this.offsets.gridOffset[layer] / 4;
+        return this.u32.subarray(off, off + this.gridW * this.gridH);
+    }
+    /** Get a view of field layer N (Uint8Array). */
+    getFieldGrid(layer = 0) {
+        const off = this.offsets.fieldOffset[layer];
+        return this.u8.subarray(off, off + this.gridW * this.gridH * 4);
+    }
+    /** Get a view of an extra grid (Uint32Array). */
+    getExtraGrid(name) {
+        const off = this.offsets.extraGridOffset[name] / 4;
+        return this.u32.subarray(off, off + this.gridW * this.gridH);
+    }
+    getInput(field) {
+        return this.buf[this.offsets.inputOffset / 4 + field / 4];
+    }
+    getInputF32(field) {
+        return this.f32[(this.offsets.inputOffset + field) / 4];
+    }
+    getStat(field) {
+        return this.buf[this.offsets.statsOffset / 4 + field / 4];
+    }
+    getPlayerF32(field) {
+        return this.f32[(this.offsets.playerOffset + field) / 4];
+    }
+    getPlayerI32(field) {
+        return this.buf[this.offsets.playerOffset / 4 + field / 4];
+    }
+    /** Get a Uint32Array view of an extra region. */
+    getExtraRegionU32(name, count) {
+        const off = this.offsets.extraRegionOffset[name] / 4;
+        return this.u32.subarray(off, off + count);
+    }
+}
+// --- Writer ---
+export class GridSimBufferWriter {
+    u32;
+    buf;
+    u8;
+    f32;
+    offsets;
+    gridW;
+    gridH;
+    constructor(sab, offsets, gridW, gridH) {
+        this.u32 = new Uint32Array(sab);
+        this.buf = new Int32Array(sab);
+        this.u8 = new Uint8Array(sab);
+        this.f32 = new Float32Array(sab);
+        this.offsets = offsets;
+        this.gridW = gridW;
+        this.gridH = gridH;
+    }
+    setDims(w, h) {
+        this.gridW = w;
+        this.gridH = h;
+    }
+    getOffsets() {
+        return this.offsets;
+    }
+    writeGrid(grid, layer = 0) {
+        const off = this.offsets.gridOffset[layer] / 4;
+        this.u32.set(grid.subarray(0, this.gridW * this.gridH), off);
+    }
+    writeFieldGrid(fields, layer = 0) {
+        const off = this.offsets.fieldOffset[layer];
+        this.u8.set(fields.subarray(0, this.gridW * this.gridH * 4), off);
+    }
+    writeExtraGrid(name, grid) {
+        const off = this.offsets.extraGridOffset[name] / 4;
+        this.u32.set(grid.subarray(0, this.gridW * this.gridH), off);
+    }
+    writeInput(field, value) {
+        this.buf[this.offsets.inputOffset / 4 + field / 4] = value;
+    }
+    writeInputF32(field, value) {
+        this.f32[(this.offsets.inputOffset + field) / 4] = value;
+    }
+    writeStat(field, value) {
+        this.buf[this.offsets.statsOffset / 4 + field / 4] = value;
+    }
+    writePlayerF32(field, value) {
+        this.f32[(this.offsets.playerOffset + field) / 4] = value;
+    }
+    writePlayerI32(field, value) {
+        this.buf[this.offsets.playerOffset / 4 + field / 4] = value;
+    }
+    writeExtraRegionU32(name, data) {
+        const off = this.offsets.extraRegionOffset[name] / 4;
+        this.u32.set(data, off);
+    }
+    /** Clear the input region to zeros. */
+    clearInput() {
+        const inputBytes = this.offsets.extraRegionOffset["__input_end__"] ?? 128;
+        this.buf.fill(0, this.offsets.inputOffset / 4, (this.offsets.inputOffset + inputBytes) / 4);
+    }
+}

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

@@ -0,0 +1,20 @@
+// @downdraft/engine/libraries/sand — reusable falling-sand simulation primitives.
+//
+// Extracted from a game so multiple games share the same material definitions,
+// cell packing, and SandWorld simulation.
+// Games keep their own SharedArrayBuffer/worker wiring but import the core
+// sim types and the SandWorld class from here.
+export { FLAG_ANCHORED, FLAG_POPPED, FLAG_SPARK, FLAG_UPDATED, FLAG_UPDATED_BIT, pack, packCell, SHADE_MASK, unpack } from "./cell.js";
+export { SandRNG } from "./rng.js";
+export { DEFAULT_GRAVITY, DEFAULT_TEMP, FIELD } from "./fields.js";
+export { FluidGrid } from "./fluid-grid.js";
+export { PARTICLE_BYTES, PARTICLE_FLOATS, PARTICLE_TYPES, ParticleSystem } from "./particles.js";
+export { buildMaterialProps, buildPalette, PALETTE_SIZE, SHADES_PER_MATERIAL } from "./palette.js";
+export { getMaterialColor, IS_COLD, IS_FIRE, IS_HOT, MAT_CLIMBABLE, MAT_DENSITY, MAT_FLAGS, MAT_FLAMMABLE, MAT_GAS, MAT_GRAVITY, MAT_GRAVITY_DIR, MAT_LIFETIME, MAT_LIQUID, MAT_MAGNETIC, MAT_SOLID, Material, MATERIALS, MAX_MATERIAL } from "./materials.js";
+export { SandStepPool } from "./sand-step-pool.js";
+export { GRAVEL_DISTURB_SETTLE_TICKS, GRAVEL_SETTLE_TICKS, SandWorld } from "./sand-world.js";
+// Generic grid-based SharedArrayBuffer framework for sand/grid games
+export { allocateGridSimBuffer, computeGridSimOffsets, GridSimBufferReader, GridSimBufferWriter } from "./grid-sim-buffer.js";
+export { computeGridDims } from "./grid-dims.js";
+export { SandLib, SandWorldTok } from "./library.js";
+export { MAX_SCATTER_CELLS, SandGridPass } from "./render/sand-grid-pass.js";

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

@@ -0,0 +1,67 @@
+// ============================================================================
+// SandLib — declarative engine library descriptor for @downdraft/engine/libraries/sand
+//
+// Games declare `libraries: [SandLib]` (or with config override) in their
+// GameModule. The host allocates the sand grid SAB, creates the SandWorld
+// (sim-side), and exposes it via a typed token.
+//
+// Games that need full control can still import SandWorld directly
+// (escape hatch).
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { SandWorld } from "./sand-world.js";
+// ── Typed tokens (DI) ──
+/** Token for the sim-side sand world. Inject in sim systems that need sand. */
+export const SandWorldTok = resourceToken("sand:world");
+// ── SAB channel sizing ──
+// Grid: W*H cells * 4 bytes (Uint32Array)
+// Fields: W*H cells * 4 bytes (Uint8Array: gravity, temp, windX, windY)
+// Skip mask: W*H cells * 1 byte
+// Deferred mask: W*H cells * 1 byte
+function sandSABSize(w, h) {
+    const cells = w * h;
+    return cells * 4 + cells * 4 + cells + cells;
+}
+// ── Descriptor ──
+export const SandLib = {
+    name: "sand",
+    version: "1.0.0",
+    sabChannels: [
+        { name: "sand", size: sandSABSize(256, 256) },
+    ],
+    provides: [SandWorldTok],
+    sim: {
+        create(config, ctx) {
+            const w = config.width ?? 256;
+            const h = config.height ?? 256;
+            const cells = w * h;
+            const gridBytes = cells * 4;
+            const fieldsBytes = cells * 4;
+            const skipMaskOffset = gridBytes + fieldsBytes;
+            const deferredMaskOffset = skipMaskOffset + cells;
+            const world = new SandWorld(w, h, {
+                sab: ctx.buffers.sand,
+                gridOffset: 0,
+                fieldsOffset: gridBytes,
+                skipMaskOffset,
+                deferredMaskOffset,
+            });
+            ctx.provide(SandWorldTok, world);
+            return world;
+        },
+        dispose(world) {
+            // SandWorld holds SAB views — no GPU resources to free.
+            // The SAB itself is managed by the host.
+        },
+        // tick is game-specific (calls world.step() with material rules, etc.)
+        // — games wire this via onReady or a sim system.
+    },
+    tickPhase: "post-physics",
+    // No renderer setup — sand rendering is game-specific (the game creates
+    // a sand render pass that reads the grid SAB).
+    defaultConfig: {
+        width: 256,
+        height: 256,
+        useSAB: true,
+    },
+};