Install & set up a project

You need Node.js 22+ and npm. VGAI targets modern browsers with WebGL2.

A game built with vgai is a standalone project — its own folder — that you scaffold with the vgai CLI and then author in the visual editor. It does not belong inside the VGAI engine repository or its examples/ directory. The generated project installs versioned public packages while keeping engine TypeScript readable in node_modules/@vgai/engine/src.

Create and open the project

1. From the directory that should contain your new game, run:

   npx @vgai/cli@latest create my-game

2. The command creates and installs ./my-game, starts its visual editor, and prints the exact editor URL. Leave it running while you or an agent builds.
3. Later, reopen the same project with:

   cd my-game
   npm run dev

No global install or engine checkout is required. For repeated use, installing @vgai/cli globally is optional.

Scaffold a project

npx @vgai/cli@latest create my-game                  # Three.js + React roots
npx @vgai/cli@latest create my-game --template 2d    # PixiJS + React roots
npx @vgai/cli@latest create my-game --template react # React-only
npx @vgai/cli@latest create my-game --example fps    # editable example copy

Use --no-edit only for automation where no person may be watching. The single public create command is npx @vgai/cli@latest create; add --no-edit when a scripted workflow deliberately does not need an editor session.

Templates

Template	Contents
default	A Three.js scene root plus a React UI root.
2d	A PixiJS scene root plus a React UI root.
react	A React-only game, ideal for DOM games.

Build with an agent

1. Open Claude Code, Codex, Copilot, Cursor, or another coding agent in the generated game folder and describe the outcome once.
2. The project includes compact AGENTS.md/CLAUDE.md instructions, progressively loaded skills, and .mcp.json. Compatible hosts can start the project-scoped VGAI MCP server without a separate plugin install.
3. The agent should keep the matching editor visible, enter Play, check status/logs, and capture evidence before claiming the game works.

To start the MCP server manually from the project folder:

npx @vgai/cli@latest mcp .

Continue without an agent

The same editor remains the normal authoring surface:

1. Launch or reuse it:

   npm run dev

2. Use the viewport, hierarchy, inspector, and Play mode. The printed URL is authoritative because VGAI may choose another port when one is occupied.
3. A connected Play acknowledgement plus a rendered frame verifies the starter.

Authoring versus player view

npm run dev opens the editor for the current project. Use npm run game only when you explicitly need the standalone player view for bots or CI.

Multiplayer is separate

Neither npm run vgai -- edit nor npm run dev starts a Colyseus server. Run npm run server from the project folder to boot Colyseus (port 2567) alongside it; the Multiplayer section has the details.

Useful commands

Command	What it does
npm run dev	Launch or reuse the visual editor for this project.
npm run game	Run the standalone player page, without the editor.
npx @vgai/cli@latest examples	List scaffoldable example projects.
npx @vgai/cli@latest edit [project]	Launch the editor on an explicit project from outside it.
npm run vgai -- play / npm run vgai -- stop	Drive Play mode from a generated project.
npx @vgai/cli@latest inspect <folder>	Detect an existing web game with no writes.
npx @vgai/cli@latest adapt <folder>	Preview VGAI metadata; add --write only after review.
npm run build	Type-check + production build.
npm run typecheck	Type-check game and server code.
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.