unity-state-machines

State & Behavior Systems -- Decision Patterns

Prerequisite skills: unity-game-architecture (MonoBehaviour vs plain C#, component composition), unity-animation (Animator FSM, StateMachineBehaviour), unity-scripting (MonoBehaviour lifecycle)

These patterns address the most common state management failure: Claude writes ad-hoc if/else chains or giant switch statements with no structure, making state logic unmaintainable beyond 3-4 states.

PATTERN: State System Selection

WHEN: Implementing AI behavior, game flow, character states, or UI navigation

DECISION:

• Animator FSM -- States are tied to animations. Character locomotion, attack combos, death animations. Designer-friendly visual graph. See unity-animation for full coverage -- do not build a code FSM just to drive animations.
• Code FSM (enum or class-based) -- Game flow (MainMenu/Playing/Paused/GameOver), ability systems, turn phases. Fully testable, no Animator overhead. Use when states have complex logic, not just animation swaps.
• Hierarchical FSM (HFSM) -- States within states. Combat contains {Melee, Ranged, Blocking}. When flat FSM has too many transitions between related states.
• Behavior Tree (BT) -- Complex AI with prioritization, interruptible sequences, parallel behaviors. When FSM has >8-10 states and transition explosion makes the graph unreadable.
• Stack-Based (Pushdown) -- UI screens, pause menus, modal dialogs. States push/pop, previous state is preserved and resumed.

How many states? What kind of transitions?
|
+-- 2-3 states, simple toggling?
|     --> if/else or bool flags (don't over-engineer)
|
+-- 4-8 states, clear transitions?
|     --> Code FSM (enum or IState)
|
+-- States group naturally into clusters?
|     --> HFSM (Locomotion > {Idle,Walk,Run}, Combat > {Melee,Ranged})
|
+-- AI with priorities, interrupts, parallel tasks?
|     --> Behavior Tree
|
+-- Need to return to previous state (back button, unpause)?
|     --> Stack-Based State Machine
|
+-- States tied to animations?
      --> Animator FSM (use unity-animation skill)