@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/worker/sim-worker-base.js

@@ -0,0 +1,558 @@
+// ============================================================================
+// createSimWorker — helper for game sim worker entries.
+//
+// Handles the standard sim worker API: init, pause, resume, shutdown, setSpeed,
+// step, getStats, resize. Games provide only onInit, onTick, and optional
+// onResize/onAfterTicks/onShutdown.
+//
+// This enforces the standard API shape — consumers can't deviate. The helper
+// handles:
+//   - Tick loop with fixed-step accumulator + speed multiplier
+//   - FPS tracking (per-second frame counter)
+//   - frameCount + tickCount
+//   - stepOnce (single-step mode: step once then pause)
+//   - startPaused option (for workers that need to wait for save data before simulating)
+//   - getStats() returning { fps, tick, frame }
+//   - expose() wiring with the standard API
+//   - "ready" event emission after onInit
+//   - Error recovery (logs error, retries after 100ms)
+//   - SAB polyfill buffer sync (when SharedArrayBuffer is unavailable, e.g.
+//     polyfilled — see sab-polyfill.ts + buffer-sync.ts)
+//
+// Usage in a game worker entry:
+//   createSimWorker({
+//     fixedDt: 1/30,
+//     onInit(sab, gridW, gridH) { ... },
+//     onTick(dt, ctx) { ... },
+//     onAfterTicks(ctx) { ... },  // once-per-frame writes (e.g. SAB upload)
+//     onResize(gridW, gridH) { ... },
+//     startPaused: true,          // start paused (e.g. wait for save data)
+//     onSyncConfig(sab) { ... },  // buffer sync regions (SAB polyfill)
+//     extraApi: { clear: () => { ... }, loadGrid: (...) => { ... } },
+//   });
+// ============================================================================
+// Import the SAB polyfill FIRST — it must execute before any code that
+// references SharedArrayBuffer. On hosts with real SABs this is a no-op.
+import { flushProfilingTick, getWarningEngine, METRIC_TICK_LATENCY, recordTaskLatency } from "../profiling/worker-prelude.js";
+import "../sab/sab-polyfill.js";
+import { usingRealSAB } from "../sab/sab-polyfill.js";
+import { mulberry32 } from "../math/rng.js";
+import { createLogger } from "../util/logger.js";
+import { expose, exposeEvents } from "./rpc.js";
+const log = createLogger();
+/**
+ * Detect deterministic/test mode inside a worker. `DOWNDRAFT_DETERMINISTIC`
+ * reaches workers via `globalThis.__DOWNDRAFT_DETERMINISTIC__` (set by the
+ * host before worker creation) or `process.env` (Bun/Node workers).
+ */
+function detectDeterministic() {
+    const g = globalThis;
+    if (g.__DOWNDRAFT_DETERMINISTIC__)
+        return true;
+    try {
+        return g.process?.env
+            ?.DOWNDRAFT_DETERMINISTIC === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Replace `Math.random` with a seeded-RNG-backed function that warns once per
+ * callsite. In deterministic mode this makes stray `Math.random()` calls in
+ * sim code deterministic (they draw from the same stream as `ctx.rng`) while
+ * surfacing migration targets. Only installed when deterministic mode is on.
+ */
+function installDeterministicMathGuard(rng) {
+    const warned = new Set();
+    const original = Math.random;
+    Math.random = () => {
+        const stack = new Error().stack ?? "";
+        if (!warned.has(stack)) {
+            warned.add(stack);
+            const line = stack.split("\n")[1]?.trim() ?? "unknown callsite";
+            log.warn("create-sim-worker", `Math.random() called in deterministic sim — use ctx.rng (from ${line})`);
+        }
+        return rng();
+    };
+    // Restore path for tests / unusual host reuse.
+    Math.random.__downdraftRestore = () => {
+        Math.random = original;
+    };
+}
+/**
+ * Creates and starts a sim worker with the standard API.
+ * Call this at the top level of a game's worker entry file.
+ *
+ * The exposed API is:
+ *   init(sab, ...args) — calls onInit, starts the loop, emits "ready"
+ *   resize(...args) — calls onResize
+ *   pause() — pauses the loop
+ *   resume() — resumes the loop (resets accumulator to prevent catch-up spike)
+ *   shutdown() — stops the loop, calls onShutdown
+ *   setSpeed(speed) — sets the speed multiplier (0 = paused)
+ *   step() — single-steps (runs 1 tick then pauses)
+ *   getStats() — returns { fps, tick, frame }
+ *   save/load/initSaveStore/restoreFromState — when opts.save is provided
+ *   sendCommand(cmd) — when opts.onCommand is provided
+ *   ...extraApi — any additional methods
+ */
+export function createSimWorker(opts) {
+    const tickMs = opts.fixedDt * 1000;
+    const maxStepsPerFrame = opts.maxStepsPerFrame ?? 5;
+    let running = false;
+    let loopActive = false;
+    let paused = false;
+    let stepOnce = false;
+    let speedMultiplier = 1;
+    let lastTick = 0;
+    let tickAccumulator = 0;
+    let tickCount = 0;
+    let tickTimeAccum = 0;
+    let frameCount = 0;
+    let fpsTimer = 0;
+    let fps = 0;
+    // SAB polyfill: buffer sync worker (only created when SAB is unavailable).
+    let syncWorker = null;
+    // SAB polyfill: throttled sync counter. When onSyncFastRegions is provided,
+    // fast regions are synced every tick batch, and ALL regions (including slow
+    // ones) are synced every onSyncSlowInterval tick batches.
+    let syncSlowCounter = 0;
+    const syncSlowInterval = opts.onSyncSlowInterval ?? 10;
+    // Inline save store (created by initSaveStore() via opts.save.createStore).
+    let saveStore = null;
+    // Optional GC controller — offered post-tick headroom each frame.
+    let gcController = null;
+    /**
+     * Extract the restore payload from a serialized state. Handles all three
+     * wire forms: raw data, a components map (`{ name: { v, data } }`), and a
+     * full SaveState (`{ components: { name: { v, data } } }`). When
+     * componentName is omitted the components map / raw payload is returned
+     * as-is for multi-component games.
+     */
+    const extractRestoreData = (parsed) => {
+        const name = opts.save.componentName;
+        if (!name)
+            return parsed?.components ?? parsed;
+        return (parsed?.components?.[name]?.data ??
+            (parsed?.[name]?.data !== undefined ? parsed[name].data : parsed));
+    };
+    const syncFastRegions = opts.onSyncFastRegions;
+    // setTimeout truncates fractional milliseconds (e.g. 32.333 → 32), losing
+    // ~frac(tickMs) ms per iteration. For tickMs = 33.333 (30Hz), that's 0.333ms
+    // per iteration — after ~100 iterations (~3.3s) the deficit reaches one full
+    // tick, causing the accumulator to burst a 2-tick frame. This produces a
+    // slow, periodic oscillation in the effective tick rate (and thus in
+    // everything driven by dt: movement speed, drop spin, animation timing).
+    // We accumulate the sub-ms remainder and add it back when it exceeds 1ms,
+    // so the average setTimeout delay matches the desired interval exactly.
+    let timerRemainder = 0;
+    // The single armed loop timer — loop() schedules through scheduleLoop so
+    // withLoopStopped/stop/shutdown can disarm it. Without this, stopping the
+    // loop left a pending setTimeout that fired after the stop and spawned a
+    // second parallel loop chain.
+    let loopTimer = null;
+    // Promise for the in-flight onTick() call — the real barrier
+    // withLoopStopped waits on (the old code polled a flag for ~50ms then
+    // proceeded anyway, letting a suspended tick race the critical section).
+    let tickInFlight = null;
+    // Serializes withLoopStopped critical sections.
+    let stopChain = Promise.resolve();
+    const events = exposeEvents();
+    // Deterministic RNG — reseedable via control.setSeed(); the stable `rng`
+    // closure is what ctx.rng and the Math.random shim draw from.
+    let rngImpl = mulberry32(opts.seed ?? 0x9e3779b9);
+    const rng = () => rngImpl();
+    const deterministic = opts.deterministic ?? detectDeterministic();
+    if (deterministic) {
+        installDeterministicMathGuard(rng);
+    }
+    const control = {
+        pause: () => { paused = true; },
+        setSeed: (seed) => { rngImpl = mulberry32(seed); },
+        resume: () => {
+            paused = false;
+            lastTick = performance.now();
+            tickAccumulator = 0;
+        },
+        async withLoopStopped(fn) {
+            // Serialize concurrent callers — a second caller queues behind the
+            // first's stop → critical section → restart cycle.
+            const run = stopChain.then(async () => {
+                // Stop the loop from scheduling another iteration AND disarm the
+                // pending one — an armed setTimeout that fires while loopActive was
+                // already restored used to spawn a second parallel loop chain.
+                loopActive = false;
+                clearLoopTimer();
+                // Hard barrier: if onTick is mid-flight, wait for it to actually
+                // return. Its continuation observes loopActive === false and exits
+                // before touching the accumulator or rescheduling. No timeout —
+                // running fn() while a tick still mutates state is exactly the
+                // race this exists to prevent.
+                if (tickInFlight)
+                    await tickInFlight.catch(() => { });
+                try {
+                    return await fn();
+                }
+                finally {
+                    // Restart the loop — unless shutdown landed while we held the
+                    // barrier (running === false is the permanent stop signal).
+                    if (running) {
+                        loopActive = true;
+                        lastTick = performance.now();
+                        tickAccumulator = 0;
+                        void loop();
+                    }
+                }
+            });
+            // Keep the chain alive across failures in fn().
+            stopChain = run.then(() => undefined, () => undefined);
+            return run;
+        },
+        getSpeed: () => speedMultiplier,
+        setSpeed: (speed) => {
+            speedMultiplier = Math.min(opts.maxSpeed ?? Infinity, Math.max(opts.minSpeed ?? 0, speed));
+        },
+        getTickTimeAccum: () => tickTimeAccum,
+        resetTickTimeAccum: () => { tickTimeAccum = 0; },
+        getTickCount: () => tickCount,
+        setGCController: (ctrl) => { gcController = ctrl; },
+        stop: () => { running = false; loopActive = false; clearLoopTimer(); },
+        events,
+    };
+    /** Arm the next loop iteration — the ONLY place a loop timer is created. */
+    function scheduleLoop(delay) {
+        if (!loopActive)
+            return;
+        if (loopTimer !== null)
+            clearTimeout(loopTimer); // never stack timers
+        loopTimer = setTimeout(() => {
+            loopTimer = null;
+            void loop();
+        }, delay);
+    }
+    function clearLoopTimer() {
+        if (loopTimer !== null) {
+            clearTimeout(loopTimer);
+            loopTimer = null;
+        }
+    }
+    async function loop() {
+        if (!running || !loopActive)
+            return;
+        try {
+            const now = performance.now();
+            const elapsed = now - lastTick;
+            if (elapsed >= tickMs) {
+                lastTick = now - (elapsed % tickMs);
+                if (!paused || stepOnce) {
+                    // Only accumulate sim time when actually stepping. While paused,
+                    // lastTick still advances (above) so we don't get a huge elapsed
+                    // spike on resume, but we must NOT let tickAccumulator build up.
+                    //
+                    // Credit only WHOLE tick periods: the fractional remainder stays
+                    // owed in lastTick's phase (the snap above) and is re-measured as
+                    // part of the next elapsed. Crediting elapsed/tickMs fractionally
+                    // here AND keeping the remainder in lastTick counts it twice —
+                    // every late-timer remainder leaks ~its size in extra sim time,
+                    // so the sim ran measurably fast under timer jitter.
+                    tickAccumulator += Math.floor(elapsed / tickMs) * speedMultiplier;
+                    let steps = 0;
+                    const maxSteps = stepOnce ? 1 : maxStepsPerFrame;
+                    while (tickAccumulator >= 1 && steps < maxSteps) {
+                        tickCount++;
+                        const tickStart = performance.now();
+                        const tick = Promise.resolve(opts.onTick(opts.fixedDt, { tickCount, frameCount, fps, rng }));
+                        tickInFlight = tick;
+                        try {
+                            await tick;
+                        }
+                        finally {
+                            tickInFlight = null;
+                        }
+                        const tickDurationUs = (performance.now() - tickStart) * 1000;
+                        tickTimeAccum += tickDurationUs / 1000;
+                        // Record task latency for the flame graph + histogram
+                        recordTaskLatency("js", tickDurationUs, "tick");
+                        // Fire instantaneous tick-latency warning (if configured)
+                        getWarningEngine()?.checkInstant(METRIC_TICK_LATENCY, tickDurationUs);
+                        if (!loopActive)
+                            return; // resize/withLoopStopped interrupted
+                        tickAccumulator -= 1;
+                        steps++;
+                    }
+                    // Clamp accumulator if we hit the step cap (death spiral prevention)
+                    if (tickAccumulator > maxStepsPerFrame) {
+                        tickAccumulator = 0;
+                    }
+                    if (stepOnce) {
+                        stepOnce = false;
+                        paused = true;
+                        tickAccumulator = 0;
+                    }
+                    // Once-per-frame callback (after all ticks this frame)
+                    if (steps > 0) {
+                        opts.onAfterTicks?.({
+                            ticksThisFrame: steps,
+                            tickCount,
+                            frameCount,
+                            fps,
+                        });
+                        // SAB polyfill: sync written regions to the main thread after
+                        // each tick batch. No-op when real SAB is available (desktop).
+                        // When onSyncFastRegions is provided, use throttled sync:
+                        //   - Every tick batch: sync only fast regions (header, entities)
+                        //   - Every N tick batches: sync ALL regions (including grids)
+                        if (syncWorker) {
+                            if (syncFastRegions) {
+                                syncWorker.syncToMain(syncFastRegions);
+                                syncSlowCounter++;
+                                if (syncSlowCounter >= syncSlowInterval) {
+                                    syncWorker.syncToMain();
+                                    syncSlowCounter = 0;
+                                }
+                            }
+                            else {
+                                syncWorker.syncToMain();
+                            }
+                        }
+                        // Flush profiling data (ThreadMetrics + EventLoop + instant warnings)
+                        flushProfilingTick();
+                    }
+                }
+                // Offer post-tick headroom to the GC controller for proactive
+                // collection (same contract as SimWorkerLoop).
+                if (gcController) {
+                    const headroom = tickMs - (performance.now() - now);
+                    if (headroom > 0) {
+                        gcController.maybeCollect(headroom, tickMs);
+                    }
+                }
+            }
+            frameCount++;
+            fpsTimer += elapsed;
+            if (fpsTimer >= 1000) {
+                fps = Math.round((frameCount * 1000) / fpsTimer);
+                frameCount = 0;
+                fpsTimer = 0;
+            }
+            // Sleep until the next tick is due instead of spinning with setTimeout(0).
+            // The deadline is phase-aligned: lastTick holds the fractional
+            // `elapsed % tickMs` remainder from the snap above, so the next tick is
+            // due at lastTick + tickMs — NOT a fresh tickMs from now. Sleeping a
+            // whole tickMs per iteration discards that remainder: whenever the
+            // remainder + timer jitter was smaller than this iteration's work, the
+            // loop woke before the deadline, did nothing, and slept another full
+            // tickMs — producing alternating normal/doubled tick intervals.
+            // If the accumulator still holds owed ticks (step cap was hit), they're
+            // spent on the next due iteration — the backlog is clamped to
+            // maxStepsPerFrame so a deadline wait is never more than ~tickMs.
+            const remaining = lastTick + tickMs - performance.now();
+            // Compensate for setTimeout's integer truncation: accumulate the sub-ms
+            // fractional part and add 1ms when it exceeds 1ms, so the average delay
+            // matches the desired interval exactly. Without this, a fractional tickMs
+            // (e.g. 33.333 for 30Hz) loses ~0.333ms per iteration to truncation,
+            // causing a ~3.3s periodic oscillation in the effective tick rate.
+            const intRemaining = Math.max(0, Math.floor(remaining));
+            timerRemainder += remaining - intRemaining;
+            let delay = intRemaining;
+            if (timerRemainder >= 1) {
+                delay += 1;
+                timerRemainder -= 1;
+            }
+            scheduleLoop(delay);
+        }
+        catch (e) {
+            const err = e;
+            log.error("create-sim-worker", `Loop error: ${err.message}\n${err.stack}`);
+            opts.onError?.(err);
+            scheduleLoop(100);
+        }
+    }
+    const standardApi = {
+        async init(sab, ...args) {
+            await opts.onInit(sab, control, ...args);
+            // SAB polyfill: set up buffer sync if SAB is unavailable and the game
+            // provided a sync config. The BufferSyncWorker posts written regions
+            // to the main thread after each tick batch (see syncToMain() above).
+            if (!usingRealSAB && opts.onSyncConfig) {
+                const { BufferSyncWorker: BSW } = await import("./buffer-sync.js");
+                syncWorker = new BSW(opts.onSyncConfig(sab));
+                syncWorker.start();
+                // Sync initial state (e.g. board data written during onInit) to the
+                // main thread immediately — the sim may be paused at startup and
+                // syncToMain() won't be called until the first tick batch.
+                syncWorker.syncToMain();
+            }
+            running = true;
+            loopActive = true;
+            paused = opts.startPaused ?? false;
+            stepOnce = false;
+            speedMultiplier = 1;
+            lastTick = performance.now();
+            tickAccumulator = 0;
+            tickCount = 0;
+            frameCount = 0;
+            fpsTimer = 0;
+            fps = 0;
+            timerRemainder = 0;
+            clearLoopTimer();
+            events.emit("ready", {});
+            void loop();
+        },
+        async resize(...args) {
+            if (!opts.onResize)
+                return;
+            // Use withLoopStopped to safely pause the loop during resize.
+            // This prevents races between onTick() and onResize() when both
+            // access shared resources (e.g. SandStepPool).
+            await control.withLoopStopped(() => opts.onResize(...args));
+        },
+        async pause() {
+            paused = true;
+        },
+        async resume() {
+            paused = false;
+            lastTick = performance.now();
+            tickAccumulator = 0; // prevent catch-up spike after resume
+        },
+        async shutdown() {
+            running = false;
+            loopActive = false;
+            clearLoopTimer();
+            syncWorker = null; // release sync worker reference
+            saveStore = null;
+            await opts.onShutdown?.();
+        },
+        async setSpeed(speed) {
+            speedMultiplier = Math.min(opts.maxSpeed ?? Infinity, Math.max(opts.minSpeed ?? 0, speed));
+        },
+        async step() {
+            stepOnce = true;
+            paused = false;
+            lastTick = performance.now();
+            tickAccumulator = 0;
+        },
+        getStats() {
+            return { fps, tick: tickCount, frame: frameCount, tickMs: tickTimeAccum };
+        },
+        ...(opts.save?.capture
+            ? {
+                async save(slotName, saveOpts) {
+                    const data = await opts.save.capture();
+                    const capturedBlobs = await opts.save.captureBlobs?.();
+                    // Always wrap in SaveState.components format so every backend
+                    // stores the state in the expected component format —
+                    // FileSaveStore.load() expects each component to have a
+                    // { v, data } structure.
+                    const name = opts.save.componentName;
+                    const components = name
+                        ? { [name]: { v: opts.save.version ?? 1, data } }
+                        : data;
+                    const metaExtra = opts.save.meta?.(data, saveOpts);
+                    const saveStateObj = {
+                        components,
+                        meta: {
+                            engineVersion: "0.0.0",
+                            timestamp: Date.now() / 1000,
+                            entityCount: 0,
+                            playerCount: 0,
+                            ...metaExtra,
+                        },
+                    };
+                    const stateJson = JSON.stringify(saveStateObj.components);
+                    let gen;
+                    let success = true;
+                    if (saveStore) {
+                        const result = await saveStore.save(slotName, saveStateObj, {
+                            ...saveOpts,
+                            blobs: capturedBlobs ?? saveOpts?.blobs,
+                        });
+                        success = result.success;
+                        gen = result.gen;
+                    }
+                    events.emit("saved", { slotName, stateJson, success, gen, meta: saveStateObj.meta, origin: "renderer" });
+                    return { slotName, stateJson, success, gen, meta: saveStateObj.meta };
+                },
+                /**
+                 * Raw capture payload — no store interaction. Lets a
+                 * renderer-owned save system (createGameSaveSystem) pull the
+                 * worker's state and embed it in its own SaveState. Binary
+                 * payloads (typed arrays) come back in `blobs`, transferred via
+                 * structured clone.
+                 */
+                async captureState() {
+                    const data = await opts.save.capture();
+                    const blobs = await opts.save.captureBlobs?.();
+                    return { stateJson: JSON.stringify(data), blobs };
+                },
+            }
+            : {}),
+        ...(opts.save?.restore
+            ? {
+                async load(slotName, stateJson, loadOpts) {
+                    let json = stateJson;
+                    let blobs;
+                    let gen;
+                    if (!json && saveStore) {
+                        const result = await saveStore.load(slotName, loadOpts);
+                        const payload = opts.save.componentName
+                            ? result.state?.components?.[opts.save.componentName]?.data
+                            : result.state?.components;
+                        if (payload !== undefined && payload !== null) {
+                            json = JSON.stringify(payload);
+                            blobs = result.blobs;
+                            gen = result.gen;
+                        }
+                    }
+                    if (!json) {
+                        events.emit("loaded", { slotName, success: false });
+                        return false;
+                    }
+                    let data = json;
+                    try {
+                        data = extractRestoreData(JSON.parse(json));
+                    }
+                    catch {
+                        // not JSON — pass through as-is
+                    }
+                    // Stop the loop during restore — mutating sim state while a tick
+                    // is in flight is a data race.
+                    await control.withLoopStopped(() => opts.save.restore(data, blobs));
+                    events.emit("loaded", { slotName, success: true, gen });
+                    return true;
+                },
+                async restoreFromState(stateJson, blobs) {
+                    let data = stateJson;
+                    try {
+                        data = extractRestoreData(JSON.parse(stateJson));
+                    }
+                    catch {
+                        // not JSON — pass through as-is
+                    }
+                    await control.withLoopStopped(() => opts.save.restore(data, blobs));
+                },
+            }
+            : {}),
+        ...(opts.save?.createStore
+            ? {
+                async initSaveStore(storeOpts) {
+                    saveStore = opts.save.createStore(storeOpts);
+                    await saveStore.init?.();
+                },
+            }
+            : {}),
+        ...(opts.onCommand
+            ? {
+                async sendCommand(cmd) {
+                    await opts.onCommand(cmd);
+                },
+            }
+            : {}),
+    };
+    const api = { ...standardApi, ...opts.extraApi };
+    // Optionally wrap the API before exposing (e.g. with exposeDevToolsApi
+    // to add devtools + profiling RPC methods).
+    expose(opts.wrapExpose ? opts.wrapExpose(api) : api);
+    return control;
+}