Engine API

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

Engine<TState>

Abstract base class for game state coordination.

Constructor

new Engine<TState>(initialState: TState, config?: EngineConfig)

interface EngineConfig {
  logger?: LoggerInterface;
  eventBus?: EventBus<any>;
}

Pass an eventBus and every setState() emits "state-changed" with { state }. See Events.

Methods

Method	Returns	Description
getState()	Readonly<TState>	The current game state. Treat it as read-only
getHelpers()	Record<string, any>	Abstract. Implement it to return state-mutating functions
reset()	void	Abstract. Implement it to reset to initial state

setState(newState: TState) is protected, so only code inside your subclass can call it. Helpers are the intended caller.

Usage

interface MyState {
  score: number;
  player: { x: number; y: number };
}

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

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

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

Rules

• getState() returns Readonly<TState>. Build a new object and pass it to setState() rather than mutating fields in place
• getHelpers() returns plain functions, not async
• Helpers should call pure logic functions for any non-trivial computation
• No setTimeout, requestAnimationFrame, or animation timing in the engine
• State should contain everything needed to render the game