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 template prompt
npx quantum-forge init my-game --template starter       # starter template
npx quantum-forge init my-game --template quantum-pong  # full example
npx quantum-forge my-game                               # shorthand (no "init")
npx quantum-forge                                       # fully interactive

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 and checks GitHub Packages authentication
2. Prompts for template selection (if --template not provided)
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, Emscripten availability, 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