@downdraft/engine 0.2.0 → 0.3.0

package/dist/core/src/index.js

@@ -45,7 +45,7 @@ export { createMultiInputChannel, DEFAULT_KEY_BITFIELD_COUNT, DEFAULT_MAX_PLAYER
 // Game Input SAB Channel
 export { INP, INP_FLAG, INP_HDR, INPUT_MAGIC, INPUT_VERSION, InputBufferReader, InputBufferWriter, InputChannel, KEY, MAX_INPUT_PLAYERS } from "./sab/game-input.js";
 // Sim SAB Channel
-export { allocateInputBuffer, allocateSimBuffer, ENT, MAX_ENTITIES, MAX_PLAYERS, PLR, PLR_FLAG, SIM_ENTITY_SLOT_SIZE, SIM_HDR, SIM_MAGIC, SIM_PLAYER_SLOT_SIZE, SIM_VERSION, SimBufferReader, SimBufferWriter, SimChannel } from "./sab/sim-channel.js";
+export { allocateInputBuffer, allocateSimBuffer, ENT, MAX_ENTITIES, MAX_PLAYERS, PLR, PLR_FLAG, PREV, SIM_ENTITY_SLOT_SIZE, SIM_HDR, SIM_MAGIC, SIM_PLAYER_SLOT_SIZE, SIM_VERSION, SimBufferReader, SimBufferWriter, SimChannel } from "./sab/sim-channel.js";
 // SAB Framework
 export { defineChannel, defineManifest } from "./sab/define.js";
 export { isDebug, resetWarnings, ValidationError as SABValidationError, setDebug, warnOnce } from "./sab/errors.js";
@@ -57,7 +57,7 @@ export { BufferSyncHost, BufferSyncWorker, isBufferSyncMessage } from "./worker/
 export { CrashRecoveryManager, DEFAULT_RECOVERY_CONFIG } from "./worker/crash-recovery.js";
 export { EntitySimWorkerHost } from "./worker/entity-sim-worker-host.js";
 export { exposeProfilingApi, InstrumentedWorkerHost } from "./worker/instrumented-worker-host.js";
-export { expose, exposeEvents, getWorkerHost, wrap } from "./worker/rpc.js";
+export { expose, exposeBatchedEvents, exposeEvents, getWorkerHost, wrap } from "./worker/rpc.js";
 export { createSimWorker } from "./worker/sim-worker-base.js";
 export { RawInputRegionWriter, SimWorkerHost } from "./worker/sim-worker-host.js";
 export { createTaskWorker, PortChannel, TaskPool } from "./worker/task-pool.js";

package/dist/core/src/platform/rpc.js

@@ -1,3 +1,4 @@
+import { untrackedTimeout } from "../util/session-timer.js";
 export class RPC {
     handlers = new Map();
     pending = new Map();
@@ -20,7 +21,7 @@ export class RPC {
         }
         const id = this.messageIdCounter = (this.messageIdCounter + 1) % 0xFFFFFFFF;
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
+            const timer = untrackedTimeout(() => {
                 if (this.pending.has(id)) {
                     this.pending.delete(id);
                     reject(new Error(`[RPC] Call to "${channel}" timed out after ${timeoutMs}ms`));

package/dist/core/src/render/game-renderer.js

@@ -42,6 +42,9 @@ export class GameRenderer {
     uiInputRouter = null;
     /** Screen-space compositors (html-ui panels etc.) drawn in the UI pass. */
     uiCompositors = new Set();
+    /** uiCompositors as a pre-sorted array — rebuilt on add/remove so the
+     *  frame loop doesn't spread+sort the set every frame. */
+    uiCompositorOrder = [];
     // Render loop state
     running = false;
     deviceLost = false;
@@ -75,11 +78,22 @@ export class GameRenderer {
     frameCtx = null;
     // Depth texture cache (used when the graph does not own depth)
     // LRU: Map insertion order = access order (delete + re-set on access).
+    // Numeric key packs (w,h) — a `${w}x${h}` string key allocated a fresh
+    // string per lookup per viewport per frame.
     depthTextures = new Map();
     depthTextureCacheSize;
     // Frame stats
     frameDrawCalls = 0;
     frameTriangles = 0;
+    // Per-frame submit interception: while non-null, queue.submit() calls
+    // (game callbacks, render-target providers, helpers) append their buffers
+    // here in call order instead of crossing into wgpu — the whole frame then
+    // lands in ONE queue.submit at end-of-frame. Games legitimately submit
+    // inside afterFrame callbacks (2D renderers, overlays), so folding the UI
+    // composite into the main batch requires capturing those submits rather
+    // than submitting early or reordering.
+    frameSubmitSink = null;
+    submitInterceptorDevice = null;
     // Callbacks
     callbacks = {};
     // Offscreen mode (set by game for postprocessing)
@@ -150,6 +164,7 @@ export class GameRenderer {
                 return false;
             }
             this.device = borrowedDevice ?? await this.requestDeviceFromAdapter(adapter);
+            this.installQueueSubmitInterceptor(this.device);
             this.adapter = adapter;
             // The host configured the surface with its own usage set at creation —
             // reconfiguring here would tear down the swapchain and race the host's
@@ -214,8 +229,16 @@ export class GameRenderer {
                 setViewportCount: (count) => this.setViewportCount(count),
                 getUIInputRouter: () => this.uiInputRouter,
                 registerUiCompositor: (c) => {
+                    const isNew = !this.uiCompositors.has(c);
                     this.uiCompositors.add(c);
-                    return () => this.uiCompositors.delete(c);
+                    if (isNew) {
+                        this.uiCompositorOrder = [...this.uiCompositors].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+                    }
+                    return () => {
+                        if (this.uiCompositors.delete(c)) {
+                            this.uiCompositorOrder = [...this.uiCompositors].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+                        }
+                    };
                 },
             });
             // Initial viewport layout
@@ -328,6 +351,7 @@ export class GameRenderer {
             const device = await this.requestDeviceFromAdapter(adapter);
             device.lost.then((info) => this.handleDeviceLost(info));
             this.device = device;
+            this.installQueueSubmitInterceptor(device);
             this.adapter = adapter;
             installShaderValidationGuard(device);
             this.gpuResourceTracker = new GPUResourceTracker();
@@ -563,14 +587,40 @@ export class GameRenderer {
         }
         catch (err) {
             log.error("game-renderer", `Render loop error: ${err.message}\n${err.stack}`);
-            if (this.device?.lost) {
-                this.device.lost.then((info) => {
-                    this.handleDeviceLost(info);
-                });
-            }
+            // No per-error device.lost.then here: the device already has exactly
+            // one lost subscription (init + reinit paths), and on native each
+            // .lost access mints a fresh promise — per-error attaches accumulated
+            // duplicate watchers during an error storm.
         }
         this.scheduleRender();
     };
+    /**
+     * Redirect queue.submit() into frameSubmitSink while a frame is in
+     * flight. Submission order is preserved — buffers land in the sink in
+     * the order submit() was called — so mid-frame submits (uploads in
+     * beforeFrame, a game's afterFrame pass, endFrame hooks) still execute
+     * ahead of work recorded later, just inside the single end-of-frame
+     * queue.submit rather than as extra queue-lock + driver calls.
+     */
+    installQueueSubmitInterceptor(device) {
+        if (this.submitInterceptorDevice === device)
+            return;
+        this.submitInterceptorDevice = device;
+        const queue = device.queue;
+        if (queue.__ddSubmitIntercepted)
+            return;
+        queue.__ddSubmitIntercepted = true;
+        const origSubmit = queue.submit.bind(queue);
+        queue.submit = (commandBuffers) => {
+            const sink = this.frameSubmitSink;
+            if (!sink) {
+                origSubmit(commandBuffers);
+                return;
+            }
+            for (const cb of commandBuffers)
+                sink.push(cb);
+        };
+    }
     renderFrame() {
         const now = performance.now();
         // Frame rate limiter: phase accumulator (skip during XR — XR drives its own cadence)
@@ -615,6 +665,14 @@ export class GameRenderer {
         // simulation stays responsive. The flag is cleared by recovery code that
         // recreates the invalid resources.
         const gpuError = this.gpuProfiler?.hasUncapturedError() ?? false;
+        // Collect command buffers from all phases and submit once at the end
+        // of the frame — one queue.submit per frame instead of 2-4. The sink
+        // is armed BEFORE beginFrame so submit() calls from hooks and game
+        // callbacks (beforeFrame uploads, afterFrame render passes, the XR
+        // endFrame encoder) are captured in call order into the same batch
+        // rather than crossing into wgpu individually.
+        const frameCommandBuffers = [];
+        this.frameSubmitSink = frameCommandBuffers;
         // XR render target provider beginFrame hook
         if (this.renderTargetProvider && !gpuError) {
             this.renderTargetProvider.beginFrame();
@@ -625,9 +683,6 @@ export class GameRenderer {
         if (offscreen && useOffscreen && offscreen.ensureTargets && !gpuError) {
             offscreen.ensureTargets(this.canvas.width, this.canvas.height);
         }
-        // Collect command buffers from all phases and submit once at the end
-        // (reduces CPU→GPU sync points from 3+ per frame to 1).
-        const frameCommandBuffers = [];
         if (!gpuError) {
             // 2D mode with viewportCount=0: clear the canvas if a clearColor is
             // configured, then let the afterFrame callback do custom rendering.
@@ -674,19 +729,6 @@ export class GameRenderer {
         if (passMailbox) {
             frameCommandBuffers.push(...passMailbox.drain("preSubmit"));
         }
-        // Submit all command buffers for this frame in a single queue.submit() call
-        if (frameCommandBuffers.length > 0) {
-            this.device.queue.submit(frameCommandBuffers);
-        }
-        // Read GPU timer results asynchronously (1-frame latency).
-        // Must be called AFTER queue.submit() — readGpuTimers() calls mapAsync on
-        // the read buffer, and a mapped/mapping-pending buffer cannot be used in a
-        // submitted command buffer (the copy-to-readBuffer was encoded above).
-        if (this.gpuProfiler) {
-            this.gpuProfiler.readGpuTimers().then(() => {
-                // Results available for next frame
-            }).catch(() => { });
-        }
         // Record telemetry
         if (this.telemetryCollector) {
             this.telemetryCollector.recordFrame(dt * 1000);
@@ -721,42 +763,68 @@ export class GameRenderer {
             this.frameDrawCalls = 0;
             this.frameTriangles = 0;
         }
-        // XR render target provider endFrame hook (skip on GPU error)
-        if (!gpuError && this.renderTargetProvider && this.device) {
-            this.renderTargetProvider.endFrame(this.device.createCommandEncoder());
+        try {
+            // XR render target provider endFrame hook (skip on GPU error). Its
+            // submits are captured by frameSubmitSink and join the batch.
+            if (!gpuError && this.renderTargetProvider && this.device) {
+                this.renderTargetProvider.endFrame(this.device.createCommandEncoder());
+            }
+            // After frame callback — game submits here append to the batch in
+            // order, still ahead of the UI composite below.
+            this.callbacks.afterFrame?.(dt, this.elapsedTime);
+            this.rendererModuleHost?.dispatchFrame("afterFrame", dt, this.elapsedTime);
+            // Composite registered screen-space UI (html-ui panels) on top of the
+            // final image (skip on GPU error to avoid cascade). This must run AFTER
+            // afterFrame — 2D games (viewportCount=0) do their custom rendering in
+            // the afterFrame callback, so drawing UI earlier would put it underneath
+            // their clear pass.
+            if (!gpuError && this.device && this.context) {
+                const compositors = this.uiCompositorOrder.filter((c) => c.hasContent());
+                const uiCanvasView = compositors.length > 0
+                    ? this.getSurfaceTexture()?.createView()
+                    : undefined;
+                if (uiCanvasView) {
+                    const uiEncoder = this.device.createCommandEncoder();
+                    const uiPass = uiEncoder.beginRenderPass({
+                        colorAttachments: [{
+                                view: uiCanvasView,
+                                clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                                loadOp: "load",
+                                storeOp: "store",
+                            }],
+                    });
+                    compositors.forEach((c) => { c.render(uiPass, this.canvas.width, this.canvas.height); });
+                    uiPass.end();
+                    // "preUi" slot — worker passes ordered ahead of the UI-composite
+                    // buffer inside the end-of-frame submit.
+                    frameCommandBuffers.push(...(passMailbox?.drain("preUi") ?? []), uiEncoder.finish());
+                }
+            }
         }
-        // After frame callback
-        this.callbacks.afterFrame?.(dt, this.elapsedTime);
-        this.rendererModuleHost?.dispatchFrame("afterFrame", dt, this.elapsedTime);
-        // Composite registered screen-space UI (html-ui panels) on top of the
-        // final image (skip on GPU error to avoid cascade). This must run AFTER
-        // afterFrame — 2D games (viewportCount=0) do their custom rendering in
-        // the afterFrame callback, so drawing UI earlier would put it underneath
-        // their clear pass.
-        if (!gpuError && this.device && this.context) {
-            const compositors = [...this.uiCompositors]
-                .filter((c) => c.hasContent())
-                .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
-            const uiCanvasView = compositors.length > 0
-                ? this.getSurfaceTexture()?.createView()
-                : undefined;
-            if (uiCanvasView) {
-                const uiEncoder = this.device.createCommandEncoder();
-                const uiPass = uiEncoder.beginRenderPass({
-                    colorAttachments: [{
-                            view: uiCanvasView,
-                            clearValue: { r: 0, g: 0, b: 0, a: 0 },
-                            loadOp: "load",
-                            storeOp: "store",
-                        }],
-                });
-                compositors.forEach((c) => { c.render(uiPass, this.canvas.width, this.canvas.height); });
-                uiPass.end();
-                // "preUi" slot — worker passes ordered ahead of the UI-composite
-                // submit so their output is visible to the compositor this frame.
-                this.device.queue.submit([...(passMailbox?.drain("preUi") ?? []), uiEncoder.finish()]);
+        finally {
+            // End of frame: disarm the submit sink and flush everything recorded
+            // this frame — engine passes, captured callback submits, mailbox
+            // passes, the UI composite — in a single queue.submit(). Runs even on
+            // a callback throw so already-recorded work still lands.
+            this.frameSubmitSink = null;
+            if (frameCommandBuffers.length > 0 && this.device) {
+                try {
+                    this.device.queue.submit(frameCommandBuffers);
+                }
+                catch (err) {
+                    log.error("game-renderer", `queue.submit failed: ${err.message ?? err}`);
+                }
             }
         }
+        // Read GPU timer results asynchronously (1-frame latency).
+        // Must be called AFTER queue.submit() — readGpuTimers() calls mapAsync on
+        // the read buffer, and a mapped/mapping-pending buffer cannot be used in a
+        // submitted command buffer (the copy-to-readBuffer was encoded above).
+        if (this.gpuProfiler) {
+            this.gpuProfiler.readGpuTimers().then(() => {
+                // Results available for next frame
+            }).catch(() => { });
+        }
         // Present the surface (native wgpu requires explicit presentation;
         // in browsers this is automatic at the end of the frame). Must be last —
         // all submissions targeting the surface texture happen above.
@@ -951,7 +1019,7 @@ export class GameRenderer {
     createDepthTexture(w, h) {
         if (!this.device)
             throw new Error("No device");
-        const key = `${w}x${h}`;
+        const key = w * 65536 + h;
         let tex = this.depthTextures.get(key);
         if (tex) {
             // LRU: move to most-recently-used by re-inserting.
@@ -1030,9 +1098,7 @@ export class GameRenderer {
      * this helper only runs the compositors.
      */
     renderScreenUiCompositors() {
-        const compositors = [...this.uiCompositors]
-            .filter((c) => c.hasContent())
-            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        const compositors = this.uiCompositorOrder.filter((c) => c.hasContent());
         if (compositors.length === 0 || !this.device || !this.context)
             return;
         const canvasView = this.getSurfaceTexture()?.createView();

package/dist/core/src/sab/grid-buffer.js

@@ -46,6 +46,31 @@ export class GridReader {
     hasChanged(lastSeen) {
         return this.getSequence() !== lastSeen;
     }
+    /**
+     * True while the writer holds an open write window (sequence is odd).
+     * Readers can use this to cheaply defer sync work past a publish.
+     */
+    isWriteInProgress() {
+        return (Atomics.load(this.seqArr, 0) & 1) !== 0;
+    }
+    /**
+     * Run `fn` against a consistent snapshot of the channel. The sequence
+     * word is a seqlock: odd while the writer is publishing, even when the
+     * data is stable. The read is retried while the word is odd or changes
+     * mid-read; after maxRetries it returns whatever the last attempt read
+     * rather than starving the reader (writers publish every tick).
+     */
+    readConsistent(fn, maxRetries = 64) {
+        for (let i = 0; i < maxRetries; i++) {
+            const s1 = Atomics.load(this.seqArr, 0);
+            if ((s1 & 1) === 0) {
+                const out = fn();
+                if (Atomics.load(this.seqArr, 0) === s1)
+                    return out;
+            }
+        }
+        return fn();
+    }
     snapshot() {
         const data = {};
         data["sequence"] = this.getSequence();
@@ -67,6 +92,8 @@ export class GridWriter {
     layers;
     seqArr;
     layout;
+    /** True while a beginWrite() window is open (sequence is odd). */
+    writeOpen = false;
     constructor(sab, layout) {
         this.layout = layout;
         this.header = createHeaderViews(sab, layout.header.size);
@@ -82,9 +109,34 @@ export class GridWriter {
         this.header.u32[this.layout.header.magicIndex] = this.layout.magic;
         this.header.u32[this.layout.header.versionIndex] = this.layout.version;
     }
-    bumpSequence() {
+    /**
+     * Open a write window — marks the sequence word odd so readers know a
+     * publish is in progress. Idempotent so mutating paths can call it
+     * unconditionally.
+     */
+    beginWrite() {
+        if (this.writeOpen)
+            return;
+        this.writeOpen = true;
         Atomics.add(this.seqArr, 0, 1);
     }
+    /** Close the write window opened by beginWrite() — sequence back to even. */
+    endWrite() {
+        if (!this.writeOpen)
+            return;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, 1);
+    }
+    /**
+     * Publish a commit. Without an open write window it steps +2 (even→even)
+     * so the sequence always lands on a stable value while still advancing
+     * once per publish; inside a window it closes it (+1, odd→even).
+     */
+    bumpSequence() {
+        const step = this.writeOpen ? 1 : 2;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, step);
+    }
     getSequence() {
         return Atomics.load(this.seqArr, 0);
     }

package/dist/core/src/sab/record-buffer.js

@@ -47,6 +47,31 @@ export class RecordReader {
     hasChanged(lastSeen) {
         return this.getSequence() !== lastSeen;
     }
+    /**
+     * True while the writer holds an open write window (sequence is odd).
+     * Readers can use this to cheaply defer sync work past a publish.
+     */
+    isWriteInProgress() {
+        return (Atomics.load(this.seqArr, 0) & 1) !== 0;
+    }
+    /**
+     * Run `fn` against a consistent snapshot of the channel. The sequence
+     * word is a seqlock: odd while the writer is publishing, even when the
+     * data is stable. The read is retried while the word is odd or changes
+     * mid-read; after maxRetries it returns whatever the last attempt read
+     * rather than starving the reader (writers publish every tick).
+     */
+    readConsistent(fn, maxRetries = 64) {
+        for (let i = 0; i < maxRetries; i++) {
+            const s1 = Atomics.load(this.seqArr, 0);
+            if ((s1 & 1) === 0) {
+                const out = fn();
+                if (Atomics.load(this.seqArr, 0) === s1)
+                    return out;
+            }
+        }
+        return fn();
+    }
     snapshot() {
         const data = {};
         if (this.layout.fields) {
@@ -73,6 +98,8 @@ export class RecordWriter {
     fields;
     seqArr;
     layout;
+    /** True while a beginWrite() window is open (sequence is odd). */
+    writeOpen = false;
     constructor(sab, layout) {
         this.layout = layout;
         this.header = createHeaderViews(sab, layout.header.size);
@@ -88,16 +115,33 @@ export class RecordWriter {
         this.header.u32[this.layout.header.magicIndex] = this.layout.magic;
         this.header.u32[this.layout.header.versionIndex] = this.layout.version;
     }
+    /**
+     * Open a write window — marks the sequence word odd so readers know a
+     * publish is in progress. Idempotent so mutating paths can call it
+     * unconditionally.
+     */
     beginWrite() {
-        const seq = Atomics.load(this.seqArr, 0);
-        Atomics.store(this.seqArr, 0, seq + 1);
+        if (this.writeOpen)
+            return;
+        this.writeOpen = true;
+        Atomics.add(this.seqArr, 0, 1);
     }
+    /** Close the write window opened by beginWrite() — sequence back to even. */
     endWrite() {
-        // Sequence is incremented in beginWrite() — endWrite() is a no-op
-        // to avoid double incrementing.
+        if (!this.writeOpen)
+            return;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, 1);
     }
+    /**
+     * Publish a commit. Without an open write window it steps +2 (even→even)
+     * so the sequence always lands on a stable value while still advancing
+     * once per publish; inside a window it closes it (+1, odd→even).
+     */
     bumpSequence() {
-        Atomics.add(this.seqArr, 0, 1);
+        const step = this.writeOpen ? 1 : 2;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, step);
     }
     getSequence() {
         return Atomics.load(this.seqArr, 0);