If you are familiar with python dictionaries, you will easily be able to follow along in this godot dictionary tutorial. A lot of the same concepts apply. In this tutorial I will go through a number of examples to give you an in depth understand of gdscript dictionaries and how you can use them in your godot projects. Want to rather watch video? Here is the video version:

For this tutorial I will be using the latest version of godot at the time of writing this article. Which is godot version 3.2. Since dictionaries are quite a standard concept I’m hoping this will still apply to you in new versions of godot going forward.

Let’s start off with launching godot and just creating our project. Call your project Godot Dictionary Tutorial.

Go ahead and just create a gdscript call it godot dictionary example.

You should now have that. Let’s add some code.

Most basic example of godot dictionary

extends Node func _ready(): var dict = {"name":"generalistprogrammer","website":"https://generalistprogrammer.com"} print(dict)

Make sure to just add a node in your scene as well before running otherwise this won’t work.

Also attach your script to the node.

Once done hit play in your output you should see this.

godot dictionary tutorial basic output example

So now we have the basics of a very simple dictionary which holds my name and website. Let’s look at some of the methods we have available to use for dictionaries in gdscript. Then I will follow this up with some examples.

Godot dictionary available methods

clear() – This method will let us clear our dictionary so that it is a blank dictionary. This especially is useful for initializing our dictionary to be blank if we had to loop through some data and only want to assign data from that loop to our dictionary.

duplicate ( bool deep=False ) – This method will help us make a copy of a dictionary. The deep parameter will tell gdscript if we want to copy elements which are nested inside our dictionary. If false we will just do a shallow copy which will return the first level of items in our dictionary.

empty ( ) – This method will simply just return true or false if our dictionary is empty.

erase ( Variant key ) – For this method you can pass a key for your dictionary to remove a specific item from your godot dictionary. It is important to know that this does not get passed by reference while iterating through a dictionary. What this means is when iterating through a dictionary it will not be able to erase items. The method will return true or false depending on whether it found the item you trying to remove.

get ( Variant key, Variant default=null ) – With this method you can get the value of an item in your dictionary. The second parameter dictates what value must be passed back in the event of your dictionary item not being found. So from this you can see you can either get back a value if the dictionary item exists or you can get back a null by default if it does not exist.

has ( Variant key ) – This method will just tell us if a dictionary has a certain key or not and will return true or false depending on which it is.

has_all ( Array keys ) – Has all will take in an array of keys to check if all of them exist. This is really useful if you need to validate a dictionary and it needs to be of a certain structure.

hash ( ) – This generates a hash from the content of a dictionary to help you compare dictionaries more accurately. Where a straight compare between dictionaries may have unwanted detail such as memory addresses and other factors which would make a comparison between two dictionaries fail.

keys ( ) – This is another useful function which will return all the available keys in a dictionary in an array.

size ( ) – Will give you back a size of your dictionary. In other words how many keys you have in your dictionary. It is important to note that this only counts the top level items in your dictionary and doesn’t do a deep count.

values ( ) – This will give you a list of the values in your dictionary. Again this is important to note that this does not give you a deep list of your values and only returns the top level.

Godot nested dictionaries or godot dictionary in dictionary example

Before we go over all the examples of the above methods let’s first look at how we can nest dictionaries inside other dictionaries. Just so that we can get all the strange variations out of the way.

To nest a dictionary you simply need to give it another key and add some more curly braces. Here is a simple example of a dictionary in a dictionary.

var dict = {"name":"generalistprogrammer", "skills": {"frontend":"javascript","backend":"golang","gamedevelopment":"godot"} }

So as you can see from above we have added a 2nd key called skills and then under that key we have a dictionary showing off my frontend, backend and gamedevelopment skills. Pretty simple why not try that in gdscript and run it.

Should end up with an output like this.

Godot array of dictionaries

Similar to dictionaries which can live in other dictionaries we can have a whole array live inside of a dictionary or can have an array of dictionaries. Here is an example of having an array inside of a dictionary.

var dict = {"name":"generalistprogrammer", "skills": ["javascript","golang","godot"]

So very similar to doing this with dictionaries. We just use [] instead to make it of a type array.

Let’s now look how we can have an array of dictionaries.

var arrayofdict = [{"name":"generalistprogrammer"}, {"skills":["javascript"]}] print(arrayofdict[0].name)

So with this our print is selecting the first array item, then giving back our first dictionary and then we access the name field. This should print this in your output when you run this code.

So that’s how easy it is to nest arrays in dictionaries and dictionaries in arrays in gdscript. Let’s now start looking at how you can access values in your godot dictionary.

Godot access dictionary

There are two ways to access your dictionary, one is to use it’s key name and the other is to use the get method provided by gdscript. Here are basic examples of both.

var dict = {"name":"generalistprogrammer"} print(dict.name) print(dict.get('name'))

So since we have a key of name, we can use dict.name or dict.get(‘name’) to access our name value. Simple hey? Let’s move on to some of the other methods you can use.

Gdscript dictionary example – lets run through all functions

Go ahead and add this code to your project. These examples should give you a deep understanding of dictionaries and their functions.

extends Node func _ready(): var dict = {"name":"generalistprogrammer"} var dictdeep = {"name":"generalistprogrammer", "skills":{"backend":"yes", "frontend":"yes"}} dict.clear() print("After calling clear() " + String(dict)) dict = {"name":"generalistprogrammer"} var duplicateddict = dict.duplicate() print("Printing duplicated dict: " + String(duplicateddict)) var duplicateddictdeep = dictdeep.duplicate(true) print("Printing duplicated dictdeep: " + String(duplicateddictdeep)) var duplicateddictnotdeep = dictdeep.duplicate() print("Printing duplicated dictdeep not deep: " + String(duplicateddictnotdeep)) var emptydict = {} print("Printing emptydict: " + String(emptydict.empty())) print("Printing not empty dict: " + String(dict.empty())) var result = dictdeep.erase("name") print("Printing key erase the resul was: "+ String(result) + " and the end dict is : "+ String(dictdeep)) print("Printing a get: "+ dict.get("name")) print("Printing a has example: "+ String(dict.has("name"))) var hasall = dictdeep.has_all(["name","skills"]) print("Printing example of has_all: "+ String(hasall)) print("Printing example of keys: " + String(dict.keys())) print("Printing example of size: " + String(dict.size())) print("Printing example of values: " + String(dict.values())) var dict1 = {"name":"GP"} var dict2 = {"name":"GP"} print("Printing example of regular comparison: "+ String(dict1 == dict2)) print("Printing example of hash comparison: "+ String(dict1.hash() == dict2.hash()))

Explanation of the output

The output you will get from running this will look like this. The explanation of each below is in bold.

After calling clear() {} – We cleared dict so it now displaying only {} a blank dictionary

Printing duplicated dict: {name:generalistprogrammer} – We did a shallow duplication of dict and got just the name back

Printing duplicated dictdeep: {name:generalistprogrammer, skills:{backend:yes, frontend:yes}} – We duplicated a nest dictionary with the deep value set to true so it returned the nested dictionary as well

Printing duplicated dictdeep not deep: {name:generalistprogrammer, skills:{backend:yes, frontend:yes}} – Even though this looks the same because its converted to a string it only duplicated the top level portion if you try to access the nested dictionary you won’t be able to

Printing emptydict: True – We checked against a empty dictionary so got true back

Printing not empty dict: False – We checked against a non empty dictionary so got false back

Printing key erase the resul was: True and the end dict is : {skills:{backend:yes, frontend:yes}} – We erased the name key so its now no longer part of the dictionary

Printing a get: generalistprogrammer – We did a get on the name key

Printing a has example: True – We checked if the name key exists

Printing example of has_all: False – We checked if all these keys from the array exist and got false back

Printing example of keys: [name]

Printing example of size: 1

Printing example of values: [generalistprogrammer]

Printing example of regular comparison: False

Printing example of hash comparison: True

Let’s look at some other things you maybe want to do with dictionaries.

Godot iterate dictionary

The easiest way to iterate through a dictionary is to use its values then use a for loop. Here is an example of how to do this.

var dictiter = {"name":"GP", "age":"90","gender":"male"} for val in dictiter.values(): print(val)

This will produce this output.

As simple as that. If you want to loop through keys then use keys() instead of values.

Frequently asked questions

How do I nest a dictionary in a dictionary? You can easily nest a dictionary inside another one using a comma adding a key and adding curly braces below that to create a new dictionary on the second level

How can I iterate a godot dictionary? You can use the values method to get an array of the dictionary then simply loop over it.

Final words

That is it for this godot dictionary tutorial. If you liked it please consider sharing it on social media and subscribing to my youtube channel here:https://www.youtube.com/channel/UC1i4hf14VYxV14h6MsPX0Yw?sub_confirmation=1

If you want to support me and my content please check out my skillshare course here:

https://skl.sh/2YhzEfe

Here are also some other tutorials you might be interested in: