@vgai/engine 0.5.21 → 0.5.23

package/dist/runtime/types.d.ts

@@ -1,303 +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 {
-    /** 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;
-    /** 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;
-    /** 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>;
-//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/types.js

@@ -1 +0,0 @@
-export {};

package/dist/world3d-react/engine-bridge.d.ts

@@ -1,47 +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 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 declare const EngineBridge: import("react").Context<EngineBridgeValue | 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 declare function useGameContext(): R3FGameContext;
-//# sourceMappingURL=engine-bridge.d.ts.map

package/dist/world3d-react/engine-bridge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC;;wCAEoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAkC/C"}

package/dist/world3d-react/engine-bridge.js

@@ -1,73 +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';
-export const EngineBridge = createContext(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() {
-    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;
-}

package/dist/world3d-react/r3f-adapter.d.ts

@@ -1,58 +0,0 @@
-/**
- * `createR3FAdapter` — wraps a react-three-fiber tree as a first-party
- * `RootAdapter` so an R3F scene mounts as an ordinary `kind: "three"`
- * world: the engine hands `mount()` a `ThreeHostContext` (ITS OWN renderer +
- * canvas + gated loop, per `../adapter/host-context.ts`); this returns a
- * `MountedThreeRoot` (`../adapter/root-adapter.ts`) whose `scene`/`camera`
- * are fiber's REAL `THREE.Scene`/`THREE.Camera` instances.
- *
- * Upstreamed from `examples/r3f-first-party/src/r3f-adapter.tsx` (R4 — the
- * `@engine/world3d-react` opt-in module, mirroring how `pixi/` is the
- * PixiJS surface's opt-in home). The mount semantics
- * are byte-for-byte the example's live-proven Phase-1 bridge. External adopters
- * (alien-stories-style) keep the exact same calling contract.
- *
- * three.js identity: this module never imports `three` itself for scene objects
- * — fiber's internal `import * as THREE from 'three'` must resolve to the SAME
- * instance the engine's `ThreeHostContext.three` points at, which the importing
- * project guarantees via its Vite `resolve.dedupe: ['three', 'react',
- * 'react-dom']` (see `examples/r3f-first-party/vite.config.ts`).
- */
-import { type ReactNode } from 'react';
-import type { RootAdapter } from '../adapter';
-import { type WorldRendererConfig } from '../adapter/renderer-config';
-/** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
-export interface CreateR3FAdapterOptions {
-    /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
-    readonly id: string;
-    /** The R3F scene tree to mount — drei helpers, `useFrame` hooks, etc. all
-     *  work unchanged (design §1.C: "drei works unchanged (it is fiber-context
-     *  userland)"). */
-    readonly content: ReactNode;
-    /** Input map loaded through the game-owned `Game.loadInputMap` (load-once
-     *  across roots). Defaults to the classic adapter's conventional path,
-     *  `/inputmaps/default.inputmap.json`; `null` opts out (a world with no
-     *  actions). A missing/invalid map degrades loudly without failing the
-     *  mount — see `world-context.ts`. */
-    readonly inputMapPath?: string | null | undefined;
-    /**
-     * Transitional compatibility for explicit pre-native adapters. The
-     * default-export root factory always passes `false`: ordinary R3F trees get
-     * no vgai context/provider or private scheduler. Remove this switch with
-     * the last explicit legacy adapter migration.
-     */
-    readonly engineRuntime?: boolean | undefined;
-    /** The colour pipeline this world was AUTHORED for, applied to the host's renderer for the life
-     *  of the mount and restored on dispose. Omit it (every world here does) to keep the host's own
-     *  defaults; declare it when the world's colours were picked against a different engine's
-     *  pipeline — see `../adapter/renderer-config.ts`. */
-    readonly renderer?: WorldRendererConfig | undefined;
-}
-/**
- * Build a `RootAdapter` that mounts `options.content` through
- * react-three-fiber, gated entirely by the host's own loop and rendering
- * through the host's own `WebGLRenderer` — never a second renderer, never a
- * second `requestAnimationFrame` loop (design §1.C).
- */
-export declare function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter;
-//# sourceMappingURL=r3f-adapter.d.ts.map

package/dist/world3d-react/r3f-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,OAAO,EAA2B,KAAK,SAAS,EAAsB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AA+DhG,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C;;;0DAGsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA2kB9E"}