How to use a Dictionary in Godot

When storing data that needs to be easily retrieved, the Dictionary is the best and easiest tool for the job in any Godot developers arsenal.

In this guide we explain the basics of what a dictionary is, how to create one, retrieving the data, and how to manage your dictionary all in GDScript inside of the Godot Engine!


Prerequisites

Before you start this guide, we recommend you understand the basics of the Godot Editor and also how to use Variables in the Godot Engine, specifically GDScript.

Click here to read our guide on variables in Godot.


What is an Dictionary

The Dictionary, (also known in other programming languages as a Map) is a data structure that allows you to store data along side a key.

This data is tied to the key and allows easy storage and access of the data without any complex code or slow find functions.

The most important aspect to understand of the Dictionary is the Key and Value.

  • The Key is used to locate the information. This must be unique!
  • The Value can be any data you want associated to the key.

For example, lets say we want to store and retrieve all of the items based on a specific “rarity” words such as “common”, “rare”, or “ultra rare”.

We add all of our items as the value into the Dictionary using these rarity words as the key:

  • Common – Dirt, Rocks, Wood
  • Rare – Iron, Copper, Tin
  • Ultra Rare – Diamond, Platinum, Gold

We then ask the dictionary to give us all the value associated with the key. One example would be to ask the dictionary for all of the “rare” items.

This returns us the list of rare items: iron, copper, and tin.

This takes no special code and is very easy to use any script that needs easy storage and retrieval of data in your Godot game project!


How to use an Dictionary in Godot

Declaring an Dictionary

The dictionary is a variable so it must be declared as usual. We declare the dictionary variable by simply making it equal curly brackets as shown in the image below.

declaring the dictionary

Unlike arrays, in Godot 4.3 and below, you cannot declare dictionaries as statically typed. This means you have to make sure the data you are adding into your dictionary is correct for your use case.

However, like all other variables, we can export this to the editor to be managed using the @export keyword.

exporting the dictionary to the editor

When your script is added to a node, you can see the exported dictionary, it’s size, and the options to add a new key value pair.

adding new pairs to the dictionary using the exported editor menu

Clicking the small pencil icons next to New Key and New Value, we can see a large list of available types. When exporting dictionaries to the editor, you must tell it the specific types used.

showing the choice of key value types when adding a new pair to the dictionary through the exported editor

As shown in the image below, we selected the String type for our New Key and the int type for our New Value. We then press Add Key/Value Pair to add our key and value to the dictionary!

Showing the added new key value pair

Adding items to a Dictionary

Adding a new element to a dictionary is as simple as providing a key and value!

Dictionaries are interacted with square brackets.

Any data you put inside of the square brackets is used as the key.

Using the equals on this then sets the value of that key.

As shown in the image below, we set the value 10 into the key string “key”.

Setting the value and adding it are the same. If it does not exist it will add the new key to the dictionary.

Setting the dictionary "key" to 10

Retrieving items from a Dictionary

Retrieving items from the dictionary is even easier!

As shown in the image below, simply access the dictionary using the square brackets and put the key you want inside!

printing the value of "key" in the dictionary

Note: If your dictionary does not have the key it will cause and error in your code!
Use the has function inside of an if statement to check if your key exists before using the value.

checking if the dictionary has the "key" inside

If we want to get all of the keys from our dictionary, simple use the keys function. This will give us an array that contains all of the keys which can be used in loops or other code.

Getting all of the keys as an array from the dictionary

Similar to the keys function, we can use the values function to get all of the values contained in our dictionary as an array for looping or other uses.

Getting all of the values as an array from the dictionary

Managing a Dictionary

There are many useful functions to manage the keys and values inside your dictionary. Here are the most useful that you will use in your scripts.

The first is the clear function. This removes all keys and values from the dictionary.
This destroys all data inside of the dictionary. Be careful with this function!

Clearing the dictionary of all keys and values. This empties it of all data

Next is the merge function. This is the same as the append array function if you are familiar with that from our last guide.

This merges two dictionaries together, adding our second dictionary to the first. It now contains the keys and values of both.

We simply use the merge function and pass our second dictionary in and our two dictionaries are merged.

Showing the code of merging two dictionaries together

The last management function is the size function. This returns the amount of keys inside of our array!
If you have 5 keys in your array with data, the size function will return the integer 5.

Showing the code to get the size of the dictionary. This is how many key value pairs are in the dictionary

Advanced Usage

Now that you have the basics down, we encourage along your developer journey to learn how to use loops.

Loops allow you to go through each key and value in your dictionary and run code on them.

This is especially useful for looping through objects.

To learn how to use loops in Godot, click here to read our guide on loops in Godot!


Conclusion

Now you understand how to use Dictionaries in Godot!

Dictionaries are an essential tool when storing uniquely identifiable information and objects in your Godot project.

With this knowledge you can now tackle more complex topics that we cover on BlueRobotGuru!

Further Reading

Be the first to comment

Leave a Reply

Your email address will not be published.


*