@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/libraries/sand/src/sand-step-pool.js

@@ -0,0 +1,458 @@
+// ============================================================================
+// Sand step pool — multi-threaded coordinator for SandWorld.step().
+//
+// Runs inside the mining worker. Spawns N sand-step workers, each processing
+// a vertical strip of the grid. The grid + fields + deferred mask are backed
+// by a single SharedArrayBuffer shared across all workers.
+//
+// Per step:
+//   1. Dispatch step messages to all workers (postMessage, fire-and-forget).
+//   2. Wait for all workers to report done (Promise.all of message events).
+//   3. Boundary cleanup: re-run the movement pass on boundary columns, but
+//      ONLY for cells whose cross-strip move was deferred by the write guard
+//      (marked in the shared deferredMask). Write bounds are restricted to
+//      the adjacent strip so only cross-strip moves are attempted, and RNG
+//      gates are skipped (boundaryPass mode) to avoid giving boundary cells
+//      an unfair second movement chance.
+//
+// The boundary cleanup runs on the coordinator's own SandWorld instance
+// but only iterates the boundary columns and only the deferred cells within
+// them. This is O(boundaryColumns * H) — typically 2*(N-1) columns —
+// much cheaper than the full O(W*H) step.
+// ============================================================================
+import { MAT_GRAVITY, MAT_GRAVITY_DIR, SandWorld } from "./sand-world.js";
+export class SandStepPool {
+    workers = [];
+    W;
+    H;
+    numWorkers;
+    sab;
+    gridOffset;
+    fieldsOffset;
+    skipMaskOffset;
+    deferredMaskOffset;
+    histogramOffset;
+    strips = [];
+    // The coordinator's own SandWorld for boundary cleanup. It shares the same
+    // SAB-backed grid as the workers but has full-grid write bounds.
+    boundaryWorld;
+    workerUrl;
+    initialized = false;
+    // In-flight init() promise — deduplicates concurrent init() calls so that
+    // two callers (e.g. loadGrid + onTick racing) share one initialization
+    // instead of each spawning a full set of workers. Without this, concurrent
+    // init() calls each push numWorkers workers into `this.workers`, leaving
+    // workers.length > strips.length and crashing step() on `strip.startX`.
+    initPromise = null;
+    gravityOverrides;
+    // Rebalance throttle: only rebalance every N steps to avoid overhead.
+    stepCount = 0;
+    REBALANCE_INTERVAL = 8;
+    constructor(opts) {
+        this.W = opts.W;
+        this.H = opts.H;
+        this.numWorkers = Math.max(1, opts.numWorkers);
+        const cells = opts.W * opts.H;
+        const gridBytes = cells * 4;
+        const fieldsBytes = cells * 4;
+        const skipMaskBytes = cells; // 1 byte per cell
+        const deferredMaskBytes = cells; // 1 byte per cell
+        const histogramBytes = opts.W * 4; // 1 uint32 per column
+        // The histogram is a Uint32Array view — its byte offset must stay
+        // 4-aligned even when `cells` is odd (skip/deferred are 1B per cell).
+        const align4 = (n) => (n + 3) & ~3;
+        if (opts.sab) {
+            this.sab = opts.sab;
+            this.gridOffset = opts.gridOffset ?? 0;
+            this.fieldsOffset = opts.fieldsOffset ?? gridBytes;
+            this.skipMaskOffset = opts.skipMaskOffset ?? (gridBytes + fieldsBytes);
+            this.deferredMaskOffset = opts.deferredMaskOffset ?? (gridBytes + fieldsBytes + skipMaskBytes);
+            this.histogramOffset = opts.histogramOffset ?? align4(gridBytes + fieldsBytes + skipMaskBytes + deferredMaskBytes);
+        }
+        else {
+            // Allocate a SAB for grid + fields + skip mask + deferred mask + histogram.
+            this.gridOffset = 0;
+            this.fieldsOffset = gridBytes;
+            this.skipMaskOffset = gridBytes + fieldsBytes;
+            this.deferredMaskOffset = gridBytes + fieldsBytes + skipMaskBytes;
+            this.histogramOffset = align4(gridBytes + fieldsBytes + skipMaskBytes + deferredMaskBytes);
+            this.sab = new SharedArrayBuffer(this.histogramOffset + histogramBytes);
+        }
+        // Compute strip boundaries — divide W into numWorkers roughly-equal strips.
+        this.strips = this.computeStrips(opts.W, this.numWorkers);
+        // Coordinator's boundary cleanup world — full grid bounds, SAB-backed.
+        this.boundaryWorld = new SandWorld(opts.W, opts.H, {
+            sab: this.sab,
+            gridOffset: this.gridOffset,
+            fieldsOffset: this.fieldsOffset,
+            skipMaskOffset: this.skipMaskOffset,
+            deferredMaskOffset: this.deferredMaskOffset,
+            histogramOffset: this.histogramOffset,
+            skipStoneFloor: true,
+        });
+        if (opts.preserveFlagsMask !== undefined)
+            this.boundaryWorld.preserveFlagsMask = opts.preserveFlagsMask;
+        if (opts.disturbedFlags !== undefined)
+            this.boundaryWorld.disturbedFlags = opts.disturbedFlags;
+        // Apply gravity overrides to the coordinator's boundary world too.
+        if (opts.gravityOverrides) {
+            this.gravityOverrides = opts.gravityOverrides;
+            opts.gravityOverrides.forEach((o) => {
+                MAT_GRAVITY_DIR[o.mat] = o.gravityDir;
+                if (o.gravity !== 0)
+                    MAT_GRAVITY[o.mat] = o.gravity;
+            });
+        }
+        // Custom worker URL — when provided, workers are created from this URL.
+        // When not provided, init() uses the inline `new Worker(new URL(...))`
+        // pattern so Vite can bundle the nested worker for production builds.
+        this.workerUrl = opts.workerUrl ?? null;
+    }
+    computeStrips(W, n) {
+        const strips = [];
+        const base = Math.floor(W / n);
+        const rem = W % n;
+        let x = 0;
+        for (let i = 0; i < n; i++) {
+            const w = base + (i < rem ? 1 : 0);
+            strips.push({ startX: x, endX: x + w });
+            x += w;
+        }
+        return strips;
+    }
+    /**
+     * Compute balanced strip boundaries from the per-column active cell
+     * histogram. Uses a prefix-sum to find N boundaries that split the total
+     * active cell count as evenly as possible. This equalizes per-worker load
+     * regardless of where particles cluster in the X dimension.
+     *
+     * Each strip gets at least 1 column (guards against degenerate cases where
+     * most columns are empty).
+     */
+    computeBalancedStrips(histogram, n) {
+        const W = histogram.length;
+        // Prefix sum of active cells per column.
+        const prefix = new Float64Array(W + 1);
+        let total = 0;
+        for (let x = 0; x < W; x++) {
+            total += histogram[x];
+            prefix[x + 1] = total;
+        }
+        // If the grid is (nearly) empty, fall back to equal-width strips.
+        if (total < n)
+            return this.computeStrips(W, n);
+        const strips = [];
+        const targetPerStrip = total / n;
+        let x = 0;
+        for (let i = 0; i < n; i++) {
+            const target = (i + 1) * targetPerStrip;
+            // Find the column x where prefix[x+1] first reaches the target.
+            // Binary search for efficiency (W can be 640+).
+            let lo = x, hi = W;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1;
+                if (prefix[mid + 1] < target)
+                    lo = mid + 1;
+                else
+                    hi = mid;
+            }
+            let endX = lo;
+            // Ensure at least 1 column per strip.
+            if (endX <= x)
+                endX = x + 1;
+            // Ensure the last strip reaches W.
+            if (i === n - 1)
+                endX = W;
+            // Don't exceed W.
+            if (endX > W)
+                endX = W;
+            strips.push({ startX: x, endX });
+            x = endX;
+        }
+        return strips;
+    }
+    /** Initialize all workers. Must be called before step(). */
+    async init() {
+        if (this.initialized)
+            return;
+        // Deduplicate concurrent init() calls. If two callers race into init()
+        // (e.g. loadGrid's pool recreation overlapping with onTick's
+        // `if (!this.initialized) await this.init()`), they share the same
+        // initialization promise instead of each spawning numWorkers workers.
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.runInit();
+        try {
+            await this.initPromise;
+        }
+        finally {
+            this.initPromise = null;
+        }
+    }
+    async runInit() {
+        const initPromises = [];
+        for (let i = 0; i < this.numWorkers; i++) {
+            // Use inline `new Worker(new URL(...))` when no custom URL is provided
+            // so Vite can detect and bundle the nested worker for production builds.
+            // Assigning the URL to a variable first breaks Vite's worker bundling.
+            const worker = this.workerUrl
+                ? new Worker(this.workerUrl, { type: "module" })
+                : new Worker(new URL("./sand-step-worker.js", import.meta.url), { type: "module" });
+            // Nested workers are process-scoped, not parent-scoped — a sim worker
+            // force-terminated before pool.shutdown() would orphan these and pin
+            // process exit. unref keeps a leaked pool worker from holding the
+            // runtime open.
+            worker.unref?.();
+            this.workers.push(worker);
+            const strip = this.strips[i];
+            initPromises.push(new Promise((resolve, reject) => {
+                const onWorkerError = (e) => {
+                    reject(new Error(`sand-step-worker ${i} error: ${e.message ?? "undefined"} file=${e.filename ?? "none"}`));
+                };
+                worker.addEventListener("error", onWorkerError);
+                const handler = (e) => {
+                    if (e.data.type === "ready") {
+                        worker.removeEventListener("message", handler);
+                        worker.removeEventListener("error", onWorkerError);
+                        resolve();
+                    }
+                };
+                worker.addEventListener("message", handler);
+                worker.postMessage({
+                    type: "init",
+                    sab: this.sab,
+                    gridOffset: this.gridOffset,
+                    fieldsOffset: this.fieldsOffset,
+                    skipMaskOffset: this.skipMaskOffset,
+                    deferredMaskOffset: this.deferredMaskOffset,
+                    histogramOffset: this.histogramOffset,
+                    W: this.W,
+                    H: this.H,
+                    stripStartX: strip.startX,
+                    stripEndX: strip.endX,
+                    preserveFlagsMask: this.boundaryWorld.preserveFlagsMask,
+                    disturbedFlags: this.boundaryWorld.disturbedFlags,
+                    gravityOverrides: this.gravityOverrides,
+                });
+            }));
+        }
+        await Promise.all(initPromises);
+        this.initialized = true;
+    }
+    /** Get the SAB-backed skip mask (coordinator writes to it, workers read). */
+    getSkipMask() {
+        return this.boundaryWorld.skipMask;
+    }
+    /** Copy an external skip mask into the SAB-backed skip mask. */
+    setSkipMask(mask) {
+        const sabMask = this.boundaryWorld.skipMask;
+        if (sabMask) {
+            sabMask.set(mask.subarray(0, this.W * this.H));
+        }
+    }
+    /** Sync config to all workers. Called when interlace/impulse settings change. */
+    lastConfig = {
+        interlaceEnabled: false,
+        interlaceScale: 1,
+        horizontalImpulseChance: 0.02,
+        horizontalImpulseStrength: 1,
+    };
+    updateConfig(config) {
+        if (config.interlaceEnabled !== undefined)
+            this.lastConfig.interlaceEnabled = config.interlaceEnabled;
+        if (config.interlaceScale !== undefined)
+            this.lastConfig.interlaceScale = config.interlaceScale;
+        if (config.horizontalImpulseChance !== undefined)
+            this.lastConfig.horizontalImpulseChance = config.horizontalImpulseChance;
+        if (config.horizontalImpulseStrength !== undefined)
+            this.lastConfig.horizontalImpulseStrength = config.horizontalImpulseStrength;
+        // Also update the boundary world
+        this.boundaryWorld.interlaceEnabled = this.lastConfig.interlaceEnabled;
+        this.boundaryWorld.interlaceScale = this.lastConfig.interlaceScale;
+        this.boundaryWorld.horizontalImpulseChance = this.lastConfig.horizontalImpulseChance;
+        this.boundaryWorld.horizontalImpulseStrength = this.lastConfig.horizontalImpulseStrength;
+    }
+    /**
+     * Run one sand step across all workers + boundary cleanup.
+     * Returns a promise that resolves when all workers + cleanup are done.
+     */
+    async step(frame) {
+        if (!this.initialized)
+            await this.init();
+        // Dispatch step to all workers. The skip mask + histogram are in the SAB —
+        // workers read/write them directly, no need to post.
+        const stepPromises = [];
+        for (let i = 0; i < this.workers.length; i++) {
+            const worker = this.workers[i];
+            const strip = this.strips[i];
+            stepPromises.push(new Promise((resolve) => {
+                const handler = (e) => {
+                    if (e.data.type === "done") {
+                        worker.removeEventListener("message", handler);
+                        resolve();
+                    }
+                };
+                worker.addEventListener("message", handler);
+                worker.postMessage({
+                    type: "step",
+                    frame,
+                    stripStartX: strip.startX,
+                    stripEndX: strip.endX,
+                    interlaceEnabled: this.lastConfig.interlaceEnabled,
+                    interlaceScale: this.lastConfig.interlaceScale,
+                    horizontalImpulseChance: this.lastConfig.horizontalImpulseChance,
+                    horizontalImpulseStrength: this.lastConfig.horizontalImpulseStrength,
+                });
+            }));
+        }
+        await Promise.all(stepPromises);
+        // Boundary cleanup: re-run movement on the 1-cell-wide columns at each
+        // strip boundary. The workers skipped cross-strip writes; this pass lets
+        // particles at the boundary move into the adjacent strip.
+        this.runBoundaryCleanup(frame);
+        // Periodically rebalance strip boundaries based on the per-column active
+        // cell histogram (written by workers during buildActiveListAndClearFlags).
+        // The histogram is in the SAB — no postMessage needed. New boundaries take
+        // effect on the next step (passed in the step message).
+        this.stepCount++;
+        if (this.stepCount % this.REBALANCE_INTERVAL === 0 && this.numWorkers > 1) {
+            const histogram = this.boundaryWorld.histogram;
+            if (histogram) {
+                this.strips = this.computeBalancedStrips(histogram, this.numWorkers);
+            }
+        }
+    }
+    /**
+     * Boundary cleanup: re-run the movement pass on boundary columns, but ONLY
+     * for cells whose cross-strip move was deferred by the write guard during
+     * the worker pass (marked in the shared deferredMask).
+     *
+     * For each interior strip boundary (between strip i and i+1), we process:
+     *   - The last column of strip i — can now write into strip i+1.
+     *   - The first column of strip i+1 — can now write into strip i.
+     *
+     * Key differences from the old approach (which re-ran the FULL tryMove on
+     * every boundary cell with full-grid write bounds):
+     *
+     * 1. Only deferred cells are processed. Cells that didn't attempt a
+     *    cross-strip move (friction-blocked, obstacle-blocked, or already moved)
+     *    are skipped. This prevents the cleanup from re-rolling RNG gates
+     *    (friction, flicker, impulse, wind) and giving boundary cells an unfair
+     *    second movement chance — the root cause of "fast falling" artifacts at
+     *    strip boundaries.
+     *
+     * 2. Write bounds are restricted to the adjacent strip for each column, so
+     *    only cross-strip moves are attempted. Within-strip moves (which the
+     *    worker already handled) are blocked by the write guard.
+     *
+     * 3. The boundaryPass flag on the boundary world skips all RNG-based
+     *    movement gates in tryMove — those already had their chance during the
+     *    worker pass.
+     *
+     * This is a movement-only pass — reactions, combustion, and aging already
+     * ran in the workers. We only handle the cross-strip movement writes that
+     * were skipped at the boundaries.
+     */
+    runBoundaryCleanup(frame) {
+        if (this.numWorkers <= 1)
+            return; // no boundaries with a single worker
+        const bw = this.boundaryWorld;
+        bw.frame = frame;
+        bw.boundaryPass = true;
+        const grid = bw.grid;
+        const deferred = bw.deferredMask;
+        if (deferred === null) {
+            // No deferred mask (non-SAB mode) — nothing to do.
+            bw.boundaryPass = false;
+            return;
+        }
+        const W = this.W;
+        const H = this.H;
+        // Process each interior boundary pair separately so we can restrict
+        // write bounds to the adjacent strip for each column.
+        for (let bi = 0; bi < this.strips.length - 1; bi++) {
+            const leftStrip = this.strips[bi];
+            const rightStrip = this.strips[bi + 1];
+            const leftCol = leftStrip.endX - 1; // last col of left strip
+            const rightCol = rightStrip.startX; // first col of right strip
+            // Process the left boundary column — can only write into the right strip.
+            bw.writeXMin = rightStrip.startX;
+            bw.writeXMax = rightStrip.endX;
+            this.processBoundaryColumn(bw, grid, deferred, leftCol, W, H);
+            // Process the right boundary column — can only write into the left strip.
+            bw.writeXMin = leftStrip.startX;
+            bw.writeXMax = leftStrip.endX;
+            this.processBoundaryColumn(bw, grid, deferred, rightCol, W, H);
+        }
+        // Reset boundary pass state.
+        bw.boundaryPass = false;
+        bw.writeXMin = 0;
+        bw.writeXMax = W;
+        // Clear the deferred mask on all boundary columns — the mask is also
+        // cleared at the start of the next frame by buildActiveListAndClearFlags,
+        // but clearing here prevents any stale markers from affecting a potential
+        // second cleanup call within the same frame.
+        for (let bi = 0; bi < this.strips.length - 1; bi++) {
+            const leftCol = this.strips[bi].endX - 1;
+            const rightCol = this.strips[bi + 1].startX;
+            for (let y = 0; y < H; y++) {
+                deferred[y * W + leftCol] = 0;
+                deferred[y * W + rightCol] = 0;
+            }
+        }
+    }
+    /**
+     * Process a single boundary column: find the Y range of cells with the
+     * deferred marker, then run tryMove on them bottom-to-top (matching the
+     * main movement pass order). Only deferred cells are processed — tryMove
+     * early-returns for cells without the marker when boundaryPass is true.
+     */
+    processBoundaryColumn(bw, grid, deferred, col, W, H) {
+        let minY = H, maxY = 0;
+        let hasDeferred = false;
+        for (let y = 0; y < H; y++) {
+            const idx = y * W + col;
+            if (grid[idx] !== 0 && deferred[idx] !== 0) {
+                if (y < minY)
+                    minY = y;
+                if (y > maxY)
+                    maxY = y;
+                hasDeferred = true;
+            }
+        }
+        if (!hasDeferred)
+            return;
+        // Process bottom-to-top (same as the main movement pass). tryMove
+        // early-returns for non-deferred cells when boundaryPass is true, so
+        // iterating the full [minY, maxY] range is cheap.
+        bw.runBoundaryMovement([col], minY, maxY, true);
+    }
+    /** Get the shared grid (for the chunk-world to read/write directly). */
+    getGrid() {
+        return this.boundaryWorld.grid;
+    }
+    /** Get the boundary world (the coordinator's SandWorld — shared SAB grid). */
+    getBoundaryWorld() {
+        return this.boundaryWorld;
+    }
+    /** Get the shared fields array. */
+    getFields() {
+        return this.boundaryWorld.fields;
+    }
+    /** Get the SAB backing the grid + fields. */
+    getSAB() {
+        return this.sab;
+    }
+    /** Shut down all workers. */
+    shutdown() {
+        this.workers.forEach((worker) => {
+            worker.postMessage({ type: "shutdown" });
+            worker.terminate();
+        });
+        this.workers = [];
+        this.initialized = false;
+        // Clear any in-flight init promise so a subsequent init() can rebuild
+        // workers from scratch after shutdown.
+        this.initPromise = null;
+    }
+}

package/dist/libraries/sand/src/sand-step-worker.js

@@ -0,0 +1,101 @@
+// ============================================================================
+// Sand step worker — processes one vertical strip of the sand grid per step.
+//
+// Spawned by SandStepPool (which runs inside the mining worker). Each sand-step
+// worker shares the grid + fields via a SharedArrayBuffer and only writes to
+// its assigned strip [stripStartX, stripEndX). Cross-strip writes are skipped
+// by write guards in SandWorld; the coordinator's boundary cleanup pass
+// handles them after all workers finish.
+//
+// Communication:
+//   - init: { sab, gridOffset, fieldsOffset, W, H, stripStartX, stripEndX, frame }
+//   - step: { frame } → processes one SandWorld.step() for this strip
+//   - The worker responds with { done: true } when the step is complete.
+//   - Atomics.wait/postMessage handshake for low-latency dispatch.
+// ============================================================================
+import { MAT_GRAVITY, MAT_GRAVITY_DIR, SandWorld } from "./sand-world.js";
+// --- Gravity overrides for static materials ---
+// Games can pass `gravityOverrides` in the init message to patch the gravity
+// lookup tables for materials that are static by default (gravityDir=0) but
+// need to fall in the game's context (e.g. Sandjongg's Ice/Plant/Fireflies).
+// This runs in the sand-step worker thread, which has its own module instance
+// separate from the game worker.
+let gravityOverrides = null;
+function applyGravityOverrides() {
+    if (!gravityOverrides)
+        return;
+    gravityOverrides.forEach((o) => {
+        MAT_GRAVITY_DIR[o.mat] = o.gravityDir;
+        if (o.gravity !== 0)
+            MAT_GRAVITY[o.mat] = o.gravity;
+    });
+}
+let world = null;
+let stripStartX = 0;
+let stripEndX = 0;
+self.onmessage = (e) => {
+    const msg = e.data;
+    switch (msg.type) {
+        case "init": {
+            // Apply gravity overrides before creating the SandWorld so the patched
+            // tables are used from the first step.
+            if (msg.gravityOverrides) {
+                gravityOverrides = msg.gravityOverrides;
+                applyGravityOverrides();
+            }
+            world = new SandWorld(msg.W, msg.H, {
+                sab: msg.sab,
+                gridOffset: msg.gridOffset,
+                fieldsOffset: msg.fieldsOffset,
+                skipMaskOffset: msg.skipMaskOffset,
+                deferredMaskOffset: msg.deferredMaskOffset,
+                histogramOffset: msg.histogramOffset,
+                skipStoneFloor: true,
+            });
+            stripStartX = msg.stripStartX;
+            stripEndX = msg.stripEndX;
+            world.setStripBounds(stripStartX, stripEndX);
+            // Copy preserveFlagsMask + disturbedFlags from the coordinator (game-specific).
+            if (msg.preserveFlagsMask !== undefined)
+                world.preserveFlagsMask = msg.preserveFlagsMask;
+            if (msg.disturbedFlags !== undefined)
+                world.disturbedFlags = msg.disturbedFlags;
+            self.postMessage({ type: "ready" });
+            break;
+        }
+        case "step": {
+            if (!world)
+                return;
+            // Sync strip bounds (in case the coordinator rebalanced strips).
+            if (msg.stripStartX !== undefined && msg.stripEndX !== undefined) {
+                stripStartX = msg.stripStartX;
+                stripEndX = msg.stripEndX;
+                world.setStripBounds(stripStartX, stripEndX);
+            }
+            // Sync per-step config from coordinator.
+            if (msg.interlaceEnabled !== undefined)
+                world.interlaceEnabled = msg.interlaceEnabled;
+            if (msg.interlaceScale !== undefined)
+                world.interlaceScale = msg.interlaceScale;
+            if (msg.horizontalImpulseChance !== undefined)
+                world.horizontalImpulseChance = msg.horizontalImpulseChance;
+            if (msg.horizontalImpulseStrength !== undefined)
+                world.horizontalImpulseStrength = msg.horizontalImpulseStrength;
+            // Set the frame number so interlace + fuse burn + C4 visited arrays work.
+            world.frame = msg.frame;
+            world.step();
+            self.postMessage({ type: "done", activeCount: world.getActiveCount() });
+            break;
+        }
+        case "setSkipMask": {
+            // The skip mask is shared via SAB — the coordinator sets it directly.
+            // This message is a no-op placeholder for future per-worker skip masks.
+            break;
+        }
+        case "shutdown": {
+            world = null;
+            self.close();
+            break;
+        }
+    }
+};