@vgai/engine 0.5.2 → 0.5.4

package/src/world2d/physics2d-transform.ts

@@ -1,173 +0,0 @@
-import { type Container, Matrix } from 'pixi.js';
-import type { Entity2D } from './schema/entity2d';
-import type { SceneCollider2D } from './schema/physics2d';
-
-const EPSILON = 1e-6;
-
-export interface PhysicsPose2D {
-  matrix: Matrix;
-  position: [number, number];
-  rotation: number;
-  scale: [number, number];
-}
-
-export type ScaledCollider2D =
-  | { shape: 'cuboid'; halfExtents: [number, number] }
-  | { shape: 'ball'; radius: number }
-  | { shape: 'capsule'; halfHeight: number; radius: number };
-
-function isFiniteMatrix(matrix: Matrix): boolean {
-  return [matrix.a, matrix.b, matrix.c, matrix.d, matrix.tx, matrix.ty].every(Number.isFinite);
-}
-
-function linearMetrics(matrix: Matrix): {
-  determinant: number;
-  orthogonality: number;
-  scaleX: number;
-  scaleY: number;
-} {
-  return {
-    determinant: matrix.a * matrix.d - matrix.b * matrix.c,
-    orthogonality: Math.abs(matrix.a * matrix.c + matrix.b * matrix.d),
-    scaleX: Math.hypot(matrix.a, matrix.b),
-    scaleY: Math.hypot(matrix.c, matrix.d),
-  };
-}
-
-function assertRigidRepresentable(matrix: Matrix, label: string): [number, number] {
-  if (!isFiniteMatrix(matrix)) {
-    throw new Error(`world2d physics entity "${label}" has a non-finite composed transform`);
-  }
-  const { determinant, orthogonality, scaleX, scaleY } = linearMetrics(matrix);
-  if (scaleX <= EPSILON || scaleY <= EPSILON || Math.abs(determinant) <= EPSILON) {
-    throw new Error(`world2d physics entity "${label}" has a singular composed transform`);
-  }
-  if (orthogonality > EPSILON * scaleX * scaleY) {
-    throw new Error(
-      `world2d physics entity "${label}" has a sheared composed transform; ` +
-        'Rapier rigid bodies cannot represent shear',
-    );
-  }
-  return [scaleX, scaleY];
-}
-
-/** Matrix from `container` local coordinates into `root` coordinates. The
- * root's own camera/pan transform is deliberately cancelled: Rapier lives in
- * the world2d root's logical pixel space, not application/screen space. */
-export function relativeTransform2D(container: Container, root: Container): Matrix {
-  let ancestor: Container | null = container;
-  while (ancestor && ancestor !== root) ancestor = ancestor.parent;
-  if (ancestor !== root) {
-    throw new Error('world2d physics object is not a descendant of the scene root');
-  }
-
-  const rootGlobal = root.getGlobalTransform();
-  const global = container.getGlobalTransform();
-  const origin = rootGlobal.applyInverse(global.apply({ x: 0, y: 0 }));
-  const unitX = rootGlobal.applyInverse(global.apply({ x: 1, y: 0 }));
-  const unitY = rootGlobal.applyInverse(global.apply({ x: 0, y: 1 }));
-  return new Matrix(
-    unitX.x - origin.x,
-    unitX.y - origin.y,
-    unitY.x - origin.x,
-    unitY.y - origin.y,
-    origin.x,
-    origin.y,
-  );
-}
-
-/** Moving Rapier bodies may rotate after spawn. Their Pixi parent chain must
- * therefore be conformal (uniform scale plus rotation/reflection); otherwise a
- * later rigid-body rotation would become shear when converted back to the
- * parent-local display transform. Fixed bodies can retain a non-uniform parent
- * because their authored relative rotation does not change. */
-export function assertMovingPhysicsParent2D(
-  display: Container,
-  root: Container,
-  label: string,
-): void {
-  const parent = display.parent;
-  if (!parent) throw new Error(`world2d physics entity "${label}" is not mounted`);
-  if (parent === root) return;
-  const parentMatrix = relativeTransform2D(parent, root);
-  const [scaleX, scaleY] = assertRigidRepresentable(parentMatrix, label);
-  if (Math.abs(scaleX - scaleY) > EPSILON * Math.max(scaleX, scaleY)) {
-    throw new Error(
-      `world2d moving physics entity "${label}" has a non-conformal parent transform ` +
-        `(composed scale [${scaleX}, ${scaleY}]); rotating a Rapier body beneath ` +
-        'non-uniform parent scale would shear the Pixi visual',
-    );
-  }
-}
-
-/** Compose the transform Rapier actually owns for one authored entity.
- *
- * The parent uses its real Pixi transform so nested visuals and physics agree.
- * The entity's own linear transform comes from `transform2d`, not from the
- * display object's `scale`: Sprite width/height are implemented internally by
- * Pixi as scale, but collider dimensions are already authored in pixels and
- * must not be multiplied by that implementation detail. The body origin is
- * the entity position (the world position of Pixi's pivot), matching the
- * existing world2d physics contract. */
-export function computePhysicsPose2D(
-  entity: Entity2D,
-  display: Container,
-  root: Container,
-  label = entity.name,
-): PhysicsPose2D {
-  const parent = display.parent;
-  if (!parent) throw new Error(`world2d physics entity "${label}" is not mounted`);
-  const parentMatrix = parent === root ? new Matrix() : relativeTransform2D(parent, root);
-  const transform = entity.transform2d;
-  const position = transform?.position ?? [0, 0];
-  const scale = transform?.scale ?? [1, 1];
-  const local = new Matrix().setTransform(
-    position[0],
-    position[1],
-    0,
-    0,
-    scale[0],
-    scale[1],
-    transform?.rotation ?? 0,
-    0,
-    0,
-  );
-  const matrix = new Matrix().appendFrom(local, parentMatrix);
-  const [scaleX, scaleY] = assertRigidRepresentable(matrix, label);
-
-  return {
-    matrix,
-    position: [matrix.tx, matrix.ty],
-    rotation: Math.atan2(matrix.b, matrix.a),
-    scale: [scaleX, scaleY],
-  };
-}
-
-/** Bake the composed visual scale into the native Rapier collider dimensions.
- * Round shapes require uniform scale because Rapier has no ellipse collider. */
-export function scaleCollider2D(
-  collider: SceneCollider2D,
-  scale: readonly [number, number],
-  label: string,
-): ScaledCollider2D {
-  const [scaleX, scaleY] = scale;
-  if (collider.shape === 'cuboid') {
-    return {
-      shape: 'cuboid',
-      halfExtents: [collider.halfExtents[0] * scaleX, collider.halfExtents[1] * scaleY],
-    };
-  }
-  if (Math.abs(scaleX - scaleY) > EPSILON * Math.max(scaleX, scaleY)) {
-    throw new Error(
-      `world2d physics entity "${label}" uses non-uniform composed scale ` +
-        `[${scaleX}, ${scaleY}] with a ${collider.shape} collider; Rapier cannot represent ` +
-        'an elliptical round collider',
-    );
-  }
-  if (collider.shape === 'ball') return { shape: 'ball', radius: collider.radius * scaleX };
-  return {
-    shape: 'capsule',
-    halfHeight: collider.halfHeight * scaleY,
-    radius: collider.radius * scaleX,
-  };
-}

package/src/world2d/physics2d-units.ts

@@ -1,10 +0,0 @@
-/** Canonical Pixi-world scale: 100 authored pixels represent one physics meter. */
-export const DEFAULT_WORLD2D_PIXELS_PER_METER = 100;
-
-/** Earth-like downward acceleration used when a 2D scene omits gravity. */
-export const DEFAULT_WORLD2D_GRAVITY_METERS_PER_SECOND_SQUARED = 9.8;
-
-/** Derive the pixel-space default while preserving friendly decimal values. */
-export function defaultWorld2DGravityY(pixelsPerMeter: number): number {
-  return (DEFAULT_WORLD2D_GRAVITY_METERS_PER_SECOND_SQUARED * 10 * pixelsPerMeter) / 10;
-}

package/src/world2d/pixi-game-adapter.ts

@@ -1,439 +0,0 @@
-import RAPIER from '@dimforge/rapier2d-compat';
-import type { Container } from 'pixi.js';
-import { createInputManagerAdapter } from '../adapter/first-party-systems';
-import type { MountedPixiWorld } from '../adapter/game-adapter';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import { createAssetCache } from '../assets';
-import { createGameLoop } from '../core/game-loop';
-import {
-  createSeededRandom,
-  DEFAULT_SEEDED_RANDOM_SEED,
-  getSeededRandom,
-} from '../core/seeded-random';
-import { createSystemRunner } from '../core/system-runner';
-import { createComponentManager } from '../ecs/component-manager';
-import { InputManager } from '../input/input-manager';
-import {
-  createDebugRegistry,
-  type DebugRegistry,
-  getDebugRegistry,
-} from '../runtime/debug-registry';
-import {
-  createGame,
-  createWorldInstance,
-  type GameInternal,
-  type WorldFrameHooks,
-} from '../runtime/game';
-import { createCollision2DSystem, createTriggerDispatch2D } from './collision-2d';
-import { createPhysics2DRegistry } from './physics2d-registry';
-import { DEFAULT_WORLD2D_PIXELS_PER_METER, defaultWorld2DGravityY } from './physics2d-units';
-import { createPixiSurface, type PixiSurface } from './pixi-surface';
-import { loadScene2DFromData, type Scene2DInstance } from './scene2d-loader';
-import type { Scene2DFile } from './schema/entity2d';
-import { createTransformWriter2D } from './transform-writer-2d';
-import type { Component2DRegistry, World2DContext } from './types';
-
-/** Minimal host surface for world2d (the stacked-own-root model from the spec). */
-export interface World2DHost {
-  canvas: HTMLCanvasElement;
-  width: number;
-  height: number;
-  /** Headless validation mount: skip browser-only asset/input initialization. */
-  headless?: boolean;
-  /** Shared Game root when mounted by the universal multi-world host. */
-  game?: GameInternal;
-  /** DPR override (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §3 — "one DPR
-   *  everywhere"): the roots-path host computes ONE dpr for every stacked
-   *  surface and passes it here; omitted -> `createPixiSurface`'s own
-   *  default (`window.devicePixelRatio`, uncapped) — today's behavior. */
-  dpr?: number;
-  /** This world is stacked ABOVE another world (D5 §1): clear with alpha 0
-   *  instead of an opaque background so the layer below shows through. */
-  transparent?: boolean;
-  /** Capture tier cost (D5 §4) — see `PixiSurfaceOptions.preserveDrawingBuffer`. */
-  preserveDrawingBuffer?: boolean;
-}
-
-/** A world2d setup function — build the scene from the context, return cleanup. */
-export type World2DSetupFn = (
-  ctx: World2DContext,
-) => Promise<{ dispose: () => void }> | { dispose: () => void };
-
-/**
- * MountedGame for world2d — the pixi peer of the 3D `MountedThreeWorld`,
- * satisfying `MountedPixiWorld` (`adapter/game-adapter.ts`, T7.5) via `kind`/
- * `stage` so a `WorldInstance` built from this mount needs no cast through
- * the generic `MountedWorld` union. `scene`/`camera` (both the SAME `Container`
- * as `stage`) are kept as extra fields for pre-T7.5 call sites/tests that
- * already read them — `stage` is the canonical name going forward.
- */
-export interface MountedGame2D extends MountedPixiWorld {
-  /** First-party brand (T7.3 slice 2 — closes the gap `adapter/vgai-scene-
-   *  game-adapter.ts`'s `VgaiMountedGame.firstParty` doc flagged as a "T7.3
-   *  lookahead"): `runtime/game.ts`'s `isFirstPartyMounted` brand-checks
-   *  this literal, NOT a structural `'ctx' in mounted` probe (this mount's
-   *  `ctx` is a `World2DContext`, unrelated to `GameContext`). Without this,
-   *  a pixijs `WorldInstance` is silently skipped by every first-party-only
-   *  Game feature — `Game.queryByComponent` in particular, the T7.3 AC
-   *  (`test/game-three-plus-pixi.test.ts`). */
-  readonly firstParty: true;
-  /** Pre-T7.5 field names, kept for compatibility — both alias `stage`
-   *  (pixi has no separate camera concept; `MountedGame2D.mount` always sets
-   *  `scene === camera === stage`). */
-  readonly scene: Container;
-  readonly camera: Container;
-  readonly ctx: World2DContext;
-  update?(dt: number): void;
-  resize?(width: number, height: number): void;
-  dispose(): void;
-  /** Phase-partitioned frame entry point (T7.3 slice 1) — the pixi analog of
-   *  `VgaiMountedGame.frame` (`adapter/vgai-scene-game-adapter.ts`). Delegates
-   *  to this mount's own `SystemRunner`, so a `WorldInstance` built from this
-   *  mount ticks it through `Game.runFrame` instead of a standalone loop. */
-  readonly frame?: WorldFrameHooks;
-}
-
-export interface PixiSceneConfig {
-  /** A world2d scene file to load (declarative path). */
-  sceneData?: Scene2DFile;
-  /** A setup function (imperative path) — mutually exclusive with sceneData. */
-  setup?: World2DSetupFn;
-  /** Component registry the scene's `components` reference. */
-  registry?: Component2DRegistry;
-  /** Input map JSON path. Defaults to the same conventional map as Three;
-   *  explicit `null` disables loading for deliberately input-free/test mounts. */
-  inputMapPath?: string | null;
-  id?: string;
-}
-
-/**
- * The first-party implementer that mounts an authored world2d scene — the 2D
- * analog of `VgaiSceneGameAdapter`. It builds the Pixi surface + Rapier 2D world,
- * registers the engine systems into the shared phase runner, loads the scene (or
- * runs a setup), and returns a `MountedGame2D`.
- */
-export class PixiSceneGameAdapter {
-  readonly id: string;
-  constructor(private readonly config: PixiSceneConfig = {}) {
-    this.id = config.id ?? 'pixi-scene';
-  }
-
-  async mount(host: World2DHost): Promise<MountedGame2D> {
-    const {
-      inputMapPath = '/inputmaps/default.inputmap.json',
-      sceneData,
-      setup,
-      registry = {},
-    } = this.config;
-
-    // --- Pixi surface (autoStart:false; engine loop drives render) ---
-    const surface: PixiSurface = await createPixiSurface({
-      canvas: host.canvas,
-      width: host.width,
-      height: host.height,
-      ...(sceneData?.background ? { background: sceneData.background } : {}),
-      // T6.1 slice 1 (roots-path host hints — see `World2DHost`'s fields):
-      // all optional, all no-ops when the host is the legacy
-      // `createWorld2DRuntime` entry (which never sets them), so behavior
-      // there is unchanged.
-      ...(host.dpr !== undefined ? { resolution: host.dpr } : {}),
-      ...(host.transparent ? { transparent: true } : {}),
-      ...(host.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
-    });
-
-    // --- Rapier 2D world (separate from the 3D world) ---
-    await RAPIER.init();
-    const pixelsPerMeter = sceneData?.pixelsPerMeter ?? DEFAULT_WORLD2D_PIXELS_PER_METER;
-    const gravity = sceneData?.gravity ?? [0, defaultWorld2DGravityY(pixelsPerMeter)];
-    const rapier2dWorld = new RAPIER.World({ x: gravity[0], y: gravity[1] });
-    // Keep Rapier's public API in authored pixels. Its native length-unit
-    // setting scales solver/contact tolerances for those pixel-sized bodies.
-    rapier2dWorld.lengthUnit = pixelsPerMeter;
-    const eventQueue = new RAPIER.EventQueue(true);
-
-    const physics2d = createPhysics2DRegistry();
-    const writeTransforms2D = createTransformWriter2D(physics2d, surface.world);
-    const collisions2d = createCollision2DSystem(rapier2dWorld, eventQueue);
-    const ownsInput = !host.game;
-    const input = host.game?.input ?? new InputManager();
-    if (!host.headless && inputMapPath !== null) {
-      if (host.game) await host.game.loadInputMap(inputMapPath);
-      else await input.loadMap(inputMapPath);
-    }
-
-    const systemAdapters: SystemAdapters = {};
-    const debugRegistry: DebugRegistry =
-      (host.game ? getDebugRegistry(host.game) : null) ??
-      createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
-    if (ownsInput) systemAdapters.input = createInputManagerAdapter(input);
-    systemAdapters.debug = debugRegistry.adapter;
-    // W4b (F11 frame debugger): the pixijs adapter deliberately does NOT
-    // register a `renderDebug` SystemAdapter. The first-party WebGL2 frame
-    // capture (`dev/webgl-frame-capture.ts`) and its `onBeforeRender`-based
-    // attribution are three.js-shaped (three's own per-object pre-draw hook,
-    // a THREE.Scene traversal, `renderer.info` memory). PixiJS draws through
-    // its own batch renderer with no equivalent per-object seam, so a faithful
-    // pixi capture is a separate instrument — deferred, not faked. Absence of
-    // `renderDebug` here is the honest "capability not supported" signal; the
-    // editor's frame-debugger panel marks a pixi world's section absent rather
-    // than showing fabricated draws.
-
-    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'pixijs');
-    if (ownsInput) systems.add('input', () => input.poll(), { name: 'input.poll' });
-    systems.add('physics', () => rapier2dWorld.step(eventQueue), { name: 'physics2d.step' });
-    systems.add(
-      'postPhysics',
-      () => {
-        collisions2d.drain();
-        writeTransforms2D();
-      },
-      { name: 'physics2d.sync' },
-    );
-    systems.add('render', () => surface.render(), { name: 'pixi.render' });
-
-    const ctx: World2DContext = {
-      app: surface.app,
-      stage: surface.world,
-      rapier2dWorld,
-      rapier2d: RAPIER,
-      physics2d,
-      collisions2d,
-      components: null!,
-      systems,
-      input,
-      debug: debugRegistry.forWorld(this.id),
-      random:
-        (host.game ? getSeededRandom(host.game) : null) ??
-        createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED),
-      registerSystemAdapter: (kind, adapter) => {
-        systemAdapters[kind] = adapter;
-      },
-      ...(host.game ? { game: host.game, roots: host.game.roots } : {}),
-    };
-
-    debugRegistry.setInputActionsSource(this.id, () =>
-      input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
-    );
-    debugRegistry.setInputTraceSource(this.id, () => {
-      const raw = input.getInputTrace();
-      return {
-        version: raw.version,
-        seed: (host.game ? getSeededRandom(host.game) : null)?.seed ?? null,
-        fixedDt: host.game?.loop.fixedDt ?? null,
-        ticks: raw.ticks,
-      };
-    });
-    debugRegistry.setVirtualInputTarget(this.id, {
-      setVirtualAction: (action, value) => input.setVirtualAction(action, value),
-      tapVirtualAction: (action) => input.tapVirtualAction(action),
-      clearVirtualActions: () => input.clearVirtualActions(),
-      scheduleActionAtTick: (tick, action, value) =>
-        input.scheduleActionAtTick(tick, action, value),
-      startInputRecording: () => input.startInputRecording(),
-      stopInputRecording: () => input.stopInputRecording(),
-      isInputRecording: () => input.isInputRecording(),
-      injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
-      injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
-      injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
-      injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
-    });
-    if (!host.game) input.setDebugEmit((event, detail) => ctx.debug?.emit(event, detail));
-
-    // T7.3 slice 1/2: the pixi world's components attach onto the SAME
-    // unified `ComponentManager` (`ecs/component-manager.ts`) the threejs
-    // path uses, constructed for kind `'pixijs'` — the world2d-silo manager
-    // is deleted (T7.3 slice 2). The manager accepts this native
-    // `World2DContext`, so Pixi component lifecycles need no union/cast.
-    // `createComponentManager`'s positional `physics`
-    // parameter (the 3D `PhysicsRegistry`) is optional (T7.3 slice 2) and
-    // omitted here — a `'pixijs'`-kind manager never reads it (rigidBody/
-    // collider resolve from `physics2d` instead — see `resolvePhysicsRefs`
-    // in `ecs/component-manager.ts`).
-    ctx.components = createComponentManager(ctx, undefined, {
-      kind: 'pixijs',
-      physics2d,
-    });
-    collisions2d.onCollision(
-      createTriggerDispatch2D(physics2d, ctx.components, rapier2dWorld, ctx),
-    );
-
-    // --- Load scene or run setup ---
-    let sceneInstance: Scene2DInstance | null = null;
-    let cleanup: { dispose: () => void } | null = null;
-    let disposed = false;
-    systems.add('animation', (dt) => sceneInstance?.updateAnimations(dt), {
-      name: 'pixi.animated-sprites',
-    });
-    const disposeResources = (): void => {
-      if (disposed) return;
-      disposed = true;
-      const errors: unknown[] = [];
-      const attempt = (dispose: () => void): void => {
-        try {
-          dispose();
-        } catch (error) {
-          errors.push(error);
-        }
-      };
-      attempt(() => cleanup?.dispose());
-      attempt(() => sceneInstance?.dispose());
-      attempt(() => ctx.components.clear());
-      attempt(() => debugRegistry.strip(this.id));
-      if (ownsInput) attempt(() => input.dispose());
-      attempt(() => physics2d.clear());
-      attempt(() => rapier2dWorld.free());
-      attempt(() => eventQueue.free());
-      attempt(() => surface.dispose());
-      if (errors.length > 0) {
-        throw new AggregateError(errors, `Failed to dispose Pixi world "${this.id}" cleanly`);
-      }
-    };
-    try {
-      if (sceneData) {
-        sceneInstance = await loadScene2DFromData(sceneData, ctx, registry);
-      } else if (setup) {
-        cleanup = await setup(ctx);
-      }
-    } catch (error) {
-      try {
-        disposeResources();
-      } catch (cleanupError) {
-        throw new AggregateError(
-          [error, cleanupError],
-          `Pixi world "${this.id}" failed to mount and roll back cleanly`,
-        );
-      }
-      throw error;
-    }
-
-    return {
-      kind: 'pixijs',
-      firstParty: true,
-      stage: surface.world,
-      scene: surface.world,
-      camera: surface.world,
-      drivesOwnLoop: false,
-      ctx,
-      update: (dt: number) => systems.run(dt),
-      resize: (w: number, h: number) => surface.resize(w, h),
-      // Bare adapters own and close their private input frame here. A
-      // game-hosted adapter shares the one game-owned manager, whose frame is
-      // closed once after every root has advanced.
-      frame: {
-        runPhase: (phase, dt) => systems.runPhase(phase, dt),
-        ...(ownsInput ? { endFrame: () => input.endFrame() } : {}),
-      },
-      systems: systemAdapters,
-      dispose: disposeResources,
-    };
-  }
-}
-
-/** Handle returned by {@link createWorld2DRuntime}. */
-export interface World2DSession {
-  stop(): void;
-  pause(): void;
-  resume(): void;
-  /** Advance exactly one fixed substep — the pixi analog of
-   *  `GameSession.step()` (`runtime/create-runtime.ts`), delegating to the
-   *  same `Game.play.step()` (D10, T7.6). */
-  step(): void;
-  resize(width: number, height: number): void;
-  readonly mounted: MountedGame2D;
-}
-
-/**
- * Host entry for world2d — the sibling of `createGameRuntime`, kept separate so the
- * proven THREE host/interfaces are untouched (the stacked-own-root option the spec's
- * surface-host-backend-neutral allows). Owns the canvas and constructs a real `Game`
- * (T7.3 slice 1) with exactly one `'pixijs'`-kind `WorldInstance`, driven each fixed
- * substep through `Game.runFrame` — the world2d analog of `createGameRuntime`'s
- * `registerThreeWorld` (`runtime/create-runtime.ts`). Before T7.3 this ran its
- * own standalone `createGameLoop` calling `mounted.update` directly; that loop is
- * retired here in favor of one shared frame executor per game root.
- */
-export async function createWorld2DRuntime(
-  config: PixiSceneConfig & World2DHost,
-): Promise<World2DSession> {
-  const { canvas, width, height, ...sceneConfig } = config;
-  const adapter = new PixiSceneGameAdapter(sceneConfig);
-
-  const assets = createAssetCache();
-  // `game` is referenced here before its `const` below only textually — this
-  // closure isn't invoked until `loop.start()`, well after `game` exists
-  // (same forward-reference pattern `create-runtime.ts` uses).
-  const loop = createGameLoop({
-    fixedTimestep: 1 / 60,
-    maxSubSteps: 8,
-    update: (dt) => {
-      game.runFrame(dt);
-    },
-  });
-  const game: GameInternal = createGame({ loop, assets });
-  const mounted = await adapter.mount({ canvas, width, height, game });
-
-  // T7.5: `mounted` (a `MountedGame2D`, extending `MountedPixiWorld`) and
-  // `adapter` (this `PixiSceneGameAdapter`, satisfying `WorldInstance.adapter`'s
-  // minimal `AdapterHandle` shape — see that field's doc comment in
-  // `runtime/game.ts`) now pass through with ZERO cast — previously this cast
-  // through `GameAdapter`/`MountedGame`, which hardwired THREE `scene`/`camera`.
-  const pixiWorld = createWorldInstance({
-    id: 'main',
-    kind: 'pixijs',
-    adapter,
-    mounted,
-    stage: mounted.stage,
-    physics2d: mounted.ctx.physics2d,
-    collisions2d: mounted.ctx.collisions2d,
-    frame: mounted.frame,
-  });
-  // T7.2/T7.3 world-wiring backfill (mirrors `registerThreeWorld` in
-  // `create-runtime.ts`): scene-authored components attach DURING `mount()`,
-  // before this `WorldInstance` exists, so `instance.world` is left
-  // `undefined` for each of them — `adoptWorld` backfills it now, once, for
-  // every already-attached instance still missing a world.
-  mounted.ctx.components.adoptWorld(pixiWorld);
-  game.registerWorld(pixiWorld);
-
-  loop.start();
-
-  if (typeof window !== 'undefined' && import.meta.env?.DEV) {
-    (window as unknown as Record<string, unknown>)['__vgaiWorld2d'] = {
-      app: mounted.ctx.app,
-      stage: mounted.stage,
-      physics2d: mounted.ctx.physics2d,
-    };
-  }
-
-  return {
-    stop() {
-      loop.stop();
-      mounted.dispose();
-      game.dispose();
-    },
-    // D10/T7.6: route through the real `Game.play` control surface instead of
-    // `loop.timeScale = 0/1` — that starved the accumulator entirely (per D1,
-    // zero substeps ⇒ zero renders too), the exact bug this control surface
-    // replaces. `Game.play.pause()` freezes this world's simulation (it is
-    // `pausable` by default) while its `render` phase keeps running every
-    // substep — the screen does not go black while paused.
-    pause() {
-      game.play.pause();
-    },
-    resume() {
-      game.play.resume();
-    },
-    step() {
-      game.play.step();
-    },
-    resize(w: number, h: number) {
-      // T7.5/T7.6 own real per-world resize routing through the Game/host
-      // surface split (the host is not yet surface-neutral for world2d) —
-      // kept as today's direct host→surface call for this slice.
-      mounted.resize?.(w, h);
-    },
-    get mounted() {
-      return mounted;
-    },
-  };
-}