3

Description

"This article describes how a basic character can have several states with different behaviours.\r\n> [!NOTE]\r\n> The main code for the state machine as well as for the state can be found at the bottom of this page!\r\n\r\n\r\nThe basic setup for the character looks like this:\r\n\r\nIt's a simple characterbody2D with a sprite graphic, a collision shape and a navigationAgent2D.\r\n\r\nThe code for the character looks like this:\r\n```\r\nclass_name Worker extends CharacterBody2D\r\n\r\n@export var walk_speed: float = 1.0\r\nvar is_running: bool = false\r\nvar is_stopped: bool = true\r\n\r\n#reference to the sprite graphic\r\n@onready var sprite: Sprite2D = $Sprite2D\r\n\r\n#reference to the navigation agent\r\n@onready var nav_agent: NavigationAgent2D = $NavigationAgent2D\r\n\r\nfunc _physics_process(_delta: float) -> void:\r\n\t#sets the next position of the navigation agent\r\n\tvar target_pos: Vector2 = nav_agent.get_next_path_position()\r\n\t#set the moving direction where the navigation agent will go to\r\n\tvar move_dir: Vector2 = position.direction_to(target_pos)\r\n\tmove_dir = move_dir.normalized()\r\n\t\r\n\t#don't move if navigation is done or stopped.\r\n\tif nav_agent.is_navigation_finished() or is_stopped:\r\n\t\tmove_dir = Vector2.ZERO\r\n\t\r\n\t#set velocity and actually move\r\n\tvelocity = move_dir * walk_speed\r\n\tmove_and_slide()\r\n\t\r\n\t#flip sprite accordingly\r\n\tif velocity.x < 0:\r\n\t\tsprite.flip_h = true\r\n\telse:\r\n\t\tsprite.flip_h = false\r\n\r\n#call function to set a new position the agent should go to\r\nfunc move_to_pos(target_pos: Vector2) -> void:\r\n\tif not nav_agent:\r\n\t\tnav_agent = get_node(\"NavigationAgent2D\")\r\n\t\r\n\t#since we want to set a new position agent isn't stopped anymore\r\n\tis_stopped = false\r\n\t\r\n\t#simply set the new position for the navigation agent\r\n\tnav_agent.target_position = target_pos\r\n\tpass\r\n\r\n```\r\n\r\nAt the bottom you find the code for the statemachine. If you added the script to your project you'll be able to simply add a state machine to the character\r\n\r\n\r\nThen connect the navigationAgent's signal for being finished with navigation to the newly added state machine\r\n\r\n\r\n\r\nTo add a new state to the machine simply add a node as child of the state machine first\r\n\r\n\r\nThen create a new gdscript and let it inherit\/extend from State. Attach the new script to the newly created node\r\n\r\n\r\nSet the reference to the character in the inspector for the newly added state\r\n\r\n\r\nDon't forget to set the new state as initial state to the state machine in the inspector\r\n\r\n\r\n\r\nIn this example the wake_up state is pretty simple. The character wakes up and transitions itself into the next state.\r\n```\r\n# wake_up.gd\r\nextends State\r\n\r\nfunc enter() -> void:\r\n\tsuper.enter()\r\n\tprint(\"Good morning!\")\r\n\tstate_machine.change_state(\"working\")\r\n\r\nfunc exit() -> void:\r\n\tsuper.exit()\r\n\tprint(\"Time to get things done...\")\r\n```\r\n\r\nThen after a timer signal and some while in the working state it transists to the next state.\r\n```\r\nextends State\r\n\r\nvar home_position : Vector2\r\n@export var max_wander_range : float = 6\r\n@export var min_wait_time : float = 0.2\r\n@export var max_wait_time : float = 2.0\r\n\r\nfunc enter() -> void:\r\n\tsuper.enter()\r\n\tprint(\"Working...\")\r\n\t_new_wander_position()\r\n\r\nfunc navigation_complete():\r\n\tvar wait_time = randf_range(min_wait_time, max_wait_time)\r\n\tawait get_tree().create_timer(wait_time).timeout\r\n\t\r\n\tif not active:\r\n\t\treturn\r\n\t\r\n\t_new_wander_position()\r\n\r\nfunc _new_wander_position():\r\n\tvar pos = home_position * randf_range(0, max_wander_range)\r\n\tcontroller.move_to_pos(pos)\r\n\r\nfunc _on_timer_timeout() -> void:\r\n\tstate_machine.change_state(\"good_night\")\r\n```\r\n\r\n\r\nAfter working the state transists to the good_night state:\r\n```\r\nextends State\r\n\r\nfunc enter() -> void:\r\n\tsuper.enter()\r\n\tprint(\"Whoa what a day! Time to get some sleep.\")\r\n```\r\n\r\nIf you run the whole project now your console should be looking something like this:\r\n\r\n\r\n> [!IMPORTANT]\r\n> this has been a very shallow introduction to the concept of state machines and how they can be set up in godot. In a full game, each state would of course be doing a lot more, but this should serve as a starting point for implementing a state machine in your own project\r\n\r\n## Explore more\r\n[youtube:Starter state machines in Godot 4](https:\/\/www.youtube.com\/watch?v=oqFbZoA2lnU){data-author=\"The Shaggy Dev\"}\r\n[youtube: Finite State Machines in Godot 4 in Under 10 Minutes ](https:\/\/www.youtube.com\/watch?v=ow_Lum-Agbs){data-author=\"Bitlytic\"}"

Main code

############################################################################################################################
state.gd
########
@icon("res://_icons/state_icon.svg")
class_name State extends Node

#decide whether the current state is active or not
var active: bool = false
#reference to the state machine
var state_machine: StateMachine = null
#reference the character you want to control
var controller: Worker
@export_node_path("Worker") var controller_path: NodePath

#called when state is first initialized.
func initialize() -> void:
	#register itself its state machine
	state_machine = get_parent()
	#register the character node
	controller = get_node(controller_path)

#called when state is entered
func enter() -> void:
	active = true

#called when state has exited
func exit() -> void:
	active = false

#called every frame this state is active
func update(_delta: float) -> void:
	pass

#called every physics fame this state is active
func physics_update(_delta: float) -> void:
	pass

#called when the controller has completed navigation
func nav_completed() -> void:
	pass

############################################################################################################################
statemachine.gd
###############
@icon("res://_icons/statemachine_icon.svg")
class_name StateMachine extends Node

#set the initial state the machine starts with
@export var initial_state: State
#the current running state of the machine
var current_state: State
#the registered states the machine knows about
var states: Dictionary = {}

func _ready() -> void:
	#wait for the nav mesh server to be initialized
	await NavigationServer2D.map_changed
	
	#initialize all the children states
	for child in get_children():
		if child is State:
			states[child.name.to_lower()] = child
			child.initialize()
	#set the initial state
	if initial_state != null:
		change_state(initial_state.name)

#called when transition from one state to the other has to be made
func change_state(state_name: String) -> void:
	var new_state = states.get(state_name.to_lower())
	
	#safety fallback
	if new_state == null: return
	
	#nothing to do if state stays the same
	if new_state == current_state: return
	
	#exit the current state
	if current_state != null:
		current_state.exit()
	
	current_state = new_state
	#enter the new state
	new_state.enter()

#run the process function for the current state
func _process(delta: float) -> void:
	if current_state != null:
		current_state.update(delta)
		
#run the physics process function for the current state
func _physics_process(delta: float) -> void:
	if current_state != null:
		current_state.physics_update(delta)
		
func _on_navigation_agent_2d_navigation_finished() -> void:
	if current_state != null:
		current_state.nav_completed()

Comments