@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/README.md

@@ -13,25 +13,58 @@ and the world2d PixiJS stack.
 **License: Apache-2.0** (see [LICENSE](./LICENSE)). Your game code that
 imports this package carries no copyleft obligations.
 
-## How it's consumed
+## Create a complete VGAI game project
 
-This package is **not yet published to npm**. A project scaffolded with
-`create-vgai-project` consumes the engine as **source**, via a vendored
-`file:` dependency plus `@engine/*` path aliases back into the checkout you
-scaffolded from. That is deliberate: the engine is meant to be read,
-stepped through, and understood — not treated as a black box. (Editing it
-edits the shared checkout for every project scaffolded from it; a game
-that needs a divergent engine forks the checkout.)
+If you want the editor, project manifest, validation, agent guidance, and
+working starter together, use the public CLI instead of assembling packages
+by hand:
+
+```bash
+npx @vgai/cli@latest create my-game
+```
+
+The command creates a standalone project, installs its versioned VGAI
+dependencies, and opens the visual editor.
+
+## Use the engine directly
+
+Install the engine in a TypeScript-aware project:
+
+```bash
+npm install @vgai/engine
+```
+
+The bare package exposes the small game/setup surface:
+
+```ts
+import {
+  GameComponent,
+  fromSetup,
+  loadGameManifest,
+  mountManifestWorlds,
+  type GameContext,
+} from '@vgai/engine';
+```
+
+Most engine APIs use readable source subpaths, for example
+`@vgai/engine/animation/xstate-animation-binding`. The package deliberately
+ships `src/`, generated schemas, and build output. Vite and TypeScript can
+read and step through the same source a generated game uses; publishing the
+package does not turn the engine into a black box.
+
+Node.js 22 or newer is required. React and ReactDOM are optional peers needed
+only for React adapter roots; `@vgai/editor-sdk` is optional when no editor
+control integration is used.
 
 ## Orientation
 
-- Read the repo-root [ARCHITECTURE.md](../../ARCHITECTURE.md) first — the
-  target architecture (universal host, adapter layer) and what's built,
-  honestly marked.
+- 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
+  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`.
-- The adapter contracts: `src/adapter/` +
-  [docs/ADAPTER-AUTHORING-GUIDE.md](../../docs/ADAPTER-AUTHORING-GUIDE.md).
-- Tests are headless with real dependencies (real Rapier WASM, real
-  Three.js graphs): `npm run test:unit` from the repo root.
+- 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,10 +2,11 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.1",
+  "version": "0.5.0-canary.20260719.0",
+  "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
+  "keywords": ["game-engine", "three.js", "pixijs", "react", "ai-agents"],
   "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",
+  "homepage": "https://vgai-learn.pages.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/volter-ai/vgai-engine.git",
@@ -14,21 +15,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "vgai": {
-    "tools": [
-      {
-        "entry": "./tools/humanoid-bake.tool.ts",
-        "contributions": [
-          {
-            "id": "humanoid-builder",
-            "point": "workspace.document",
-            "title": "Humanoid Builder",
-            "entry": "./src/react/humanoid-bake.document.tsx"
-          }
-        ]
-      }
-    ]
-  },
   "exports": {
     ".": "./src/index.ts",
     "./package.json": "./package.json",
@@ -36,9 +22,9 @@
   },
   "files": [
     "src",
-    "tools",
     "dist",
-    "schemas"
+    "schemas",
+    "vendor"
   ],
   "engines": {
     "node": ">=22.0.0"
@@ -48,18 +34,18 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "^0.14.0",
-    "@pixi/tilemap": "^5.0.0",
     "@dimforge/rapier3d-compat": "^0.14.0",
+    "@pixi/tilemap": "^5.0.0",
     "@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",
     "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": "^0.180.0",
     "three.quarks": "^0.16.0",
     "tone": "^15.1.22",
     "xstate": "^5.32.4",

package/schemas/engine-capabilities.json

@@ -2,7 +2,7 @@
   "$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",
+  "schemaDirHash": "d092efe0ed1fffc07d8a759d16deecb978f89b0386e2a375243804e84f7e74e5",
   "reviewedAt": "2026-07-01",
   "entries": [
     {
@@ -12,12 +12,12 @@
       "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)"
+        "packages/engine/src/world2d/scene2d-loader.ts:168-179 (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"
+        "packages/engine/src/scene/scene-loader.ts": "53c8f6d756363c0638c576b7e5a3d425fe0e77ce929dac9d462b8999b7000db8",
+        "packages/engine/src/world2d/scene2d-loader.ts": "f0f74eefd9cce16bbe7826225a52f2b0407ab141641dcdd370bcff1d091bce69"
       }
     },
     {
@@ -32,7 +32,7 @@
       "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"
+        "packages/engine/src/scene/scene-loader.ts": "53c8f6d756363c0638c576b7e5a3d425fe0e77ce929dac9d462b8999b7000db8"
       }
     },
     {
@@ -46,8 +46,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": "361c2618f5a55ecd8ec6b59689a9ab2a92590d86a694d33d21e825f250675ca0",
-        "packages/engine/src/input/input-manager.ts": "15dc63f60713a6f4087d4e761b5da178555984e939328bb40bf271d9ec76ee30"
+        "packages/engine/src/input/input-types.ts": "d6c7a6d1eda6b71665407fd5ac35d414dccf4156d4f79c56671b07e0a60b7f7c",
+        "packages/engine/src/input/input-manager.ts": "f3c2683397ed36eeb34ffd54861d14e4c0675bc7fbaef5530e7552a1edd129d4"
       }
     },
     {
@@ -62,7 +62,7 @@
       "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"
+        "packages/engine/src/animation/xstate-animation-binding.ts": "34e94a7db674ea3d8a98cf98359a9ba8cdd2af9266d1e857a6ad5df02d5a5f73"
       }
     },
     {
@@ -91,7 +91,7 @@
       ],
       "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"
+        "docs/BACKBONE-TASKS.md": "206ce2818efcf2b12876160d7366d41a6afec6b545b025a98a3fcf2915cdf824"
       }
     },
     {
@@ -104,7 +104,7 @@
       ],
       "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"
+        "docs/BACKBONE-TASKS.md": "206ce2818efcf2b12876160d7366d41a6afec6b545b025a98a3fcf2915cdf824"
       }
     },
     {