@vgai/engine 0.5.2 → 0.5.3

package/README.md

@@ -1,14 +1,19 @@
 # @vgai/engine
 
-The vgai game engine: the game loop and phase scheduler, the
-`GameComponent` model (the world node *is* the entity — no ECS, no mirror
-tree), Rapier physics integration, the `.vscn.json` scene loader with its
-Zod schemas (the single source of truth for the scene format), animation
+The vgai game engine: the game loop and phase scheduler (the world node
+*is* the entity — no ECS, no mirror
+tree), Rapier physics integration, the manifest and asset-format loaders
+with their Zod schemas, animation
 (native `THREE.AnimationMixer` actions bound to XState state machines via
 `bindXStateAnimation` — see `src/animation/xstate-animation-binding.ts`),
 audio, input, the adapter seam
 (`src/adapter/` — how the editor hosts non-native and unmodified games),
-and the world2d PixiJS stack.
+and the Pixi substrate for canvas-surface games (`src/pixi/`).
+
+A world is authored as TSX/R3F **source**, and the source is the
+document — there is no scene file and no schema for one; the manifest
+schema is strict, so an unrecognized key is rejected loudly rather than
+ignored.
 
 **License: Apache-2.0** (see [LICENSE](./LICENSE)). Your game code that
 imports this package carries no copyleft obligations.
@@ -38,10 +43,9 @@ The bare package exposes the small game/setup surface:
 
 ```ts
 import {
-  GameComponent,
   fromSetup,
   loadGameManifest,
-  mountManifestWorlds,
+  mountManifestRoots,
   type GameContext,
 } from '@vgai/engine';
 ```
@@ -60,11 +64,14 @@ control integration is used.
 
 - Public Learn/manual: https://vgai-learn.pages.dev
 - Hosted editor: https://vgai-editor.pages.dev
-- In a source checkout, read the repo-root `ARCHITECTURE.md` first—the target
+- In a source checkout, read `docs/ARCHITECTURE-CORE.md` first—the target
   architecture and current implementation are marked separately.
-- Scene/format schemas: `src/scene/schema/` (every field `.describe()`d;
-  `npm run generate-schema` emits JSON Schema for autocomplete).
-- The component model: `src/ecs/game-component.ts`.
+- Schemas, in two homes (every field `.describe()`d; `npm run
+  generate-schema` emits JSON Schema for autocomplete):
+  `src/asset-formats/` (the fetched assets the render
+  path reads: `.mat.json`, `.inputmap.json`, meshes, lights, cameras,
+  colliders, particles, render-env), and `src/manifest/schema.ts`
+  (`vgai.project.json`).
 - The adapter contracts: `src/adapter/`.
 - Source-checkout tests are headless with real dependencies: `npm run
   test:unit` from the repository root.

package/package.json

@@ -2,9 +2,15 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
-  "keywords": ["game-engine", "three.js", "pixijs", "react", "ai-agents"],
+  "keywords": [
+    "game-engine",
+    "three.js",
+    "pixijs",
+    "react",
+    "ai-agents"
+  ],
   "type": "module",
   "homepage": "https://vgai-learn.pages.dev",
   "repository": {
@@ -35,11 +41,9 @@
   "dependencies": {
     "@dimforge/rapier2d-compat": "^0.14.0",
     "@dimforge/rapier3d-compat": "^0.14.0",
-    "@pixi/tilemap": "^5.0.0",
+    "@pixi/react": "8.0.5",
     "@recast-navigation/three": "^0.43.0",
     "@sparkjsdev/spark": "^2.1.0",
-    "@theatre/core": "0.7.2",
-    "gsap": "^3.12.0",
     "loglayer": "^9.1.0",
     "n8ao": "^1.10.1",
     "pixi.js": "^8.6.0",
@@ -47,7 +51,6 @@
     "recast-navigation": "^0.43.0",
     "three": "^0.180.0",
     "three.quarks": "^0.16.0",
-    "tone": "^15.1.22",
     "xstate": "^5.32.4",
     "zod": "^4.3.6"
   },
@@ -68,6 +71,7 @@
     }
   },
   "devDependencies": {
+    "@theatre/core": "0.7.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.4",

package/schemas/engine-api.json

@@ -19,7 +19,7 @@
     },
     {
       "name": "gameLogic",
-      "description": "General gameplay behavior. Default phase for GameComponents."
+      "description": "General gameplay behavior."
     },
     {
       "name": "animation",
@@ -53,72 +53,5 @@
     "ANIMATION": "animation",
     "PRE_RENDER": "preRender",
     "RENDER": "render"
-  },
-  "gameComponent": {
-    "description": "Base class for game components attached to entities. The Three.js Object3D IS the entity — there is no separate entity id.",
-    "defaultPhase": "gameLogic",
-    "statics": [
-      {
-        "name": "phase",
-        "type": "SystemPhaseName",
-        "default": "gameLogic",
-        "description": "Which phase this component's update runs in. Override in subclasses."
-      },
-      {
-        "name": "schema",
-        "type": "z.ZodObject | undefined",
-        "default": null,
-        "description": "Optional Zod object schema for authored fields. When set, scene data is validated + defaulted through `schema.parse(data)` before assignment."
-      }
-    ],
-    "fields": [
-      {
-        "name": "object3D",
-        "type": "THREE.Object3D",
-        "description": "The Object3D this component is attached to. The Object3D IS the entity."
-      },
-      {
-        "name": "rigidBody",
-        "type": "RAPIER.RigidBody | null",
-        "description": "The entity's Rapier rigid body, if it has physics."
-      },
-      {
-        "name": "collider",
-        "type": "RAPIER.Collider | null",
-        "description": "The entity's Rapier collider, if it has physics."
-      }
-    ],
-    "hooks": [
-      {
-        "name": "init",
-        "optional": true,
-        "signature": "init?(ctx: GameContext): void | Promise<void>",
-        "description": "Called once after the entity is fully constructed (object3D, physics, etc.)."
-      },
-      {
-        "name": "update",
-        "optional": false,
-        "signature": "update(dt: number, ctx: GameContext): void",
-        "description": "Called every fixed timestep, in the component's phase. Required (abstract)."
-      },
-      {
-        "name": "dispose",
-        "optional": true,
-        "signature": "dispose?(ctx: GameContext): void",
-        "description": "Called when the entity is destroyed or the component is removed."
-      },
-      {
-        "name": "onTriggerEnter",
-        "optional": true,
-        "signature": "onTriggerEnter?(other: THREE.Object3D, ctx: GameContext): void",
-        "description": "Called when a sensor overlap with `other` begins."
-      },
-      {
-        "name": "onTriggerExit",
-        "optional": true,
-        "signature": "onTriggerExit?(other: THREE.Object3D, ctx: GameContext): void",
-        "description": "Called when a sensor overlap with `other` ends."
-      }
-    ]
   }
 }

package/schemas/engine-api.md

@@ -15,39 +15,8 @@ Each frame, systems run in this exact order (from `PHASE_ORDER` in `packages/eng
 | 2 | `prePhysics` | `SystemPhase.PRE_PHYSICS` | Apply forces/intents to rigid bodies before the physics step. |
 | 3 | `physics` | `SystemPhase.PHYSICS` | Step the Rapier physics world (fixed timestep). |
 | 4 | `postPhysics` | `SystemPhase.POST_PHYSICS` | Read physics results back; sync transforms from bodies to Object3D. |
-| 5 | `gameLogic` | `SystemPhase.GAME_LOGIC` | General gameplay behavior. Default phase for GameComponents. |
+| 5 | `gameLogic` | `SystemPhase.GAME_LOGIC` | General gameplay behavior. |
 | 6 | `animation` | `SystemPhase.ANIMATION` | Advance animation graphs / mixers. |
 | 7 | `preRender` | `SystemPhase.PRE_RENDER` | Final per-frame fixups (cameras, HUD state) before drawing. |
 | 8 | `render` | `SystemPhase.RENDER` | Draw the frame. |
 
-## GameComponent Contract (v2)
-
-Base class for game components attached to entities. The Three.js Object3D IS the entity — there is no separate entity id.
-
-Default phase: `gameLogic`
-
-### Static members
-
-| Member | Type | Default | Description |
-| ------ | ---- | ------- | ----------- |
-| `phase` | `SystemPhaseName` | `"gameLogic"` | Which phase this component's update runs in. Override in subclasses. |
-| `schema` | `z.ZodObject | undefined` | `null` | Optional Zod object schema for authored fields. When set, scene data is validated + defaulted through `schema.parse(data)` before assignment. |
-
-### Instance fields (wired by ComponentManager)
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `object3D` | `THREE.Object3D` | The Object3D this component is attached to. The Object3D IS the entity. |
-| `rigidBody` | `RAPIER.RigidBody | null` | The entity's Rapier rigid body, if it has physics. |
-| `collider` | `RAPIER.Collider | null` | The entity's Rapier collider, if it has physics. |
-
-### Lifecycle / hooks
-
-| Hook | Required | Signature | Description |
-| ---- | -------- | --------- | ----------- |
-| `init` | no | `init?(ctx: GameContext): void | Promise<void>` | Called once after the entity is fully constructed (object3D, physics, etc.). |
-| `update` | yes | `update(dt: number, ctx: GameContext): void` | Called every fixed timestep, in the component's phase. Required (abstract). |
-| `dispose` | no | `dispose?(ctx: GameContext): void` | Called when the entity is destroyed or the component is removed. |
-| `onTriggerEnter` | no | `onTriggerEnter?(other: THREE.Object3D, ctx: GameContext): void` | Called when a sensor overlap with `other` begins. |
-| `onTriggerExit` | no | `onTriggerExit?(other: THREE.Object3D, ctx: GameContext): void` | Called when a sensor overlap with `other` ends. |
-

package/schemas/engine-capabilities.json

@@ -1,8 +1,8 @@
 {
-  "$comment": "Curated by human/agent review, NOT auto-generated (unlike engine-api.json beside it). Every claim was verified against code — see each entry's `evidence`. Staleness is machine-checked at two granularities: `schemaDirHash` (sha256 over packages/engine/src/scene/schema/) and per-entry `evidenceHashes` (sha256 of each cited evidence FILE — catches drift in files outside the schema dir, which is where most entries' evidence lives; T5.5/MASTER-ARCHITECTURE-REVIEW.md §7.2).",
+  "$comment": "Curated by human/agent review, NOT auto-generated (unlike engine-api.json beside it). Every claim was verified against code — see each entry's `evidence`. Staleness is machine-checked at two granularities: `schemaDirHash` (sha256 over packages/engine/src/asset-formats/) and per-entry `evidenceHashes` (sha256 of each cited evidence FILE — catches drift in files outside the schema dir, which is where most entries' evidence lives; T5.5/§7.2).",
   "_readme": "Read this before authoring scene JSON or engine code, to avoid the negatives below. Refresh flow after a schema-dir OR evidence-file change: `npx tsx scripts/capabilities-hash.ts --check` (fails naming the stale entry) -> re-review affected entries against current code -> `--write` to record fresh hashes. The pre-commit hook runs --check automatically. Each entry's `evidenceHashes` maps the repo-relative file path parsed off the front of each `evidence[]` citation (before any `:line-range` suffix) to a sha256 of that file's current content.",
-  "schemaDirPath": "packages/engine/src/scene/schema/",
-  "schemaDirHash": "d092efe0ed1fffc07d8a759d16deecb978f89b0386e2a375243804e84f7e74e5",
+  "schemaDirPath": "packages/engine/src/asset-formats/",
+  "schemaDirHash": "3f8728d85cc14c17acbdababa414b51f40d73cee30434e83cf23b01518db06a6",
   "reviewedAt": "2026-07-01",
   "entries": [
     {
@@ -11,13 +11,11 @@
       "status": "unsupported",
       "claim": "No Continuous Collision Detection (CCD). Fast/small dynamic bodies can tunnel through thin colliders in one step.",
       "evidence": [
-        "packages/engine/src/scene/scene-loader.ts (the `bodyDesc` switch: fixed/kinematicPositionBased/dynamic only; file under concurrent edit elsewhere this wave, so no line numbers — grep 'RigidBodyDesc')",
-        "packages/engine/src/world2d/scene2d-loader.ts:168-179 (2D bodyDesc: same four stock constructors)"
+        "packages/engine/src/adapter/setup-three-root-adapter.ts (the Rapier home: world init + step; no ccd flag is ever set)"
       ],
-      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches, 2D and 3D. No call ever sets a ccd flag. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders.",
+      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no rigid bodies itself — games build their own descs via ctx.RAPIER — and nothing engine-side ever enables ccd. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders; a game may also call setCcdEnabled on its own bodies directly.",
       "evidenceHashes": {
-        "packages/engine/src/scene/scene-loader.ts": "07fb9086e95959fd84e71ccc57581bb00d1f6eca1137853492b6a569755e8db5",
-        "packages/engine/src/world2d/scene2d-loader.ts": "f0f74eefd9cce16bbe7826225a52f2b0407ab141641dcdd370bcff1d091bce69"
+        "packages/engine/src/adapter/setup-three-root-adapter.ts": "fd3035e557db23e002e52707145a6e17bb3ad15767da74ec8fbafd40879d1d34"
       }
     },
     {
@@ -26,13 +24,11 @@
       "status": "unsupported",
       "claim": "No enforced limit on entity or physics-body count; practical envelope is untested.",
       "evidence": [
-        "packages/engine/src/setup/setup-physics.ts (RAPIER.World construction: no capacity/count config)",
-        "packages/engine/src/scene/scene-loader.ts (entity/body creation: no count guard)"
+        "packages/engine/src/setup/setup-physics.ts (RAPIER.World construction: no capacity/count config)"
       ],
       "notes": "Grepped for maxBodies/MAX_ENTITIES/entity limit/body limit/entityCount: no matches. No invented numbers — nothing caps entity/body count and no perf test here establishes a safe ceiling. Treat large counts (hundreds+ dynamic bodies) as unvalidated, not 'supported at scale'.",
       "evidenceHashes": {
-        "packages/engine/src/setup/setup-physics.ts": "0540c502f420018b24dac8b77c486f30f905f0a05b02ead7ed3899e5aa612ee5",
-        "packages/engine/src/scene/scene-loader.ts": "07fb9086e95959fd84e71ccc57581bb00d1f6eca1137853492b6a569755e8db5"
+        "packages/engine/src/setup/setup-physics.ts": "0540c502f420018b24dac8b77c486f30f905f0a05b02ead7ed3899e5aa612ee5"
       }
     },
     {
@@ -46,8 +42,8 @@
       ],
       "notes": "gamepad disconnect/reconnect needs no special-cased code: poll() re-reads navigator.getGamepads() and every read skips a null slot, so a disconnected gamepad's actions go neutral with a correct isJustReleased edge for free — see input-device-backends-f2.test.ts.",
       "evidenceHashes": {
-        "packages/engine/src/input/input-types.ts": "d6c7a6d1eda6b71665407fd5ac35d414dccf4156d4f79c56671b07e0a60b7f7c",
-        "packages/engine/src/input/input-manager.ts": "f3c2683397ed36eeb34ffd54861d14e4c0675bc7fbaef5530e7552a1edd129d4"
+        "packages/engine/src/input/input-types.ts": "62d9005609a72b55a8214c869d1b27825b1a17b9389f3f3f5d0b04725331b382",
+        "packages/engine/src/input/input-manager.ts": "22f0f3cc21a22b3cd3111b2c017ae9a7a430d48156c5bd5d12ed82d6f79ddab8"
       }
     },
     {
@@ -62,62 +58,54 @@
       "notes": "XState remains the only transition language. Parallel regions use distinct layer names. The binding filters native clip tracks, uses AnimationUtils.makeClipAdditive, can register with ctx.systems, and exposes live owner inspection data until disposal.",
       "evidenceHashes": {
         "packages/engine/src/animation/xstate-animation-meta.ts": "80376ac74819803616c4b396244a971cb9a6b2859c33409d032363bfeb3db44f",
-        "packages/engine/src/animation/xstate-animation-binding.ts": "34e94a7db674ea3d8a98cf98359a9ba8cdd2af9266d1e857a6ad5df02d5a5f73"
-      }
-    },
-    {
-      "id": "component-fields-no-nested-objects",
-      "area": "scene-schema",
-      "status": "unsupported",
-      "claim": "Authored `components.<Name>` values in .vscn.json/.prefab.json must be a scalar or homogeneous scalar array — nested objects/arrays-of-objects are rejected before a component's own static schema sees them.",
-      "evidence": [
-        "packages/engine/src/scene/schema/entity.ts:46-54 (ComponentScalarSchema/ComponentValueSchema/ComponentDataSchema/ComponentsSchema)",
-        "packages/engine/src/scene/schema/entity.ts:89 (`components: ComponentsSchema.optional()` on SceneEntitySchema, validated at scene-parse time)",
-        "packages/engine/src/scene/component-registry.ts:21-37 (applyComponents' `Klass.schema.parse(data)` runs on data that already passed ComponentDataSchema)"
-      ],
-      "notes": "The ceiling: `z.union([number, string, boolean, number[], string[], boolean[]])`. A GameComponent's own static `schema` CAN declare z.object() fields, but the scene-file parse rejects a nested value first, so authored JSON never carries one that far. Workaround: flatten (`targetX`/`targetY`/`targetZ` instead of `target:{x,y,z}`).",
-      "evidenceHashes": {
-        "packages/engine/src/scene/schema/entity.ts": "2b73fec245362168b1824ee06b820c801e7590de95ab1f11176fadad54991f21",
-        "packages/engine/src/scene/component-registry.ts": "7ea93439c56fdcd1db915893ebb0f3cabfc08112dbf24c15c76df64a063713e4"
+        "packages/engine/src/animation/xstate-animation-binding.ts": "d23739a5820f8e7a36707b5d0a9de2feba0c7200bd9f56de876eded62ce7e9d9"
       }
     },
     {
       "id": "ingestion-pixi-tiers",
       "area": "ingestion",
       "status": "supported-with-tiers",
-      "claim": "Unmodified OSS PixiJS games run via the world2d seam: manifest 'iframe-reachable' + bundleUrl — in-realm capture, editor edits, overlay persistence. extraDeps must be registry-known (unknown throws); capture failure degrades loudly.",
+      "claim": "Unmodified OSS PixiJS games run via the canvas ingest seam: manifest 'iframe-reachable' + bundleUrl — in-realm capture, editor edits, overlay persistence. extraDeps must be registry-known (unknown throws); capture failure degrades loudly.",
       "evidence": [
-        "docs/BACKBONE-TASKS.md:389-414"
+        "vendor/games/verify-unaltered.mjs (zero-diff vendoring gate)",
+        "packages/engine/src/manifest/schema.ts"
       ],
-      "notes": "Track P shipped 2026-07-03; proven: bubbo-bubbo/puzzling-potions/flappy-pixi. Tiers/limits: docs/CAPABILITY-TIERS.md, docs/PIXI-INGEST-LANDING-DESIGN.md.",
+      "notes": "Track P shipped 2026-07-03; proven: bubbo-bubbo/puzzling-potions/flappy-pixi. Tiers/limits: ARCHITECTURE-CORE.md.",
       "evidenceHashes": {
-        "docs/BACKBONE-TASKS.md": "4d58398e22ed0261ec246668cac115ec9cfdde9881920070e95ee642f1323eb1"
+        "vendor/games/verify-unaltered.mjs": "c41ce285aaa26a8fd0e6f5e20385b434d6fc73fc3f39ac1a61204d7141166201",
+        "packages/engine/src/manifest/schema.ts": "63d3f6fdbe3e9323ecbd4910c540d8a77e57d95e9044016424b46ca15a5c0bea"
       }
     },
     {
       "id": "ingestion-react-dom",
       "area": "ingestion",
       "status": "supported-with-caveats",
-      "claim": "Unmodified native-React DOM games run via the manifest `ingest-react` identity: vendored byte-for-byte (vendor/react-games/, zero-diff CI), mounted through the react world stack under the host React 19 (deduped). Embed-only in v1 — hosted, sized, disposed; NO authoring (the editor never writes JSX back into an unmodified game, D-N4).",
+      "claim": "Unmodified native-React DOM games run via the manifest `ingest-react` identity: vendored byte-for-byte (vendor/games/, zero-diff CI), mounted through the react world stack under the host React 19 (deduped). Embed-only in v1 — hosted, sized, disposed; NO authoring (the editor never writes JSX back into an unmodified game, D-N4).",
       "evidence": [
-        "docs/BACKBONE-TASKS.md:415-435 (Track N, N0-N4 all done)"
+        "vendor/games/verify-unaltered.mjs (zero-diff vendoring gate)",
+        "packages/editor/src/adapter-resolver.ts"
       ],
-      "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate. Design: docs/REACT-INGEST-LANDING-DESIGN.md.",
+      "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate.",
       "evidenceHashes": {
-        "docs/BACKBONE-TASKS.md": "4d58398e22ed0261ec246668cac115ec9cfdde9881920070e95ee642f1323eb1"
+        "vendor/games/verify-unaltered.mjs": "c41ce285aaa26a8fd0e6f5e20385b434d6fc73fc3f39ac1a61204d7141166201",
+        "packages/editor/src/adapter-resolver.ts": "ce88071c9a4061df0a3b7edef24031bf81704ae2c3ede62ed6bf43d4f34ac556"
       }
     },
     {
       "id": "engine-supports-summary",
       "area": "summary",
       "status": "supported",
-      "claim": "For contrast, the engine DOES support: discrete Rapier bodies (fixed/kinematic/dynamic) with triggers; phase-ordered GameComponents; Zod-validated scene/prefab JSON; masked layered animation state machines with blend trees; boolean+thresholded-analog input actions; direct (unwrapped) Colyseus multiplayer.",
+      "claim": "For contrast, the engine DOES support: discrete Rapier bodies (fixed/kinematic/dynamic) with triggers; phase-ordered systems; Zod-validated fetched asset formats; XState-driven animation state machines with masked, weighted, additive layers and 1D/2D blend trees; boolean+thresholded-analog input actions; direct (unwrapped) Colyseus multiplayer.",
       "evidence": [
-        "packages/engine/schemas/engine-api.json (auto-generated positive/imperative-surface manifest beside this file)"
+        "packages/engine/schemas/engine-api.json (auto-generated positive/imperative-surface manifest beside this file)",
+        "packages/engine/src/animation/xstate-animation-binding.ts",
+        "packages/engine/src/animation/blend-node.ts"
       ],
       "notes": "This file exists for negatives engine-api.json can't express (e.g. 'parses but does nothing'). For the full positive surface, read engine-api.json/.md — regenerated by `npm run generate-engine-manifest`, can't drift.",
       "evidenceHashes": {
-        "packages/engine/schemas/engine-api.json": "9cdf401821aaa4065a32eb0c042c3962e27a9bb76b017ee6ab5a282ab4c7c004"
+        "packages/engine/schemas/engine-api.json": "cdfd395fab88575a13c74451051e6c86f8b07980152120f00caa62098ecf7917",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "d23739a5820f8e7a36707b5d0a9de2feba0c7200bd9f56de876eded62ce7e9d9",
+        "packages/engine/src/animation/blend-node.ts": "9e1d2018acf138bb984fd0d2c7ff1045ef00689e613abf531453af0a1ba06b2e"
       }
     }
   ]

package/schemas/{vgai-game.schema.json → vgai-project.schema.json}

@@ -20,12 +20,6 @@
       "description": "Stable reverse-domain application id used by packaged targets",
       "type": "string"
     },
-    "editorPort": {
-      "description": "Stable preferred local editor port; launchers may fall forward when occupied",
-      "type": "integer",
-      "minimum": 1024,
-      "maximum": 65535
-    },
     "version": {
       "type": "string",
       "description": "The game's own version (used for orphan detection)"
@@ -58,13 +52,14 @@
             "type": "string"
           },
           "adapter": {
+            "description": "This root's adapter and sole rendering/lifecycle discriminator",
             "anyOf": [
               {
                 "type": "string",
                 "enum": [
-                  "threejs",
-                  "pixijs",
-                  "react"
+                  "three",
+                  "canvas",
+                  "dom"
                 ]
               },
               {
@@ -77,9 +72,9 @@
                   "surface": {
                     "type": "string",
                     "enum": [
-                      "threejs",
-                      "pixijs",
-                      "react"
+                      "three",
+                      "canvas",
+                      "dom"
                     ],
                     "description": "Native surface exposed by this custom adapter contract"
                   }
@@ -96,9 +91,9 @@
                   "surface": {
                     "type": "string",
                     "enum": [
-                      "threejs",
-                      "pixijs",
-                      "react"
+                      "three",
+                      "canvas",
+                      "dom"
                     ],
                     "description": "Native surface captured from the unmodified game"
                   },
@@ -116,7 +111,7 @@
                         "description": "Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier"
                       },
                       "entryHtml": {
-                        "description": "Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through the project-static route and hosted in a sandboxed iframe (embed-only, no scene introspection), for both pixijs and threejs roots. Legal but NOT wired to a mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` instead, the wired reachable route).",
+                        "description": "Entry HTML path, project-relative. WIRED for opaque-embed (D-W2): the file`s bytes are read verbatim through the project-static route and hosted in a sandboxed iframe (embed-only, no scene introspection), for both canvas and three roots. Legal but NOT wired to a mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` instead, the wired reachable route).",
                         "type": "string"
                       },
                       "assets": {
@@ -137,11 +132,11 @@
                         }
                       },
                       "captureTimeoutMs": {
-                        "description": "Max time to wait for in-realm/cross-realm capture before failing loudly",
+                        "description": "How long to wait for capture before REPORTING the degrade loudly — not how long to keep listening. On the self-hosted-three route the devtools subscription is permanent, so a renderer appearing later still upgrades a reported-embed-only mount in place; the host clamps this value so a long one cannot block the editor on a question the upgrade path answers anyway.",
                         "type": "number"
                       },
                       "bundleUrl": {
-                        "description": "Absolute URL of the externalized built game bundle — the WIRED iframe-reachable mount route (iframe-reachable only), for BOTH pixijs (Track P, ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, docs/WAVE4-FTUE-HARDENING-DESIGN.md, ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). PRECONDITION: the bundle must externalize its root`s own runtime as a bare, un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` does this for you) so it resolves through the iframe importmap to the HOST instance the capture trap is installed on; a bundle with an inlined runtime is unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/entryHtml is required when strategy is iframe-reachable.",
+                        "description": "Absolute URL of the externalized built game bundle — the WIRED iframe-reachable mount route (iframe-reachable only), for BOTH canvas (Track P, ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and three (D-W1, ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). PRECONDITION: the bundle must externalize its root`s own runtime as a bare, un-rewritten import (`pixi.js` for canvas, `three` for three — `vgai bundle` does this for you) so it resolves through the iframe importmap to the HOST instance the capture trap is installed on; a bundle with an inlined runtime is unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/entryHtml is required when strategy is iframe-reachable.",
                         "type": "string"
                       },
                       "baseHref": {
@@ -149,18 +144,18 @@
                         "type": "string"
                       },
                       "assetBaseUrl": {
-                        "description": "Host-side basePath forced onto the trapped runtime's own asset resolution — pixi's `Assets.init` for a pixijs root, three's `DefaultLoadingManager.setURLModifier` for a threejs root (D-W1) — absolute, or root-relative (resolved against the editor page's own origin at mount time, ingest-mode.ts, so a static manifest never has to know the dev-server port) (iframe-reachable only — a document.write iframe keeps the parent window.location).",
+                        "description": "Host-side basePath forced onto the trapped runtime's own asset resolution — pixi's `Assets.init` for a canvas root, three's `DefaultLoadingManager.setURLModifier` for a three root (D-W1) — absolute, or root-relative (resolved against the editor page's own origin at mount time, ingest-mode.ts, so a static manifest never has to know the dev-server port) (iframe-reachable only — a document.write iframe keeps the parent window.location).",
                         "type": "string"
                       },
                       "extraDeps": {
-                        "description": "Bare specifiers of this root's externalized deps beyond its own runtime (pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's host-namespace registry into module namespaces when known (D-P1 — the manifest carries data, not code); an unregistered specifier falls back to the open project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served as a verbatim iframe importmap URL. Throws a named error if neither resolves it (iframe-reachable only).",
+                        "description": "Bare specifiers of this root's externalized deps beyond its own runtime (pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's host-namespace registry into module namespaces when known (D-P1 — the manifest carries data, not code); an unregistered specifier falls back to the open project's own node_modules (D-Z3), served as a verbatim iframe importmap URL. Throws a named error if neither resolves it (iframe-reachable only).",
                         "type": "array",
                         "items": {
                           "type": "string"
                         }
                       },
                       "pixiModuleUrl": {
-                        "description": "PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for version skew) (iframe-reachable only). Declaring this on a `kind: \"threejs\"` root is schema-legal (this field is kind-agnostic here) but throws a NAMED not-supported error at resolve — three has no version-skew mount this wave (D-W7, docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly parked, no consumer exists).",
+                        "description": "PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for version skew) (iframe-reachable only). Declaring this on a `kind: \"three\"` root is schema-legal (this field is kind-agnostic here) but throws a NAMED not-supported error at resolve — three has no version-skew mount this wave (D-W7: a hypothetical `threeModuleUrl` is explicitly parked, no consumer exists).",
                         "type": "string"
                       },
                       "bodyHtml": {
@@ -180,20 +175,15 @@
                 ],
                 "additionalProperties": false
               }
-            ],
-            "description": "This root's adapter and sole rendering/lifecycle discriminator"
-          },
-          "scene": {
-            "description": ".vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)",
-            "type": "string"
+            ]
           },
           "entry": {
-            "description": "Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)",
+            "description": "Module exporting a world root — a TSX/R3F component or a setup()/adapter (three), or a React component (dom). Required for every built-in adapter root.",
             "type": "string"
           },
           "zOrder": {
             "default": 0,
-            "description": "Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order",
+            "description": "Canvas stacking order; ties broken by array order",
             "type": "integer",
             "minimum": -9007199254740991,
             "maximum": 9007199254740991
@@ -203,6 +193,11 @@
             "description": "Whether play-mode pause/step applies to this root",
             "type": "boolean"
           },
+          "dev": {
+            "default": false,
+            "description": "Marks this root as a DEV LAYER: the game's own dev GUI, not shipped game content. Four readers act on it. `mountManifestRoots` mounts it only when dev layers are enabled (`devLayersEnabled`, runtime/dev-layers.ts), so a production build carries no dev GUI; the host stacks every dev root ABOVE every non-dev root (a dev layer sits topmost, and as a DOM layer it steals no input from the game while closed); the play compositor EXCLUDES dev layers from a capture unless the capture asks for them; and the editor mounts a dev root as edit-time CHROME rather than authorable content (no hierarchy entry, no OID stamping, no JSX write-back, not selectable).",
+            "type": "boolean"
+          },
           "loop": {
             "default": "gated",
             "description": "gated: host-driven loop (default). self-driven: this root drives its own loop (the \"composited, unsynchronized\" tier) — an axis independent of capability tier",
@@ -249,7 +244,7 @@
         ],
         "additionalProperties": false
       },
-      "description": "The Game's explicit, non-empty adapter-root composition. There is no implicit root."
+      "description": "The Game's explicit, non-empty adapter-root composition. There is no implicit root. Root ids are unique, and a project declares at most ONE world root per medium — one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest and canvas module are the same medium). A `dev: true` root is counted in its own band: a dev layer is chrome stacked above the game, not content competing for the medium, so a game may declare a `dom` HUD and a `dom` dev layer — but not two of either."
     },
     "authoring": {
       "description": "Editor-only authoring metadata; never runtime ownership",
@@ -314,6 +309,29 @@
         "module": {
           "description": "Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap",
           "type": "string"
+        },
+        "relay": {
+          "description": "Deploy-baked managed-relay credentials. NEVER hand-authored in source — written only into the staged manifest by `vgai deploy` and fetched at runtime by the standalone client",
+          "type": "object",
+          "properties": {
+            "signalingUrl": {
+              "description": "Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one",
+              "type": "string"
+            },
+            "accessToken": {
+              "type": "string",
+              "description": "Room-scoped managed-relay access token minted at `vgai deploy` and read by the standalone client (main.ts)"
+            },
+            "expiresAt": {
+              "type": "number",
+              "description": "Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed"
+            }
+          },
+          "required": [
+            "accessToken",
+            "expiresAt"
+          ],
+          "additionalProperties": false
         }
       },
       "required": [
@@ -352,12 +370,12 @@
       ]
     },
     "determinism": {
-      "description": "Seeded-RNG determinism contract (D15, docs/D15-DETERMINISM-DESIGN.md) — governs whether ctx.random is boot-seeded from a reproducible seed and whether the gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.",
+      "description": "Seeded-RNG determinism contract (D15) — governs whether ctx.random is boot-seeded from a reproducible seed and whether the gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.",
       "type": "object",
       "properties": {
         "seededRandom": {
           "type": "boolean",
-          "description": "Declares that ALL gameplay RNG in this project flows through ctx.random (the named-stream seeded PRNG, docs/D15-DETERMINISM-DESIGN.md) rather than raw Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: the boot-time seeding reader (mount-manifest.ts seeds ctx.random from defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay frame, never throws). Default false: an undeclared project gets no determinism contract at all (that IS the opt-out — no dead field, per the T4.1 policy)."
+          "description": "Declares that ALL gameplay RNG in this project flows through ctx.random (the named-stream seeded PRNG) rather than raw Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: the boot-time seeding reader (mount-manifest.ts seeds ctx.random from defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay frame, never throws). Default false: an undeclared project gets no determinism contract at all (that IS the opt-out — no dead field)."
         },
         "defaultSeed": {
           "description": "The seed ctx.random boots from when seededRandom is true, unless overridden by ?vgai-seed=<int> (the query param always wins over this manifest default) or an even higher-precedence explicit config value a host passes directly. Optional — omit to fall back to the runtime's own fixed default seed.",
@@ -385,7 +403,7 @@
           "exclusiveMinimum": 0
         },
         "maxEntities": {
-          "description": "Maximum allowed entity-tagged scene-graph nodes (nodes carrying userData.entityId) summed across the game's threejs/pixijs worlds at the end of a `vgai perf` run. Exact and deterministic under a seed — no tolerance band.",
+          "description": "Maximum allowed entity-tagged scene-graph nodes (nodes carrying userData.entityId) summed across the game's three/canvas worlds at the end of a `vgai perf` run. Exact and deterministic under a seed — no tolerance band.",
           "type": "integer",
           "minimum": 0,
           "maximum": 9007199254740991
@@ -476,5 +494,5 @@
     "roots"
   ],
   "additionalProperties": false,
-  "description": "Game manifest (vgai.game.json) — the complete v2 project configuration"
+  "description": "Game manifest (vgai.project.json) — the complete v2 project configuration"
 }

package/src/adapter/adapter-surface.ts

@@ -1,16 +1,16 @@
 /**
  * `AdapterSurface` — the kinds of render surface a world can be (T7.1/T7.3/T6.2).
  *
- * Moved here (T7.5, `docs/BACKBONE-TASKS.md`'s D6 row) from `runtime/game.ts`
- * so `adapter/game-adapter.ts`'s kind-tagged `MountedWorld` types can name it
+ * Moved here from `runtime/game.ts`
+ * so `adapter/root-adapter.ts`'s kind-tagged `MountedRoot` types can name it
  * without a value-level import cycle (`runtime/game.ts` type-imports from
- * `adapter/game-adapter.ts` already). This is a leaf module — it imports
+ * `adapter/root-adapter.ts` already). This is a leaf module — it imports
  * nothing — so anything may import it with zero risk of a cycle.
  * `runtime/game.ts` re-exports this SAME type (`export type { AdapterSurface }`),
  * so no existing `import type { AdapterSurface } from '../runtime/game'` call site
  * needed to change.
  */
-export type AdapterSurface = 'threejs' | 'pixijs' | 'react';
+export type AdapterSurface = 'three' | 'canvas' | 'dom';
 
 /**
  * Exhaustiveness guard for `AdapterSurface` dispatch (v4 architecture-review
@@ -19,7 +19,7 @@ export type AdapterSurface = 'threejs' | 'pixijs' | 'react';
  * kind). Lives here — colocated with the kind vocabulary itself, not in a
  * generic util module — so the three call sites that need it
  * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
- * `resolveAllWorlds`, `editor/play-mode.ts`'s `installMultiWorldAuthoring`)
+ * `resolveAllRoots`, `editor/play-mode.ts`'s `installMultiRootAuthoring`)
  * import it from the same leaf module that defines `AdapterSurface`, keeping the
  * type and its guard from drifting apart. The `never` parameter is the
  * compile-time half of the guard (TS refuses to call this with anything the