@vgai/engine 0.5.5 → 0.5.6

package/dist/adapter/system-adapter.d.ts

@@ -0,0 +1,453 @@
+/**
+ * System adapters — optional subsystem capability providers hung off a mounted
+ * game (`MountedThreeRoot.systems`). Each is a thin capability boundary the editor can
+ * coordinate with WITHOUT owning the implementation. The first-party
+ * implementers wrap Rapier / Colyseus / recast; an external game supplies its
+ * own or none, and the editor degrades per `capabilities`.
+ *
+ * These are introspection/coordination boundaries, NOT re-implementations: e.g.
+ * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
+ * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
+ * edit it".
+ */
+import type * as THREE from 'three';
+import type { RenderMemorySnapshot } from '../dev/render-memory';
+import type { FrameCapture } from '../dev/webgl-frame-capture';
+import type { Transform, TransformOwner } from './transform';
+/**
+ * Physics coordination so the editor can stably edit an object a simulation
+ * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
+ *
+ * Keyed by NODE ID (the `EditorNode` id), not `THREE.Object3D` (P-4). The
+ * Object3D keying made this seam structurally unreachable for any non-three
+ * world: a Pixi or React world could never expose a physics inspector, because
+ * the seam spoke a vocabulary it has no values in — which is why the Pixi
+ * surface grew a parallel `PhysicsAdapter2D` (`pixi/system-adapters.ts`)
+ * instead of implementing this. Substrate-specific resolution (id → the native
+ * object) is the IMPLEMENTER's job, done once at its own boundary.
+ */
+export interface PhysicsAdapter {
+    /** Returns `'physics'` when a body drives this node, else another owner. */
+    ownerOf(nodeId: string): TransformOwner;
+    /** Pause the body driving `nodeId` (kinematic / sleep / detach) for editing. */
+    freeze(nodeId: string): void;
+    /** Teleport the body to the edited pose (so the sim continues from there). */
+    commit(nodeId: string, t: Transform): void;
+    /** Resume simulation of `nodeId`. */
+    unfreeze(nodeId: string): 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 {
+    id: string;
+    label?: string;
+}
+/** The project's declared multiplayer server, readable with the game NOT
+ *  running. `null` from `getServerConfig` means no server is declared. */
+export interface NetServerConfig {
+    endpoint: string;
+    roomName: string;
+}
+/** The signed-in player's authored identity, used as the connect default. */
+export interface NetPlayerIdentity {
+    name?: string;
+    id?: string;
+}
+/** The live connection lifecycle, for the editor's network inspector. */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** Identity of the room the local peer is currently in, or `null` when not connected. */
+export interface RoomInfo {
+    roomId: string;
+    sessionId: string;
+    roomName: string;
+}
+/** Lightweight replication counters for the editor's network inspector. */
+export interface ReplicationStats {
+    /** Number of replicated entities currently known (e.g. players + NPCs). */
+    entities: number;
+    /** Approximate inbound replication activity (state changes observed per second). */
+    msgsInPerSec: number;
+    /** Approximate outbound message rate (client → server sends per second). */
+    msgsOutPerSec: number;
+}
+export type Unsubscribe = () => void;
+/** 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[];
+    /** Keyed by NODE ID, not `THREE.Object3D` — see {@link PhysicsAdapter} (P-4). */
+    networkId(nodeId: string): string | null;
+    authority(nodeId: string): 'local' | 'remote' | 'server';
+    /** Remote/server-authoritative nodes → inspect-only in the editor. */
+    editable(nodeId: string): boolean;
+    /** Current connection lifecycle state. */
+    getConnectionState(): ConnectionState;
+    /** The active room's identity, or `null` when not connected to a room. */
+    getRoomInfo(): RoomInfo | null;
+    /** Replication activity snapshot, for a live network inspector panel. */
+    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;
+    /** Optional edit-time capability: the project's declared server, readable
+     *  with the game NOT running (`null` = no server declared). Hides on
+     *  absence, like the other optionals. */
+    getServerConfig?(): NetServerConfig | null;
+    /** Optional capability: the local player's identity, as the GAME defines it
+     *  (e.g. read off its own room state). The editor consumes this for display —
+     *  a seat label — ONLY when a real implementer provides it, falling back to a
+     *  generic label otherwise. */
+    getPlayerIdentity?(): NetPlayerIdentity;
+    /** Optional capability, PAIRED with {@link getPlayerIdentity}: set the local
+     *  player's identity through the game's OWN multiplayer mechanism. The editor
+     *  renders an editable name field ONLY when a real implementer provides this
+     *  (consume-by-presence, exactly like {@link setConditioning}); its absence
+     *  means the game does not support an author-settable name and no field shows.
+     *
+     *  This is NOT the editor imposing a name: whether a name is settable, and how
+     *  it reaches the server, is entirely the game's decision — a game that names
+     *  players by join order simply never provides this member. When it does, the
+     *  implementation drives the game's real path (a join option honoured by the
+     *  server, a rename message, …), so what the editor sets is the same value the
+     *  multiplayer build actually uses — never a placeholder the server discards. */
+    setPlayerIdentity?(identity: NetPlayerIdentity): void | Promise<void>;
+}
+export interface NavPoint {
+    x: number;
+    y: number;
+    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;
+}
+/**
+ * Silence/restore a world's own audio (D10, T7.6) — NOT a mixer/bus API. This
+ * is the seam `Game.play.pause()` calls so a paused world's audio goes quiet
+ * too ("an audio seam in `SystemAdapters` so pause can silence game audio
+ * (howler et al.) or explicitly report it 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`
+ *  are the engine's own counters AT EMISSION, so events and state reads
+ *  correlate frame-exactly across every door (in-page bridge, relay, panels).
+ *
+ *  `seq` (run-4 friction #5 fix) is a registry-lifetime MONOTONIC counter,
+ *  strictly increasing by one per `emit()` call regardless of `tick` —
+ *  unlike `tick`, it is never shared by two events, which is what makes it
+ *  safe to fence on. A debug command handler runs BETWEEN ticks (its
+ *  emissions carry whatever `tick` is current at that instant, same as every
+ *  other emission at that instant would), so two DIFFERENT events — or an
+ *  event and a consumer's fence point — can legitimately share one `tick`;
+ *  `seq` never collides the same way, so "everything after what I've already
+ *  observed" is unambiguous. See `events(sinceSeq)` below. */
+export interface TickStampedEvent {
+    tick: number;
+    simT: number;
+    event: string;
+    detail?: unknown;
+    seq: number;
+}
+/** One registered debug command's listing shape — `locus` is always present
+ *  (defaults to `'client'` when a command didn't declare one) so every
+ *  listing surface can print it without a fallback of its own. */
+export interface DebugCommandInfo {
+    name: string;
+    description?: string | undefined;
+    /** JSON-Schema projection of the command's Zod args tuple, when declared. */
+    argsJsonSchema?: unknown;
+    locus: 'client' | 'server';
+}
+/**
+ * The debug/synthetic-player seam: 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/live` all read/drive through.
+ */
+export interface DebugAdapter {
+    providers(): {
+        name: string;
+        tier: 'observable' | 'assisted';
+    }[];
+    /** One provider's current value. Throws `DebugError` code
+     *  `STATE_PROVIDER_NOT_FOUND` (`data.registered`) for an unknown name. */
+    state(name: string): unknown;
+    /** One coherent snapshot of every registered provider — a throwing
+     *  provider contributes `{ __error: String(err) }` for its own key rather
+     *  than failing the whole snapshot. */
+    stateAll(): Record<string, unknown>;
+    commands(): DebugCommandInfo[];
+    /** Validates `args` against the command's declared Zod tuple (when
+     *  present), then awaits the registered fn. Throws `DebugError` code
+     *  `DEBUG_COMMAND_NOT_REGISTERED` for an unknown name,
+     *  `DEBUG_COMMAND_ARGS_INVALID` for a validation failure, or
+     *  `DEBUG_COMMAND_FAILED` wrapping anything the command itself threw. */
+    invoke(name: string, args: unknown[]): Promise<unknown>;
+    /** The tick-stamped event ring (cap 500, drops oldest).
+     *
+     *  - `sinceSeq` given (run-4 friction #5 fix): filters to `seq > sinceSeq`
+     *    — the unambiguous fence for "everything emitted after what I've
+     *    already observed" (see `TickStampedEvent.seq`'s doc comment for why
+     *    `tick` alone can't do this: a debug-command emission and a consumer's
+     *    fence point can share one tick).
+     *  - Omitted: the whole ring.
+     *
+     *  There was a second, KNOWN-DEFECTIVE `sinceTick` parameter (`tick >
+     *  sinceTick`, which silently dropped same-tick events) kept for
+     *  back-compat after the seq fix. It is REMOVED — a fence is `seq` or
+     *  nothing. */
+    events(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.
+ */
+export interface SystemAdapters {
+    physics?: PhysicsAdapter;
+    networking?: NetworkingAdapter;
+    navigation?: NavigationAdapter;
+    audio?: AudioAdapter;
+    debug?: DebugAdapter;
+    renderDebug?: RenderDebugAdapter;
+}
+//# sourceMappingURL=system-adapter.d.ts.map

package/dist/adapter/system-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/system-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;IACxC,gFAAgF;IAChF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,IAAI,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,mBAAmB,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C;;;;;OAKG;IACH,aAAa,CAAC,IAAI,YAAY,CAAC;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;0EAC0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAEpF,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;sCAIsC;AACtC,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC;IACxB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb;;uEAEmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;iEAE6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;kEAEkE;AAClE,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;wEAEwE;AACxE,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,EAAE,CAAC;IACnB,iFAAiF;IACjF,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACzC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,0CAA0C;IAC1C,kBAAkB,IAAI,eAAe,CAAC;IACtC,0EAA0E;IAC1E,WAAW,IAAI,QAAQ,GAAG,IAAI,CAAC;IAC/B,yEAAyE;IACzE,mBAAmB,IAAI,gBAAgB,CAAC;IACxC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,WAAW,CAAC;IACvC;;;wEAGoE;IACpE,gBAAgB,CAAC,IAAI,OAAO,CAAC;IAC7B;;8EAE0E;IAC1E,aAAa,CAAC,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAAC;IACrD,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,QAAQ,CAAC;IACtB;mCAC+B;IAC/B,eAAe,CAAC,IAAI,eAAe,CAAC;IACpC,wEAAwE;IACxE,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C;;6CAEyC;IACzC,eAAe,CAAC,IAAI,eAAe,GAAG,IAAI,CAAC;IAC3C;;;mCAG+B;IAC/B,iBAAiB,CAAC,IAAI,iBAAiB,CAAC;IACxC;;;;;;;;;;;qFAWiF;IACjF,iBAAiB,CAAC,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;2CAC2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,IAAI,OAAO,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACrD,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACrD;wEACoE;IACpE,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC;IAC7D;4EACwE;IACxE,UAAU,CAAC,IAAI,UAAU,CAAC;IAC1B,sEAAsE;IACtE,WAAW,CAAC,IAAI,kBAAkB,EAAE,CAAC;CACtC;AAED;;0DAE0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX;;iDAE6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;gFAC4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;yEACyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;6DAC6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;wEAGwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,IAAI,IAAI,eAAe,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;0EAK0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EACA,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,GACjB,qBAAqB,GACrB,MAAM,GACN,QAAQ,GACR,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B;;sEAEkE;IAClE,MAAM,CAAC,IAAI,IAAI,CAAC;IAChB;;kFAE8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,oEAAoE;IACpE,OAAO,IAAI,OAAO,CAAC;IACnB;;;6EAGyE;IACzE,aAAa,CAAC,IAAI,cAAc,EAAE,CAAC;IACnC;;;8EAG0E;IAC1E,cAAc,CAAC,IAAI,mBAAmB,GAAG,IAAI,CAAC;IAC9C;;2DAEuD;IACvD,aAAa,CAAC,IAAI,gBAAgB,GAAG,IAAI,CAAC;IAC1C;8DAC0D;IAC1D,WAAW,CAAC,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAAC;CACpD;AAED;;;;;;;;;;;;8DAY8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;kEAEkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,GAAG,UAAU,CAAA;KAAE,EAAE,CAAC;IACjE;8EAC0E;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B;;2CAEuC;IACvC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,IAAI,gBAAgB,EAAE,CAAC;IAC/B;;;;6EAIyE;IACzE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD;;;;;;;;;;;;mBAYe;IACf,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;CAC/C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IACtC,cAAc,CAAC,IAAI,oBAAoB,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC"}

package/dist/adapter/system-adapter.js

@@ -0,0 +1,13 @@
+/**
+ * System adapters — optional subsystem capability providers hung off a mounted
+ * game (`MountedThreeRoot.systems`). Each is a thin capability boundary the editor can
+ * coordinate with WITHOUT owning the implementation. The first-party
+ * implementers wrap Rapier / Colyseus / recast; an external game supplies its
+ * own or none, and the editor degrades per `capabilities`.
+ *
+ * These are introspection/coordination boundaries, NOT re-implementations: e.g.
+ * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
+ * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
+ * edit it".
+ */
+export {};

package/dist/adapter/transform.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The neutral transform value used across adapter interfaces. Position + scale
+ * are xyz; rotation is a quaternion (xyzw) — matching `Object3D.quaternion`, so
+ * adapters never have to agree on an Euler convention.
+ */
+export interface Transform {
+    position: [number, number, number];
+    rotation: [number, number, number, number];
+    scale: [number, number, number];
+}
+/**
+ * Who currently owns an object's transform — i.e. what writes it each frame.
+ * The editor uses this to decide whether a gizmo edit is durable (`editor`),
+ * needs simulation coordination (`physics`), or is best-effort/inspect-only
+ * (`script`/`network`/`external`).
+ */
+export type TransformOwner = 'editor' | 'physics' | 'animation' | 'script' | 'network' | 'external';
+//# sourceMappingURL=transform.d.ts.map

package/dist/adapter/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/adapter/transform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC"}

package/dist/adapter/transform.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/navigation.d.ts

@@ -0,0 +1,78 @@
+/**
+ * NavMeshManager — wraps recast-navigation for navmesh generation + crowd pathfinding.
+ *
+ * Usage:
+ *   await init();  // WASM init (call once per app)
+ *   const nav = new NavMeshManager();
+ *   await nav.buildFromMeshes(meshes);
+ *   const path = nav.findPath(start, end);
+ *   const crowd = nav.createCrowd(10);
+ *   // In game loop: nav.updateCrowd(dt);
+ */
+import { NavMeshHelper } from '@recast-navigation/three';
+import type { CrowdAgent } from 'recast-navigation';
+import { Crowd } from 'recast-navigation';
+import type { Mesh, Scene } from 'three';
+export type { CrowdAgent };
+export interface Vector3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+/** One crowd agent's live state — a plain-data snapshot safe to hand across
+ *  the adapter seam (no WASM handles), for editor debug draw. */
+export interface CrowdAgentSnapshot {
+    position: Vector3Like;
+    velocity: Vector3Like;
+    radius: number;
+    height: number;
+}
+export interface NavMeshBuildParams {
+    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;
+}
+export declare function initNavigation(): Promise<void>;
+export declare class NavMeshManager {
+    private navMesh;
+    private query;
+    private crowd;
+    private helper;
+    /** Build navmesh from Three.js Mesh objects (grounds, obstacles, etc.). */
+    buildFromMeshes(meshes: Mesh[], params?: NavMeshBuildParams): boolean;
+    /**
+     * Destroy all live recast handles (crowd, query, navmesh) and dispose the
+     * debug helper. Recast objects live on the WASM heap and are NOT GC'd —
+     * they must be explicitly `.destroy()`ed or they leak.
+     */
+    private destroyRecast;
+    /** True once a navmesh has been built (for the NavigationAdapter to gate on). */
+    hasNavMesh(): boolean;
+    /** Find a straight path between two world positions. Returns [] if no path. */
+    findPath(start: Vector3Like, end: Vector3Like): Vector3Like[];
+    /** Create a crowd with up to maxAgents agents. */
+    createCrowd(maxAgents: number): Crowd;
+    /** Step the crowd simulation. Call once per frame. */
+    updateCrowd(dt: number): void;
+    /**
+     * Plain-data snapshots of every active crowd agent (interpolated position,
+     * velocity, radius, height) — the introspection feed for the editor's
+     * play-mode crowd debug draw. Empty when no crowd exists.
+     */
+    getCrowdAgents(): CrowdAgentSnapshot[];
+    /** Get or create the wireframe debug mesh. Add to scene once, call update() after rebuilding. */
+    getDebugMesh(scene: Scene): NavMeshHelper | null;
+    /** Serialize the current navmesh to a binary blob. */
+    exportData(): Uint8Array;
+    /** Load a navmesh from a previously exported binary blob. */
+    loadFromData(data: Uint8Array): void;
+    dispose(scene: Scene): void;
+}
+//# sourceMappingURL=navigation.d.ts.map

package/dist/ai/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/ai/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAoD,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGzC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;iEACiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAID,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAA8B;IAE5C,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO;IA4BrE;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,iFAAiF;IACjF,UAAU,IAAI,OAAO;IAIrB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,EAAE;IAO7D,kDAAkD;IAClD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAMrC,sDAAsD;IACtD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,cAAc,IAAI,kBAAkB,EAAE;IActC,iGAAiG;IACjG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI;IAShD,sDAAsD;IACtD,UAAU,IAAI,UAAU;IAKxB,6DAA6D;IAC7D,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAM5B"}