@vgai/engine 0.5.22 → 0.5.24

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.
@@ -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
@@ -66,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 {
@@ -75,6 +77,7 @@ import type {
   PhysicsJointSnapshot,
   PhysicsJointType,
 } from '../adapter/system-adapter';
+import { createSystemSlot } from '../adapter/system-slot';
 
 export interface RapierPhysicsBridgeProps {
   /**
@@ -151,12 +154,33 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
       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();
@@ -170,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()) };
       }
     };
 
@@ -182,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();
@@ -219,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;
       }
     };
 
@@ -343,16 +376,18 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
     };
 
     const adapter: PhysicsAdapter = {
-      ...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]);
 
@@ -363,21 +398,66 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
 // 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: PhysicsAdapter | null = null;
+/**
+ * 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;
 
-function requireLiveAdapter(): PhysicsAdapter {
-  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 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
@@ -387,28 +467,5 @@ function requireLiveAdapter(): PhysicsAdapter {
  * name rather than fabricating.
  */
 export function rapierPhysicsSystem(): PhysicsAdapter {
-  // 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 = <K extends keyof PhysicsAdapter>(member: K) => {
-    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) as NonNullable<PhysicsAdapter[K]>;
-  };
-  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;
 }

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"}