Match Statement

Hello and welcome to the GDScript fundamental tutorial series.

In this episode, I go over coding match statements in Godot GDScript.

What is a match statement?

A match statement, just like a case statement, is a type of selection control mechanism used to allow the value of a variable or expression to change the control flow of program execution in search and map.

Basically, you use a variable to ‘match’ a pattern and execute the code inside the match statement.

# Example of a match statement chain

var health: int = 1

match x:
    1:
        # If health == 1, run this block of code
    _:
        # If nothing matches, run this block of code

Types of match patterns

• Constant Pattern
• Variable Pattern
• Wildcard Pattern
• Binding Pattern
• Array Pattern
• Dictionary Pattern
• Multiple Patterns

Constant Pattern

A constant pattern is when you use a primitive/literal data type.

These would include integers, floats, booleans, strings, etc.

When matching string values, keep in mind that they are case sensitive.

var health: int = 1

match health:
    1:
        # Constant Pattern Block
    "Hello":
        # Constant Pattern Block
    2.03:
        # Constant Pattern Block
    true:
        # Constant Pattern Block

Variable Pattern

With GDScript, you can use variables as a match pattern.

var health: int = 1
var matchPatternOne: int = 1

match x:
    matchPatternOne:
        # Variable Pattern Block

Wildcard Pattern

A wildcard pattern is when you use the underscore symbol as a match pattern _.

You use the wildcard pattern when you want to match everything.

It can also be thought of as a “default” block statement, meaning it will always run when all other match patterns fail.

Since the match patterns run in chronological order, it is best to use the wildcard pattern as the last pattern in your match statement chain.

var health: int = 1

match x:
    _:
        # Wildcard Pattern Block will always run when everything fails

Binding Pattern

A binding pattern catches everything just like the wildcard pattern. The difference is the binding pattern assigns the value acquired into a variable that can be used inside the binding pattern match block.

var health: int = 1

match x:
    var matchValue:
        # Binding Pattern Block, matchValue will equal the match variable
        # matchValue = x

Array Pattern

You can use arrays as a match pattern.

Every single element in the array is a match pattern in itself.

You can also use sub-patterns inside your array. The .. is a sub-pattern. Using the .. makes the array an open-ended array.

Arrays patterns are tested in the following way:

1. The length of the array is tested. The match fails if the array lengths are not the same. Unless you use the .. sub-pattern.

2. The match array is tested against the array pattern. If a single element is different, then the pattern fails.

var health: int = [1,2,3]

match x:
    []:
        # only an empty array will match
    [1,2]:
        # An array of only [1,2] will match
    [1,2,..]:
        # An array with the first and second elements being [1,2] will match
        # The array can have any other value after the third element and still match

Dictionary Pattern

A dictionary pattern is used to test against dictionaries.

Sub-patterns such as .. can also be used.

Dictionary patterns are tested in the following way:

1. The length of the dictionary is tested. The match fails if the dictionary lengths are not the same. Unless you use the .. sub-pattern.

2. Key and values are tested. If a single element is different, then the pattern fails.

var health: int = {"key": "value", "key2", "value2"}

match x:
    {}:
        # only an empty dictionary will match
    {"key": "value"}:
        # A dictionary of {"key": "value"} will match
    {"key": "value", ..}:
        # A dictionary of {"key": "value"} will match followed by another key/value pair

Multiple Pattern

You can specify multiple patterns as long as they are separated by commas:

var health: int = 3

match x:
    1,2,3,4,5:
        # Matches any variable that has an integer in the range of 1-5

Resources

Github Project:

• Link to Github Project

Godot Tutorials Resources

• Youtube
• Twitter
• Reddit
• Github
• Trello