Why Quantum?

Quantum Forge is not a random number generator. It is a compiled C++ quantum simulator running in WebAssembly that gives your game objects genuine quantum behavior — superposition, measurement collapse, entanglement, and interference. These mechanics create gameplay that is fundamentally impossible with classical randomness.

What Makes It Different from Math.random()

When you call Math.random(), you get an independent number with no memory and no connections to anything else. Quantum properties are different in three critical ways:

1. Superposition is stateful. A quantum property holds a full probability distribution that evolves as you apply gates. A Hadamard creates equal superposition; a phase rotation biases it without collapsing it. You can read probabilities without disturbing the state.

2. Measurement is irreversible. When you measure, the superposition collapses to a definite value. This is a one-way event that creates a dramatic game moment — the player's action forces reality to decide.

3. Entanglement creates correlations. Two entangled properties share a quantum state. Measuring one instantly determines the other, even if they represent game objects on opposite sides of the screen. No classical system does this.

Quick Primer for Game Devs

Superposition

A quantum property can be in multiple states at once. For a dimension-2 property (qubit), the two states are |0⟩ and |1⟩. A Hadamard gate puts it in equal superposition — 50% chance of each. You can read this probability without collapsing it, so you can render a "ghost" at half opacity.

Measurement

When you measure a property in superposition, it collapses to one definite value. The probability distribution determines the odds, but the outcome is genuinely quantum-random. After measurement, the property is in a definite state — no more superposition.

Entanglement

Use iSwap to link two properties. Now they share a quantum state. If you entangle a ball at |1⟩ (exists) with one at |0⟩ (doesn't exist), you get a superposition of "ball A exists, ball B doesn't" and "ball B exists, ball A doesn't." Measuring one instantly collapses the other.

Dimension Choice

The dimension parameter controls how many basis states each property has:

Dimension	States	Use Case
2	|0⟩, |1⟩	Binary states: exists/doesn't, alive/dead, left/right
4	|0⟩ – |3⟩	Four directions, four colors, four piece types
7	|0⟩ – |6⟩	Hex geometry — one state per neighbor direction
8	|0⟩ – |7⟩	Octagonal tiles, 8-directional movement

Higher dimensions give more states but grow the state space exponentially. Start with dimension 2 unless your game design specifically needs more.

Quick Taste

Here is a complete quantum interaction in 15 lines:

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

await ensureLoaded();

class GameRegistry extends QuantumPropertyManager {
  constructor() { super({ dimension: 2 }); }

  spawnQuantumEntity(id: string) {
    const prop = this.acquireProperty();
    this.cycle(prop);           // |0⟩ → |1⟩ (exists)
    this.hadamard(prop);        // → equal superposition
    this.setProperty(id, prop);
  }

  observe(id: string): number {
    const prop = this.getProperty(id)!;
    const [value] = this.measureProperties([prop]); // collapses!
    this.deleteProperty(id);
    this.releaseProperty(prop, value);               // pool for reuse
    return value; // 0 or 1
  }
}

This is not a simulation of randomness — the WASM module maintains a real quantum state vector, applies unitary gates, and performs projective measurement. The outcome follows Born's rule, not a PRNG seed.

What's Next

• Setup — Build the WASM module, configure the Vite plugin
• Property Manager — Core abstraction for quantum properties
• Gates — Full gate reference with game examples
• Measurement — Collapse, probabilities, forced measure
• Entanglement — iSwap patterns from five production games
• Phase & Interference — Clock gate, interference, Grover oracle
• Recording & Replay — Save/load quantum state
• Performance — Pooling, budgets, dimension limits