Packages API

Collision

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

SpatialGrid

Spatial partitioning for broad-phase collision detection.

const grid = new SpatialGrid(cellSize: number);
grid.clear();
grid.insert(entity: { bounds: { x, y, width, height } });
grid.query(bounds: { x, y, width, height }): Entity[];

checkCollision

checkCollision(a: Collidable, b: Collidable): boolean;
// Supports AABB, circle, and point shapes

Audio

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

Howler.js wrapper for game audio.

const audio = new AudioManager({ logger });
audio.loadSound(key: string, path: string, options?: HowlOptions);
audio.play(key: string): void;
audio.stop(key?: string): void;  // stop specific or all
audio.setVolume(volume: number): void;  // 0–1
audio.mute(muted: boolean): void;

Particles

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

const particles = new ParticleSystem();

particles.burst(x, y, options: {
  count: number;
  speed: number;
  lifetime: number;
  color: string;
  size?: number;
  spread?: number;  // radians
});

particles.trail(x, y, options);  // continuous emission
particles.update(dt: number);
particles.render(ctx: CanvasRenderingContext2D);

Animation

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

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

tween.update(dt);  // call each frame
tween.isComplete(): boolean;

Easing functions: linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeOutElastic, easeOutBounce

Entities

import { EntityManager } from "quantum-forge/entities";

const entities = new EntityManager();
entities.add(entity);
entities.remove(entity);
entities.getByTag(tag: string): Entity[];
entities.queryRect(bounds): Entity[];  // spatial query
entities.forEach(callback);

State Machine

import { StateMachine } from "quantum-forge/state-machine";

const fsm = new StateMachine({
  initial: "idle",
  states: {
    idle: { on: { START: "running" } },
    running: { on: { STOP: "idle", JUMP: "jumping" } },
    jumping: { on: { LAND: "running" } },
  },
});

fsm.send("START");
fsm.getState();  // "running"
fsm.matches("running");  // true

Timer

import { GameTimer } from "quantum-forge/timer";

Game-aware timer that respects pause state.

const timer = new GameTimer();
timer.after(2000, () => { /* fires after 2s of game time */ });
timer.every(500, () => { /* repeats every 500ms of game time */ });
timer.update(dt);  // call each frame
timer.pause();
timer.resume();

Save

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

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

saves.save(data: any, slot?: number);
saves.load(slot?: number): any | null;
saves.hasSave(slot?: number): boolean;
saves.deleteSave(slot?: number);
saves.getSlots(): SaveSlotInfo[];

Save data is versioned. If version changes, old saves can be migrated via an optional migrate function.

Scenes

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

Stack-based scene management.

const scenes = new SceneManager();

scenes.register("menu", {
  enter: () => { /* setup */ },
  exit: () => { /* cleanup */ },
  update: (dt) => { /* tick */ },
  render: () => { /* draw */ },
});

scenes.push("menu");   // enter scene
scenes.push("game");   // push on stack (menu paused)
scenes.pop();           // return to menu
scenes.replace("end");  // swap top of stack