quantum-forge-engine

Full game framework for building quantum games. Includes engine, rendering, input, audio, collision, particles, and more — plus the quantum-forge core (WASM quantum simulator, property manager, Vite plugin).

Install

npm install quantum-forge-engine

This installs both the engine and the quantum core. No separate install needed.

Scaffold a New Project

npx quantum-forge-engine init my-game
npx quantum-forge-engine init my-game --template quantum-pong
npx quantum-forge-engine init my-game --edition qubit

The CLI scaffolds a complete project with Vite, TypeScript, tests, and AI coding assistant configs (CLAUDE.md, AGENTS.md, .copilotinstructions.md).

Architecture

Games follow a four-layer pattern:

Pure Functions → Engine → Renderer → Controller

1. Pure Functions — Game logic in separate modules, no side effects
2. Engine — State coordinator with getState(), setState(), getHelpers()
3. Renderer — Derives visuals from state (PixiJS or Canvas 2D)
4. Controller — Wires Engine + Renderer + Input + GameLoop

import { ensureLoaded } from "quantum-forge/quantum";
import { Engine } from "quantum-forge-engine/engine";
import { PixiRenderer, GameLoop } from "quantum-forge-engine/rendering";
import { InputManager } from "quantum-forge-engine/input";

await ensureLoaded();

const engine = new MyEngine();
const renderer = new MyRenderer({ canvas });
await renderer.init();

const input = new InputManager();
input.bind("jump", { type: "key", code: "Space" });

const loop = new GameLoop({
  update: (dt) => { input.poll(); /* update state */ },
  render: () => renderer.render(engine.getState()),
});
loop.start();

Package Exports

| Export | Contents | |--------|----------| | quantum-forge-engine/engine | Engine base class | | quantum-forge-engine/rendering | PixiRenderer, CanvasRenderer, GameLoop, Camera | | quantum-forge-engine/input | InputManager, LocalMultiplayerManager, GamepadButtons | | quantum-forge-engine/events | EventBus | | quantum-forge-engine/collision | AABB, circle, point detection, SpatialGrid | | quantum-forge-engine/audio | AudioManager (Howler.js) | | quantum-forge-engine/particles | ParticleSystem (burst, trail, continuous) | | quantum-forge-engine/animation | AnimationSystem (tweening with easing) | | quantum-forge-engine/entities | EntityManager with spatial queries | | quantum-forge-engine/state-machine | StateMachine | | quantum-forge-engine/timer | TimerManager (pause-aware) | | quantum-forge-engine/save | SaveManager (versioned) | | quantum-forge-engine/scenes | SceneManager (stack-based lifecycle) | | quantum-forge-engine/operations | OperationRegistry, OperationExecutor |

Optional packages (collision, audio, particles, etc.) can be added interactively:

npx quantum-forge-engine add-system

CLI Tools

| Command | Description | |---------|-------------| | init <name> | Scaffold a new project | | add-system | Add optional packages interactively | | validate | Score project architecture against framework patterns | | doctor | Diagnose environment issues |

Quantum Integration

The quantum core is included automatically. See the quantum-forge README for quantum API details (gates, measurement, entanglement patterns).

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

await ensureLoaded();

class MyRegistry extends QuantumPropertyManager {
  constructor() {
    super({ dimension: 2 });
  }

  addEntity(id: string) {
    const prop = this.acquireProperty();
    this.cycle(prop);        // |0⟩ → |1⟩
    this.setProperty(id, prop);
  }

  entangle(id1: string, id2: string) {
    const p1 = this.getProperty(id1);
    const p2 = this.getProperty(id2);
    if (p1 && p2) this.iSwap(p1, p2);
  }

  measure(id: string): number {
    const prop = this.getProperty(id);
    if (!prop) return 0;
    const [value] = this.measureProperties([prop]);
    this.deleteProperty(id);
    this.releaseProperty(prop, value);
    return value;
  }
}

Documentation

• Full documentation
• Getting started guide
• Developer site
• Discord

License

TypeScript source: MIT (see LICENSE.md). WASM binaries in the quantum-forge dependency are proprietary — free for apps under $100K annual revenue with attribution.