Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Dictionary

Une structure de données intégrée qui contient des paires clé-valeur.

Description

Dictionaries are associative containers that contain values referenced by unique keys. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is often referred to as a hash map or an associative array.

You can define a dictionary by placing a comma-separated list of key: value pairs inside curly braces {}.

Creating a dictionary:

var my_dict = {} # Creates an empty dictionary.

var dict_variable_key = "Another key name"
var dict_variable_value = "value2"
var another_dict = {
    "Some key name": "value1",
    dict_variable_key: dict_variable_value,
}

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }

# Alternative Lua-style syntax.
# Doesn't require quotes around keys, but only string constants can be used as key names.
# Additionally, key names must start with a letter or an underscore.
# Here, `some_key` is a string literal, not a variable!
another_dict = {
    some_key = 42,
}

var myDict = new Godot.Collections.Dictionary(); // Creates an empty dictionary.
var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 },
};

You can access a dictionary's value by referencing its corresponding key. In the above example, points_dict["White"] will return 50. You can also write points_dict.White, which is equivalent. However, you'll have to use the bracket syntax if the key you're accessing the dictionary with isn't a fixed string (such as a number or variable).

@export_enum("White", "Yellow", "Orange") var my_color: String
var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
func _ready():
    # We can't use dot syntax here as `my_color` is a variable.
    var points = points_dict[my_color]

[Export(PropertyHint.Enum, "White,Yellow,Orange")]
public string MyColor { get; set; }
private Godot.Collections.Dictionary _pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 },
};

public override void _Ready()
{
    int points = (int)_pointsDict[MyColor];
}

In the above code, points will be assigned the value that is paired with the appropriate color selected in my_color.

Dictionaries can contain more complex data:

var my_dict = {
    "First Array": [1, 2, 3, 4] # Assigns an Array to a String key.
}

var myDict = new Godot.Collections.Dictionary
{
    { "First Array", new Godot.Collections.Array { 1, 2, 3, 4 } }
};

To add a key to an existing dictionary, access it like an existing key and assign to it:

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.

var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 },
};
pointsDict["Blue"] = 150; // Add "Blue" as a key and assign 150 as its value.

Finally, untyped dictionaries can contain different types of keys and values in the same dictionary:

# This is a valid dictionary.
# To access the string "Nested value" below, use `my_dict.sub_dict.sub_key` or `my_dict["sub_dict"]["sub_key"]`.
# Indexing styles can be mixed and matched depending on your needs.
var my_dict = {
    "String Key": 5,
    4: [1, 2, 3],
    7: "Hello",
    "sub_dict": { "sub_key": "Nested value" },
}

// This is a valid dictionary.
// To access the string "Nested value" below, use `((Godot.Collections.Dictionary)myDict["sub_dict"])["sub_key"]`.
var myDict = new Godot.Collections.Dictionary {
    { "String Key", 5 },
    { 4, new Godot.Collections.Array { 1, 2, 3 } },
    { 7, "Hello" },
    { "sub_dict", new Godot.Collections.Dictionary { { "sub_key", "Nested value" } } },
};

The keys of a dictionary can be iterated with the for keyword:

var groceries = { "Orange": 20, "Apple": 2, "Banana": 4 }
for fruit in groceries:
    var amount = groceries[fruit]

var groceries = new Godot.Collections.Dictionary { { "Orange", 20 }, { "Apple", 2 }, { "Banana", 4 } };
foreach (var (fruit, amount) in groceries)
{
    // `fruit` is the key, `amount` is the value.
}

To enforce a certain type for keys and values, you can create a typed dictionary. Typed dictionaries can only contain keys and values of the given types, or that inherit from the given classes:

# Creates a typed dictionary with String keys and int values.
# Attempting to use any other type for keys or values will result in an error.
var typed_dict: Dictionary[String, int] = {
    "some_key": 1,
    "some_other_key": 2,
}

# Creates a typed dictionary with String keys and values of any type.
# Attempting to use any other type for keys will result in an error.
var typed_dict_key_only: Dictionary[String, Variant] = {
    "some_key": 12.34,
    "some_other_key": "string",
}

// Creates a typed dictionary with String keys and int values.
// Attempting to use any other type for keys or values will result in an error.
var typedDict = new Godot.Collections.Dictionary<String, int> {
    {"some_key", 1},
    {"some_other_key", 2},
};

// Creates a typed dictionary with String keys and values of any type.
// Attempting to use any other type for keys will result in an error.
var typedDictKeyOnly = new Godot.Collections.Dictionary<String, Variant> {
    {"some_key", 12.34},
    {"some_other_key", "string"},
};

Note: Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use duplicate().

Note: Erasing elements while iterating over dictionaries is not supported and will result in unpredictable behavior.

Note: In a boolean context, a dictionary will evaluate to false if it's empty ({}). Otherwise, a dictionary will always evaluate to true.

Note

Il y a des différences notables dans l'utilisation de cette API en C#. Voir Différences de l'API C# par rapport à GDScript pour plus d'informations.

Tutoriels

Constructeurs

Dictionary	Dictionary()
Dictionary	Dictionary(base: Dictionary, key_type: int, key_class_name: StringName, key_script: Variant, value_type: int, value_class_name: StringName, value_script: Variant)
Dictionary	Dictionary(from: Dictionary)

Méthodes

void	assign(dictionary: Dictionary)
void	clear()
Dictionary	duplicate(deep: bool = false) const
Dictionary	duplicate_deep(deep_subresources_mode: int = 1) const
bool	erase(key: Variant)
Variant	find_key(value: Variant) const
Variant	get(key: Variant, default: Variant = null) const
Variant	get_or_add(key: Variant, default: Variant = null)
int	get_typed_key_builtin() const
StringName	get_typed_key_class_name() const
Variant	get_typed_key_script() const
int	get_typed_value_builtin() const
StringName	get_typed_value_class_name() const
Variant	get_typed_value_script() const
bool	has(key: Variant) const
bool	has_all(keys: Array) const
int	hash() const
bool	is_empty() const
bool	is_read_only() const
bool	is_same_typed(dictionary: Dictionary) const
bool	is_same_typed_key(dictionary: Dictionary) const
bool	is_same_typed_value(dictionary: Dictionary) const
bool	is_typed() const
bool	is_typed_key() const
bool	is_typed_value() const
Array	keys() const
void	make_read_only()
void	merge(dictionary: Dictionary, overwrite: bool = false)
Dictionary	merged(dictionary: Dictionary, overwrite: bool = false) const
bool	recursive_equal(dictionary: Dictionary, recursion_count: int) const
bool	set(key: Variant, value: Variant)
int	size() const
void	sort()
Array	values() const

Opérateurs

bool	operator !=(right: Dictionary)
bool	operator ==(right: Dictionary)
Variant	operator [](key: Variant)

Descriptions des constructeurs

Dictionary Dictionary() 🔗

Construit un Dictionary vide.

Dictionary Dictionary(base: Dictionary, key_type: int, key_class_name: StringName, key_script: Variant, value_type: int, value_class_name: StringName, value_script: Variant)

Crée un dictionnaire typé depuis le dictionnaire base. Un dictionnaire typé ne peut contenir que des clés et des valeurs des types donnés, ou qui héritent des classes données, telles que décrits par les paramètres du constructeur.

Dictionary Dictionary(from: Dictionary)

Renvoie le même dictionnaire que from. Si vous avez besoin d'une copie du dictionnaire, utilisez duplicate().

Descriptions des méthodes

void assign(dictionary: Dictionary) 🔗

Assigne des éléments d'un autre dictionnaire dictionary dans le dictionnaire. Redimensionne le dictionnaire pour faire correspondre à dictionary. Effectue des conversions de type si le dictionnaire est typé.

void clear() 🔗

Vide le dictionnaire, en supprimant toutes les entrées de celui-ci.

Dictionary duplicate(deep: bool = false) const 🔗

Renvoie une nouvelle copie du dictionnaire.

Par défaut, une copie superficielle (shallow copy) est renvoyée : toutes les clés Array, Dictionary et Resource imbriquées sont partagés avec le dictionnaire original. Modifier l'un dans un dictionnaire va aussi modifier l'autre.

Si deep vaut true, une copie profonde (deep copy) est renvoyée : tous les tableaux et les dictionnaires imbriqués sont également dupliqués (récursivement). Les Resources sont cependant toujours partagées avec le dictionnaire original.

Dictionary duplicate_deep(deep_subresources_mode: int = 1) const 🔗

Duplicates this dictionary, deeply, like duplicate() when passing true, with extra control over how subresources are handled.

deep_subresources_mode must be one of the values from DeepDuplicateMode. By default, only internal resources will be duplicated (recursively).

bool erase(key: Variant) 🔗

Retire l'entrée du dictionnaire par sa clé, si elle existe. Renvoie true si la clé key donnée existait dans le dictionnaire, sinon false.

Note : N'effacez pas d'entrées lors de l'itération sur le dictionnaire. Vous pouvez itérer sur le tableau keys() à la place.

Variant find_key(value: Variant) const 🔗

Trouve et renvoie la première clé dont la valeur associée est égale à value, ou null si elle n'est pas trouvée.

Note : null est également une clé valide. Si elle est dans le dictionnaire, find_key() peut donner des résultats trompeurs.

Variant get(key: Variant, default: Variant = null) const 🔗

Returns the corresponding value for the given key in the dictionary. If the key does not exist, returns default, or null if the parameter is omitted.

Note: If the default argument is computationally expensive or has unwanted side effects, consider using the has() method instead:

# Always calls `expensive_function()`.
dict.get("key", expensive_function())
# Calls `expensive_function()` only if the key does not exist.
dict.get("key") if dict.has("key") else expensive_function()

Variant get_or_add(key: Variant, default: Variant = null) 🔗

Obtient une valeur et assure que la clé est définie. Si la key existe dans le dictionnaire, cela se comporte comme get(). Sinon, la valeur default est insérée dans le dictionnaire et renvoyée.

int get_typed_key_builtin() const 🔗

Renvoie le type Variant intégré des clés du dictionnaire de type en tant que constante Variant.Type. Si les clés ne sont pas typées, renvoie @GlobalScope.TYPE_NIL. Voir aussi is_typed_key().

StringName get_typed_key_class_name() const 🔗

Renvoie le nom de classe intégrée des clés du dictionnaire typé, si le type Variant intégré est @GlobalScope.TYPE_OBJECT. Sinon, renvoie un StringName vide. Voir aussi is_typed_key() et Object.get_class().

Variant get_typed_key_script() const 🔗

Renvoie l'instance Script associée aux clés de ce dictionnaire, ou null si elle n'existe pas. Voir aussi is_typed_key().

int get_typed_value_builtin() const 🔗

Renvoie le type Variant intégré des valeurs du dictionnaire typé en tant que constante Variant.Type. Si les valeurs ne sont pas typées, renvoie @GlobalScope.TYPE_NIL. Voir aussi is_typed_value().

StringName get_typed_value_class_name() const 🔗

Renvoie le nom de classe intégrée des valeurs du dictionnaire typé, si le type Variant intégré est @GlobalScope.TYPE_OBJECT. Sinon, renvoie un StringName vide. Voir aussi is_typed_value() et Object.get_class().

Variant get_typed_value_script() const 🔗

Renvoie l'instance Script associée aux valeurs de ce dictionnaire, ou null si elle n'existe pas. Voir aussi is_typed_value().

bool has(key: Variant) const 🔗

Renvoie true si le dictionnaire contient une entrée avec la clé key donnée.

var my_dict = {
    "Godot" : 4,
    210 : null,
}

print(my_dict.has("Godot")) # Affiche true
print(my_dict.has(210))     # Affiche true
print(my_dict.has(4))       # Affiche false

var myDict = new Godot.Collections.Dictionary
{
    { "Godot", 4 },
    { 210, default },
};

GD.Print(myDict.ContainsKey("Godot")); // Affiche True
GD.Print(myDict.ContainsKey(210));     // Affiche True
GD.Print(myDict.ContainsKey(4));       // Affiche False

En GDScript, cela équivaut à l'opérateur in :

if "Godot" in {"Godot": 4}:
    print("La clé est ici !") # Sera affiché.

Note: Cette méthode renvoie true tant que la key existe, même si sa valeur correspondante est null.

bool has_all(keys: Array) const 🔗

Renvoie true si le dictionnaire contient toutes les clés du tableau keys donné.

var donnees = {"largeur" : 10, "hauteur" : 20}
donnees.has_all(["hauteur", "largeur"]) # Renvoie true

int hash() const 🔗

Renvoie une valeur d'entier de 32 bits hachée représentant le contenu du dictionnaire.

var dict1 = { "A": 10, "B": 2 }
var dict2 = { "A": 10, "B": 2 }

print(dict1.hash() == dict2.hash()) # Affiche true

var dict1 = new Godot.Collections.Dictionary { { "A", 10 }, { "B", 2 } };
var dict2 = new Godot.Collections.Dictionary { { "A", 10 }, { "B", 2 } };

// Godot.Collections.Dictionary n'a pas de méthode Hash(). Utilisez GD.Hash() à la place.
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Affiche True

Note : Les dictionnaires avec les mêmes entrées mais dans un ordre différent n'auront pas le même hachage.

Note : Les dictionnaires avec des valeurs de hachage égales ne sont pas garantis d'être le même, en raison des collisions de hachage. Au contraire, les dictionnaires avec différentes valeurs de hachage sont garantis d'être différents.

bool is_empty() const 🔗

Renvoie true si le dictionnaire est vide (sa taille est de 0). Voir aussi size().

bool is_read_only() const 🔗

Renvoie true si le dictionnaire est en lecture seule. Voir make_read_only(). Les dictionnaires sont automatiquement en lecture seule s'ils sont déclarés avec le mot-clé const.

bool is_same_typed(dictionary: Dictionary) const 🔗

Renvoie true si le dictionnaire est typé de la même manière que le dictionnaire dictionary.

bool is_same_typed_key(dictionary: Dictionary) const 🔗

Renvoie true si les clés du dictionnaire sont typées de la même manière que les clés du dictionnaire dictionary.

bool is_same_typed_value(dictionary: Dictionary) const 🔗

Renvoie true si les valeurs du dictionnaire sont typées de la même manière que les valeurs du dictionnaire dictionary.

bool is_typed() const 🔗

Renvoie true si le dictionnaire est typé. Les dictionnaires typés ne peuvent stocker que des clés et des valeurs du type associé et fournissent une sûreté du typage pour l'opérateur []. Les méthodes des dictionnaires typés renvoient toujours des Variant.

bool is_typed_key() const 🔗

Renvoie true si les clés du dictionnaire sont typées.

bool is_typed_value() const 🔗

Renvoie true si les valeurs du dictionnaire sont typées.

Array keys() const 🔗

Renvoie la liste des clés du dictionnaire.

void make_read_only() 🔗

Oblige le dictionnaire à être en lecture seule, c'est-à-dire désactive la modification du contenu du dictionnaire. Ne s'applique pas au contenu imbriqué, par exemple le contenu de dictionnaires imbriqués.

void merge(dictionary: Dictionary, overwrite: bool = false) 🔗

Ajoute des entrées du dictionanaire dictionary à ce dictionnaire. Par défaut, les clés en double ne sont pas copiés, sauf si overwrite vaut true.

var dict = { "objet": "epee", "quantite": 2 }
var autre_dict = { "quantite": 15, "couleur": "argent" }

# L'écrasement des clés existantes est désactivé par défaut.
dict.merge(autre_dict)
print(dict)  # { "objet": "epee", "quantite": 2, "couleur": "argent" }

# Avec l'écrasement des clés activé.
dict.merge(autre_dict, true)
print(dict)  # { "objet": "epee", "quantite": 15, "couleur": "argent" }

var dict = new Godot.Collections.Dictionary
{
    ["objet"] = "epee",
    ["quantite"] = 2,
};

var autreDict = new Godot.Collections.Dictionary
{
    ["quantite"] = 15,
    ["couleur"] = "argent",
};

// L'écrasement des clés existantes est désactivé par défaut.
dict.Merge(autreDict);
GD.Print(dict); // { "objet": "epee", "quantite": 2, "couleur": "argent" }

// Avec l'écrasement des clés activé.
dict.Merge(autreDict, true);
GD.Print(dict); // { "objet": "epee", "quantite": 15, "couleur": "argent" }

Note : merge() n'est pas récursive. Les dictionnaires imbriqués sont considérés comme des clés qui peuvent être remplacées ou non selon la valeur de overwrite, mais ils ne seront jamais fusionnés ensemble.

Dictionary merged(dictionary: Dictionary, overwrite: bool = false) const 🔗

Renvoie une copie de ce dictionnaire fusionné avec l'autre dictionnaire dictionary. Par défaut, les clés en double ne sont pas copiées, sauf si overwrite vaut true. Voir aussi merge().

Cette méthode est utile pour créer rapidement des dictionnaires avec des valeurs par défaut :

var base = { "fruit": "pomme", "legume": "patate" }
var extra = { "fruit": "orange", "assaisonnement": "vinaigre" }
# Affiche { "fruit": "orange", "legume": "patate", "assaisonnement": "vinaigre" }
print(extra.merged(base))
# Affiche { "fruit": "pomme", "legume": "patate", "assaisonnement": "vinaigre" }
print(extra.merged(base, true))

bool recursive_equal(dictionary: Dictionary, recursion_count: int) const 🔗

Renvoie true si les deux dictionnaires contiennent les mêmes clés et valeurs, les clés des Dictionary et Array intérieurs sont comparées récursivement.

bool set(key: Variant, value: Variant) 🔗

Définit la valeur de l'élément à la clé key donnée à la valeur value donnée. Renvoie true si la valeur a été définie avec succès. Échoue et renvoie false si le dictionnaire est en lecture-seule, ou si key et value ne correspondent pas aux types du dictionnaire. Ceci est identique à l'utilisation de l'opérateur [] (dict[key] = value).

int size() const 🔗

Renvoie le nombre d'entrées dans le dictionnaire. Les dictionnaires vides ({ }) renvoient toujours 0. Voir aussi is_empty().

void sort() 🔗

Trie le dictionnaire en ordre ascendant, par clé. L'ordre final dépend de la comparaison "inférieur à" (<) entre les clés..

var nombres = { "c": 2, "a": 0, "b": 1 }
nombres.sort()
print(nombres) # Affiche { "a": 0, "b": 1, "c": 2 }

Cette méthode garantit que les entrées du dictionnaire sont triées de manière consistante lorsque keys() ou values() sont appelées, ou lorsque le dictionnaire doit être converti en une chaîne par @GlobalScope.str() ou JSON.stringify().

Array values() const 🔗

Renvoie la liste des valeurs dans ce dictionnaire.

Descriptions des opérateurs

bool operator !=(right: Dictionary) 🔗

Renvoie true si les deux dictionnaires ne contiennent pas les mêmes clés et valeurs.

bool operator ==(right: Dictionary) 🔗

Renvoie true si les deux dictionnaires contiennent les mêmes clés et valeurs. L'ordre des entrées n'a aucune importance.

Note : En C#, par convention, cet opérateur compare par référence. Si vous devez comparer par valeur, itérez sur les deux dictionnaires.

Variant operator [](key: Variant) 🔗

Renvoie la valeur correspondante à la clé key donnée dans le dictionnaire. Si l'entrée n'existe pas, échoue et renvoie null. Pour un accès sécurisé, utilisez get() ou has().