Framework Tools

These tools come from quantum-forge-engine, an optional package that bundles quantum-forge with extras for web games: state management, rendering, input handling, and packages for audio, collision, particles, and more. Quantum Forge itself needs none of it. If you only want quantum mechanics in your own renderer or engine, npm install quantum-forge and start from the Quick start.

npm install quantum-forge-engine   # installs quantum-forge too

Engine

The Engine<TState> base class manages game state. You extend it and expose state-mutating functions via getHelpers():

import { Engine } from "quantum-forge-engine/engine";

class MyEngine extends Engine<GameState> {
  constructor(config: { logger?: any; eventBus?: any } = {}) {
    super({ score: 0, player: { x: 0, y: 0 } }, config);
  }

  getHelpers() {
    return {
      movePlayer: (dx: number, dy: number) => {
        const state = this.getState();
        this.setState({
          ...state,
          player: { x: state.player.x + dx, y: state.player.y + dy },
        });
      },
    };
  }

  reset(): void {
    this.setState({ score: 0, player: { x: 0, y: 0 } });
  }
}

getState() returns Readonly<TState>, so build a new object rather than mutating in place. See Engine for details.

Rendering

Two renderers are available:

• PixiRenderer: WebGL/WebGPU via PixiJS 8 (recommended for new games)
• CanvasRenderer: Canvas 2D for simpler use cases

Plus GameLoop for the update/render cycle and Camera for world-space transforms.

import { PixiRenderer, GameLoop } from "quantum-forge-engine/rendering";

class MyRenderer extends PixiRenderer {
  protected draw(state: GameState) {
    this.graphics.circle(state.player.x, state.player.y, 10).fill("#fff");
  }
}

const renderer = new MyRenderer({ canvas, backgroundColor: 0x000000, logger });
await renderer.init();

const loop = new GameLoop({
  update: (dt) => { /* game logic */ },
  render: () => renderer.render(engine.getState()),
  targetFps: 60,
  logger,
});
loop.start();

See Rendering for details.

Input

InputManager provides a unified binding system across keyboard, mouse, gamepad, and touch:

import { InputManager, GamepadButtons } from "quantum-forge-engine/input";

const input = new InputManager({ logger });
input.bind("jump",
  { type: "key", code: "Space" },
  { type: "gamepad-button", index: GamepadButtons.A },
);

// In game loop:
input.poll();
if (input.isActionDown("jump")) { /* ... */ }

Supports touch zones, virtual joysticks, gestures, and local multiplayer. See Input for details.

Events

EventBus is a typed wrapper over eventemitter3. Pass one to the engine and every setState() emits "state-changed", which is how renderers and UI hear about updates.

import { EventBus } from "quantum-forge-engine/events";

const eventBus = new EventBus<MyGameEvents>();
const engine = new MyEngine({ logger, eventBus });

eventBus.on("state-changed", ({ state }) => hud.update(state));

See Events for details.

Optional packages

Package	Import	Description
Collision	quantum-forge-engine/collision	Rect, circle, and point tests with a SpatialGrid
Audio	quantum-forge-engine/audio	Howler.js wrapper for sounds and music
Particles	quantum-forge-engine/particles	Burst, trail, and explosion effects
Animation	quantum-forge-engine/animation	Tweening with easing functions
Entities	quantum-forge-engine/entities	Entity management with spatial queries
State machine	quantum-forge-engine/state-machine	Finite state machine
Timer	quantum-forge-engine/timer	Pause-aware game timers
Save	quantum-forge-engine/save	Slot-based saves with versioning
Scenes	quantum-forge-engine/scenes	Stack-based scene lifecycle
Operations	quantum-forge-engine/operations	Operation registry and executor

These are subpaths of the quantum-forge-engine package you already installed, so adding one is an import, not an install. The exceptions are the two optional peer dependencies:

npm install pixi.js   # PixiRenderer
npm install howler    # AudioManager

See Packages for usage examples and API Reference for full specs.