Quick Start

Get a quantum game running in under 5 minutes.

Prerequisites

• Node.js 18+
• Git

Create a Project

Option 1: CLI Scaffold (Recommended)

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

The CLI creates a complete project with Quantum Forge configured, Vite dev server, and a working quantum game.

Edition: The init flow prompts you to choose an 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)

You can also pass --edition qubit or --edition qutrit to skip the prompt. See Quantum Setup for details on how editions affect your project.

Template: Choose from:

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

Option 2: Add to 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