@vgai/engine 0.5.22 → 0.5.23

package/src/runtime/mount-game.ts

@@ -12,10 +12,11 @@
 // callers register, but it registers NONE itself. In particular there is no
 // built-in 'canvas'/'react' registration here (that would require this file
 // to value-import `pixi.js`/`react`/`react-dom`, exactly what `mount-manifest
-// .ts` forbids); a project that has a canvas or react world MUST register a
-// factory for that kind itself — see `defaultThreeAdapterFactory` below for why
-// even the 'three' convenience export is a plain function the CALLER
-// registers, not something this module wires up automatically.
+// .ts` forbids); a project that has a three, canvas, or react world MUST
+// register a factory for that kind itself — the factories live with the
+// modules that own their dependencies (`r3fRootFactory` in
+// `@engine/world3d-react`, its Pixi twin in `@engine/canvas-react`), never
+// wired up here automatically.
 
 import { declaredRoots } from '../adapter/manifest-interpreter';
 import {
@@ -26,12 +27,10 @@ import {
   nativeDebugBindingFromEntryModule,
   nativeSystemsBindingFromEntryModule,
 } from '../adapter/native-debug-module';
-import type { RootAdapter } from '../adapter/root-adapter';
 import { publishDevInstruments } from '../dev/instruments';
 import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { GameSession } from './create-runtime';
 import { type MountEntry, mountManifestRoots, resolveManifest } from './mount-manifest';
-import type { GameSetupFn } from './types';
 import { assertExportedOrInEditor } from './unexported-game-trap';
 
 // ---------------------------------------------------------------------------
@@ -149,50 +148,6 @@ export function __clearAdapterSurfaceRegistryForTests(): void {
   registry.clear();
 }
 
-// ---------------------------------------------------------------------------
-// `defaultThreeAdapterFactory` — an OPT-IN convenience, never auto-registered
-// ---------------------------------------------------------------------------
-
-/** The entry-module export shape every first-party entry module follows
- *  (an explicit world entry module, including `examples/*` projects'
- *  `src/index.ts` — see CLAUDE.md's "Adding an example project"). */
-interface ThreeEntryModuleExports {
-  readonly adapter?: RootAdapter;
-  readonly setup?: GameSetupFn;
-}
-
-/**
- * A ready-to-register {@link AdapterSurfaceFactory} for `kind: 'three'` roots
- * that follow the first-party entry-module convention (`export const
- * adapter` and/or `export async function setup`). Threejs is safe to
- * ship as an exported convenience (unlike canvas/react) because `three`/
- * `SetupThreeRootAdapter` are already unconditional engine dependencies —
- * see `mount-manifest.ts`'s header comment. Still never auto-registered:
- * the registry itself stays zero-policy (see this file's header comment) —
- * a caller opts in with `registerAdapter('three', defaultThreeAdapterFactory)`.
- *
- * Resolution mirrors `mount-manifest.ts`'s own `resolveThreeAdapter` branch
- * order: an entry module's `adapter` export wins outright; else its `setup`
- * export (wrapping via `fromSetup` happens inside `mountManifestRoots`
- * itself — this factory just returns the `MountEntry` shape).
- */
-export const defaultThreeAdapterFactory: AdapterSurfaceFactory = (world, ctx) => {
-  const mod = ctx.entryModule as ThreeEntryModuleExports | undefined;
-  if (mod?.adapter) return { kind: 'three', adapter: mod.adapter };
-  if (mod?.setup) return { kind: 'three', setup: mod.setup };
-  if (world.entry !== undefined) {
-    throw new Error(
-      `defaultThreeAdapterFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
-        'neither `adapter` nor `setup` — every first-party entry module exports at least one ' +
-        '(export one from the declared entry module).',
-    );
-  }
-  throw new Error(
-    `defaultThreeAdapterFactory: world "${world.id}" declares no \`entry\` — a three root is ` +
-      'authored as a TSX/R3F world module; point `entry` at it.',
-  );
-};
-
 // ---------------------------------------------------------------------------
 // The composer
 // ---------------------------------------------------------------------------
@@ -208,12 +163,9 @@ export interface MountGameOptions {
 /** True for the one shape `mountManifestRoots` can ALREADY mount with zero
  *  `entries[id]` at all.
  *
- *  WO-8: nothing is self-sufficient any more. The one shape that was — a plain
- *  `default`-adapter, SCENE-driven, no-`entry` three world, which
- *  `resolveThreeAdapter`'s scene branch could mount from the manifest alone —
- *  died with the `.vscn.json` format. `load.ts` now rejects a three root with no
+ *  NOTHING is self-sufficient: `load.ts` rejects a three root with no
  *  `entry` outright, so every world needs a registered factory or an explicit
- *  entry, and this predicate is retained only to keep the loud-degrade error the
+ *  entry. This predicate is retained so the loud-degrade error stays the
  *  documented outcome rather than a silent skip. */
 function worldIsSelfSufficient(_world: ResolvedAdapterRoot): boolean {
   return false;
@@ -292,7 +244,7 @@ export async function mountGameFromManifest(
       `mountGameFromManifest: root "${world.id}" (adapter "${world.adapter.identity}") has no registered ` +
         `adapter factory and no explicit entries["${world.id}"] — call ` +
         `registerAdapter("${world.adapter.identity}", factory) before mounting (see ` +
-        '`defaultThreeAdapterFactory` for a worked three example), or pass ' +
+        '`r3fRootFactory` in `@vgai/engine/world3d-react` for the worked three factory), or pass ' +
         `opts.entries["${world.id}"] directly (see mount-manifest.ts's \`MountEntry\`).`,
     );
   }

package/src/runtime/mount-manifest.ts

@@ -1,8 +1,8 @@
 // The standalone manifest-mount helper: an ENGINE-side generalization of
 // `examples/tri-world/src/main.ts`'s hand-built `RootMountSpec[]`.
 //
-// `resolveAllRoots`/`resolveRootAdapter` (`packages/editor/src/
-// adapter-resolver.ts`) already do this translation for the EDITOR, but they
+// `resolveAllRoots`/`resolveRootBinding` (`packages/editor/src/
+// binding-resolver.ts`) already do this translation for the EDITOR, but they
 // are Vite-coupled by construction (`/@fs/` dynamic imports of project files
 // through the dev server, §0.1/§0.5 of the design doc) — unusable from a
 // plain static build. This module mirrors their per-kind dispatch
@@ -17,18 +17,15 @@
 // type-only import): this file never value-imports
 // `pixi.js`, `react`, or `react-dom` — a
 // canvas or react world's adapter is ALWAYS supplied already-constructed via
-// `entries[id].adapter` (the caller's own module graph built it). Threejs is
-// different: `three`/
-// `SetupThreeRootAdapter` are already unconditional dependencies of every
-// caller of `createGameRuntime`, so wrapping a `setup` with
-// `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
+// `entries[id].adapter` (the caller's own module graph built it), so no
+// surface's library is pulled into a game that has no world on it.
 
 import { assertNever } from '../adapter/adapter-surface';
+import type { RootDeclaration } from '../adapter/binding';
 import { declaredRoots } from '../adapter/manifest-interpreter';
 import type { RootAdapter } from '../adapter/root-adapter';
 // Value-imported from the implementer's OWN path, not the type-only
 // `../adapter` barrel (P-6).
-import { fromSetup } from '../adapter/setup-three-root-adapter';
 import {
   loadGameManifest,
   type ResolvedAdapterRoot,
@@ -38,8 +35,8 @@ import { createGameRuntime, type GameSession, type RootMountSpec } from './creat
 import { type DebugBridgeWindowTarget, maybeInstallDebugBridge } from './debug-bridge';
 import { getDebugRegistry } from './debug-registry';
 import { getGameplayRngTrapControl } from './gameplay-rng-trap';
+import type { PlaytestContext } from './playtest';
 import { RENDER_SEED_QUERY_PARAM } from './render-seed';
-import type { GameSetupFn, PlaytestContext } from './types';
 
 // ---------------------------------------------------------------------------
 // The `entries` contract
@@ -53,20 +50,28 @@ import type { GameSetupFn, PlaytestContext } from './types';
  *  - `{ adapter }` — a fully-constructed {@link RootAdapter} (first-party or
  *    not). Always wins if present, regardless of the world's `entry` field —
  *    full caller control, including for a `{ module }`-adapter world
- *    (mountManifestRoots cannot import an arbitrary module path itself).
- *  - `{ setup }` — for an `entry`-declaring world: the project's own
- *    `entry` module's exported `setup` function (the same `GameSetupFn`
- *    shape `loadProjectScripts` extracts editor-side). Wrapped in a
- *    `SetupThreeRootAdapter` here, mirroring `resolveDefaultThreeAdapter`'s
- *    entry branch exactly.
- *
- * The former third shape, `{ componentRegistry }` for a `scene`-declaring
- * world, went with the `.vscn.json` format in WO-8.
+ *    (mountManifestRoots cannot import an arbitrary module path itself —
+ *    for a default-exported world, build the adapter with
+ *    `resolveR3FEntryAdapter(entryModule, worldId)` from
+ *    `@vgai/engine/world3d-react` and pass it here).
  */
-export interface ThreeMountEntry {
+export interface ThreeMountEntry extends MountEntryDeclaration {
   readonly kind: 'three';
   readonly adapter?: RootAdapter | undefined;
-  readonly setup?: GameSetupFn | undefined;
+}
+
+/**
+ * The half of a root's binding declaration a CALLER holds — everything in
+ * `adapter/binding.ts`'s {@link RootDeclaration} except `root`, which this
+ * file already has from the manifest it just resolved.
+ *
+ * Optional throughout, and absent is the honest state for a caller who built
+ * an adapter by hand out of its own module graph: there is no entry namespace
+ * to report a static surface for, so the root registers with `binding: null`
+ * rather than one describing a module nobody loaded.
+ */
+export interface MountEntryDeclaration {
+  readonly declaration?: Omit<RootDeclaration, 'root'> | undefined;
 }
 
 /**
@@ -77,7 +82,7 @@ export interface ThreeMountEntry {
  * `pixi.js`, which it deliberately never does (see this file's header
  * comment).
  */
-export interface PixiMountEntry {
+export interface PixiMountEntry extends MountEntryDeclaration {
   readonly kind: 'canvas';
   readonly adapter: RootAdapter<'canvas'>;
 }
@@ -95,7 +100,7 @@ export interface PixiMountEntry {
  * itself (see this file's header comment) — building the adapter is
  * entirely the caller's job.
  */
-export interface ReactMountEntry {
+export interface ReactMountEntry extends MountEntryDeclaration {
   readonly kind: 'dom';
   readonly adapter: RootAdapter<'dom'>;
 }
@@ -244,8 +249,8 @@ export function resolveManifest(raw: unknown): ResolvedGameManifest {
 }
 
 // ---------------------------------------------------------------------------
-// Per-kind entry -> adapter resolution (mirrors `resolveRootAdapter`'s
-// per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
+// Per-kind entry -> adapter resolution (mirrors `resolveRootBinding`'s
+// per-identity dispatch, `packages/editor/src/binding-resolver.ts`)
 // ---------------------------------------------------------------------------
 
 function resolveThreeAdapter(
@@ -274,19 +279,17 @@ function resolveThreeAdapter(
 
   // type === 'default'
   if (world.entry !== undefined) {
-    if (!entry?.setup) {
-      throw new Error(
-        `mountManifestRoots: world "${world.id}" (three) declares \`entry\` "${world.entry}" ` +
-          `— supply entries["${world.id}"] = { kind: 'three', setup } (the entry module's ` +
-          "exported `setup` function) or { kind: 'three', adapter } for full control. Got " +
-          `${entry === undefined ? 'no entry at all' : 'an entry with neither `setup` nor `adapter`'}.`,
-      );
-    }
-    return fromSetup(world.id, entry.setup);
+    throw new Error(
+      `mountManifestRoots: world "${world.id}" (three) declares \`entry\` "${world.entry}" ` +
+        `— supply entries["${world.id}"] = { kind: 'three', adapter } (for a default-exported ` +
+        'world, build it with `resolveR3FEntryAdapter(entryModule, worldId)` from ' +
+        '`@vgai/engine/world3d-react`). Got ' +
+        `${entry === undefined ? 'no entry at all' : 'an entry with no `adapter`'}.`,
+    );
   }
   // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
   // `entry` for every 'default' THREE adapter world at manifest-load time (and
-  // rejects `scene` outright — the `.vscn.json` format was removed in WO-8).
+  // rejects any other content declaration on one outright).
   throw new Error(
     `mountManifestRoots: world "${world.id}" is default-three with no \`entry\` — this ` +
       'should have been rejected by manifest validation.',
@@ -337,6 +340,12 @@ function buildRootMountSpec(
     id: world.id,
     zOrder: world.zOrder,
     pausable: world.pausable,
+    // `root` is this file's own resolved manifest record; the rest — the
+    // parsed `vgai.adapter.ts`, the entry namespace, the entry's declared
+    // debug/systems bindings — only the caller who loaded the entry can know.
+    ...(entry?.declaration === undefined
+      ? {}
+      : { declaration: { root: world, ...entry.declaration } }),
   };
 
   // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard

package/src/runtime/playtest.ts

@@ -0,0 +1,22 @@
+/**
+ * WHO IS PLAYING, and under what identity — the host's own declaration for one
+ * private play run or coordinated team test.
+ *
+ * Its own module because it is a PUBLISHED path: a project's Colyseus
+ * networking adapter (the `colyseus` capability, copied into every game) names
+ * this type, so it must live somewhere that survives. The engine never joins a
+ * room and never couples this authoring identity to a networking library —
+ * games may pass `roomKey` as a Colyseus filter/join option, and that is the
+ * whole of the coupling.
+ */
+
+/** Host-supplied identity for one private play run or coordinated team test.
+ * Games may pass `roomKey` as a Colyseus filter/join option; the engine never
+ * joins a room or couples this authoring identity to a networking library. */
+export interface PlaytestContext {
+  readonly mode: 'private' | 'team';
+  readonly id: string;
+  readonly roomKey: string;
+  readonly revision: number | null;
+  readonly participantId: string | null;
+}

package/src/runtime/state-bridge.ts

@@ -48,9 +48,8 @@ export interface GameStateBridge {
 export interface GameStateBridgeInternal extends GameStateBridge {
   /** Bump `frameVersion` by one and notify every current subscriber, in
    *  subscription order. Subscriber errors are isolated (per-subscriber
-   *  try/catch, loud `console.error`, never swallowed silently) — mirrors
-   *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
-   *  `update()` calls: one offending subscriber must not stop its siblings
+   *  try/catch, loud `console.error`, never swallowed silently): one
+   *  offending subscriber must not stop its siblings
    *  from being notified, and must not break the frame loop. */
   bump(): void;
 }
@@ -84,6 +83,7 @@ export function createStateBridge(): GameStateBridgeInternal {
         try {
           onFrame();
         } catch (err) {
+          // biome-ignore lint/suspicious/noConsole: a throwing subscriber must not take the notify loop down, and the console (captured by the editor session ledger) is the engine runtime's one report channel.
           console.error('[state-bridge] subscriber threw:', err);
         }
       }

package/src/setup/setup-audio.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { type AudioBusMixer, createAudioBusMixer } from '../audio/bus-mixer';
 
 export interface AudioContext {
   listener: THREE.AudioListener;
@@ -8,10 +9,24 @@ export interface AudioContext {
     sfx: GainNode;
     voice: GainNode;
   };
+  /**
+   * The named-bus mixer the three below are buses OF (`../audio/bus-mixer.ts`).
+   *
+   * `buses` is a fixed struct because those three names are the ones the engine
+   * itself routes; a game with an `ambience`, a `ui` or a per-character bus asks
+   * the mixer for it by name — `audio.mixer.bus('ambience', 'master')` mints it
+   * under the master gain, `audio.mixer.setDb('ambience', -6)` sets it in
+   * decibels — and `audio.mixer.disconnect()` is the ONE teardown for all of
+   * them, the three struct members included.
+   */
+  mixer: AudioBusMixer;
   /** Call this on first user interaction (click/key) to resume audio context */
   resume: () => void;
 }
 
+/** The bus every other bus routes into, and the node `masterGain` is. */
+const MASTER_BUS = 'master';
+
 /**
  * Creates the audio listener and bus hierarchy.
  *
@@ -23,25 +38,19 @@ export function setupAudio(camera: THREE.Camera): AudioContext {
   camera.add(listener);
 
   const ctx = listener.context;
-  const masterGain = ctx.createGain();
-  masterGain.connect(ctx.destination);
+  const mixer = createAudioBusMixer({ context: ctx, destination: ctx.destination });
+  const masterGain = mixer.bus(MASTER_BUS);
 
   // Route the Three.js listener through masterGain so that THREE.Audio /
   // THREE.PositionalAudio objects are also silenced by the mute button.
   listener.gain.disconnect();
   listener.gain.connect(masterGain);
 
-  const musicGain = ctx.createGain();
+  const musicGain = mixer.bus('music', MASTER_BUS);
   musicGain.gain.value = 0.7;
-  musicGain.connect(masterGain);
-
-  const sfxGain = ctx.createGain();
-  sfxGain.gain.value = 1.0;
-  sfxGain.connect(masterGain);
 
-  const voiceGain = ctx.createGain();
-  voiceGain.gain.value = 1.0;
-  voiceGain.connect(masterGain);
+  const sfxGain = mixer.bus('sfx', MASTER_BUS);
+  const voiceGain = mixer.bus('voice', MASTER_BUS);
 
   return {
     listener,
@@ -51,6 +60,7 @@ export function setupAudio(camera: THREE.Camera): AudioContext {
       sfx: sfxGain,
       voice: voiceGain,
     },
+    mixer,
     resume() {
       if (ctx.state === 'suspended') {
         ctx.resume();

package/src/setup/setup-renderer.ts

@@ -9,7 +9,7 @@ import {
   DepthOfFieldEffect,
   DotScreenEffect,
   type Effect,
-  EffectComposer,
+  type EffectComposer,
   EffectPass,
   GlitchEffect,
   GodRaysEffect,
@@ -42,13 +42,6 @@ import { DEFAULTS } from '../defaults';
 import { detectKtx2Support } from '../loader';
 import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
 
-export interface RendererContext {
-  renderer: THREE.WebGLRenderer;
-  scene: THREE.Scene;
-  camera: THREE.PerspectiveCamera;
-  composer: EffectComposer;
-}
-
 /**
  * Apply the live renderer-level render settings (shadows, resolution scale) from
  * the resolved cascade. `antialias`/`backend` are reload-only (renderer re-init)
@@ -73,7 +66,7 @@ export function applyRendererSettings(
 /**
  * Create ONLY the WebGL renderer. The HOST owns the renderer (see
  * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
- * renders into. Split out of `setupRenderer` for the adapter inversion.
+ * renders into.
  *
  * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
  * reload-only `antialias` option at construction and the live shadow/resolution
@@ -118,58 +111,6 @@ export function createHostRenderer(
   return renderer;
 }
 
-/**
- * Create the scene, camera, and postprocessing composer that a first-party game
- * renders into, given a host-provided renderer. The GPU-only `composer` is
- * created here; a headless host (no GPU) skips this entirely.
- */
-export function createSceneView(
-  renderer: THREE.WebGLRenderer,
-  width = window.innerWidth,
-  height = window.innerHeight,
-): { scene: THREE.Scene; camera: THREE.PerspectiveCamera; composer: EffectComposer } {
-  const safeWidth = Math.max(1, width);
-  const safeHeight = Math.max(1, height);
-  const scene = new THREE.Scene();
-  scene.background = new THREE.Color(0x1a1a2e);
-
-  const camera = new THREE.PerspectiveCamera(
-    DEFAULTS.camera.fov,
-    safeWidth / safeHeight,
-    DEFAULTS.camera.near,
-    DEFAULTS.camera.far,
-  );
-  camera.position.set(0, 5, 10);
-  camera.lookAt(0, 0, 0);
-
-  const composer = new EffectComposer(renderer);
-  composer.addPass(new RenderPass(scene, camera));
-  composer.addPass(
-    new EffectPass(
-      camera,
-      new BloomEffect({ luminanceThreshold: DEFAULTS.postProcessing.bloom.luminanceThreshold }),
-    ),
-  );
-
-  return { scene, camera, composer };
-}
-
-/**
- * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
- *
- * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
- * combination of {@link createHostRenderer} + {@link createSceneView}.)
- */
-export function setupRenderer(
-  canvas: HTMLCanvasElement,
-  width = window.innerWidth,
-  height = window.innerHeight,
-): RendererContext {
-  const renderer = createHostRenderer(canvas, width, height);
-  const { scene, camera, composer } = createSceneView(renderer, width, height);
-  return { renderer, scene, camera, composer };
-}
-
 const toneMappingModes: Record<string, THREE.ToneMapping> = {
   none: THREE.NoToneMapping,
   linear: THREE.LinearToneMapping,

package/src/world3d-react/r3f-root-factory.tsx

@@ -18,13 +18,13 @@
  *
  * ## Why this is NOT in `mount-game.ts`
  *
- * `defaultThreeAdapterFactory` lives beside the registry, and the registry
- * module is deliberately dependency-free: its own doc notes threejs is safe to
- * ship there because `three` is already an unconditional engine dependency.
- * `@react-three/fiber` is NOT — it is the PROJECT's dependency, and
- * `world3d-react` is the opt-in module that owns it. Putting this factory
- * there would make R3F unconditional for every game, including ones with no
- * React at all.
+ * The adapter registry module is deliberately dependency-free beyond `three`
+ * (already an unconditional engine dependency). `@react-three/fiber` is NOT —
+ * it is the PROJECT's dependency, and `world3d-react` is the opt-in module
+ * that owns it. Putting this factory beside the registry would make R3F
+ * unconditional for every game, including ones with no React at all; instead
+ * each project's `main.ts` registers it (`registerAdapter('three',
+ * r3fRootFactory)`).
  *
  * ## The mount mechanics (fiber v9, host-gated)
  *