Installation

Get a Quantum Forge game running in under 5 minutes.

Prerequisites

• Node.js 18+
• Git

Quick Start

Option 1: CLI Scaffold (Recommended)

npx quantum-forge init my-game
cd my-game
npm run dev

The CLI creates a complete project with Quantum Forge configured, Vite dev server, and the four-layer architecture in place. Choose from:

• Starter — minimal game loop with player movement
• Quantum Pong — full example with quantum mechanics, audio, AI opponent, and 75 tests

Option 2: Git Dependency

Add to an existing project's package.json:

{
  "dependencies": {
    "@quantum-realm-games/quantum-forge-framework": "git+ssh://git@github.com:quantum-realm-games/quantum-forge.git#framework-v1.9.1"
  }
}

Then import by feature:

import { Engine } from "@quantum-realm-games/quantum-forge-framework/engine";
import { PixiRenderer, GameLoop } from "@quantum-realm-games/quantum-forge-framework/rendering";
import { InputManager } from "@quantum-realm-games/quantum-forge-framework/input";
import { QuantumPropertyManager, ensureLoaded } from "@quantum-realm-games/quantum-forge-framework/quantum";

Building Quantum Forge

The WASM module must be built from source:

npm run setup

This interactive script:

1. Detects or installs Emscripten
2. Builds the WASM module (~30 seconds for small preset)
3. Copies artifacts to dist/

See Quantum Setup for build variants and configuration.

Vite Configuration

Add the Quantum Forge Vite plugin to serve WASM during development:

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

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

Verify

npm run dev

Open http://localhost:3000. If you see the starter game running, Quantum Forge is configured and ready.

Next Steps

• Project Structure — understand the four-layer pattern
• First Quantum Game — step-by-step tutorial
• Why Quantum? — what makes quantum different from Math.random()