@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/modules/devtools/src/material-stats-panel.js

@@ -0,0 +1,171 @@
+// ============================================================================
+// createMaterialStatsPanelExtension — reusable DevTools "Materials" tab for
+// any game using the unified material system.
+//
+// Shows:
+//   - Registered material count, material types breakdown
+//   - Variant cache size, LRU hits/misses
+//   - Shader graph node count, compiled WGSL size
+//   - GPU texture count/bytes (from GPUResourceTracker)
+//
+// Gated by requiredMethods: ["getMaterialStats"]. The framework auto-provides
+// getMaterialStats() from the renderer's MaterialLibrary / variant cache
+// (feature-detected in createDevToolsRendererAdapter or registered via
+// devtools.registerDataFeed).
+// ============================================================================
+export function createMaterialStatsPanelExtension(opts = {}) {
+    const tabLabel = opts.tabLabel ?? "Materials";
+    const tabTooltip = opts.tabTooltip ?? "Material system stats (library, variants, GPU textures)";
+    const order = opts.order ?? 25;
+    const hasExtra = typeof opts.extraRows === "function";
+    const extraRowsSrc = hasExtra ? opts.extraRows.toString() : "null";
+    const html = `
+<div class="panel-header">
+  <h3>Materials</h3>
+  <span id="mat-status-badge" class="perf-status">Waiting for data...</span>
+</div>
+<div id="mat-stats-panel">
+  <div class="debug-section">
+    <h4>Library</h4>
+    <div id="mat-library-grid" class="debug-grid"></div>
+  </div>
+  <div class="debug-section">
+    <h4>Variants</h4>
+    <div id="mat-variants-grid" class="debug-grid"></div>
+  </div>
+  <div class="debug-section">
+    <h4>GPU Textures</h4>
+    <div id="mat-textures-grid" class="debug-grid"></div>
+  </div>
+  <div class="debug-section">
+    <h4>Shader Graph</h4>
+    <div id="mat-graph-grid" class="debug-grid"></div>
+  </div>
+</div>
+`;
+    const css = `
+#mat-stats-panel {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px 12px;
+}
+#mat-stats-panel .debug-section {
+  margin-bottom: 12px;
+}
+#mat-stats-panel .debug-section h4 {
+  font-size: 12px;
+  color: #569cd6;
+  margin: 8px 0 4px 0;
+  border-bottom: 1px solid #333;
+  padding-bottom: 2px;
+}
+#mat-status-badge.running { color: #98c379; }
+#mat-status-badge.empty { color: #e5c07b; }
+`;
+    const script = `
+(function(DevToolsPanel) {
+  var callInspector = DevToolsPanel.callInspector;
+  var evalInPage = DevToolsPanel.evalInPage;
+  var escapeHtml = DevToolsPanel.escapeHtml;
+  var fmtVal = DevToolsPanel.fmtVal;
+  var debugGridHtml = DevToolsPanel.debugGridHtml;
+
+  var extraRowsFn = ${extraRowsSrc};
+
+  function refreshMatStats() {
+    var libEl = document.getElementById("mat-library-grid");
+    var varEl = document.getElementById("mat-variants-grid");
+    var texEl = document.getElementById("mat-textures-grid");
+    var graphEl = document.getElementById("mat-graph-grid");
+    var statusEl = document.getElementById("mat-status-badge");
+
+    evalInPage(
+      "window.__sceneInspector ? JSON.stringify(window.__sceneInspector.getMaterialStats()) : null",
+      function (result, err) {
+        if (err || !result) {
+          if (libEl) libEl.innerHTML = '<div class="debug-label">Not available</div>';
+          if (statusEl) { statusEl.textContent = "Not available"; statusEl.className = "perf-status"; }
+          return;
+        }
+        try {
+          var s = JSON.parse(result);
+          if (!s) {
+            if (libEl) libEl.innerHTML = '<div class="debug-label">Not available</div>';
+            return;
+          }
+
+          // Library stats
+          var libRows = [
+            ["Registered", s.library?.count ?? 0],
+            ["Types", s.library?.types?.join(", ") ?? "—"],
+          ];
+          if (libEl) libEl.innerHTML = debugGridHtml(libRows);
+
+          // Variant stats
+          var varRows = [
+            ["Cached Pipelines", s.variants?.cachedPipelines ?? 0],
+            ["Max Pipelines", s.variants?.maxPipelines ?? 0],
+            ["LRU Hits", s.variants?.lruHits ?? 0],
+            ["LRU Misses", s.variants?.lruMisses ?? 0],
+            ["Permutation Count", s.variants?.permutationCount ?? 0],
+          ];
+          if (varEl) varEl.innerHTML = debugGridHtml(varRows);
+
+          // GPU textures
+          var texRows = [
+            ["Texture Count", s.textures?.count ?? 0],
+            ["Texture Memory", fmtVal((s.textures?.bytes ?? 0) / 1048576, 1) + " MB"],
+            ["Bindless Entries", s.textures?.bindlessEntries ?? 0],
+          ];
+          if (texEl) texEl.innerHTML = debugGridHtml(texRows);
+
+          // Shader graph
+          var graphRows = [
+            ["Graph Materials", s.graph?.materialCount ?? 0],
+            ["Total Nodes", s.graph?.totalNodes ?? 0],
+            ["Total Connections", s.graph?.totalConnections ?? 0],
+            ["Compiled WGSL Size", fmtVal((s.graph?.compiledWgslBytes ?? 0) / 1024, 1) + " KB"],
+          ];
+          if (graphEl) graphEl.innerHTML = debugGridHtml(graphRows);
+
+          // Extra rows
+          if (extraRowsFn && s) {
+            try {
+              var extra = extraRowsFn(s);
+              if (extra && extra.length) {
+                var extraHtml = debugGridHtml(extra);
+                if (graphEl) graphEl.innerHTML += extraHtml;
+              }
+            } catch (e) { /* ignore */ }
+          }
+
+          if (statusEl) {
+            var count = s.library?.count ?? 0;
+            statusEl.textContent = count > 0 ? count + " materials" : "No materials";
+            statusEl.className = "perf-status " + (count > 0 ? "running" : "empty");
+          }
+        } catch (e) {
+          if (libEl) libEl.innerHTML = '<div class="debug-label">Error: ' + escapeHtml(String(e)) + '</div>';
+        }
+      }
+    );
+  }
+
+  return {
+    onActivate: function () { refreshMatStats(); },
+    onRefresh: refreshMatStats,
+    onDeactivate: function () {},
+  };
+})
+`;
+    return {
+        id: "material-stats",
+        tabLabel,
+        tabTooltip,
+        order,
+        requiredMethods: ["getMaterialStats"],
+        html,
+        css,
+        script,
+    };
+}

package/dist/modules/devtools/src/profiling-bridge.js

@@ -0,0 +1,288 @@
+// ============================================================================
+// ProfilingBridge — renderer-side bridge that wires the profiling system into
+// the devtools host.
+//
+// Responsibilities:
+//   1. Allocate the global ProfilingSAB (shared with all workers + the
+//      devtools host).
+//   2. Create a renderer-side WarningEngine + EventLoopMonitor + TraceEventWriter.
+//   3. Drain the warning ring from the ProfilingSAB each frame + merge with
+//      renderer-side warnings → emit toasts + forward to onWarning callbacks.
+//   4. Wire auto-trace: when a warning with autoTrace config fires, start
+//      recording with the in-engine TraceEventWriter (auto-stopping after
+//      the rule's configured duration).
+//   5. Wire the TelemetryCollector (pass timings, system timings) into the
+//      ProfilingSAB so the devtools profiling views can read them.
+//   6. Register the 10 built-in view descriptors with the devtools API.
+//
+// Created by initDevTools() when profiling is enabled.
+// ============================================================================
+import { allocateProfilingSAB, claimSlot, computeProfilingSABLayout, DEFAULT_RENDERER_WARNING_RULES, EventLoopMonitor, fnv1a32, PROFILING_IOPS_RING_CAP, PROFILING_MAX_SLOTS, PROFILING_STRING_TABLE_CAP, PROFILING_WARNING_RING_CAP, ProfilingSABReader, ProfilingSABWriter, TraceEventWriter, WarningEngine } from "@downdraft/engine/profiling";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { devtools } from "./api.js";
+import { BUILTIN_VIEW_DESCRIPTORS } from "./debug-view-descriptors.js";
+const log = createLogger("info");
+/** Only the in-engine TraceEventWriter exists on the native host.
+ *  Normalize instead of failing so untyped callers (MCP tool args, saved
+ *  configs) degrade gracefully. */
+function normalizeTraceSource(source) {
+    if (source !== "in-engine") {
+        log.warn("profiling-bridge", `traceSource "${source}" is unsupported — using the in-engine trace writer`);
+        return "in-engine";
+    }
+    return source;
+}
+export class ProfilingBridge {
+    profilingSAB;
+    layout;
+    reader;
+    writer = null;
+    rendererSlot = -1;
+    tickCount = 0;
+    cpuTimeStart = 0;
+    lastFrameMs = 0;
+    warningEngine;
+    eventLoopMonitor;
+    traceEventWriter;
+    traceSource;
+    autoTraceActive = false;
+    autoTraceWarningId = null;
+    /** Result of the most recent auto-trace recording (for tooling/MCP). */
+    lastAutoTrace = null;
+    lastSnapshot = null;
+    warningCallbacks = new Set();
+    seenWarningIds = new Set(); // dedup across workers
+    constructor(opts = {}) {
+        this.layout = opts.sharedSAB?.layout ?? computeProfilingSABLayout(opts.maxSlots ?? PROFILING_MAX_SLOTS, opts.iopsRingCap ?? PROFILING_IOPS_RING_CAP, opts.warningRingCap ?? PROFILING_WARNING_RING_CAP, opts.stringTableCap ?? PROFILING_STRING_TABLE_CAP);
+        const allocated = opts.sharedSAB ?? allocateProfilingSAB(this.layout.maxSlots, this.layout.iopsRingCap, this.layout.warningRingCap, this.layout.stringTableCap);
+        this.profilingSAB = allocated.sab;
+        this.reader = new ProfilingSABReader(this.profilingSAB, this.layout);
+        this.warningEngine = new WarningEngine(null); // renderer writes warnings directly
+        this.warningEngine.setWorkerTag(0); // renderer tag = 0
+        this.warningEngine.setAutoTraceAvailable(true); // in-engine writer is always available
+        // Register default renderer warning rules
+        DEFAULT_RENDERER_WARNING_RULES.forEach((rule) => {
+            this.warningEngine.addRule(rule);
+        });
+        // Event loop monitor (renderer) — writer is set after slot claim below
+        if (opts.enableEventLoopMonitor !== false) {
+            this.eventLoopMonitor = new EventLoopMonitor({
+                warningEngine: this.warningEngine,
+                expectedFrameMs: opts.expectedFrameMs ?? 16.67,
+            });
+            this.eventLoopMonitor.start();
+        }
+        else {
+            this.eventLoopMonitor = null;
+        }
+        this.traceEventWriter = new TraceEventWriter();
+        this.traceSource = normalizeTraceSource(opts.traceSource ?? "in-engine");
+        // Attach the ProfilingSAB to the devtools API
+        devtools.attachProfilingSAB(this.profilingSAB);
+        // Register built-in view descriptors
+        BUILTIN_VIEW_DESCRIPTORS.forEach((view) => {
+            devtools.registerView(view);
+        });
+        // Claim a renderer slot so the profiler overlay always has at least one
+        // slot to display (renderer heap/CPU/GC metrics).
+        const rendererTag = fnv1a32("renderer");
+        this.rendererSlot = claimSlot(this.profilingSAB, this.layout, rendererTag, 0 /* RUNTIME_JS */, "renderer");
+        if (this.rendererSlot >= 0) {
+            this.writer = new ProfilingSABWriter(this.profilingSAB, this.layout, this.rendererSlot);
+            // Attach the writer to the event loop monitor so it writes event loop data
+            if (this.eventLoopMonitor) {
+                this.eventLoopMonitor.writer = this.writer;
+            }
+        }
+        this.cpuTimeStart = performance.now();
+        this.lastFrameMs = performance.now();
+    }
+    /** The global ProfilingSAB — share this with all workers + the devtools host. */
+    getProfilingSAB() {
+        return this.profilingSAB;
+    }
+    /** The SAB layout (needed by workers to claim slots). */
+    getProfilingLayout() {
+        return this.layout;
+    }
+    /** Serializable layout params (safe to pass via postMessage / structured clone).
+     *  The worker reconstructs the full layout via computeProfilingSABLayout(...). */
+    getLayoutParams() {
+        return {
+            maxSlots: this.layout.maxSlots,
+            iopsRingCap: this.layout.iopsRingCap,
+            warningRingCap: this.layout.warningRingCap,
+            stringTableCap: this.layout.stringTableCap,
+        };
+    }
+    /** The renderer-side warning engine. Add custom rules via this. */
+    getWarningEngine() {
+        return this.warningEngine;
+    }
+    /** The renderer-side event-loop monitor. */
+    getEventLoopMonitor() {
+        return this.eventLoopMonitor;
+    }
+    /** The trace event writer (for in-engine trace export). */
+    getTraceEventWriter() {
+        return this.traceEventWriter;
+    }
+    /** Subscribe to warnings (merged from all workers + renderer). */
+    onWarning(cb) {
+        this.warningCallbacks.add(cb);
+        return () => { this.warningCallbacks.delete(cb); };
+    }
+    /** Set the trace source for auto-trace. */
+    setTraceSource(source) {
+        this.traceSource = normalizeTraceSource(source);
+    }
+    /** Start a manual trace recording. */
+    startRecording() {
+        this.traceEventWriter.startRecording();
+    }
+    /** Stop recording and return the trace data. */
+    async stopRecording() {
+        const result = this.traceEventWriter.stopRecording();
+        return { ...result, source: this.traceSource };
+    }
+    /** The last completed auto-trace payload, if any. */
+    getLastAutoTrace() {
+        return this.lastAutoTrace;
+    }
+    /** Check if currently recording. */
+    isRecording() {
+        return this.traceEventWriter.isRecording();
+    }
+    /**
+     * Called each frame from the render loop. Drains the warning ring from the
+     * ProfilingSAB, merges with renderer-side warnings, fires auto-trace if
+     * needed, and ingests the snapshot into the TraceEventWriter if recording.
+     */
+    tick() {
+        // Record frame start for event loop monitoring
+        this.eventLoopMonitor?.recordFrameStart();
+        // Write renderer metrics to the ProfilingSAB (heap, CPU, GC, tick count)
+        this.tickCount++;
+        if (this.writer) {
+            const mem = performance.memory; // performance.memory is non-standard; undefined outside Blink
+            const cpuMs = performance.now() - this.cpuTimeStart;
+            const now = performance.now();
+            const frameMs = now - this.lastFrameMs;
+            this.lastFrameMs = now;
+            // CPU% = actual rAF callback work time / wall-clock frame time.
+            // This is true utilization (0% when idle, ~4% when the renderer does
+            // minimal work), NOT "frame time as % of 60fps budget" which was
+            // always ~100% when called every frame.
+            const workMs = this.eventLoopMonitor?.getLastWorkMs() ?? 0;
+            const cpuPercent = frameMs > 0
+                ? Math.min(100, (workMs / frameMs) * 100)
+                : 0;
+            this.writer.writeThreadMetrics({
+                heapUsed: mem?.usedJSHeapSize ?? 0,
+                heapTotal: mem?.totalJSHeapSize ?? 0,
+                rss: mem?.jsHeapSizeLimit ?? 0,
+                cpuTimeMs: cpuMs,
+                cpuPercent,
+                gcPauseTotalUs: 0,
+                gcPauseCount: 0,
+                gcPauseMaxUs: 0,
+                tick: this.tickCount,
+                taskCount: 1,
+                taskLatencyP50Us: workMs * 1000,
+                taskLatencyP95Us: workMs * 1000,
+                taskLatencyP99Us: workMs * 1000,
+                taskLatencyMaxUs: workMs * 1000,
+            });
+        }
+        // Read the latest profiling snapshot
+        const snapshot = this.reader.readSnapshot();
+        this.lastSnapshot = snapshot;
+        // Record frame end for event loop monitoring (writes event loop block)
+        this.eventLoopMonitor?.recordFrameEnd();
+        // Ingest into trace event writer if recording
+        if (this.traceEventWriter.isRecording()) {
+            this.traceEventWriter.ingestSnapshot(snapshot);
+        }
+        // Drain warning ring — merge worker warnings into the renderer's callback set
+        for (let _i = 0, _it = snapshot.warnings, _n = _it.length; _i < _n; _i++) {
+            const w = _it[_i];
+            // Dedup by ruleIdHash + ts (a warning may appear in multiple reads)
+            const warningId = `${w.ruleIdHash}:${w.ts}`;
+            if (this.seenWarningIds.has(warningId))
+                continue;
+            this.seenWarningIds.add(warningId);
+            // Keep the set from growing unbounded
+            if (this.seenWarningIds.size > 1000) {
+                this.seenWarningIds.clear();
+                this.seenWarningIds.add(warningId);
+            }
+            // Reconstruct the warning record for callbacks
+            const record = {
+                ruleId: "",
+                ruleIdHash: w.ruleIdHash,
+                severity: w.severity,
+                metricKind: w.metricKind,
+                value: w.value,
+                threshold: w.threshold,
+                workerTag: w.workerTag,
+                ts: w.ts,
+                autoTraceFired: w.autoTraceFired,
+            };
+            const ctx = {
+                workerTag: w.workerTag,
+                runtime: 0,
+                rule: { id: "", severity: w.severity, metric: w.metricKind, compare: ">", threshold: w.threshold },
+                autoTraceAvailable: false,
+            };
+            // Fire callbacks
+            for (const cb of this.warningCallbacks.values()) {
+                try {
+                    cb(record, ctx);
+                }
+                catch (err) {
+                    log.error("profiling-bridge", `Warning callback error: ${err}`);
+                }
+            }
+            // Auto-trace: if this warning has autoTrace and we're not already tracing,
+            // start recording — then auto-stop after the rule's configured duration.
+            // Without the stop the writer ingests a snapshot per frame forever and
+            // the event array wedges the main thread.
+            if (w.autoTraceFired && !this.autoTraceActive) {
+                this.autoTraceActive = true;
+                this.autoTraceWarningId = warningId;
+                this.startRecording();
+                log.warn("profiling-bridge", `Auto-trace started due to warning ${w.ruleIdHash}`);
+                const rule = this.warningEngine.getRules().find((r) => fnv1a32(r.id) === w.ruleIdHash);
+                const durationMs = rule?.autoTrace?.durationMs ?? 3000;
+                const timer = setTimeout(() => {
+                    this.autoTraceActive = false;
+                    this.autoTraceWarningId = null;
+                    void this.stopRecording().then((result) => {
+                        this.lastAutoTrace = result;
+                        log.info("profiling-bridge", `Auto-trace captured ${result.bytes} bytes`);
+                    }).catch(() => { });
+                }, durationMs);
+                timer.unref?.();
+            }
+        }
+        // Record frame start/end for the event-loop monitor
+        this.eventLoopMonitor?.recordFrameStart();
+    }
+    /** Called at the end of the render frame (after render work completes). */
+    endFrame() {
+        this.eventLoopMonitor?.recordFrameEnd();
+    }
+    /** Get the latest profiling snapshot (for the profiler overlay to read). */
+    getSnapshot() {
+        return this.lastSnapshot;
+    }
+    /** Dispose — stop monitors + clear state. */
+    dispose() {
+        this.eventLoopMonitor?.dispose();
+        this.warningEngine.clearCallbacks();
+        this.warningEngine.clearRules();
+        this.warningCallbacks.clear();
+        this.seenWarningIds.clear();
+        this.lastSnapshot = null;
+    }
+}

package/dist/modules/devtools/src/profiling-hooks.js

@@ -0,0 +1,63 @@
+// ============================================================================
+// wireProfilingBridge — shared profiling wiring.
+//
+// Generalized from to-the-ocean's main.tsx + sandjongg's game-module.tsx.
+//
+// wireProfilingBridge() connects the ProfilingBridge (created by
+// initDevTools({ profiling: true }) and exposed via
+// window.__sceneInspector.__getProfilingBridge()) into the render loop:
+//   - wraps the renderer's beforeFrame/afterFrame callbacks with
+//     bridge.tick() / bridge.endFrame()
+//   - shares the ProfilingSAB with the given worker hosts so each can claim
+//     a slot (worker-side profiling prelude patches prototypes + warning
+//     engine + event-loop monitor)
+// ============================================================================
+function getProfilingBridge(explicit) {
+    if (explicit)
+        return explicit;
+    return window.__sceneInspector?.__getProfilingBridge?.() ?? null;
+}
+/**
+ * Wire the ProfilingBridge into the renderer's frame callbacks and share the
+ * ProfilingSAB with the given worker hosts. Returns the bridge, or null when
+ * profiling isn't enabled — callers can skip their profiling-only work.
+ */
+export function wireProfilingBridge(opts) {
+    const bridge = getProfilingBridge(opts.bridge);
+    if (!bridge)
+        return null;
+    const { renderer } = opts;
+    // Guard against double-wiring: bootstrapGame auto-wires the bridge when
+    // `devtools.profiling` is enabled, but older games call this themselves —
+    // a second wrap would tick/endFrame twice per frame. Worker attach below
+    // still runs every call (the worker-side attach is idempotent).
+    const marker = "__ddProfilingWired";
+    const rend = renderer;
+    if (!rend[marker]) {
+        rend[marker] = true;
+        const prevCallbacks = renderer.getCallbacks?.() ?? renderer.callbacks ?? {};
+        renderer.setCallbacks({
+            ...prevCallbacks,
+            beforeFrame: (dt, elapsedTime) => {
+                bridge.tick();
+                prevCallbacks.beforeFrame?.(dt, elapsedTime);
+            },
+            afterFrame: (dt, elapsedTime) => {
+                prevCallbacks.afterFrame?.(dt, elapsedTime);
+                bridge.endFrame();
+            },
+        });
+    }
+    // Share the ProfilingSAB with each worker host so it can claim a slot.
+    const sab = bridge.getProfilingSAB();
+    const layout = bridge.getLayoutParams?.();
+    for (let _i = 0, _it = opts.workerHosts ?? [], _n = _it.length; _i < _n; _i++) {
+        const entry = _it[_i];
+        if (!entry)
+            continue;
+        const host = "attachProfilingSAB" in entry ? entry : entry.host;
+        const workerTag = "attachProfilingSAB" in entry ? undefined : entry.workerTag;
+        void host?.attachProfilingSAB(sab, { workerTag, layout });
+    }
+    return bridge;
+}

package/dist/modules/devtools/src/renderer-adapter.js

@@ -0,0 +1,61 @@
+// ============================================================================
+// createDevToolsRendererAdapter — auto-discovers the renderer's framework
+// capabilities via feature detection and builds an IDevToolsDataRenderer
+// with all available systems wired.
+//
+// Games pass their renderer instance; the adapter probes for gpuProfiler,
+// telemetryCollector, gpuResourceTracker, gcController, etc. and wires them.
+// No hand-rolled adapter objects needed.
+// ============================================================================
+/**
+ * Create an IDevToolsDataRenderer by feature-detecting the renderer's
+ * framework systems. Works with any renderer that exposes the standard
+ * GameRenderer fields (gpuProfiler, telemetryCollector, etc.) or the
+ * minimal { getFPS() } surface.
+ */
+export function createDevToolsRendererAdapter(renderer) {
+    return {
+        getFPS: () => {
+            return typeof renderer?.getFPS === "function" ? renderer.getFPS() : 0;
+        },
+        getGPUInfo: renderer?.gpuProfiler
+            ? () => renderer.gpuProfiler.getGPUInfo?.() ?? null
+            : renderer?.getGPUInfo ? () => renderer.getGPUInfo() : undefined,
+        getGPUErrors: renderer?.gpuProfiler
+            ? () => renderer.gpuProfiler.getGPUErrors?.() ?? []
+            : renderer?.getGPUErrors ? () => renderer.getGPUErrors() : undefined,
+        clearGPUErrors: renderer?.gpuProfiler
+            ? () => renderer.gpuProfiler.clearGPUErrors?.()
+            : renderer?.clearGPUErrors ? () => renderer.clearGPUErrors() : undefined,
+        getFrameTelemetry: renderer?.telemetryCollector
+            ? () => renderer.telemetryCollector.getFrameTelemetry?.() ?? null
+            : renderer?.getFrameTelemetry ? () => renderer.getFrameTelemetry() : undefined,
+        getGPUResourceTracker: () => {
+            const tracker = renderer?.gpuResourceTracker ?? renderer?.getGPUResourceTracker?.();
+            return tracker ?? null;
+        },
+        getTelemetryCollector: () => {
+            const tc = renderer?.telemetryCollector ?? renderer?.getTelemetryCollector?.();
+            return tc ?? null;
+        },
+        getGPUProfiler: () => {
+            const p = renderer?.gpuProfiler ?? renderer?.getGPUProfiler?.();
+            return p ?? null;
+        },
+        getFrameGraph: renderer?.getFrameGraph
+            ? () => renderer.getFrameGraph()
+            : undefined,
+        setDebugMode: renderer?.setDebugMode
+            ? (enabled) => renderer.setDebugMode(enabled)
+            : undefined,
+        getGCStats: renderer?.gcController
+            ? () => renderer.gcController.getStats?.()
+            : renderer?.getGCStats ? () => renderer.getGCStats() : undefined,
+        setGCConfig: renderer?.gcController
+            ? (config) => renderer.gcController.setConfig?.(config)
+            : renderer?.setGCConfig ? (config) => renderer.setGCConfig(config) : undefined,
+        forceMajorGC: renderer?.gcController
+            ? () => renderer.gcController.forceMajorGC?.()
+            : renderer?.forceMajorGC ? () => renderer.forceMajorGC() : undefined,
+    };
+}