A Dictionary stores values under keys. Write it with curly braces and key: value pairs:
30
Slime
{ "hp": 20, "attack": 7, "name": "Slime", "defense": 2 }
4 keys
Keys are usually strings, but any value can be a key: numbers, vectors, even nodes. The dot form, stats.name, works when the key is a string that is a valid name.
Reading Safely with get()
Reading a missing key with [] stops the function with an error. get() returns null, or a default you pass:
4
<null>
0
Has a level
false
The error from [] on a missing key looks like this:
Invalid access to property or key 'coins' on a base object of type 'Dictionary'.
Adding, Changing and Removing Keys
{ "potion": 3, "arrow": 10 }
true
false
{ "potion": 3 }
{ "bat": 2, "slime": 1 }
hits.get(enemy, 0) + 1 is the standard way to count things: it starts every new key at 0.
Looping Over a Dictionary
A for loop gives the keys, in the order they were added:
sword costs 50
shield costs 30
potion costs 5
["sword", "shield", "potion"]
[50, 30, 5]
All items: 85
Do not add or erase keys while you loop over the same dictionary. Loop over prices.keys(), which is a separate array, when you need to erase as you go.
Sorting by Value
A dictionary has no sort(). Sort its keys instead:
1. Bo 300
2. Ana 120
3. Chidi 95
Merging and Copying
merge() adds another dictionary's keys. Existing keys keep their values unless you pass true:
{ "volume": 40, "music": true, "language": "en" }
{ "volume": 100, "music": true, "language": "en" }
{ "volume": 40 }
Like arrays, dictionaries are shared, not copied, when you assign them or pass them to a function. Use duplicate() for a copy, and duplicate(true) to copy nested arrays and dictionaries too.
Typed Dictionaries
Since Godot 4.4 you can type the keys and the values:
{ "sword": 50, "bow": 35 }
true
A key or value of the wrong type is then an error the editor shows before you run, such as Invalid index type "int" for a base of type "Dictionary[String, int]".
Nested Data
Dictionaries and arrays nest freely, which is how save data and level data usually look:
Ana
120.0
map
false
To write such data to a file, JSON.stringify(save) turns it into text. Note that JSON has no Vector2, so convert vectors to arrays or use var_to_str() instead.
Quick Reference
| Task | Code |
|---|---|
| Read, failing if missing | d[key] |
| Read with a default | d.get(key, default) |
| Add or change | d[key] = value |
| Remove | d.erase(key), d.clear() |
| Check | d.has(key), key in d, d.is_empty() |
| Size | d.size() |
| Keys, values | d.keys(), d.values() |
| Key for a value | d.find_key(value) |
| Combine | d.merge(other), d.merge(other, true) |
| Copy | d.duplicate(), d.duplicate(true) |
Frequently Asked Questions
How do I check if a key exists in a Godot dictionary?
Use has() or in: stats.has("hp") or "hp" in stats. Both return true or false. To read a key that may be missing, use stats.get("hp", 0), which returns the default instead of failing.
How do I loop through a dictionary in GDScript?
for key in stats: gives each key, and stats[key] gives its value. Loop over stats.values() for the values alone. Keys come out in the order they were added.
How do I remove a key from a dictionary in Godot?
Call erase(key). It returns true if the key was there and false if it was not. clear() removes every key.
Does Godot 4 have typed dictionaries?
Yes, since Godot 4.4: var prices: Dictionary[String, int] = {}. The keys must be String and the values int, and the editor checks both.
Why does reading a missing key give an error?
stats["mana"] on a dictionary without that key stops with "Invalid access to property or key 'mana' on a base object of type 'Dictionary'." Use get() with a default, or check with has() first.
