@vgai/engine

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 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 serialized scene file or schema for one; TSX scene composition modules remain ordinary source, and the manifest schema is strict, so an unrecognized key is rejected loudly rather than ignored.

License: Apache-2.0 (see LICENSE). Your game code that imports this package carries no copyleft obligations.

Create a complete VGAI game project

If you want the editor, project manifest, validation, agent guidance, and working starter together, use the public CLI instead of assembling packages by hand:

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:

npm install @vgai/engine

The bare package exposes the small manifest/mount surface:

import {
  loadGameManifest,
  mountManifestRoots,
  type GameSession,
} from '@vgai/engine';

Game source itself stays ecosystem-native (R3F/Pixi/React with their own hooks and schedulers); vgai.project.json and vgai.adapter.ts are the boundary that adapts it — world components never import a vgai runtime API.

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

• Public Learn/manual: https://vgai-learn.pages.dev
• Hosted editor: https://vgai-editor.pages.dev
• In a source checkout, read docs/ARCHITECTURE-CORE.md first—the target architecture and current implementation are marked separately.
• Schemas, in two homes (every field .describe()d; npm run generate-schema emits JSON Schema for autocomplete): src/asset-formats/ (runtime descriptors for materials, meshes, lights, cameras, colliders, particles, and render settings), and src/manifest/schema.ts (vgai.project.json). Input maps own their schema under src/input/; models and materials persist in glTF or source.
• The adapter contracts: src/adapter/.
• Source-checkout tests are headless with real dependencies: npm run test:unit from the repository root.