@downdraft/engine 0.2.0 → 0.3.1

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

@@ -4,6 +4,7 @@
 // Works in both Web Workers and Node.js worker_threads.
 // ============================================================================
 import { createLogger } from "../util/logger.js";
+import { untrackedTimeout } from "../util/session-timer.js";
 const log = createLogger();
 // In Node.js/Bun worker_threads, `parentPort` is non-null only inside a
 // worker connected to a parent — its presence IS the worker check. (The old
@@ -54,6 +55,54 @@ export function getWorkerHost() {
         },
     };
 }
+// --- Event channel stats ---
+// Cheap counters the DOWNDRAFT_EVENT_STATS logger (and QA tooling) read to
+// verify batching is actually engaging: emitted events vs postMessage posts
+// on the worker side, messages vs delivered events on the host side.
+const eventChannelStats = {
+    /** Worker side: emit() calls. */
+    emitted: 0,
+    /** Worker side: postMessage calls carrying events (batch or single). */
+    posts: 0,
+    /** Host side: messages received carrying events. */
+    messages: 0,
+    /** Host side: events delivered to listeners. */
+    events: 0,
+    /** Host side: largest observed __eventBatch. */
+    maxBatch: 0,
+};
+export function getEventChannelStats() {
+    return eventChannelStats;
+}
+function envFlag(name) {
+    try {
+        return (globalThis.process?.env?.[name] === "1");
+    }
+    catch {
+        return false;
+    }
+}
+let statsLoggerStarted = false;
+function startEventStatsLogger() {
+    if (statsLoggerStarted || !envFlag("DOWNDRAFT_EVENT_STATS"))
+        return;
+    statsLoggerStarted = true;
+    let prev = { emitted: 0, posts: 0, messages: 0, events: 0 };
+    const t = setInterval(() => {
+        const s = eventChannelStats;
+        const d = {
+            emitted: s.emitted - prev.emitted,
+            posts: s.posts - prev.posts,
+            messages: s.messages - prev.messages,
+            events: s.events - prev.events,
+        };
+        prev = { emitted: s.emitted, posts: s.posts, messages: s.messages, events: s.events };
+        if (d.emitted || d.posts || d.messages || d.events) {
+            log.info("rpc-events", `5s Δ emitted=${d.emitted} posts=${d.posts} msgs=${d.messages} events=${d.events} maxBatch=${s.maxBatch}`);
+        }
+    }, 5000);
+    t.unref?.();
+}
 function isRpcRequest(msg) {
     return msg && msg.__rpc === true && typeof msg.method === "string";
 }
@@ -63,6 +112,9 @@ function isRpcResponse(msg) {
 function isEventMessage(msg) {
     return msg && msg.__event === true;
 }
+function isEventBatchMessage(msg) {
+    return msg && msg.__eventBatch === true;
+}
 export function expose(api, options) {
     const h = options?.host ?? getWorkerHost();
     h.onHostMessage(async (msg) => {
@@ -84,14 +136,52 @@ export function expose(api, options) {
 }
 export function exposeEvents(host) {
     const h = host ?? getWorkerHost();
+    startEventStatsLogger();
     return {
         emit: (kind, data) => {
+            eventChannelStats.emitted++;
+            eventChannelStats.posts++;
             h.postToHost({ __event: true, kind, data });
         },
     };
 }
+/**
+ * Event emitter that coalesces emit() calls into a single `__eventBatch`
+ * postMessage per macrotask. A sim emitting per-tick or per-entity events
+ * otherwise produces one structured clone + one main-thread task per event,
+ * and the task burst competes with rAF. Events emitted during a tick batch
+ * (the worker never yields to timers mid-tick) all land in one message;
+ * events emitted between ticks flush on the next macrotask, so latency for
+ * isolated events is unchanged.
+ */
+export function exposeBatchedEvents(host) {
+    const h = host ?? getWorkerHost();
+    startEventStatsLogger();
+    let queue = [];
+    let flushScheduled = false;
+    const flush = () => {
+        flushScheduled = false;
+        if (queue.length === 0)
+            return;
+        eventChannelStats.posts++;
+        h.postToHost({ __eventBatch: true, events: queue });
+        queue = [];
+    };
+    return {
+        emit: (kind, data) => {
+            eventChannelStats.emitted++;
+            queue.push({ kind, data });
+            if (!flushScheduled) {
+                flushScheduled = true;
+                setTimeout(flush, 0);
+            }
+        },
+        flush,
+    };
+}
 const DEFAULT_TIMEOUT_MS = 30_000;
 export function wrap(worker, options) {
+    startEventStatsLogger();
     const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     // A worker nobody terminates must not pin the runtime after the host's
     // window closes — in-flight RPCs still hold the loop via their timeout.
@@ -114,13 +204,20 @@ export function wrap(worker, options) {
                 p.resolve(msg.result);
             return;
         }
-        if (isEventMessage(msg)) {
-            for (const cb of eventListeners.values()) {
-                try {
-                    cb(msg.kind, msg.data);
-                }
-                catch (err) {
-                    log.error("worker-proxy", `Event listener error: ${err}`);
+        if (isEventMessage(msg) || isEventBatchMessage(msg)) {
+            const events = isEventBatchMessage(msg) ? msg.events : [msg];
+            eventChannelStats.messages++;
+            eventChannelStats.events += events.length;
+            if (events.length > eventChannelStats.maxBatch)
+                eventChannelStats.maxBatch = events.length;
+            for (const ev of events) {
+                for (const cb of eventListeners.values()) {
+                    try {
+                        cb(ev.kind, ev.data);
+                    }
+                    catch (err) {
+                        log.error("worker-proxy", `Event listener error: ${err}`);
+                    }
                 }
             }
         }
@@ -172,7 +269,7 @@ export function wrap(worker, options) {
                     const id = ++reqId;
                     const entry = { resolve, reject };
                     if (timeoutMs > 0) {
-                        entry.timer = setTimeout(() => {
+                        entry.timer = untrackedTimeout(() => {
                             if (pending.delete(id)) {
                                 reject(new Error(`RPC '${method}' timed out after ${timeoutMs}ms`));
                             }

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

@@ -38,7 +38,7 @@ 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";
+import { expose, exposeBatchedEvents } from "./rpc.js";
 const log = createLogger();
 /**
  * Detect deterministic/test mode inside a worker. `DOWNDRAFT_DETERMINISTIC`
@@ -158,7 +158,7 @@ export function createSimWorker(opts) {
     let tickInFlight = null;
     // Serializes withLoopStopped critical sections.
     let stopChain = Promise.resolve();
-    const events = exposeEvents();
+    const events = exposeBatchedEvents();
     // 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);
@@ -423,6 +423,9 @@ export function createSimWorker(opts) {
             syncWorker = null; // release sync worker reference
             saveStore = null;
             await opts.onShutdown?.();
+            // Drain any events queued during onShutdown so they aren't lost to
+            // a flush timer the terminating worker never runs.
+            events.flush();
         },
         async setSpeed(speed) {
             speedMultiplier = Math.min(opts.maxSpeed ?? Infinity, Math.max(opts.minSpeed ?? 0, speed));

package/dist/core/src/worker/task-pool.js

@@ -78,6 +78,11 @@ export class TaskPool {
             for (let i = 0; i < this.workerCount; i++) {
                 const worker = this.createWorker();
                 worker.onerror = (e) => {
+                    // Session teardown tags tracked workers __ddExpectTerminate and
+                    // fires synthetic error events to settle waiters — not faults
+                    // (see session-tracker.ts terminateTrackedWorker).
+                    if (worker.__ddExpectTerminate || this.destroyed)
+                        return;
                     if (this.onWorkerError)
                         this.onWorkerError(i, e);
                     else

package/dist/libraries/blitz-ui/src/native-module.js

@@ -116,7 +116,14 @@ export function createBlitzUiNativeModule(options) {
                 const device = ctx.getDevice();
                 const view = ensureTexture(device);
                 const context = ctx.getSurface().getContext("webgpu");
-                const targetTex = context?.getCurrentTexture();
+                // Join the in-flight frame, never start one: on a frame the
+                // game skipped (dirty-tracking), acquiring the surface here
+                // would present the UI blit over a blank swapchain image.
+                const peek = context
+                    ?.peekCurrentTexture;
+                const targetTex = typeof peek === "function"
+                    ? peek.call(context)
+                    : context?.getCurrentTexture() ?? null;
                 const target = targetTex?.createView();
                 if (!view || !target || !targetTex)
                     return;

package/dist/libraries/devtools/src/backend.js

@@ -44,6 +44,12 @@ export class DevtoolsBackend {
     providers = new Map();
     commandHandlers = new Map();
     globalCommandHandler = null;
+    /** Dynamically-allocated slots for provider names outside the fixed PANEL
+     *  table — panelSlot() alone collapsed every unknown name onto slot 0
+     *  ("console"), so a second game provider silently replaced the first. */
+    dynSlots = new Map();
+    dynSlotNames = new Map();
+    nextDynSlot = 100;
     lastProviderPush = new Map();
     providerIntervalMs = 1500;
     /** When non-null, the cadence loop only auto-refreshes this provider
@@ -178,37 +184,57 @@ export class DevtoolsBackend {
         this.emit("console.clear", {});
     }
     // ── Providers / commands ──
+    /** Resolve a panel id to its slot. Names outside the fixed PANEL table
+     *  get a stable dynamically-allocated slot so bespoke game providers can
+     *  coexist instead of colliding on slot 0. */
+    slotFor(panel) {
+        if (typeof panel === "number")
+            return panel;
+        const fixed = PANEL[panel];
+        if (fixed !== undefined)
+            return fixed;
+        let s = this.dynSlots.get(panel);
+        if (s === undefined) {
+            s = this.nextDynSlot++;
+            this.dynSlots.set(panel, s);
+            this.dynSlotNames.set(s, panel);
+        }
+        return s;
+    }
+    nameFor(slot) {
+        return this.dynSlotNames.get(slot) ?? slotName(slot);
+    }
     registerProvider(panel, collect) {
-        this.providers.set(panelSlot(panel), collect);
+        this.providers.set(this.slotFor(panel), collect);
     }
     registerCommandHandler(panel, handler) {
         if (panel === "*") {
             this.globalCommandHandler = handler;
         }
         else {
-            this.commandHandlers.set(panelSlot(panel), handler);
+            this.commandHandlers.set(this.slotFor(panel), handler);
         }
     }
     /** Registered provider slots — the dynamic tab list for frontends. */
     providerSlots() {
-        return [...this.providers.keys()].map((slot) => ({ slot, name: slotName(slot) }));
+        return [...this.providers.keys()].map((slot) => ({ slot, name: this.nameFor(slot) }));
     }
     /** Collect + emit one provider's snapshot immediately. */
     refreshPanel(panel) {
         const trace = [performance.now()];
-        const slot = panelSlot(panel);
+        const slot = this.slotFor(panel);
         trace.push(performance.now());
         const collect = this.providers.get(slot);
         if (!collect)
             return;
         const push = (snap) => {
             if (snap)
-                this.emit("snapshot", { panel: slotName(slot), slot, snap });
+                this.emit("snapshot", { panel: this.nameFor(slot), slot, snap });
             this.lastProviderPush.set(slot, performance.now());
         };
         const fail = (err) => {
             this.emit("snapshot", {
-                panel: slotName(slot), slot,
+                panel: this.nameFor(slot), slot,
                 snap: { status: "error", statusMsg: String(err), sections: [] },
             });
             this.lastProviderPush.set(slot, performance.now());
@@ -231,7 +257,7 @@ export class DevtoolsBackend {
         const total = trace[4] - trace[0];
         if (total > 10) {
             const seg = `pre=${(trace[2] - trace[0]).toFixed(1)} collect=${(trace[3] - trace[2]).toFixed(1)} emit=${(trace[4] - trace[3]).toFixed(1)}`;
-            this.diagWarn(`slow provider ${slotName(slot)}: ${total.toFixed(1)}ms [${seg}]`);
+            this.diagWarn(`slow provider ${this.nameFor(slot)}: ${total.toFixed(1)}ms [${seg}]`);
         }
     }
     dispatchCommand(cmd) {
@@ -374,7 +400,7 @@ export class DevtoolsBackend {
                 return collectThreads(this.ctx, [...this.threadEvals.keys()]);
             case "snapshot": {
                 const panel = params.panel;
-                const slot = typeof panel === "number" ? panel : panelSlot(panel);
+                const slot = typeof panel === "number" ? panel : this.slotFor(String(panel));
                 const collect = this.providers.get(slot);
                 if (!collect)
                     return { status: "unsupported", statusMsg: `no provider for ${String(panel)}`, sections: [] };
@@ -388,7 +414,7 @@ export class DevtoolsBackend {
             }
             case "command": {
                 const panel = params.panel;
-                const slot = typeof panel === "number" ? panel : panelSlot(panel ?? "console");
+                const slot = typeof panel === "number" ? panel : this.slotFor(String(panel ?? "console"));
                 this.dispatchCommand({ panel: slot, action: String(params.action ?? ""), payload: String(params.payload ?? "") });
                 return true;
             }

package/dist/libraries/devtools/src/collectors.js

@@ -72,31 +72,81 @@ export async function collectThreads(ctx, evalThreadIds) {
     });
     return threads;
 }
-/** Scene-graph tree (label + ctor + child counts). */
+function sceneInspectorApi() {
+    const g = globalThis;
+    return (g.window?.__sceneInspector ?? g.__sceneInspector ?? null);
+}
+/** Scene-graph tree (label + ctor + child counts). Prefers a live
+ *  `gameScene.stage` walk; falls back to the SceneInspector's scene store
+ *  (`__sceneInspector.getSceneTree`) so games without a DOM-like stage still
+ *  get a populated tree — with stable nodeIds for pick/details. */
 export function collectSceneTree(ctx) {
     const stage = ctx.gameScene?.stage;
-    if (!stage)
+    if (stage) {
+        const nodes = [];
+        let idCounter = 1;
+        const collect = (node, parentId, depth) => {
+            const id = idCounter++;
+            // Prefer `label` (some scene-graph hosts warn on `name` access); fall
+            // back to `name` for hosts that only set that.
+            const nodeLabel = typeof node.label === "string" ? node.label
+                : typeof node.name === "string" ? node.name : "";
+            const ctorName = node.constructor?.name ?? "Node";
+            nodes.push({
+                id, parentId, depth,
+                childCount: node.children?.length ?? 0,
+                kind: 0,
+                label: nodeLabel || ctorName,
+                detail: nodeLabel ? ctorName : "",
+                nodeId: typeof node.id === "string" ? node.id : undefined,
+            });
+            node.children?.forEach((child) => collect(child, id, depth + 1));
+        };
+        collect(stage, -1, 0);
+        return nodes;
+    }
+    // Scene-store fallback — the same snapshot the inspector's getSceneTree
+    // exposes. Nodes are flat with id/parentId links; walk roots → children.
+    try {
+        const snap = sceneInspectorApi()?.getSceneTree?.();
+        const storeNodes = snap?.nodes;
+        if (!Array.isArray(storeNodes) || !storeNodes.length)
+            return [];
+        const byId = new Map(storeNodes.map((n) => [n.id, n]));
+        const roots = storeNodes.filter((n) => n.parentId === null || !byId.has(n.parentId));
+        const rows = [];
+        const visited = new Set();
+        let idCounter = 1;
+        const walk = (n, parentId, depth) => {
+            if (visited.has(n.id))
+                return; // corrupted parent/child links — don't loop
+            visited.add(n.id);
+            const id = idCounter++;
+            const p = n.position;
+            rows.push({
+                id, parentId, depth,
+                childCount: n.children?.length ?? 0,
+                kind: 0,
+                label: String(n.name ?? n.id),
+                detail: `${n.type ?? "node"}${Array.isArray(p) ? ` (${p.map((v) => (+v).toFixed(1)).join(", ")})` : ""}`,
+                nodeId: String(n.id),
+            });
+            for (const cid of n.children ?? []) {
+                const c = byId.get(cid);
+                if (c)
+                    walk(c, id, depth + 1);
+            }
+        };
+        roots.forEach((n) => walk(n, -1, 0));
+        // Orphans (every node has a parent but no root resolves) — still show them.
+        for (const n of storeNodes)
+            if (!visited.has(n.id))
+                walk(n, -1, 0);
+        return rows;
+    }
+    catch {
         return [];
-    const nodes = [];
-    let idCounter = 1;
-    const collect = (node, parentId, depth) => {
-        const id = idCounter++;
-        // Prefer `label` (some scene-graph hosts warn on `name` access); fall
-        // back to `name` for hosts that only set that.
-        const nodeLabel = typeof node.label === "string" ? node.label
-            : typeof node.name === "string" ? node.name : "";
-        const ctorName = node.constructor?.name ?? "Node";
-        nodes.push({
-            id, parentId, depth,
-            childCount: node.children?.length ?? 0,
-            kind: 0,
-            label: nodeLabel || ctorName,
-            detail: nodeLabel ? ctorName : "",
-        });
-        node.children?.forEach((child) => collect(child, id, depth + 1));
-    };
-    collect(stage, -1, 0);
-    return nodes;
+    }
 }
 /** DOM tree: scene-graph stage or ECS entities depending on mode. */
 export function collectDomTree(ctx, mode) {
@@ -122,6 +172,7 @@ export function collectDomTree(ctx, mode) {
                 id, parentId: -1, depth: 0, childCount: 0, kind: 1,
                 label: `Entity ${ent.idx}`,
                 detail: `type=${entityType} pos=(${x.toFixed(1)},${y.toFixed(1)},${z.toFixed(1)})`,
+                nodeId: `ent-${ent.idx}`,
             });
         });
     }

package/dist/libraries/devtools/src/native-providers.js

@@ -515,8 +515,6 @@ async function collectWorkers(ctx) {
                 kind: "kv",
                 name: `Worker manifest (v${m.manifestVersion ?? "?"})`,
                 rows: [
-                    kv("Panels", (m.panels ?? []).map((p) => p.id ?? p.name ?? "?").join(", ") || "(none)"),
-                    kv("Toggles", (m.toggles ?? []).map((t) => t.id ?? "?").join(", ") || "(none)"),
                     kv("Data feeds", (m.dataFeeds ?? []).map((f) => `${f.name}@${f.writeRateHz}hz`).join(", ") || "(none)"),
                     kv("Commands", (m.commands ?? []).join(", ") || "(none)"),
                 ],