@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/dev/render-debug-adapter.ts

@@ -0,0 +1,199 @@
+/**
+ * First-party {@link RenderDebugAdapter} wiring (W4b, F11) — the glue between
+ * the WebGL2 frame capture (`webgl-frame-capture.ts`), a live three.js scene,
+ * and the render adapter's per-frame render pass.
+ *
+ * Split OUT of `vgai-scene-game-adapter.ts` so the capture/attribution/restore
+ * flow is unit-testable in a headless Node test with a mock GL context and a
+ * plain scene — a real non-headless GPU mount (EffectComposer + WebGLRenderer)
+ * cannot run under vitest here, the same reason the adapter suite drives
+ * `setup(ctx)` only through hotReload on a data scene. `mount()` owns the
+ * DECISION to construct this (only under a real WebGL2 context, never
+ * headless — see `frameCaptureContextFor`); this module owns the BEHAVIOR.
+ *
+ * Attribution model (honest by construction): `captureFrame()` wraps every
+ * renderable's `onBeforeRender` to feed one annotation to the capture. three
+ * calls `onBeforeRender` immediately before that object's MAIN-pass draw, so
+ * main-pass draws are attributed and shadow/composer-pass draws record
+ * `annotation: null` (counted as unattributed) — never a fabricated guess. The
+ * wrappers are all restored when the capture resolves, rejects, times out, or
+ * the adapter is disposed.
+ */
+
+import type * as THREE from 'three';
+import type { RenderDebugAdapter } from '../adapter/system-adapter';
+import type { RenderMemorySnapshot } from './render-memory';
+import type { DrawAnnotation, FrameCapture, WebGLFrameCapture } from './webgl-frame-capture';
+
+/** Decide whether a mount can host frame capture — a real WebGL2 context with
+ *  the draw entry points, never a headless/stub renderer. Exported so the
+ *  mount uses ONE predicate and a unit test can assert both sides (mock GL ⇒
+ *  the context; headless/missing ⇒ null) without a GPU. */
+export function frameCaptureContextFor(
+  headless: boolean,
+  rendererContext: unknown,
+): WebGL2RenderingContext | null {
+  if (headless) return null;
+  if (!rendererContext || typeof rendererContext !== 'object') return null;
+  const gl = rendererContext as Partial<WebGL2RenderingContext>;
+  if (typeof gl.getExtension !== 'function') return null;
+  if (typeof gl.drawArrays !== 'function' || typeof gl.drawElements !== 'function') return null;
+  return rendererContext as WebGL2RenderingContext;
+}
+
+export interface RenderDebugAdapterDeps {
+  /** The armed-on-demand frame capture over the mount's real context. */
+  capture: WebGLFrameCapture;
+  /** The live scene root traversed to attribute draws. */
+  scene: THREE.Object3D;
+  /** Memory snapshot supplier (renderer.info-backed). When omitted, the
+   *  adapter's `memorySnapshot` is absent (honest capability degradation). */
+  memory?: () => RenderMemorySnapshot;
+  /** Timeout (ms) after which a pending `captureFrame` rejects — the world
+   *  never rendered (paused/stopped). Default 5000. */
+  timeoutMs?: number;
+  /** Injected timer, for tests. Defaults to the real `setTimeout`/
+   *  `clearTimeout`. */
+  setTimeoutFn?: (fn: () => void, ms: number) => unknown;
+  clearTimeoutFn?: (handle: unknown) => void;
+}
+
+export interface RenderDebugWiring {
+  readonly adapter: RenderDebugAdapter;
+  /** Call at the START of the host render pass, before draws. */
+  beforeRender(): void;
+  /** Call at the END of the host render pass, after draws (in a `finally`). */
+  afterRender(): void;
+  /** Restore any pending attribution wrappers and reject a pending capture. */
+  dispose(): void;
+}
+
+interface Pending {
+  resolve(capture: FrameCapture): void;
+  reject(error: Error): void;
+  restores: (() => void)[];
+  timer: unknown;
+  settled: boolean;
+}
+
+/** Objects three actually issues draws for (and thus calls `onBeforeRender`
+ *  on before the main-pass draw). */
+function isRenderable(object: THREE.Object3D): boolean {
+  const o = object as unknown as {
+    isMesh?: boolean;
+    isSkinnedMesh?: boolean;
+    isPoints?: boolean;
+    isLine?: boolean;
+    isSprite?: boolean;
+  };
+  return Boolean(o.isMesh || o.isSkinnedMesh || o.isPoints || o.isLine || o.isSprite);
+}
+
+function annotationFor(object: THREE.Object3D): DrawAnnotation {
+  const mesh = object as THREE.Mesh;
+  const geometry = mesh.geometry as THREE.BufferGeometry | undefined;
+  const rawMaterial = mesh.material;
+  const material = (Array.isArray(rawMaterial) ? rawMaterial[0] : rawMaterial) as
+    | THREE.Material
+    | undefined;
+  const entityId = object.userData?.['entityId'];
+  return {
+    object: {
+      name: object.name || object.type,
+      type: object.type,
+      ...(entityId !== undefined ? { entityId: String(entityId) } : {}),
+    },
+    geometry: {
+      type: geometry?.type ?? 'unknown',
+      name: geometry?.name ?? '',
+      attributes: geometry ? Object.keys(geometry.attributes) : [],
+      indexed: Boolean(geometry?.index),
+    },
+    material: {
+      type: material?.type ?? 'unknown',
+      name: material?.name ?? '',
+    },
+  };
+}
+
+export function createRenderDebugAdapter(deps: RenderDebugAdapterDeps): RenderDebugWiring {
+  const { capture, scene, memory } = deps;
+  const timeoutMs = deps.timeoutMs ?? 5000;
+  const setTimer = deps.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer =
+    deps.clearTimeoutFn ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+
+  let pending: Pending | null = null;
+
+  function wrapOnBeforeRender(): (() => void)[] {
+    const restores: (() => void)[] = [];
+    scene.traverse((object) => {
+      if (!isRenderable(object)) return;
+      const original = object.onBeforeRender;
+      object.onBeforeRender = function patched(this: THREE.Object3D, ...args) {
+        capture.annotateNextDraw(annotationFor(object));
+        original.apply(this, args as Parameters<THREE.Object3D['onBeforeRender']>);
+      };
+      restores.push(() => {
+        object.onBeforeRender = original;
+      });
+    });
+    return restores;
+  }
+
+  function settlePending(): Pending | null {
+    const p = pending;
+    if (p && !p.settled) {
+      p.settled = true;
+      clearTimer(p.timer);
+      for (const restore of p.restores) restore();
+      pending = null;
+      return p;
+    }
+    return null;
+  }
+
+  const adapter: RenderDebugAdapter = {
+    captureFrame(): Promise<FrameCapture> {
+      if (pending) {
+        return Promise.reject(new Error('RenderDebugAdapter: a frame capture is already pending'));
+      }
+      return new Promise<FrameCapture>((resolve, reject) => {
+        const restores = wrapOnBeforeRender();
+        capture.arm();
+        // Assign `pending` BEFORE arming the timer so a synchronous injected
+        // timer (test) sees a settle-able pending rather than a null one.
+        const p: Pending = { resolve, reject, restores, timer: null, settled: false };
+        pending = p;
+        p.timer = setTimer(() => {
+          if (settlePending()) {
+            reject(
+              new Error(
+                `RenderDebugAdapter: no frame rendered within ${timeoutMs}ms — the world may be paused or stopped`,
+              ),
+            );
+          }
+        }, timeoutMs);
+      });
+    },
+    ...(memory ? { memorySnapshot: (): RenderMemorySnapshot => memory() } : {}),
+  };
+
+  return {
+    adapter,
+    beforeRender(): void {
+      capture.beginPass();
+    },
+    afterRender(): void {
+      const result = capture.endPass();
+      if (result && pending) {
+        const p = settlePending();
+        p?.resolve(result);
+      }
+    },
+    dispose(): void {
+      const p = settlePending();
+      if (p) p.reject(new Error('RenderDebugAdapter: disposed before a frame was captured'));
+    },
+  };
+}

package/src/dev/render-memory.ts

@@ -0,0 +1,243 @@
+/**
+ * First-party GPU-memory estimator (W4b, F11 profiler memory tab).
+ *
+ * Walks a live three.js scene and reports geometry/texture byte footprints
+ * from data this engine ALREADY holds — attribute buffers and texture images —
+ * plus the renderer's own resource counts (`renderer.info`). Uses three.js
+ * directly, no wrapper.
+ *
+ * HONESTY (adapters never fabricate; unmeasurable = absent-with-reason):
+ *  - `estimateGeometryBytes` is EXACT: the summed `byteLength` of every
+ *    attribute and index array. Not an estimate at all — it is what the
+ *    buffers occupy in CPU memory (and, uploaded 1:1, on the GPU).
+ *  - `estimateTextureBytes` returns `null` when the footprint is genuinely
+ *    unknowable at this seam (no image dimensions, or a pixel format/type we
+ *    can't size). A null NEVER enters the totals — it goes to `unestimated[]`
+ *    with a reason, so the panel can say "N textures unmeasured" instead of
+ *    silently undercounting.
+ *  - JS heap is deliberately NOT here: `performance.memory` is a browser-only
+ *    global read editor-side (M2), not an engine-scene property.
+ */
+
+import * as THREE from 'three';
+
+export interface RenderMemoryEntry {
+  readonly name: string;
+  readonly bytes: number;
+}
+
+export interface RenderMemoryUnestimated {
+  readonly name: string;
+  readonly reason: string;
+}
+
+export interface RenderMemorySnapshot {
+  readonly counts: {
+    readonly geometries: number;
+    readonly textures: number;
+    /** Compiled program count, or `null` when the renderer doesn't expose it
+     *  (`renderer.info.programs` is populated only after the first render). */
+    readonly programs: number | null;
+  };
+  /** Sum of every ESTIMABLE texture (nulls excluded — they are in
+   *  `unestimated`). */
+  readonly estimatedTextureBytes: number;
+  /** Exact sum of geometry attribute + index buffers. */
+  readonly estimatedGeometryBytes: number;
+  readonly topTextures: readonly RenderMemoryEntry[];
+  readonly topGeometries: readonly RenderMemoryEntry[];
+  readonly unestimated: readonly RenderMemoryUnestimated[];
+}
+
+const TOP_N = 10;
+
+/** Channel count per pixel format. Packed/compressed formats are handled by
+ *  the byte-size logic in {@link estimateTextureBytes}, not here. */
+const FORMAT_CHANNELS: Record<number, number> = {
+  [THREE.AlphaFormat]: 1,
+  [THREE.RedFormat]: 1,
+  [THREE.RedIntegerFormat]: 1,
+  [THREE.RGFormat]: 2,
+  [THREE.RGIntegerFormat]: 2,
+  [THREE.RGBAFormat]: 4,
+  [THREE.RGBAIntegerFormat]: 4,
+  [THREE.DepthFormat]: 1,
+  [THREE.DepthStencilFormat]: 2,
+};
+
+/** Bytes per channel for a (non-packed) pixel type. */
+const TYPE_BYTES: Record<number, number> = {
+  [THREE.UnsignedByteType]: 1,
+  [THREE.ByteType]: 1,
+  [THREE.ShortType]: 2,
+  [THREE.UnsignedShortType]: 2,
+  [THREE.IntType]: 4,
+  [THREE.UnsignedIntType]: 4,
+  [THREE.FloatType]: 4,
+  [THREE.HalfFloatType]: 2,
+};
+
+/** Packed pixel types occupy a FIXED size per texel regardless of channel
+ *  count — sized here directly rather than via channels × type-bytes. */
+const PACKED_TYPE_TEXEL_BYTES: Record<number, number> = {
+  [THREE.UnsignedShort4444Type]: 2,
+  [THREE.UnsignedShort5551Type]: 2,
+  [THREE.UnsignedInt248Type]: 4,
+};
+
+function bytesPerTexel(format: number, type: number): number | null {
+  const packed = PACKED_TYPE_TEXEL_BYTES[type];
+  if (packed !== undefined) return packed;
+  const channels = FORMAT_CHANNELS[format];
+  const typeBytes = TYPE_BYTES[type];
+  if (channels === undefined || typeBytes === undefined) return null;
+  return channels * typeBytes;
+}
+
+/** EXACT CPU/GPU footprint of a geometry's attribute + index buffers. */
+export function estimateGeometryBytes(geometry: THREE.BufferGeometry): number {
+  // Interleaved attributes share ONE backing buffer (`attribute.data.array`);
+  // a plain attribute owns its own (`attribute.array`). Count each unique
+  // backing view exactly once.
+  const counted = new Set<ArrayBufferView>();
+  let bytes = 0;
+  const add = (view: ArrayBufferView | undefined): void => {
+    if (view && !counted.has(view)) {
+      counted.add(view);
+      bytes += view.byteLength;
+    }
+  };
+  for (const attribute of Object.values(geometry.attributes)) {
+    const interleaved = (attribute as THREE.InterleavedBufferAttribute).data?.array as
+      | ArrayBufferView
+      | undefined;
+    add(interleaved ?? ((attribute as THREE.BufferAttribute).array as ArrayBufferView | undefined));
+  }
+  add(geometry.index?.array as ArrayBufferView | undefined);
+  return bytes;
+}
+
+/** Estimated GPU footprint of a texture, or `null` when unknowable at this
+ *  seam (the caller routes null into `unestimated[]` with a reason). */
+export function estimateTextureBytes(texture: THREE.Texture): number | null {
+  // Compressed textures carry their real per-mip byte arrays — sum them; no
+  // format math needed and no estimate involved.
+  const compressed = texture as THREE.CompressedTexture;
+  if (
+    (compressed as { isCompressedTexture?: boolean }).isCompressedTexture &&
+    Array.isArray(compressed.mipmaps)
+  ) {
+    let bytes = 0;
+    for (const mip of compressed.mipmaps) {
+      const data = (mip as { data?: ArrayBufferView }).data;
+      if (data?.byteLength) bytes += data.byteLength;
+    }
+    return bytes;
+  }
+
+  const image = texture.image as { width?: number; height?: number } | undefined;
+  const width = image?.width;
+  const height = image?.height;
+  if (!width || !height) return null;
+
+  const bpt = bytesPerTexel(texture.format, texture.type);
+  if (bpt === null) return null;
+
+  const base = width * height * bpt;
+  return texture.generateMipmaps ? Math.round(base * 1.333) : base;
+}
+
+function textureName(texture: THREE.Texture): string {
+  return texture.name || (texture.image as { src?: string })?.src || `texture:${texture.uuid}`;
+}
+
+function geometryName(geometry: THREE.BufferGeometry): string {
+  return geometry.name || `${geometry.type}:${geometry.uuid}`;
+}
+
+function unestimatedReason(texture: THREE.Texture): string {
+  const image = texture.image as { width?: number; height?: number } | undefined;
+  if (!image?.width || !image?.height) return 'no image dimensions available';
+  return `unsupported format/type (format 0x${texture.format.toString(16)}, type 0x${texture.type.toString(16)})`;
+}
+
+/** Collect every unique geometry and texture referenced by a scene graph. */
+function collectResources(scene: THREE.Object3D): {
+  geometries: Map<string, THREE.BufferGeometry>;
+  textures: Map<string, THREE.Texture>;
+} {
+  const geometries = new Map<string, THREE.BufferGeometry>();
+  const textures = new Map<string, THREE.Texture>();
+
+  const addMaterialTextures = (material: THREE.Material): void => {
+    for (const value of Object.values(material as unknown as Record<string, unknown>)) {
+      if (value && (value as THREE.Texture).isTexture) {
+        const tex = value as THREE.Texture;
+        textures.set(tex.uuid, tex);
+      }
+    }
+  };
+
+  scene.traverse((object) => {
+    const geometry = (object as THREE.Mesh).geometry as THREE.BufferGeometry | undefined;
+    if (geometry?.isBufferGeometry) geometries.set(geometry.uuid, geometry);
+    const material = (object as THREE.Mesh).material;
+    if (Array.isArray(material)) material.forEach(addMaterialTextures);
+    else if (material) addMaterialTextures(material);
+  });
+
+  // Scene-level environment/background textures count too.
+  for (const maybe of [scene as unknown as THREE.Scene]) {
+    for (const value of [maybe.background, maybe.environment]) {
+      if (value && (value as THREE.Texture).isTexture) {
+        const tex = value as THREE.Texture;
+        textures.set(tex.uuid, tex);
+      }
+    }
+  }
+
+  return { geometries, textures };
+}
+
+export function collectRenderMemory(
+  scene: THREE.Object3D,
+  info: THREE.WebGLInfo,
+): RenderMemorySnapshot {
+  const { geometries, textures } = collectResources(scene);
+
+  const geometryEntries: RenderMemoryEntry[] = [];
+  let estimatedGeometryBytes = 0;
+  for (const geometry of geometries.values()) {
+    const bytes = estimateGeometryBytes(geometry);
+    estimatedGeometryBytes += bytes;
+    geometryEntries.push({ name: geometryName(geometry), bytes });
+  }
+
+  const textureEntries: RenderMemoryEntry[] = [];
+  const unestimated: RenderMemoryUnestimated[] = [];
+  let estimatedTextureBytes = 0;
+  for (const texture of textures.values()) {
+    const bytes = estimateTextureBytes(texture);
+    if (bytes === null) {
+      unestimated.push({ name: textureName(texture), reason: unestimatedReason(texture) });
+      continue;
+    }
+    estimatedTextureBytes += bytes;
+    textureEntries.push({ name: textureName(texture), bytes });
+  }
+
+  const byBytesDesc = (a: RenderMemoryEntry, b: RenderMemoryEntry): number => b.bytes - a.bytes;
+
+  return {
+    counts: {
+      geometries: info.memory.geometries,
+      textures: info.memory.textures,
+      programs: info.programs ? info.programs.length : null,
+    },
+    estimatedTextureBytes,
+    estimatedGeometryBytes,
+    topTextures: textureEntries.sort(byBytesDesc).slice(0, TOP_N),
+    topGeometries: geometryEntries.sort(byBytesDesc).slice(0, TOP_N),
+    unestimated,
+  };
+}