CLI Tools

The framework includes CLI tools for scaffolding new projects, adding systems, validating architecture, and diagnosing issues.

init

Scaffold a new game project:

npx quantum-forge init my-game                         # interactive prompts
npx quantum-forge init my-game --template starter       # starter template
npx quantum-forge init my-game --template quantum-pong  # full example
npx quantum-forge init my-game --edition qubit          # qubit edition (20 qubits)
npx quantum-forge init my-game --edition qutrit         # qutrit edition (default)
npx quantum-forge my-game                               # shorthand (no "init")
npx quantum-forge                                       # fully interactive

Editions

The init flow prompts you to select an edition, which 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

Skip the prompt with --edition qubit or --edition qutrit.

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

Templates

Starter (default): Minimal game with movable player circle. 12 generated files: package.json, vite.config.ts, engine, renderer, logic, tests, CLAUDE.md.

Quantum Pong: Full working game with quantum mechanics, audio, AI opponent, and 75 tests. 17 generated files including QuantumRegistry, PongLogic, audio assets.

What It Does

1. Validates project name
2. Prompts for template and edition selection (if not provided via flags)
3. Creates project directory and generates all files
4. Runs npm install (triggers framework's prepare script)
5. Initializes git repository with initial commit

add-system

Add optional packages to an existing game:

npm run add-system

Interactive selection from available 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
Audio Manager	Web Audio API wrapper for sounds and music
Particle System	Visual effects with burst, trail, continuous modes
Animation System	Tweening with easing functions

Creates src/systems-integration.ts with imports and usage examples.

validate

Check that a game follows architectural best practices:

npm run validate [path]

Checks

1. Project Structure: required files present (main.ts, index.html, engine/)
2. Engine Pattern: engine extends base Engine class
3. Pure Functions: no timing/animation code in engine
4. Console Usage: uses logger instead of console.*
5. Quantum Integration: Quantum Forge properly initialized
6. TypeScript Config: path aliases configured

Score

• 100%: Perfect architecture
• 70-99%: Good, minor issues
• < 70%: Needs refactoring

Use in CI:

npm run validate || exit 1

doctor

Diagnose environment issues:

npm run doctor

Checks Node.js version, WASM build status, dependencies, and framework configuration.

Common Workflows

Start a new game:

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

Add features incrementally:

npm run add-system    # add audio, particles, etc.
npm run validate      # check architecture

Diagnose problems:

npm run doctor        # check everything