@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/adapter/rapier-physics-adapter.ts

@@ -9,16 +9,61 @@
 import type RAPIER from '@dimforge/rapier3d-compat';
 import type * as THREE from 'three';
 import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { PhysicsContext } from '../setup/setup-physics';
 import type { PhysicsAdapter } from './system-adapter';
 import type { Transform, TransformOwner } from './transform';
 
 export function createRapierPhysicsAdapter(
   registry: PhysicsRegistry,
-  debugMesh?: THREE.Object3D | null,
+  physics?: PhysicsContext | null,
 ): PhysicsAdapter {
   /** Saved body types while frozen, so unfreeze can restore them. */
   const frozen = new Map<RAPIER.RigidBody, number>();
 
+  /**
+   * Reused backing store for `contactPoints` (grown ×2 on demand, never
+   * shrunk) — the seam contract says the returned view is only valid until
+   * the next call, exactly so this never allocates per frame once warm.
+   */
+  let contactBuf = new Float32Array(64 * 3);
+  let contactCount = 0;
+
+  const pushContact = (x: number, y: number, z: number): void => {
+    if ((contactCount + 1) * 3 > contactBuf.length) {
+      const grown = new Float32Array(contactBuf.length * 2);
+      grown.set(contactBuf);
+      contactBuf = grown;
+    }
+    contactBuf[contactCount * 3] = x;
+    contactBuf[contactCount * 3 + 1] = y;
+    contactBuf[contactCount * 3 + 2] = z;
+    contactCount++;
+  };
+
+  const appendManifoldContacts = (manifold: RAPIER.TempContactManifold): void => {
+    const count = manifold.numSolverContacts();
+    for (let i = 0; i < count; i++) {
+      // Solver contacts are WORLD-space (unlike localContactPoint1/2).
+      const p = manifold.solverContactPoint(i);
+      if (p) pushContact(p.x, p.y, p.z);
+    }
+  };
+
+  const collectContactPoints = (): Float32Array => {
+    if (!physics) return contactBuf.subarray(0, 0);
+    const world = physics.rapierWorld;
+    contactCount = 0;
+    for (const [, refs] of registry.entries()) {
+      world.contactPairsWith(refs.collider, (other) => {
+        // Each touching pair is enumerated from BOTH sides — process it only
+        // from the lower-handle side (also skips self).
+        if (other.handle <= refs.collider.handle) return;
+        world.contactPair(refs.collider, other, appendManifoldContacts);
+      });
+    }
+    return contactBuf.subarray(0, contactCount * 3);
+  };
+
   return {
     ownerOf(o: THREE.Object3D): TransformOwner {
       const body = registry.get(o)?.body;
@@ -51,6 +96,14 @@ export function createRapierPhysicsAdapter(
         frozen.delete(body);
       }
     },
-    debugDraw: () => debugMesh ?? null,
+    debugDraw: () => physics?.debugMesh ?? null,
+    setDebugDrawEnabled(enabled: boolean): void {
+      if (!physics) return;
+      // Same two fields the in-game KeyP toggle flips — the adapter's render
+      // system reads `debugEnabled` and feeds `debugRender()` into the mesh.
+      physics.debugEnabled = enabled;
+      physics.debugMesh.visible = enabled;
+    },
+    contactPoints: collectContactPoints,
   };
 }

package/src/adapter/system-adapter.ts

@@ -12,6 +12,8 @@
  */
 
 import type * as THREE from 'three';
+import type { RenderMemorySnapshot } from '../dev/render-memory';
+import type { FrameCapture } from '../dev/webgl-frame-capture';
 import type { ActionValueType, Vector2 } from '../input/input-types';
 import type { Transform, TransformOwner } from './transform';
 
@@ -30,6 +32,20 @@ export interface PhysicsAdapter {
   unfreeze(o: THREE.Object3D): void;
   /** Optional debug-draw object (collider wireframes). */
   debugDraw?(): THREE.Object3D | null;
+  /**
+   * Optional: turn the engine's per-frame physics debug rendering on/off —
+   * the first-party implementation drives Rapier's `debugRender()` into the
+   * `debugDraw()` object inside the game's own render system, so an editor
+   * overlay toggle costs the editor zero per-frame work (W2a §2.3c).
+   */
+  setDebugDrawEnabled?(enabled: boolean): void;
+  /**
+   * Optional: live world-space contact points this frame, as xyz triples.
+   * Returns a view over a REUSED backing buffer — valid only until the next
+   * call (no per-frame allocation churn; callers copy into their own
+   * geometry).
+   */
+  contactPoints?(): Float32Array;
 }
 
 export interface NetPeer {
@@ -59,7 +75,61 @@ export interface ReplicationStats {
 
 export type Unsubscribe = () => void;
 
-/** INTROSPECTION over replication state — NOT a networking transport. */
+/** One captured network message, for the inspector's message log (W3b).
+ *  `seq` is an adapter-lifetime MONOTONIC counter — the ring-buffer fence a
+ *  consumer polls with (`messageEvents(sinceSeq)`), mirroring
+ *  `DebugAdapter.events`' seq discipline. `time` is a `performance.now()`-
+ *  domain ms timestamp at capture. */
+export interface NetMessageEvent {
+  seq: number;
+  time: number;
+  direction: 'in' | 'out';
+  /** Message type/channel (e.g. `'input'`, `'players.add'`, `'state.phase'`). */
+  type: string;
+  /** Approximate payload size in bytes, when measurable. OMITTED — never
+   *  fabricated — when the transport doesn't expose it (e.g. Colyseus schema
+   *  patches observed via the Callbacks API carry no byte count). */
+  size?: number;
+  /** `true` when the link conditioner (`setConditioning`) dropped this
+   *  outbound message instead of sending it — logged so the inspector can
+   *  show the drop honestly rather than silently losing it. */
+  dropped?: boolean;
+}
+
+/** Send/receive rates for the inspector's sparklines (W3b). The byte fields
+ *  are OPTIONAL capabilities-within-the-capability: an implementer omits a
+ *  direction it cannot measure (never reports a fabricated 0). */
+export interface NetRates {
+  msgsInPerSec: number;
+  msgsOutPerSec: number;
+  bytesInPerSec?: number;
+  bytesOutPerSec?: number;
+}
+
+/** Client-side link-conditioning parameters, applied AT THE ADAPTER SEAM
+ *  (W3b M3) — the implementer wraps its own transport calls (e.g. delaying/
+ *  dropping around `room.send`); nobody patches transport internals. */
+export interface NetConditioning {
+  /** Fixed added delay per outbound message, ms. */
+  latencyMs: number;
+  /** Uniform random extra delay in `[0, jitterMs)`, ms. */
+  jitterMs: number;
+  /** Probability in `[0, 1]` that an outbound message is dropped. */
+  packetLoss: number;
+}
+
+/**
+ * INTROSPECTION over replication state — NOT a networking transport.
+ *
+ * The optional members are CAPABILITIES in the `SystemAdapters` sense
+ * (absence means "not supported" and the editor's Network inspector marks
+ * that section absent — it never fabricates data): `getStateSnapshot` feeds
+ * the replicated-state tree, `messageEvents` the message log, `getRates` the
+ * rate sparklines, and `getConditioning`/`setConditioning` the latency/loss
+ * conditioner. The first-party Colyseus factory
+ * (`createColyseusNetworkingAdapter`) only attaches each one when its config
+ * supplies the accessor, so partial implementers degrade honestly.
+ */
 export interface NetworkingAdapter {
   peers(): NetPeer[];
   networkId(o: THREE.Object3D): string | null;
@@ -74,6 +144,22 @@ export interface NetworkingAdapter {
   getReplicationStats(): ReplicationStats;
   /** Subscribe to changes in connection state / room / replication stats. */
   subscribe(cb: () => void): Unsubscribe;
+  /** Optional capability: one plain-data (JSON-safe) snapshot of the
+   *  replicated room state, or `null` when not connected. Colyseus schema is
+   *  self-describing (`state.toJSON()`), so the first-party implementation
+   *  is one call — the inspector renders whatever tree comes back. */
+  getStateSnapshot?(): unknown;
+  /** Optional capability: captured message events with `seq > sinceSeq`
+   *  (whole ring when omitted). Implementations ring-buffer (drop oldest);
+   *  the inspector keeps its own consumer-side ring and fences on `seq`. */
+  messageEvents?(sinceSeq?: number): NetMessageEvent[];
+  /** Optional capability: msg + byte rates for the inspector's sparklines. */
+  getRates?(): NetRates;
+  /** Optional capability (paired with `setConditioning`): current
+   *  conditioning parameters. */
+  getConditioning?(): NetConditioning;
+  /** Optional capability: apply link conditioning at the adapter seam. */
+  setConditioning?(c: NetConditioning): void;
 }
 
 /** One action's current value, tagged with its declared shape (F1 `ActionValueType`) so a
@@ -105,14 +191,125 @@ export interface NavPoint {
   z: number;
 }
 
+/**
+ * Navmesh bake parameters — the recast `rcConfig` vocabulary the scene schema
+ * (`SceneNavigationSchema`) also mirrors. All optional; an implementation
+ * applies its own defaults. `walkableHeight`/`walkableClimb`/`walkableRadius`
+ * are in VOXEL units (multiples of `cellHeight`/`cellSize`), per recast.
+ */
+export interface NavBakeParams {
+  cellSize?: number | undefined;
+  cellHeight?: number | undefined;
+  walkableSlopeAngle?: number | undefined;
+  walkableHeight?: number | undefined;
+  walkableClimb?: number | undefined;
+  walkableRadius?: number | undefined;
+  maxEdgeLen?: number | undefined;
+  maxSimplificationError?: number | undefined;
+  minRegionArea?: number | undefined;
+  mergeRegionArea?: number | undefined;
+}
+
+/** One crowd agent's live state — plain data (no engine/WASM handles), for the
+ *  editor's play-mode crowd debug draw. */
+export interface NavCrowdAgentState {
+  position: NavPoint;
+  velocity: NavPoint;
+  radius: number;
+  height: number;
+}
+
 /**
  * Inspect a game's navigation mesh: whether one is built, query a path, and get a
  * debug overlay. Coordination/introspection only — the editor doesn't own the build.
+ *
+ * The optional members are CAPABILITIES in the `SystemAdapters` sense (absence
+ * means "not supported", the editor degrades): `bake`/`exportData` let the
+ * editor's Navigation panel (re)build and persist a navmesh through the seam —
+ * the first-party recast implementation (`createNavigationAdapter`) is the
+ * blessed implementer — while an external game that owns its build simply
+ * omits them. `crowdAgents` feeds the play-mode crowd debug draw.
  */
 export interface NavigationAdapter {
   hasNavMesh(): boolean;
   findPath(start: NavPoint, end: NavPoint): NavPoint[];
   debugMesh(scene: THREE.Scene): THREE.Object3D | null;
+  /** (Re)build the navmesh from source meshes. Synchronous in the blessed
+   *  recast/WASM implementation; returns `false` on a failed bake. */
+  bake?(meshes: THREE.Mesh[], params?: NavBakeParams): boolean;
+  /** Serialize the current navmesh to a binary blob (the editor persists it
+   *  as the scene's `.navmesh` sidecar). Throws when nothing is built. */
+  exportData?(): Uint8Array;
+  /** Live crowd-agent snapshots for debug draw. Empty when no crowd. */
+  crowdAgents?(): NavCrowdAgentState[];
+}
+
+/** One node in an audio-graph snapshot (W3c, the Audio debugger tab). Edges
+ *  point DOWNSTREAM: `outputs` holds the ids of nodes this node's output
+ *  feeds (ultimately reaching the `destination` node). */
+export interface AudioGraphNode {
+  id: string;
+  /** Node class/constructor name (`'GainNode'`, `'Gain'` for a Tone node,
+   *  `'AudioDestinationNode'`, …) — whatever the implementation truthfully
+   *  knows, never a prettified fabrication. */
+  type: string;
+  /** Human-facing label (`'Master'`, `'Music bus'`) when one exists. */
+  label?: string;
+  /** ids of downstream nodes this node's output connects to. */
+  outputs: string[];
+  /** Lifecycle/playback state when truthfully known (`'running'`,
+   *  `'suspended'`, `'started'`…). OMITTED — never fabricated — otherwise. */
+  state?: string;
+}
+
+/** Musical-transport snapshot for the Audio debugger's transport strip
+ *  (W3c). The first-party implementation reads Tone's real transport. */
+export interface AudioTransportState {
+  state: 'started' | 'stopped' | 'paused';
+  /** Playback position along the transport's timeline, seconds. */
+  seconds: number;
+  bpm: number;
+  /** Musical position (`Bars:Beats:Sixteenths`) when a musical grid exists. */
+  position?: string;
+}
+
+/** One bus level sample: `level` is linear RMS over the implementation's most
+ *  recent analysis window (0 = silence; ~1 = full-scale). */
+export interface AudioMeterFrame {
+  id: string;
+  label: string;
+  level: number;
+}
+
+/** A live metering session. Metering costs real audio nodes (Tone.Meter /
+ *  AnalyserNode taps), so it is ACQUIRED for exactly as long as a meter UI is
+ *  visible and MUST be released via `dispose()` — the first-party handle
+ *  disconnects its analyser taps there (no leaked nodes after Stop). */
+export interface AudioMeterHandle {
+  /** Current level per bus. Cheap enough to poll at UI rate (~10 Hz). */
+  read(): AudioMeterFrame[];
+  /** Release the metering nodes. Idempotent. */
+  dispose(): void;
+}
+
+/** One entry in the audio event ring (W3c). `seq` is an adapter-lifetime
+ *  MONOTONIC counter — the same ring-buffer fence discipline as
+ *  `NetMessageEvent.seq` / `DebugAdapter.events`. `time` is a
+ *  `performance.now()`-domain ms timestamp at capture. `'error'` is reserved
+ *  for implementations that can truthfully report one (the first-party
+ *  adapter has no honest audio-error source today and never emits it). */
+export interface AudioDebugEvent {
+  seq: number;
+  time: number;
+  kind:
+    | 'transport-start'
+    | 'transport-stop'
+    | 'transport-pause'
+    | 'context-statechange'
+    | 'mute'
+    | 'unmute'
+    | 'error';
+  detail?: string;
 }
 
 /**
@@ -123,14 +320,46 @@ export interface NavigationAdapter {
  * cannot"). Absence on a world's `mounted.systems` means exactly that:
  * `Game.play.pause()` reports it loudly once per world rather than silently
  * leaving that world's audio playing under a "paused" game.
+ *
+ * The OPTIONAL methods below are the W3c read-only INTROSPECTION capabilities
+ * feeding the editor's Audio debugger tab (graph / transport / meters /
+ * events). They follow the W3a degradation ladder: an implementer omits what
+ * it cannot truthfully provide, and the editor marks that section absent —
+ * never fabricated. The full MIXER (sends/effects/gain editing) is SQ-4-gated
+ * and deliberately NOT part of this seam. The first-party implementation over
+ * the engine's own Tone/Web-Audio stack is
+ * `packages/engine/src/audio/audio-introspection.ts`; pre-existing
+ * mute-only registrants keep compiling untouched (every addition is
+ * optional).
  */
 export interface AudioAdapter {
+  /** Resume/unlock this adapter's real audio context from a user gesture.
+   * Optional for external adapters that do not own a resumable Web Audio
+   * context; first-party edit and play adapters both provide it. */
+  resume?(): void;
   /** `true` silences this world's audio; `false` restores it to whatever
    *  level it was at before silencing (an implementer's own concern — the
    *  first-party adapter restores its master-gain value, not a hardcoded 1). */
   setMuted(muted: boolean): void;
   /** Current muted state, for inspection (editor mute UI, proofs). */
   isMuted(): boolean;
+  /** Optional: current audio-graph snapshot (active nodes + downstream
+   *  edges). The first-party adapter reports the engine bus hierarchy plus
+   *  every Tone node routed through `connectToneBusToMasterGain` — it cannot
+   *  see a game's private Tone-internal wiring and does not pretend to. */
+  graphSnapshot?(): AudioGraphNode[];
+  /** Optional: musical-transport snapshot. Returns `null` — an honest
+   *  "this world has no musical transport" — when none is active (e.g. the
+   *  first-party adapter when the game never bridged Tone onto this world's
+   *  context). Method ABSENT means the capability itself is unsupported. */
+  transportState?(): AudioTransportState | null;
+  /** Optional: begin a per-bus metering session. Returns `null` when the
+   *  environment cannot meter (headless world with no real AudioContext) —
+   *  the UI says so rather than showing frozen zeros. */
+  acquireMeters?(): AudioMeterHandle | null;
+  /** Optional: the audio event ring (bounded, drops oldest). `sinceSeq`
+   *  filters to `seq > sinceSeq` — the consumer's fence. */
+  audioEvents?(sinceSeq?: number): AudioDebugEvent[];
 }
 
 /** One tick-stamped debug event (`ctx.debug.emit`, spec §3.3): `tick`/`simT`
@@ -170,7 +399,7 @@ export interface DebugCommandInfo {
  * game-scoped introspection + actuation over whatever a game registers via
  * `ctx.debug` (`registerStateProvider`/`registerCommand`/`emit`). NOT a
  * gameplay API — this is the one seam the debug bridge, the editor's Debug
- * Console/State Watch panels, and `@vgai/probe` all read/drive through.
+ * Console/State Watch panels, and `@vgai/e2e` all read/drive through.
  */
 export interface DebugAdapter {
   providers(): { name: string; tier: 'observable' | 'assisted' }[];
@@ -205,6 +434,23 @@ export interface DebugAdapter {
   events(sinceTick?: number, sinceSeq?: number): TickStampedEvent[];
 }
 
+/**
+ * Read-only render-debugging introspection (W4b, F11 frame debugger +
+ * profiler) — NOT a renderer. `captureFrame` arms the first-party WebGL2
+ * capture (`dev/webgl-frame-capture.ts`) and resolves with the NEXT rendered
+ * frame's draw list, attributed by wrapping each renderable's `onBeforeRender`
+ * (three calls it immediately before that object's main-pass draw; shadow/
+ * composer-pass draws stay unattributed BY CONSTRUCTION — an honest gap, not a
+ * guess). It REJECTS — never fabricates — if no frame renders within a bounded
+ * timeout (a paused/stopped world). `memorySnapshot` is the W3a-style OPTIONAL
+ * capability: present only when the mount can supply `renderer.info` (a
+ * headless mount omits it, and the editor marks the section absent).
+ */
+export interface RenderDebugAdapter {
+  captureFrame(): Promise<FrameCapture>;
+  memorySnapshot?(): RenderMemorySnapshot;
+}
+
 /**
  * The set of optional subsystem providers a mounted game may expose. Absence of
  * a provider means "capability not supported" — the editor degrades gracefully.
@@ -217,4 +463,5 @@ export interface SystemAdapters {
   navigation?: NavigationAdapter;
   audio?: AudioAdapter;
   debug?: DebugAdapter;
+  renderDebug?: RenderDebugAdapter;
 }