Quantris

The most complex quantum integration in the Quantum Forge lineup. A Tetris-inspired puzzle game where falling pieces exist in quantum superposition — blocks can be "quantum" (partially existing) and entangled with each other.

Overview

In Quantris, pieces have a quantum "existence" property. When you activate a quantum intervention, pieces enter superposition — they might exist or not. Entangled pieces form groups where clearing one piece affects the probability of others. Line clearing measures quantum pieces, and those that collapse to "doesn't exist" leave gaps.

Quantum Mechanics Used

Mechanism	Gate	Game Effect
Existence state	cycle	Set piece existence to |1⟩ when spawned
Superposition	hadamard	Quantum intervention puts pieces in superposition
Entanglement groups	iSwap(0.5)	Overlapping pieces entangle into correlated groups
Subgroup entanglement	Predicated iSwap	Conditional entanglement based on piece positions
Coherence visualization	reduced_density_matrix()	Glow intensity from off-diagonal magnitude
Line clear measurement	measureProperties()	Clearing a line collapses all quantum pieces in it
Entanglement multiplier	Entangled count	More entangled pieces in a clear = higher score multiplier

Registry Pattern

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

  // Spawn a piece in definite |1⟩ state
  addPiece(id: string): void {
    const prop = this.acquireProperty();
    this.cycle(prop); // |0⟩ → |1⟩
    this.setProperty(id, prop);
  }

  // Put a piece into superposition
  applyQuantumIntervention(id: string): void {
    const prop = this.getProperty(id);
    if (!prop) return;
    this.hadamard(prop);
  }

  // Entangle two overlapping pieces
  entanglePieces(id1: string, id2: string): void {
    const p1 = this.getProperty(id1);
    const p2 = this.getProperty(id2);
    if (!p1 || !p2) return;
    this.iSwap(p1, p2, 0.5);
  }

  // Get coherence for visualization
  getCoherenceInfo(id: string): { probability: number; coherence: number } {
    const prop = this.getProperty(id);
    if (!prop) return { probability: 1, coherence: 0 };

    const probs = this.getModule().probabilities([prop]);
    const probability = probs.find(r => r.qudit_values[0] === 1)?.probability ?? 0;

    const rdm = this.getModule().reduced_density_matrix([prop]);
    const offDiag = rdm.find(e => e.row_values[0] !== e.col_values[0]);
    const coherence = offDiag
      ? Math.sqrt(offDiag.value.real ** 2 + offDiag.value.imag ** 2)
      : 0;

    return { probability, coherence };
  }

  // Measure piece during line clear
  measurePiece(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

Entanglement Groups

When pieces land adjacent to or overlapping quantum pieces, they form entanglement groups via iSwap. This creates correlated clusters where measuring one piece affects the probabilities of all others in the group.

The scoring mechanic rewards large entanglement groups: clearing a line with 4 entangled pieces gives a higher multiplier than 4 independent pieces.

RDM-Driven Visualization

Quantris uses the reduced density matrix to extract both probability and coherence for each piece. Probability controls opacity (how "solid" the piece looks). Coherence controls glow intensity (how "quantum" it looks — pulsing energy that fades as the piece decoheres).

Quantum Interventions as Tutorial

The game introduces quantum mechanics gradually. Early levels have no quantum effects. Later levels introduce interventions — player abilities that put pieces into superposition. The tutorial explains: "this piece now has a chance of not being real."

Measurement Creates Gaps

The dramatic moment: a full line triggers measurement of every quantum piece in it. Pieces that collapse to |0⟩ (doesn't exist) disappear, leaving gaps. This means a "complete" line might not actually clear if quantum pieces vanish. The player must manage entanglement to ensure the right pieces survive.