Quick start

Install one package, check it with the example game that ships inside it, then write your first quantum code.

Coming from 2.x?

These docs cover quantum-forge 3.0, where each quantum property is a handle you call gates on. QuantumPropertyManager still works through 3.x but is deprecated. Migrating to 3.0 maps every 2.x call to its 3.0 form.

Prerequisites

• Node.js 22 or newer

Install

npm install quantum-forge

That is the whole SDK: the WASM quantum simulator, the quantum() handle API, and a Vite plugin. It has no runtime dependencies and works with any renderer or game engine.

Check your install with Quantum Pong

Quantum Pong ships inside quantum-forge. It draws with the plain Canvas 2D API and uses nothing but the core package, so if it runs, your install works:

npx quantum-forge example my-pong
cd my-pong
npm run dev    # play it in the browser
npm test       # play it headless against the same WASM

example copies the game into my-pong and runs npm install. Pass --no-install to skip the install. The command arrived in core 3.1.0. On an older core, run npm install quantum-forge@latest first.

A ball that enters one of the boxes on the top and bottom walls splits into two entangled halves, and only one of them is real. A half that reaches a goal is measured: it scores or vanishes as a ghost, and its partner collapses in the same step. Every quantum call the game makes is in logic/QuantumRegistry.ts. See Quantum Pong for how it works.

Add it to your project

Add the Vite plugin, which serves the WASM during development:

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

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

The package is ESM-only. Name the file vite.config.ts or vite.config.mjs, or add "type": "module" to your package.json. Tests, servers and other Node code need no plugin: see Node and headless use.

Your first quantum code

Here's the core pattern: declare a quantum property, put it in superposition, then collapse it.

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

await ensureLoaded(); // once, before the first quantum() call

const alive = quantum([false, true]); // a qubit, starts false
alive.superpose();                    // the same gate as hadamard(): 50/50

// Read without collapsing
alive.probability(true);              // 0.5

// Collapse to a definite value
const value = alive.measure();        // false or true
console.log(value ? "exists!" : "gone!");

// End its life when the thing it describes is gone
alive.dispose();

A property is declared by the values it can take, and it starts at the first one. quantum(["red", "green", "blue"]) is a qutrit, and quantum(3) is the numeric form with values 0, 1, 2. Gates are methods on the handle and chain, so quantum([false, true]).superpose() works in one line.

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

Optional: quantum-forge-engine

quantum-forge-engine bundles quantum-forge with extras that are handy for web games: an Engine state class, PixiJS rendering, input, audio, collision, particles, and a project scaffolder. You don't need it to use Quantum Forge. If you want it:

npx quantum-forge-engine init my-game

See Framework Tools and the CLI for what it adds.

Next steps

• Why Quantum?: what makes quantum different from Math.random()
• Core Concepts: properties, gates, predicates, measurement
• Quantum Setup: loading, editions, Node and headless use
• First Quantum Game: a step-by-step tutorial built on the engine
• AI Agents: machine-readable docs, headless setup, and the Claude Code skill