Gates

Quantum gates transform the state of properties without measuring them. They are the building blocks of all quantum gameplay. Every gate in Quantum Forge is a protected method on your QuantumPropertyManager subclass, automatically recorded when operation recording is active.

Gate Reference

Gate	Method	Dim	Default Fraction	Records As
Cycle	this.cycle(prop, fraction?, predicates?)	Any	1	"cycle"
Shift / X	this.shift(prop, fraction?, predicates?)	Any	1	"shift"
Hadamard	this.hadamard(prop, fraction?, predicates?)	Any	1	"hadamard"
Inverse Hadamard	this.inverseHadamard(prop, predicates?)	Any	—	"inverse_hadamard"
Clock / Z	this.clock(prop, fraction, predicates?)	Any	—	"clock"
Y	this.y(prop, fraction?, predicates?)	2 only	1	"y"
iSwap	this.iSwap(p1, p2, fraction, predicates?)	Any	—	"i_swap"
Swap	this.swap(p1, p2, predicates?)	Any	—	"swap"
Phase Rotate	this.phaseRotate(predicates, angle)	Any	—	"phase_rotate"

Aliases: this.x() → this.shift(), this.z() → this.clock()

Single-Property Gates

Cycle

Cyclic permutation of basis states. For dimension 2, this is the NOT gate.

this.cycle(prop);        // |0⟩ → |1⟩, |1⟩ → |0⟩ (dim=2)
this.cycle(prop, 0.5);   // fractional cycle (√NOT)

Game use cases:

• Quantum Pong — Initialize ball to |1⟩ (exists) after acquiring at |0⟩
• Quantris — Set a piece's existence state to |1⟩ when spawned

Hadamard

Creates equal superposition from a definite state. The most common gate for putting objects "into quantum."

this.hadamard(prop);        // |0⟩ → (|0⟩+|1⟩)/√2, |1⟩ → (|0⟩−|1⟩)/√2
this.hadamard(prop, 0.5);   // fractional Hadamard (H^0.5)
this.hadamard(prop, 0.1);   // very gentle — barely moves probabilities

Game use cases:

• Hex Diffusion — Fractional Hadamard (H^t) for gradual probability diffusion across hex cells. Small t = slow spread, large t = fast spread.
• Bloch Invaders — Full Hadamard to put invaders into superposition before basis measurement

Inverse Hadamard

The adjoint (reverse) of Hadamard. Collapses a superposition back toward a definite state.

this.inverseHadamard(prop);  // (|0⟩+|1⟩)/√2 → |0⟩

Game use cases:

• Hex Diffusion — "Focus" ability that concentrates probability back to specific cells

Clock / Z

Phase rotation (Z-rotation). Changes the phase of a state without changing measurement probabilities — until the property interacts with something else.

this.clock(prop, 1.0);   // full Z gate: |1⟩ picks up a phase of π
this.clock(prop, 0.5);   // half Z: |1⟩ picks up a phase of π/2
this.z(prop, 1.0);       // alias for clock

Game use cases:

• Quantum Pong — Phase dial on paddle hits biases subsequent entanglement interactions
• Bloch Invaders — Phi rotation on the Bloch sphere (Z-axis)
• Ponq — Phase charging that affects coherence-driven steering forces

TIP

Phase alone doesn't change what you'll measure — it changes how the property interacts with other properties. Phase + iSwap = probability redistribution. See Phase & Interference.

Shift / X

Generalized bit-flip. For dimension 2, identical to cycle. For higher dimensions, shifts states: |0⟩→|1⟩→|2⟩→...→|d-1⟩→|0⟩.

this.shift(prop);         // same as cycle for dim=2
this.x(prop);             // Pauli X alias — same behavior
this.x(prop, 0.5);        // fractional X

Game use cases:

• Bloch Invaders — X-basis measurement decomposition

Y Gate

Pauli Y gate. Qubit-only — throws an error if dimension is not 2. Composite gate: S-X-S-dagger.

this.y(prop);          // full Y gate (dim must be 2)
this.y(prop, 0.5);     // fractional Y: rotate around Y-axis on Bloch sphere

DANGER

this.y() throws if the property's dimension is not 2. This is intentional — the Y gate has no standard generalization to higher dimensions.

Game use cases:

• Bloch Invaders — Theta rotation on the Bloch sphere (Y-axis). The game uses Y and Z gates to navigate Bloch sphere coordinates.

Two-Property Gates

iSwap

The primary entanglement gate. Creates quantum correlations between two properties.

this.iSwap(prop1, prop2, 0.5);   // half iSwap — maximal entanglement
this.iSwap(prop1, prop2, 1.0);   // full iSwap — complete state exchange with phase
this.iSwap(prop1, prop2, 0.25);  // quarter iSwap — partial entanglement

At fraction=0.5, starting from |10⟩:

(|10⟩ + i|01⟩) / √2

This means: 50% chance property 1 is |1⟩ and property 2 is |0⟩, and 50% chance the reverse — and they are correlated. Measuring one instantly determines the other.

WARNING

iSwap between properties in different shared states triggers a tensor product, growing the combined state space. This is why pooling is critical — pooled properties are already in the shared state.

Game use cases:

• Quantum Pong — Entangle-split: ball enters quantum zone, splits into correlated pair
• Ponq — Same pattern, plus phase-charged entanglement for steering mechanics
• Quantris — Entangle pieces that overlap, creating correlated groups
• Hex Diffusion — Entangle cells at shared hex boundaries
• Bloch Invaders — Create entangled twin boss pairs

Swap

Direct state exchange between two properties. No entanglement — just moves quantum state from one to the other.

this.swap(prop1, prop2);

Conditional Gates (Predicates)

Every gate accepts an optional predicates parameter that conditions the gate on the state of other properties:

import type { PredicateSpec } from "quantum-forge-framework/quantum";

const predicates: PredicateSpec[] = [
  { property: controlProp, value: 1, isEqual: true },   // control must be |1⟩
  { property: otherProp, value: 0, isEqual: false },     // other must NOT be |0⟩
];

// Gate only applies when ALL predicates are satisfied
this.cycle(targetProp, 1, predicates);      // controlled-NOT
this.hadamard(targetProp, 1, predicates);   // controlled-Hadamard
this.iSwap(p1, p2, 0.5, predicates);       // controlled entanglement

The PredicateSpec type:

interface PredicateSpec {
  property: QFProperty;  // the property to check
  value: number;         // the basis state to compare against
  isEqual: boolean;      // true = "is this value", false = "is NOT this value"
}

Game use cases:

• Quantris — Gate on piece A conditioned on piece B's existence state
• Hex Diffusion — Grover oracle: phaseRotate conditioned on cell occupancy

Phase Rotate

Applies a phase rotation conditioned on predicates. Unlike other gates, predicates are required — phase rotation without a condition is meaningless.

this.phaseRotate(predicates, Math.PI);       // π phase flip on matching states
this.phaseRotate(predicates, Math.PI / 4);   // π/4 phase shift

Game use cases:

• Hex Diffusion — Grover oracle barriers. Walls apply phaseRotate(predicates, Math.PI) to reflect probability via destructive interference.

Gate Wrapper vs getModule()

State-mutating operations — always use gate wrappers:

this.cycle(prop);                    // ✓ recorded, uses wrapper
this.iSwap(p1, p2, 0.5);           // ✓ recorded, uses wrapper
this.measureProperties([prop]);      // ✓ recorded, uses wrapper

Read-only queries — use getModule() directly:

this.getModule().probabilities([prop]);              // ✓ no state change
this.getModule().reduced_density_matrix([p1, p2]);   // ✓ no state change

Anti-pattern

Never call WASM functions directly for state mutations:

this.getModule().cycle(prop);                 // ✗ NOT recorded
this.getModule().i_swap(prop1, prop2, 0.5);   // ✗ NOT recorded
this.getModule().measure_properties([prop]);   // ✗ NOT recorded

This bypasses recording and breaks save/load.

Fractional Gates

Most gates accept a fraction parameter for partial application:

• fraction=1 — full gate (default for cycle, shift, hadamard)
• fraction=0.5 — square root of the gate
• fraction=0.1 — very gentle, barely moves the state
• fraction=2 — applies the gate twice (often identity)

Fractional gates are key to creating gradual quantum effects. Hex Diffusion uses hadamard(prop, 0.05) for slow probability diffusion, while Bloch Invaders uses y(prop, 0.3) for precise Bloch sphere navigation.