game-design-patterns

Files (7)

• README.md
• SKILL.md
• evals.json
• command-pattern.md · references/
• event-systems.md · references/
• object-pooling.md · references/
• state-machines.md · references/

SKILL.md (first lines)

## Key principles

1. **Frame budget is law** - Every pattern choice must respect the ~16ms frame budget.
   Allocations during gameplay cause GC spikes. Indirection has cache costs. Always
   profile before adding abstraction.

2. **Decouple, but not infinitely** - Game systems should communicate through events
   and commands rather than direct references, but over-decoupling creates debugging
   nightmares. One level of indirection is usually enough.

3. **State is explicit** - Implicit state (nested boolean flags, mode integers) leads
   to impossible combinations and subtle bugs. Make every valid state a first-class
   object with defined transitions.

4. **Pool what you spawn** - Any entity created and destroyed more than once per
   second should be pooled. The cost of allocation is not the constructor - it is the
   garbage collector pause 3 seconds later.

5. **Commands are data** - When input actions are objects rather than direct method
   calls, you get undo, replay, networking, and AI "for free." The command pattern
   is the single highest-leverage pattern in gameplay code.

---

## Core concepts

**State machines** model entities that have distinct behavioral modes. A character
can be Idle, Running, Jumping, or Attacking - but never Jumping and Idle at the same
time. Each state encapsulates its own update logic, entry/exit behavior, and valid
transitions. Hierarchical state machines (HFSM) add nested sub-states for complex AI.

**Object pooling** pre-allocates a fixed set of objects and recycles them instead of
creating and destroying instances at runtime. The pool maintains an "available" list
and hands out pre-initialized objects on request, reclaiming them when they are
"killed." This eliminates allocation pressure during gameplay.

**Event systems** (also called observer, pub/sub, or message bus) let game systems
communicate without direct references. When a player takes damage, the health system
fires a `DamageTaken` event. The UI, audio, camera shake, and analytics systems each
subscribe independently. Adding a new reaction requires zero changes to the damage code.

**The command pattern** encapsulates an action as an object with `execute()` and
optionally `undo()`. Player input becomes a stream of command objects. This enables
input rebinding, replay recording, undo/redo in editors, and sending commands over
the network for multiplayer.

---

## Common tasks

### Implement a finite state machine for character behavior

Each state is a class with `enter()`, `update()`, `exit()`, and a transition check.
The machine holds the current state and delegates to it.

```typescript
interface State {
  enter(): void;
  update(dt: number): void;
  exit(): void;
}

class IdleState implements State {
  constructor(private character: Character) {}
  enter() { this.character.playAnimation("idle"); }
  update(dt: number) {
    if (this.character.input.jump) {
      this.character.fsm.transition(new JumpState(this.character));
    }
  }
  exit() {}
}

class StateMachine {
  private current: State;

  transition(next: State) {
    this.current.exit();
    this.current = next;
    this.current.enter();
  }

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

> Avoid string-based state names. Use typed state classes so the compiler catches
> invalid transitions.

### Build an object pool

Pre-allocate objects at startup. `acquire()` returns a recycled instance; `release()`
returns it to the pool. Never allocate during gameplay.

```typescript
class ObjectPool<T> {
  private available: T[] = [];
  private active: Set<T> = new Set();

  constructor(
    private factory: () => T,
    private reset: (obj: T) => void,
    initialSize: number
  ) {
    for (let i = 0; i < initialSize; i++) {
      this.available.push(this.factory());
    }
  }

  acquire(): T | null {
    if (this.available.length === 0) return null;
    const obj = this.available.pop()!;
    this.active.add(obj);
    return obj;
  }

  release(obj: T): void {

From mkurman/zorai, MIT.

More from mkurman/zorai