@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/README.md

@@ -4,7 +4,9 @@ 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
-(mixer + `AnimGraph` state machines), audio, input, the adapter seam
+(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.
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.2.0",
+  "version": "0.4.0-canary.20260715.0",
   "type": "module",
   "description": "The vgai game engine — core loop, GameComponent model, physics, scene loader, adapter seam.",
   "homepage": "https://github.com/volter-ai/vgai-engine#readme",
@@ -14,12 +14,24 @@
   "publishConfig": {
     "access": "public"
   },
+  "vgai": {
+    "operations": [
+      "./src/humanoid/bake.operation.ts"
+    ]
+  },
   "exports": {
     ".": "./src/index.ts",
     "./package.json": "./package.json",
     "./*": "./src/*"
   },
-  "files": ["src", "dist"],
+  "files": [
+    "src",
+    "dist",
+    "schemas"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json"
   },
@@ -34,8 +46,12 @@
     "postprocessing": "^6.38.0",
     "realism-effects": "^1.1.2",
     "recast-navigation": "^0.43.0",
+    "@theatre/core": "0.7.2",
+    "gsap": "^3.12.0",
     "three": "^0.170.0",
     "three.quarks": "^0.16.0",
+    "tone": "^15.1.22",
+    "xstate": "^5.32.4",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
@@ -43,8 +59,12 @@
     "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "react-dom": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/react": "^19.2.14",

package/schemas/engine-api.json

@@ -0,0 +1,124 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-engine-manifest.ts — do not edit manually. Run 'npm run generate-engine-manifest'.",
+  "phases": [
+    {
+      "name": "input",
+      "description": "Sample input devices (keyboard, mouse, gamepad) at the top of the frame."
+    },
+    {
+      "name": "prePhysics",
+      "description": "Apply forces/intents to rigid bodies before the physics step."
+    },
+    {
+      "name": "physics",
+      "description": "Step the Rapier physics world (fixed timestep)."
+    },
+    {
+      "name": "postPhysics",
+      "description": "Read physics results back; sync transforms from bodies to Object3D."
+    },
+    {
+      "name": "gameLogic",
+      "description": "General gameplay behavior. Default phase for GameComponents."
+    },
+    {
+      "name": "animation",
+      "description": "Advance animation graphs / mixers."
+    },
+    {
+      "name": "preRender",
+      "description": "Final per-frame fixups (cameras, HUD state) before drawing."
+    },
+    {
+      "name": "render",
+      "description": "Draw the frame."
+    }
+  ],
+  "phaseOrder": [
+    "input",
+    "prePhysics",
+    "physics",
+    "postPhysics",
+    "gameLogic",
+    "animation",
+    "preRender",
+    "render"
+  ],
+  "phaseConstants": {
+    "INPUT": "input",
+    "PRE_PHYSICS": "prePhysics",
+    "PHYSICS": "physics",
+    "POST_PHYSICS": "postPhysics",
+    "GAME_LOGIC": "gameLogic",
+    "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

@@ -0,0 +1,53 @@
+<!-- AUTO-GENERATED by scripts/generate-engine-manifest.ts — do not edit manually. -->
+<!-- Run 'npm run generate-engine-manifest' to regenerate. -->
+
+# Engine API Manifest
+
+The schema-as-source-of-truth artifact for the engine's imperative surface — generated from the actual code so docs can never drift (see ROADMAP P0.3 / P2.9).
+
+## System Phases
+
+Each frame, systems run in this exact order (from `PHASE_ORDER` in `packages/engine/src/core/types.ts`):
+
+| # | Phase | Constant | Description |
+| - | ----- | -------- | ----------- |
+| 1 | `input` | `SystemPhase.INPUT` | Sample input devices (keyboard, mouse, gamepad) at the top of the frame. |
+| 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. |
+| 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

@@ -0,0 +1,124 @@
+{
+  "$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).",
+  "_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": "3530962568323eb7f0ea4aca8262c616d59fcc64c5fc5a171e4066f672bb77e1",
+  "reviewedAt": "2026-07-01",
+  "entries": [
+    {
+      "id": "physics-no-ccd",
+      "area": "physics",
+      "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:144-154 (2D bodyDesc: same four stock constructors)"
+      ],
+      "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.",
+      "evidenceHashes": {
+        "packages/engine/src/scene/scene-loader.ts": "58ed692dc8bc71ab40839ff5ab48f392f90839734262da2a96bedddc81af09b5",
+        "packages/engine/src/world2d/scene2d-loader.ts": "125f51fd58d6a7912a22c9b8a78f280c59f1a9c035343faf1d266ee81efaa9a6"
+      }
+    },
+    {
+      "id": "physics-no-enforced-envelope",
+      "area": "physics",
+      "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)"
+      ],
+      "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": "58ed692dc8bc71ab40839ff5ab48f392f90839734262da2a96bedddc81af09b5"
+      }
+    },
+    {
+      "id": "input-value-model",
+      "area": "input",
+      "status": "supported-with-caveats",
+      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
+      "evidence": [
+        "packages/engine/src/input/input-types.ts:2-40 (InputBinding union incl. mouse_move/gamepad_axis_pair/touch_button/touch_stick/test_*)",
+        "packages/engine/src/input/input-manager.ts:609-1905 (digital/gating/typed getters/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt)"
+      ],
+      "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": "361c2618f5a55ecd8ec6b59689a9ab2a92590d86a694d33d21e825f250675ca0",
+        "packages/engine/src/input/input-manager.ts": "15dc63f60713a6f4087d4e761b5da178555984e939328bb40bf271d9ec76ee30"
+      }
+    },
+    {
+      "id": "animation-masked-layers",
+      "area": "animation",
+      "status": "supported",
+      "claim": "A native XState machine can drive multiple simultaneous named AnimationMixer layers through parallel regions. Layers support 0..1 weights, normal or additive Three.js blending, and include/exclude masks over named bone/Object3D subtrees.",
+      "evidence": [
+        "packages/engine/src/animation/xstate-animation-meta.ts (strict layer, weight, blendMode, and boneMask metadata schemas)",
+        "packages/engine/src/animation/xstate-animation-binding.ts (parallel-region reconciliation, subtree track filtering, and native additive composition)"
+      ],
+      "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": "bfccffe15e265fa2d3843dfaad0d3f1b6a7227a23742efa1f0e11182c8efc33a"
+      }
+    },
+    {
+      "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"
+      }
+    },
+    {
+      "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.",
+      "evidence": [
+        "docs/BACKBONE-TASKS.md:389-414"
+      ],
+      "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.",
+      "evidenceHashes": {
+        "docs/BACKBONE-TASKS.md": "0a39f9539731af1de5440aa53ad92d463b809fd7458edb7e34df5dac71e911ac"
+      }
+    },
+    {
+      "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).",
+      "evidence": [
+        "docs/BACKBONE-TASKS.md:415-435 (Track N, N0-N4 all done)"
+      ],
+      "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.",
+      "evidenceHashes": {
+        "docs/BACKBONE-TASKS.md": "0a39f9539731af1de5440aa53ad92d463b809fd7458edb7e34df5dac71e911ac"
+      }
+    },
+    {
+      "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.",
+      "evidence": [
+        "packages/engine/schemas/engine-api.json (auto-generated positive/imperative-surface manifest beside this file)"
+      ],
+      "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"
+      }
+    }
+  ]
+}