🇺🇸English
Advanced State Machines
Hierarchical states, state stacks, and context passing define complex behavior management.
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 : Read hsm_logic_state.gd before implementing hierarchical AI behaviors.
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.
# hierarchical_state.gd
class_name HierarchicalState
extends Node
signal transitioned(from_state: String, to_state: String)
var current_state: Node
var state_stack: Array[Node] = []
func _ready() -> void:
for child in get_children():
child.state_machine = self
if get_child_count() > 0:
current_state = get_child(0)
current_state.enter()
func transition_to(state_name: String) -> void:
if not has_node(state_name):
return
var new_state := get_node(state_name)
if current_state:
current_state.exit()
transitioned.emit(current_state.name if current_state else "", state_name)
current_state = new_state
current_state.enter()
func push_state(state_name: String) -> void:
if current_state:
state_stack.append(current_state)
current_state.exit()
transition_to(state_name)
func pop_state() -> void:
if state_stack.is_empty():
return
var previous_state := state_stack.pop_back()
transition_to(previous_state.name)
State Base Class
# state.gd
class_name State
extends Node
var state_machine: HierarchicalState
func enter() -> void:
pass
func exit() -> void:
pass
func update(delta: float) -> void:
pass
func physics_update(delta: float) -> void:
pass
func handle_input(event: InputEvent) -> void:
pass
Best Practices
- Separation - One state per file
- Signals - Communicate state changes
- Stack - Use push/pop for interruptions
Reference
- Related:
godot-characterbody-2d, godot-animation-player
Related
- Master Skill: godot-master
Weekly Installs
84
Repository
thedivergentai/…c-skills
GitHub Stars
62
First Seen
Feb 10, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli81
codex80
opencode78
kimi-cli76
github-copilot76
amp76
