@vgai/engine 0.5.7 → 0.5.9

package/src/dev/performance-profiler.ts

@@ -35,6 +35,15 @@ export interface PerformanceRenderStats {
   readonly triangles: number;
   readonly geometries: number;
   readonly textures: number;
+  /**
+   * How many top-level `renderer.render()` submissions the last presentation
+   * took (`renderer.info.render.frame`'s delta across one draw) — a composer
+   * chain, a shadow pass and a post stack each cost one. `null` (never a
+   * fabricated 0, same rule as `gpuMs`) when no reporter counted them: a
+   * reporter that omits `renderPasses` is saying it does not know, which is
+   * different from saying nothing was drawn.
+   */
+  readonly renderPasses: number | null;
 }
 
 export interface PerformanceFrame {
@@ -75,13 +84,7 @@ export interface PerformanceSnapshot {
   readonly phases: readonly PerformanceTiming[];
   readonly systems: readonly PerformanceTiming[];
   readonly components: readonly PerformanceTiming[];
-  readonly render: {
-    readonly gpuMs: number | null;
-    readonly drawCalls: number;
-    readonly triangles: number;
-    readonly geometries: number;
-    readonly textures: number;
-  };
+  readonly render: PerformanceRenderStats;
 }
 
 const now = () => globalThis.performance?.now() ?? Date.now();
@@ -110,15 +113,27 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
   let frameId = 0;
   let frameStart = 0;
   let lastFrameStart = 0;
-  let phaseStart = 0;
+  /**
+   * Phase start times, innermost last. A STACK rather than the single slot
+   * this used to be, because phases NEST: the three adapter brackets its CPU
+   * render submission as its own phase (`render.submit`,
+   * `dev/render-vitals.ts`) from inside the frame's enclosing `render` phase.
+   * With one slot the inner `beginPhase()` overwrote the outer's start, so the
+   * outer `endPhase('render')` measured only the tail after the inner phase —
+   * silently under-reporting the very phase the inner one was decomposing.
+   * Balanced callers are unaffected; `endPhase` with an empty stack falls back
+   * to `frameStart` rather than a stale start from a previous frame.
+   */
+  const phaseStack: number[] = [];
   let systemStart = 0;
   let componentStart = 0;
-  let render = {
-    gpuMs: null as number | null,
+  let render: PerformanceRenderStats = {
+    gpuMs: null,
     drawCalls: 0,
     triangles: 0,
     geometries: 0,
     textures: 0,
+    renderPasses: null,
   };
   let snapshot: PerformanceSnapshot = {
     enabled,
@@ -188,15 +203,28 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       currentComponents.clear();
       frameSystems = [];
       frameComponents = [];
-      render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
+      // A frame that threw mid-phase leaves entries on the stack; a fresh
+      // frame starts from nothing rather than inheriting them.
+      phaseStack.length = 0;
+      render = {
+        gpuMs: null,
+        drawCalls: 0,
+        triangles: 0,
+        geometries: 0,
+        textures: 0,
+        renderPasses: null,
+      };
       frameStart = now();
     },
     beginPhase() {
       if (!enabled) return;
-      phaseStart = now();
+      phaseStack.push(now());
     },
     endPhase(name: string) {
       if (!enabled) return;
+      // See `phaseStack`: pop restores the ENCLOSING phase's own start, so a
+      // nested bracket measures itself without truncating its parent.
+      const phaseStart = phaseStack.pop() ?? frameStart;
       const elapsed = now() - phaseStart;
       const existing = currentPhases.get(name);
       // Accumulate ms across re-entries of the same phase, but keep the FIRST
@@ -247,6 +275,9 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       triangles: number;
       geometries: number;
       textures: number;
+      /** Omit when this reporter does not count passes — see
+       *  {@link PerformanceRenderStats.renderPasses}. */
+      renderPasses?: number;
     }) {
       if (!enabled) return;
       render = {
@@ -255,6 +286,10 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
         triangles: render.triangles + stats.triangles,
         geometries: render.geometries + stats.geometries,
         textures: render.textures + stats.textures,
+        renderPasses:
+          stats.renderPasses === undefined
+            ? render.renderPasses
+            : (render.renderPasses ?? 0) + stats.renderPasses,
       };
     },
     endFrame() {

package/src/dev/register-render-vitals.ts

@@ -0,0 +1,249 @@
+/**
+ * THE DOOR for live render vitals: one provider and four commands on the
+ * game's own debug registry (`runtime/debug-registry.ts`), so a running game
+ * explains its own frame cost through the SAME seam every other reading and
+ * verb uses — `game.state('render.vitals')` / `game.command('render.census')`
+ * through `vgai eval`, and `game.providers()`/`game.commands()` to discover
+ * them without being told they exist.
+ *
+ * Engine-owned and first-party, seeded by the three adapter
+ * (`adapter/setup-three-root-adapter.ts`) at the same spot it seeds
+ * `systemAdapters.renderDebug` — a game writes nothing to get these, and there
+ * is no capability to install. The measurement half is `dev/render-vitals.ts`
+ * (derived entirely from profiler frames); the address-book half is
+ * `dev/render-census.ts` (pure walks over the live scene). This module is only
+ * the wiring between them and the registry.
+ *
+ * ── THE READING AND THE EXPERIMENTS ─────────────────────────────────────────
+ * A number alone does not route an investigation, so each command is the
+ * experiment that turns one reading into an address:
+ *  - `render.census`   — which subtree owns the meshes and triangles, with a
+ *                        drill-down argument;
+ *  - `render.families` — which meshes are identical enough to instance;
+ *  - `render.toggle`   — hide a subtree and watch the stat move (the only way
+ *                        to ATTRIBUTE cost rather than infer it);
+ *  - `render.dpr`      — change the pixel count, which separates GPU fill cost
+ *                        from vsync idle: render CPU that does not move when
+ *                        the drawing buffer halves was never fill-bound.
+ *
+ * ── GATING ──────────────────────────────────────────────────────────────────
+ * The caller gates. `setup-three-root-adapter.ts` calls this only under
+ * `devLayersEnabled()` (`runtime/dev-layers.ts` — the ONE owner of "is this a
+ * dev context"), so a ship build registers nothing and pays nothing.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: {@link registerRenderVitals}'s caller. It allocates one
+ * {@link RenderVitals} fold (which owns one `profiler.subscribe`), a SECOND,
+ * self-ending `profiler.subscribe` for the static-batch advisory, and the
+ * registrations, whose provenance is the caller's `worldId`. SHARERS: none.
+ * TEARDOWN: the returned `dispose()` — the ONE path that ends both
+ * subscriptions. The REGISTRATIONS are ended by the registry's own
+ * `strip(worldId)`, which the adapter already runs on stop and warm restart;
+ * this module never strips, because a blind strip here would take the game's
+ * registrations with it.
+ */
+
+import * as THREE from 'three';
+import { z } from 'zod';
+import type { DebugRegistry } from '../runtime/debug-registry';
+import type { PerformanceProfiler } from './performance-profiler';
+import { findByName, meshFamilies, sceneCensus, structuralBatchScan } from './render-census';
+import { createRenderVitals, type RenderVitals } from './render-vitals';
+import {
+  ADVISOR_SETTLE_FRAMES,
+  decideStaticBatchAdvisory,
+  warnStaticBatchAdvisory,
+} from './static-batch-advisor';
+
+/** The one provider name — spelled here, referenced everywhere else. */
+export const RENDER_VITALS_PROVIDER = 'render.vitals';
+export const RENDER_CENSUS_COMMAND = 'render.census';
+export const RENDER_FAMILIES_COMMAND = 'render.families';
+export const RENDER_TOGGLE_COMMAND = 'render.toggle';
+export const RENDER_DPR_COMMAND = 'render.dpr';
+
+/** The slice of `THREE.WebGLRenderer` `render.dpr` actuates. Narrow on
+ *  purpose: a headless mount has no renderer at all and passes `null`. */
+export interface RenderVitalsRenderer {
+  getSize(target: THREE.Vector2): THREE.Vector2;
+  setPixelRatio(value: number): void;
+  setSize(width: number, height: number, updateStyle?: boolean): void;
+  getPixelRatio(): number;
+  readonly domElement: { readonly width: number; readonly height: number };
+}
+
+export interface RenderVitalsRegistration {
+  /** The live fold, exposed so a test can drive it without a registry. */
+  readonly vitals: RenderVitals;
+  /** See the ownership note — the ONE teardown path. Idempotent. */
+  dispose(): void;
+}
+
+export interface RegisterRenderVitalsDeps {
+  readonly registry: DebugRegistry;
+  /** Registration provenance — the mount's adapter id, so the adapter's own
+   *  `strip(worldId)` on stop/warm-restart removes exactly these. */
+  readonly worldId: string;
+  readonly profiler: PerformanceProfiler;
+  /** The live scene the census walks. */
+  readonly scene: THREE.Object3D;
+  /** `null` under a headless mount — `render.dpr` then refuses by name rather
+   *  than silently doing nothing. */
+  readonly renderer: RenderVitalsRenderer | null;
+}
+
+const NO_RENDERER =
+  'render.dpr: this world has no WebGL renderer (headless mount), so there is no pixel ratio ' +
+  'to change. The other render.* commands still work — they read the scene graph.';
+
+/**
+ * Seed the vitals door for one world. Returns `null` when another live world
+ * already owns the door: the names are fixed and discoverable on purpose, and
+ * the registry (correctly) throws on a cross-world name collision, so the
+ * FIRST three root to mount owns them. A second three root's draws still show
+ * up in the readings — the profiler is game-scoped, so every world's
+ * submission folds into the same frame — but the census commands address the
+ * owning root's scene.
+ */
+export function registerRenderVitals(
+  deps: RegisterRenderVitalsDeps,
+): RenderVitalsRegistration | null {
+  const { registry, worldId, profiler, scene, renderer } = deps;
+  const taken = registry.adapter
+    .providers()
+    .some((provider) => provider.name === RENDER_VITALS_PROVIDER);
+  if (taken) return null;
+
+  const vitals = createRenderVitals(profiler);
+  const debug = registry.forRoot(worldId);
+
+  debug.registerStateProvider(RENDER_VITALS_PROVIDER, () => vitals.read());
+
+  debug.registerCommand(
+    RENDER_CENSUS_COMMAND,
+    {
+      description:
+        'Visible meshes and triangles per subtree — the address book behind the draw-call ' +
+        'reading. Pass a subtree name (as listed by a previous census) to drill into it.',
+      args: z.tuple([z.string().optional()]),
+      locus: 'client',
+    },
+    (subtree) => {
+      if (subtree === undefined || subtree === '') return sceneCensus(scene);
+      const node = findByName(scene, subtree);
+      if (!node) {
+        throw new Error(
+          `render.census: no node named "${subtree}" in this world. Run render.census with no ` +
+            'argument to list the addressable subtrees.',
+        );
+      }
+      return sceneCensus(node, subtree);
+    },
+  );
+
+  debug.registerCommand(
+    RENDER_FAMILIES_COMMAND,
+    {
+      description:
+        'Meshes grouped by shared (geometry, material) identity, largest group first — the ' +
+        'instancing shortlist for a draw-call diet. `structural` is the same scan keyed by ' +
+        'VALUE instead of object identity: what would collapse under a <Frozen> wrapper ' +
+        '(vgai add static-batch) even when every mesh carries its own inline material.',
+      args: z.tuple([]),
+      locus: 'client',
+    },
+    // Two readings, deliberately: the identity families (what can be instanced
+    // as the scene stands) and the STRUCTURAL scan (what would collapse if the
+    // same draws were batched by value). A world writing inline materials —
+    // every fresh scaffold — has families of one and a large structural win,
+    // and reporting only the first would say "nothing to do" about the exact
+    // scene the `static-batch` capability exists for.
+    () => ({ ...meshFamilies(scene), structural: structuralBatchScan(scene) }),
+  );
+
+  debug.registerCommand(
+    RENDER_TOGGLE_COMMAND,
+    {
+      description:
+        'Show/hide a named subtree (as listed by render.census) and read render.vitals again — ' +
+        'the difference is what that subtree costs.',
+      args: z.tuple([z.string()]),
+      locus: 'client',
+    },
+    (name) => {
+      const node = findByName(scene, name);
+      if (!node) {
+        throw new Error(
+          `render.toggle: no node named "${name}" in this world. Run render.census to list the ` +
+            'addressable subtrees.',
+        );
+      }
+      node.visible = !node.visible;
+      return { name, visible: node.visible };
+    },
+  );
+
+  debug.registerCommand(
+    RENDER_DPR_COMMAND,
+    {
+      description:
+        'Set the renderer pixel ratio (retina default is ~2) to probe GPU fill cost — render CPU ' +
+        'that does not move when the drawing buffer shrinks was never fill-bound.',
+      args: z.tuple([z.number().positive().max(8)]),
+      locus: 'client',
+    },
+    (ratio) => {
+      if (!renderer) throw new Error(NO_RENDERER);
+      const size = renderer.getSize(new THREE.Vector2());
+      renderer.setPixelRatio(ratio);
+      // `updateStyle: false` — the CSS size is the layout's, not ours to
+      // change; only the drawing buffer moves, which is the whole experiment.
+      renderer.setSize(size.x, size.y, false);
+      return {
+        pixelRatio: renderer.getPixelRatio(),
+        drawingBuffer: { width: renderer.domElement.width, height: renderer.domElement.height },
+      };
+    },
+  );
+
+  // --- The static-batch advisory (issue #1503) -------------------------------
+  // A reading nobody asks for is a reading nobody gets, so the measurement
+  // routes itself: once the frame rate has settled, scan ONCE, and if this
+  // world is paying for draws it does not have to, name the exact wrapper on
+  // the console (`dev/static-batch-advisor.ts` owns the decision and the
+  // wording; this owns only WHEN).
+  //
+  // It rides the profiler subscription rather than a timer because the trigger
+  // is presented frames, not wall time: a tab that never presents (hidden,
+  // headless) should never scan, and a slow boot should not be measured before
+  // its assets are in the graph. The subscription ends itself the moment it
+  // fires or the advisory turns out to be `null`.
+  let stopAdvisor: (() => void) | null = null;
+  let advised = false;
+  const advisorTick = (): void => {
+    if (advised) return;
+    if (vitals.read().presentedFrames < ADVISOR_SETTLE_FRAMES) return;
+    advised = true;
+    stopAdvisor?.();
+    stopAdvisor = null;
+    const advisory = decideStaticBatchAdvisory({
+      drawCalls: vitals.read().drawCalls,
+      census: sceneCensus(scene),
+      structural: structuralBatchScan(scene),
+    });
+    if (advisory) warnStaticBatchAdvisory(advisory);
+  };
+  stopAdvisor = profiler.subscribe(advisorTick);
+
+  let disposed = false;
+  return {
+    vitals,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stopAdvisor?.();
+      stopAdvisor = null;
+      vitals.dispose();
+    },
+  };
+}