Skip to content
vgai Learn

CLI, SDK & scaffolding

Scaffolding new projects

Section titled “Scaffolding new projects”

The one public entry point is @vgai/cli. Its create command copies the selected adapter-root template, rewrites package.json, tsconfig.json, vite.config.ts, and vgai.game.json, installs dependencies, and opens the new project’s editor. Pass --example <id> to copy a worked game instead.

Terminal window
npx @vgai/cli@latest create my-game [target-dir]

Choose the root composition explicitly when the default Three.js + React project is not what you want:

Terminal window
npx @vgai/cli@latest create my-game --template 2d    # PixiJS + React
npx @vgai/cli@latest create my-game --template react # React only

Driving the editor: the CLI

Section titled “Driving the editor: the CLI”

The vgai CLI (packages/vgai-cli/src/index.ts) controls a running editor — useful for scripting and automation:

The CLI and editor SDK drive a running editor over REST and SSE
The CLI/SDK talk to the editor over /__editor/* (REST + SSE).
AreaCommands
Projectcreate, edit, open, project, projects, upgrade, validate, deploy (vgai <folder>, e.g. vgai ., is shorthand for edit <folder>)
Scenescene <path>, open-asset <path> <kind>, apply-diff <scene> <patch> [--report]
Playplay, stop, pause, resume, step
Navigateselect <id> | --all, focus [id], view <top|front|right|perspective>
Panels/displayshow <viewport|inspector|console|build>, grid, helpers, stats, shading
Statestatus

Under the hood it talks to the editor’s /__editor/* routes (REST + SSE), defaulting to http://localhost:5173 (override with VGAI_EDITOR_URL; the default port also honors VGAI_EDITOR_PORT — the same variable the dev server reads).

Three commands work on the filesystem instead of a running editor. npm run vgai -- apply-diff <scene.vscn.json> <patch.json> [--report] (T4.5) is the canonical programmatic edit op: it applies a JSON SceneDiff patch (add/remove/update/move ops + environment/name) to a scene file, validating the scene, the patch, and the result through the engine’s Zod schemas — plus dereferencing every asset reference the patch introduces (the file must exist; .mat/prefab refs must also content-parse) — nothing is written on any failure, and --report validates + summarizes without writing at all. Prefer it over hand-editing .vscn JSON in scripts. npm run vgai -- upgrade [folder] re-syncs a scaffolded project after you update the vgai checkout (the engine is source-linked, so engine code updates arrive instantly — upgrade handles the copied half: template files and the manifest’s engine.version pin). It always reports first (pin delta, per-file classification against the scaffold baseline, validation), updates only files you never edited, shows diffs for the ones you did, and re-pins only when validation passes — and if the project’s pin is ahead of the checkout’s engine (a wrong-worktree tell), it refuses rather than silently downgrading, unless you pass --force-downgrade. --report for report-only. Both verbs in depth: Project lifecycle. vgai validate [folder] checks a manifest in-process — no monorepo/editor/Vite needed beyond the checkout: it validates vgai.game.json, confirms every declared entry/scene/entryHtml/bundleUrl file exists, and prints the engine pin (exit 0 valid, 1 invalid or missing file, 2 usage).

The editor SDK

Section titled “The editor SDK”

@vgai/editor-sdk (packages/editor-sdk/src/) is the TypeScript client the CLI uses — EditorClient with methods like openScene, play/stop/pause/resume/step, select, focusEntity, viewPreset, panel toggles, getState, and waitForState. Use it to build custom tooling.

See also

Section titled “See also”