@downdraft/engine 0.2.0 → 0.3.0

package/core/src/index.ts

@@ -56,7 +56,7 @@ export type { MultiInputChannelInstance, MultiInputChannelOptions } from "./sab/
 export { INP, INP_FLAG, INP_HDR, INPUT_MAGIC, INPUT_VERSION, InputBufferReader, InputBufferWriter, InputChannel, KEY, MAX_INPUT_PLAYERS } from "./sab/game-input";
 
 // 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";
+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";
 export type { PhysicsTimingData } from "./sab/sim-channel";
 
 // SAB Framework
@@ -90,7 +90,7 @@ export { EntitySimWorkerHost } from "./worker/entity-sim-worker-host";
 export type { EntitySimApi, EntitySimHostOptions } from "./worker/entity-sim-worker-host";
 export { exposeProfilingApi, InstrumentedWorkerHost } from "./worker/instrumented-worker-host";
 export type { InstrumentedWorkerHostOptions } from "./worker/instrumented-worker-host";
-export { expose, exposeEvents, getWorkerHost, wrap } from "./worker/rpc";
+export { expose, exposeBatchedEvents, exposeEvents, getWorkerHost, wrap } from "./worker/rpc";
 export type { ExposeOptions, HostMessageHandler, WorkerApi, WorkerEventEmitter, WorkerHost, WorkerProxy } from "./worker/rpc";
 export { createSimWorker } from "./worker/sim-worker-base";
 export type { CreateSimWorkerOptions, SimAfterTicksContext, SimTickContext, SimWorkerControl, SimWorkerStats } from "./worker/sim-worker-base";

package/core/src/platform/rpc.ts

@@ -1,3 +1,6 @@
+
+import { untrackedTimeout } from "../util/session-timer";
+
 export type RPCMessageType = "request" | "response" | "event";
 
 export interface RPCMessage {
@@ -34,7 +37,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/core/src/render/game-renderer.ts

@@ -233,6 +233,9 @@ export class GameRenderer implements CanvasResizeHandler {
   uiInputRouter: UIInputRouter | null = null;
   /** Screen-space compositors (html-ui panels etc.) drawn in the UI pass. */
   private uiCompositors = new Set<import("../module/renderer-module").ScreenUiCompositor>();
+  /** uiCompositors as a pre-sorted array — rebuilt on add/remove so the
+   *  frame loop doesn't spread+sort the set every frame. */
+  private uiCompositorOrder: import("../module/renderer-module").ScreenUiCompositor[] = [];
 
   // Render loop state
   private running = false;
@@ -272,13 +275,25 @@ export class GameRenderer implements CanvasResizeHandler {
 
   // Depth texture cache (used when the graph does not own depth)
   // LRU: Map insertion order = access order (delete + re-set on access).
-  private depthTextures = new Map<string, GPUTexture>();
+  // Numeric key packs (w,h) — a `${w}x${h}` string key allocated a fresh
+  // string per lookup per viewport per frame.
+  private depthTextures = new Map<number, GPUTexture>();
   private depthTextureCacheSize: number;
 
   // Frame stats
   private frameDrawCalls = 0;
   private 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.
+  private frameSubmitSink: GPUCommandBuffer[] | null = null;
+  private submitInterceptorDevice: GPUDevice | null = null;
+
   // Callbacks
   private callbacks: FrameCallbacks = {};
 
@@ -354,6 +369,7 @@ export class GameRenderer implements CanvasResizeHandler {
         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
@@ -426,8 +442,16 @@ export class GameRenderer implements CanvasResizeHandler {
         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));
+            }
+          };
         },
       });
 
@@ -543,6 +567,7 @@ export class GameRenderer implements CanvasResizeHandler {
       const device = await this.requestDeviceFromAdapter(adapter);
       device.lost.then((info) => this.handleDeviceLost(info));
       this.device = device;
+      this.installQueueSubmitInterceptor(device);
       this.adapter = adapter;
 
       installShaderValidationGuard(device);
@@ -798,15 +823,39 @@ export class GameRenderer implements CanvasResizeHandler {
       this.renderFrame();
     } catch (err) {
       log.error("game-renderer", `Render loop error: ${(err as Error).message}\n${(err as Error).stack}`);
-      if (this.device?.lost) {
-        this.device.lost.then((info: GPUDeviceLostInfo) => {
-          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.
+   */
+  private installQueueSubmitInterceptor(device: GPUDevice): void {
+    if (this.submitInterceptorDevice === device) return;
+    this.submitInterceptorDevice = device;
+    const queue = device.queue as any;
+    if (queue.__ddSubmitIntercepted) return;
+    queue.__ddSubmitIntercepted = true;
+    const origSubmit: GPUQueue["submit"] = queue.submit.bind(queue);
+    queue.submit = (commandBuffers: Iterable<GPUCommandBuffer>) => {
+      const sink = this.frameSubmitSink;
+      if (!sink) {
+        origSubmit(commandBuffers);
+        return;
+      }
+      for (const cb of commandBuffers) sink.push(cb);
+    };
+  }
+
   private renderFrame(): void {
     const now = performance.now();
 
@@ -856,6 +905,15 @@ export class GameRenderer implements CanvasResizeHandler {
     // 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: GPUCommandBuffer[] = [];
+    this.frameSubmitSink = frameCommandBuffers;
+
     // XR render target provider beginFrame hook
     if (this.renderTargetProvider && !gpuError) {
       this.renderTargetProvider.beginFrame();
@@ -869,9 +927,6 @@ export class GameRenderer implements CanvasResizeHandler {
       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: GPUCommandBuffer[] = [];
     if (!gpuError) {
       // 2D mode with viewportCount=0: clear the canvas if a clearColor is
       // configured, then let the afterFrame callback do custom rendering.
@@ -922,21 +977,6 @@ export class GameRenderer implements CanvasResizeHandler {
       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);
@@ -975,43 +1015,68 @@ export class GameRenderer implements CanvasResizeHandler {
       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
-    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" as GPULoadOp,
-            storeOp: "store" as GPUStoreOp,
-          }],
-        });
-        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()]);
+      // 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" as GPULoadOp,
+              storeOp: "store" as GPUStoreOp,
+            }],
+          });
+          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());
+        }
       }
+    } 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 as Error).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;
@@ -1220,7 +1285,7 @@ export class GameRenderer implements CanvasResizeHandler {
 
   private createDepthTexture(w: number, h: number): GPUTextureView {
     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.
@@ -1314,9 +1379,7 @@ export class GameRenderer implements CanvasResizeHandler {
    * this helper only runs the compositors.
    */
   protected renderScreenUiCompositors(): void {
-    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();
     if (!canvasView) return;

package/core/src/sab/grid-buffer.ts

@@ -1,5 +1,5 @@
-import type { ChannelLayout, GridLayerLayout, HeaderViews } from "./types";
 import { describeHeaderValidation } from "./errors";
+import type { ChannelLayout, GridLayerLayout, HeaderViews } from "./types";
 
 function createHeaderViews(sab: SharedArrayBuffer, headerSize: number): HeaderViews {
   const u32Length = headerSize / 4;
@@ -66,6 +66,32 @@ export class GridReader {
     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(): boolean {
+    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<T>(fn: () => T, maxRetries = 64): T {
+    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(): Record<string, unknown> {
     const data: Record<string, unknown> = {};
     data["sequence"] = this.getSequence();
@@ -88,6 +114,8 @@ export class GridWriter {
   layers: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
   private seqArr: Int32Array;
   private layout: ChannelLayout;
+  /** True while a beginWrite() window is open (sequence is odd). */
+  private writeOpen = false;
 
   constructor(sab: SharedArrayBuffer, layout: ChannelLayout) {
     this.layout = layout;
@@ -107,10 +135,35 @@ export class GridWriter {
     this.header.u32[this.layout.header.versionIndex] = this.layout.version;
   }
 
-  bumpSequence(): void {
+  /**
+   * 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(): void {
+    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(): void {
+    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(): void {
+    const step = this.writeOpen ? 1 : 2;
+    this.writeOpen = false;
+    Atomics.add(this.seqArr, 0, step);
+  }
+
   getSequence(): number {
     return Atomics.load(this.seqArr, 0);
   }

package/core/src/sab/record-buffer.ts

@@ -67,6 +67,32 @@ export class RecordReader {
     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(): boolean {
+    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<T>(fn: () => T, maxRetries = 64): T {
+    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(): Record<string, unknown> {
     const data: Record<string, unknown> = {};
     if (this.layout.fields) {
@@ -93,6 +119,8 @@ export class RecordWriter {
   fields: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
   private seqArr: Int32Array;
   private layout: ChannelLayout;
+  /** True while a beginWrite() window is open (sequence is odd). */
+  private writeOpen = false;
 
   constructor(sab: SharedArrayBuffer, layout: ChannelLayout) {
     this.layout = layout;
@@ -112,18 +140,33 @@ export class RecordWriter {
     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(): void {
-    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(): void {
-    // 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(): void {
-    Atomics.add(this.seqArr, 0, 1);
+    const step = this.writeOpen ? 1 : 2;
+    this.writeOpen = false;
+    Atomics.add(this.seqArr, 0, step);
   }
 
   getSequence(): number {