@vgai/engine 0.5.22 → 0.5.24

package/dist/runtime/playtest.js

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

package/dist/runtime/run-ticks-settled.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `runTicksWhenSettled` — the settled-aware tick driver behind BOTH session run-ticks doors
+ * (the bridge's `window.__vgai.runTicksSettled`, the editor relay's `run-ticks` case), one
+ * implementation with byte-identical semantics across doors, exactly as `runTicks` itself is
+ * shared (D17).
+ *
+ * Why it exists: `Game.runTicks` is deliberately SYNCHRONOUS, but a game may be intentionally
+ * BETWEEN worlds when a tick arrives — `reload_current_scene` unmounts the running scene and
+ * the fresh one arrives on an ASYNC React commit. A tick driven into that gap runs against
+ * nothing, and WHICH tick first runs the fresh world then depends on wall timing between
+ * driver calls — measured on the starter-kit fidelity drive: the same script produced 7 or 8
+ * post-respawn walked ticks depending on how long the driver idled between ticks. The fidelity
+ * contract (docs/MIGRATE-FIDELITY.md) treats a nondeterministic channel as a MECHANISM defect,
+ * and this is the mechanism: ticks must not race remounts.
+ *
+ * So this driver runs the budget ONE tick at a time and, before each tick, waits for every
+ * registered world-settled probe ({@link DebugRegistry.registerWorldSettledProbe} — declared by
+ * the game through its `debug.settled` entry export) to answer `true`. The wall-clock poll is
+ * sound because the OUTCOME no longer depends on timing: however long the commit takes, the
+ * next tick is always the fresh world's first. A game that registers no probe gets the old
+ * behavior exactly (every wait resolves immediately).
+ *
+ * The wait is BOUNDED and loud: a remount that never settles is a real defect, and
+ * `WORLD_UNSETTLED_TIMEOUT` names it rather than letting the driver hang.
+ */
+import { type DebugRegistry, type RunTicksOptions } from './debug-registry';
+export declare function runTicksWhenSettled(registry: Pick<DebugRegistry, 'worldSettled' | 'getRunTicksTarget'>, n: number, opts?: RunTicksOptions, 
+/** Test-only overrides — real callers leave this unset (the same seam
+ *  convention as fast-forward's `batchTicks`). */
+waits?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=run-ticks-settled.d.ts.map

package/dist/runtime/run-ticks-settled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-ticks-settled.d.ts","sourceRoot":"","sources":["../../src/runtime/run-ticks-settled.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAc,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAQxF,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,cAAc,GAAG,mBAAmB,CAAC,EACnE,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE,eAAe;AACtB;kDACkD;AAClD,KAAK,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/runtime/run-ticks-settled.js

@@ -0,0 +1,59 @@
+/**
+ * `runTicksWhenSettled` — the settled-aware tick driver behind BOTH session run-ticks doors
+ * (the bridge's `window.__vgai.runTicksSettled`, the editor relay's `run-ticks` case), one
+ * implementation with byte-identical semantics across doors, exactly as `runTicks` itself is
+ * shared (D17).
+ *
+ * Why it exists: `Game.runTicks` is deliberately SYNCHRONOUS, but a game may be intentionally
+ * BETWEEN worlds when a tick arrives — `reload_current_scene` unmounts the running scene and
+ * the fresh one arrives on an ASYNC React commit. A tick driven into that gap runs against
+ * nothing, and WHICH tick first runs the fresh world then depends on wall timing between
+ * driver calls — measured on the starter-kit fidelity drive: the same script produced 7 or 8
+ * post-respawn walked ticks depending on how long the driver idled between ticks. The fidelity
+ * contract (docs/MIGRATE-FIDELITY.md) treats a nondeterministic channel as a MECHANISM defect,
+ * and this is the mechanism: ticks must not race remounts.
+ *
+ * So this driver runs the budget ONE tick at a time and, before each tick, waits for every
+ * registered world-settled probe ({@link DebugRegistry.registerWorldSettledProbe} — declared by
+ * the game through its `debug.settled` entry export) to answer `true`. The wall-clock poll is
+ * sound because the OUTCOME no longer depends on timing: however long the commit takes, the
+ * next tick is always the fresh world's first. A game that registers no probe gets the old
+ * behavior exactly (every wait resolves immediately).
+ *
+ * The wait is BOUNDED and loud: a remount that never settles is a real defect, and
+ * `WORLD_UNSETTLED_TIMEOUT` names it rather than letting the driver hang.
+ */
+import { DebugError } from './debug-registry';
+/** A remount is a couple of React commits on an idle main thread; polling faster buys nothing
+ *  and slower delays every settled check by the poll period. */
+const SETTLED_POLL_MS = 4;
+/** A commit that hasn't landed after this long is not "in flight", it is stuck. */
+const SETTLED_TIMEOUT_MS = 10_000;
+export async function runTicksWhenSettled(registry, n, opts, 
+/** Test-only overrides — real callers leave this unset (the same seam
+ *  convention as fast-forward's `batchTicks`). */
+waits) {
+    const target = registry.getRunTicksTarget();
+    if (target === null) {
+        throw new DebugError('RUN_TICKS_UNAVAILABLE', 'runTicksWhenSettled: no run-ticks target is wired — no Game has mounted yet');
+    }
+    const timeoutMs = waits?.timeoutMs ?? SETTLED_TIMEOUT_MS;
+    const pollMs = waits?.pollMs ?? SETTLED_POLL_MS;
+    const render = opts?.render ?? 'last';
+    for (let i = 0; i < n; i++) {
+        if (!registry.worldSettled()) {
+            const deadline = Date.now() + timeoutMs;
+            while (!registry.worldSettled()) {
+                if (Date.now() > deadline) {
+                    throw new DebugError('WORLD_UNSETTLED_TIMEOUT', `runTicksWhenSettled: a world-settled probe still answers false after ${timeoutMs}ms — ` +
+                        'a scene remount (or a broken probe) is stuck, and driving ticks into it would race it');
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollMs));
+            }
+        }
+        const isFinalTick = i === n - 1;
+        // Same per-tick render policy `Game.runTicks` applies across its own loop.
+        const tickRender = render === 'all' ? 'all' : render === 'none' ? 'none' : isFinalTick ? 'last' : 'none';
+        target.runTicks(1, { render: tickRender });
+    }
+}

package/dist/runtime/state-bridge.d.ts

@@ -46,9 +46,8 @@ export interface GameStateBridge {
 export interface GameStateBridgeInternal extends GameStateBridge {
     /** Bump `frameVersion` by one and notify every current subscriber, in
      *  subscription order. Subscriber errors are isolated (per-subscriber
-     *  try/catch, loud `console.error`, never swallowed silently) — mirrors
-     *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
-     *  `update()` calls: one offending subscriber must not stop its siblings
+     *  try/catch, loud `console.error`, never swallowed silently): one
+     *  offending subscriber must not stop its siblings
      *  from being notified, and must not break the frame loop. */
     bump(): void;
 }

package/dist/runtime/state-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B;;;;kEAI8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;mEAKmE;AACnE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;;kEAK8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8B3D"}
+{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B;;;;kEAI8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;mEAKmE;AACnE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;kEAI8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA+B3D"}

package/dist/runtime/state-bridge.js

@@ -54,6 +54,7 @@ export function createStateBridge() {
                     onFrame();
                 }
                 catch (err) {
+                    // biome-ignore lint/suspicious/noConsole: a throwing subscriber must not take the notify loop down, and the console (captured by the editor session ledger) is the engine runtime's one report channel.
                     console.error('[state-bridge] subscriber threw:', err);
                 }
             }

package/dist/setup/setup-audio.d.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { type AudioBusMixer } from '../audio/bus-mixer';
 export interface AudioContext {
     listener: THREE.AudioListener;
     masterGain: GainNode;
@@ -7,6 +8,17 @@ export interface AudioContext {
         sfx: GainNode;
         voice: GainNode;
     };
+    /**
+     * The named-bus mixer the three below are buses OF (`../audio/bus-mixer.ts`).
+     *
+     * `buses` is a fixed struct because those three names are the ones the engine
+     * itself routes; a game with an `ambience`, a `ui` or a per-character bus asks
+     * the mixer for it by name — `audio.mixer.bus('ambience', 'master')` mints it
+     * under the master gain, `audio.mixer.setDb('ambience', -6)` sets it in
+     * decibels — and `audio.mixer.disconnect()` is the ONE teardown for all of
+     * them, the three struct members included.
+     */
+    mixer: AudioBusMixer;
     /** Call this on first user interaction (click/key) to resume audio context */
     resume: () => void;
 }

package/dist/setup/setup-audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-audio.d.ts","sourceRoot":"","sources":["../../src/setup/setup-audio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE;QACL,KAAK,EAAE,QAAQ,CAAC;QAChB,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,EAAE,QAAQ,CAAC;KACjB,CAAC;IACF,8EAA8E;IAC9E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAuC7D"}
+{"version":3,"file":"setup-audio.d.ts","sourceRoot":"","sources":["../../src/setup/setup-audio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,oBAAoB,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE;QACL,KAAK,EAAE,QAAQ,CAAC;QAChB,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,EAAE,QAAQ,CAAC;KACjB,CAAC;IACF;;;;;;;;;OASG;IACH,KAAK,EAAE,aAAa,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAKD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAkC7D"}

package/dist/setup/setup-audio.js

@@ -1,4 +1,7 @@
 import * as THREE from 'three';
+import { createAudioBusMixer } from '../audio/bus-mixer';
+/** The bus every other bus routes into, and the node `masterGain` is. */
+const MASTER_BUS = 'master';
 /**
  * Creates the audio listener and bus hierarchy.
  *
@@ -9,21 +12,16 @@ export function setupAudio(camera) {
     const listener = new THREE.AudioListener();
     camera.add(listener);
     const ctx = listener.context;
-    const masterGain = ctx.createGain();
-    masterGain.connect(ctx.destination);
+    const mixer = createAudioBusMixer({ context: ctx, destination: ctx.destination });
+    const masterGain = mixer.bus(MASTER_BUS);
     // Route the Three.js listener through masterGain so that THREE.Audio /
     // THREE.PositionalAudio objects are also silenced by the mute button.
     listener.gain.disconnect();
     listener.gain.connect(masterGain);
-    const musicGain = ctx.createGain();
+    const musicGain = mixer.bus('music', MASTER_BUS);
     musicGain.gain.value = 0.7;
-    musicGain.connect(masterGain);
-    const sfxGain = ctx.createGain();
-    sfxGain.gain.value = 1.0;
-    sfxGain.connect(masterGain);
-    const voiceGain = ctx.createGain();
-    voiceGain.gain.value = 1.0;
-    voiceGain.connect(masterGain);
+    const sfxGain = mixer.bus('sfx', MASTER_BUS);
+    const voiceGain = mixer.bus('voice', MASTER_BUS);
     return {
         listener,
         masterGain,
@@ -32,6 +30,7 @@ export function setupAudio(camera) {
             sfx: sfxGain,
             voice: voiceGain,
         },
+        mixer,
         resume() {
             if (ctx.state === 'suspended') {
                 ctx.resume();

package/dist/setup/setup-renderer.d.ts

@@ -1,13 +1,7 @@
-import { EffectComposer } from 'postprocessing';
+import { type EffectComposer } from 'postprocessing';
 import * as THREE from 'three';
 import type { RenderEnvironment } from '../asset-formats/render-env';
 import { type RenderScope } from '../render/render-settings';
-export interface RendererContext {
-    renderer: THREE.WebGLRenderer;
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    composer: EffectComposer;
-}
 /**
  * Apply the live renderer-level render settings (shadows, resolution scale) from
  * the resolved cascade. `antialias`/`backend` are reload-only (renderer re-init)
@@ -22,7 +16,7 @@ export declare function applyRendererSettings(renderer: THREE.WebGLRenderer, ren
 /**
  * Create ONLY the WebGL renderer. The HOST owns the renderer (see
  * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
- * renders into. Split out of `setupRenderer` for the adapter inversion.
+ * renders into.
  *
  * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
  * reload-only `antialias` option at construction and the live shadow/resolution
@@ -39,23 +33,6 @@ export declare function createHostRenderer(canvas: HTMLCanvasElement, width?: nu
     alpha?: boolean;
     preserveDrawingBuffer?: boolean;
 }): THREE.WebGLRenderer;
-/**
- * Create the scene, camera, and postprocessing composer that a first-party game
- * renders into, given a host-provided renderer. The GPU-only `composer` is
- * created here; a headless host (no GPU) skips this entirely.
- */
-export declare function createSceneView(renderer: THREE.WebGLRenderer, width?: number, height?: number): {
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    composer: EffectComposer;
-};
-/**
- * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
- *
- * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
- * combination of {@link createHostRenderer} + {@link createSceneView}.)
- */
-export declare function setupRenderer(canvas: HTMLCanvasElement, width?: number, height?: number): RendererContext;
 /**
  * Rebuild composer passes from scene environment settings.
  * Scenes without toneMapping default to ACES (the runtime default).

package/dist/setup/setup-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-renderer.d.ts","sourceRoot":"","sources":["../../src/setup/setup-renderer.ts"],"names":[],"mappings":"AAGA,OAAO,EAQL,cAAc,EAoBf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,2BAA2B,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAChC,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,SAAS,CAAC,EAAE,WAAW,EACvB,cAAc,SAAuC,GACpD,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,EAC3B,SAAS,CAAC,EAAE,WAAW,EACvB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D,KAAK,CAAC,aAAa,CAwBrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,SAAoB,EACzB,MAAM,SAAqB,GAC1B;IAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAyBnF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,GAC1B,eAAe,CAIjB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACvC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACjC,IAAI,CAsVN;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,IAAI,CAeN"}
+{"version":3,"file":"setup-renderer.d.ts","sourceRoot":"","sources":["../../src/setup/setup-renderer.ts"],"names":[],"mappings":"AAGA,OAAO,EAQL,KAAK,cAAc,EAoBpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,2BAA2B,CAAC;AAEpF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,SAAS,CAAC,EAAE,WAAW,EACvB,cAAc,SAAuC,GACpD,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,EAC3B,SAAS,CAAC,EAAE,WAAW,EACvB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D,KAAK,CAAC,aAAa,CAwBrB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACvC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACjC,IAAI,CAsVN;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,IAAI,CAeN"}

package/dist/setup/setup-renderer.js

@@ -1,6 +1,6 @@
 /// <reference path="../types-n8ao.d.ts" />
 import { N8AOPostPass } from 'n8ao';
-import { BloomEffect, BrightnessContrastEffect, ChromaticAberrationEffect, ColorDepthEffect, DepthOfFieldEffect, DotScreenEffect, EffectComposer, EffectPass, GlitchEffect, GodRaysEffect, GridEffect, HueSaturationEffect, LensDistortionEffect, NoiseEffect, NormalPass, OutlineEffect, PixelationEffect, RenderPass, ScanlineEffect, SepiaEffect, ShockWaveEffect, SMAAEffect, SMAAPreset, SSAOEffect, TiltShiftEffect, VignetteEffect, } from 'postprocessing';
+import { BloomEffect, BrightnessContrastEffect, ChromaticAberrationEffect, ColorDepthEffect, DepthOfFieldEffect, DotScreenEffect, EffectPass, GlitchEffect, GodRaysEffect, GridEffect, HueSaturationEffect, LensDistortionEffect, NoiseEffect, NormalPass, OutlineEffect, PixelationEffect, RenderPass, ScanlineEffect, SepiaEffect, ShockWaveEffect, SMAAEffect, SMAAPreset, SSAOEffect, TiltShiftEffect, VignetteEffect, } from 'postprocessing';
 import * as THREE from 'three';
 import { MotionBlurEffect, SSGIEffect, SSREffect, VelocityDepthNormalPass, } from '../../vendor/realism-effects/dist/index.js';
 import { DEFAULTS } from '../defaults';
@@ -25,7 +25,7 @@ export function applyRendererSettings(renderer, rendering, basePixelRatio = Math
 /**
  * Create ONLY the WebGL renderer. The HOST owns the renderer (see
  * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
- * renders into. Split out of `setupRenderer` for the adapter inversion.
+ * renders into.
  *
  * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
  * reload-only `antialias` option at construction and the live shadow/resolution
@@ -63,35 +63,6 @@ export function createHostRenderer(canvas, width = window.innerWidth, height = w
     detectKtx2Support(renderer);
     return renderer;
 }
-/**
- * Create the scene, camera, and postprocessing composer that a first-party game
- * renders into, given a host-provided renderer. The GPU-only `composer` is
- * created here; a headless host (no GPU) skips this entirely.
- */
-export function createSceneView(renderer, width = window.innerWidth, height = window.innerHeight) {
-    const safeWidth = Math.max(1, width);
-    const safeHeight = Math.max(1, height);
-    const scene = new THREE.Scene();
-    scene.background = new THREE.Color(0x1a1a2e);
-    const camera = new THREE.PerspectiveCamera(DEFAULTS.camera.fov, safeWidth / safeHeight, DEFAULTS.camera.near, DEFAULTS.camera.far);
-    camera.position.set(0, 5, 10);
-    camera.lookAt(0, 0, 0);
-    const composer = new EffectComposer(renderer);
-    composer.addPass(new RenderPass(scene, camera));
-    composer.addPass(new EffectPass(camera, new BloomEffect({ luminanceThreshold: DEFAULTS.postProcessing.bloom.luminanceThreshold })));
-    return { scene, camera, composer };
-}
-/**
- * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
- *
- * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
- * combination of {@link createHostRenderer} + {@link createSceneView}.)
- */
-export function setupRenderer(canvas, width = window.innerWidth, height = window.innerHeight) {
-    const renderer = createHostRenderer(canvas, width, height);
-    const { scene, camera, composer } = createSceneView(renderer, width, height);
-    return { renderer, scene, camera, composer };
-}
 const toneMappingModes = {
     none: THREE.NoToneMapping,
     linear: THREE.LinearToneMapping,

package/dist/world3d-react/r3f-root-factory.d.ts

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

package/dist/world3d-react/r3f-root-factory.js

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

package/dist/world3d-react/rapier-physics-bridge.d.ts

@@ -4,11 +4,9 @@
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
  * coordination (`freeze → apply → unfreeze`) and the 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
+ * "Colliders drawn" instrument (`@engine/dev/instruments`) read. An R3F world
+ * builds no first-party Rapier runtime at all — 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.
@@ -51,9 +49,12 @@
  * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key
  * and the slot it set (identity-guarded), so a play stop/start, a hot
  * restart, or a world that unmounts `<Physics>` leaves no stale adapter
- * behind. Because the slot is game-global, mount exactly ONE bridge per
- * GAME: with two, the later mount wins the slot and the later unmount clears
- * it while the earlier bridge is still live.
+ * behind. Because the slot is PAGE-global (see its doc below — an engine
+ * module is shared across the editor's Play instances), mount exactly ONE
+ * bridge per PAGE: with two — a scene that mounts two, or two Play instances
+ * of one rapier world — the later mount wins the slot and the later unmount
+ * clears it while the earlier bridge is still live. That state is reported
+ * loudly the moment it starts (`warnOnContendedMount`).
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked

package/dist/world3d-react/rapier-physics-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AASH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAkCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CA0OrF;AAqBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAyBpD"}
+{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAUH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAkCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CA0QrF;AAkED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

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

@@ -4,11 +4,9 @@
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
  * coordination (`freeze → apply → unfreeze`) and the 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
+ * "Colliders drawn" instrument (`@engine/dev/instruments`) read. An R3F world
+ * builds no first-party Rapier runtime at all — 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.
@@ -51,9 +49,12 @@
  * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key
  * and the slot it set (identity-guarded), so a play stop/start, a hot
  * restart, or a world that unmounts `<Physics>` leaves no stale adapter
- * behind. Because the slot is game-global, mount exactly ONE bridge per
- * GAME: with two, the later mount wins the slot and the later unmount clears
- * it while the earlier bridge is still live.
+ * behind. Because the slot is PAGE-global (see its doc below — an engine
+ * module is shared across the editor's Play instances), mount exactly ONE
+ * bridge per PAGE: with two — a scene that mounts two, or two Play instances
+ * of one rapier world — the later mount wins the slot and the later unmount
+ * clears it while the earlier bridge is still live. That state is reported
+ * loudly the moment it starts (`warnOnContendedMount`).
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
@@ -64,6 +65,7 @@ import { useRapier } from '@react-three/rapier';
 import { useEffect } from 'react';
 import * as THREE from 'three';
 import { createRapierBodyEditing, } from '../adapter/rapier-physics-adapter';
+import { createSystemSlot } from '../adapter/system-slot';
 function lateEntityObject(states, nodeId) {
     let found;
     for (const state of states) {
@@ -119,6 +121,25 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                 return undefined;
             return owningBody(object, rigidBodyStates.values());
         };
+        /**
+         * The same question, with the two negative answers KEPT APART for the
+         * editing protocol — see {@link RapierBodyLookup}. This world's search
+         * space is the `<RigidBody>` subtrees, so "no object here" really is "not a
+         * node of mine", not "a node of mine without physics".
+         */
+        const bodyLookup = (nodeId) => {
+            const object = lateEntityObject(rigidBodyStates.values(), nodeId);
+            if (!object)
+                return { kind: 'unresolved' };
+            const body = owningBody(object, rigidBodyStates.values());
+            return body ? { kind: 'body', body } : { kind: 'no-body' };
+        };
+        /** Rapier's own name for a shape type, via the enum's reverse mapping —
+         *  so an unprojected collider reports WHICH shape it is (`TriMesh`,
+         *  `HeightField`, …) instead of a bare number, and a shape added by a
+         *  future rapier still names itself. */
+        const rapierShapeName = (shapeType) => rapier.ShapeType[shapeType] ??
+            `shapeType ${shapeType}`;
         const colliderShape = (collider) => {
             switch (collider.shapeType()) {
                 case rapier.ShapeType.Cuboid: {
@@ -133,8 +154,13 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                         halfHeight: collider.halfHeight(),
                         radius: collider.radius(),
                     };
+                // Rapier has many more shapes than this seam projects (TriMesh,
+                // HeightField, ConvexPolyhedron, Cylinder, Cone, …). The collider is
+                // REAL; only our plain-data projection of it is missing, so it is
+                // reported as itself rather than dropped — a body whose only collider
+                // is a trimesh used to inspect as a body with no colliders at all.
                 default:
-                    return null;
+                    return { type: 'unsupported', kind: rapierShapeName(collider.shapeType()) };
             }
         };
         const colliders = (nodeId) => {
@@ -146,8 +172,6 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                 if (state.collider.parent()?.handle !== body.handle)
                     continue;
                 const shape = colliderShape(state.collider);
-                if (!shape)
-                    continue;
                 state.object.updateWorldMatrix(true, false);
                 const position = state.collider.translation();
                 const rotation = state.collider.rotation();
@@ -182,6 +206,11 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                     collider.setHalfHeight(shape.halfHeight);
                     collider.setRadius(shape.radius);
                     break;
+                // A shape this seam does not project has no dimensions to write back.
+                // `colliders()` reports it so the body's physics is not invisible; that
+                // is a READ, and it does not make the shape editable.
+                case 'unsupported':
+                    break;
             }
         };
         const jointType = (type) => {
@@ -279,17 +308,18 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                 joint.setAnchor2(value);
         };
         const adapter = {
-            ...createRapierBodyEditing(bodyFor),
+            ...createRapierBodyEditing(bodyLookup),
             setDebugDrawEnabled: (enabled) => onDebugChange(enabled),
             colliders,
             previewCollider,
             joints,
             previewJointAnchor,
         };
-        liveAdapter = adapter;
+        warnOnContendedMount();
+        const detach = physicsSlot.attach(adapter);
         return () => {
-            if (liveAdapter === adapter)
-                liveAdapter = null;
+            liveBridgeCount -= 1;
+            detach();
         };
     }, [colliderStates, onDebugChange, rapier, rigidBodyStates, world]);
     return null;
@@ -297,17 +327,61 @@ export function RapierPhysicsBridge({ onDebugChange }) {
 // ---------------------------------------------------------------------------
 // The entry-declaration half
 // ---------------------------------------------------------------------------
-/** The mounted bridge's adapter, while one is live. Module-scoped on purpose:
- *  the entry's `systems` declaration is static, the rapier world is not, and
- *  this slot is the seam between the two. */
-let liveAdapter = null;
-function requireLiveAdapter() {
-    if (!liveAdapter) {
-        throw new Error('rapierPhysicsSystem: no <RapierPhysicsBridge> is mounted inside a live <Physics> right ' +
-            'now — the world is not playing, or the scene never mounted the bridge.');
-    }
-    return liveAdapter;
+/**
+ * The bridge's slot. Module-scoped on purpose: the entry's `systems`
+ * declaration is static, the rapier world is not, and this slot is the seam
+ * between the two. Module scope here means one per PAGE, not one per game:
+ * this file is an ENGINE module, reached by bare specifier, so the editor's
+ * multi-instance Play (which stamps mount ids onto PROJECT-owned specifiers
+ * only — `server/project-module-instance.ts`) shares this one slot across
+ * every mounted instance. Two live instances of a rapier world therefore
+ * contend for it: the LAST bridge to mount wins every instance's declared
+ * `systems.physics`, and the loser's detach is dropped by the identity guard.
+ * {@link warnOnContendedMount} makes that state loud at the moment it
+ * happens; making the slot instance-scoped needs a per-mount rendezvous the
+ * context-free declaration (`rapierPhysicsSystem()` at project-module scope)
+ * does not yet have.
+ *
+ * Every member is an ACTION: each one either edits the sim or reads a live
+ * Rapier handle, and all of them arrive at gesture rate (a gizmo drag, an
+ * instrument command), never from a per-frame loop — so refusing by name is
+ * always the right answer, and a fabricated empty never is.
+ * `debugDraw`/`contactPoints` are OMITTED, not stubbed, for the anti-shim
+ * reason stated at the top of this file; a member the config does not list
+ * does not exist on the slot.
+ */
+let liveBridgeCount = 0;
+/** The page-scope contention above, made LOUD instead of silent (never a
+ *  silent degrade): a second concurrent bridge mount — a scene that mounted
+ *  two, or a second Play instance of a rapier world — is reported the moment
+ *  it happens, naming what breaks and until when. */
+function warnOnContendedMount() {
+    liveBridgeCount += 1;
+    if (liveBridgeCount <= 1)
+        return;
+    // biome-ignore lint/suspicious/noConsole: the standing-warning channel for a capability the adapter cannot reach — the editor console surfaces it during play
+    console.warn(`[rapierPhysicsSystem] ${liveBridgeCount} <RapierPhysicsBridge> mounts are live on this ` +
+        'page, but the declared physics slot is one per page (engine modules are shared across ' +
+        "Play instances). Every instance's `systems.physics` now forwards to the LAST bridge " +
+        'mounted, so physics gizmo edits and instruments address that world — not necessarily ' +
+        'the one selected — until the extra mounts unmount.');
 }
+const physicsSlot = createSystemSlot({
+    name: 'rapierPhysicsSystem',
+    unattachedMessage: 'no <RapierPhysicsBridge> is mounted inside a live <Physics> right now — the world is not ' +
+        'playing, or the scene never mounted the bridge.',
+    members: {
+        ownerOf: { kind: 'action' },
+        freeze: { kind: 'action' },
+        commit: { kind: 'action' },
+        unfreeze: { kind: 'action' },
+        setDebugDrawEnabled: { kind: 'action' },
+        colliders: { kind: 'action' },
+        previewCollider: { kind: 'action' },
+        joints: { kind: 'action' },
+        previewJointAnchor: { kind: 'action' },
+    },
+});
 /**
  * The `systems.physics` slot for a default-exported world — declare it from
  * the entry (`export const systems = { physics: rapierPhysicsSystem() }`) and
@@ -317,27 +391,5 @@ function requireLiveAdapter() {
  * name rather than fabricating.
  */
 export function rapierPhysicsSystem() {
-    // Every forward REQUIRES the live adapter and its member — a silent no-op
-    // or fabricated empty answer is the shape the anti-shim rule forbids. The
-    // bridge's adapter always carries all five optional members, so the member
-    // checks only ever fire against a foreign replacement.
-    const requireMember = (member) => {
-        const adapter = requireLiveAdapter();
-        const value = adapter[member];
-        if (typeof value !== 'function') {
-            throw new Error(`rapierPhysicsSystem: the live physics adapter has no ${String(member)}().`);
-        }
-        return value.bind(adapter);
-    };
-    return {
-        ownerOf: (nodeId) => requireLiveAdapter().ownerOf(nodeId),
-        freeze: (nodeId) => requireLiveAdapter().freeze(nodeId),
-        commit: (nodeId, t) => requireLiveAdapter().commit(nodeId, t),
-        unfreeze: (nodeId) => requireLiveAdapter().unfreeze(nodeId),
-        setDebugDrawEnabled: (enabled) => requireMember('setDebugDrawEnabled')(enabled),
-        colliders: (nodeId) => requireMember('colliders')(nodeId),
-        previewCollider: (colliderId, shape) => requireMember('previewCollider')(colliderId, shape),
-        joints: (nodeId) => requireMember('joints')(nodeId),
-        previewJointAnchor: (jointId, endpoint, anchor) => requireMember('previewJointAnchor')(jointId, endpoint, anchor),
-    };
+    return physicsSlot.slot;
 }