Dictionary in Godot – Complete Guide

Welcome to our dive into the world of Godot 4’s Dictionary class – a powerful and versatile data structure that should be in every game developer’s toolkit. Dictionaries are a cornerstone of game programming, allowing developers to create and manipulate complex data with ease. Whether you’re a budding game developer or have some experience under your belt, understanding how to leverage dictionaries in Godot 4 can unlock new possibilities for your game’s functionality and help you manage game data more effectively.

What is a Dictionary in Godot?

Dictionaries in Godot, much like their counterparts in other programming languages, are collections of key-value pairs. Each item in a dictionary is a combination of a key, which is unique, and a value that corresponds to that key. Dictionaries in Godot are very flexible – they can store any type of data as a value, be it an integer, a string, an array, another dictionary, and so on.

What Is It For?

In Godot, dictionaries have a wide range of uses. They’re essential for:

  • Storing game states, like player scores or inventory items.
  • Mapping input commands to character actions.
  • Organizing data for levels, characters, and game objects.
  • Creating lookup tables for quick access to data.

They become especially useful in games where you need to retrieve and update information efficiently, without knowing the exact position of an item in a list, like you would for arrays.

Why Should I Learn It?

Understanding the Dictionary class and how to effectively utilize it can vastly simplify your code and make your game logic more intuitive. Not only does it make accessing and sorting through game data a breeze, but it also can lead to performance improvements in your game, particularly when dealing with a large amount of data. Learning to use dictionaries effectively is definitely a power-up for any game developer working with Godot 4.

CTA Small Image

Creating and Initializing Dictionaries

Let’s begin by learning how to create and initialize dictionaries in Godot 4. We can create an empty dictionary or initialize it with some key-value pairs.

var empty_dict = {} # An empty dictionary

var initialized_dict = {
  "name": "Zenva Warrior",
  "health": 100,
  "inventory": ["sword", "shield", "potion"]
} # A dictionary with data

You can also create a dictionary using the Dictionary constructor, which is useful when you need to generate a dictionary from code dynamically.

var constructed_dict = Dictionary()
constructed_dict["name"] = "Zenva Archer"
constructed_dict["health"] = 80
constructed_dict["inventory"] = ["bow", "arrow bundle", "cloak"]

Accessing and Modifying Dictionary Values

To access a value, you reference its key. If the key doesn’t exist, Godot will return null, so always ensure the key exists or handle the null case. Here’s how you can access and modify dictionary values:

# Accessing values
var hero_name = initialized_dict["name"]
print(hero_name) # Output: Zenva Warrior

# Modifying values
initialized_dict["health"] = 95
print(initialized_dict["health"]) # Output: 95

Adding new entries is just as simple:

# Adding a new key-value pair
initialized_dict["mana"] = 50
print(initialized_dict["mana"]) # Output: 50

Removing entries can be done using the erase() function:

# Removing the 'mana' entry
print(initialized_dict.has("mana")) # Output: False (meaning the key does not exist)

Working with Dictionary Methods

Godot’s Dictionary class comes with a variety of methods that enhance its utility. Here’s how to use some essential ones:

# Checking if a dictionary has a certain key
var has_key = initialized_dict.has("health")
print(has_key) # Output: True

# Getting a list of all keys
var keys = initialized_dict.keys()
print(keys) # Output: ["name", "health", "inventory"]

# Getting a list of all values
var values = initialized_dict.values()
print(values) # Outputs the values of all the keys in the dictionary

Dictionaries in Godot are powerful because they can be nested, meaning that a dictionary value can be another dictionary, which forms a complex and well-organized structure.

# Nested dictionaries
var game_state = {
  "player": {
    "name": "Zenva Mage",
    "health": 70
  "enemy": {
    "name": "Goblin",
    "health": 50

print(game_state["player"]["name"]) # Output: Zenva Mage

This should provide you with a solid foundation for creating, accessing, and manipulating dictionaries in Godot 4. Stay tuned as we delve deeper into dictionaries and explore more advanced operations in the next part of this tutorial. Understanding these basics is essential for managing complex data in your games and will pave the way for creating more intricate and interactive gaming experiences.

More Advanced Dictionary Operations

Now that we’re familiar with the basics of Godot’s Dictionary class, let’s delve into some more advanced operations that can help you manipulate and handle your game data more effectively.

Finding the Size

Determining the number of key-value pairs in a dictionary is done with the size() method. This can be useful when you need to know how many items are in a player’s inventory, for example.

var items_count = initialized_dict.size()
print(items_count) # If initialized_dict is the dictionary from previous examples, this will output: 3

Iterating Over Dictionaries

You can iterate over the keys and values of a dictionary using a loop. This is particularly useful when you want to perform an action for each pair, such as checking every player’s score in a leaderboard.

for key in initialized_dict.keys():
    print("Key: " + key + " has value: " + str(initialized_dict[key]))

You might also want to iterate over both – keys and values at the same time. In this case, you can use the items() method, which returns an array of key-value pairs.

for key, value in initialized_dict.items():
    print("Key:", key, "Value:", value)

Updating Dictionaries

You can update the contents of a dictionary with the update() method. This method merges a dictionary with another set of key-value pairs. Any existing keys will have their values updated.

var additional_stats = {"mana": 100, "stamina": 50}

Note that if the keys already exist, they will be overwritten by the keys in the dictionary passed to update.

Merging Dictionaries

Sometimes, you might want to merge two dictionaries into a new one without modifying the originals. The duplicate() method combined with update() allows you to do just that:

var merged_dict = initialized_dict.duplicate()

Clearing a Dictionary

If you need to remove all items from a dictionary, you can utilize the clear() method. This is useful when resetting a game state, for example.

print(initialized_dict) # This will print an empty dictionary: {}

Remember, while dictionaries are highly useful, they also need to be used judiciously. Overusing dictionaries where a simpler data structure could work may unnecessarily complicate your code. Equipped with these advanced techniques, you can now handle dictionaries in Godot like a pro, optimizing your coding for better game performance and complexity. These structures will play a pivotal role in managing your game world’s data, player progress, and more in a clean and accessible way. Happy coding!Dictionary to JSON

In many instances, especially when involving saving and loading game data, you’ll want to convert your dictionaries into JSON format. Godot makes this simple with its JSON class.

var dict_to_json = JSON.print(initialized_dict)
print(dict_to_json) # Outputs the JSON string representation of the dictionary

When you’re ready to load your data back from JSON, you can easily parse it and recover your original dictionary.

var json_to_dict = JSON.parse(dict_to_json).result
print(json_to_dict) # Outputs the original dictionary from the JSON string

Checking for Null

When accessing keys that may or may not exist in a dictionary, it’s important to safely handle potential null values. The get() method allows you to provide a default value if the key is missing.

# Safely get the value of 'magic' or default to 0 if not found
var magic = initialized_dict.get("magic", 0)
print(magic) # Outputs: 0, since 'magic' does not exist in our example's initialized dictionary

Erasing Elements Conditionally

Sometimes you want to parse through a dictionary and remove certain elements based on a condition. Here’s how you could remove high-score entries that are too low, for instance.

var high_scores = {"Alice": 1200, "Bob": 850, "Carol": 1450}

high_scores.erase("Bob") # Explicitly remove Bob's score

# Conditionally remove scores less than 1000
for name in high_scores.keys():
    if high_scores[name] < 1000:

print(high_scores) # Outputs: {"Carol": 1450, "Alice": 1200}

Using Dictionaries With Arrays

Combining dictionaries with arrays can be a powerful tool. For instance, you could store multiple states of game progress as an array of dictionaries.

var game_progress = [
    {"level": 1, "score": 2000, "lives": 3},
    {"level": 2, "score": 3500, "lives": 2},
    # ... etc.

# Access the score for level 2 progress
print(game_progress[1]["score"]) # Outputs: 3500

Deep Copying Dictionaries

If you need a completely separate copy of a dictionary, where changes to the new dictionary won’t affect the original, you can perform a deep copy using the duplicate(true) method.

var original_dict = {"name": "Zenva", "courses": 100}
var deep_copied_dict = original_dict.duplicate(true)
deep_copied_dict["courses"] = 150

print(original_dict["courses"]) # Outputs: 100

Sorting Dictionaries

While dictionaries themselves are unordered, you can sort the keys or values into an array if needed.

var scores = {"Alice": 1200, "Bob": 850, "Carol": 1450}
var sorted_keys = scores.keys()

# Now sorted_keys is ["Alice", "Bob", "Carol"]
for key in sorted_keys:
    print("Score of " + key + ": " + str(scores[key]))
    # This will print the scores in ascending order by name

These examples and operations showcase the flexibility and power of dictionaries in Godot. They can significantly streamline the process of data management in your game, allowing quick saves, loads, and updates to your game state. Not to mention, dictionaries are indispensable when it comes to dynamically creating and handling game objects and their attributes within Godot’s robust programming environment. As you continue to develop games with Godot 4, effective use of dictionaries will no doubt be a key player in your development toolkit.

Continuing Your Game Development Journey

Congratulations on taking these first steps into mastering dictionaries in Godot 4! Armed with this knowledge, you’re well on your way to creating more complex and dynamic games. But don’t stop here – there’s a whole world of game development waiting for you to explore further.

We at Zenva understand the excitement and passion that drives you to learn more, and our Godot Game Development Mini-Degree is an excellent next step. This curated collection of courses will dive deeper into the power of Godot, from the essentials of GDScript to complex gameplay mechanics. Whether you dream of crafting immersive 2D worlds, designing challenging 3D landscapes, or anything in between, this Mini-Degree will help you build the skills and portfolio you need to stand out in the game development universe.

Looking for a broader range of topics? Our selection of Godot courses covers various aspects and levels of game development. With Zenva, you can learn at your own pace with the flexibility to fit your learning into your schedule. So why wait? Take your passion for game development to the next level with us, and join a community dedicated to turning game creation dreams into reality. Your next big project awaits!


Mastering the use of dictionaries is a game-changer in the world of Godot 4. They provide the structure and flexibility needed to manage game data efficiently, and they pave the way for advanced game features and logic. Don’t forget, what you’ve learned here is just the beginning of what’s possible with Godot’s robust framework. As you continue to experiment and build with these concepts, you’ll find that your ability to craft compelling game experiences grows by leaps and bounds.

We hope you’ve enjoyed this journey through Godot 4’s Dictionary class. Keep the momentum going by deepening your knowledge and skills with Zenva’s comprehensive Godot Game Development Mini-Degree. There’s no time like the present to expand your expertise and take your games from concept to reality. The adventure continues, and we can’t wait to see what you’ll create next!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.