@vgai/engine 0.5.21 → 0.5.23

package/src/world3d-react/rapier-physics-bridge.tsx

@@ -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.
@@ -40,18 +38,23 @@
  * 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
- * 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.
+ * OWNER: this component owns one physics ADAPTER, published onto the ONE
+ * module-scoped slot `rapierPhysicsSystem()` forwards to (GAME-GLOBAL — the
+ * entry's static `systems.physics` declaration cannot be per-root). 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 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
+ * 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 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 +67,7 @@ import { useEffect } from 'react';
 import * as THREE from 'three';
 import {
   createRapierBodyEditing,
+  type RapierBodyLookup,
   type RapierEditableBody,
 } from '../adapter/rapier-physics-adapter';
 import type {
@@ -73,7 +77,7 @@ import type {
   PhysicsJointSnapshot,
   PhysicsJointType,
 } from '../adapter/system-adapter';
-import { useGameContext } from './engine-bridge';
+import { createSystemSlot } from '../adapter/system-slot';
 
 export interface RapierPhysicsBridgeProps {
   /**
@@ -123,57 +127,60 @@ function owningBody(
  * `useRapier()`). Renders nothing.
  */
 export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps): null {
-  const ctx = useGameContext();
+  // This bridge publishes the module slot below, which the entry's
+  // `systems.physics` declaration (`rapierPhysicsSystem()`) forwards to —
+  // that declaration is the ONE path the host reads this world's physics
+  // through.
   const { colliderStates, rapier, rigidBodyStates, world } = 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.
+     * node id → the Rapier body driving it, entirely through the library's
+     * OWN body↔object map (`rigidBodyStates`, carried on the `RapierContext`
+     * `useRapier()` returns): resolve `userData.entityId` — this stack's
+     * identity convention, stamped by the editor's R3F authoring adapter —
+     * inside the body-owned subtrees, then walk ANCESTORS to the owning body
+     * (`<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 —
+     * The map is 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.
+     * never per frame, and only objects under a `<RigidBody>` can have a body
+     * at all, so the body subtrees are the complete search space.
      */
     const bodyFor = (nodeId: string): RapierEditableBody | undefined => {
-      const indexed = ctx.sceneIndex?.byEntityId(nodeId);
-      const object = indexed ?? lateEntityObject(rigidBodyStates.values(), nodeId);
-      if (!indexed && object) {
-        // The editor assigns its stable authoring entity ids AFTER Fiber's
-        // first commit, while the root's SceneIndex is constructed during
-        // that commit. Resolve the one late id inside the library-owned body
-        // subtrees and immediately reindex it; subsequent gestures take the
-        // normal indexed path. This is the SceneIndex's documented escape
-        // hatch for a userData id written after construction, not a parallel
-        // scene mirror.
-        ctx.sceneIndex?.reindex(object);
-      }
+      const object = lateEntityObject(rigidBodyStates.values(), nodeId);
       if (!object) 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: string): RapierBodyLookup => {
+      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: number): string =>
+      (rapier.ShapeType as unknown as Record<number, string | undefined>)[shapeType] ??
+      `shapeType ${shapeType}`;
+
     const colliderShape = (collider: {
       shapeType(): number;
       halfExtents(): { x: number; y: number; z: number };
       radius(): number;
       halfHeight(): number;
-    }): PhysicsColliderShape | null => {
+    }): PhysicsColliderShape => {
       switch (collider.shapeType()) {
         case rapier.ShapeType.Cuboid: {
           const halfExtents = collider.halfExtents();
@@ -187,8 +194,13 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
             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()) };
       }
     };
 
@@ -199,7 +211,6 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
       for (const state of colliderStates.values()) {
         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();
@@ -236,6 +247,11 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
           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;
       }
     };
 
@@ -360,16 +376,96 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
     };
 
     const adapter: PhysicsAdapter = {
-      ...createRapierBodyEditing(bodyFor),
+      ...createRapierBodyEditing(bodyLookup),
       setDebugDrawEnabled: (enabled) => onDebugChange(enabled),
       colliders,
       previewCollider,
       joints,
       previewJointAnchor,
     };
-    registerSystemAdapter('physics', adapter);
-    return () => registerSystemAdapter('physics', undefined);
-  }, [colliderStates, ctx, onDebugChange, rapier, registerSystemAdapter, rigidBodyStates, world]);
+    warnOnContendedMount();
+    const detach = physicsSlot.attach(adapter);
+    return () => {
+      liveBridgeCount -= 1;
+      detach();
+    };
+  }, [colliderStates, onDebugChange, rapier, rigidBodyStates, world]);
 
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// The entry-declaration half
+// ---------------------------------------------------------------------------
+
+/**
+ * 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(): void {
+  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<PhysicsAdapter>({
+  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
+ * keep `<RapierPhysicsBridge />` mounted inside `<Physics>`. Every call
+ * forwards to the LIVE bridge adapter, so the static declaration answers with
+ * the running world's physics; while none is mounted, every call refuses by
+ * name rather than fabricating.
+ */
+export function rapierPhysicsSystem(): PhysicsAdapter {
+  return physicsSlot.slot;
+}

package/dist/adapter/setup-three-root-adapter.d.ts

@@ -1,86 +0,0 @@
-/**
- * SetupThreeRootAdapter — the first-party implementer of {@link RootAdapter}
- * that mounts ONE three root from an imperative `setup(ctx)` function.
- *
- * This is where Rapier lives now: the host no longer knows about it.
- * `mount(host)` builds the full first-party runtime (the body
- * that used to live inline in `create-runtime.ts`) from a neutral
- * {@link ThreeHostContext}, runs the game's `setup`, and returns a
- * {@link MountedThreeRoot}. First-party content is now just one implementer of
- * the same interface an unmodified external game implements (Phase B).
- *
- * It was `VgaiSceneGameAdapter` until WO-9 tasks #6/#9. Both halves of that
- * name had stopped being true: it loads no scene (the `.vscn.json` branches
- * went with the format in WO-8 — `setup` is the only mount path left), and what
- * it mounts is one three ROOT, not a game (a game is the manifest's whole set
- * of roots). The R3F/TSX world root is a SEPARATE adapter; this one is
- * specifically the `fromSetup` path.
- *
- * `GameSetupFn` / `GameContext` are imported ONLY here (and in the example
- * `fromSetup` wrappers) — never by the host. That confinement is the inversion.
- */
-import type { EffectComposer } from 'postprocessing';
-import { type ViewportShadingMode } from '../render/viewport-shading';
-import { type RootFrameHooks } from '../runtime/game';
-import type { EditorPreview, GameContext, GameSetupFn } from '../runtime/types';
-import type { ThreeHostContext } from './host-context';
-import type { MountedThreeRoot, RootAdapter } from './root-adapter';
-/** How a {@link SetupThreeRootAdapter} builds its game (the former RuntimeConfig). */
-export interface SetupThreeRootConfig {
-    /** Game setup function — registers systems and loads scenes. */
-    setup?: GameSetupFn | undefined;
-    /** Editor context — passed to setup() when launched from the editor. */
-    editorPreview?: EditorPreview | undefined;
-    /** Input map JSON path. Defaults to 'inputmaps/default.inputmap.json'. */
-    inputMapPath?: string | undefined;
-    /** URL prefix for relative asset paths. Defaults to '/'. */
-    assetPrefix?: string | undefined;
-    /** Stable adapter id (for registry/conformance). Defaults to 'setup-three'. */
-    id?: string | undefined;
-}
-/**
- * The first-party `MountedThreeRoot`, with concrete extras the editor host uses for
- * first-party features (HMR, physics sync) that are NOT part of the neutral
- * interface. The generic host only touches the `MountedThreeRoot` surface.
- */
-export interface MountedSetupThreeRoot extends MountedThreeRoot {
-    /**
-     * First-party brand (checklist item 1 / T7.3 lookahead): a plain `'ctx' in
-     * mounted` structural check misfires against any foreign mount that happens
-     * to carry an unrelated `ctx` key. This literal-`true`
-     * property is what `isFirstPartyMounted` (`runtime/game.ts`) actually
-     * checks; `game.ts` reads it via a structural `{ firstParty?: unknown }`
-     * probe so it never needs a value import of this module (the existing
-     * import is type-only and must stay that way).
-     */
-    readonly firstParty: true;
-    readonly ctx: GameContext;
-    readonly composer: EffectComposer | null;
-    /** Render-only developer view; native game materials are restored before the frame returns. */
-    setViewportShadingMode(mode: ViewportShadingMode): void;
-    /** Warm-restart: dispose the current game, re-run a new setup on the same ctx. */
-    hotReload(newSetup: GameSetupFn, editorPreview?: EditorPreview): Promise<void>;
-    /**
-     * Phase-partitioned frame entry point (T7.1 slice 2) — wired onto this
-     * world's `RootInstance` by `registerThreeRoot` (`create-runtime.ts`).
-     * `Game.runFrame` is the CANONICAL driver going forward: it calls
-     * `frame.runPhase` once per (phase, substep) for every world, then
-     * `frame.endFrame` once per substep after all roots finish all phases.
-     * `update` is the direct entry point to the same `SystemRunner` for hosts
-     * that do not partition phases themselves.
-     */
-    readonly frame: RootFrameHooks;
-}
-/**
- * Wrap a first-party `setup` function as a {@link RootAdapter}. This is how every
- * first-party example becomes an implementer of the same interface an external
- * game implements — with no change to the setup's body.
- */
-export declare function fromSetup(id: string, setup: GameSetupFn): RootAdapter;
-export declare class SetupThreeRootAdapter implements RootAdapter {
-    private readonly config;
-    readonly id: string;
-    constructor(config?: SetupThreeRootConfig);
-    mount(host: ThreeHostContext): Promise<MountedSetupThreeRoot>;
-}
-//# sourceMappingURL=setup-three-root-adapter.d.ts.map

package/dist/adapter/setup-three-root-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup-three-root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/setup-three-root-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAoCrD,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,4BAA4B,CAAC;AAO/F,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGpE,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,+FAA+F;IAC/F,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAErE;AAED,qBAAa,qBAAsB,YAAW,WAAW;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBACS,MAAM,GAAE,oBAAyB;IAKxD,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAq1BpE"}