GDScript match: Switch Statements, Patterns and Guards

match compares one value against a list of patterns and runs the first branch that fits. It is GDScript's switch:

extends Node

func reaction(command: String) -> String:
	match command:
		"jump":
			return "Up!"
		"duck":
			return "Down!"
		"left", "right":
			return "Moving sideways"
		_:
			return "Unknown command"

func _ready():
	for command in ["jump", "right", "dance"]:
		print(command, ": ", reaction(command))

jump: Up!
right: Moving sideways
dance: Unknown command

• Each branch is a pattern followed by : and an indented block.
• Commas list several values in one branch.
• _ matches anything, so it works as the default and goes last.
• There is no break and no fall through: after one branch runs, the match is done.

match with Enums

The most common use is a state machine, with one branch per state of an enum:

extends Node

enum State { IDLE, CHASE, ATTACK }

var state := State.IDLE

func think(distance: float) -> void:
	match state:
		State.IDLE:
			if distance < 200:
				state = State.CHASE
		State.CHASE:
			if distance < 30:
				state = State.ATTACK
		State.ATTACK:
			if distance > 50:
				state = State.CHASE
	print(distance, " -> ", State.find_key(state))

func _ready():
	for distance in [300.0, 150.0, 20.0, 80.0]:
		think(distance)

300.0 -> IDLE
150.0 -> CHASE
20.0 -> ATTACK
80.0 -> CHASE

Binding a Value with var

var name as a pattern matches anything and stores the value in name for that branch:

extends Node

func describe(value) -> String:
	match value:
		0:
			return "zero"
		var other:
			return "something else: %s" % other

func _ready():
	print(describe(0))
	print(describe(42))

zero
something else: 42

Guards with when

Since Godot 4.3, a pattern may end with when and a condition. The branch is taken only if the pattern fits and the condition is true:

extends Node

func grade(score: int) -> String:
	match score:
		100:
			return "perfect"
		var s when s >= 90:
			return "A"
		var s when s >= 75:
			return "B"
		_:
			return "keep practicing"

func _ready():
	for score in [100, 93, 80, 40]:
		print(score, ": ", grade(score))

100: perfect
93: A
80: B
40: keep practicing

Array Patterns

An array pattern matches an array of the same length, element by element. .. at the end allows any number of extra elements:

extends Node

func read_move(move: Array) -> String:
	match move:
		[]:
			return "no move"
		["walk", var steps]:
			return "walk %d steps" % steps
		["say", ..]:
			return "say " + " ".join(move.slice(1))
		_:
			return "unknown move"

func _ready():
	print(read_move([]))
	print(read_move(["walk", 3]))
	print(read_move(["say", "hello", "there"]))
	print(read_move(["fly"]))

no move
walk 3 steps
say hello there
unknown move

Dictionary Patterns

A dictionary pattern checks keys and values. The dictionary must have exactly the listed keys, unless the pattern ends with ..:

extends Node

func pick_up(item: Dictionary) -> String:
	match item:
		{"type": "coin", "value": var value}:
			return "+%d gold" % value
		{"type": "key", ..}:
			return "a key"
		_:
			return "nothing useful"

func _ready():
	print(pick_up({"type": "coin", "value": 5}))
	print(pick_up({"type": "key", "color": "red"}))
	print(pick_up({"type": "rock"}))

+5 gold
a key
nothing useful

Matching on a Type

match compares values, not types. To branch on a type, match on typeof():

extends Node

func kind(value) -> String:
	match typeof(value):
		TYPE_INT, TYPE_FLOAT:
			return "number"
		TYPE_STRING:
			return "text"
		TYPE_ARRAY:
			return "list"
		_:
			return "other"

func _ready():
	for value in [1, 2.5, "a", [1], null]:
		print(kind(value))

number
number
text
list
other

match or if?

Use match when you compare one value against several fixed options, like states, commands or item types. Use if and elif when each branch tests a different condition, such as hp < 10 and then is_on_floor().