Packages

Optional, composable packages that add functionality to your game. Install what you need — each package is self-contained with minimal dependencies.

Add packages to an existing game interactively:

npm run add-system

Available Packages

Package	Import	Description
Input	quantum-forge/input	Keyboard, mouse, gamepad, touch, gestures, local multiplayer
Collision	quantum-forge/collision	AABB, circle, point collision with SpatialGrid optimization
Audio	quantum-forge/audio	Howler.js wrapper for sounds and music
Particles	quantum-forge/particles	Burst, trail, and continuous particle effects
Animation	quantum-forge/animation	Tweening with easing functions
Entities	quantum-forge/entities	Entity management with spatial queries and tagging
State Machine	quantum-forge/state-machine	Generic finite state machine
Timer	quantum-forge/timer	Game-aware timers (pause-aware, delta-based)
Save	quantum-forge/save	Save management with versioning and auto-save
Scenes	quantum-forge/scenes	Scene management with stack-based lifecycle

Collision

import { SpatialGrid, checkCollision } from "quantum-forge/collision";

const grid = new SpatialGrid(cellSize);
grid.insert(entity);

const nearby = grid.query(entity.bounds);
for (const other of nearby) {
  if (checkCollision(entity, other)) {
    // handle collision
  }
}

Audio

import { AudioManager } from "quantum-forge/audio";

const audio = new AudioManager({ logger });
audio.loadSound("hit", "/sounds/hit.ogg");
audio.play("hit");
audio.setVolume(0.8);

Particles

import { ParticleSystem } from "quantum-forge/particles";

const particles = new ParticleSystem();
particles.burst(x, y, {
  count: 20,
  speed: 100,
  lifetime: 0.5,
  color: "#a855f7",
});

// In game loop
particles.update(dt);
particles.render(ctx);

Animation

import { Tween, easeOutCubic } from "quantum-forge/animation";

const tween = new Tween({
  from: { x: 0, y: 0 },
  to: { x: 100, y: 200 },
  duration: 500,
  easing: easeOutCubic,
  onUpdate: (values) => {
    sprite.x = values.x;
    sprite.y = values.y;
  },
});

Save

import { SaveManager } from "quantum-forge/save";

const saves = new SaveManager({
  key: "my-game",
  version: 1,
  autoSave: true,
  autoSaveInterval: 30000, // 30s
});

saves.save({ gameState, quantumLog }); // includes quantum recording
const data = saves.load();

Scenes

import { SceneManager } from "quantum-forge/scenes";

const scenes = new SceneManager();
scenes.register("menu", menuScene);
scenes.register("game", gameScene);

scenes.push("menu");   // enter menu
scenes.push("game");   // push game on top
scenes.pop();           // back to menu