@vgai/engine 0.5.16 → 0.5.17

package/src/world3d-react/world-context.ts

@@ -147,6 +147,103 @@ export interface R3FRootRuntime {
   dispose(): void;
 }
 
+/**
+ * The GAME-SCOPED input wiring one three root owns — and the half that has
+ * nothing to do with the vgai runtime context.
+ *
+ * Two things happen here, both of them HOST work performed from outside the
+ * world's own tree:
+ *
+ *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
+ *     load-once), so the actions the project declared exist;
+ *  2. this root's seams are registered on the game-scoped debug registry
+ *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
+ *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
+ *     doctrine) and the built-in `input.actions`/`input.trace` providers
+ *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *
+ * It is called on BOTH three-root paths, and that is the point: a world that
+ * mounts as a default-exported component receives no vgai runtime context
+ * (`engineRuntime: false` — see `r3f-root-factory.tsx`), but "no context in the
+ * tree" was never meant to say "the host does not wire this game's input". It
+ * was read that way, and the cost was measured on a fresh scaffold: the
+ * declared map never loaded and every `game.input.*` door threw, so the QA
+ * bot, autoplay routes and `vgai eval` could not drive the ONE world shape
+ * `vgai create` produces. Same split, same reasoning, as `WorldProvider`
+ * riding `host.game` rather than the runtime (see `r3f-adapter.tsx`).
+ *
+ * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
+ * never named a map: an absent file is the ordinary state of a brand-new
+ * project, so it resolves quietly instead of printing an error on every boot.
+ * A map that exists and fails to parse is as loud as ever.
+ *
+ * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose (both
+ * paths), but it walks providers/commands only — the three seams set here
+ * survive it, keyed by this world's id, until a remount of the same id
+ * overwrites them. That residue is inert rather than hidden: every closure
+ * below reads GAME-scoped state (`game.input`, `game.loop.fixedDt`, the game's
+ * seed), so a stale entry actuates exactly what a live one would. See the
+ * dispose comment in `r3f-adapter.tsx` for the full accounting.
+ */
+export function wireGameInputSeams(
+  host: ThreeHostContext,
+  registry: DebugRegistry,
+  options: {
+    readonly id: string;
+    readonly inputMapPath?: string | null | undefined;
+    readonly optionalInputMap?: boolean | undefined;
+  },
+): Promise<void> {
+  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH, optionalInputMap = false } = options;
+  if (!host.game) return Promise.resolve();
+  const game = host.game;
+  const input = game.input;
+  registry.setInputActionsSource(id, () =>
+    input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
+  );
+  registry.setInputTraceSource(id, () => {
+    const raw = input.getInputTrace();
+    return {
+      version: raw.version,
+      seed: getSeededRandom(game)?.seed ?? null,
+      fixedDt: game.loop.fixedDt,
+      ticks: raw.ticks,
+    };
+  });
+  registry.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) return Promise.resolve();
+  // Load-once through the game-owned path (competing paths across roots throw
+  // THERE, loudly). A FAILED load (missing/bad file) must not fail the mount:
+  // a three world with no declared actions is legal. It degrades loudly
+  // instead — naming exactly what breaks.
+  // The non-optional call passes ONE argument, exactly as it always has — a
+  // trailing `undefined` is a different call to any observer of it.
+  const load = optionalInputMap
+    ? game.loadInputMap(inputMapPath, { optional: true })
+    : game.loadInputMap(inputMapPath);
+  return load.catch((err: unknown) => {
+    // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
+    console.error(
+      `three 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)}`,
+    );
+  });
+}
+
 /**
  * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
  * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`
@@ -216,57 +313,9 @@ export function createR3FRootContext(
     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<void> = Promise.resolve();
-  if (host.game) {
-    const game = host.game;
-    const input = game.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: unknown) => {
-        // 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)}`,
-        );
-      });
-    }
-  }
+  // --- ctx.input + the debug-registry input seams (gap 3) — see
+  // `wireGameInputSeams` below; `ctx.input` is that same game-owned manager. ---
+  const inputMapReady = wireGameInputSeams(host, debugRegistry, { id, inputMapPath });
 
   return {
     ctx,

package/dist/runtime/dev-layers.d.ts

@@ -1,34 +0,0 @@
-/**
- * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
- * root flag). Every reader that has to answer that question calls
- * {@link devLayersEnabled}; there is deliberately NO second source of truth —
- * not a module-level cached boolean, not a `globalThis` flag, not a per-host
- * copy of the `import.meta.env` read below. A dev GUI that ships to players
- * because two places disagreed about what "dev" means is exactly the failure
- * this single owner exists to make impossible.
- *
- * Ownership, stated in one place (the build rule):
- *  - OWNER: this function. It resolves the answer; nothing else derives it.
- *  - SHARERS: `mountManifestRoots` (the ship gate — a dev root only mounts
- *    when this returns true). Any future host that mounts manifest roots
- *    itself calls this too, with its own `override`.
- *  - TEARDOWN: none. This is a pure predicate over build config and one
- *    caller-supplied argument — it owns no resource, allocates nothing, and
- *    has no lifecycle to end.
- *
- * The three inputs, highest precedence first:
- *  1. `override` — the explicit per-mount answer. A headless test, a capture
- *     harness, or a host that knows better passes `true`/`false` and gets
- *     exactly that. Passing `undefined` (or omitting it) means "decide for
- *     me" and falls through.
- *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
- *     dev layers are on.
- *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
- *     Shipping the dev GUI in a production bundle is a real, legitimate
- *     choice (an internal playtest build, a QA build), and it must be an
- *     opt-in someone had to type, never something a default drifts into.
- *
- * Anything else — a production build with no opt-in — is `false`.
- */
-export declare function devLayersEnabled(override?: boolean | undefined): boolean;
-//# sourceMappingURL=dev-layers.d.ts.map

package/dist/runtime/dev-layers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dev-layers.d.ts","sourceRoot":"","sources":["../../src/runtime/dev-layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAaxE"}

package/dist/runtime/dev-layers.js

@@ -1,46 +0,0 @@
-/**
- * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
- * root flag). Every reader that has to answer that question calls
- * {@link devLayersEnabled}; there is deliberately NO second source of truth —
- * not a module-level cached boolean, not a `globalThis` flag, not a per-host
- * copy of the `import.meta.env` read below. A dev GUI that ships to players
- * because two places disagreed about what "dev" means is exactly the failure
- * this single owner exists to make impossible.
- *
- * Ownership, stated in one place (the build rule):
- *  - OWNER: this function. It resolves the answer; nothing else derives it.
- *  - SHARERS: `mountManifestRoots` (the ship gate — a dev root only mounts
- *    when this returns true). Any future host that mounts manifest roots
- *    itself calls this too, with its own `override`.
- *  - TEARDOWN: none. This is a pure predicate over build config and one
- *    caller-supplied argument — it owns no resource, allocates nothing, and
- *    has no lifecycle to end.
- *
- * The three inputs, highest precedence first:
- *  1. `override` — the explicit per-mount answer. A headless test, a capture
- *     harness, or a host that knows better passes `true`/`false` and gets
- *     exactly that. Passing `undefined` (or omitting it) means "decide for
- *     me" and falls through.
- *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
- *     dev layers are on.
- *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
- *     Shipping the dev GUI in a production bundle is a real, legitimate
- *     choice (an internal playtest build, a QA build), and it must be an
- *     opt-in someone had to type, never something a default drifts into.
- *
- * Anything else — a production build with no opt-in — is `false`.
- */
-export function devLayersEnabled(override) {
-    if (override !== undefined)
-        return override;
-    // `import.meta` is cast whole, not just its `.env`: this module is reachable
-    // from programs whose tsconfig does not pull in `vite/client` (the session
-    // client's, for one, which reaches the three adapter transitively), and there
-    // `ImportMeta` has no declared `env` at all. The cast keeps the single owner
-    // of the dev answer importable from ANY program rather than forcing every
-    // downstream tsconfig to adopt Vite's ambient types.
-    const env = import.meta.env;
-    if (env?.DEV === true)
-        return true;
-    return env?.VITE_VGAI_DEV_LAYERS === 'true';
-}

package/src/runtime/dev-layers.ts

@@ -1,46 +0,0 @@
-/**
- * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
- * root flag). Every reader that has to answer that question calls
- * {@link devLayersEnabled}; there is deliberately NO second source of truth —
- * not a module-level cached boolean, not a `globalThis` flag, not a per-host
- * copy of the `import.meta.env` read below. A dev GUI that ships to players
- * because two places disagreed about what "dev" means is exactly the failure
- * this single owner exists to make impossible.
- *
- * Ownership, stated in one place (the build rule):
- *  - OWNER: this function. It resolves the answer; nothing else derives it.
- *  - SHARERS: `mountManifestRoots` (the ship gate — a dev root only mounts
- *    when this returns true). Any future host that mounts manifest roots
- *    itself calls this too, with its own `override`.
- *  - TEARDOWN: none. This is a pure predicate over build config and one
- *    caller-supplied argument — it owns no resource, allocates nothing, and
- *    has no lifecycle to end.
- *
- * The three inputs, highest precedence first:
- *  1. `override` — the explicit per-mount answer. A headless test, a capture
- *     harness, or a host that knows better passes `true`/`false` and gets
- *     exactly that. Passing `undefined` (or omitting it) means "decide for
- *     me" and falls through.
- *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
- *     dev layers are on.
- *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
- *     Shipping the dev GUI in a production bundle is a real, legitimate
- *     choice (an internal playtest build, a QA build), and it must be an
- *     opt-in someone had to type, never something a default drifts into.
- *
- * Anything else — a production build with no opt-in — is `false`.
- */
-export function devLayersEnabled(override?: boolean | undefined): boolean {
-  if (override !== undefined) return override;
-  // `import.meta` is cast whole, not just its `.env`: this module is reachable
-  // from programs whose tsconfig does not pull in `vite/client` (the session
-  // client's, for one, which reaches the three adapter transitively), and there
-  // `ImportMeta` has no declared `env` at all. The cast keeps the single owner
-  // of the dev answer importable from ANY program rather than forcing every
-  // downstream tsconfig to adopt Vite's ambient types.
-  const env = (import.meta as unknown as { env?: unknown }).env as
-    | { DEV?: boolean | undefined; VITE_VGAI_DEV_LAYERS?: string | undefined }
-    | undefined;
-  if (env?.DEV === true) return true;
-  return env?.VITE_VGAI_DEV_LAYERS === 'true';
-}