Back to Details

godot-state-machine-advanced

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Advanced State Machines

高级状态机

Hierarchical states, state stacks, and context passing define complex behavior management.
分层状态、状态栈和上下文传递定义了复杂行为的管理方式。

Available Scripts

可用脚本

hsm_logic_state.gd

hsm_logic_state.gd

Expert HSM base class with state stack management and validation.
具备状态栈管理与验证功能的专业HSM基类。

pushdown_automaton.gd

pushdown_automaton.gd

Stack-based state machine for interrupt-resume behavior (pause menus, cutscenes).
MANDATORY: Read hsm_logic_state.gd before implementing hierarchical AI behaviors.
基于栈的状态机，用于实现中断-恢复行为（如暂停菜单、过场动画）。
必须注意：在实现分层AI行为前，请先阅读hsm_logic_state.gd。

NEVER Do in Advanced State Machines

高级状态机中的绝对禁忌

  • NEVER forget to call exit() before enter() — Transition without exit? Previous state cleanup skipped = resource leaks (timers, tweens). ALWAYS exit → enter.
  • NEVER use push_state() without pop_state() — Pushed 100 interrupt states? Stack overflow + memory leak. EVERY push needs matching pop.
  • NEVER modify state during transition — 
    transition_to()
    called inside 
    exit()
    ? Re-entrant transition = undefined behavior. Flag transitions, execute after current completes.
  • NEVER skip state validation — 
    transition_to("AttackState")
    but state doesn't exist? Silent failure OR crash. Validate state exists before transition.
  • NEVER forget to process child states — Hierarchical state with sub-states? Parent 
    update()
    must call 
    current_child_state.update()
    for delegation.
  • NEVER use string state names in code — 
    transition_to("Idel")
    typo = silent failure. Use constants OR enums: 
    transition_to(States.IDLE)
    .
gdscript
undefined
  • 绝对不要在调用enter()之前忘记调用exit() —— 不执行exit就转换状态？会跳过之前状态的清理操作，导致资源泄漏（如计时器、补间动画）。必须始终遵循先exit再enter的顺序。
  • 绝对不要只调用push_state()而不调用pop_state() —— 推入100个中断状态？会导致栈溢出和内存泄漏。每一次push都必须对应一次pop。
  • 绝对不要在转换过程中修改状态 —— 在exit()内部调用transition_to()？重入式转换会导致未定义行为。应标记转换请求，在当前操作完成后再执行。
  • 绝对不要跳过状态验证 —— 调用
    transition_to("AttackState")
    但该状态不存在？会导致静默失败或崩溃。转换前必须验证状态是否存在。
  • 绝对不要忘记处理子状态 —— 带有子状态的分层状态？父状态的
    update()
    必须调用
    current_child_state.update()
    以实现委托处理。
  • 绝对不要在代码中使用字符串类型的状态名称 —— 输入错误如
    transition_to("Idel")
    会导致静默失败。请使用常量或枚举：
    transition_to(States.IDLE)
    。
gdscript
undefined

hierarchical_state.gd

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)
undefined
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)
undefined

State Base Class

状态基类

gdscript
undefined
gdscript
undefined

state.gd

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
undefined
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
undefined

Best Practices

最佳实践

  1. Separation - One state per file
  2. Signals - Communicate state changes
  3. Stack - Use push/pop for interruptions
  1. 分离原则 - 每个状态对应一个文件
  2. 信号机制 - 通过信号传递状态变更消息
  3. 栈的使用 - 利用push/pop处理中断场景

Reference

参考

  • Related: 
    godot-characterbody-2d
    , 
    godot-animation-player
  • 相关资源：
    godot-characterbody-2d
    , 
    godot-animation-player

Related

相关技能

  • Master Skill: godot-master
  • 核心技能：godot-master