Framework Tools

Beyond quantum mechanics, the framework provides tools for building complete games: state management, rendering, input handling, and optional packages for audio, collision, particles, and more.

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.