Quantum Pong

The canonical starter example — a Pong game where balls enter quantum superposition when they pass through a quantum zone.

Overview

When a ball enters the quantum zone (center of the field), it splits into two entangled balls. Both exist as quantum ghosts — semi-transparent — until one exits the field and is measured. Measurement collapses both balls: one scores, the other vanishes.

Players can bias which ball survives by applying phase rotations via a paddle-mounted phase dial.

Quantum Mechanics Used

Mechanism	Gate	Game Effect
Entangle-split	cycle + iSwap(0.5)	Ball splits into correlated pair
Quantum-split	iSwap(0.5) on existing	Already-quantum ball splits again
Phase rotation	clock(fraction)	Paddle dial biases survival probability
Existence probability	probabilities()	Ghost opacity reflects quantum state
Relative phase	reduced_density_matrix()	Phase dial display
Measurement	measureProperties()	Scoring — collapses to exists/ghost
Pooling	releaseProperty()	Reset measured balls for reuse

Registry

QuantumRegistry extends QuantumPropertyManager with five operations:

class QuantumRegistry extends QuantumPropertyManager {
  constructor(logger?: LoggerInterface) {
    super({ dimension: 2, logger });
  }

  entangleSplit(originalId: string, newId: string): void {
    const prop1 = this.acquireProperty();
    const prop2 = this.acquireProperty();
    this.cycle(prop1);                 // |1⟩ (exists)
    this.iSwap(prop1, prop2, 0.5);    // entangle
    this.setProperty(originalId, prop1);
    this.setProperty(newId, prop2);
  }

  quantumSplit(originalId: string, newId: string): boolean {
    const prop1 = this.getProperty(originalId);
    if (!prop1) return false;
    const prop2 = this.acquireProperty();
    try {
      this.iSwap(prop1, prop2, 0.5);
    } catch {
      this.releaseProperty(prop2, 0);
      return false;
    }
    this.setProperty(newId, prop2);
    return true;
  }

  applyPhase(id: string, fraction: number): void {
    const prop = this.getProperty(id);
    if (!prop) return;
    this.clock(prop, fraction);
  }

  getExistenceProbability(id: string): number {
    const prop = this.getProperty(id);
    if (!prop) return 1.0;
    const results = this.getModule().probabilities([prop]);
    for (const r of results) {
      if (r.qudit_values[0] === 1) return r.probability;
    }
    return 0;
  }

  measureExistence(id: string): number {
    const prop = this.getProperty(id);
    if (!prop) return 1;
    const [value] = this.measureProperties([prop]);
    this.deleteProperty(id);
    this.releaseProperty(prop, value);
    return value;
  }
}

Key Design Patterns

Entangle-Split as Core Mechanic

The quantum zone is a spatial trigger. When a classical ball crosses the threshold:

1. Two properties are acquired (from pool if possible)
2. One is cycled to |1⟩, the other stays at |0⟩
3. iSwap(0.5) entangles them into (|10⟩ + i|01⟩)/√2
4. Both balls render at ~50% opacity

Phase as Player Skill

The phase dial on each paddle gives players a way to influence quantum outcomes. Applying clock(fraction) rotates the relative phase between entangled balls. When the next iSwap occurs, the phase bias redistributes probability — so a skilled player can increase their scoring chance.

Measurement as Drama

The moment of measurement is the highest-drama event in the game. The player doesn't know which ball will score until it exits the field and gets measured. Ghost bursts (for |0⟩) and score bursts (for |1⟩) provide visual feedback.

Pooling for Sustainability

Every measured ball returns its property to the pool. This means the game can run indefinitely without hitting the qudit limit — there are always recycled properties available for the next entangle-split.

Source

framework/examples/quantum-pong/ — shipped with the framework, available as a template via npx quantum-forge init my-game --template quantum-pong.