game-state-machines-and-ai

Game State Machines and AI

Overview

Character controllers, enemies, menus and match flow are all state machines whether or not the code admits it. When they are written as a pile of booleans (isJumping, isAttacking, isStunned), illegal combinations become reachable and every new state touches every branch. Make the states and the legal transitions explicit, and test the table.

Core principle: One current state, an explicit list of (state, event) → next state, and enter/exit hooks. Anything not in the table cannot happen.

Flags vs a table

// ❌ flag soup: can be jumping AND stunned AND attacking; every rule checks every flag
if (input.attack && !this.isStunned && !this.isDead && (!this.isJumping || this.canAirAttack)) { ... }

// ✅ explicit states and transitions
type State = "idle" | "run" | "jump" | "attack" | "stunned" | "dead";
type Event = "move" | "stop" | "jump" | "land" | "attack" | "attackEnd" | "hit" | "recover" | "die";

const transitions: Record<State, Partial<Record<Event, State>>> = {
  idle:    { move: "run", jump: "jump", attack: "attack", hit: "stunned", die: "dead" },
  run:     { stop: "idle", jump: "jump", attack: "attack", hit: "stunned", die: "dead" },
  jump:    { land: "idle", hit: "stunned", die: "dead" },
  attack:  { attackEnd: "idle", hit: "stunned", die: "dead" },
  stunned: { recover: "idle", die: "dead" },
  dead:    {},
};

export class Fsm {
  constructor(public state: State, private hooks: Hooks) {}
  send(e: Event): boolean {
    const next = transitions[this.state][e];
    if (!next) return false;
    this.hooks.exit?.(this.state); this.state = next; this.hooks.enter?.(next);
    return true;
  }
}

The same shape in C# is an enum plus a Dictionary<(State, Event), State> built once; in GDScript a Dictionary of dictionaries or one node per state (godot-gdscript-patterns); in Unreal a UENUM with a switch, or StateTree for larger designs.

Testing the table

it.each([
  ["idle", "jump", "jump"], ["jump", "attack", "jump"],   // no air attack in this design
  ["stunned", "move", "stunned"], ["dead", "recover", "dead"],
  ["attack", "hit", "stunned"],
])("%s + %s → %s", (from, ev, to) => {
  const fsm = new Fsm(from as State, {});
  fsm.send(ev as Event);
  expect(fsm.state).toBe(to);
});