@vgai/engine 0.5.21 → 0.5.23

package/src/runtime/types.ts

@@ -1,328 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import type { EffectComposer } from 'postprocessing';
-import type * as THREE from 'three';
-import type { z } from 'zod';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import type { AssetCache } from '../assets';
-import type { SeededRandom } from '../core/seeded-random';
-import type { SimClock } from '../core/sim-clock';
-import type { createSystemRunner } from '../core/system-runner';
-import type { createDebugDraw } from '../dev/debug-draw';
-import type { SceneIndex } from '../ecs/scene-index';
-import type { InputManager } from '../input/input-manager';
-import type { CollisionSystem } from '../physics/collision-system';
-import type { PhysicsRegistry } from '../physics/physics-registry';
-import type { AudioContext as GameAudio } from '../setup/setup-audio';
-import type { ParticlesContext } from '../setup/setup-particles';
-import type { Game, RootInstance } from './game';
-
-/**
- * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
- * Colyseus room: just enough to send the reserved `__vgai:debugCommand`
- * message and listen for its `__vgai:debugCommandResult` reply. Structural,
- * not a Colyseus type import — the same seam-boundary style every other
- * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
- * `onMessage`'s return type is `unknown` because Colyseus's own return shape
- * (void in some client versions, an unsubscribe function in others) isn't
- * load-bearing here: the registry calls it defensively (invokes it on detach
- * only if it's actually a function).
- */
-export interface DebugRoomHandle {
-  send(type: string, message?: unknown): void;
-  onMessage(type: string, cb: (message: unknown) => void): unknown;
-}
-
-/**
- * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
- * handler's parameter tuple from its declared Zod `args` tuple (dry-run
- * finding, ledger — "`registerCommand` fn typing forces `unknown[]` casts"):
- * a real `z.ZodTuple` infers its element types (`z.tuple([z.number(),
- * z.string()])` → `(n: number, s: string) => ...`), while omitting `args`
- * (the generic's `undefined` default) resolves to the original permissive
- * `(...args: unknown[]) => ...` shape every command had before this generic
- * existed. That permissive fallback is deliberate, not just a placeholder —
- * it keeps every existing no-schema registration (including ones whose
- * handler reads positional args the runtime never validates, since
- * `invoke()` only parses `args` against a schema when one is declared)
- * compiling byte-for-byte unchanged.
- */
-export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T extends z.ZodTuple
-  ? z.infer<T>
-  : unknown[];
-
-/**
- * The authoring half of the debug/synthetic-player seam — the read/actuate half is
- * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from any
- * `init` (one file per new provider/command), or from a react world's
- * `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration feeds the ONE
- * game-scoped registry (`runtime/debug-registry.ts`) — never a per-world accumulator.
- */
-export interface DebugCtxSurface {
-  /** Register (or replace) a named, JSON-serializable state read. Duplicate
-   *  names from the SAME world replace + warn once; the SAME name from a
-   *  DIFFERENT world throws (`DebugError` code `DEBUG_NAME_COLLISION`). */
-  registerStateProvider(
-    name: string,
-    fn: () => unknown,
-    opts?: { tier?: 'observable' | 'assisted' },
-  ): void;
-  /** Register (or replace) an invokable command. `locus` is REQUIRED once the
-   *  project declares a Colyseus room (`DebugRegistry.setRoomDeclared`) — a
-   *  fixture must say whether it mutates authoritative (server) or predicted
-   *  (client) state.
-   *
-   *  Generic over the declared `args` Zod tuple ({@link DebugCommandArgs}) so
-   *  `fn`'s parameters INFER from it: `registerCommand('setHp', { args:
-   *  z.tuple([z.number()]) }, (hp) => ...)` types `hp` as `number` with no
-   *  cast. Leaving `args` off keeps `fn` typed `(...args: unknown[]) => ...`,
-   *  same as before this generic existed. */
-  registerCommand<T extends z.ZodTuple | undefined = undefined>(
-    name: string,
-    spec: { description?: string; args?: T; locus?: 'client' | 'server' },
-    fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
-  ): void;
-  /** Push a tick-stamped event onto the debug event ring (spec §3.3) — the
-   *  engine stamps `tick`/`simT` at emission, not at read time. */
-  emit(event: string, detail?: unknown): void;
-  /**
-   * Task 2.2 — server-locus command routing (client leg). Call once your
-   * game code has joined its Colyseus room, so `locus: 'server'` commands
-   * have somewhere to send `__vgai:debugCommand`. Returns a detach function
-   * (call on room leave/dispose) — game-scoped, last-attached room wins.
-   */
-  attachRoom(room: DebugRoomHandle): () => void;
-}
-
-/**
- * All engine subsystems, passed to every game `setup(ctx)` and to each
- * game lifecycle callback.
- *
- * The surface is intentionally split in two:
- *
- * - **Raw libraries** — the actual Three.js / Rapier / postprocessing objects.
- *   Call their documented APIs directly; do NOT build wrappers around them.
- * - **Engine handles** — thin VGAI-owned managers that bridge those libraries
- *   into the phase-ordered game loop. Reach for these when you need behavior the
- *   raw library doesn't provide (physics↔Object3D mapping, system phases, etc.).
- */
-/** 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;
-}
-
-export interface GameContext {
-  // ─── Raw libraries (the real library objects — call them directly) ───
-
-  /** Three.js scene graph root. Add/remove any `Object3D` (meshes, lights,
-   *  groups) here. This is THE scene — there is no separate engine scene. */
-  scene: THREE.Scene;
-  /** The single render camera. Move/aim it directly, or (preferred) drive it
-   *  from game code — see the camera-precedence note below. */
-  camera: THREE.PerspectiveCamera;
-  /** The Rapier physics `World`. Step/query it, create bodies & colliders via
-   *  `ctx.rapier`. One shared world for the whole scene. */
-  rapierWorld: RAPIER.World;
-  /** The Rapier module namespace itself (`RigidBodyDesc`, `ColliderDesc`,
-   *  `Vector3`, enums, …). Use to construct physics descriptors. */
-  rapier: typeof RAPIER;
-  /** The `postprocessing` EffectComposer driving the final render. Use to
-   *  add/remove passes (bloom, vignette, …) or reach the underlying
-   *  `WebGLRenderer` via `composer.getRenderer()`. */
-  composer: EffectComposer;
-
-  // ─── Engine handles (VGAI managers — use when the raw lib isn't enough) ───
-
-  /** Keyboard/mouse/gamepad input. Polled once per frame in the `input` phase;
-   *  read action/axis state inside your `update`. */
-  input: InputManager;
-  /** Rapier collision-event dispatcher. Register handlers with
-   *  `collisions.onCollision(...)`; it is drained each `postPhysics`. Prefer a
-   *  own handler for per-entity sensor logic. */
-  collisions: CollisionSystem;
-  /** `Object3D ↔ Rapier body/collider` registry (+ collider→Object3D reverse
-   *  index). Use to find an entity's body/collider, or the entity behind a
-   *  raw collision. Inside a component, `this.rigidBody`/`this.collider` are
-   *  pre-resolved from here. */
-  physics: PhysicsRegistry;
-  /** Procedural audio: master gain, listener, and one-shot/impact helpers.
-   *  Use for SFX and music; the listener tracks the camera. */
-  audio: GameAudio;
-  /** three.quarks particle system: the batched renderer + spawn helpers. Use
-   *  to emit runtime particle effects; declarative scene particles register
-   *  here automatically. */
-  particles: ParticlesContext;
-  /** Immediate-mode debug drawing (`line`/`box`/`sphere`/`arrow`). Drawn
-   *  objects persist until you call `debugDraw.clear()` yourself (the
-   *  adapter also clears on scene dispose/hot-reload) — nothing clears it
-   *  automatically per frame. Dev-only visualization — not for shipped
-   *  visuals. */
-  debugDraw: ReturnType<typeof createDebugDraw>;
-  /** Shared GLTF/texture cache. Use `assets.loadGLTF(...)` etc. to load+cache
-   *  models at runtime so repeated loads reuse geometry/material. */
-  assets: AssetCache;
-  /** The phase-ordered system runner. `systems.add(phase, fn)` registers a
-   *  per-frame callback. Reserve this for non-gameplay infra (audio mixers,
-   *  network send); per-entity GAMEPLAY belongs in a `useFrame` hook. */
-  systems: ReturnType<typeof createSystemRunner>;
-  /**
-   * P3 — the SIM-TIME scheduler (`core/sim-clock.ts`). `await ctx.clock.delay(n)`
-   * waits `n` seconds of the fixed loop's own time, so it pauses when the game
-   * pauses, steps when `Game.play.step()` steps, and reproduces exactly in an
-   * offline export; `ctx.clock.after(n, fn)` is the frame-exact synchronous
-   * form, and `ctx.clock.disposeAfter(obj, n)` is debris removal. Cancellation
-   * is `AbortSignal`.
-   *
-   * REQUIRED, unlike `debug`/`random` above: every world has a sim clock. When
-   * a Game hosts the mount it is the ONE game-scoped clock the fixed loop
-   * flushes; a bare harness mount with no Game shell gets a private,
-   * mount-local clock that nothing advances (so `now()` stays 0) rather than an
-   * absent field.
-   *
-   * NOT `AnimationClock` (`animation/animation-clock.ts`) — that one is the
-   * seekable cinematic playhead and runs backwards. This one is monotonic and
-   * never rewinds, which is exactly why a Promise can be bound to it. See
-   * `core/sim-clock.ts`'s header.
-   */
-  clock: SimClock;
-  /** The live scene index for this root (P2 `observe`): tag/entity-id lookup
-   *  that never traverses, plus the change signals — `entityadded`,
-   *  `entityremoved`, `tagadded`, `tagremoved`, `attributechanged` — on a plain
-   *  `EventTarget`, unsubscribed with an `AbortSignal`. Maintained from three's
-   *  own `childadded`/`childremoved` parent events, so it costs nothing on a
-   *  frame where nothing changes. See `ecs/scene-index.ts`; the one-shot
-   *  `ecs/scene-query.ts` walks remain for a single ad-hoc question. */
-  sceneIndex: SceneIndex;
-  /** Register a game-owned `SystemAdapters` capability (networking,
-   *  navigation, …) on the mounted game's adapter surface, so the editor's
-   *  introspection panels (via `getActiveSystems()`) can see it. The engine
-   *  wires the first-party physics/input/assets/audio entries itself;
-   *  capabilities the GAME owns (a Colyseus connection, a NavMeshManager)
-   *  are registered here by the game's setup. Optional capability — absent
-   *  in contexts that expose no adapter surface (some test harnesses);
-   *  call as `ctx.registerSystemAdapter?.(…)`.
-   *
-   *  Ordering contract: **game registrations always win** — the engine seeds
-   *  its first-party entries (physics/input/assets/audio) BEFORE setup()
-   *  runs, so a game that registers any of those same kinds during its own
-   *  setup overrides the engine's entry, not the other way around. This also
-   *  holds across a warm restart (`hotReload`): every kind the outgoing game
-   *  registered is stripped back to the engine's entry (or absent, for
-   *  game-only kinds like networking/navigation) before the incoming game's
-   *  setup runs, so a disposed game's adapter is never left stale on the
-   *  mounted surface. */
-  registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
-
-  /** The debug/synthetic-player authoring surface — see {@link DebugCtxSurface}.
-   *  Optional, same absence precedent as `registerSystemAdapter`: present on every
-   *  first-party mount, absent only in bare test harnesses that build a
-   *  hand-rolled `ctx`. */
-  debug?: DebugCtxSurface;
-
-  /**
-   * D15 (T-D15.1) — the game-scoped, named-stream seeded PRNG. `ctx.random()`
-   * draws from the `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other
-   * name) draws from an INDEPENDENT stream, so a cosmetic/VFX draw can never
-   * shift the gameplay draw sequence. Use this instead of raw `Math.random()` for
-   * anything a project wants to keep reproducible; `ctx.random` itself always
-   * exists and is always internally consistent (same seed ⇒ same sequence)
-   * whether or not the project's manifest declares `determinism.seededRandom` —
-   * that flag only gates the BOOT-TIME seeding from
-   * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint scan,
-   * and the dev-mode `Math.random` phase trap (three separate enforcers,
-   * `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`), never
-   * `ctx.random`'s mere presence. Same absence precedent as `debug` above:
-   * present on every first-party mount, optional only for bare test harnesses
-   * that build a hand-rolled `ctx`. `reseed(seed)` (future draws only) is
-   * `play.seed.set`'s eventual target (T-D15.6, not yet wired).
-   */
-  random?: SeededRandom;
-
-  // ─── Game root (T7.1 slice 1 — D6) ───
-
-  /** The Game root — the loop, the world registry, and game-scoped handles.
-   *  Absent only in bare test harnesses that construct a partial context (the
-   *  host always sets it in `createGameRuntime`). Optional so every existing
-   *  harness that builds a hand-rolled `ctx` object keeps compiling
-   *  unmodified — the same precedent as `registerSystemAdapter`. */
-  game?: Game | undefined;
-  /** Alias for `game.roots` — the live, declaration-ordered world registry.
-   *  Same optionality/absence rule as `game` above. */
-  roots?: ReadonlyArray<RootInstance> | undefined;
-  /** The host's current private play or Team Test identity. Optional for
-   * standalone/custom hosts; networking remains game-owned and direct. */
-  playtest?: PlaytestContext | null | undefined;
-}
-
-/**
- * Services shared by component-authored roots, independent of their render
- * surface. This is deliberately an explicit pick from {@link GameContext}:
- * adding a subsystem to the imperative Three setup context never silently
- * exposes it to R3F or Canvas components.
- *
- * `input` is nullable because it belongs to the optional `Game` host. Normal
- * vgai project mounts always provide it; bare harnesses and foreign hosts do
- * not. Component code therefore sees the absence in its type instead of a
- * getter that first throws from inside a frame callback.
- *
- * `clock` is surface-specific and intentionally absent here. The imperative
- * and R3F clocks can dispose `THREE.Object3D` debris; a Canvas context narrows
- * that Three-only operation away.
- */
-export type ComponentContextBase = Pick<
-  GameContext,
-  'systems' | 'debug' | 'random' | 'game' | 'roots' | 'playtest' | 'registerSystemAdapter'
-> & {
-  readonly input: InputManager | null;
-};
-
-/** Return value from a game setup function. */
-export interface GameCleanup {
-  dispose: () => void;
-}
-
-/** Context passed to setup() when launched from the editor's play mode. */
-export interface EditorPreview {
-  /** Editor viewport camera transform — use this as the initial game camera viewpoint. */
-  viewportCamera?: {
-    position: [number, number, number];
-    quaternion: [number, number, number, number];
-  };
-  /**
-   * Which bundled example the static/browser build's project picker wants to
-   * run (Adjudication H).
-   *
-   * Its one former reader — `browser-play-entry.ts`'s whole-bundle `setup()`,
-   * which dispatched over the generated `SETUP_BY_EXAMPLE_ID` table — is
-   * DELETED. Hosted dispatch is per-root (`ADAPTER_BY_EXAMPLE_ROOT` /
-   * `REACT_BY_EXAMPLE_ROOT`, resolved in `adapter-resolver.ts`) and never
-   * consults this field; `exampleDispatchFor` still sets it as the marker for
-   * "play the project's own shipped game" rather than a `?scene=` override
-   * (which sets `assetPrefix` instead — that one IS read, by
-   * `SetupThreeRootAdapter`). Every `GameSetupFn` consumer ignores it.
-   */
-  exampleId?: string | undefined;
-  /**
-   * Asset prefix for the static/browser build's GENERIC scene-loader fallback,
-   * set INSTEAD of `exampleId` when the editor has a non-default scene of a
-   * bundled example open (hosted `?project=<id>&scene=<project-relative>` —
-   * Track H): the open scene plays via `sceneData`, but its relative asset
-   * refs still live under the example's staged `/examples/<id>/` public root.
-   * Ignored whenever `exampleId` is set; undefined ⇒ root prefix `/`.
-   */
-  assetPrefix?: string | undefined;
-}
-
-/** A game setup function: receives engine context, returns cleanup.
- *
- * This is the MOUNT body of the FIRST-PARTY implementer. The host no longer
- * depends on it — the host depends on `RootAdapter` (`@engine/adapter`), and
- * `GameSetupFn` is wrapped into a `SetupThreeRootAdapter` via `fromSetup`.. (The
- * former `RootAdapter` `{ setup, components }` interface lived here; it is
- * superseded by the real adapter interfaces in `@engine/adapter`.) */
-export type GameSetupFn = (ctx: GameContext, editor?: EditorPreview) => Promise<GameCleanup>;

package/src/world3d-react/engine-bridge.ts

@@ -1,86 +0,0 @@
-/**
- * `@engine/world3d-react` — the React context that carries this R3F world's
- * engine runtime into its fiber tree: the world's `R3FGameContext`, read
- * with {@link useGameContext}.
- *
- * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4).
- * The bridge value
- * is built by `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
- * `createSystemRunner` whose phases the adapter's `update(dt)` runs under the
- * HOST loop — so registered systems tick in engine phase order, pause included
- * (no update while the world is frozen).
- *
- * Behavior in an R3F world is components and hooks: `useGameContext` is how a
- * component reaches engine services.
- */
-
-import { createContext, useContext } from 'react';
-import { useOptionalGame } from '../react/world-state';
-import type { R3FGameContext } from './world-context';
-
-export interface EngineBridgeValue {
-  /** This root's context — `input`, `debug`, `random`, `game`, `roots`, … .
-   *  Present so ordinary components can reach engine services with a HOOK
-   *  (see {@link useGameContext}). */
-  readonly ctx?: R3FGameContext | undefined;
-}
-
-export const EngineBridge = createContext<EngineBridgeValue | null>(null);
-
-/**
- * This R3F root's context, for use inside any component in the tree — an
- * {@link R3FGameContext}, which is exactly the subsystems an R3F world builds.
- * The ones it does not build are absent from the type, so reaching for one is
- * a compile error at the call site; that type's doc comment says what to reach
- * for instead.
- *
- * An ordinary component does what a model would write:
- *
- * ```tsx
- * function Player({ speed = 4.5 }) {
- *   const { input } = useGameContext();
- *   const ref = useRef<THREE.Group>(null);
- *   useFrame((_, dt) => { if (input?.isPressed('move_forward')) … });
- *   return <group ref={ref}><PlayerCharacter /></group>;
- * }
- * ```
- *
- * Throws when called outside an R3F root mounted by `createR3FAdapter` —
- * absent context is a wiring bug, and a silent `null` would surface as a
- * mystery `undefined` deep in a frame callback.
- */
-export function useGameContext(): R3FGameContext {
-  const bridge = useContext(EngineBridge);
-  // Read unconditionally (rules of hooks) — used only to shape the throw below.
-  const hostedByGame = useOptionalGame() !== null;
-  if (!bridge?.ctx) {
-    // NAME THE REAL CAUSE. This throw used to say "check that the component is
-    // rendered inside your world entry" — advice a scaffolded game has already
-    // followed, because the shape `vgai create` produces (`export default
-    // function World()`) mounts as a COMPONENT ROOT and receives no vgai
-    // runtime context at all: `r3f-root-factory.tsx` passes
-    // `engineRuntime: false` deliberately, so this hook can never resolve
-    // there however the component is nested. A world whose first render calls
-    // it dies with "fiber crashed before its first commit" and a fix
-    // instruction that cannot work. The `Game` in scope tells the two cases
-    // apart: present means a vgai-mounted world, absent means no root at all.
-    throw new Error(
-      hostedByGame
-        ? 'useGameContext(): this world mounts as a COMPONENT ROOT (the default-exported ' +
-            'shape `vgai create` scaffolds) and receives no vgai runtime context — by design, ' +
-            'so nesting cannot fix it. Game-scoped services are on the Game handle instead: ' +
-            '`useGame().input` (from @vgai/engine/react/world-state) is the game-owned ' +
-            "InputManager the host already loaded this project's input map into and the same " +
-            'one `game.input.hold/tap` drives; `useDebugProvider`/`useDebugCommand`/' +
-            '`useWorldState` are the state/command doors. If this world genuinely needs the ' +
-            'imperative runtime (`ctx.systems`, adapter options like `inputMapPath`), export ' +
-            '`adapter = createR3FAdapter({ id, content: <World/> })` from the entry instead of ' +
-            'default-exporting the component.'
-        : 'useGameContext(): no engine root context and no Game in scope — this component is ' +
-            'rendering outside any mounted vgai root (a standalone <Canvas>, a story, or a ' +
-            "bare test render). Mount it through your project's three root, or read services " +
-            'the component root way (native hooks and project-owned state).',
-    );
-  }
-  return bridge.ctx;
-}