npc-state-machine-design
Designs testable NPC state machines with explicit transitions and recovery. Use when villagers, enemies, workers, or companions become stuck or act unpredictably.
SKILL.mdplugins/all-skills-collection/skills/npc-state-machine-design/SKILL.md
GitHubNpc State Machine Design
Use when
NPC behavior is buried in conditionals, causing invalid transitions, repeated actions, or dead-end states.
Workflow
- Define the NPC's observable states, active goals, permitted transitions, entry/exit effects, and interruption rules.
- Separate sensing, state transition evaluation, action execution, and dialogue selection into testable stages.
- Specify timeout, retry, unreachable-target, resource-unavailable, and despawn/reload recovery behavior.
- Create table-driven tests for each transition and representative event sequences.
Required output
A state diagram or transition table, transition guards, failure recovery rules, and test cases.
Validation
- Every state has valid exits or a documented intentional terminal condition.
- Actions are not executed twice merely because a transition is re-evaluated.
- Interrupted and restored NPCs return to a valid state.
Guardrails
Do not invoke an expensive language model on every simulation tick; reserve generative calls for suitable, bounded decisions.