state-machine

State Machines in Godot 4.3+

Choose the right FSM pattern for your complexity level. All examples target Godot 4.3+ with no deprecated APIs.

Related skills: player-controller for movement state integration, ai-navigation for AI state patterns, resource-pattern for resource-based state configuration, animation-system for AnimationTree states driven by FSM, dialogue-system for dialogue flow as a state machine, ability-system for caster state gating (casting/stunned), limboai for the LimboAI addon's HSM (BTState) if you need a behavior tree alongside your FSM, beehave for a GDScript-only BT alternative.

When to reach for an addon: This skill covers the built-in FSM patterns (enum, node-based, resource-based). If your agent needs a full behavior tree, see limboai (C++ + HSM, Godot 4.6+) or beehave (pure GDScript, Godot 4.1+) instead.

---

1. Approach Comparison

Approach	Complexity	Best For
Enum-Based	Low	Simple objects, fewer than 5 states
Node-Based	Medium	Characters with complex behavior
Resource-Based	High	Data-driven or editor-configurable AI

When you recommend one, name the approach you rejected and the factor that decided it (state count, independent concerns, designer editing) — "node-based, not an enum with match, because seven states with their own enter/exit logic outgrow one script". A pick with no named alternative cannot be overruled.

---

2. Approach 1: Enum-Based (Simplest)

Use when you have a small number of states and no significant enter/exit logic.

GDScript

extends CharacterBody2D

enum State { IDLE, PATROL, CHASE, ATTACK }

@export var patrol_range: float = 200.0
@export var chase_range: float = 300.0
@export var attack_range: float = 50.0
@export var speed: float = 80.0

var current_state: State = State.IDLE
var patrol_target: Vector2 = Vector2.ZERO

@onready var player: Node2D = get_tree().get_first_node_in_group("player")


func _physics_process(delta: float) -> void:
	match current_state:
		State.IDLE:
			_state_idle()
		State.PATROL:
			_state_patrol()
		State.CHASE:
			_state_chase()
		State.ATTACK:
			_state_attack()

	move_and_slide()


func _state_idle() -> void:
	velocity = Vector2.ZERO
	if _player_in_range(chase_range):
		current_state = State.CHASE
	elif randf() < 0.005:
		patrol_target = global_position + Vector2(randf_range(-patrol_range, patrol_range), 0.0)
		current_state = State.PATROL


func _state_patrol() -> void:
	var direction := (patrol_target - global_position)
	if direction.length() < 4.0:
		current_state = State.IDLE
		return
	velocity = direction.normalized() * speed
	if _player_in_range(chase_range):
		current_state = State.CHASE


func _state_chase() -> void:
	if not is_instance_valid(player):
		current_state = State.IDLE
		return
	if _player_in_range(attack_range):
		current_state = State.ATTACK
		return
	if not _player_in_range(chase_range):
		current_state = State.PATROL
		return
	velocity = (player.global_position - global_position).normalized() * speed


func _state_attack() -> void:
	velocity = Vector2.ZERO
	if not _player_in_range(attack_range):
		current_state = State.CHASE


func _player_in_range(range: float) -> bool:
	if not is_instance_valid(player):
		return false
	return global_position.distance_to(player.global_position) <= range