If you are searching for a switch statement in GDScript, you will not find one. Godot uses match instead, and it does considerably more than a traditional switch.
Basic Syntax
The structure is straightforward:
match state:n "idle":n play_idle()n "run":n play_run()n _:n print("unknown state")The underscore is the wildcard — the equivalent of default. It matches anything, so it must always come last.
The Difference That Catches People Out
There is no fall-through. In C-style switch statements you need break to stop execution continuing into the next case. In GDScript, the first matching branch runs and the match ends.
This is almost always what you wanted anyway, and it removes an entire category of bug.
Matching Multiple Values
Separate patterns with a comma:
match damage_type:n "fire", "lava", "plasma":n apply_burn()n "ice", "frost":n apply_slow()Binding Patterns
This is where match goes beyond a switch. You can capture the matched value into a variable:
match value:n 0:n print("zero")n var other:n print("got ", other)Matching Arrays
Arrays match on size and contents, and you can bind elements:
match command:n ["move", var x, var y]:n move_to(x, y)n ["quit"]:n quit_game()Use .. to allow extra elements: ["move", ..] matches any array starting with “move”.
Matching Dictionaries
match event:n {"type": "click", "pos": var p}:n handle_click(p)The dictionary must contain the listed keys. Add .. to permit others.
Using Constants and Enums
Match works cleanly with enums, which is the idiomatic way to handle state machines in Godot:
enum State { IDLE, RUN, JUMP }nnmatch current_state:n State.IDLE:n idle_logic()n State.RUN:n run_logic()When Not to Use It
For two branches, if/else is clearer. match earns its place at three or more cases, or whenever you are destructuring arrays and dictionaries — which is where it genuinely beats a switch statement.
More Godot resources in our Godot collection.
