Quick Start

Get a quantum game running in under 5 minutes.

Prerequisites

• Node.js 22 or newer
• Git

Create a project

Option 1: CLI scaffold (recommended)

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

The CLI ships in the engine package. npx quantum-forge init my-game works too from core 2.7.0 onward: the core package carries a quantum-forge command that hands off to the engine. Older core releases have no executable, so on them that spelling fails with "could not determine executable to run".

The scaffold writes a complete project: Vite config with the WASM plugin, an Engine subclass, a renderer, pure logic modules, tests, and a working game loop.

Anything you don't pass as a flag becomes a prompt: project name, template, platforms, edition, and whether to install the Claude Code skill.

Flag	Values	Default
--template	starter, quantum-pong	starter
--edition	qutrit, qubit	qutrit
--platforms	web, desktop, ios, android (comma-separated)	web
--claude-skill / --no-claude-skill	installs /quantum-forge for Claude Code	prompts
--no-install	write the project without running npm install	installs

web is always included, so --platforms desktop means web plus desktop.

Edition:

Edition	Dimensions	Max Qudits	Best For
Qutrit (default)	2–3	12	Games using three-valued quantum states (rock/paper/scissors, left/center/right)
Qubit	2 only	20	Games needing more quantum objects with binary states (exists/doesn't, alive/dead)

See Quantum Setup for how editions affect your project.

Template:

• Starter: minimal game loop with player movement, a renderer, and a test file
• Quantum Pong: full example with quantum mechanics, audio, AI opponent, and 75 tests

Non-interactive: pass every flag and the CLI never prompts. Use this in CI, in containers, or when an AI agent drives the scaffold.

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

Option 2: add to an existing project

npm install quantum-forge-engine
# → automatically installs quantum-forge (core) as a dependency

Then import by feature:

import { Engine } from "quantum-forge-engine/engine";
import { PixiRenderer, GameLoop } from "quantum-forge-engine/rendering";
import { QuantumPropertyManager, ensureLoaded } from "quantum-forge/quantum";

Vite configuration

Add the Quantum Forge Vite plugin to serve WASM during development:

// vite.config.ts
import { quantumForgeVitePlugin } from "quantum-forge/vite-plugin";

export default defineConfig({
  plugins: [quantumForgeVitePlugin()],
  build: {
    rollupOptions: {
      external: [/quantum-forge-web-api/],
    },
  },
});

The WASM module ships pre-built. Call await ensureLoaded() before quantum operations. See Quantum Setup for details.

Your first quantum code

Here's the core pattern: give a game object quantum state, then collapse it.

import { QuantumPropertyManager, ensureLoaded } from "quantum-forge/quantum";

await ensureLoaded();

const manager = new QuantumPropertyManager({ dimension: 2 });
const prop = manager.acquireProperty();     // starts in |0⟩
const m = manager.getModule();

m.cycle(prop);                              // |0⟩ → |1⟩ (exists)
m.hadamard(prop);                           // → 50/50 superposition

// Read probability without collapsing
const probs = m.probabilities([prop]);      // ~50% each

// Collapse to a definite value
const [value] = m.measure_properties([prop]); // 0 or 1
console.log(value === 1 ? "exists!" : "gone!");

This isn't Math.random(). The WASM module maintains a real quantum state vector, applies unitary gates, and performs projective measurement.

Verify

npm run dev

Open http://localhost:3000. If you see the starter game running, Quantum Forge is configured and ready.

Next steps

• Why Quantum?: what makes quantum different from Math.random()
• First Quantum Game: step-by-step tutorial building a full quantum game
• Core Concepts: properties, operations, predicates, measurement
• AI Agents: machine-readable docs, headless setup, and the Claude Code skill