@vgai/engine 0.2.0

package/src/adapter/vgai-scene-game-adapter.ts

@@ -0,0 +1,886 @@
+/**
+ * VgaiSceneGameAdapter — the FIRST-PARTY implementer of {@link GameAdapter}.
+ *
+ * This is where `.vscn` + `GameComponent` + Rapier live now: the host no longer
+ * knows about any of them. `mount(host)` builds the full first-party runtime
+ * (the body that used to live inline in `create-runtime.ts`) from a neutral
+ * {@link HostContext}, runs the game's `setup`/scene load, and returns a
+ * {@link MountedGame}. First-party content is now just one implementer of the
+ * same interface an unmodified external game implements (Phase B).
+ *
+ * `GameSetupFn` / `GameContext` are imported ONLY here (and in the example
+ * `fromSetup` wrappers) — never by the host. That confinement is the inversion.
+ */
+
+import RAPIER from '@dimforge/rapier3d-compat';
+import type { EffectComposer } from 'postprocessing';
+import * as THREE from 'three';
+import type { AnimGraph } from '../animation/anim-graph';
+import { animationSystem } from '../animation/anim-system';
+import { createSystemRunner } from '../core/system-runner';
+import { createDebugDraw } from '../dev/debug-draw';
+import { createComponentManager } from '../ecs/component-manager';
+import { InputManager } from '../input/input-manager';
+import { setAssetPrefix } from '../loader';
+import { createCollisionSystem } from '../physics/collision-system';
+import { createPhysicsRegistry } from '../physics/physics-registry';
+import { createTransformWriter } from '../physics/transform-writer';
+import { createTriggerDispatch } from '../physics/trigger-dispatch';
+import { RenderBatchSystem } from '../render/render-batch-system';
+import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
+import type { WorldFrameHooks } from '../runtime/game';
+import {
+  renderSceneUI,
+  type SceneUIDataSourceLike,
+  type SceneUIGameServices,
+  type SceneUIHandle,
+} from '../runtime/scene-ui-bridge';
+import { gameStateDataSource } from '../runtime/scene-ui-data';
+import type { EditorPreview, GameCleanup, GameContext, GameSetupFn } from '../runtime/types';
+import type { ComponentRegistry } from '../scene/component-registry';
+import { tickCustomMaterials } from '../scene/material-registry';
+import {
+  clearAssetCaches,
+  loadScene,
+  loadSceneFromData,
+  type SceneInstance,
+  updateSceneLODs,
+} from '../scene/scene-loader';
+import type { SceneFile } from '../scene/scene-types';
+import { hasUserData, setUserData } from '../scene/user-data';
+import { type AudioContext as GameAudio, setupAudio } from '../setup/setup-audio';
+import { setupParticles } from '../setup/setup-particles';
+import { setupPhysics, updatePhysicsDebug } from '../setup/setup-physics';
+import {
+  applyRendererSettings,
+  applyScenePostProcessing,
+  createSceneView,
+} from '../setup/setup-renderer';
+import {
+  createAnimationAdapter,
+  createAudioSystemAdapter,
+  createInputManagerAdapter,
+  createNavigationAdapter,
+  createVgaiAssetAdapter,
+} from './first-party-systems';
+import type { GameAdapter, MountedGame } from './game-adapter';
+import type { HostContext } from './host-context';
+import { createRapierPhysicsAdapter } from './rapier-physics-adapter';
+import type { SystemAdapters } from './system-adapter';
+
+/** How a {@link VgaiSceneGameAdapter} builds its game (the former RuntimeConfig). */
+export interface VgaiSceneConfig {
+  /** Game setup function — registers systems and loads scenes. */
+  setup?: GameSetupFn | undefined;
+  /** Editor context — passed to setup() when launched from the editor. */
+  editorPreview?: EditorPreview | undefined;
+  /** Path to a .vscn.json scene file. Loaded if no setup is provided. */
+  scenePath?: string | undefined;
+  /** In-memory scene data. Loaded if no setup and no scenePath is provided. */
+  sceneData?: SceneFile | undefined;
+  /**
+   * Component name -> GameComponent class map, threaded into the scene
+   * loader's `SceneLoadContext.componentRegistry` for both the `scenePath`
+   * and `sceneData` branches (never for `setup` — a custom setup already
+   * owns its own registry, e.g. `template/src/scripts/main.ts`'s generic
+   * fallback). Without this, a scene's `components:` entries throw
+   * ("Component ... not found in registry") or, pre-T7.2-closure, were
+   * simply unreachable through these two config options at all (the T7.2
+   * finding `docs/CLI-ON-FOLDER-DESIGN.md` §1D calls out — see
+   * `packages/editor/src/adapter-resolver.ts`, the only production caller
+   * that sets this today).
+   */
+  componentRegistry?: ComponentRegistry | undefined;
+  /**
+   * The project's scene-UI registry (design/24-scene-ui.md D9/D11) —
+   * `components`/`transforms`/`strings` only, opaque records engine-side (the
+   * engine never imports `@vgai/scene-ui`'s real `ProjectUIRegistry` type;
+   * they're React things it never inspects). Threaded per-mount into the
+   * services `renderSceneUI` receives, mirroring `componentRegistry` above:
+   * the editor's default-three adapter resolver passes its cached project
+   * registry here for the editor-play path (D11); a standalone host that
+   * already registered a static registry via `registerSceneUIRenderer`
+   * typically omits this (registration-time registry is enough there).
+   */
+  uiRegistry?:
+    | {
+        components?: Record<string, unknown>;
+        transforms?: Record<string, unknown>;
+        strings?: Record<string, Record<string, string>>;
+      }
+    | undefined;
+  /** Input map JSON path. Defaults to 'inputmaps/default.inputmap.json'. */
+  inputMapPath?: string | undefined;
+  /** URL prefix for relative asset paths. Defaults to '/'. */
+  assetPrefix?: string | undefined;
+  /** Stable adapter id (for registry/conformance). Defaults to 'vgai-scene'. */
+  id?: string | undefined;
+}
+
+/**
+ * The first-party `MountedGame`, with concrete extras the editor host uses for
+ * first-party features (HMR, physics sync) that are NOT part of the neutral
+ * interface. The generic host only touches the `MountedGame` surface.
+ */
+export interface VgaiMountedGame extends MountedGame {
+  /**
+   * First-party brand (checklist item 1 / T7.3 lookahead): a plain `'ctx' in
+   * mounted` structural check misfires once world2d's `MountedGame2D`
+   * (`world2d/pixi-game-adapter.ts`) also has a `ctx` key — its `ctx` is a
+   * `World2DContext`, not a `GameContext`, and has none of
+   * `queryByComponent`/`physics`/`collisions`/`camera`. This literal-`true`
+   * property is what `isFirstPartyMounted` (`runtime/game.ts`) actually
+   * checks; `game.ts` reads it via a structural `{ firstParty?: unknown }`
+   * probe so it never needs a value import of this module (the existing
+   * import is type-only and must stay that way).
+   */
+  readonly firstParty: true;
+  readonly ctx: GameContext;
+  readonly composer: EffectComposer | null;
+  /** Warm-restart: dispose the current game, re-run a new setup on the same ctx. */
+  hotReload(newSetup: GameSetupFn, editorPreview?: EditorPreview): Promise<void>;
+  /**
+   * Phase-partitioned frame entry point (T7.1 slice 2,
+   * `docs/GAME-ROOT-DESIGN.md` §4) — wired onto this world's `WorldInstance`
+   * by `registerDefaultThreeWorld` (`create-runtime.ts`). `Game.runFrame` is
+   * the CANONICAL driver going forward: it calls `frame.runPhase` once per
+   * (phase, substep) for every world, then `frame.endFrame` once per
+   * substep after all worlds finish all phases. `update` (below) remains
+   * the legacy/direct entry point to the exact same `SystemRunner` — direct
+   * callers (editor HMR, adapter conformance tests) keep using it unchanged.
+   */
+  readonly frame: WorldFrameHooks;
+}
+
+/** Minimal stand-in for the GPU composer when mounting headlessly. */
+function headlessComposer(renderer: THREE.WebGLRenderer): EffectComposer {
+  return {
+    render: () => {},
+    setSize: () => {},
+    dispose: () => {},
+    addPass: () => {},
+    removeAllPasses: () => {},
+    passes: [],
+    getRenderer: () => renderer,
+  } as unknown as EffectComposer;
+}
+
+/**
+ * Wrap a first-party `setup` function as a {@link GameAdapter}. This is how every
+ * first-party example becomes an implementer of the same interface an external
+ * game implements — with no change to the setup's body.
+ */
+export function fromSetup(id: string, setup: GameSetupFn): GameAdapter {
+  return new VgaiSceneGameAdapter({ id, setup });
+}
+
+export class VgaiSceneGameAdapter implements GameAdapter {
+  readonly id: string;
+  constructor(private readonly config: VgaiSceneConfig = {}) {
+    this.id = config.id ?? 'vgai-scene';
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive first-party bootstrap (moved verbatim from create-runtime); splitting it would obscure the ordering contract
+  async mount(host: HostContext): Promise<VgaiMountedGame> {
+    const {
+      setup,
+      editorPreview,
+      scenePath,
+      sceneData,
+      componentRegistry,
+      uiRegistry,
+      inputMapPath = '/inputmaps/default.inputmap.json',
+      assetPrefix = '/',
+    } = this.config;
+    const headless = host.headless === true;
+    const { width, height } = host.surface;
+    const renderer = host.renderer;
+
+    setAssetPrefix(assetPrefix);
+
+    // --- Scene view (scene/camera/composer). Browser: the canonical builder, so
+    //     behavior is byte-identical to the old create-runtime. Headless: plain
+    //     scene/camera + a no-op composer (no GPU). ---
+    let scene: THREE.Scene;
+    let camera: THREE.PerspectiveCamera;
+    let composer: EffectComposer;
+    if (headless) {
+      scene = new THREE.Scene();
+      scene.background = new THREE.Color(0x1a1a2e);
+      camera = new THREE.PerspectiveCamera(60, width / height || 1, 0.1, 1000);
+      camera.position.set(0, 5, 10);
+      camera.lookAt(0, 0, 0);
+      composer = headlessComposer(renderer);
+    } else {
+      const view = createSceneView(renderer, width, height);
+      scene = view.scene;
+      camera = view.camera;
+      composer = view.composer;
+    }
+
+    // --- Rapier physics ---
+    await RAPIER.init();
+    const physics = setupPhysics(RAPIER, scene);
+    const physicsRegistry = createPhysicsRegistry();
+    const writeTransforms = createTransformWriter(physicsRegistry, scene);
+
+    // --- Input (InputManager attaches window listeners; stub it headlessly) ---
+    const input = headless ? headlessInput() : new InputManager();
+    if (!headless) await input.loadMap(inputMapPath);
+
+    // --- Collision system ---
+    const collisions = createCollisionSystem(physics.rapierWorld, physics.eventQueue);
+
+    // --- Audio (Web Audio — browser only) ---
+    const audio = headless ? headlessAudio() : setupAudio(camera);
+
+    // --- Particles (three.quarks BatchedRenderer) ---
+    const particles = setupParticles(scene);
+
+    // --- UI container (host-provided) ---
+    const uiContainer = host.ui as HTMLDivElement;
+
+    // --- Debug draw / assets / anim graphs ---
+    const debugDraw = createDebugDraw(scene);
+    const assets = host.assets;
+    const animGraphs = new Map<THREE.Object3D, AnimGraph>();
+
+    // --- System runner (engine-level systems) ---
+    const systems = createSystemRunner();
+    systems.add('input', () => input.poll());
+    systems.add('physics', () => physics.rapierWorld.step(physics.eventQueue));
+    systems.add('postPhysics', () => {
+      collisions.drain();
+      writeTransforms();
+    });
+    systems.add('animation', (dt) => animationSystem(animGraphs, dt));
+    systems.add('preRender', (dt) => {
+      particles.batchedRenderer.update(dt);
+      tickCustomMaterials(scene, dt);
+      updateSceneLODs(scene, camera);
+    });
+    if (!headless) {
+      systems.add('render', (dt) => {
+        composer.render(dt);
+        if (physics.debugEnabled) updatePhysicsDebug(physics.rapierWorld, physics.debugMesh);
+      });
+    }
+
+    // --- Debug toggle (browser only) ---
+    const onDebugToggle = (e: KeyboardEvent) => {
+      if (e.code === 'KeyP') {
+        physics.debugEnabled = !physics.debugEnabled;
+        physics.debugMesh.visible = physics.debugEnabled;
+      }
+    };
+    if (!headless) window.addEventListener('keydown', onDebugToggle);
+
+    const postFrame = () => input.endFrame();
+
+    // The mounted game's adapter surface (`mounted.systems`). Declared before
+    // ctx so `ctx.registerSystemAdapter` can close over it: the engine fills
+    // the first-party entries below; GAME-owned capabilities (networking,
+    // navigation) are registered by the game's setup through the ctx hook.
+    // The editor holds this same object reference (setActiveSystems), so
+    // late registrations are visible to its panels at read time.
+    const systemAdapters: SystemAdapters = {};
+
+    // Game-registered scene-UI services (design/24-scene-ui.md D2/D7) — a `let`
+    // bag mutated by `ctx.setSceneUIServices`, declared here (BEFORE `ctx` is
+    // built) so the closure below has something to capture: a GameComponent
+    // calling `ctx.setSceneUIServices` from its `init()` runs DURING
+    // `componentManager.initAll()` (scene-loader.ts), which is awaited before
+    // `loadScene`/`loadFromData` return below — well before `sceneUIHandle`
+    // exists — so early calls just accumulate here and are folded into the
+    // FIRST render (`buildSceneUIServices`, below) rather than routed through
+    // the late-update path.
+    let sceneUIServices: SceneUIGameServices = {};
+
+    // --- GameContext (the first-party runtime surface) ---
+    const ctx: GameContext = {
+      scene,
+      camera,
+      rapierWorld: physics.rapierWorld,
+      rapier: RAPIER,
+      physics: physicsRegistry,
+      input,
+      collisions,
+      composer,
+      audio,
+      particles,
+      debugDraw,
+      animGraphs,
+      assets,
+      systems,
+      components: null!,
+      uiContainer,
+      registerSystemAdapter: (kind, adapter) => {
+        systemAdapters[kind] = adapter;
+      },
+      setSceneUIServices: (incoming) => {
+        sceneUIServices = { ...sceneUIServices, ...incoming };
+        // Late call (after the initial mount already resolved a sceneInstance
+        // and rendered it): route to the live handle instead of just banking
+        // the services for a mount that already happened (D7).
+        if (sceneUIHandle && sceneInstance) {
+          const merged = buildSceneUIServices(sceneInstance);
+          if (sceneUIHandle.update) {
+            sceneUIHandle.update(merged);
+          } else {
+            sceneUIHandle.dispose();
+            sceneUIHandle = sceneInstance.ui
+              ? renderSceneUI(uiContainer, sceneInstance.ui, merged)
+              : null;
+          }
+        }
+      },
+    };
+    // Game root (T7.1 slice 1): only present once the host has constructed a
+    // Game shell (createGameRuntime does this before mount; headless/foreign
+    // hosts may omit it — ctx.game/ctx.worlds simply stay undefined, which is
+    // the documented zero-break behavior). `ctx.worlds` is assigned the SAME
+    // live array `host.game` mutates via `registerWorld` (not a copy) — the
+    // default world is registered AFTER mount returns, and this reference
+    // must observe that later push.
+    if (host.game) {
+      ctx.game = host.game;
+      ctx.worlds = host.game.worlds;
+    }
+    ctx.components = createComponentManager(ctx, physicsRegistry);
+    collisions.onCollision(
+      createTriggerDispatch(physicsRegistry, ctx.components, physics.rapierWorld, ctx),
+    );
+
+    // Everything registered above (engine systems + the ComponentManager's
+    // per-phase tick, just wired in) is "engine" and must survive a warm
+    // restart. Everything a game (setup()/scenePath/sceneData, below) adds
+    // from here on is "game" content that `hotReload` bulk-removes via
+    // `systems.removeAllNonEngine()` on every restart (T1.7).
+    systems.markEngineBoundary();
+
+    // First-party System adapters over the real subsystems — seeded HERE,
+    // BEFORE setup()/scene load runs below, so that a game which registers any
+    // of these kinds during its own setup (via `ctx.registerSystemAdapter`)
+    // always wins over the engine's first-party entry (see
+    // registerSystemAdapter's docstring in runtime/types.ts). `navigation` is
+    // ALSO first-party now (R8 item 7): `createNavigationAdapter` wraps the
+    // real `NavMeshManager` a scenePath/sceneData scene load may produce (see
+    // `applySceneNavigation` below) — it is wired once that scene instance
+    // resolves, not here (no NavMeshManager exists yet at this point in the
+    // mount). `networking` remains the one game-owned capability with no
+    // first-party implementer; it simply starts absent here.
+    systemAdapters.physics = createRapierPhysicsAdapter(physicsRegistry, physics.debugMesh);
+    systemAdapters.input = createInputManagerAdapter(input);
+    systemAdapters.assets = createVgaiAssetAdapter();
+    systemAdapters.animation = createAnimationAdapter(animGraphs);
+    // D10/T7.6: the audio seam `Game.play.pause()` silences on pause. Works
+    // against the headless stand-in too (`headlessAudio()`'s plain
+    // `masterGain.gain` object) — this world's `pause()` mutes it harmlessly.
+    systemAdapters.audio = createAudioSystemAdapter(audio);
+
+    // Snapshot of the engine-owned adapter kinds, taken right after seeding
+    // and before any setup() has had a chance to run. `hotReload`/`disposeGame`
+    // use this to strip every GAME-registered kind (including an override of a
+    // first-party kind) left over from the outgoing game, so a warm restart or
+    // a full stop never exposes a disposed game's networking/etc. adapter to
+    // the next setup.
+    const engineAdapterKinds = new Set(Object.keys(systemAdapters));
+    // 'navigation' is engine-owned too (R8 item 7), but the scene load that
+    // populates it (below, `applySceneNavigation`) happens AFTER this
+    // snapshot — add it explicitly so the generic "strip every non-engine
+    // kind" step (hotReload/disposeGame) never mistakes a first-party
+    // navigation adapter for game-registered content and deletes it. (The
+    // adapter is still kept in sync with the CURRENT scene's NavMeshManager
+    // via the dedicated `clear navigation adapter` teardown step below, which
+    // runs independently of this snapshot.)
+    engineAdapterKinds.add('navigation');
+
+    // --- Scene / game setup ---
+    const engineSceneChildren = new Set(scene.children.slice());
+    // Tag engine-owned infra (particle BatchedRenderer, debug-draw + subtrees) so
+    // the editor's play-mode hierarchy skips them — they're not game entities.
+    for (const c of engineSceneChildren) {
+      c.traverse((n) => setUserData(n, 'engineInternal', true));
+    }
+    let currentCleanup: GameCleanup | null = null;
+    let sceneUIHandle: SceneUIHandle | null = null;
+    let batchSystem: RenderBatchSystem | null = null;
+    // The scenePath/sceneData branch's resolved SceneInstance, if either ran
+    // (stays undefined for a `setup`-based mount — see the `sceneUI` deriva-
+    // tion below). Single source of truth for both the scene-graph `ui` tree
+    // and (potentially, in future) other instance-derived wiring.
+    let sceneInstance: SceneInstance | undefined;
+
+    // Apply scene-level render settings + transparent auto-batching after a scene
+    // loads (GPU host only). Gated on the resolved `environment.rendering` cascade
+    // (defaults preserve prior behavior when a scene omits `rendering`).
+    const applySceneRendering = (inst: SceneInstance): void => {
+      if (headless) return;
+      const scope = inst.environment?.rendering as RenderScope | undefined;
+      const settings = resolveRenderSettings(scope);
+      // live renderer settings (shadows, resolution scale)
+      applyRendererSettings(renderer, scope);
+      // post-processing master switch: (re)build when the scene defines effects OR
+      // the master is off (to strip the default bloom pass down to a plain scene).
+      if (inst.environment?.postProcessing || !settings['postProcessing']) {
+        applyScenePostProcessing(composer, renderer, scene, camera, inst.environment);
+      }
+      // transparent batching: collapse static/mover meshes sharing a signature
+      if (settings['autoBatch']) {
+        batchSystem = new RenderBatchSystem(scene, settings);
+        batchSystem.build();
+        ctx.systems.add('preRender', () => batchSystem?.update());
+        if (import.meta.env?.DEV)
+          (window as unknown as { __vgaiBatch?: unknown }).__vgaiBatch = batchSystem;
+      }
+    };
+
+    // Wire the (first-party) navigation system adapter to whichever
+    // NavMeshManager the CURRENT scene instance carries — reassigned on every
+    // scene load, and explicitly cleared (not just left stale) when the new
+    // scene has none, so `mounted.systems.navigation` never lingers pointing
+    // at a manager a later teardown step disposes (R8 item 7).
+    const applySceneNavigation = (inst: SceneInstance): void => {
+      if (inst.navMesh) {
+        systemAdapters.navigation = createNavigationAdapter(inst.navMesh);
+      } else {
+        delete systemAdapters.navigation;
+      }
+    };
+
+    // Scratch vector for the D5 default worldProjector — reused across calls
+    // (one per bound world-tracked canvas per render), never allocated per-frame.
+    const _sceneUIProjectorTmp = new THREE.Vector3();
+
+    // The D4 default data source subscribes to game.state for its whole
+    // lifetime with no unsubscribe path, so it must be built at most ONCE per
+    // adapter mount — buildSceneUIServices runs again on every late
+    // setSceneUIServices call, and rebuilding it there would both leak a
+    // subscription and force every bound node to resubscribe to a fresh store.
+    let defaultSceneUIData: SceneUIDataSourceLike | undefined;
+
+    /**
+     * Assemble the services `renderSceneUI` receives (design/24-scene-ui.md
+     * D2): engine defaults (D4 data source, D5 worldProjector, D6 onEvent) <-
+     * the project's per-mount UI registry (D11, editor-play threading) <-
+     * game-registered services (`ctx.setSceneUIServices`) — per key, each
+     * later layer winning over the one before it.
+     */
+    const buildSceneUIServices = (inst: SceneInstance): SceneUIGameServices => {
+      const defaults: SceneUIGameServices = {
+        onEvent: (handlerId) => {
+          console.warn(
+            `scene-ui: unhandled UI event "${handlerId}" — register onEvent via ctx.setSceneUIServices`,
+          );
+        },
+        worldProjector: (id) => {
+          const obj = inst.entities.get(id);
+          if (!obj) return null;
+          const projected = obj.getWorldPosition(_sceneUIProjectorTmp).project(camera);
+          if (projected.z > 1) return null; // behind the camera -> hidden
+          const w = uiContainer.clientWidth;
+          const h = uiContainer.clientHeight;
+          // Rounded (not sub-pixel) — matches CrtScreen's integer-rounding
+          // (crt-screen.ts), which exists specifically to stop an asymptotic
+          // camera lerp from shimmering a tracked canvas every frame.
+          return {
+            x: Math.round(((projected.x + 1) / 2) * w),
+            y: Math.round(((1 - projected.y) / 2) * h),
+          };
+        },
+      };
+      // Lazily and at-most-once; skipped entirely while the game supplies its
+      // own `data` service (no point subscribing a default nobody reads).
+      if (!sceneUIServices.data && ctx.game && componentRegistry) {
+        defaultSceneUIData ??= gameStateDataSource(ctx.game, componentRegistry);
+        defaults.data = defaultSceneUIData;
+      }
+      const registryPortion: SceneUIGameServices = {
+        ...(uiRegistry?.components ? { components: uiRegistry.components } : {}),
+        ...(uiRegistry?.transforms ? { transforms: uiRegistry.transforms } : {}),
+        ...(uiRegistry?.strings ? { strings: uiRegistry.strings } : {}),
+      };
+      return { ...defaults, ...registryPortion, ...sceneUIServices };
+    };
+
+    const loadFromData = async (data: SceneFile): Promise<SceneInstance> => {
+      const inst = await loadSceneFromData(data, {
+        scene,
+        rapierWorld: ctx.rapierWorld,
+        rapier: ctx.rapier,
+        physics: ctx.physics,
+        audioListener: ctx.audio.listener,
+        animGraphs: ctx.animGraphs,
+        ...(componentRegistry ? { componentRegistry } : {}),
+        componentManager: ctx.components,
+        particleRenderer: ctx.particles.batchedRenderer,
+        ...(headless ? {} : { renderer }),
+      });
+      applySceneRendering(inst);
+      applySceneNavigation(inst);
+      ctx.systems.add('postPhysics', (dt) => inst.update(dt));
+      return inst;
+    };
+
+    if (setup) {
+      if (headless) throw new Error('VgaiSceneGameAdapter: setup-based games require a GPU host');
+      currentCleanup = await setup(ctx, editorPreview);
+    } else if (scenePath) {
+      const inst = await loadScene(scenePath, {
+        scene,
+        rapierWorld: ctx.rapierWorld,
+        rapier: ctx.rapier,
+        physics: ctx.physics,
+        audioListener: ctx.audio.listener,
+        animGraphs: ctx.animGraphs,
+        ...(componentRegistry ? { componentRegistry } : {}),
+        componentManager: ctx.components,
+        particleRenderer: ctx.particles.batchedRenderer,
+        ...(headless ? {} : { renderer }),
+      });
+      applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera);
+      applySceneRendering(inst);
+      applySceneNavigation(inst);
+      ctx.systems.add('postPhysics', (dt) => inst.update(dt));
+      sceneInstance = inst;
+      // A pre-baked navmesh (sibling .navmesh file — see scene-loader.ts) holds
+      // live recast-navigation WASM handles that leak unless destroyed
+      // explicitly; dispose it alongside the scene instance on teardown.
+      currentCleanup = {
+        dispose: () => {
+          inst.navMesh?.dispose(scene);
+          inst.dispose();
+        },
+      };
+    } else if (sceneData) {
+      const inst = await loadFromData(sceneData);
+      applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera);
+      sceneInstance = inst;
+      currentCleanup = {
+        dispose: () => {
+          inst.navMesh?.dispose(scene);
+          inst.dispose();
+        },
+      };
+    }
+
+    // Render scene-graph UI (the `ui` tree) into the overlay via the injected React
+    // renderer (B1). Sourced from the loaded `SceneInstance` — the single source of
+    // truth for BOTH the scenePath and sceneData branches (R8 item 7 / B: previously
+    // only sceneData's raw `SceneFile.ui` was read via a `resolvedSceneData` special-
+    // case, so a scenePath mount's `ui` tree was silently dropped even though
+    // `loadScene` fully parses it). A `setup`-based mount has no `sceneInstance` at
+    // all — its game owns any UI mounting itself. No-op if no UI or no renderer
+    // registered. Engine stays React-free.
+    const sceneUI = sceneInstance?.ui;
+    if (sceneUI && sceneInstance && !headless) {
+      sceneUIHandle = renderSceneUI(uiContainer, sceneUI, buildSceneUIServices(sceneInstance));
+    }
+
+    // Idempotency guard for disposeGame — see below. Declared here (not inside
+    // disposeGame) so hotReload can also refuse to run on an already-disposed
+    // adapter.
+    let disposed = false;
+
+    // Run one teardown step in isolation: a throwing step (e.g. a
+    // GameComponent's dispose() misbehaving, or a WASM free() panicking) must
+    // not abort the remaining steps — otherwise a single bad component leaks
+    // the Rapier world and skips input.dispose() with no way to retry (a
+    // second call is a no-op once `disposed` is set). Logs and continues.
+    const safeStep = (label: string, fn: () => void): void => {
+      try {
+        fn();
+      } catch (err) {
+        console.error(`VgaiSceneGameAdapter: teardown step "${label}" threw (continuing)`, err);
+      }
+    };
+
+    const disposeGame = (): void => {
+      // A second stop() must be a safe no-op — do NOT double-free the Rapier
+      // world/EventQueue (WASM handles panic/throw on a second free) or
+      // double-run teardown side effects.
+      if (disposed) return;
+      disposed = true;
+
+      safeStep('batchSystem.teardown', () => {
+        batchSystem?.teardown(); // re-attach detached sources before scene teardown
+        batchSystem = null;
+      });
+      safeStep('currentCleanup.dispose', () => {
+        currentCleanup?.dispose();
+        currentCleanup = null;
+      });
+      // The scene instance's NavMeshManager (if any) was just disposed above
+      // (currentCleanup.dispose calls `inst.navMesh?.dispose(scene)`) — clear
+      // the wrapper too, or `mounted.systems.navigation` would keep pointing
+      // at a freed manager (R8 item 7). Unconditional: harmless if navigation
+      // was never set.
+      safeStep('clear navigation adapter', () => {
+        delete systemAdapters.navigation;
+      });
+      if (!headless) {
+        safeStep('removeEventListener(keydown)', () =>
+          window.removeEventListener('keydown', onDebugToggle),
+        );
+      }
+
+      // Components BEFORE the physics world is freed/bodies are removed: a
+      // GameComponent's dispose() may read `this.rigidBody`/`this.collider`
+      // (see game-component.ts) — freeing the world first would make those
+      // dangling WASM references. Isolated: a throwing component dispose must
+      // not prevent the world/eventQueue frees or input.dispose() below.
+      safeStep('components.clear', () => ctx.components.clear());
+
+      safeStep('remove rigid bodies', () => {
+        const handles: number[] = [];
+        physics.rapierWorld.forEachRigidBody((b) => handles.push(b.handle));
+        for (const h of handles) {
+          const b = physics.rapierWorld.getRigidBody(h);
+          if (b) physics.rapierWorld.removeRigidBody(b);
+        }
+      });
+      safeStep('rapierWorld.free', () => physics.rapierWorld.free());
+      safeStep('eventQueue.free', () => physics.eventQueue.free()); // WASM handle — must be freed manually
+      safeStep('physicsRegistry.clear', () => physicsRegistry.clear());
+
+      safeStep('scene children dispose', () => {
+        for (const obj of [...scene.children]) {
+          scene.remove(obj);
+          obj.traverse((node) => {
+            if (node instanceof THREE.Mesh) {
+              if (!hasUserData(node, '__sharedGeometry')) node.geometry?.dispose();
+              if (Array.isArray(node.material))
+                node.material.forEach((m) => {
+                  m.dispose();
+                });
+              else node.material?.dispose();
+            }
+          });
+        }
+        scene.fog = null;
+        scene.background = null;
+        scene.environment = null;
+      });
+      safeStep('clearAssetCaches', () => clearAssetCaches());
+      safeStep('debugDraw.clear', () => debugDraw.clear());
+      safeStep('animGraphs.clear', () => animGraphs.clear());
+      safeStep('sceneUIHandle.dispose', () => {
+        sceneUIHandle?.dispose();
+        sceneUIHandle = null;
+      });
+      safeStep('uiContainer reset', () => {
+        uiContainer.innerHTML = '';
+      });
+
+      // R8 item 7 (C) — disposeGame (Stop) used to skip both of these, unlike
+      // hotReload (warm restart), which already ran them: a game lifecycle
+      // system registered via `ctx.systems.register(...)` never had its
+      // `dispose()` hook called on a full Stop, and a game-registered
+      // systemAdapters kind (e.g. a `setup`-registered 'networking') survived
+      // a Stop and would be visible on a STALE `mounted.systems` even though
+      // the game that owned it is gone. Same two steps, same relative
+      // ordering as hotReload (right after `uiContainer reset`, before the
+      // engine-owned audio/input teardown below, which hotReload doesn't
+      // touch at all since it warm-restarts rather than tearing engine
+      // subsystems down).
+      safeStep('systems.removeAllNonEngine', () => systems.removeAllNonEngine());
+      safeStep('strip game-registered systemAdapters', () => {
+        for (const kind of Object.keys(systemAdapters)) {
+          if (!engineAdapterKinds.has(kind)) delete systemAdapters[kind as keyof SystemAdapters];
+        }
+      });
+
+      if (!headless) {
+        safeStep('audio teardown', () => {
+          audio.masterGain.gain.value = 0;
+          audio.listener.context.suspend();
+          camera.remove(audio.listener);
+          composer.dispose();
+        });
+      }
+      safeStep('input.dispose', () => input.dispose());
+    };
+
+    const hotReload = async (
+      newSetup: GameSetupFn,
+      newEditorPreview?: EditorPreview,
+    ): Promise<void> => {
+      if (disposed) {
+        throw new Error('VgaiSceneGameAdapter: cannot hotReload after dispose()/stop()');
+      }
+
+      // Full parity with disposeGame for the parts a warm restart rebuilds:
+      // batch-render teardown, game cleanup, component batch teardown (in that
+      // ordering, BEFORE bodies are pulled from the world — see disposeGame),
+      // scene-UI dispose (React root unmount), and bulk system removal. Each
+      // step isolated the same way as disposeGame — one throwing step (e.g. a
+      // component dispose) must not abort the rest of the warm restart.
+      safeStep('batchSystem.teardown', () => {
+        batchSystem?.teardown(); // re-attach detached sources before scene teardown
+        batchSystem = null;
+      });
+      safeStep('currentCleanup.dispose', () => {
+        currentCleanup?.dispose();
+        currentCleanup = null;
+      });
+      // Same reasoning as disposeGame: the outgoing scene instance's
+      // NavMeshManager was just disposed above, and `hotReload`'s `newSetup`
+      // (below) never auto-wires a replacement (that only happens for THIS
+      // adapter's own scenePath/sceneData mount, once, at initial mount) — so
+      // clear the stale wrapper here. A `newSetup` that wants navigation may
+      // register its own via `ctx.registerSystemAdapter('navigation', ...)`.
+      safeStep('clear navigation adapter', () => {
+        delete systemAdapters.navigation;
+      });
+
+      safeStep('components.clear', () => ctx.components.clear());
+
+      safeStep('remove rigid bodies', () => {
+        const handles: number[] = [];
+        physics.rapierWorld.forEachRigidBody((b) => handles.push(b.handle));
+        for (const h of handles) {
+          const b = physics.rapierWorld.getRigidBody(h);
+          if (b) physics.rapierWorld.removeRigidBody(b);
+        }
+        physicsRegistry.clear();
+      });
+      safeStep('scene children dispose', () => {
+        for (const obj of [...scene.children]) {
+          if (engineSceneChildren.has(obj)) continue;
+          scene.remove(obj);
+          obj.traverse((node) => {
+            if (node instanceof THREE.Mesh) {
+              if (!hasUserData(node, '__sharedGeometry')) node.geometry?.dispose();
+              if (Array.isArray(node.material))
+                node.material.forEach((m) => {
+                  m.dispose();
+                });
+              else node.material?.dispose();
+            }
+          });
+        }
+        scene.fog = null;
+        scene.background = null;
+        scene.environment = null;
+      });
+      safeStep('debugDraw.clear', () => debugDraw.clear());
+      safeStep('animGraphs.clear', () => animGraphs.clear());
+      safeStep('sceneUIHandle.dispose', () => {
+        sceneUIHandle?.dispose();
+        sceneUIHandle = null;
+      });
+      // Strip game-registered scene-UI services back to none before the
+      // incoming game's setup/init runs (D7) — same contract as the
+      // systemAdapters strip below: a disposed game's onEvent/data/
+      // worldProjector must never leak onto the next mount.
+      safeStep('reset sceneUIServices', () => {
+        sceneUIServices = {};
+      });
+      safeStep('uiContainer reset', () => {
+        uiContainer.innerHTML = '';
+      });
+
+      // Bulk-remove every system the outgoing game registered (this restart's
+      // predecessor) so warm restarts never accumulate duplicate systems —
+      // engine systems registered before mount()'s boundary mark are untouched.
+      safeStep('systems.removeAllNonEngine', () => systems.removeAllNonEngine());
+
+      // Strip every GAME-registered systemAdapters kind left by the outgoing
+      // game (including any override of a first-party kind) so the disposed
+      // game's networking/etc. adapter is never exposed to the next setup —
+      // see registerSystemAdapter's docstring in runtime/types.ts. ('navigation'
+      // is engine-kind and is NOT touched here — it's a first-party adapter now,
+      // kept in sync with the current scene's NavMeshManager by the dedicated
+      // `clear navigation adapter` step above instead.) The new setup below
+      // either re-registers a kind or it stays absent.
+      safeStep('strip game-registered systemAdapters', () => {
+        for (const kind of Object.keys(systemAdapters)) {
+          if (!engineAdapterKinds.has(kind)) delete systemAdapters[kind as keyof SystemAdapters];
+        }
+      });
+
+      currentCleanup = await newSetup(ctx, newEditorPreview);
+    };
+
+    return {
+      kind: 'threejs',
+      scene,
+      camera,
+      firstParty: true,
+      drivesOwnLoop: false,
+      update: (dt: number) => {
+        systems.run(dt);
+        postFrame();
+      },
+      resize: (w: number, h: number) => {
+        composer.setSize(w, h);
+        camera.aspect = w / h;
+        camera.updateProjectionMatrix();
+      },
+      dispose: disposeGame,
+      systems: systemAdapters,
+      ctx,
+      composer: headless ? null : composer,
+      hotReload,
+      frame: {
+        runPhase: (phase, dt) => systems.runPhase(phase, dt),
+        endFrame: postFrame,
+      },
+    };
+  }
+}
+
+// --- Camera precedence helpers (moved from create-runtime, unchanged) ---
+
+function applyEditorCamera(
+  editor: EditorPreview | undefined,
+  runtimeCamera: THREE.PerspectiveCamera,
+): boolean {
+  if (!editor?.viewportCamera) return false;
+  runtimeCamera.position.fromArray(editor.viewportCamera.position);
+  runtimeCamera.quaternion.fromArray(editor.viewportCamera.quaternion);
+  return true;
+}
+
+export function adoptSceneCamera(
+  sceneInstance: SceneInstance,
+  runtimeCamera: THREE.PerspectiveCamera,
+): boolean {
+  const sceneCam = sceneInstance.cameras[0];
+  if (!sceneCam) return false;
+  const parent = sceneCam.parent;
+  if (parent) {
+    parent.updateMatrixWorld(true);
+    runtimeCamera.position.copy(parent.getWorldPosition(new THREE.Vector3()));
+    runtimeCamera.quaternion.copy(parent.getWorldQuaternion(new THREE.Quaternion()));
+  }
+  if (sceneCam instanceof THREE.PerspectiveCamera) {
+    runtimeCamera.fov = sceneCam.fov;
+    runtimeCamera.near = sceneCam.near;
+    runtimeCamera.far = sceneCam.far;
+    runtimeCamera.updateProjectionMatrix();
+  }
+  return true;
+}
+
+/** Headless input stand-in — `InputManager` attaches `window` listeners in its
+ *  constructor, which Node lacks. The scene-data path never reads input. */
+function headlessInput(): InputManager {
+  return {
+    poll: () => {},
+    endFrame: () => {},
+    dispose: () => {},
+    loadMap: async () => {},
+    isPressed: () => false,
+    getAxis: () => 0,
+  } as unknown as InputManager;
+}
+
+/** Headless audio stand-in (no Web Audio). Only the fields the loader/cleanup
+ *  touch are present; setup-based games never mount headlessly. */
+function headlessAudio(): GameAudio {
+  return {
+    listener: undefined as unknown as THREE.AudioListener,
+    masterGain: { gain: { value: 1 } },
+  } as unknown as GameAudio;
+}