CLI tools

The CLI ships in the engine package (quantum-forge-engine) and covers scaffolding, adding systems, validating architecture, and diagnosing the environment.

Every command below goes through quantum-forge-engine. From core 2.7.0 the core package also carries a quantum-forge command that hands every argument to the engine CLI, so npx quantum-forge <command> is a synonym. On older core releases that spelling fails with "could not determine executable to run", because the core package had no executable.

init

Scaffold a new game project:

npx quantum-forge-engine init my-game                         # prompts for the rest
npx quantum-forge-engine init my-game --template starter      # starter template
npx quantum-forge-engine init my-game --template quantum-pong # full example
npx quantum-forge-engine init my-game --edition qubit         # qubit edition (20 qubits)
npx quantum-forge-engine init my-game --platforms web,desktop # add an Electron target
npx quantum-forge-engine init                                 # prompts for everything

The init keyword is optional, so npx quantum-forge-engine my-game also works. Spell it out anyway. The same bin serves the other subcommands, and an explicit init keeps the intent unambiguous.

Flags

Flag	Values	Default
--template	starter, quantum-pong	starter
--edition	qutrit, qubit	qutrit
--platforms	comma-separated web, desktop, ios, android	web
--claude-skill	install the /quantum-forge skill for Claude Code	prompts
--no-claude-skill	skip the skill	prompts
--no-install	write the project without running npm install; the Claude skill needs node_modules, so it is skipped too	installs

web is always included, so --platforms desktop produces a web plus desktop project. Desktop targets go through Electron, iOS and Android through Capacitor.

Anything you leave off becomes a prompt: project name, template, platforms, edition, and the Claude Code skill.

Non-interactive

Pass every flag and nothing prompts, which is what CI and AI agents need:

npx -y quantum-forge-engine init my-game \
  --template starter --platforms web --edition qutrit --no-claude-skill

Editions

The edition determines the WASM build variant bundled with your project:

Edition	Dimensions	Max Qudits	Trade-off
Qutrit (default)	2–3	12	Supports qutrits (3-state properties) but fewer total qudits
Qubit	2 only	20	More quantum objects, but locked to binary states

The Qubit edition generates code that calls useQuantumForgeBuild("qubit") before ensureLoaded() to load the qubit-optimized variant. The Qutrit edition uses the default build and needs no extra configuration. See Quantum Setup: Editions for runtime details.

Templates

Starter (default): a minimal game with a movable player circle. You get package.json, tsconfig.json, vite.config.ts (dev server on port 3000, WASM plugin, vitest config), index.html, and a src/ tree split into pure logic, an Engine subclass, a PixiJS renderer, a controller in main.ts, and a vitest file. From quantum-forge-engine 1.3.0 the scaffold also writes CLAUDE.md and AGENTS.md so coding agents pick up the project conventions.

Quantum Pong: a complete working game with quantum mechanics, audio, an AI opponent, and 75 tests. Adds a QuantumRegistry, pure pong logic, and bundled audio assets on top of the same skeleton.

What it does

1. Validates the project name
2. Prompts for anything not passed as a flag
3. Creates the project directory and generates the files
4. Runs npm install
5. Installs the Claude Code skill, if you asked for it
6. Initializes a git repository with an initial commit

add-system

Requires quantum-forge-engine 1.3.0 or later

add-system, validate, and doctor became subcommands of the engine bin in 1.3.0. On earlier versions they were monorepo-only scripts and cannot be run from a scaffolded project at all. Scaffolded projects have no npm run add-system script, so use the npx form.

Add optional packages to an existing game:

npx quantum-forge-engine add-system

Interactive selection from ten systems:

System	Description
Entity Manager	Entity tracking with spatial queries, tagging, lifecycle
Input Manager	Keyboard, mouse, touch, gamepad with action mapping
Collision Detection	AABB, circle, point collision with spatial grid optimization
Audio Manager	Web Audio API wrapper for sounds and music
Particle System	Visual effects with burst, trail, and continuous modes
Animation System	Tweening with easing functions, multi-value animation
State Machine	Generic FSM for AI behavior, game phases, menu flows
Timer Manager	Game-aware timers with time scaling and pause/resume
Save Manager	Save/load state with versioning, migration, and auto-save
Scene Manager	Stack-based scene lifecycle with transitions

Writes src/systems-integration.ts with the imports and usage examples for whatever you picked.

validate

Check that a game follows the framework's architectural patterns:

npx quantum-forge-engine validate [path]

Checks

1. Project structure: required files present (main.ts, index.html, engine/)
2. Engine pattern: engine extends the base Engine class
3. Pure functions: no timing or animation code in the engine
4. Console usage: uses the logger instead of console.*
5. Quantum integration: Quantum Forge initialized properly
6. TypeScript config: path aliases configured

Score

• 100%: perfect architecture
• 70-99%: good, minor issues
• < 70%: needs refactoring

Use in CI:

npx quantum-forge-engine validate || exit 1

doctor

Diagnose environment issues:

npx quantum-forge-engine doctor

Checks Node.js, npm, git, and TypeScript versions, whether the Quantum Forge packages and their dependencies are installed, whether the WASM artifacts and built libraries are present, and whether port 3000 is free.

Common workflows

Start a new game:

npx quantum-forge-engine init my-game
cd my-game
npm run dev

Add features as you go:

npx quantum-forge-engine add-system   # audio, particles, and the rest
npx quantum-forge-engine validate     # check architecture

Diagnose problems:

npx quantum-forge-engine doctor