@downdraft/engine 0.0.0 → 0.1.1

package/modules/devtools/src/init.ts

@@ -0,0 +1,261 @@
+// ============================================================================
+// initDevTools — one-line DevTools wiring for games.
+//
+// Replaces the per-game boilerplate of:
+//   1. Creating an IDevToolsDataRenderer adapter
+//   2. Instantiating DevToolsDataBridge (or BaseSceneInspector)
+//   3. Calling init()
+//   4. Wiring sim stats provider, panel extensions, overlay toggles, etc.
+//
+// Also merges globally-registered panels/feeds/commands from the `devtools`
+// singleton (registered by plugins via ctx.devtools.registerPanel() etc.)
+// and from worker manifests (via syncWorkerManifests).
+//
+// Returns the bridge instance for games that need post-init calls
+// (e.g. to-the-ocean's sceneInspector.setSimBridge()).
+// ============================================================================
+
+import { _devtoolsImpl, devtools, DevToolsAPITok } from "./api";
+import { DevToolsDataBridge } from "./data-bridge";
+import { ProfilingBridge, type ProfilingBridgeOptions } from "./profiling-bridge";
+import { createDevToolsRendererAdapter } from "./renderer-adapter";
+import { BaseSceneInspector } from "./scene-inspector";
+import type {
+    IAssetResolver,
+    IDebugModeProvider,
+    IDebugOverlayProvider,
+    IDevToolsOverlayToggle,
+    IDevToolsPanelExtension,
+    IDevToolsRenderer,
+    IPerformanceMetricsProvider,
+    ISimStatsProvider,
+} from "./types";
+import { syncWorkerManifests, type WorkerSyncEntry } from "./worker-sync";
+
+export interface InitDevToolsOptions {
+  // --- Panel extensions & toggles (game-declared) ---
+  panels?: IDevToolsPanelExtension[];
+  overlayToggles?: IDevToolsOverlayToggle[];
+
+  // --- Providers (game-specific) ---
+  simStatsProvider?: ISimStatsProvider & { start?: () => void; stop?: () => void };
+  debugOverlayProvider?: IDebugOverlayProvider;
+  debugModeProvider?: IDebugModeProvider;
+  performanceMetricsProvider?: IPerformanceMetricsProvider;
+  assetResolver?: IAssetResolver;
+
+  // --- Scene inspector (3D games) ---
+  /** Use BaseSceneInspector instead of DevToolsDataBridge. Auto-detected if renderer implements IDevToolsRenderer. */
+  sceneInspector?: boolean;
+  /** Custom bridge class (extends BaseSceneInspector). If provided, sceneInspector is implied. */
+  bridgeClass?: new () => BaseSceneInspector;
+
+  // --- Worker sync ---
+  /** Worker hosts to sync manifests from. Data feeds read from SAB, commands forwarded via worker RPC. */
+  workerHosts?: WorkerSyncEntry[];
+
+  // --- Renderer ---
+  /** The renderer instance. If omitted, uses an empty adapter (for testing). */
+  renderer?: any;
+
+  // --- Profiling ---
+  /** Enable the profiling system (ProfilingSAB + ProfilingBridge + built-in views).
+   *  When true, a ProfilingBridge is created and the ProfilingSAB is shared
+   *  with all workers + the devtools host. Default: false. */
+  profiling?: boolean | ProfilingBridgeOptions;
+}
+
+/**
+ * Initialize DevTools with one call. Creates the bridge, wires all providers,
+  merges globally-registered panels/feeds/commands, syncs worker manifests,
+ * and exposes the API on window.__sceneInspector.
+ *
+ * Returns the bridge instance.
+ */
+export async function initDevTools(renderer: any, options: InitDevToolsOptions = {}): Promise<DevToolsDataBridge> {
+  // 1. Build the renderer adapter (auto-discovers framework capabilities)
+  const adapter = createDevToolsRendererAdapter(renderer);
+
+  // 2. Determine bridge type
+  const useSceneInspector = options.sceneInspector
+    || !!options.bridgeClass
+    || isSceneRenderer(renderer);
+
+  // 3. Register game-declared panels/toggles into the global registry
+  //    (these merge with plugin-registered ones)
+  if (options.panels) {
+    options.panels.forEach((panel) => {
+      devtools.registerPanel(panel);
+    });
+  }
+  if (options.overlayToggles) {
+    options.overlayToggles.forEach((toggle) => {
+      devtools.registerOverlayToggle(toggle);
+    });
+  }
+
+  // 4. Sync worker manifests (fetches panels/feeds/commands from sim workers)
+  if (options.workerHosts && options.workerHosts.length > 0) {
+    await syncWorkerManifests(options.workerHosts);
+  }
+
+  // 4b. Inject devtools into the renderer's plugin host so renderer plugins
+  //     can self-register via ctx.devtools.register*(...).
+  const rendererModuleHost = renderer?.getRendererModuleHost?.();
+  if (rendererModuleHost && typeof rendererModuleHost.setDevToolsAPI === "function") {
+    rendererModuleHost.setDevToolsAPI(devtools);
+  }
+  // Also provide the API as a DI token so engine libraries can inject it
+  // (ctx.injectOptional(DevToolsAPITok)) instead of importing the singleton.
+  if (rendererModuleHost && typeof rendererModuleHost.provideExternal === "function") {
+    rendererModuleHost.provideExternal("devtools", DevToolsAPITok, devtools);
+  }
+
+  // 5. Create the bridge
+  let bridge: DevToolsDataBridge;
+  if (useSceneInspector) {
+    const BridgeClass = (options.bridgeClass ?? BaseSceneInspector) as new () => BaseSceneInspector;
+    bridge = new BridgeClass();
+    (bridge as BaseSceneInspector).init(renderer as IDevToolsRenderer);
+  } else {
+    bridge = new DevToolsDataBridge();
+    bridge.init(adapter);
+  }
+
+  // 6. Wire providers
+  if (options.simStatsProvider) {
+    wireSimStatsProvider(bridge, options.simStatsProvider);
+  }
+  if (options.debugOverlayProvider) {
+    wireDebugOverlayProvider(bridge, options.debugOverlayProvider);
+  }
+  if (options.debugModeProvider) {
+    wireDebugModeProvider(bridge, options.debugModeProvider);
+  }
+  if (options.performanceMetricsProvider) {
+    wirePerformanceMetricsProvider(bridge, options.performanceMetricsProvider);
+  }
+
+  // 7. Merge globally-registered panels/toggles/feeds/commands into the bridge
+  //    The bridge's getPanelExtensions()/getOverlayToggles() already returns
+  //    game-declared ones; we augment the __sceneInspector API with
+  //    plugin-registered data feeds and commands.
+  mergeGlobalRegistrations(bridge);
+
+  // 8. Initialize the profiling system (if enabled)
+  if (options.profiling) {
+    const profilingOpts = typeof options.profiling === "object" ? options.profiling : {};
+    const profilingBridge = new ProfilingBridge(profilingOpts);
+    (bridge as any)._profilingBridge = profilingBridge;
+    // Expose the ProfilingSAB + views on __sceneInspector for the profiler overlay
+    const api = (window as any).__sceneInspector;
+    if (api) {
+      api.__getProfilingSAB = () => profilingBridge.getProfilingSAB();
+      api.__getProfilingBridge = () => profilingBridge;
+      api.__getViews = () => devtools.getViews();
+    }
+  }
+
+  return bridge;
+}
+
+// --- Helpers ---
+
+function isSceneRenderer(renderer: any): boolean {
+  if (!renderer) return false;
+  // Feature-detect: IDevToolsRenderer requires these methods
+  return typeof renderer.setGizmoPosition === "function"
+    && typeof renderer.uploadModel === "function";
+}
+
+function wireSimStatsProvider(bridge: DevToolsDataBridge, provider: ISimStatsProvider & { start?: () => void }): void {
+  // The bridge's getSimStatsProvider() is overridden via a closure hack:
+  // We store the provider on the bridge instance and override the protected method.
+  (bridge as any)._simStatsProvider = provider;
+  (bridge as any).getSimStatsProvider = () => provider;
+  // Start polling if the provider has a start() method (from createSimStatsProvider)
+  provider.start?.();
+}
+
+function wireDebugOverlayProvider(bridge: DevToolsDataBridge, provider: any): void {
+  (bridge as any)._debugOverlayProvider = provider;
+  (bridge as any).getDebugOverlayProvider = () => provider;
+}
+
+function wireDebugModeProvider(bridge: DevToolsDataBridge, provider: any): void {
+  (bridge as any)._debugModeProvider = provider;
+  (bridge as any).getDebugModeProvider = () => provider;
+}
+
+function wirePerformanceMetricsProvider(bridge: DevToolsDataBridge, provider: any): void {
+  (bridge as any)._performanceMetricsProvider = provider;
+  (bridge as any).getPerformanceMetricsProvider = () => provider;
+}
+
+/**
+ * Merge globally-registered panels, data feeds, and commands from the `devtools`
+ * singleton into the bridge's __sceneInspector API.
+ *
+ * - Panels: merged into getPanelExtensions() (game panels + plugin panels)
+ * - Data feeds: added as methods on __sceneInspector (called synchronously)
+ * - Commands: added as methods on __sceneInspector (forwarded to worker or called directly)
+ * - SAB stats: added as methods on __sceneInspector (read from SAB)
+ */
+function mergeGlobalRegistrations(bridge: DevToolsDataBridge): void {
+  const manifest = devtools.getManifest();
+
+  // Augment getPanelExtensions to merge global registry panels
+  const originalGetPanels = (bridge as any).getPanelExtensions?.bind(bridge);
+  (bridge as any).getPanelExtensions = (): IDevToolsPanelExtension[] => {
+    const gamePanels = originalGetPanels?.() ?? [];
+    // Merge: game panels take precedence on id collisions
+    const merged = new Map<string, IDevToolsPanelExtension>();
+    manifest.panels.forEach((p) => { merged.set(p.id, p);; });
+    gamePanels.forEach((p: any) => { merged.set(p.id, p);; });
+    return Array.from(merged.values()).sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+  };
+
+  // Augment getOverlayToggles to merge global registry toggles
+  const originalGetToggles = (bridge as any).getOverlayToggles?.bind(bridge);
+  (bridge as any).getOverlayToggles = (): IDevToolsOverlayToggle[] => {
+    const gameToggles = originalGetToggles?.() ?? [];
+    const merged = new Map<string, IDevToolsOverlayToggle>();
+    manifest.toggles.forEach((t) => { merged.set(t.id, t);; });
+    gameToggles.forEach((t: any) => { merged.set(t.id, t);; });
+    return Array.from(merged.values());
+  };
+
+  // Add data feed methods to the __sceneInspector API
+  // These are called synchronously by the panel via callInspector()
+  const api = (window as any).__sceneInspector;
+  if (api) {
+    for (let _i = 0, _it = manifest.dataFeeds, _n = _it.length; _i < _n; _i++) { const feed = _it[_i];
+      if (typeof api[feed.name] === "function") continue; // don't override game-provided
+      const feedName = feed.name;
+      api[feedName] = (): any => {
+        // Main realm: call the registered fn directly
+        const fn = _devtoolsImpl.getDataFeedFn(feedName);
+        if (fn) return fn();
+        // Worker realm: read from SAB
+        return _devtoolsImpl.readDataFeed(feed.feedIndex);
+      };
+    }
+
+    // Add command methods
+    for (let _i = 0, _it = manifest.commands, _n = _it.length; _i < _n; _i++) { const cmdName = _it[_i];
+      if (typeof api[cmdName] === "function") continue;
+      api[cmdName] = (...args: any[]): any => {
+        return _devtoolsImpl.callCommand(cmdName, args);
+      };
+    }
+
+    // Add SAB stat methods (get{Name} → number)
+    for (let _i = 0, _it = manifest.sabStats, _n = _it.length; _i < _n; _i++) { const stat = _it[_i];
+      const methodName = `get${stat.name.charAt(0).toUpperCase()}${stat.name.slice(1)}`;
+      if (typeof api[methodName] === "function") continue;
+      api[methodName] = (): number | null => {
+        return _devtoolsImpl.readSABStat(stat.name);
+      };
+    }
+  }
+}

package/modules/devtools/src/label-overlay.ts

@@ -0,0 +1,154 @@
+// ============================================================================
+// LabelOverlay — HTML-based billboard labels for dev mode
+// Generic DOM management + projection; game provides labels via ILabelProvider.
+// ============================================================================
+
+import { calculateViewProj, type RenderSurface } from "@downdraft/engine";
+import type { ILabelProvider } from "./types";
+
+interface LabelEntry {
+  el: HTMLDivElement;
+}
+
+const MAX_LABELS = 512;
+
+export class LabelOverlay {
+  private container: HTMLDivElement;
+  private labels: Map<string, LabelEntry> = new Map();
+  private active = false;
+  private canvas: HTMLCanvasElement;
+  private provider: ILabelProvider | null = null;
+
+  constructor(surface: RenderSurface) {
+    // DOM-overlay widget — the canvas/element members it touches
+    // (parentElement, 2d overlay canvas) are DOM-host concepts; on native
+    // they degrade to the compat stubs (display:none anyway).
+    const canvas = surface as unknown as HTMLCanvasElement;
+    this.canvas = canvas;
+    this.container = document.createElement("div");
+    this.container.className = "label-overlay";
+    this.container.style.cssText = `
+      position: absolute;
+      top: 0; left: 0;
+      width: 100%; height: 100%;
+      pointer-events: none;
+      overflow: hidden;
+      z-index: 0;
+      display: none;
+    `;
+    const parent = canvas.parentElement;
+    if (parent) {
+      parent.style.position = parent.style.position || "relative";
+      parent.appendChild(this.container);
+    } else {
+      document.body.appendChild(this.container);
+    }
+  }
+
+  setProvider(provider: ILabelProvider): void {
+    this.provider = provider;
+  }
+
+  setActive(active: boolean): void {
+    this.active = active;
+    this.container.style.display = active ? "block" : "none";
+    if (!active) {
+      this.clearLabels();
+    }
+  }
+
+  isActive(): boolean {
+    return this.active;
+  }
+
+  private clearLabels(): void {
+    for (const entry of this.labels.values()) {
+      entry.el.remove();
+    }
+    this.labels.clear();
+  }
+
+  private getOrCreateLabel(key: string): HTMLDivElement | null {
+    let entry = this.labels.get(key);
+    if (entry) return entry.el;
+
+    if (this.labels.size >= MAX_LABELS) return null;
+
+    const el = document.createElement("div");
+    el.className = "dev-label";
+    el.style.cssText = `
+      position: absolute;
+      font-family: monospace;
+      font-size: 11px;
+      color: #fff;
+      background: rgba(0, 0, 0, 0.65);
+      border-radius: 3px;
+      padding: 1px 5px;
+      white-space: nowrap;
+      pointer-events: none;
+      transform: translate(-50%, -100%);
+      will-change: transform, left, top;
+      border: 1px solid rgba(255, 255, 255, 0.15);
+    `;
+    this.container.appendChild(el);
+    this.labels.set(key, { el });
+    return el;
+  }
+
+  private projectToScreen(
+    worldX: number, worldY: number, worldZ: number,
+    viewProj: Float32Array,
+    canvasW: number, canvasH: number,
+  ): { x: number; y: number; behind: boolean } | null {
+    const x = viewProj[0] * worldX + viewProj[4] * worldY + viewProj[8] * worldZ + viewProj[12];
+    const y = viewProj[1] * worldX + viewProj[5] * worldY + viewProj[9] * worldZ + viewProj[13];
+    const w = viewProj[3] * worldX + viewProj[7] * worldY + viewProj[11] * worldZ + viewProj[15];
+
+    if (w <= 0) return { x: 0, y: 0, behind: true };
+
+    const ndcX = x / w;
+    const ndcY = y / w;
+
+    const screenX = (ndcX + 1) * 0.5 * canvasW;
+    const screenY = (1 - ndcY) * 0.5 * canvasH;
+
+    return { x: screenX, y: screenY, behind: false };
+  }
+
+  update(camera: Parameters<typeof calculateViewProj>[0]): void {
+    if (!this.active || !this.provider) return;
+
+    const viewProj = calculateViewProj(camera);
+    const canvasW = this.canvas.clientWidth;
+    const canvasH = this.canvas.clientHeight;
+
+    const labels = this.provider.getLabels();
+    const usedKeys = new Set<string>();
+
+    for (let _i = 0, _it = labels, _n = _it.length; _i < _n; _i++) { const label = _it[_i];
+      usedKeys.add(label.key);
+      const proj = this.projectToScreen(label.x, label.y, label.z, viewProj, canvasW, canvasH);
+      if (!proj || proj.behind) continue;
+
+      const el = this.getOrCreateLabel(label.key);
+      if (!el) continue;
+
+      el.textContent = label.text;
+      el.style.left = `${proj.x}px`;
+      el.style.top = `${proj.y}px`;
+      el.style.color = label.color;
+      el.style.display = "block";
+    }
+
+    for (const [key, entry] of this.labels.entries()) {
+      if (!usedKeys.has(key)) {
+        entry.el.style.display = "none";
+      }
+    }
+  }
+
+  destroy(): void {
+    this.clearLabels();
+    this.container.remove();
+  }
+}

package/modules/devtools/src/material-stats-panel.ts

@@ -0,0 +1,188 @@
+// ============================================================================
+// 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).
+// ============================================================================
+
+import type { IDevToolsPanelExtension } from "./types";
+
+export interface MaterialStatsPanelOptions {
+  tabLabel?: string;
+  tabTooltip?: string;
+  order?: number;
+  /** Optional callback to append custom rows to the stats grid. */
+  extraRows?: (stats: any) => [string, string][];
+}
+
+export function createMaterialStatsPanelExtension(
+  opts: MaterialStatsPanelOptions = {},
+): IDevToolsPanelExtension {
+  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,
+  };
+}