@downdraft/engine 0.0.0 → 0.1.1

package/modules/devtools/src/data-bridge.ts

@@ -0,0 +1,286 @@
+// ============================================================================
+// DevToolsDataBridge — non-abstract data-feed API exposed on
+// window.__sceneInspector. Games that don't need the full 3D scene inspector
+// (e.g. falling-sand, model-viewer) can instantiate this directly with a
+// minimal IDevToolsDataRenderer to get perf metrics, GC stats, GPU info, and
+// telemetry in the DevTools panel.
+//
+// BaseSceneInspector extends this class and adds scene-tree / model / gizmo /
+// material-editor methods on top.
+// ============================================================================
+
+import { startGCProfiler, TelemetryCollector, type GCProfilerHandle, type GCStats } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { useDebugStore } from "./debug-store";
+import type {
+    IDebugModeProvider,
+    IDevToolsDataRenderer,
+    IDevToolsOverlayToggle,
+    IDevToolsPanelExtension,
+    IPerformanceMetricsProvider,
+    ISimStatsProvider,
+} from "./types";
+
+const log = createLogger("info");
+
+export class DevToolsDataBridge {
+  protected renderer: IDevToolsDataRenderer | null = null;
+  protected initialized = false;
+  protected perfGcHandle: GCProfilerHandle | null = null;
+  protected perfActive = false;
+  protected cachedGpuSystemInfo: any = null;
+  protected cachedGpuAdapterInfo: any = null;
+  protected cachedFeatureLog: any = null;
+  protected hostFetchInterval: ReturnType<typeof setInterval> | null = null;
+
+  // --- Optional overrides ---
+
+  protected getDebugModeProvider(): IDebugModeProvider | null {
+    return null;
+  }
+
+  protected getPerformanceMetricsProvider(): IPerformanceMetricsProvider | null {
+    return null;
+  }
+
+  /** Games override this to declare custom DevTools panel tabs. */
+  protected getPanelExtensions(): IDevToolsPanelExtension[] {
+    return [];
+  }
+
+  /** Games override this to declare custom overlay toggles. */
+  protected getOverlayToggles(): IDevToolsOverlayToggle[] {
+    return [];
+  }
+
+  /** Games override this to expose sim stats + controls (pause/step/speed/clear). */
+  protected getSimStatsProvider(): ISimStatsProvider | null {
+    return null;
+  }
+
+  // --- Init ---
+
+  init(renderer?: IDevToolsDataRenderer): void {
+    this.renderer = renderer ?? null;
+    this.initialized = true;
+
+    this.fetchHostData();
+    this.hostFetchInterval = setInterval(() => this.fetchHostData(), 2000);
+
+    const api = this.buildApi();
+    (window as any).__sceneInspector = api;
+    log.info("DevToolsDataBridge", "API exposed on window.__sceneInspector");
+  }
+
+  protected buildApi(): Record<string, any> {
+    return {
+      isReady: (): boolean => {
+        return this.initialized;
+      },
+
+      // --- Performance monitoring ---
+      enablePerformanceMonitoring: (): void => {
+        if (this.perfActive) return;
+        this.perfActive = true;
+
+        if (!this.perfGcHandle) {
+          this.perfGcHandle = startGCProfiler('renderer', (stats: GCStats) => {
+            useDebugStore.getState().updateGCStats(stats);
+          });
+        }
+
+        this.renderer?.setDebugMode?.(true);
+        this.getDebugModeProvider()?.setDebugMode(true);
+      },
+
+      disablePerformanceMonitoring: (): void => {
+        if (!this.perfActive) return;
+        this.perfActive = false;
+
+        this.perfGcHandle?.stop();
+        this.perfGcHandle = null;
+
+        if (!useDebugStore.getState().showDebugPage) {
+          this.renderer?.setDebugMode?.(false);
+          this.getDebugModeProvider()?.setDebugMode(false);
+        }
+      },
+
+      getPerformanceMetrics: (): any => {
+        const provider = this.getPerformanceMetricsProvider();
+        if (provider) return provider.getPerformanceMetrics();
+
+        // Fallback: basic renderer-only metrics
+        const gcStats = useDebugStore.getState().gcStats;
+        const fps = this.renderer?.getFPS() ?? 0;
+        const frameTimeMs = fps > 0 ? 1000 / fps : 0;
+        const targetFrameMs = 1000 / 60;
+        const gpuUtil = Math.min(100, (frameTimeMs / targetFrameMs) * 100);
+        const perfMem = (performance as any).memory;
+        const rendererMemMB = perfMem ? perfMem.usedJSHeapSize / 1048576 : 0;
+
+        function gcFor(label: string) {
+          const g = gcStats[label];
+          if (!g) return { count: 0, totalTime: 0, scavengeCount: 0, majorCount: 0 };
+          return {
+            count: g.interval.count,
+            totalTime: g.interval.totalTime,
+            scavengeCount: g.interval.scavengeCount,
+            majorCount: g.interval.majorCount,
+          };
+        }
+
+        return {
+          gpu: { utilization: gpuUtil, frameTimeMs, fps },
+          renderer: {
+            cpuPercent: gpuUtil, memUsedMB: rendererMemMB,
+            diskKBps: 0, networkKBps: 0, gc: gcFor("renderer"),
+          },
+          main: { cpuPercent: 0, memUsedMB: 0, diskKBps: 0, networkKBps: 0, gc: gcFor("main") },
+          worker: { cpuPercent: 0, memUsedMB: 0, diskKBps: 0, networkKBps: 0, gc: gcFor("sim-worker") },
+          timestamp: performance.now(),
+        };
+      },
+
+      // --- GPU Debugging ---
+      getGPUInfo: (): any => {
+        return this.renderer?.getGPUInfo?.() ?? null;
+      },
+
+      // --- Feature Log (cached by fetchHostData; sync for callInspector) ---
+      getFeatureLog: (): any => {
+        return this.cachedFeatureLog;
+      },
+
+      getGPUErrors: (): any => {
+        return this.renderer?.getGPUErrors?.() ?? [];
+      },
+
+      clearGPUErrors: (): void => {
+        this.renderer?.clearGPUErrors?.();
+      },
+
+      getFrameTelemetry: (): any => {
+        return this.renderer?.getFrameTelemetry?.() ?? null;
+      },
+
+      getGPUResourceStats: (): any => {
+        const tracker = this.renderer?.getGPUResourceTracker?.();
+        if (!tracker) return null;
+        return tracker.getStats();
+      },
+
+      getPassTimings: (): any => {
+        const tc = this.renderer?.getTelemetryCollector?.();
+        if (!tc) return [];
+        return tc.getPassTimings();
+      },
+
+      getFrameGraph: (): any => {
+        return this.renderer?.getFrameGraph?.() ?? null;
+      },
+
+      saveSnapshot: (label: string): any => {
+        const tc = this.renderer?.getTelemetryCollector?.();
+        if (!tc) return null;
+        return tc.saveSnapshot(label || "Snapshot");
+      },
+
+      getSnapshots: (): any => {
+        const tc = this.renderer?.getTelemetryCollector?.();
+        if (!tc) return [];
+        return tc.getSnapshots();
+      },
+
+      clearSnapshots: (): void => {
+        this.renderer?.getTelemetryCollector?.()?.clearSnapshots();
+      },
+
+      diffSnapshots: (idxA: number, idxB: number): any => {
+        const tc = this.renderer?.getTelemetryCollector?.();
+        if (!tc) return [];
+        const snaps = tc.getSnapshots();
+        if (idxA < 0 || idxB < 0 || idxA >= snaps.length || idxB >= snaps.length) return [];
+        return TelemetryCollector.diffSnapshots(snaps[idxA], snaps[idxB]);
+      },
+
+      // --- GC Controller ---
+      getGCStats: (): any => {
+        const r = this.renderer as any;
+        const stats: Record<string, any> = {};
+        if (r?.getGCStats) stats.renderer = r.getGCStats();
+        // Worker stats come from debug store (forwarded via events)
+        const debugStats = useDebugStore.getState().gcControllerStats;
+        if (debugStats["sim-worker"]) stats["sim-worker"] = debugStats["sim-worker"];
+        return stats;
+      },
+
+      setGCConfig: (config: any): void => {
+        const r = this.renderer as any;
+        if (r?.setGCConfig) r.setGCConfig(config);
+        // Forward to worker via debug mode provider
+        const provider = this.getDebugModeProvider() as any;
+        if (provider?.setGCConfig) provider.setGCConfig(config);
+        useDebugStore.getState().setGCConfig(config);
+      },
+
+      forceMajorGC: (): void => {
+        const r = this.renderer as any;
+        if (r?.forceMajorGC) r.forceMajorGC();
+        const provider = this.getDebugModeProvider() as any;
+        if (provider?.forceMajorGC) provider.forceMajorGC();
+      },
+
+      getVersion: (): string => {
+        return "1.0.0";
+      },
+
+      getGPUSystemInfo: (): any => {
+        return this.cachedGpuSystemInfo;
+      },
+
+      getGPUAdapterInfo: (): any => {
+        return this.cachedGpuAdapterInfo;
+      },
+
+      // --- Panel extensions (game-specific tabs and overlay toggles) ---
+      getPanelExtensions: (): IDevToolsPanelExtension[] => this.getPanelExtensions(),
+      getOverlayToggles: (): IDevToolsOverlayToggle[] => this.getOverlayToggles(),
+
+      // --- Sim stats & controls (optional — games implement ISimStatsProvider) ---
+      getSimStats: (): any => this.getSimStatsProvider()?.getSimStats() ?? null,
+      pauseSim: (): void => { this.getSimStatsProvider()?.pauseSim(); },
+      resumeSim: (): void => { this.getSimStatsProvider()?.resumeSim(); },
+      stepSim: (): void => { this.getSimStatsProvider()?.stepSim?.(); },
+      setSimSpeed: (speed: number): void => { this.getSimStatsProvider()?.setSimSpeed?.(speed); },
+      clearSim: (): void => { this.getSimStatsProvider()?.clearSim?.(); },
+    };
+  }
+
+  // --- Host data fetching ---
+
+  private fetchHostData(): void {
+    const w = window as any;
+    if (w.downdraft?.getGPUSystemInfo) {
+      w.downdraft.getGPUSystemInfo().then((data: any) => { this.cachedGpuSystemInfo = data; }).catch(() => {});
+    }
+    if (w.downdraft?.getGpuInfo) {
+      w.downdraft.getGpuInfo().then((info: any) => { this.cachedGpuAdapterInfo = info; }).catch(() => {});
+    }
+    // Feature log — host (direct call) merged with renderer cache. Dynamic import
+    // avoids pulling @downdraft/engine/app/renderer at data-bridge construction time.
+    import("@downdraft/engine/app/renderer").then(({ getCombinedFeatureLog }) => {
+      getCombinedFeatureLog().then((data: any) => { this.cachedFeatureLog = data; }).catch(() => {});
+    }).catch(() => {});
+  }
+
+  destroy(): void {
+    this.initialized = false;
+    this.renderer = null;
+    if (this.hostFetchInterval) {
+      clearInterval(this.hostFetchInterval);
+      this.hostFetchInterval = null;
+    }
+    delete (window as any).__sceneInspector;
+  }
+}

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

@@ -0,0 +1,238 @@
+// ============================================================================
+// DebugOverlay — 2D canvas overlay for chunk grid + velocity arrows
+// Generic rendering logic; game provides data via IDebugOverlayData interface.
+// ============================================================================
+
+import { calculateViewProj, CanvasResizeWatcher, type RenderSurface } from "@downdraft/engine";
+import type { IDebugOverlayData } from "./types";
+
+export class DebugOverlay {
+  private canvas: HTMLCanvasElement;
+  private overlay: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D;
+  private showChunkGrid = false;
+  private showVelocityArrows = false;
+  private resizeWatcher: CanvasResizeWatcher;
+
+  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.overlay = document.createElement("canvas");
+    this.overlay.className = "debug-overlay";
+    this.overlay.style.cssText = `
+      position: absolute;
+      top: 0; left: 0;
+      width: 100%; height: 100%;
+      pointer-events: none;
+      z-index: 0;
+      display: none;
+    `;
+    const parent = canvas.parentElement;
+    if (parent) {
+      parent.style.position = parent.style.position || "relative";
+      parent.appendChild(this.overlay);
+    } else {
+      document.body.appendChild(this.overlay);
+    }
+    this.ctx = this.overlay.getContext("2d")!;
+    this.resizeWatcher = new CanvasResizeWatcher(canvas, {
+      onResize: (w, h) => {
+        if (this.overlay.width !== w || this.overlay.height !== h) {
+          this.overlay.width = w;
+          this.overlay.height = h;
+        }
+      },
+    });
+  }
+
+  setShowChunkGrid(show: boolean): void {
+    this.showChunkGrid = show;
+    this.updateDisplay();
+  }
+
+  setShowVelocityArrows(show: boolean): void {
+    this.showVelocityArrows = show;
+    this.updateDisplay();
+  }
+
+  isChunkGridVisible(): boolean {
+    return this.showChunkGrid;
+  }
+
+  isVelocityArrowsVisible(): boolean {
+    return this.showVelocityArrows;
+  }
+
+  private updateDisplay(): void {
+    const active = this.showChunkGrid || this.showVelocityArrows;
+    this.overlay.style.display = active ? "block" : "none";
+    if (!active) {
+      this.ctx.clearRect(0, 0, this.overlay.width, this.overlay.height);
+    }
+  }
+
+  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],
+    data: IDebugOverlayData,
+  ): void {
+    if (!this.showChunkGrid && !this.showVelocityArrows) return;
+
+    const ctx = this.ctx;
+    const canvasW = this.overlay.width;
+    const canvasH = this.overlay.height;
+    ctx.clearRect(0, 0, canvasW, canvasH);
+
+    const viewProj = calculateViewProj(camera);
+
+    if (this.showChunkGrid) {
+      this.renderChunkGrid(ctx, camera, viewProj, canvasW, canvasH, data);
+    }
+
+    if (this.showVelocityArrows) {
+      this.renderVelocityArrows(ctx, viewProj, canvasW, canvasH, data);
+    }
+  }
+
+  private renderChunkGrid(
+    ctx: CanvasRenderingContext2D,
+    camera: { position: [number, number, number] },
+    viewProj: Float32Array,
+    canvasW: number, canvasH: number,
+    data: IDebugOverlayData,
+  ): void {
+    const playerPos = data.getPlayerPosition();
+    if (!playerPos) return;
+    const { chunkSize, chunksVisible } = data.getChunkGridConfig();
+
+    const playerChunkX = Math.floor(playerPos.x / chunkSize);
+    const playerChunkZ = Math.floor(playerPos.z / chunkSize);
+    const half = Math.ceil(chunksVisible / 2);
+
+    ctx.strokeStyle = "rgba(100, 200, 255, 0.35)";
+    ctx.lineWidth = 1;
+    ctx.font = "10px monospace";
+    ctx.fillStyle = "rgba(100, 200, 255, 0.6)";
+
+    for (let cx = playerChunkX - half; cx <= playerChunkX + half; cx++) {
+      for (let cz = playerChunkZ - half; cz <= playerChunkZ + half; cz++) {
+        const worldX = cx * chunkSize;
+        const worldZ = cz * chunkSize;
+
+        const corners = [
+          this.projectToScreen(worldX, 0, worldZ, viewProj, canvasW, canvasH),
+          this.projectToScreen(worldX + chunkSize, 0, worldZ, viewProj, canvasW, canvasH),
+          this.projectToScreen(worldX + chunkSize, 0, worldZ + chunkSize, viewProj, canvasW, canvasH),
+          this.projectToScreen(worldX, 0, worldZ + chunkSize, viewProj, canvasW, canvasH),
+        ];
+
+        if (corners.some(c => c === null || c.behind)) continue;
+
+        ctx.beginPath();
+        ctx.moveTo(corners[0]!.x, corners[0]!.y);
+        ctx.lineTo(corners[1]!.x, corners[1]!.y);
+        ctx.lineTo(corners[2]!.x, corners[2]!.y);
+        ctx.lineTo(corners[3]!.x, corners[3]!.y);
+        ctx.closePath();
+        ctx.stroke();
+
+        const centerProj = this.projectToScreen(
+          worldX + chunkSize / 2, 0, worldZ + chunkSize / 2,
+          viewProj, canvasW, canvasH,
+        );
+        if (centerProj && !centerProj.behind) {
+          const dx = (worldX + chunkSize / 2) - camera.position[0];
+          const dz = (worldZ + chunkSize / 2) - camera.position[2];
+          const dist = Math.sqrt(dx * dx + dz * dz);
+          if (dist < chunkSize * half) {
+            ctx.fillText(`${cx},${cz}`, centerProj.x - 15, centerProj.y);
+          }
+        }
+      }
+    }
+  }
+
+  private renderVelocityArrows(
+    ctx: CanvasRenderingContext2D,
+    viewProj: Float32Array,
+    canvasW: number, canvasH: number,
+    data: IDebugOverlayData,
+  ): void {
+    const entityCount = data.getEntityCount();
+
+    ctx.strokeStyle = "rgba(255, 200, 50, 0.8)";
+    ctx.fillStyle = "rgba(255, 200, 50, 0.8)";
+    ctx.lineWidth = 2;
+
+    for (let i = 0; i < entityCount; i++) {
+      const pos = data.getEntityPosition(i);
+      const vel = data.getEntityVelocity(i);
+      if (!pos || !vel) continue;
+
+      const speed = Math.sqrt(vel.x * vel.x + vel.y * vel.y + vel.z * vel.z);
+      if (speed < 0.1) continue;
+
+      const scale = 2.0;
+      const endX = pos.x + vel.x * scale;
+      const endY = pos.y + vel.y * scale;
+      const endZ = pos.z + vel.z * scale;
+
+      const startProj = this.projectToScreen(pos.x, pos.y, pos.z, viewProj, canvasW, canvasH);
+      const endProj = this.projectToScreen(endX, endY, endZ, viewProj, canvasW, canvasH);
+
+      if (!startProj || startProj.behind || !endProj || endProj.behind) continue;
+
+      ctx.beginPath();
+      ctx.moveTo(startProj.x, startProj.y);
+      ctx.lineTo(endProj.x, endProj.y);
+      ctx.stroke();
+
+      const dx = endProj.x - startProj.x;
+      const dy = endProj.y - startProj.y;
+      const angle = Math.atan2(dy, dx);
+      const headLen = 6;
+      ctx.beginPath();
+      ctx.moveTo(endProj.x, endProj.y);
+      ctx.lineTo(
+        endProj.x - headLen * Math.cos(angle - Math.PI / 6),
+        endProj.y - headLen * Math.sin(angle - Math.PI / 6),
+      );
+      ctx.lineTo(
+        endProj.x - headLen * Math.cos(angle + Math.PI / 6),
+        endProj.y - headLen * Math.sin(angle + Math.PI / 6),
+      );
+      ctx.closePath();
+      ctx.fill();
+
+      ctx.font = "10px monospace";
+      ctx.fillText(`${speed.toFixed(1)} m/s`, endProj.x + 4, endProj.y - 4);
+    }
+  }
+
+  destroy(): void {
+    this.resizeWatcher.destroy();
+    this.overlay.remove();
+  }
+}