quantum-forge

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.