@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/dev/performance-profiler.ts

@@ -0,0 +1,213 @@
+export interface PerformanceTiming {
+  readonly name: string;
+  readonly ms: number;
+}
+
+export interface PerformanceFrame {
+  readonly id: number;
+  readonly timestamp: number;
+  readonly intervalMs: number;
+  readonly cpuMs: number;
+  readonly phases: readonly PerformanceTiming[];
+}
+
+export interface PerformanceSnapshot {
+  readonly enabled: boolean;
+  readonly recording: boolean;
+  readonly fps: number;
+  readonly cpuMs: number;
+  readonly p95Ms: number;
+  readonly p99Ms: number;
+  readonly frames: readonly PerformanceFrame[];
+  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;
+  };
+}
+
+const now = () => globalThis.performance?.now() ?? Date.now();
+
+function percentile(values: readonly number[], fraction: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))] ?? 0;
+}
+
+/** Game-owned, bounded external store for browser-native performance diagnostics. */
+export function createPerformanceProfiler(initiallyEnabled = false) {
+  const listeners = new Set<() => void>();
+  const frames: PerformanceFrame[] = [];
+  const currentPhases = new Map<string, number>();
+  const currentSystems = new Map<string, number>();
+  const currentComponents = new Map<string, number>();
+  let enabled = initiallyEnabled;
+  let recording = false;
+  let frameId = 0;
+  let frameStart = 0;
+  let lastFrameStart = 0;
+  let phaseStart = 0;
+  let systemStart = 0;
+  let componentStart = 0;
+  let render = {
+    gpuMs: null as number | null,
+    drawCalls: 0,
+    triangles: 0,
+    geometries: 0,
+    textures: 0,
+  };
+  let snapshot: PerformanceSnapshot = {
+    enabled,
+    recording,
+    fps: 0,
+    cpuMs: 0,
+    p95Ms: 0,
+    p99Ms: 0,
+    frames,
+    phases: [],
+    systems: [],
+    components: [],
+    render,
+  };
+
+  function publish(): void {
+    const latest = frames.at(-1);
+    const intervals = frames.map((frame) => frame.intervalMs).filter((value) => value > 0);
+    snapshot = {
+      enabled,
+      recording,
+      fps: latest?.intervalMs ? 1000 / latest.intervalMs : 0,
+      cpuMs: latest?.cpuMs ?? 0,
+      p95Ms: percentile(intervals, 0.95),
+      p99Ms: percentile(intervals, 0.99),
+      frames,
+      phases: latest?.phases ?? [],
+      systems: [...currentSystems].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+      components: [...currentComponents]
+        .map(([name, ms]) => ({ name, ms }))
+        .sort((a, b) => b.ms - a.ms),
+      render,
+    };
+    for (const listener of listeners) listener();
+  }
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    set enabled(value: boolean) {
+      if (enabled === value) return;
+      enabled = value;
+      publish();
+    },
+    get recording() {
+      return recording;
+    },
+    startRecording() {
+      enabled = true;
+      recording = true;
+      frames.length = 0;
+      publish();
+    },
+    stopRecording() {
+      recording = false;
+      publish();
+    },
+    clear() {
+      frames.length = 0;
+      publish();
+    },
+    beginFrame() {
+      if (!enabled) return;
+      currentPhases.clear();
+      currentSystems.clear();
+      currentComponents.clear();
+      render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
+      frameStart = now();
+    },
+    beginPhase() {
+      if (!enabled) return;
+      phaseStart = now();
+    },
+    endPhase(name: string) {
+      if (!enabled) return;
+      const elapsed = now() - phaseStart;
+      currentPhases.set(name, (currentPhases.get(name) ?? 0) + elapsed);
+      if (recording)
+        performance.measure(`vgai.phase.${name}`, { start: phaseStart, duration: elapsed });
+    },
+    systemObserver: {
+      beginSystem() {
+        if (!enabled) return;
+        systemStart = now();
+      },
+      endSystem(scope: string, phase: string, name: string) {
+        if (!enabled) return;
+        const end = now();
+        const key = `${scope} / ${phase} / ${name}`;
+        currentSystems.set(key, (currentSystems.get(key) ?? 0) + end - systemStart);
+      },
+    },
+    beginComponent() {
+      if (!recording) return;
+      componentStart = now();
+    },
+    endComponent(name: string) {
+      if (!recording) return;
+      currentComponents.set(name, (currentComponents.get(name) ?? 0) + now() - componentStart);
+    },
+    reportRender(stats: {
+      gpuMs: number | null;
+      drawCalls: number;
+      triangles: number;
+      geometries: number;
+      textures: number;
+    }) {
+      if (!enabled) return;
+      render = {
+        gpuMs: stats.gpuMs ?? render.gpuMs,
+        drawCalls: render.drawCalls + stats.drawCalls,
+        triangles: render.triangles + stats.triangles,
+        geometries: render.geometries + stats.geometries,
+        textures: render.textures + stats.textures,
+      };
+    },
+    endFrame() {
+      if (!enabled) return;
+      const timestamp = now();
+      const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
+      lastFrameStart = frameStart;
+      const frame: PerformanceFrame = {
+        id: ++frameId,
+        timestamp,
+        intervalMs,
+        cpuMs: timestamp - frameStart,
+        phases: [...currentPhases].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+      };
+      frames.push(frame);
+      if (frames.length > 600) frames.splice(0, frames.length - 600);
+      if (recording)
+        performance.measure('vgai.frame', { start: frameStart, duration: frame.cpuMs });
+      publish();
+    },
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    exportJSON() {
+      return JSON.stringify({ version: 1, capturedAt: new Date().toISOString(), frames }, null, 2);
+    },
+  };
+}
+
+export type PerformanceProfiler = ReturnType<typeof createPerformanceProfiler>;

package/src/dev/webgl-gpu-timer.ts

@@ -0,0 +1,53 @@
+interface DisjointTimerQueryExtension {
+  readonly TIME_ELAPSED_EXT: number;
+  readonly GPU_DISJOINT_EXT: number;
+}
+
+/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
+export function createWebGLGpuTimer(context: WebGLRenderingContext | WebGL2RenderingContext) {
+  const gl = context as WebGL2RenderingContext;
+  const extension = gl.getExtension(
+    'EXT_disjoint_timer_query_webgl2',
+  ) as DisjointTimerQueryExtension | null;
+  const supported = extension !== null && typeof gl.createQuery === 'function';
+  const pending: WebGLQuery[] = [];
+  let active: WebGLQuery | null = null;
+  let latestMs: number | null = null;
+
+  return {
+    begin() {
+      if (!supported || active) return;
+      active = gl.createQuery();
+      if (active) gl.beginQuery(extension!.TIME_ELAPSED_EXT, active);
+    },
+    end() {
+      if (!supported || !active) return;
+      gl.endQuery(extension!.TIME_ELAPSED_EXT);
+      pending.push(active);
+      active = null;
+    },
+    poll(): number | null {
+      if (!supported) return null;
+      if (gl.getParameter(extension!.GPU_DISJOINT_EXT)) {
+        for (const query of pending.splice(0)) gl.deleteQuery(query);
+        return null;
+      }
+      while (pending.length > 0) {
+        const query = pending[0]!;
+        if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) break;
+        pending.shift();
+        latestMs = (gl.getQueryParameter(query, gl.QUERY_RESULT) as number) / 1_000_000;
+        gl.deleteQuery(query);
+      }
+      return latestMs;
+    },
+    dispose() {
+      if (active) {
+        gl.endQuery(extension!.TIME_ELAPSED_EXT);
+        gl.deleteQuery(active);
+        active = null;
+      }
+      for (const query of pending.splice(0)) gl.deleteQuery(query);
+    },
+  };
+}

package/src/ecs/component-manager.ts

@@ -2,23 +2,28 @@ import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import { PHASE_ORDER, type SystemPhaseName } from '../core/types';
 import type { PhysicsRefs, PhysicsRegistry } from '../physics/physics-registry';
-import { isFirstPartyMounted, type WorldInstance, type WorldKind } from '../runtime/game';
+import { type AdapterSurface, isFirstPartyMounted, type WorldInstance } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
 import type { Physics2DRefs, Physics2DRegistry } from '../world2d/physics2d-registry';
-import { GameComponent, type GameComponentClass, type NodeOf } from './game-component';
+import {
+  GameComponent,
+  type GameComponentClass,
+  linkGameComponentHmrClasses,
+  type NodeOf,
+} from './game-component';
 import { logHmrSwapMiss } from './hmr-swap-report';
 
 /**
- * The manager's node/instance types, widened over every `WorldKind` (T7.2
- * slice 2, D8 §3). `NodeOf<WorldKind>` distributes to `THREE.Object3D |
+ * The manager's node/instance types, widened over every `AdapterSurface` (T7.2
+ * slice 2, D8 §3). `NodeOf<AdapterSurface>` distributes to `THREE.Object3D |
  * PIXI.Container` (react contributes `never`, which drops out of the
  * union) — this is what lets a single manager instance be constructed for
  * ANY one kind (threejs, pixijs, or react) while still type-checking
  * `attach()` calls made with a default-kind (`GameComponent`, K =
  * 'threejs') instance, unmodified, from every existing call site.
  */
-type AnyNode = NodeOf<WorldKind>;
-type AnyComponent = GameComponent<WorldKind>;
+type AnyNode = NodeOf<AdapterSurface>;
+type AnyComponent = GameComponent<AdapterSurface>;
 
 /**
  * Optional identity a caller of `attach()` can supply for a component instance
@@ -42,10 +47,10 @@ export interface RegistryAttachInfo {
  * ctx` identity (the same probe `isFirstPartyMounted` narrows for) rather
  * than by id, so it works unmodified whether this manager belongs to the
  * default world or a second/third registered world (`test/
- * game-two-worlds.test.ts`).
+ * game-two-roots.test.ts`).
  *
  * WORLD-WIRING STATE (T7.2 slice 2 — was a KNOWN GAP in slice 1, now closed
- * two ways): `ctx.game`/`ctx.worlds` exist from the start of `mount()`, but
+ * two ways): `ctx.game`/`ctx.roots` exist from the start of `mount()`, but
  * the `WorldInstance` itself is constructed by `registerThreeWorld` in
  * `create-runtime.ts` only AFTER `mount()` returns — i.e. AFTER
  * scene-authored components have already been attached by the scene loader
@@ -65,7 +70,7 @@ export interface RegistryAttachInfo {
  */
 function resolveWorldInstance(ctx: GameContext): WorldInstance | undefined {
   if (!ctx.game) return undefined;
-  for (const w of ctx.game.worlds) {
+  for (const w of ctx.game.roots) {
     if (isFirstPartyMounted(w.mounted) && w.mounted.ctx === ctx) return w;
   }
   return undefined;
@@ -98,7 +103,7 @@ function describeNode(node: AnyNode): string {
  * `test/system-runs-before-component-tick.test.ts`).
  *
  * Kind (T7.2 slice 2, D8 §3): a manager is constructed for exactly ONE
- * `WorldKind` (`opts.kind`, default `'threejs'` — every existing call site
+ * `AdapterSurface` (`opts.kind`, default `'threejs'` — every existing call site
  * omits it and gets the same manager slice 1 built). `attach()` enforces two
  * rules against that kind, loudly:
  *  - a `'react'`-kind manager throws on EVERY attach (react entities host no
@@ -118,9 +123,9 @@ function describeNode(node: AnyNode): string {
 export function createComponentManager(
   ctx: GameContext,
   physics?: PhysicsRegistry,
-  opts?: { kind?: WorldKind; physics2d?: Physics2DRegistry },
+  opts?: { kind?: AdapterSurface; physics2d?: Physics2DRegistry },
 ) {
-  const kind: WorldKind = opts?.kind ?? 'threejs';
+  const kind: AdapterSurface = opts?.kind ?? 'threejs';
   const physics2d = opts?.physics2d;
 
   const byPhase = new Map<SystemPhaseName, AnyComponent[]>();
@@ -322,9 +327,12 @@ export function createComponentManager(
           // flushed). Failures are loud — logged with the component name —
           // never swallowed silently.
           try {
+            ctx.game?.profiler.beginComponent();
             inst.update(dt, ctx);
           } catch (err) {
             console.error(`[component-manager] ${inst.constructor.name}.update() threw:`, err);
+          } finally {
+            ctx.game?.profiler.endComponent(inst.constructor.name);
           }
         }
       } finally {
@@ -362,6 +370,7 @@ export function createComponentManager(
     if (!isMatch) return false;
     const oldPhase = (inst.constructor as typeof GameComponent).phase ?? 'gameLogic';
     const newPhase = (NewClass as unknown as typeof GameComponent).phase ?? 'gameLogic';
+    linkGameComponentHmrClasses(inst.constructor as unknown as GameComponentClass, NewClass);
     Object.setPrototypeOf(inst, NewClass.prototype);
     migratePhase(inst, oldPhase, newPhase);
     reparseSchemaOnSwap(inst, NewClass, name);
@@ -601,6 +610,30 @@ export function createComponentManager(
       return byEntity.get(node) ?? [];
     },
 
+    /**
+     * Get the first attached instance of a given component class on an
+     * entity node — the typed single-component sibling of `getComponents`
+     * (issue #99: `onTriggerEnter`'s `other` is a raw node; this is how a
+     * handler asks "does my trigger partner have a `Collectible` (or
+     * whatever marker) component?" instead of an untyped `getComponents`
+     * walk or a fragile `other.name === '...'` display-name check).
+     * Matches via `instanceof`, so a subclass of `cls` is returned too
+     * (same subclass handling as `queryByComponent`). Same ordering as
+     * `getComponents` (attach order for that node) and, like
+     * `getComponents`, does NOT exclude instances pending-detach this tick
+     * — a caller inside a phase tick that cares should filter itself, same
+     * as any other `getComponents` consumer. `undefined` if the node has no
+     * attached instance of `cls`.
+     */
+    getComponent<T extends AnyComponent>(node: AnyNode, cls: new () => T): T | undefined {
+      const instances = byEntity.get(node);
+      if (!instances) return undefined;
+      for (const inst of instances) {
+        if (inst instanceof cls) return inst;
+      }
+      return undefined;
+    },
+
     /**
      * Query all live attached instances of a given component class within
      * THIS manager — the per-world half of the §5 cross-world query

package/src/ecs/game-component.ts

@@ -4,30 +4,30 @@ import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import type { z } from 'zod';
 import type { SystemPhaseName } from '../core/types';
-import type { WorldInstance, WorldKind } from '../runtime/game';
+import type { AdapterSurface, WorldInstance } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
 
 /**
- * Map a {@link WorldKind} to its native world node type (T7.2, D8 —
+ * Map a {@link AdapterSurface} to its native world node type (T7.2, D8 —
  * `docs/GAME-COMPONENT-GENERALIZATION.md` §2). `react` maps to `never`: react
  * entities host no GameComponents (they render from game state via the T7.4
  * state bridge instead).
  */
-export type NodeOf<K extends WorldKind> = K extends 'threejs'
+export type NodeOf<K extends AdapterSurface> = K extends 'threejs'
   ? THREE.Object3D
   : K extends 'pixijs'
     ? PIXI.Container
     : never;
 
-/** Map a {@link WorldKind} to its native Rapier rigid-body type. */
-export type BodyOf<K extends WorldKind> = K extends 'threejs'
+/** Map a {@link AdapterSurface} to its native Rapier rigid-body type. */
+export type BodyOf<K extends AdapterSurface> = K extends 'threejs'
   ? RAPIER3D.RigidBody
   : K extends 'pixijs'
     ? RAPIER2D.RigidBody
     : never;
 
-/** Map a {@link WorldKind} to its native Rapier collider type. */
-export type ColliderOf<K extends WorldKind> = K extends 'threejs'
+/** Map a {@link AdapterSurface} to its native Rapier collider type. */
+export type ColliderOf<K extends AdapterSurface> = K extends 'threejs'
   ? RAPIER3D.Collider
   : K extends 'pixijs'
     ? RAPIER2D.Collider
@@ -54,13 +54,97 @@ export type ColliderOf<K extends WorldKind> = K extends 'threejs'
  * State lives on `this` (instance properties). On HMR, the engine swaps the
  * prototype via Object.setPrototypeOf — instance state survives, method bodies
  * update to the new code.
+ *
+ * `update` is deliberately mandatory, not optional like `init`/`dispose`
+ * (owner decision, issue #101): components are for BEHAVIOR. If your
+ * subclass's `update(dt, ctx)` body is empty, that is a signal the class may
+ * not need to be a component at all — a plain state-holder with only
+ * `init`/event methods (score/hits counters, etc.) usually belongs as a
+ * plain object or a static-scenery/UI object instead (see the "GameComponents
+ * are for things with behavior only" rule).
+ */
+/**
+ * Cross-copy brand (`Symbol.for` is process-global, so every physical copy of
+ * the engine shares ONE symbol): `x.prototype instanceof GameComponent` is
+ * FALSE when a project resolves TWO copies of the engine at once — the
+ * published `@vgai/engine/*` subpaths next to the `@engine/*` source alias,
+ * exactly what a scaffolded project's node-side scripts do (meteor-dodge
+ * dry-run friction: `validate-scenes --components` reported every field of a
+ * pristine scaffold's `SceneCamera` as unknown). Structural checks
+ * (`isGameComponentClass`) test this brand as well as `instanceof`.
  */
-export abstract class GameComponent<K extends WorldKind = 'threejs'> {
+export const GAME_COMPONENT_BRAND = Symbol.for('vgai.GameComponent');
+
+/**
+ * HMR class lineage. A true component hot-swap deliberately replaces a live
+ * instance's prototype with the newly imported class, but other already-live
+ * project modules can still hold the previous class object. Native
+ * `instanceof PreviousClass` would then become false even though the object is
+ * still the same component under the same hot-reload lineage. That broke both
+ * ordinary trigger guards (`component instanceof PlayerController`) and the
+ * canonical React-state selector (`game.queryByComponent(PlayerController)`).
+ *
+ * Keep this as class-to-class lineage rather than a string/name registry:
+ * minified classes, aliases, and two unrelated components with the same name
+ * remain distinct. The WeakMap owns no game/entity state and introduces no
+ * second identity model; it records only the exact constructor pairs the
+ * existing HMR boundary has actually swapped.
+ */
+type HmrComponentConstructor = abstract new (...args: never[]) => object;
+
+const hmrLineages = new WeakMap<HmrComponentConstructor, Set<HmrComponentConstructor>>();
+
+/** @internal Called only by ComponentManager's successful HMR swap path. */
+export function linkGameComponentHmrClasses(
+  previous: HmrComponentConstructor,
+  next: HmrComponentConstructor,
+): void {
+  const previousLineage = hmrLineages.get(previous);
+  const nextLineage = hmrLineages.get(next);
+  const merged = new Set<HmrComponentConstructor>([previous, next]);
+  if (previousLineage) {
+    for (const member of previousLineage) merged.add(member);
+  }
+  if (nextLineage) {
+    for (const member of nextLineage) merged.add(member);
+  }
+  for (const member of merged) hmrLineages.set(member, merged);
+}
+
+function classesShareHmrLineage(a: HmrComponentConstructor, b: HmrComponentConstructor): boolean {
+  return a === b || hmrLineages.get(a)?.has(b) === true;
+}
+
+export abstract class GameComponent<K extends AdapterSurface = 'threejs'> {
   /** Which phase this component's update runs in. Override in subclasses. */
   static phase: SystemPhaseName = 'gameLogic';
 
+  /** See {@link GAME_COMPONENT_BRAND} — inherited by every subclass. */
+  static readonly [GAME_COMPONENT_BRAND] = true;
+
+  /**
+   * Preserve ordinary JavaScript `instanceof` across a true HMR prototype
+   * swap. Subclasses inherit this static hook, so `value instanceof
+   * PlayerController` first performs the native prototype-chain check and,
+   * only when that fails, accepts an exact constructor lineage previously
+   * linked by ComponentManager.hotSwap(). Non-HMR values retain byte-for-byte
+   * native semantics.
+   */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    // biome-ignore lint/complexity/noThisInStatic: Symbol.hasInstance is inherited; `this` must be the queried subclass, not the GameComponent base.
+    const expected = this as HmrComponentConstructor;
+    const nativeMatch = Function.prototype[Symbol.hasInstance].call(expected, value) as boolean;
+    if (nativeMatch) return true;
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return false;
+    const actual = (value as { constructor?: unknown }).constructor;
+    return (
+      typeof actual === 'function' &&
+      classesShareHmrLineage(expected, actual as HmrComponentConstructor)
+    );
+  }
+
   /**
-   * Runtime-checkable declaration of which {@link WorldKind} this component
+   * Runtime-checkable declaration of which {@link AdapterSurface} this component
    * is written for (T7.2, D8 §3 — `docs/GAME-COMPONENT-GENERALIZATION.md`).
    * TS's `K` type parameter is erased at runtime, so this static is what the
    * ComponentManager checks at attach time: a node whose world's kind
@@ -71,7 +155,7 @@ export abstract class GameComponent<K extends WorldKind = 'threejs'> {
    * any world components are legal in (every world except `'react'`, which
    * always throws regardless of `declaredKind` — see the ComponentManager).
    */
-  static declaredKind: WorldKind | 'any' = 'threejs';
+  static declaredKind: AdapterSurface | 'any' = 'threejs';
 
   /**
    * Optional Zod object schema for this component's authored fields. When set,
@@ -88,7 +172,7 @@ export abstract class GameComponent<K extends WorldKind = 'threejs'> {
   world!: WorldInstance;
 
   /**
-   * Typed accessor, threejs worlds only — kept for compatibility. On a
+   * Typed accessor, threejs roots only — kept for compatibility. On a
    * `GameComponent` (default `K`) this types as `THREE.Object3D`, so every
    * existing component compiles unchanged. On a non-threejs instance it
    * THROWS a descriptive error rather than ever returning a wrong-kind node —