Quantum Forge Setup

Quantum Forge is a C++ quantum simulator compiled to WebAssembly. It must be built from source before your game can use quantum operations.

Quick Setup

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

If you're working in the monorepo directly:

cd quantum-forge/framework
npm run setup                     # interactive — handles everything
npm run dev

What npm run setup Does

1. Locates the Quantum Forge C++ core in the monorepo
2. Checks Node.js version (requires 18+)
3. Detects or installs Emscripten (the C++ → WASM compiler)
4. Builds the WASM module with the small preset
5. Copies artifacts to dist/:
   • quantum-forge-web-api.mjs — JavaScript API
   • quantum-forge-web-esm.mjs — ESM wrapper
   • quantum-forge-web-esm.wasm — WASM binary
   • quantum-forge-web-api.d.mts — TypeScript definitions

Initialization in Code

Always call ensureLoaded() before any quantum operation:

import { ensureLoaded, startBackgroundLoad } from "quantum-forge-framework/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-framework/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-framework/quantum";

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

Build Variants

Different games need different qudit configurations. Build variants let you trade compilation time and binary size for quantum capacity:

# Small (fast build, limited capacity)
npm run build:quantum-forge:small

# Medium (balanced — default)
npm run build:quantum-forge

# Custom dimensions and qudit count
npm run build:quantum-forge:custom

Named Variants

For games that need multiple configurations (e.g., a lobby mode with dim=2 and a puzzle mode with dim=7):

npm run build:quantum-forge:variant -- --name d7n10 --max-dimension 7 --max-qudits 10

This builds to dist/quantum-forge-d7n10/. Switch at runtime:

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

useQuantumForgeBuild("d7n10"); // before ensureLoaded()
await ensureLoaded();

The Vite plugin automatically serves named variants at /quantum-forge-{name}/.

Variant Tradeoffs

Preset	Max Dim	Max Qudits	State Space	Build Time
Small	2	5	32 states	~30s
Medium	2	8	256 states	~1 min
Custom (d3n32)	3	32	3^32 states	~3 min

WARNING

Memory grows exponentially: dimension^qudits * 16 bytes worst case. A dim=3, 32-qudit system could theoretically need 26 TB — but sparse state representation means you only pay for states with non-zero amplitude.

Offline Support

Register the service worker for offline WASM caching:

import { registerServiceWorker } from "quantum-forge-framework/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.

Runtime Queries

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

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

console.log(getVersion());          // e.g., "1.2.0"
console.log(getMaxDimension());     // e.g., 2
console.log(getMaxQudits());        // e.g., 8
console.log(getWasmMemoryBytes());  // current WASM heap usage

Troubleshooting

"Quantum Forge not loaded"

Call await ensureLoaded() before using any quantum operations.

Setup can't find Emscripten

The setup script checks in order:

1. emcc on your PATH
2. EMSDK_PATH in .env.local
3. Local emsdk at ../emsdk

If none work, it offers to install Emscripten for you.

WASM files not found in production

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