@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/modules/camera-controls/src/index.js

@@ -0,0 +1,116 @@
+// ============================================================================
+// Camera Controls Module — orbit/pan/zoom camera controller as a renderer plugin
+//
+// Registers a `CameraController` as the active camera provider on the
+// `RendererModuleContext`, wires orbit/pan/zoom input from the shared input
+// bus, and disposes cleanly on unload. This is the engine-builtin replacement
+// for game-local `OrbitCamera` classes.
+//
+// For games with bespoke render loops (no `GameRenderer`), use
+// `createCameraController(inputBus, opts)` instead — it returns a bare
+// `CameraController` wired to a `RendererInputBus` without the plugin wrapper.
+// ============================================================================
+import { Camera, CameraController, } from "@downdraft/engine";
+/**
+ * Creates a configured `CameraController` and wires it to a
+ * `RendererInputBus` for orbit/pan/zoom input. For games that use
+ * `GameRenderer` + `RendererModuleHost`, prefer `createCameraControlsModule`
+ * instead — it handles registration and disposal automatically.
+ *
+ * The caller is responsible for:
+ *  - calling `controller.setAspect(w, h)` on resize
+ *  - calling `controller.update(dt)` each frame (if lerp is enabled)
+ *  - calling `controller.unbindOrbit()` + `controller.dispose()` on teardown
+ *
+ * @example
+ * ```ts
+ * const inputBus = new RendererInputBusImpl(canvas);
+ * const controller = createCameraController(inputBus, {
+ *   initialCamera: { position: [0, 5, 10], target: [0, 0, 0], fov: 45 },
+ *   orbit: { minDistance: 0.1, maxDistance: 500 },
+ * });
+ * ```
+ */
+export function createCameraController(inputBus, opts = {}) {
+    const camId = opts.initialCamera?.id ?? "main";
+    const cam = new Camera();
+    if (opts.initialCamera) {
+        const ic = opts.initialCamera;
+        if (ic.position) {
+            if (ic.position.length !== 3) {
+                throw new RangeError(`initialCamera.position must have length 3, got ${ic.position.length}`);
+            }
+            cam.setPosition(...ic.position);
+        }
+        if (ic.target) {
+            if (ic.target.length !== 3) {
+                throw new RangeError(`initialCamera.target must have length 3, got ${ic.target.length}`);
+            }
+            cam.setTarget(...ic.target);
+        }
+        if (ic.fov !== undefined) {
+            if (!(ic.fov > 0)) {
+                throw new RangeError(`initialCamera.fov must be > 0, got ${ic.fov}`);
+            }
+            cam.setFov(ic.fov);
+        }
+        if (ic.near !== undefined) {
+            if (!(ic.near > 0)) {
+                throw new RangeError(`initialCamera.near must be > 0, got ${ic.near}`);
+            }
+            cam.near = ic.near;
+        }
+        if (ic.far !== undefined) {
+            if (ic.near !== undefined && !(ic.far > ic.near)) {
+                throw new RangeError(`initialCamera.far (${ic.far}) must be > near (${ic.near})`);
+            }
+            cam.far = ic.far;
+        }
+    }
+    const controller = new CameraController({
+        ...opts.controller,
+        defaultCameraId: camId,
+    });
+    // The constructor's defaultCameraId creates its own Camera; replace it
+    // with our configured one.
+    controller.removeCamera(camId);
+    controller.addCamera(camId, cam);
+    controller.setActive(camId);
+    // Wire orbit/pan/zoom input from the supplied input bus.
+    controller.bindOrbit(inputBus, opts.orbit);
+    return controller;
+}
+/**
+ * Creates a `RendererModule` that registers an orbit camera controller.
+ * The controller is accessible via `ctx.getCameraController()` after
+ * registration, or by capturing the return value of `createCameraControlsModule`.
+ */
+export function createCameraControlsModule(opts = {}) {
+    let controller = null;
+    const plugin = {
+        name: "camera-controls",
+        version: "0.1.0",
+        register(ctx) {
+            controller = createCameraController(ctx.getInputBus(), opts);
+            // Register as the active camera provider.
+            ctx.setCameraController(controller);
+            // Clean up on dispose.
+            ctx.onDispose(() => {
+                controller?.unbindOrbit();
+                controller?.dispose();
+                controller = null;
+                ctx.setCameraController(null);
+            });
+        },
+        getController() {
+            return controller;
+        },
+    };
+    return plugin;
+}
+/**
+ * Convenience default instance with sensible orbit defaults. Games that need
+ * custom sensitivity/lerp should use `createCameraControlsModule(opts)`.
+ */
+export const CameraControlsModule = createCameraControlsModule();
+export { Camera, CameraController } from "@downdraft/engine";

package/dist/modules/controller-ui/src/index.js

@@ -0,0 +1,149 @@
+// ============================================================================
+// controller-ui — engine-provided controller settings screen.
+//
+//   renderer.useRendererModule(createHtmlUi({ build(ui) { ... } }));
+//   renderer.useRendererModule(createControllerUi());
+//   // game code: ui.open() from a menu action, or bind to START+SELECT, etc.
+//
+// A full "Controllers" settings panel built on html-ui + html-ui-kit:
+// device list (name, pad type, battery), a live button/axis test diagram,
+// and per-device rumble test. Because it mounts through HtmlUiContext.mount,
+// controller nav + OSK + focus zones come free — this module is also the
+// dogfood proof for the nav stack.
+// ============================================================================
+import { createLogger, resourceToken } from "@downdraft/engine";
+import { GamepadHubTok } from "@downdraft/engine/libraries/gamepad";
+import { esc, kitStyleTag, tvCss } from "@downdraft/engine/libraries/html-ui-kit";
+import { HtmlUiTok } from "@downdraft/engine/modules/html-ui";
+import { GP_AXIS, GP_BTN } from "@downdraft/engine/sab/gamepad-devices";
+const log = createLogger("info");
+export const ControllerUiTok = resourceToken("controller-ui");
+const BTN_LABELS = [
+    [GP_BTN.SOUTH, "A"], [GP_BTN.EAST, "B"], [GP_BTN.WEST, "X"], [GP_BTN.NORTH, "Y"],
+    [GP_BTN.LEFT_SHOULDER, "LB"], [GP_BTN.RIGHT_SHOULDER, "RB"],
+    [GP_BTN.LEFT_TRIGGER_BTN, "LT"], [GP_BTN.RIGHT_TRIGGER_BTN, "RT"],
+    [GP_BTN.SELECT, "SEL"], [GP_BTN.START, "STR"], [GP_BTN.HOME, "HOME"],
+    [GP_BTN.LEFT_STICK, "L3"], [GP_BTN.RIGHT_STICK, "R3"],
+    [GP_BTN.DPAD_UP, "▲"], [GP_BTN.DPAD_DOWN, "▼"], [GP_BTN.DPAD_LEFT, "◀"], [GP_BTN.DPAD_RIGHT, "▶"],
+];
+const AXIS_LABELS = ["LX", "LY", "RX", "RY", "LT", "RT", "DX", "DY"];
+function screenMarkup() {
+    const btns = BTN_LABELS.map(([bit, lbl]) => `<div class="dd-btn ctl-btn" id="ctl-btn-${bit}" data-nav data-i="${bit}">${lbl}</div>`).join("");
+    const axes = AXIS_LABELS.map((lbl, i) => `<div class="ctl-axis"><div class="dd-label">${lbl}</div>` +
+        `<div class="dd-progress" style="flex:1"><div class="dd-pfill" id="ctl-ax-${i}" data-part="fill" style="width:0%"></div></div>` +
+        `<div class="dd-label" id="ctl-av-${i}" style="width:44px;text-align:right">0.00</div></div>`).join("");
+    return `
+<div style="height:100%;display:flex;flex-direction:column;background:var(--dd-bg)">
+  <div class="dd-row" style="padding:18px 22px 10px">
+    <div style="font-size:22px;flex:1">Controllers</div>
+    <div class="dd-btn" data-nav data-action="ctlui:close">Close</div>
+  </div>
+  <div id="ctl-devs" class="dd-col" style="padding:0 22px 12px;gap:6px"></div>
+  <div class="dd-panel" style="margin:0 22px 12px;flex:0 0 auto">
+    <div class="dd-section">BUTTON TEST</div>
+    <div style="display:flex;flex-wrap:wrap;gap:8px">${btns}</div>
+  </div>
+  <div class="dd-panel" style="margin:0 22px 12px;flex:1;display:flex;flex-direction:column;gap:8px">
+    <div class="dd-row"><div class="dd-section" style="flex:1">AXES</div>
+      <div class="dd-btn" data-nav data-action="ctlui:rumble">Rumble test</div></div>
+    ${axes}
+  </div>
+</div>`;
+}
+const CSS = `
+.ctl-dev-row { display:flex; align-items:center; gap:12px; padding:10px 12px;
+  border:1px solid var(--dd-line); border-radius:6px; background:var(--dd-panel); }
+.ctl-dev-row[data-nav-focus="1"] { border-color:var(--dd-accent); background:var(--dd-panel2); }
+.ctl-dev-name { flex:1; font-size:15px; }
+.ctl-axis { display:flex; align-items:center; gap:10px; }
+.ctl-btn[data-on="true"] { background:var(--dd-accent-bg); color:var(--dd-accent); border-color:var(--dd-accent); }
+`;
+export function createControllerUi() {
+    return {
+        name: "controller-ui",
+        version: "1.0.0",
+        requires: [HtmlUiTok],
+        provides: [ControllerUiTok],
+        register(ctx) {
+            const ui = ctx.inject(HtmlUiTok);
+            const hub = ctx.injectOptional(GamepadHubTok);
+            let panel = null;
+            const api = {
+                get panel() { return panel; },
+                get isOpen() { return panel !== null; },
+                open() {
+                    if (panel)
+                        return;
+                    const w = ctx.getSurface().clientWidth, h = ctx.getSurface().clientHeight;
+                    const pw = Math.min(720, w - 80), ph = Math.min(760, h - 80);
+                    panel = ui.mount(`${kitStyleTag()}<style>${tvCss()}${CSS}</style>${screenMarkup()}`, {
+                        id: "controller-ui",
+                        rect: { x: (w - pw) / 2, y: (h - ph) / 2, w: pw, h: ph },
+                        z: 50,
+                    });
+                    refreshDevices();
+                    ui.onAction("ctlui:close", () => api.close());
+                    ui.onAction("ctlui:rumble", () => {
+                        const dev = selected();
+                        if (dev)
+                            dev.rumble(32768, 65535, 300);
+                    });
+                },
+                close() {
+                    panel?.dispose();
+                    panel = null;
+                },
+            };
+            let sel = 0;
+            function selected() {
+                const devs = hub?.list() ?? [];
+                return devs[Math.min(sel, Math.max(0, devs.length - 1))] ?? null;
+            }
+            function refreshDevices() {
+                if (!panel)
+                    return;
+                const devs = hub?.list() ?? [];
+                const rows = devs.length
+                    ? devs.map((d, i) => {
+                        const bat = d.batteryPercent;
+                        const meta = [
+                            d.info.padType ?? "gamepad",
+                            bat !== null ? `${bat}%${d.charging ? " ⚡" : ""}` : "wired",
+                        ].join(" · ");
+                        return `<div class="ctl-dev-row" data-nav data-action="ctlui:sel" data-i="${i}">` +
+                            `<div class="ctl-dev-name">${esc(d.info.name)}</div>` +
+                            `<div class="dd-label">${esc(meta)}</div></div>`;
+                    }).join("")
+                    : `<div class="dd-label" style="padding:8px 4px">No controllers connected</div>`;
+                panel.mutate([{ op: "innerHtml", sel: "#ctl-devs", html: rows }]);
+                ui.nav?.invalidate(panel);
+            }
+            ui.onAction?.("ctlui:sel", (d) => { sel = Number(d.i ?? 0); });
+            ui.onUpdate(() => {
+                const p = panel;
+                const dev = selected();
+                if (!p || !dev)
+                    return;
+                const ops = [];
+                for (const [bit] of BTN_LABELS) {
+                    ops.push({ op: "attr", sel: `#ctl-btn-${bit}`, name: "data-on",
+                        value: dev.pressed(bit) ? "true" : "false" });
+                }
+                const ax = dev.axes();
+                for (let i = 0; i < AXIS_LABELS.length; i++) {
+                    const v = ax[i] ?? 0;
+                    const isTrigger = i === GP_AXIS.LEFT_TRIGGER || i === GP_AXIS.RIGHT_TRIGGER;
+                    const pct = Math.round((isTrigger ? v : (v + 1) / 2) * 100);
+                    ops.push({ op: "style", sel: `#ctl-ax-${i}`, prop: "width", value: `${pct}%` });
+                    ops.push({ op: "text", sel: `#ctl-av-${i}`, text: v.toFixed(2) });
+                }
+                p.mutate(ops);
+            });
+            hub?.on("connect", refreshDevices);
+            hub?.on("disconnect", refreshDevices);
+            ctx.provide(ControllerUiTok, api);
+            ctx.onDispose(() => api.close());
+            log.info("controller-ui", hub ? "ready" : "ready (no gamepad source — screen will show 'No controllers')");
+        },
+    };
+}

package/dist/modules/devtools/src/api.js

@@ -0,0 +1,317 @@
+// ============================================================================
+// Unified DevTools API — single registration surface for plugins, games, and
+// engine systems, regardless of which thread they run on.
+//
+// Realm detection determines transport:
+//   - Main realm: panels/feeds/commands registered directly on
+//     window.__sceneInspector via DevToolsDataBridge.
+//   - Worker realm: panels/feeds/commands registered in a worker-side
+//     registry. Data feeds are written to a devtools SAB region (zero-copy,
+//     synchronous reads). Commands are forwarded via worker RPC. Panel
+//     declarations are synced to the renderer via a one-time manifest RPC.
+//
+// Plugins import `devtools` from @downdraft/engine/modules/devtools and call
+// registerPanel/registerDataFeed/registerCommand/registerSABStat — the same
+// API works in both realms.
+// ============================================================================
+import { resourceToken } from "@downdraft/engine/ecs/resource";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { BUILTIN_VIEW_DESCRIPTORS } from "./debug-view-descriptors.js";
+const log = createLogger("info");
+// --- Realm detection ---
+// Mirrors the pattern in @downdraft/engine/worker/rpc.ts but is self-contained
+// so this package doesn't depend on core's worker module (avoids pulling
+// Node worker_threads code into the renderer bundle).
+function detectRealm() {
+    // Node.js worker_thread
+    if (typeof globalThis.process !== "undefined"
+        && globalThis.process.versions?.node
+        && typeof globalThis.require === "function") {
+        try {
+            const parentPort = globalThis.require("worker_threads")?.parentPort;
+            if (parentPort)
+                return "worker";
+        }
+        catch { /* not in a Node worker */ }
+    }
+    // Web Worker: no window, has self/importScripts
+    if (typeof globalThis.window === "undefined"
+        && typeof globalThis.self !== "undefined"
+        && typeof globalThis.importScripts === "function") {
+        return "worker";
+    }
+    return "main";
+}
+export const DEVTOOLS_REALM = detectRealm();
+// --- SAB layout for worker→renderer data feeds ---
+//
+// The devtools SAB is a dedicated region for JSON-serialized data feed
+// results + direct numeric stats. The worker writes; the renderer reads
+// synchronously. No RPC polling needed.
+//
+// Layout:
+//   [0..3]   manifestVersion: Uint32  (bumped when panels/feeds change)
+//   [4..7]   feedCount: Uint32
+//   [8..]    feed entries: each is [lengthBytes: Uint32][JSON bytes...]
+//            (lengthBytes = 0 means "not yet written" / "unavailable")
+//   ...      direct stat slots: registered via registerSABStat, read as
+//            raw u32/f32/i32 at plugin-specified offsets (relative to the
+//            statsBaseOffset returned by getDevToolsSABStatsBase)
+export const DEVTOOLS_SAB_HEADER_BYTES = 8; // manifestVersion + feedCount
+export const DEVTOOLS_SAB_MAX_FEEDS = 32;
+export const DEVTOOLS_SAB_FEED_HEADER_BYTES = 4; // lengthBytes per feed
+export const DEVTOOLS_SAB_DEFAULT_FEED_BLOB_BYTES = 4096;
+export const DEVTOOLS_SAB_DEFAULT_STATS_BYTES = 256;
+export function computeDevToolsSABLayout(maxFeedBlobBytes = DEVTOOLS_SAB_DEFAULT_FEED_BLOB_BYTES, statsBytes = DEVTOOLS_SAB_DEFAULT_STATS_BYTES) {
+    const feedEntryBytes = DEVTOOLS_SAB_FEED_HEADER_BYTES + maxFeedBlobBytes;
+    const feedsEnd = DEVTOOLS_SAB_HEADER_BYTES + feedEntryBytes * DEVTOOLS_SAB_MAX_FEEDS;
+    const statsBaseOffset = feedsEnd;
+    const totalBytes = statsBaseOffset + statsBytes;
+    return {
+        feedOffset: (i) => DEVTOOLS_SAB_HEADER_BYTES + i * feedEntryBytes,
+        feedBlobOffset: (i) => DEVTOOLS_SAB_HEADER_BYTES + i * feedEntryBytes + DEVTOOLS_SAB_FEED_HEADER_BYTES,
+        feedBlobBytes: maxFeedBlobBytes,
+        statsBaseOffset,
+        totalBytes,
+    };
+}
+export function allocateDevToolsSAB(maxFeedBlobBytes, statsBytes) {
+    const layout = computeDevToolsSABLayout(maxFeedBlobBytes, statsBytes);
+    return new SharedArrayBuffer(layout.totalBytes);
+}
+class DevToolsAPIImpl {
+    realm;
+    panels = new Map();
+    toggles = new Map();
+    dataFeeds = new Map();
+    dataFeedNames = []; // ordered list for feedIndex assignment
+    commands = new Map();
+    sabStats = new Map();
+    sab = null;
+    sabLayout = null;
+    sabU32 = null;
+    sabU8 = null;
+    sabF32 = null;
+    sabI32 = null;
+    profilingSAB = null;
+    views = new Map();
+    manifestVersion = 0;
+    constructor(realm) {
+        this.realm = realm;
+    }
+    registerPanel(ext) {
+        this.panels.set(ext.id, ext);
+        this.bumpManifest();
+    }
+    registerOverlayToggle(toggle) {
+        this.toggles.set(toggle.id, toggle);
+        this.bumpManifest();
+    }
+    registerDataFeed(name, fn, writeRateHz = 10) {
+        if (this.dataFeeds.has(name)) {
+            // Update fn/rate, keep feedIndex and hasWritten
+            const existing = this.dataFeeds.get(name);
+            this.dataFeeds.set(name, { ...existing, fn, writeRateHz });
+            return;
+        }
+        const feedIndex = this.dataFeedNames.length;
+        if (feedIndex >= DEVTOOLS_SAB_MAX_FEEDS) {
+            log.warn("devtools", `Max data feeds (${DEVTOOLS_SAB_MAX_FEEDS}) reached, ignoring "${name}"`);
+            return;
+        }
+        this.dataFeedNames.push(name);
+        this.dataFeeds.set(name, { name, fn, feedIndex, writeRateHz, lastWriteMs: 0, hasWritten: false });
+        this.bumpManifest();
+    }
+    registerCommand(name, fn) {
+        this.commands.set(name, fn);
+        this.bumpManifest();
+    }
+    registerSABStat(name, offset, type) {
+        // All stat types are 4 bytes and read via typed-array views — offsets
+        // must be 4-byte aligned and unique, or two stats silently stomp each
+        // other's values (there is no allocator for this region).
+        if (!Number.isInteger(offset) || offset < 0 || offset % 4 !== 0) {
+            log.warn("devtools", `registerSABStat("${name}"): offset ${offset} must be a non-negative 4-byte-aligned integer — ignoring`);
+            return;
+        }
+        for (const existing of this.sabStats.values()) {
+            if (existing.name !== name && existing.offset === offset) {
+                log.warn("devtools", `registerSABStat("${name}"): offset ${offset} is already used by stat "${existing.name}" — ignoring (duplicate offset)`);
+                return;
+            }
+        }
+        this.sabStats.set(name, { name, offset, type });
+        this.bumpManifest();
+    }
+    attachSAB(sab, layout) {
+        this.sab = sab;
+        this.sabLayout = layout ?? computeDevToolsSABLayout();
+        this.sabU32 = new Uint32Array(sab);
+        this.sabU8 = new Uint8Array(sab);
+        this.sabF32 = new Float32Array(sab);
+        this.sabI32 = new Int32Array(sab);
+        // Write initial manifest version + feed count
+        if (this.sabU32) {
+            this.sabU32[0] = this.manifestVersion;
+            this.sabU32[1] = this.dataFeedNames.length;
+        }
+    }
+    getSAB() {
+        return this.sab;
+    }
+    getSABLayout() {
+        return this.sabLayout;
+    }
+    attachProfilingSAB(sab) {
+        this.profilingSAB = sab;
+    }
+    getProfilingSAB() {
+        return this.profilingSAB;
+    }
+    registerView(view) {
+        this.views.set(view.id, view);
+        this.bumpManifest();
+    }
+    getViews() {
+        // Merge built-in views with custom ones (custom takes precedence on id collision)
+        const merged = new Map();
+        BUILTIN_VIEW_DESCRIPTORS.forEach((v) => { merged.set(v.id, v); ; });
+        for (const v of this.views.values())
+            merged.set(v.id, v);
+        return Array.from(merged.values()).sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+    }
+    getManifest() {
+        return {
+            panels: Array.from(this.panels.values()),
+            toggles: Array.from(this.toggles.values()),
+            dataFeeds: this.dataFeedNames.map((name, i) => ({
+                name,
+                feedIndex: i,
+                writeRateHz: this.dataFeeds.get(name)?.writeRateHz ?? 10,
+            })),
+            commands: Array.from(this.commands.keys()),
+            sabStats: Array.from(this.sabStats.values()),
+            manifestVersion: this.manifestVersion,
+        };
+    }
+    flushDataFeeds() {
+        // Works in any realm — writes to SAB if attached. The sim loop only
+        // calls this in the worker realm, but it's also used in tests.
+        if (!this.sab || !this.sabLayout || !this.sabU32 || !this.sabU8)
+            return;
+        const now = performance.now();
+        for (const feed of this.dataFeeds.values()) {
+            // writeRateHz = 0 means "flush every call" (no rate limiting)
+            const intervalMs = feed.writeRateHz > 0 ? 1000 / feed.writeRateHz : 0;
+            // Always write the first time; after that, respect rate limiting
+            if (feed.hasWritten && intervalMs > 0 && (now - feed.lastWriteMs) < intervalMs)
+                continue;
+            feed.lastWriteMs = now;
+            feed.hasWritten = true;
+            try {
+                const result = feed.fn();
+                const json = JSON.stringify(result);
+                const jsonBytes = new TextEncoder().encode(json);
+                const blobOffset = this.sabLayout.feedBlobOffset(feed.feedIndex);
+                const maxBytes = this.sabLayout.feedBlobBytes;
+                if (jsonBytes.length > maxBytes) {
+                    // Truncate: write a marker so the renderer knows it's truncated
+                    this.sabU32[this.sabLayout.feedOffset(feed.feedIndex) / 4] = 0xFFFFFFFF;
+                    continue;
+                }
+                // Write length (in bytes) followed by the JSON blob
+                this.sabU32[this.sabLayout.feedOffset(feed.feedIndex) / 4] = jsonBytes.length;
+                this.sabU8.set(jsonBytes, blobOffset);
+            }
+            catch (e) {
+                // Write 0 length = "error/unavailable"
+                this.sabU32[this.sabLayout.feedOffset(feed.feedIndex) / 4] = 0;
+            }
+        }
+    }
+    /** Read a data feed from the SAB (renderer-side). Returns parsed JSON or null. */
+    readDataFeed(feedIndex) {
+        if (!this.sab || !this.sabLayout || !this.sabU32 || !this.sabU8)
+            return null;
+        const entryOffset = this.sabLayout.feedOffset(feedIndex) / 4;
+        const lengthBytes = this.sabU32[entryOffset];
+        if (lengthBytes === 0 || lengthBytes === 0xFFFFFFFF)
+            return null;
+        const blobOffset = this.sabLayout.feedBlobOffset(feedIndex);
+        const jsonBytes = this.sabU8.subarray(blobOffset, blobOffset + lengthBytes);
+        try {
+            const json = new TextDecoder().decode(jsonBytes);
+            return JSON.parse(json);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Read a SAB stat (renderer-side). */
+    readSABStat(name) {
+        const stat = this.sabStats.get(name);
+        if (!stat || !this.sab || !this.sabLayout || !this.sabU32 || !this.sabF32 || !this.sabI32)
+            return null;
+        const byteOffset = this.sabLayout.statsBaseOffset + stat.offset;
+        switch (stat.type) {
+            case "u32": return this.sabU32[byteOffset / 4];
+            case "f32": return this.sabF32[byteOffset / 4];
+            case "i32": return this.sabI32[byteOffset / 4];
+        }
+    }
+    /** Call a command (renderer-side, for worker realm commands forwarded via RPC). */
+    callCommand(name, args) {
+        const fn = this.commands.get(name);
+        if (!fn)
+            throw new Error(`Unknown devtools command: ${name}`);
+        return fn(...args);
+    }
+    /** Get data feed function (main realm — called directly). */
+    getDataFeedFn(name) {
+        return this.dataFeeds.get(name)?.fn ?? null;
+    }
+    /** Get SAB stat names (for renderer to wire read methods). */
+    getSABStatNames() {
+        return Array.from(this.sabStats.keys());
+    }
+    clear() {
+        this.panels.clear();
+        this.toggles.clear();
+        this.dataFeeds.clear();
+        this.dataFeedNames = [];
+        this.commands.clear();
+        this.sabStats.clear();
+        this.views.clear();
+        this.profilingSAB = null;
+        this.bumpManifest();
+    }
+    bumpManifest() {
+        this.manifestVersion++;
+        if (this.sabU32) {
+            this.sabU32[0] = this.manifestVersion;
+            this.sabU32[1] = this.dataFeedNames.length;
+        }
+    }
+}
+// --- Singleton ---
+const _devtools = new DevToolsAPIImpl(DEVTOOLS_REALM);
+/**
+ * Unified DevTools API. Auto-detects realm (main vs worker) and chooses
+ * the appropriate transport for data feeds (direct call vs SAB) and
+ * commands (direct call vs RPC forwarding).
+ *
+ * Plugins import this and call registerPanel/registerDataFeed/registerCommand.
+ * The same code works in both realms.
+ */
+export const devtools = _devtools;
+/**
+ * DI token for the DevTools API. `initDevTools()` provides this into the
+ * renderer module host (`provideExternal`), so engine libraries can declare
+ * it in `requires`/inject it via `ctx.injectOptional(DevToolsAPITok)` instead
+ * of importing the `devtools` singleton — keeps library code testable and
+ * realm-correct.
+ */
+export const DevToolsAPITok = resourceToken("devtools:api");
+/** @internal — exposed for the renderer bridge to access impl methods. */
+export const _devtoolsImpl = _devtools;

package/dist/modules/devtools/src/asset-utils.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// Asset Utilities — generic model/texture/buffer fetching and cache management
+// Games provide URL maps via IAssetUrlMaps; these utilities handle fetching.
+// ============================================================================
+const MAX_BUFFER_CACHE_ENTRIES = 20;
+const MAX_THUMBNAIL_CACHE_ENTRIES = 50;
+export const bufferCache = new Map();
+export const thumbnailCache = new Map();
+export function syncFetchArrayBuffer(url) {
+    const cached = bufferCache.get(url);
+    if (cached) {
+        bufferCache.delete(url);
+        bufferCache.set(url, cached);
+        return cached;
+    }
+    const xhr = new XMLHttpRequest();
+    xhr.open("GET", url, false);
+    xhr.overrideMimeType("text/plain; charset=x-user-defined");
+    xhr.send();
+    if (xhr.status !== 200)
+        return null;
+    const text = xhr.responseText;
+    const buffer = new ArrayBuffer(text.length);
+    const bytes = new Uint8Array(buffer);
+    for (let i = 0; i < text.length; i++) {
+        bytes[i] = text.charCodeAt(i) & 0xff;
+    }
+    while (bufferCache.size >= MAX_BUFFER_CACHE_ENTRIES) {
+        const oldestKey = bufferCache.keys().next().value;
+        if (oldestKey === undefined)
+            break;
+        bufferCache.delete(oldestKey);
+    }
+    bufferCache.set(url, buffer);
+    return buffer;
+}
+export function evictThumbnailCache() {
+    while (thumbnailCache.size >= MAX_THUMBNAIL_CACHE_ENTRIES) {
+        const oldestKey = thumbnailCache.keys().next().value;
+        if (oldestKey === undefined)
+            break;
+        thumbnailCache.delete(oldestKey);
+    }
+}
+export function findMTLForOBJ(filename, buffer, urlMaps) {
+    const text = new TextDecoder().decode(buffer);
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.toLowerCase().startsWith("mtllib")) {
+            const parts = trimmed.split(/\s+/);
+            if (parts.length >= 2) {
+                const mtlName = parts[1];
+                const mtlUrl = urlMaps.mtlUrlMap.get(mtlName.toLowerCase());
+                if (mtlUrl) {
+                    return syncFetchArrayBuffer(mtlUrl);
+                }
+            }
+        }
+    }
+    const baseName = filename.replace(/\.[^.]+$/, "").toLowerCase();
+    const mtlUrl = urlMaps.mtlUrlMap.get(baseName + ".mtl");
+    if (mtlUrl) {
+        return syncFetchArrayBuffer(mtlUrl);
+    }
+    return null;
+}
+export function findBinForGLTF(filename, buffer, urlMaps) {
+    try {
+        const json = JSON.parse(new TextDecoder().decode(buffer));
+        if (json.buffers && json.buffers[0] && json.buffers[0].uri) {
+            const uri = json.buffers[0].uri;
+            if (!uri.startsWith("data:")) {
+                const binName = uri.split("/").pop() ?? uri;
+                const binUrl = urlMaps.binUrlMap.get(binName.toLowerCase());
+                if (binUrl) {
+                    return syncFetchArrayBuffer(binUrl);
+                }
+            }
+        }
+    }
+    catch {
+        // Not valid JSON or no buffers
+    }
+    const baseName = filename.replace(/\.[^.]+$/, "").toLowerCase();
+    const binUrl = urlMaps.binUrlMap.get(baseName + ".bin");
+    if (binUrl) {
+        return syncFetchArrayBuffer(binUrl);
+    }
+    return null;
+}
+export async function asyncFetchArrayBuffer(url) {
+    try {
+        const resp = await fetch(url);
+        if (!resp.ok)
+            return null;
+        return await resp.arrayBuffer();
+    }
+    catch {
+        return null;
+    }
+}