@vgai/engine 0.5.5 → 0.5.6

package/dist/world3d-react/rapier-physics-bridge.js

@@ -0,0 +1,120 @@
+/**
+ * `<RapierPhysicsBridge>` — the one line that makes an R3F world's
+ * `@react-three/rapier` physics VISIBLE to the engine's editor/dev seams.
+ *
+ * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
+ * coordination (`freeze → apply → unfreeze`) and the dev menu's universal
+ * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
+ * first-party imperative three root registers one from
+ * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
+ * Rapier runtime at all (see `R3FGameContext`'s doc comment) — it does physics
+ * with `@react-three/rapier` INSIDE the fiber tree, where nothing engine-side
+ * can see it. Result, before this: the colliders instrument read `null` (an
+ * em-dash) and its toggle threw "no physics adapter" in every shipped example
+ * and every scaffolded game.
+ *
+ * NOT A WRAPPER. This registers an adapter and gets out of the way: the world
+ * still writes `<Physics>` itself, with the library's own props, and every
+ * `<RigidBody>`/collider call stays `@react-three/rapier`'s own API. The one
+ * thing it cannot do for you is flip the library's debug rendering, because
+ * `@react-three/rapier@2` exposes that ONLY as the `debug` boolean PROP on
+ * `<Physics>` (its `<Debug>` component is internal and unexported). A prop is
+ * the parent's to own, so the world holds the state and this bridge hands the
+ * setter to the instrument — which is why `onDebugChange` is required:
+ *
+ * ```tsx
+ * const [physicsDebug, setPhysicsDebug] = useState(false);
+ * // …
+ * <Physics debug={physicsDebug}>
+ *   <RapierPhysicsBridge onDebugChange={setPhysicsDebug} />
+ *   …
+ * </Physics>
+ * ```
+ *
+ * Nothing draws colliders here: the wireframes are the library's own
+ * `world.debugRender()` output, rendered by its own component.
+ *
+ * ANTI-SHIM. `debugDraw()` and `contactPoints()` are OMITTED, not stubbed —
+ * the library owns its debug line segments inside the tree and hands out no
+ * handle to them, so claiming the capability would be a fabrication. Absence
+ * is how a `SystemAdapters` member says "not supported".
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * OWNER: this component owns exactly ONE `SystemAdapters.physics` registration,
+ * on the R3F root it is mounted in. It allocates nothing else — no timers, no
+ * subscriptions, no per-frame work (see the phase note below), and no Rapier
+ * objects: the bodies it edits belong to `<Physics>`.
+ * SHARERS: every reader of `game.systemAdapters.physics` — the dev menu's
+ * colliders instrument, the editor's transform coordination. They read; they
+ * never dispose.
+ * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
+ * set (`registerSystemAdapter('physics', undefined)`, which
+ * `Game.computeSystemAdapters` skips), so a play stop/start, a hot restart, or
+ * a world that unmounts `<Physics>` leaves no stale adapter behind. Two
+ * bridges in one root would fight over that one key; mount exactly one.
+ *
+ * PHASE ORDERING: none to respect — this component registers pull-only
+ * callbacks and runs no per-frame work. Every method it exposes is invoked
+ * BETWEEN frames, by an editor gesture or a dev-menu command, never from a
+ * phase.
+ */
+import { useRapier } from '@react-three/rapier';
+import { useEffect } from 'react';
+import { createRapierBodyEditing, } from '../adapter/rapier-physics-adapter';
+import { useGameContext } from './engine-bridge';
+/**
+ * Register this R3F world's `@react-three/rapier` physics as the game's
+ * `SystemAdapters.physics`. Mount it once, INSIDE `<Physics>` (it reads
+ * `useRapier()`). Renders nothing.
+ */
+export function RapierPhysicsBridge({ onDebugChange }) {
+    const ctx = useGameContext();
+    const { rigidBodyStates } = useRapier();
+    const registerSystemAdapter = ctx.registerSystemAdapter;
+    useEffect(() => {
+        if (!registerSystemAdapter)
+            return;
+        /**
+         * node id → the Rapier body driving it, in two hops the library and the
+         * engine each already own:
+         *
+         *  1. id → `Object3D`, through the live scene index — `userData.entityId`
+         *     is this stack's identity convention (the editor's R3F authoring
+         *     adapter stamps it; `../adapter/setup-three-root-adapter.ts` resolves
+         *     the same way for the imperative root).
+         *  2. `Object3D` → body, through `rigidBodyStates` — the library's OWN
+         *     body↔object map, carried on the `RapierContext` `useRapier()`
+         *     returns. Walking ANCESTORS matters: `<RigidBody>` owns a subtree, so
+         *     the selected mesh is usually a descendant of the object the state
+         *     names.
+         *
+         * Both maps are live, so this is computed per call rather than cached —
+         * calls arrive at gesture rate (a gizmo drag start/end, a dev command),
+         * never per frame. `ctx.sceneIndex` is read AT CALL TIME, never captured:
+         * the R3F root backfills it once fiber resolves the scene, which can land
+         * after this component's first effect (`world-context.ts`'s
+         * `setSceneCamera`), so a destructured copy would be permanently absent.
+         */
+        const bodyFor = (nodeId) => {
+            const object = ctx.sceneIndex?.byEntityId(nodeId);
+            if (!object)
+                return undefined;
+            const byObject = new Map();
+            for (const state of rigidBodyStates.values())
+                byObject.set(state.object, state.rigidBody);
+            for (let node = object; node; node = node.parent) {
+                const body = byObject.get(node);
+                if (body)
+                    return body;
+            }
+            return undefined;
+        };
+        const adapter = {
+            ...createRapierBodyEditing(bodyFor),
+            setDebugDrawEnabled: (enabled) => onDebugChange(enabled),
+        };
+        registerSystemAdapter('physics', adapter);
+        return () => registerSystemAdapter('physics', undefined);
+    }, [ctx, registerSystemAdapter, rigidBodyStates, onDebugChange]);
+    return null;
+}

package/dist/world3d-react/renderer-config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * world3d-react/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ *
+ * The host owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it with this
+ * engine's defaults: ACES tone mapping, sRGB output, PCF-soft shadows. Those defaults are right for
+ * a world authored against them and WRONG for a world that was authored against a different
+ * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
+ * at all, so ACES quietly desaturates and darkens every colour its author picked.
+ *
+ * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
+ * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
+ * of that shape are load-bearing:
+ *
+ *  - **It is per-renderer, never engine-wide.** Every field here is a `WebGLRenderer` instance
+ *    property, and a play root gets its own renderer (`create-runtime.ts`). Nothing here reaches a
+ *    module-level three global, so one world's declaration cannot change how the editor's own
+ *    viewport, another root, or a thumbnail bake renders.
+ *  - **Absent means "leave the host's value alone".** Every field is optional and an omitted one
+ *    is never written, so declaring a tone mapping does not silently reset the clear colour.
+ *  - **It is restored on dispose.** The renderer outlives the mount, so a world that did not put
+ *    back what it found would leak its pipeline into whatever mounts next.
+ *
+ * This is deliberately NOT a general render-settings system. It carries what a world can honestly
+ * state about its own colour pipeline and nothing else; a property the host fixes at CONSTRUCTION
+ * (the WebGL context's `antialias` attribute, and therefore the MSAA sample count) cannot be
+ * declared here, because there would be no honest moment to apply it.
+ */
+import type * as THREE from 'three';
+/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
+export type WorldToneMapping = 'none' | 'linear' | 'reinhard' | 'cineon' | 'aces' | 'agx' | 'neutral';
+/**
+ * The output transfer function the frame is written with.
+ *
+ *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
+ *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
+ *    result is already in display space and encoding it a second time washes the frame out.
+ */
+export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
+/** What a world may declare about the renderer that draws it. Every field is optional; see header. */
+export interface WorldRendererConfig {
+    readonly toneMapping?: WorldToneMapping | undefined;
+    readonly toneMappingExposure?: number | undefined;
+    readonly outputColorSpace?: WorldOutputColorSpace | undefined;
+    /**
+     * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
+     * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
+     * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
+     */
+    readonly clearColor?: string | undefined;
+}
+/**
+ * Apply `config` to `renderer`, returning the restore function that puts back what was there.
+ *
+ * `three` is passed in rather than imported for values so the enum constants come from the HOST's
+ * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ */
+export declare function applyWorldRendererConfig(three: typeof THREE, renderer: THREE.WebGLRenderer, config: WorldRendererConfig): () => void;
+//# sourceMappingURL=renderer-config.d.ts.map

package/dist/world3d-react/renderer-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-config.d.ts","sourceRoot":"","sources":["../../src/world3d-react/renderer-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,MAAM,GACN,KAAK,GACL,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,aAAa,CAAC;AAE3D,sGAAsG;AACtG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,KAAK,EACnB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,MAAM,EAAE,mBAAmB,GAC1B,MAAM,IAAI,CAgEZ"}

package/dist/world3d-react/renderer-config.js

@@ -0,0 +1,96 @@
+/**
+ * world3d-react/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ *
+ * The host owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it with this
+ * engine's defaults: ACES tone mapping, sRGB output, PCF-soft shadows. Those defaults are right for
+ * a world authored against them and WRONG for a world that was authored against a different
+ * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
+ * at all, so ACES quietly desaturates and darkens every colour its author picked.
+ *
+ * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
+ * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
+ * of that shape are load-bearing:
+ *
+ *  - **It is per-renderer, never engine-wide.** Every field here is a `WebGLRenderer` instance
+ *    property, and a play root gets its own renderer (`create-runtime.ts`). Nothing here reaches a
+ *    module-level three global, so one world's declaration cannot change how the editor's own
+ *    viewport, another root, or a thumbnail bake renders.
+ *  - **Absent means "leave the host's value alone".** Every field is optional and an omitted one
+ *    is never written, so declaring a tone mapping does not silently reset the clear colour.
+ *  - **It is restored on dispose.** The renderer outlives the mount, so a world that did not put
+ *    back what it found would leak its pipeline into whatever mounts next.
+ *
+ * This is deliberately NOT a general render-settings system. It carries what a world can honestly
+ * state about its own colour pipeline and nothing else; a property the host fixes at CONSTRUCTION
+ * (the WebGL context's `antialias` attribute, and therefore the MSAA sample count) cannot be
+ * declared here, because there would be no honest moment to apply it.
+ */
+/**
+ * Apply `config` to `renderer`, returning the restore function that puts back what was there.
+ *
+ * `three` is passed in rather than imported for values so the enum constants come from the HOST's
+ * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ */
+export function applyWorldRendererConfig(three, renderer, config) {
+    // A host that mounts a world WITHOUT rasterizing it hands the adapter a duck-typed renderer —
+    // the editor's design session (`createDesignTimeRenderer`: four members, deliberately never
+    // widened) and jsdom test harnesses both do. Such a surface has no colour pipeline to configure:
+    // the frame the user sees is drawn by a DIFFERENT renderer (the editor's own), so applying the
+    // world's config there is meaningless — and calling `getClearColor` on it is a TypeError that
+    // unmounts the whole world at edit time (measured: every Godot port's edit viewport blanked with
+    // '"world" failed to mount — renderer.getClearColor is not a function'). Detect the real
+    // `WebGLRenderer` surface by the one method this function must call, and no-op otherwise.
+    if (typeof renderer.getClearColor !== 'function') {
+        return () => { };
+    }
+    const toneMappings = {
+        none: three.NoToneMapping,
+        linear: three.LinearToneMapping,
+        reinhard: three.ReinhardToneMapping,
+        cineon: three.CineonToneMapping,
+        aces: three.ACESFilmicToneMapping,
+        agx: three.AgXToneMapping,
+        neutral: three.NeutralToneMapping,
+    };
+    const colorSpaces = {
+        srgb: three.SRGBColorSpace,
+        'srgb-linear': three.LinearSRGBColorSpace,
+    };
+    const restores = [];
+    if (config.toneMapping !== undefined) {
+        const previous = renderer.toneMapping;
+        renderer.toneMapping = toneMappings[config.toneMapping];
+        restores.push(() => {
+            renderer.toneMapping = previous;
+        });
+    }
+    if (config.toneMappingExposure !== undefined) {
+        const previous = renderer.toneMappingExposure;
+        renderer.toneMappingExposure = config.toneMappingExposure;
+        restores.push(() => {
+            renderer.toneMappingExposure = previous;
+        });
+    }
+    if (config.outputColorSpace !== undefined) {
+        const previous = renderer.outputColorSpace;
+        renderer.outputColorSpace = colorSpaces[config.outputColorSpace];
+        restores.push(() => {
+            renderer.outputColorSpace = previous;
+        });
+    }
+    if (config.clearColor !== undefined) {
+        const previousColor = new three.Color();
+        renderer.getClearColor(previousColor);
+        // Alpha is READ BACK and re-passed, never assumed: see `clearColor`'s doc above.
+        const alpha = renderer.getClearAlpha();
+        renderer.setClearColor(new three.Color(config.clearColor), alpha);
+        restores.push(() => {
+            renderer.setClearColor(previousColor, alpha);
+        });
+    }
+    return () => {
+        // Reverse order, so a field written twice (it cannot be, today) unwinds correctly.
+        for (let i = restores.length - 1; i >= 0; i--)
+            restores[i]?.();
+    };
+}

package/dist/world3d-react/world-context.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `createR3FRootContext` — the ENGINE runtime an R3F world owns, split out of
+ * `./r3f-adapter.tsx` so it stays react-free and headlessly unit-testable
+ * (`test/world3d-react-context-parity.test.tsx`).
+ *
+ * Context parity with the classic first-party adapter
+ * (`../adapter/setup-three-root-adapter.ts`) — closed here after a dogfood
+ * build had to shim around three silent gaps:
+ *
+ *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired**
+ *     exactly the way the classic adapter wires them: the ONE game-scoped
+ *     debug registry (`getDebugRegistry(host.game)`) provides
+ *     `ctx.debug = registry.forRoot(id)`, so a component's
+ *     effect can `ctx.debug.registerStateProvider(...)` and be visible
+ *     to `vgai eval`/the editor's debug panels — previously a silent no-op.
+ *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` —
+ *     the same instance the classic adapter uses when hosted), and this
+ *     module registers the SAME per-world debug-registry seams the classic
+ *     adapter registers (`setVirtualInputTarget`/`setInputActionsSource`/
+ *     `setInputTraceSource`), which is what makes `game.input.*` (the bot
+ *     input doctrine) work instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *     The project's input map is loaded through `Game.loadInputMap` (the
+ *     game-owned, load-once path every root shares) with the SAME default
+ *     path the classic adapter uses. A missing/unparseable map degrades
+ *     LOUDLY (console.error naming the path and what breaks) without
+ *     failing the mount — an R3F tree with no actions (e.g. a pure
+ *     OrbitControls demo, `examples/r3f-first-party`) is legal.
+ *  3. **Absent subsystems are absent from the TYPE.** An R3F world builds no
+ *     Rapier world, composer, audio, particles, or debug-draw, and
+ *     {@link R3FGameContext} — the type `useGameContext()` hands back — simply
+ *     does not have those fields. Reaching for one is a compile error at the
+ *     call site, with the sanctioned alternative in that type's doc comment.
+ * */
+import type * as THREE from 'three';
+import type { ThreeHostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import { createSystemRunner } from '../core/system-runner';
+import type { GameContext } from '../runtime/types';
+/** The classic adapter's default input-map path — the conventional location
+ *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
+export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json";
+/**
+ * The engine context an R3F world genuinely provides — what
+ * `useGameContext()` hands back.
+ *
+ * An EXPLICIT `Pick`, never an `Omit`: a field added to `GameContext` later
+ * must be deliberately admitted here, so this surface can never silently widen
+ * into something an R3F mount does not build.
+ *
+ * **What an R3F world does NOT have, and what to reach for instead.** These
+ * are not oversights — the mount builds none of them, so they are absent from
+ * this type and naming one is a compile error rather than a crash mid-render:
+ *
+ * - **Physics** (`rapierWorld`, `rapier`, `physics`, `collisions`) — an R3F
+ *   world does not build the first-party Rapier runtime. Use a physics
+ *   solution inside the fiber tree (e.g. `@react-three/rapier`), or an
+ *   imperative three root whose `setup(ctx)` receives the first-party Rapier
+ *   runtime.
+ * - **`composer`** — R3F renders through react-three-fiber against the host
+ *   renderer; there is no postprocessing `EffectComposer` here. Use
+ *   fiber-native postprocessing inside the tree.
+ * - **`audio`** — no first-party audio context is built. Own a Web Audio graph
+ *   inside the tree (or use drei's audio helpers) and register it as this
+ *   world's `SystemAdapters.audio` via
+ *   `ctx.registerSystemAdapter('audio', …)`, so host mute/pause can still
+ *   silence it — `examples/third-person/src/lib/audio/sfx.ts` is the worked
+ *   reference.
+ * - **`particles`** — no three.quarks particle runtime. Drive particles from
+ *   the fiber tree.
+ * - **`debugDraw`** — no debug-draw helper. Add helper objects to the fiber
+ *   tree directly.
+ *
+ * For the full classic runtime, use an imperative three root instead: a module
+ * exporting `setup(ctx): Promise<GameCleanup>`, which `SetupThreeRootAdapter`
+ * mounts with the complete {@link GameContext}.
+ */
+export type R3FGameContext = Pick<GameContext, 'scene' | 'camera' | 'sceneIndex' | 'input' | 'assets' | 'systems' | 'clock' | 'debug' | 'random' | 'game' | 'roots' | 'playtest' | 'registerSystemAdapter'>;
+export interface R3FRootContextOptions {
+    /** World id — provenance for every debug-registry registration (matches the
+     *  manifest root id by the same convention the classic adapter follows). */
+    readonly id: string;
+    /**
+     * Input map to load through `Game.loadInputMap` (game-owned, load-once —
+     * several roots asking for the SAME path share one load; competing paths
+     * throw there). Defaults to {@link DEFAULT_INPUT_MAP_PATH}, the classic
+     * adapter's own default. Pass `null` to skip loading (a world with no
+     * actions). Ignored when no `host.game` is present.
+     */
+    readonly inputMapPath?: string | null | undefined;
+}
+/** What {@link createR3FRootContext} returns — the engine runtime one R3F
+ *  world owns, plus the wiring hooks `createR3FAdapter`'s `mount()` drives. */
+export interface R3FRootRuntime {
+    /** The context this world's components read through `useGameContext()` —
+     *  see {@link R3FGameContext} for exactly what an R3F world provides. */
+    readonly ctx: R3FGameContext;
+    /** The world-local phase runner `mount().update(dt)` ticks. */
+    readonly systems: ReturnType<typeof createSystemRunner>;
+    /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
+     *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
+    readonly systemAdapters: SystemAdapters;
+    /** Resolves once the input map load settles (immediately when skipped).
+     *  Never rejects — a failed load reports loudly and resolves. */
+    readonly inputMapReady: Promise<void>;
+    /** Backfill fiber's real scene/camera onto `ctx` after the first commit
+     *  resolves them — before any tick can run. `camera` is fiber's union
+     *  (perspective OR orthographic) — the ctx surface exposes whatever the
+     *  tree declared, exactly as the mounted world does. */
+    setSceneCamera(scene: THREE.Scene, camera: THREE.Camera): void;
+    /** Detach every component and strip this world's debug registrations
+     *  (scoped, like the classic adapter's teardown — sibling roots and
+     *  react-door registrations are untouched when a Game hosts this world). */
+    dispose(): void;
+}
+/**
+ * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
+ * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`
+ * performs for the subsystems an R3F world shares with it (debug, input,
+ * random). The ones it does not build are not on
+ * {@link R3FGameContext} at all.
+ */
+export declare function createR3FRootContext(host: ThreeHostContext, options: R3FRootContextOptions): R3FRootRuntime;
+//# sourceMappingURL=world-context.d.ts.map

package/dist/world3d-react/world-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQ3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,WAAW,EACT,OAAO,GACP,QAAQ,GACR,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,uBAAuB,CAC1B,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;6EACyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAqKhB"}

package/dist/world3d-react/world-context.js

@@ -0,0 +1,204 @@
+/**
+ * `createR3FRootContext` — the ENGINE runtime an R3F world owns, split out of
+ * `./r3f-adapter.tsx` so it stays react-free and headlessly unit-testable
+ * (`test/world3d-react-context-parity.test.tsx`).
+ *
+ * Context parity with the classic first-party adapter
+ * (`../adapter/setup-three-root-adapter.ts`) — closed here after a dogfood
+ * build had to shim around three silent gaps:
+ *
+ *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired**
+ *     exactly the way the classic adapter wires them: the ONE game-scoped
+ *     debug registry (`getDebugRegistry(host.game)`) provides
+ *     `ctx.debug = registry.forRoot(id)`, so a component's
+ *     effect can `ctx.debug.registerStateProvider(...)` and be visible
+ *     to `vgai eval`/the editor's debug panels — previously a silent no-op.
+ *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` —
+ *     the same instance the classic adapter uses when hosted), and this
+ *     module registers the SAME per-world debug-registry seams the classic
+ *     adapter registers (`setVirtualInputTarget`/`setInputActionsSource`/
+ *     `setInputTraceSource`), which is what makes `game.input.*` (the bot
+ *     input doctrine) work instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *     The project's input map is loaded through `Game.loadInputMap` (the
+ *     game-owned, load-once path every root shares) with the SAME default
+ *     path the classic adapter uses. A missing/unparseable map degrades
+ *     LOUDLY (console.error naming the path and what breaks) without
+ *     failing the mount — an R3F tree with no actions (e.g. a pure
+ *     OrbitControls demo, `examples/r3f-first-party`) is legal.
+ *  3. **Absent subsystems are absent from the TYPE.** An R3F world builds no
+ *     Rapier world, composer, audio, particles, or debug-draw, and
+ *     {@link R3FGameContext} — the type `useGameContext()` hands back — simply
+ *     does not have those fields. Reaching for one is a compile error at the
+ *     call site, with the sanctioned alternative in that type's doc comment.
+ * */
+import { createSeededRandom, DEFAULT_SEEDED_RANDOM_SEED, getSeededRandom, } from '../core/seeded-random';
+import { createSimClock, getSimClock } from '../core/sim-clock';
+import { createSystemRunner } from '../core/system-runner';
+import { createSceneIndex } from '../ecs/scene-index';
+import { createDebugRegistry, getDebugRegistry, } from '../runtime/debug-registry';
+import { disposeDebrisSubtree } from '../runtime/game';
+/** The classic adapter's default input-map path — the conventional location
+ *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
+export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
+/**
+ * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
+ * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`
+ * performs for the subsystems an R3F world shares with it (debug, input,
+ * random). The ones it does not build are not on
+ * {@link R3FGameContext} at all.
+ */
+export function createR3FRootContext(host, options) {
+    const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH } = options;
+    // Same observer threading as the classic adapter — profiler sees this
+    // world's phases under the shared game profiler when hosted.
+    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'three');
+    // The mounted world's adapter surface (`mounted.systems`) — declared before
+    // ctx so `ctx.registerSystemAdapter` can close over it (classic parity: a
+    // game-owned capability like networking registers here from component code).
+    const systemAdapters = {};
+    // The world's live scene index — built in `setSceneCamera` (below), because
+    // fiber resolves the scene after this function returns. Same lifetime as
+    // `ctx.scene`, which is backfilled at the same moment.
+    let sceneIndex = null;
+    const ctxRaw = {
+        systems,
+        assets: host.assets,
+        registerSystemAdapter: (kind, adapter) => {
+            // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the classic adapter performs; correct by construction
+            systemAdapters[kind] = adapter;
+            host.game?.notifySystemAdaptersChanged();
+        },
+    };
+    const ctx = ctxRaw;
+    if (host.game) {
+        ctx.game = host.game;
+        ctx.roots = host.game.roots;
+        ctx.playtest = host.game.playtest ?? null;
+    }
+    // --- ctx.debug (gap 1) — the ONE registry per Game root, shared across
+    // every world mounted onto it; a bare mount with no Game shell gets a
+    // private, mount-local registry instead (same absence precedent as the
+    // classic adapter). ---
+    const debugRegistry = (host.game ? getDebugRegistry(host.game) : null) ??
+        createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
+    systemAdapters.debug = debugRegistry.adapter;
+    ctx.debug = debugRegistry.forRoot(id);
+    ctx.random =
+        (host.game ? getSeededRandom(host.game) : null) ??
+            createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
+    // --- ctx.clock (P3) — every world has a sim clock, R3F included. Same
+    // game-scoped reach-in as `ctx.random` above; a bare mount with no Game
+    // shell gets a private, mount-local clock that nothing flushes (there is no
+    // fixed loop to bind timers to). The mount-local fallback uses the SAME
+    // `disposeDebrisSubtree` the hosted path uses — it drops
+    // the subtree and disposes geometry/materials, with no Rapier owners
+    // because this ctx carries no `physics`/`rapierWorld` (the
+    // honest "this world owns no bodies").
+    const gameClock = host.game ? getSimClock(host.game) : null;
+    const clock = gameClock ?? createSimClock({ dispose: (obj) => disposeDebrisSubtree(obj, []) });
+    ctx.clock = clock;
+    // --- ctx.input + the debug-registry input seams (gap 3) — the game-owned
+    // InputManager, polled by the game-scoped runner each frame; this world
+    // registers the SAME per-world seams the classic adapter registers so
+    // `game.input.*` (virtual input) and the built-in `input.actions`/
+    // `input.trace` providers resolve to it. ---
+    let inputMapReady = Promise.resolve();
+    if (host.game) {
+        const game = host.game;
+        const input = game.input;
+        ctxRaw['input'] = input;
+        debugRegistry.setInputActionsSource(id, () => input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })));
+        debugRegistry.setInputTraceSource(id, () => {
+            const raw = input.getInputTrace();
+            return {
+                version: raw.version,
+                seed: getSeededRandom(game)?.seed ?? null,
+                fixedDt: game.loop.fixedDt,
+                ticks: raw.ticks,
+            };
+        });
+        debugRegistry.setVirtualInputTarget(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.headless && inputMapPath !== null) {
+            // Load-once through the game-owned path (classic parity — competing
+            // paths across roots throw THERE, loudly). A FAILED load (missing/bad
+            // file) must not fail this mount: an R3F tree with no declared actions
+            // is legal. It degrades loudly instead — naming exactly what breaks.
+            inputMapReady = game.loadInputMap(inputMapPath).catch((err) => {
+                // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
+                console.error(`R3F world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+                    'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+                    'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
+                    `createR3FAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+    }
+    else {
+        // `input` IS a field of every R3F world's ctx — it is game-owned, and this
+        // particular mount has no Game to own it (a bare harness or a foreign
+        // host). A throwing getter names that at the read, instead of handing back
+        // `undefined` that breaks deep inside a frame callback. Non-enumerable so
+        // spreads/serialization of the ctx never trip it.
+        Object.defineProperty(ctxRaw, 'input', {
+            configurable: true,
+            enumerable: false,
+            get() {
+                throw new Error(`R3F world "${id}": ctx.input is game-owned and this mount has no Game host ` +
+                    '(host.game is absent — bare harness/foreign host); mount through the vgai host ' +
+                    'to get the shared InputManager.');
+            },
+        });
+    }
+    return {
+        ctx,
+        systems,
+        systemAdapters,
+        inputMapReady,
+        setSceneCamera(scene, camera) {
+            const sameScene = ctxRaw['scene'] === scene && sceneIndex !== null;
+            ctxRaw['scene'] = scene;
+            ctxRaw['camera'] = camera;
+            // The live scene index (P2 `observe`) is a REAL value here, not a
+            // throwing getter — every three world has one. It can only be built once
+            // fiber has resolved the scene, which is the same moment `ctx.scene`
+            // itself becomes readable, so index and scene share one lifetime. A
+            // second commit (fiber handing back a different scene) replaces it.
+            //
+            // Keyed on the SCENE, so a camera-only backfill (a world swapping the
+            // default camera after mount) leaves the index — and every `observe`
+            // subscription hanging off it — alone.
+            if (sameScene)
+                return;
+            sceneIndex?.dispose();
+            sceneIndex = createSceneIndex(scene);
+            ctxRaw['sceneIndex'] = sceneIndex;
+        },
+        dispose() {
+            // Same ownership rule as the classic adapter's teardown: dispose ONLY a
+            // clock this mount created. The game-scoped one belongs to
+            // `GameInternal.dispose()` — killing it here would freeze sim time and
+            // cancel every SIBLING world's timers.
+            if (!gameClock)
+                clock.dispose();
+            sceneIndex?.dispose();
+            sceneIndex = null;
+            // Scoped strip when a Game hosts this world (sibling roots stay live);
+            // a bare standalone mount owns its private registry and clears it all.
+            if (host.game)
+                debugRegistry.strip(id);
+            else
+                debugRegistry.strip();
+        },
+    };
+}