# 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`](https://www.npmjs.com/package/quantum-forge-engine) instead.

## Install

```bash
npm install quantum-forge
```

## Quick Start

### 1. Configure Vite

```typescript
// 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

```typescript
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

```typescript
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:

```typescript
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](https://docs.quantum.dev)
- [Developer site](https://quantum.dev)
- [Discord](https://discord.gg/quantumforge)

## License

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