Dictionary

A dictionary is a data structure that stores a set of key-value pairs. It maps keys to values and allows you to retrieve a value by its key.

If you take a phone book, for example, you can quickly find a person's phone number if you know their name. No matter how big the phone book is, you can find the phone number in about the same amount of time. It's similar to a dictionary in programming. In this example, the name corresponds to the key, and the phone number corresponds to the value.

Dictionaries are useful to store data that you can look up quickly. They have a roughly constant time complexity for looking up values, which means that retrieving a value with its key takes about the same time, regardless of the size of the dictionary.

In other programming languages, dictionaries are also known as associative arrays, maps, or hash tables.

Creating a dictionary in GDScript

Here is the syntax to create a dictionary in GDScript:

var dictionary := {
    "godot": "a game engine", 
    "gdscript": "a programming language"
}

This creates a dictionary with two key-value pairs. The keys are "godot" and "gdscript", and the values are "a game engine" and "a programming language". The dictionary maps the key "godot" to the value "a game engine", and the key "gdscript" to the value "a programming language".

In GDScript, you can also use the following syntax. It's inspired by the programming language Lua. In the dictionary below, the keys are on the left, godot and gdscript, and the values are on the right, "a game engine" and "a programming language". It is equivalent to the previous example:

var dictionary := {
    godot = "a game engine", 
    gdscript = "a programming language"
}

But be careful, when using the Lua-inspired syntax, the key cannot use the value of a variable, reserved keywords of the GDScript language, or contain spaces.

Here's a more realistic dictionary example, which you may use to store the positions of chess pieces in a game. It maps a Vector2Vector2 position on a chess board to a hypothetical ChessPiece object:

var chess_pieces := {
    Vector2(0, 0): ChessPiece(Piece.Rook, Color.White),
    Vector2(0, 1): ChessPiece(Piece.Knight, Color.White),
    Vector2(0, 2): ChessPiece(Piece.Bishop, Color.White),
    Vector2(0, 3): ChessPiece(Piece.Queen, Color.White),
    Vector2(0, 4): ChessPiece(Piece.King, Color.White),
    Vector2(0, 5): ChessPiece(Piece.Bishop, Color.White),
    Vector2(0, 6): ChessPiece(Piece.Knight, Color.White),
    Vector2(0, 7): ChessPiece(Piece.Rook, Color.White),
    Vector2(1, 0): ChessPiece(Piece.Pawn, Color.White),
    Vector2(1, 1): ChessPiece(Piece.Pawn, Color.White),
    # ...
}

Iterating over a dictionary

You can list all keys of a dictionary by calling the dictionary's .keys() method, and all values with .values().

For example:

# Print all the positions of the chess pieces
for position in chess_pieces.keys(): 
    print(position)

# Print all the chess piece objects
for piece in chess_pieces.values():
    print(piece)

Note that if you write a for loop like this without calling any method, it will iterate over the keys of the dictionary by default:

# This also prints all the positions of the chess pieces
for grid_position in chess_pieces: 
    print(grid_position)

Accessing individual values in a dictionary

You access the values in a dictionary with square brackets:

var dictionary := {
    "godot": "a game engine", 
    "gdscript": "a programming language"
}

func _ready() -> void:
    # Print the value associated with the key "godot"
    print(dictionary["godot"])

Writing dictionary["godot"] retrieves the value "a game engine" associated with the key "godot". And writing dictionary["gdscript"] retrieves the value "a programming language" associated with the key "gdscript".

You can use this to read and modify values in a dictionary. Let's bring back our chess example:

var chess_pieces := {
    Vector2(0, 0): ChessPiece(Piece.Rook, Color.White),
    Vector2(0, 1): ChessPiece(Piece.Knight, Color.White),
    # ...
}

When iterating over the dictionary, you can access the value associated with each key like this:

for grid_position in chess_pieces: 
    var chess_piece = chess_pieces[grid_position]

You can also add key-value pairs to a dictionary or modify existing values like this:

func _ready() -> void:
    dictionary["sophia"] = "a Godot mascot, reminiscent of Godette, created by Tyson Tan"

This adds a new key-value pair to the dictionary. The key is "sophia", and the value is "a Godot mascot, reminiscent of Godette, created by Tyson Tan".