Quantum Forge Setup

The WASM quantum simulator ships pre-built with the framework. Call ensureLoaded() before any quantum operations.

Quick Start

npx quantum-forge init my-game    # scaffolds project with setup included
cd my-game
npm run dev                       # WASM already configured

Initialization in Code

Always call ensureLoaded() before any quantum operation:

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

// Option 1: Background preload (recommended)
// Call after initial render for faster perceived startup
startBackgroundLoad(logger);

// Option 2: Blocking load before quantum operations
await ensureLoaded();

TIP

startBackgroundLoad() uses requestIdleCallback to begin loading the WASM module without blocking the main thread. Call it early (e.g., after your first render), then await ensureLoaded() later when you actually need quantum operations.

Vite Plugin

The framework includes a Vite plugin that serves WASM artifacts during development:

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

export default defineConfig({
  plugins: [quantumForgeVitePlugin()],
  build: {
    rollupOptions: {
      external: [/quantum-forge-web-api/],
    },
  },
});

The plugin routes /quantum-forge/* requests to the built WASM files in dist/. No additional configuration needed.

Plugin options:

Option	Default	Description
wasmDir	"dist"	Directory containing WASM artifacts
servePath	"/quantum-forge"	URL path prefix for serving

Custom WASM Base Path

If you serve WASM files from a non-default location:

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

setWasmBasePath("/assets/wasm"); // must be called BEFORE ensureLoaded()
await ensureLoaded();

Offline Support

Register the service worker for offline WASM caching:

import { registerServiceWorker } from "quantum-forge/quantum";

await registerServiceWorker("/quantum-forge-sw.js");

The service worker uses a cache-first strategy for WASM artifacts. After the first load, the module works offline.

Editions

The published npm package ships two WASM build variants, called editions. You choose an edition when you run npx quantum-forge init:

Edition	Dimensions	Max Qudits	WASM Variant
Qutrit (default)	2–3	12	Default build — no extra config needed
Qubit	2 only	20	Loads from /quantum-forge-qubit/

Qutrit Edition supports both qubits (dim=2) and qutrits (dim=3), giving you three-valued quantum states at the cost of a lower qudit ceiling. Qubit Edition locks dimension to 2 but raises the limit to 20 qubits, letting you run more quantum objects simultaneously.

Properties in separate (non-entangled) systems don't count against each other's limit. Proper pooling (measure → release → reuse) keeps the active count low. See Performance.

Switching Editions at Runtime

If you chose the Qubit edition during init, your generated main.ts already contains the required call. If you need to switch manually or add it to an existing project:

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

// Select the qubit variant — MUST be called before ensureLoaded()
useQuantumForgeBuild("qubit");
await ensureLoaded();

The Qutrit edition uses the default build and does not need useQuantumForgeBuild().

WARNING

useQuantumForgeBuild() must be called before ensureLoaded(). If the WASM module is already loaded, the call is ignored with a warning.

Querying the Active Edition

After loading, you can verify which build is active:

import { getMaxDimension, getMaxQudits } from "quantum-forge/quantum";

console.log(getMaxDimension()); // 3 (qutrit) or 2 (qubit)
console.log(getMaxQudits());    // 12 (qutrit) or 20 (qubit)

Future Versions

Future versions will support arbitrary qudit dimensions and higher qudit counts. The current limits are chosen to balance capability with WASM binary size and memory usage.

Runtime Queries

After loading, you can query the WASM module's configuration:

import { getVersion, getMaxDimension, getMaxQudits, getWasmMemoryBytes } from "quantum-forge/quantum";

console.log(getVersion());          // e.g., "1.2.0"
console.log(getMaxDimension());     // 3 (qutrit) or 2 (qubit)
console.log(getMaxQudits());        // 12 (qutrit) or 20 (qubit)
console.log(getWasmMemoryBytes());  // current WASM heap usage

Troubleshooting

"Quantum Forge not loaded"

Call await ensureLoaded() before using any quantum operations.

WASM files not found in production

Ensure WASM artifacts are copied to your public/static directory and setWasmBasePath() points to the correct URL path.