| name | godot-state-machine-advanced |
| description | Expert blueprint for hierarchical finite state machines (HSM) and pushdown automata for complex AI/character behaviors. Covers state stacks, sub-states, transition validation, and state context passing. Use when basic FSMs are insufficient OR implementing layered AI. Keywords state machine, HSM, hierarchical, pushdown automata, state stack, FSM, AI behavior. |
Available Scripts
Advanced HSM base delegator for propagating physics and input to sub-states.
Professional Pushdown Automata for interruptive state (Pause/Menu) stacking.
Decoupled context object pattern for passing persistent data between states.
Expert transition validation logic to prevent illegal state changes.
Automated Logic-to-AnimationTree syncing with state-based travel logic.
Orchestration for parallel state machines (e.g., Move + Attack).
Data-driven state definition using custom Godot Resources (.tres).
Handling resume-from-stack logic vs fresh entry events.
Debug ring-buffer for tracking state transition history and stack depth.
Auto-transition component for finite states like Stun or Dash.
MANDATORY: For hierarchy / pushdown / guards read hsm_hierarchical_base.gd, hsm_pushdown_stack.gd, hsm_transition_guard.gd (plus hsm_logic_state.gd for leaf behaviors).
Decision Tree — Which Machine?
NEVER Do (Expert State Rules)
Hierarchy & Delegation
- NEVER forget to propagate physics/input to children — In an HSM, failing to call
child.physics_update() from the parent's _physics_process orphans child logic.
- NEVER use deep nesting (>3 levels) — Extreme hierarchy creates "State Spaghetti." If logic is that complex, consider a Behavior Tree or Utility AI.
Transitions & Lifecycle
- NEVER call enter() without a preceding exit() — Skipping exit logic leaves timers, tweens, or audio loops running in the background, causing resource leaks.
- NEVER modify state during a transition frame — Re-entrant
transition_to() calls inside enter() cause recursion crashes. Use call_deferred if immediate sub-transitioning is required.
- NEVER hardcode state names as strings — Typos like
transition_to("Idel") are silent killers. Use class_name based checks OR Constants.
Architecture & Context
- NEVER use global singletons for state data — Coupling states to
GameManager.player_health makes them non-reusable. Pass a Context object.
- NEVER push states indefinitely — In a Pushdown Automaton, every
push_state MUST have a retirement plan (pop_state) to avoid stack overflow.
- NEVER assume state re-entry is always a fresh start — Resuming from a stack pop should often bypass "Entry SFX/VFX"; use re-entry flags.
Implementation — Scripts Are Source of Truth
Do NOT copy inline HierarchicalState / push_state samples. Prior body double-exit()ed and ignored resume messages.
MANDATORY route:
Pushdown contract (from script — single exit, resume msg):
# See hsm_pushdown_stack.gd — do not reimplement
func push_state(state_path: String, msg: Dictionary = {}) -> void: ...
func pop_state() -> void:
# old.exit(); stack.back().enter({"is_resume": true})
pass
Expert State Machine Patterns
1. HSM Visualizer (Debug Tool)
Use a specialized Control node with _draw() to visualize the current state stack/hierarchy in the viewport for immediate debugging [3, 11].
class_name HSMVisualizer extends Control
@export var state_machine: Node
func _draw() -> void:
var font := ThemeDB.fallback_font
var pos := Vector2(20, 20)
# Recursively draw active state names...
draw_string(font, pos, "Active: " + state_machine.current_state.name)
2. State-Based Audio (Decoupled)
Avoid hardcoding audio.play() inside state enter() methods. Use a syncer that listens to state_changed and maps state names to AudioStream resources [12, 13].
class_name StateAudioSyncer extends Node
@export var state_machine: Node
@export var audio_map: Dictionary # { "Jump": preload("jump.wav") }
func _ready() -> void:
state_machine.state_changed.connect(_on_state_changed)
func _on_state_changed(_old, new_state: Node):
if audio_map.has(new_state.name):
$AudioPlayer.stream = audio_map[new_state.name]
$AudioPlayer.play()
3. Transition Cost (Utility AI)
Enable states to evaluate their own "weight" based on context. The StateMachine polls sibling costs and transitions to the lowest-cost behavior [17, 18].
# CostState.gd (Base)
func get_cost(context: Dictionary) -> float:
return 10.0 # Default weight
# UtilityStateMachine.gd
func _physics_process(_d: float) -> void:
var best_state: Node = current_state
var low_cost: float = INF
for child in get_children():
var cost = child.get_cost(context)
if cost < low_cost:
low_cost = cost
best_state = child
if best_state != current_state:
transition_to(best_state.name)
Deep recipes (on demand)
LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.
Reference
Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.
Official Documentation
- Using signals — Drive
state_changed / transition fan-out so listeners (anim, audio, AI) stay decoupled from enter/exit bodies.
- Scene organization — Child-node state ownership and signal-up / call-down so the machine orchestrates without sibling hard-coupling.
- What are Godot classes — Prefer composed state nodes +
class_name over deep inheritance trees for layered AI behaviors.
- Idle and Physics Processing — Why HSMs must forward
_physics_process / _process into the active child (or hierarchy) every tick.
- Using SceneTree —
call_deferred transitions avoid re-entrant transition_to() crashes inside enter().
- Godot notifications — Safe wiring timing for initial
enter() relative to _ready and parent caches.
- Resources — Data-driven state definitions (
.tres) for modular AI without baking scripts into every actor.
- Using AnimationTree — Logic-to-AnimationTree travel when gameplay HSM states map to blend/state-machine graphs.
- AnimationNodeStateMachinePlayback —
travel() / start() APIs used by animation syncers tied to HSM state names.
- Node — Child lookup, process modes, and lifecycle hooks state nodes inherit as scene-tree citizens.
- InputEvent — Typed events parents forward into
handle_input on the active state.
- Timer — Finite-duration states (stun, dash) via one-shot timers that emit transition signals.
Related Skills
Prerequisites
- godot-project-foundations — Scene ownership and project layout conventions every HSM root and child state scene assumes.
- godot-gdscript-mastery — class_name, typed Dictionaries/payloads, and Callables needed for guards, deferred transitions, and context objects.
- godot-signal-architecture — Signal-up transition events without circular graphs where states emit and also listen to themselves.
Complements
- godot-composition — Drop HSM / VSM as a StateComponent under a composition root instead of bloating the actor script.
- godot-input-handling — Sense-layer sampling; states receive directions/actions via handle_input rather than polling globals.
- godot-characterbody-2d — Locomotion states call move_and_slide / velocity APIs on the actor passed through context.
- godot-animation-tree-mastery — Blend trees and AnimationNodeStateMachine graphs that HSM syncers travel into by state name.
- godot-resource-data-patterns — Tunable state Resources (speeds, stun durations, AI weights) separate from runtime Node lifecycle.
- godot-2d-animation — Sprite / AnimationPlayer presentation when a lighter sync path than a full AnimationTree is enough.
Downstream / consumers
- godot-combat-system — Hit-stun, attack windup, and death stacks are classic pushdown / HSM consumers on fighters.
- godot-ability-system — Cast, channel, and cooldown phases map cleanly to guarded transitions and timed states.
- godot-turn-system — Turn phases and interrupt stacks reuse pushdown / concurrent machine orchestration patterns.
- godot-dialogue-system — Cutscene and dialogue overlays push over gameplay states and must pop without losing context.
Master
- godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting architecture concern.
