quantum-forge

Real quantum mechanics for game developers. Superposition, entanglement, and interference powered by a compiled C++ quantum simulator running via WebAssembly.

This is the core package — WASM loader, quantum property manager, and Vite plugin. For the full game framework (engine, rendering, input, audio, etc.), install quantum-forge-engine instead.

Install

npm install quantum-forge

Quick Start

1. Configure Vite

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

export default defineConfig({
  plugins: [quantumForgeVitePlugin()],
});

ESM note: If using vite.config.js (not .ts or .mjs), add "type": "module" to your package.json.

2. Use Quantum Mechanics

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

// Initialize WASM (call once at startup)
await ensureLoaded();

// Create a property manager
const qpm = new QuantumPropertyManager({ dimension: 2 });

// Create a qubit and put it in superposition
const qubit = qpm.acquireProperty();
qpm.hadamard(qubit);

// Read probabilities (no collapse)
const probs = qpm.probabilities(qubit); // [~0.5, ~0.5]

// Measure (collapses to 0 or 1)
const [value] = qpm.measureProperties([qubit]);

// Recycle for reuse
qpm.releaseProperty(qubit, value);

3. Entanglement

const a = qpm.acquireProperty();
const b = qpm.acquireProperty();

qpm.hadamard(a);
qpm.iSwap(a, b); // Entangle — measuring one determines the other

const [va, vb] = qpm.measureProperties([a, b]);
// va and vb are always anti-correlated

Editions

Two WASM builds are included:

| Edition | Dimensions | Max Qudits | Use Case | |---------|-----------|------------|----------| | Qutrit (default) | 2–3 | 12 | Games using qutrits (3-state quantum digits) | | Qubit | 2 | 20 | Games needing more qubits at dimension 2 |

To use the Qubit Edition:

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

useQuantumForgeBuild("qubit"); // Call before ensureLoaded()
await ensureLoaded();

Package Exports

| Export | Contents | |--------|----------| | quantum-forge/quantum | ensureLoaded, QuantumPropertyManager, QuantumRecorder, useQuantumForgeBuild | | quantum-forge/logging | Logger | | quantum-forge/vite-plugin | quantumForgeVitePlugin |

Gates

| Gate | Qudits | Description | |------|--------|-------------| | hadamard | 1 | Equal superposition | | cycle | 1 | Deterministic rotation: |0⟩→|1⟩→|2⟩→|0⟩ | | clock (Z) | 1 | Phase rotation | | shift (X) | 1 | Value shift | | y | 1 | Y gate (qubit-only) | | iSwap | 2 | Entangling swap | | swap | 2 | Value swap |

All gates support fractional application and conditional predicates.

Documentation

• Full documentation
• Developer site
• Discord

License

TypeScript source: MIT (see LICENSE.md). WASM binaries: proprietary — free for apps under $100K annual revenue with attribution. See dist/LICENSE-BINARY.md for binary terms.