Install & set up a project

You need Node.js 18+ and npm. vgai targets modern browsers with WebGL2.

Scaffold a project

create-vgai-project

npx create-vgai-project my-game
cd my-game

The scaffolder copies the starter template (the full example project) — or pass a flag for a minimal empty template — rewrites package.json, tsconfig.json, vite.config.ts, and project.json for your project name, and runs npm install for you.

vgai CLI

npm i -g @vgai/cli      # or: npm link from packages/vgai-cli
vgai create my-game --template starter

The CLI’s create command scaffolds the same project and can also drive a running editor (open scenes, start/stop play mode, focus entities, toggle panels). See Tooling & Publishing.

Templates

Template	Contents
starter (default)	The full template project: example games, shared UI, a Colyseus server. The fastest way to learn by reading working code.
empty	Minimal: one .vscn.json, a src/main.ts, and base config. For starting clean.

Run the editor

1. From your project directory, start the dev server:

   npm run dev

2. Open the editor at http://localhost:5173.
3. You should see the 3D viewport with the default scene. If it loads, your toolchain is working.

Multiplayer is separate

npm run dev does not start a Colyseus server — it’s a single-port editor dev server. The room bootstrap (server/colyseus-setup.ts, port 2567) is launched separately; the Multiplayer section shows how.

Useful commands

Command	What it does
npm run dev	Editor dev server on http://localhost:5173.
npm run build	Type-check + production build.
npm run typecheck	Type-check engine, editor, and server code.
npm run test:unit	Vitest unit tests.
npm run test:e2e	Playwright end-to-end suite.
npm run validate-scenes	Validate .vscn.json files against the component registry.

Next

• First look at the editor — a tour of the UI.
• Foundations — write your first GameComponent.