Godot State Machine Advanced

Available Scripts

hsm_hierarchical_base.gd

Advanced HSM base delegator for propagating physics and input to sub-states.

hsm_pushdown_stack.gd

Professional Pushdown Automata for interruptive state (Pause/Menu) stacking.

hsm_state_context.gd

Decoupled context object pattern for passing persistent data between states.

hsm_transition_guard.gd

Expert transition validation logic to prevent illegal state changes.

hsm_animation_syncer.gd

Automated Logic-to-AnimationTree syncing with state-based travel logic.

hsm_concurrent_logic.gd

Orchestration for parallel state machines (e.g., Move + Attack).

hsm_resource_state_loader.gd

Data-driven state definition using custom Godot Resources (.tres).

hsm_reentry_aware_state.gd

Handling resume-from-stack logic vs fresh entry events.

hsm_state_history_logger.gd

Debug ring-buffer for tracking state transition history and stack depth.

hsm_state_timer_component.gd

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:

• Hierarchy / physics-input forward: hsm_hierarchical_base.gd
• Push / pop with enter({"is_resume": true}): hsm_pushdown_stack.gd
• Illegal transition blocking: hsm_transition_guard.gd
• Context payload: hsm_state_context.gd

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.