Command Pattern

The command pattern encapsulates actions as objects. Instead of calling player.jump() directly, you create a JumpCommand object and execute it. This single layer of indirection unlocks undo, redo, replay, networking, AI input, input rebinding, and macro recording.

Core interface

Every command implements at minimum:

interface Command {
  execute(): void;
  undo(): void;
}

For networking and replay, add serialization:

interface SerializableCommand extends Command {
  readonly type: string;
  serialize(): Record<string, unknown>;
  static deserialize(data: Record<string, unknown>): SerializableCommand;
}

Undo stack management

A command history tracks executed commands and supports undo/redo.

class CommandHistory {
  private stack: Command[] = [];
  private pointer = -1;
  private maxSize: number;

  constructor(maxSize = 100) {
    this.maxSize = maxSize;
  }

  execute(cmd: Command) {
    // Discard redo history when a new command is executed
    this.stack.length = this.pointer + 1;

    cmd.execute();
    this.stack.push(cmd);
    this.pointer++;

    // Enforce max size to prevent memory leaks
    if (this.stack.length > this.maxSize) {
      this.stack.shift();
      this.pointer--;
    }
  }

  undo(): boolean {
    if (this.pointer < 0) return false;
    this.stack[this.pointer].undo();
    this.pointer--;
    return true;
  }

  redo(): boolean {
    if (this.pointer >= this.stack.length - 1) return false;
    this.pointer++;
    this.stack[this.pointer].execute();
    return true;
  }

  clear() {
    this.stack.length = 0;
    this.pointer = -1;
  }
}

Key decisions:

• Max size - Cap at 50-200 commands for gameplay, 1000+ for editors.
• Redo discard - When executing a new command after undoing, discard the redo branch. This is the standard UX expectation.
• Checkpoint - For long sessions, periodically snapshot the full state and truncate old commands. Undo only goes back to the last checkpoint.

Composite commands

Group multiple commands into one undoable unit. Essential for batch operations in editors (e.g., "move all selected objects").

class CompositeCommand implements Command {
  constructor(private commands: Command[]) {}

  execute() {
    for (const cmd of this.commands) {
      cmd.execute();
    }
  }

  undo() {
    // Undo in reverse order
    for (let i = this.commands.length - 1; i >= 0; i--) {
      this.commands[i].undo();
    }
  }
}

// Usage: move 5 selected tiles at once
const moveAll = new CompositeCommand(
  selectedTiles.map(tile => new MoveCommand(tile, offset))
);
history.execute(moveAll); // Undo reverts ALL tiles in one step

Replay system

Record commands with timestamps during gameplay. Replay by feeding the same commands to a fresh game state at the same timings.

interface TimestampedCommand {
  frame: number;
  command: SerializableCommand;
}

class ReplayRecorder {
  private recording: TimestampedCommand[] = [];
  private currentFrame = 0;

  record(cmd: SerializableCommand) {
    this.recording.push({ frame: this.currentFrame, command: cmd });
  }

  tick() {
    this.currentFrame++;
  }

  export(): string {
    return JSON.stringify(
      this.recording.map(r => ({
        frame: r.frame,
        type: r.command.type,
        data: r.command.serialize(),
      }))
    );
  }
}

class ReplayPlayer {
  private recording: TimestampedCommand[];
  private index = 0;
  private currentFrame = 0;

  constructor(data: string, private commandFactory: CommandFactory) {
    const parsed = JSON.parse(data);
    this.recording = parsed.map((r: any) => ({
      frame: r.frame,
      command: this.commandFactory.create(r.type, r.data),
    }));
  }

  tick() {
    while (
      this.index < this.recording.length &&
      this.recording[this.index].frame === this.currentFrame
    ) {
      this.recording[this.index].command.execute();
      this.index++;
    }
    this.currentFrame++;
  }

  get isComplete(): boolean {
    return this.index >= this.recording.length;
  }
}

Critical requirement for replay: The game must be deterministic. Same commands on same frame must produce same result. This means:

• No Math.random() - use a seeded PRNG and include the seed in the replay
• No Date.now() for gameplay logic - use frame count
• Fixed timestep physics (not variable dt)
• Consistent floating-point behavior across platforms (use fixed-point if needed)

Networking with commands

In multiplayer, send commands over the network instead of state. This reduces bandwidth and leverages the same determinism required for replay.

Lockstep model

Both clients wait for the other's commands before advancing a frame.

Frame N:
  1. Collect local input -> create commands
  2. Send commands to server/peer
  3. Wait for remote commands
  4. Execute ALL commands (local + remote) in deterministic order
  5. Advance to frame N+1

Rollback model (GGPO-style)

Predict the remote player's input. If the prediction was wrong, roll back to the last confirmed frame and replay with correct commands.

class RollbackManager {
  private confirmedFrame = 0;
  private stateSnapshots = new Map<number, GameState>();
  private commandHistory = new Map<number, Command[]>();

  predict(frame: number, localCmd: Command, predictedRemoteCmd: Command) {
    this.commandHistory.set(frame, [localCmd, predictedRemoteCmd]);
    this.stateSnapshots.set(frame, this.gameState.snapshot());
    localCmd.execute();
    predictedRemoteCmd.execute();
  }

  correctPrediction(frame: number, actualRemoteCmd: Command) {
    const predicted = this.commandHistory.get(frame)?.[1];
    if (predicted && this.commandsEqual(predicted, actualRemoteCmd)) {
      this.confirmedFrame = frame;
      return; // Prediction was correct
    }

    // Rollback to the frame before the misprediction
    this.gameState.restore(this.stateSnapshots.get(frame)!);

    // Replay from that frame with correct commands
    this.commandHistory.get(frame)![1] = actualRemoteCmd;
    // ... re-execute all frames from here to current
  }
}

Rollback requires the ability to snapshot and restore game state quickly. Keep gameplay state compact and separate from visual state.

Input rebinding

When input is mapped through commands, rebinding is just changing which key maps to which command - no gameplay code changes.

class InputMapper {
  private bindings = new Map<string, () => Command>();

  bind(key: string, commandFactory: () => Command) {
    this.bindings.set(key, commandFactory);
  }

  handleInput(key: string): Command | null {
    const factory = this.bindings.get(key);
    return factory ? factory() : null;
  }
}

// Default bindings
const mapper = new InputMapper();
mapper.bind("Space", () => new JumpCommand(player));
mapper.bind("KeyZ", () => new AttackCommand(player));

// Player rebinds attack to KeyX
mapper.bind("KeyX", () => new AttackCommand(player));
mapper.bind("KeyZ", () => new DashCommand(player)); // Z is now dash

Macro recording

Record a sequence of commands as a single reusable macro. Useful for strategy games, automation tools, and level editors.

class MacroRecorder {
  private isRecording = false;
  private commands: Command[] = [];

  startRecording() {
    this.commands = [];
    this.isRecording = true;
  }

  record(cmd: Command) {
    if (this.isRecording) this.commands.push(cmd);
  }

  stopRecording(): CompositeCommand {
    this.isRecording = false;
    return new CompositeCommand([...this.commands]);
  }
}

Common pitfalls

1. Skipping undo() - "We'll add it later." You won't, and then replay breaks. Implement undo() for every command from day one.
2. Mutable command state - A command that references mutable objects may produce different results on redo. Capture values at execute time, not construction time.
3. Non-deterministic commands - Using Math.random() or system time inside execute(). All randomness must come from a seeded PRNG passed to the command.
4. Unbounded history - Storing every command forever. Set a max size and/or use periodic checkpoints.
5. Forgetting composite undo order - Composite commands must undo in reverse order. Forward undo creates inconsistent state.

Event Systems

Event systems decouple game systems by letting them communicate through messages rather than direct references. The damage system does not need to know about the UI, audio, analytics, or camera shake - it just emits "damage dealt" and subscribers handle the rest.

Immediate dispatch vs event queue

Immediate dispatch

Handlers fire synchronously the moment emit() is called. Simple and predictable.

class ImmediateEventBus {
  private handlers = new Map<string, Set<Function>>();

  emit(event: string, data: any) {
    this.handlers.get(event)?.forEach(fn => fn(data));
  }
}

Pros: Simple. Handlers see the event in the same frame. Stack trace is readable. Cons: A slow handler blocks the emitter. Handlers can emit more events, causing re-entrant cascades.

Event queue

Events are buffered and processed at a defined point in the frame (e.g., end of update, between fixed steps).

class QueuedEventBus {
  private queue: Array<{ event: string; data: any }> = [];
  private handlers = new Map<string, Set<Function>>();

  emit(event: string, data: any) {
    this.queue.push({ event, data });
  }

  processQueue() {
    const current = this.queue;
    this.queue = []; // Swap to avoid infinite loops from handlers emitting
    for (const { event, data } of current) {
      this.handlers.get(event)?.forEach(fn => fn(data));
    }
  }
}

Pros: No re-entrancy issues. Can batch-process events. Easier to debug. Cons: One frame of latency. Harder to reason about ordering.

Recommendation: Use immediate dispatch for UI and simple gameplay. Use queued dispatch for physics callbacks, networking, and any system where re-entrancy is a risk.

Priority ordering

When multiple systems react to the same event, order can matter. A shield system should reduce damage before the health system applies it.

class PriorityEventBus {
  private handlers = new Map<string, Array<{ priority: number; fn: Function }>>();

  on(event: string, handler: Function, priority = 0) {
    if (!this.handlers.has(event)) this.handlers.set(event, []);
    const list = this.handlers.get(event)!;
    list.push({ priority, fn: handler });
    list.sort((a, b) => b.priority - a.priority); // Higher priority first
  }

  emit(event: string, data: any) {
    this.handlers.get(event)?.forEach(({ fn }) => fn(data));
  }
}

// Shield processes damage first (priority 100), then health (priority 0)
bus.on("damage-taken", shieldSystem.onDamage, 100);
bus.on("damage-taken", healthSystem.onDamage, 0);

Use priority sparingly. If you have more than 3 priority levels for one event, the systems are too coupled and you should redesign the data flow.

Event filtering

Not every subscriber cares about every instance of an event. The UI only cares about damage to the player, not to every enemy.

Filter at subscribe time

bus.on("damage-taken", (data) => {
  if (data.target !== player) return; // Early exit
  healthBar.update(data.amount);
});

Scoped event buses

Instead of one global bus, create buses per scope:

class Entity {
  readonly events = new EventBus(); // Per-entity bus
}

// Subscribe to this specific enemy's events
boss.events.on("health-changed", updateBossHealthBar);

Best practice: Use a global bus for system-level events (level-complete, pause, game-over). Use per-entity buses for entity-specific events (health-changed, state-changed).

Debugging leaked subscriptions

The #1 bug with event systems: a destroyed entity's handler is still subscribed, causing it to process events after "death."

Prevention: unsubscribe on destroy

class Enemy {
  private unsubscribers: Array<() => void> = [];

  init() {
    this.unsubscribers.push(
      bus.on("player-moved", this.onPlayerMoved.bind(this))
    );
  }

  destroy() {
    this.unsubscribers.forEach(unsub => unsub());
    this.unsubscribers.length = 0;
  }
}

Detection: debug mode listener tracking

class DebugEventBus extends EventBus {
  private subscriberSources = new Map<Function, string>();

  on(event: string, handler: Function) {
    this.subscriberSources.set(handler, new Error().stack ?? "unknown");
    return super.on(event, handler);
  }

  debugListeners(event: string) {
    console.log(`Listeners for "${event}":`);
    this.handlers.get(event)?.forEach(fn => {
      console.log(" -", this.subscriberSources.get(fn));
    });
  }
}

In debug builds, log a warning when event handler count for any event exceeds a threshold (e.g., 50). This catches subscription leaks early.

Typed events pattern

Use TypeScript's type system to enforce correct event payloads at compile time.

// Define all events and their payloads in one place
interface GameEvents {
  "player:damage": { amount: number; source: string; isCritical: boolean };
  "player:death": { killer: string; position: Vector2 };
  "enemy:spawn": { type: string; level: number; position: Vector2 };
  "ui:notification": { message: string; duration: number };
  "game:pause": {};
  "game:resume": {};
}

class TypedEventBus {
  private handlers = new Map<string, Set<Function>>();

  on<K extends keyof GameEvents>(
    event: K,
    handler: (data: GameEvents[K]) => void
  ): () => void {
    if (!this.handlers.has(event)) this.handlers.set(event, new Set());
    this.handlers.get(event)!.add(handler);
    return () => this.handlers.get(event)!.delete(handler);
  }

  emit<K extends keyof GameEvents>(event: K, data: GameEvents[K]) {
    this.handlers.get(event)?.forEach(fn => fn(data));
  }
}

This catches typos in event names and wrong payload shapes at compile time.

Common pitfalls

1. God bus - One global bus handles everything. Hard to trace which systems react to what. Split into domain-specific buses.
2. Event storms - Handler A emits event B, handler for B emits event A, creating an infinite loop. Use queued dispatch or add re-entrancy guards.
3. Order dependence - System correctness depends on handler execution order without making that order explicit. Use priority if order matters.
4. Stale data in events - Event carries a reference to mutable data that changes before all handlers process it. Copy data into the event payload.
5. Subscription leaks - Destroyed entities still subscribed. Always unsubscribe in the destroy/cleanup method.

Object Pooling

Object pooling eliminates runtime allocation by pre-creating objects and recycling them. In games, this is not an optimization - it is a requirement for any entity spawned more than once per second.

Why pooling matters in games

The problem is not allocation - it is deallocation. Creating an object is fast. But when the garbage collector eventually runs to clean up destroyed objects, it pauses your game for milliseconds. At 60fps, a 5ms GC pause means a visible stutter.

When to pool:

• Bullets, projectiles, particles (high spawn rate)
• Enemies that spawn in waves
• UI elements like damage numbers, floating text
• Audio source objects
• Visual effects (explosions, hit sparks)

When NOT to pool:

• Singleton systems (one instance, never destroyed)
• Level geometry (loaded once, persists all level)
• Anything created fewer than once per 10 seconds

Pool sizing strategies

Fixed pool

Pre-allocate an exact count. If the pool is empty, refuse the spawn.

const MAX_BULLETS = 200;
const bulletPool = new ObjectPool(() => new Bullet(), MAX_BULLETS);

function fireBullet(pos: Vector2, dir: Vector2) {
  const bullet = bulletPool.acquire();
  if (!bullet) return; // Pool exhausted - skip this bullet
  bullet.init(pos, dir);
}

Pros: Predictable memory. No allocations ever. Cons: Hard to tune. Too small = missed spawns. Too large = wasted memory.

Growing pool with warning

Start with an estimate. If exhausted, grow by allocating more - but log a warning so you can tune the initial size.

class GrowablePool<T> {
  private available: T[] = [];
  private growCount = 0;

  constructor(
    private factory: () => T,
    private reset: (obj: T) => void,
    initialSize: number,
    private growSize: number = 10
  ) {
    this.fill(initialSize);
  }

  private fill(count: number) {
    for (let i = 0; i < count; i++) {
      this.available.push(this.factory());
    }
  }

  acquire(): T {
    if (this.available.length === 0) {
      this.growCount++;
      console.warn(`Pool grew ${this.growCount} times. Consider increasing initial size.`);
      this.fill(this.growSize);
    }
    return this.available.pop()!;
  }

  release(obj: T) {
    this.reset(obj);
    this.available.push(obj);
  }
}

Best practice: Run your heaviest gameplay scenario and check growCount. Set initial size to cover that peak with 20% headroom.

Double-buffer pool

For systems where objects are spawned and released in bulk (particle bursts), use two lists and swap them each frame to avoid iterator invalidation.

Reset contract

The most critical part of pooling is the reset function. When an object is released back to the pool, it MUST be returned to a pristine state. Stale data from a previous life is the #1 pooling bug.

function resetBullet(bullet: Bullet) {
  bullet.active = false;
  bullet.position.set(0, 0);
  bullet.velocity.set(0, 0);
  bullet.damage = 0;
  bullet.owner = null;
  bullet.lifetime = 0;
  // Clear any event listeners attached during this life
  bullet.removeAllListeners();
}

Checklist for a reset function:

• Zero all physics state (position, velocity, acceleration)
• Reset all gameplay state (health, damage, owner, team)
• Deactivate rendering (hide sprite, disable mesh)
• Remove event subscriptions added during this object's life
• Cancel any active timers or coroutines
• Reset animation to default

Language-specific GC considerations

JavaScript / TypeScript

• No manual memory management. GC is unavoidable for unreferenced objects.
• Pool ALL frequently spawned objects. Avoid new in update loops.
• Use TypedArray (Float32Array, etc.) for bulk numeric data instead of object arrays.
• Avoid closures in hot paths - they allocate.

C# (Unity)

• Use ObjectPool<T> from Unity 2021+ (UnityEngine.Pool).
• For older Unity: implement your own with Queue<T>.
• Disable GameObjects with SetActive(false) instead of Destroy().
• Use struct for small value types to avoid heap allocation.

C++

• Pooling is still valuable for cache locality even without GC.
• Use contiguous arrays (std::vector<T>) for cache-friendly iteration.
• Consider slot maps (sparse set) for stable handles with dense storage.
• Object pools in C++ also prevent memory fragmentation.

Rust

• No GC, but pooling still helps with allocation cost and cache performance.
• Use Vec<T> as a free list. pop() to acquire, push() to release.
• Consider Arena allocators for frame-scoped temporary objects.

Thread safety

If your game uses multithreaded job systems (Unity DOTS, Bevy ECS), pools need synchronization:

class ThreadSafePool<T> {
  private available: T[] = [];
  private lock = new Mutex();

  acquire(): T | null {
    this.lock.acquire();
    try {
      return this.available.pop() ?? null;
    } finally {
      this.lock.release();
    }
  }

  release(obj: T) {
    this.lock.acquire();
    try {
      this.available.push(obj);
    } finally {
      this.lock.release();
    }
  }
}

Better approach: Use per-thread pools. Each thread has its own pool, eliminating contention entirely. Only rebalance between threads periodically.

Common pitfalls

1. Forgetting to reset - Object retains state from previous use. Add assertions in debug builds that verify the reset contract.
2. Double release - Releasing an object that is already in the pool. Guard with an active flag or a set of active references.
3. Pool too small - Causes allocation during gameplay. Profile your peak and add headroom.
4. Pool too large - Wastes memory on objects never used. Log high-water marks and trim during loading screens.
5. Holding references to released objects - Other systems still point at a recycled object. Use handle/generation systems to detect stale references.

State Machines

State machines are the most fundamental pattern for managing entity behavior in games. Every character, AI agent, UI screen, and game phase can be modeled as a state machine.

Finite State Machine (FSM)

The simplest form. An entity is always in exactly one state. Each state defines:

• enter() - Run once when entering the state (play animation, set flags)
• update(dt) - Run every frame while in the state
• exit() - Run once when leaving (cleanup, stop effects)
• transitions - Conditions that trigger a move to another state

Transition table design

Define valid transitions upfront rather than scattering them through state code. This makes the machine auditable and prevents spaghetti.

type TransitionTable = {
  [fromState: string]: {
    [condition: string]: string; // target state
  };
};

const playerTransitions: TransitionTable = {
  Idle:      { jump: "Jumping", move: "Running", attack: "Attacking" },
  Running:   { stop: "Idle", jump: "Jumping", attack: "Attacking" },
  Jumping:   { land: "Idle", attack: "AirAttack" },
  Attacking: { done: "Idle" },
  AirAttack: { land: "Idle" },
};

If a transition is not in the table, it is illegal. This catches bugs like "attacking while already attacking" at the architecture level.

Common FSM implementation patterns

Enum-based FSM - Simplest. Good for fewer than 5 states with minimal per-state logic.

enum PlayerState { Idle, Running, Jumping }

class Player {
  state = PlayerState.Idle;

  update(dt: number) {
    switch (this.state) {
      case PlayerState.Idle:
        if (this.input.move) this.state = PlayerState.Running;
        break;
      case PlayerState.Running:
        this.position.x += this.speed * dt;
        if (!this.input.move) this.state = PlayerState.Idle;
        break;
    }
  }
}

Class-based FSM - Better for 5+ states or states with significant per-state logic. Each state is its own class implementing a common interface. This is the recommended approach for most game entities.

Data-driven FSM - States and transitions defined in external data (JSON, ScriptableObjects). Good for designer-facing tools where non-programmers need to tweak behavior.

Hierarchical State Machine (HFSM)

When a flat FSM has too many states, group related states into parent states. The parent handles shared behavior; children handle specifics.

CombatState (parent)
  - AttackingState (child)
  - DefendingState (child)
  - FlankingState (child)

IdleState (parent)
  - PatrolState (child)
  - StandingState (child)

Key rule: Transitions can target a parent state (enters its default child) or a specific child. A child can transition to a sibling without leaving the parent. Transitioning out of a child to a non-sibling exits the parent too.

When to use HFSM vs flat FSM

Pushdown Automata

A stack-based state machine where new states push onto a stack and popping resumes the previous state. Perfect for interrupt-and-resume patterns.

Use cases:

• Pause menu pushes onto gameplay state; unpausing pops back
• Cutscene pushes onto exploration; cutscene ends, exploration resumes exactly
• Stun effect pushes onto any current state; stun ends, previous behavior resumes

class PushdownFSM {
  private stack: State[] = [];

  get current(): State | undefined {
    return this.stack[this.stack.length - 1];
  }

  push(state: State) {
    this.current?.pause?.();
    this.stack.push(state);
    state.enter();
  }

  pop() {
    const old = this.stack.pop();
    old?.exit();
    this.current?.resume?.();
  }

  update(dt: number) {
    this.current?.update(dt);
  }
}

The pause() and resume() hooks are critical. Without them, a paused state's timers and animations continue running in the background.

FSM vs Behavior Trees

Rule of thumb: Start with an FSM. If you find yourself adding transitions between states that shouldn't know about each other, it is time to consider a behavior tree.

Common pitfalls

1. State explosion - Too many states in a flat FSM. Solution: use HFSM or behavior trees.
2. Transition spaghetti - Every state can go to every other state. Solution: define a transition table and enforce it.
3. Duplicated exit logic - Multiple states need the same cleanup. Solution: use a parent state in an HFSM.
4. Missing enter/exit hooks - Putting initialization in update() behind a firstFrame flag instead of using enter(). Always use the hooks.
5. Stateless state machine - Storing state data on the entity instead of in the state object. This leads to stale data when re-entering a state.