@vgai/engine 0.5.11 → 0.5.13

package/src/adapter/ingest/game-contract.ts

@@ -15,9 +15,18 @@
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems).
+ * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems), WO-SYS2
+ * (`systems.systemAdapters`).
  */
 
+import type {
+  AudioAdapter,
+  NavigationAdapter,
+  NetworkingAdapter,
+  PhysicsAdapter,
+  RenderDebugAdapter,
+} from '../system-adapter';
+
 /**
  * Session lifecycle endpoints. Declaring `start` means "I support cold
  * mount": when the host sets `window.__vgaiMountCold` before the game's entry
@@ -66,6 +75,29 @@ export interface VgaiGameStateProvider {
   read(): unknown;
 }
 
+/**
+ * One top-level semantic hierarchy group from the game's OWN model. `count`
+ * is recomputed by the game when the host reads the hierarchy; it is not
+ * inferred from render objects. The editor presents these rows beside the
+ * captured render tree, so a system-driven game can say what its content is
+ * without pretending its scene graph is authored truth.
+ */
+export interface VgaiGameHierarchyGroup {
+  id: string;
+  label: string;
+  count: number;
+}
+
+/**
+ * Synchronous read plus an optional game-owned invalidation signal. The
+ * editor never polls or guesses when a game's model changed; a dynamic game
+ * subscribes its ordinary authoring hierarchy to the same truth it reads.
+ */
+export interface VgaiGameHierarchyProvider {
+  (): VgaiGameHierarchyGroup[];
+  subscribe?(listener: () => void): () => void;
+}
+
 /**
  * The game's SYSTEM surface: what its content actually IS, as opposed to how
  * it renders. An ingested game's content is not always its scene graph — in a
@@ -73,9 +105,10 @@ export interface VgaiGameStateProvider {
  * is reached through the game's own verbs, which `root`/`lifecycle` could not
  * express.
  *
- * Both members are read by exactly one consumer,
- * `adapter/ingest/contract-debug-adapter.ts`, which projects them onto the
- * host's ordinary `DebugAdapter` (`adapter/system-adapter.ts`) — so
+ * Every member is read by a concrete consumer: commands/state are projected
+ * by `adapter/ingest/contract-debug-adapter.ts` onto the host's ordinary
+ * `DebugAdapter` (`adapter/system-adapter.ts`), while `hierarchy` is projected
+ * by the editor onto the ordinary `AuthoringAdapter.hierarchy` surface. Thus
  * `game.commands()`/`game.state()` reach an ingested game through the same
  * bridge first-party content uses, with no second vocabulary for agents to
  * learn. That is deliberate scope: this
@@ -88,6 +121,62 @@ export interface VgaiGameSystems {
   commands?: VgaiGameCommand[];
   /** State reads, enumerated by `game.providers()` and read by `game.state(...)`. */
   state?: VgaiGameStateProvider[];
+  /** Semantic hierarchy groups from the game's own model, recomputed on read. */
+  hierarchy?: VgaiGameHierarchyProvider;
+  /**
+   * The game's own {@link SystemAdapters} slots — the ingest-realm equivalent
+   * of a first-party world's `ctx.registerSystemAdapter`. Read and projected by
+   * `contract-system-adapters.ts` onto the mounted root's `systems` bag, so an
+   * ingested game's physics/audio/navigation/networking reach the editor's
+   * ordinary panels through the SAME registry a native world publishes to.
+   */
+  systemAdapters?: VgaiGameSystemAdapters;
+}
+
+/**
+ * A slot's IMPLEMENTED-EMPTY answer: "this game genuinely has no X", carried
+ * with the source-level evidence that establishes it.
+ *
+ * This exists because `SystemAdapters` is capability-by-PRESENCE, and presence
+ * has only two values while the ingestion bar (docs/BRINGING-AN-EXISTING-GAME.md
+ * §The ingestion checklist) has three inputs: bound, positively-absent, and
+ * not-yet-answered. Omitting a slot cannot tell the last two apart — an editor
+ * reading a bare absence cannot know whether anyone ever looked. Declaring this
+ * record says someone looked, says what they found, and turns a work-order row
+ * into a terminal one.
+ *
+ * It is deliberately NOT an adapter whose methods return zeros: a
+ * `getConnectionState()` of `'disconnected'` on a game with no transport at all
+ * is a fabrication (it implies a connection that could exist), which the
+ * anti-shim rule forbids. The absence is stated, never simulated.
+ */
+export interface VgaiGameSystemEmpty {
+  /** Always `false` — the discriminant that separates this from an adapter. */
+  present: false;
+  /**
+   * Why the slot is empty, in SOURCE terms: what was searched and what was
+   * found. "no netcode anywhere in `src/`" is a finished answer; "not
+   * implemented yet" is not one, and a reviewer reading this field is meant to
+   * be able to re-run the search.
+   */
+  evidence: string;
+}
+
+/**
+ * The declarable `SystemAdapters` slots, each either a real implementation or a
+ * positively-answered {@link VgaiGameSystemEmpty}.
+ *
+ * `debug` is deliberately NOT here: it is already the projection of
+ * `commands`/`state` above (`contract-debug-adapter.ts`), and a second door onto
+ * the same slot would let a game declare two different debug planes with no rule
+ * for which wins.
+ */
+export interface VgaiGameSystemAdapters {
+  physics?: PhysicsAdapter | VgaiGameSystemEmpty;
+  networking?: NetworkingAdapter | VgaiGameSystemEmpty;
+  navigation?: NavigationAdapter | VgaiGameSystemEmpty;
+  audio?: AudioAdapter | VgaiGameSystemEmpty;
+  renderDebug?: RenderDebugAdapter | VgaiGameSystemEmpty;
 }
 
 export interface VgaiGameContract {
@@ -114,11 +203,11 @@ export interface VgaiGameContract {
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
  * (pre-contract fallbacks apply) rather than half-interpreted.
  *
- * `scope` is the REALM to read from, and defaults to this module's own `window`
- * — correct for a same-realm mount, where the game's modules and the host share
- * one global. An iframe-hosted game declares on ITS realm's window, so the host
- * passes `iframe.contentWindow`: the contract is a property of the realm the
- * game runs in, never of the realm that happens to be asking.
+ * `scope` is the REALM to read from, and defaults to this module's own
+ * `window` — the realm every ingest mount runs the game's modules in, where the
+ * game and the host share one global. It is a parameter at all because the
+ * contract is a property of the realm the game runs in, never of the realm that
+ * happens to be asking.
  */
 export function readGameContract(
   scope: Window | null | undefined = typeof window === 'undefined' ? null : window,

package/src/adapter/ingest/scene-capture.ts

@@ -70,11 +70,11 @@ export interface SceneCaptureOptions {
    * each with its own offscreen renderer and its own little light rig) is a
    * candidate to be captured AS THE GAME.
    *
-   * That is what made `cov-mismatched-three` — the spec for "a game bundling
-   * its own three is DETECTED and degrades to embed-only, never silently" —
+   * That is what made the "a game bundling its own three is DETECTED, never
+   * silently mistaken for a capture" spec
    * pass or fail on timing alone: whether a thumbnail happened to bake inside
-   * the game's 2.5s capture window. When it did, the editor adopted its own
-   * preview scene as the game and `captureFailed` never fired.
+   * the game's capture window. When it did, the editor adopted its own
+   * preview scene as the game and the mount reported success.
    *
    * Identity, not shape, is the discriminator: a host renderer and a game
    * renderer are the same class, both built after install, both drawing real
@@ -84,10 +84,38 @@ export interface SceneCaptureOptions {
   isHostRenderer?: (renderer: unknown) => boolean;
 }
 
+/**
+ * Brackets ONE `render()` call the captured renderer makes.
+ *
+ * The trap already stands between an ingested game and its own
+ * `WebGLRenderer.render`, which is the only place a host can see the game's
+ * render pass begin and end — the game owns its loop, so nothing else in the
+ * editor gets a `finally` around it. That is exactly the bracket
+ * `dev/render-debug-adapter.ts`'s `beforeRender`/`afterRender` need, so the
+ * first-party `RenderDebugAdapter` works for an ingested game with no per-game
+ * shimming and no second capture mechanism.
+ *
+ * Neither hook may throw: they run inside the game's own render call, so an
+ * exception here would break the game's frame. The trap calls them in a
+ * `try`/`finally` for `after`, but a throwing `before` is the hook author's bug.
+ */
+export interface RenderPassHooks {
+  before(): void;
+  after(): void;
+}
+
 /** Handle returned by {@link installSceneCapture}. */
 export interface SceneCaptureHandle {
   /** The captured runtime, or null until the game renders its first frame. */
   readonly captured: CapturedRuntime | null;
+  /**
+   * Install (or clear, with `null`) hooks bracketing every `render()` the
+   * CAPTURED renderer makes. Set AFTER capture, because the consumer
+   * (`RenderDebugAdapter`) is built from the captured scene and context. Only
+   * the captured renderer's renders are bracketed — the editor's own viewport
+   * renders come through the same trap and are not the game's frame.
+   */
+  setRenderPassHooks(hooks: RenderPassHooks | null): void;
   /** Resolve once a scene+camera is captured (rejects on timeout). */
   waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
   /** Total `render()` calls observed through the trap (a liveness signal). */
@@ -156,6 +184,8 @@ export function installSceneCapture(
 
   let captured: CapturedRuntime | null = null;
   let drawCount = 0;
+  /** Set post-capture by the host; see {@link SceneCaptureHandle.setRenderPassHooks}. */
+  let renderPassHooks: RenderPassHooks | null = null;
   const waiters: Array<(rt: CapturedRuntime) => void> = [];
 
   // Preserve any descriptor already on the prototype so uninstall can restore it.
@@ -190,6 +220,26 @@ export function installSceneCapture(
     },
   });
 
+  /**
+   * Call the renderer's own real `render`, bracketed by the render-pass hooks
+   * when this IS the captured game's renderer (see `setRenderPassHooks`).
+   * `after` runs in a `finally`, so a throwing game frame still restores
+   * whatever the hook armed.
+   */
+  function forwardRender(self: Record<symbol, unknown>, args: unknown[]): unknown {
+    const real = self[REAL] as (...a: unknown[]) => unknown;
+    const hooks = renderPassHooks;
+    if (hooks === null || !captured || (self as unknown) !== captured.renderer) {
+      return real.apply(self, args);
+    }
+    hooks.before();
+    try {
+      return real.apply(self, args);
+    } finally {
+      hooks.after();
+    }
+  }
+
   Object.defineProperty(proto, 'render', {
     configurable: true,
     set(this: Record<symbol, unknown>, fn: unknown) {
@@ -211,13 +261,11 @@ export function installSceneCapture(
         if (!captured || (self as unknown) === captured.renderer) drawCount++;
         // Never capture a scene the HOST owns. The trap sits on the shared
         // `WebGLRenderer.prototype`, so the editor's own viewport renders
-        // arrive here too — and when a game bundles its own MISMATCHED three
-        // (the case this whole degrade-to-embed-only path exists for), the
-        // editor's scene is then the only thing that ever reaches the trap.
+        // arrive here too — and when a game bundles its own MISMATCHED three,
+        // the editor's scene is then the only thing that ever reaches the trap.
         // It was duly "captured" as the game: the editor got a hierarchy of
         // its own GridHelper, BatchedRenderer and viewport lights presented as
-        // the ingested game's content, and `captureFailed` — the signal the
-        // whole graceful-degradation contract is built on — never fired.
+        // the ingested game's content, and the mount reported success.
         // Whether that happened at all came down to whether the editor
         // rendered a frame inside the game's capture window, so the same
         // session could pass or fail on timing alone.
@@ -230,8 +278,7 @@ export function installSceneCapture(
           };
           for (const resolve of waiters.splice(0)) resolve(captured);
         }
-        // Forward to the renderer's real render with the original args.
-        return (self[REAL] as (...a: unknown[]) => unknown).apply(self, args);
+        return forwardRender(self, args);
       };
     },
   });
@@ -276,6 +323,9 @@ export function installSceneCapture(
     getDrawCount() {
       return drawCount;
     },
+    setRenderPassHooks(hooks: RenderPassHooks | null) {
+      renderPassHooks = hooks;
+    },
     getAnimationLoop(renderer: THREE.WebGLRenderer) {
       return loopCallbacks.get(renderer as unknown as object) ?? null;
     },

package/src/adapter/ingest/structural-ids.ts

@@ -29,7 +29,7 @@ export const CAMERA_ID = 'ingest:camera';
  * The editor parks its OWN objects — grid, its two lights, the particle
  * BatchedRenderer, every TransformControls/gizmo helper — on layer 31
  * (`packages/editor/src/editor-layers.ts`'s `EDITOR_LAYER`) so the game camera
- * never sees them. In ingest mode those objects are added to the GAME'S OWN
+ * never sees them. On an ingest root those objects are added to the GAME'S OWN
  * scene, which is the same tree this walk indexes.
  */
 const EDITOR_ONLY_LAYER_MASK = 1 << 31;
@@ -74,7 +74,7 @@ export interface StructuralIdWalk {
  * tree re-binds the same ids to the same objects.
  *
  * EDITOR FURNITURE IS EXCLUDED, and that exclusion is load-bearing rather than
- * cosmetic. In ingest mode the editor adds its grid, lights, particle
+ * cosmetic. On an ingest root the editor adds its grid, lights, particle
  * BatchedRenderer and TransformControls gizmo to the GAME'S OWN scene, and
  * they arrive asynchronously — some before the walk, some after. Indexing them
  * made a game object's path depend on how much editor furniture happened to be

package/src/adapter/reflection-probe.ts

@@ -0,0 +1,75 @@
+/**
+ * Format-neutral live reflection-probe mark.
+ *
+ * A project-owned scene component writes this mark onto the Object3D it
+ * returns. The renderer capability owns capture and material integration; the
+ * editor only reads the mark to draw ordinary probe gizmos and expose the
+ * capture command/status. Authored truth remains the component's JSX props —
+ * this is a live adapter seam, not another document format.
+ */
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+export type ReflectionProbeShape = 'box' | 'sphere';
+export type ReflectionProbeCaptureMode = 'on-change' | 'manual' | 'realtime';
+export type ReflectionProbeCaptureStatus = 'idle' | 'queued' | 'capturing' | 'ready' | 'error';
+
+export interface ReflectionProbeConfig {
+  readonly shape: ReflectionProbeShape;
+  /** Full local-space box dimensions. */
+  readonly size: readonly [number, number, number];
+  /** Local-space sphere radius when `shape === 'sphere'`. */
+  readonly radius: number;
+  /** Local-space distance over which this probe fades at its boundary. */
+  readonly blendDistance: number;
+  /** Larger values win before equal-priority probes blend. */
+  readonly priority: number;
+  readonly intensity: number;
+  readonly parallaxProjection: boolean;
+  /** Full local-space projection-box dimensions. */
+  readonly parallaxSize: readonly [number, number, number];
+  readonly parallaxOffset: readonly [number, number, number];
+  readonly captureOffset: readonly [number, number, number];
+  readonly captureMode: ReflectionProbeCaptureMode;
+  readonly resolution: number;
+  readonly near: number;
+  readonly far: number;
+  readonly cullMask: number;
+  readonly captureShadows: boolean;
+}
+
+export interface ReflectionProbeSnapshot {
+  readonly status: ReflectionProbeCaptureStatus;
+  /** Monotonic browser time from `performance.now()`, or null before capture. */
+  readonly lastCapturedAt: number | null;
+  readonly message?: string;
+}
+
+export interface ReflectionProbeMark {
+  readonly config: ReflectionProbeConfig;
+  readonly revision: number;
+  recapture(): void;
+  getSnapshot(): ReflectionProbeSnapshot;
+  subscribe(listener: () => void): () => void;
+}
+
+export function reflectionProbeOf(
+  object: THREE.Object3D | null | undefined,
+): ReflectionProbeMark | null {
+  const candidate = getUserData(object, 'reflectionProbe');
+  if (!candidate || typeof candidate !== 'object') return null;
+  const mark = candidate as Partial<ReflectionProbeMark>;
+  return mark.config &&
+    typeof mark.recapture === 'function' &&
+    typeof mark.getSnapshot === 'function'
+    ? (candidate as ReflectionProbeMark)
+    : null;
+}
+
+export function setReflectionProbeMark(object: THREE.Object3D, mark: ReflectionProbeMark): void {
+  setUserData(object, 'reflectionProbe', mark);
+}
+
+export function clearReflectionProbeMark(object: THREE.Object3D): void {
+  deleteUserData(object, 'reflectionProbe');
+}

package/src/asset-formats/index.ts

@@ -1,14 +1,11 @@
 /**
- * The engine's remaining authored asset formats and descriptor schemas.
+ * The engine's runtime descriptor schemas.
  *
  * WO-8 deleted the `.vscn.json` scene format and everything under
  * `engine/src/scene/`. What survived is here, and each module is here because a
  * real runtime reader still consumes it:
  *
- * - `material.ts`   — the `.mat.json` shared-material format (`parseMaterialFile`)
- *                     plus the inline material descriptor `render/material-factory.ts` reads
- * - `instances.ts`   — the `.instances.json` transform format (`parseInstancesFile`),
- *                     read by `render/instance-mesh.ts`
+ * - `material.ts`   — the inline material descriptor `render/material-factory.ts` reads
  * - `mesh.ts`        — the geometry descriptor `render/material-factory.ts`'s `createGeometry` reads
  * - `light.ts` / `camera.ts` — the descriptors `render/light-camera-factory.ts` reads
  * - `collider.ts`    — the descriptor `physics/collider-dimensions.ts` and the editor's
@@ -29,15 +26,12 @@ export type { CameraDescriptor } from './camera';
 export { CameraDescriptorSchema } from './camera';
 export type { ColliderDescriptor } from './collider';
 export { ColliderDescriptorSchema } from './collider';
-export type { InstancesFile } from './instances';
-export { InstancesFileSchema } from './instances';
 export type { LightDescriptor } from './light';
 export { LightDescriptorSchema } from './light';
-export type { MaterialDescriptor, MaterialFile } from './material';
-export { MaterialDescriptorSchema, MaterialFileSchema } from './material';
+export type { MaterialDescriptor } from './material';
+export { MaterialDescriptorSchema } from './material';
 export type { MeshDescriptor } from './mesh';
 export { MeshDescriptorSchema } from './mesh';
-export { parseInstancesFile, parseMaterialFile } from './parse';
 export type { ParticlesDescriptor } from './particles';
 export { ParticlesDescriptorSchema } from './particles';
 export type {

package/src/asset-formats/material.ts

@@ -91,14 +91,3 @@ export const MaterialDescriptorSchema = MaterialDescriptorObjectSchema.describe(
 );
 
 export type MaterialDescriptor = z.infer<typeof MaterialDescriptorSchema>;
-
-/** .mat.json file format for shared/reusable material assets. */
-export const MaterialFileSchema = z
-  .object({
-    version: z.number().describe('File format version'),
-    name: z.string().describe('Human-readable material name'),
-    material: MaterialDescriptorSchema.describe('Material definition'),
-  })
-  .describe('Shared material asset file (.mat.json)');
-
-export type MaterialFile = z.infer<typeof MaterialFileSchema>;

package/src/asset-formats/mesh.ts

@@ -30,15 +30,6 @@ const MeshDescriptorBase = z
           'lifted out of its armature — if the named node is a SkinnedMesh (or contains one), ' +
           'resolving it throws (degrade loudly, not silently).',
       ),
-    instances: z
-      .string()
-      .optional()
-      .describe(
-        'Path to an instance-transform asset (.instances.json: an array of ' +
-          '[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples). Renders one ' +
-          'THREE.InstancedMesh (one draw call). Bulk transform data is referenced as an asset, ' +
-          'never inlined — keeps the document thin.',
-      ),
     lod: z
       .array(
         z.object({
@@ -61,7 +52,7 @@ const MeshDescriptorBase = z
       .describe(
         'Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance ' +
           '(THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when ' +
-          'off, only the closest level renders. Cannot combine with node/instances.',
+          'off, only the closest level renders. Cannot combine with node.',
       ),
   })
   .strict();
@@ -79,12 +70,8 @@ export const MeshDescriptorSchema = MeshDescriptorBase.refine(
   .refine((m) => m.lod == null || m.type === 'gltf', {
     message: "Mesh 'lod' is only meaningful with type: 'gltf'",
   })
-  .refine((m) => m.instances == null || m.type !== 'splat', {
-    message: "Mesh 'instances' is not supported with type: 'splat'",
-  })
-  .refine((m) => !(m.lod && (m.node || m.instances)), {
-    message:
-      "Mesh 'lod' cannot combine with 'node'/'instances' — LOD is the multi-level form of a node ref",
+  .refine((m) => !(m.lod && m.node), {
+    message: "Mesh 'lod' cannot combine with 'node' — LOD is the multi-level form of a node ref",
   })
   .describe('Mesh geometry definition');
 

package/src/asset-parse-error.ts

@@ -4,14 +4,13 @@
  * Every authored asset format the engine validates at fetch time throws this
  * when Zod rejects the payload, naming the offending file (T4.6). It lives
  * here — beside `loader.ts`/`assets.ts` — rather than inside a format module so
- * every caller (the `.mat.json` parser, the input-map loader in
- * `input/input-manager.ts`) does not have to reach into the format half for
- * it.
+ * every caller (currently the input-map loader in `input/input-manager.ts`)
+ * does not have to reach into an unrelated subsystem for it.
  *
  * It was called `SceneParseError` until WO-9 task #6. The extraction that gave
  * this file its name deliberately deferred the class rename ("extraction, not
- * redesign"); with `.vscn` gone the old name described nothing — a `.mat.json`
- * or `.inputmap.json` failure is not a scene failure — so the class and its
+ * redesign"); with `.vscn` gone the old name described nothing — an
+ * `.inputmap.json` failure is not a scene failure — so the class and its
  * message header now say `asset`.
  */
 

package/src/config.ts

@@ -3,6 +3,19 @@
  * evaluated. The package build emits this entry as ordinary JavaScript, so
  * project config remains package-native without asking Node to execute raw
  * TypeScript or reach into an adjacent checkout.
+ *
+ * A project's `*.schema.ts` is reached from `vite.config.ts` itself (through
+ * `./src/data/assets`, so the dangling-ref gate can run the real Zod), which
+ * is why every schema-time field factory belongs here: `dataRef` and `curve`
+ * are both authored in a schema, and a schema module must stay loadable by
+ * plain Node.
  */
+export {
+  type CurveAxes,
+  type CurvePoint,
+  type CurveValue,
+  curve,
+  sampleCurve,
+} from './data/curve';
 export { type DataRef, dataRef, getRef } from './data/data-ref';
 export { type VgaiDataCheckOptions, vgaiDataCheck } from './data/vite-plugin-data';