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

Встроенная структура данных, содержащая пары ключ-значение.

Описание

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.

Примечание

Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.

Обучающие материалы

Конструкторы

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)

Методы

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

Операторы

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

Описания конструктора

Dictionary 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)

Создает типизированный словарь из словаря base. Типизированный словарь может содержать только ключи и значения указанных типов или наследуемые от указанных классов, как описано параметрами этого конструктора.

Dictionary Dictionary(from: Dictionary)

Возвращает тот же словарь, что и from. Если вам нужна копия словаря, используйте duplicate().

Описания метода

void assign(dictionary: Dictionary) 🔗

Назначает элементы другого dictionary в словарь. Изменяет размер словаря для соответствия dictionary. Выполняет преобразования типов, если словарь типизирован.

void clear() 🔗

Очищает словарь, удаляя из него все записи.

Dictionary duplicate(deep: bool = false) const 🔗

Возвращает новую копию словаря.

По умолчанию возвращается поверхностная копия: все вложенные ключи и значения Array, Dictionary и Resource используются совместно с исходным словарем. Изменение любого из них в одном словаре также повлияет на них в другом.

Если deep равен true, возвращается глубокая копия: все вложенные массивы и словари также дублируются (рекурсивно). Однако любой Resource по-прежнему используется совместно с исходным словарем.

Dictionary duplicate_deep(deep_subresources_mode: int = 1) const 🔗

Дублирует этот словарь, глубоко, как duplicate() при передаче true, с дополнительным контролем над обработкой подресурсов.

deep_subresources_mode должен быть одним из значений из DeepDuplicateMode. По умолчанию дублируются только внутренние ресурсы (рекурсивно).

bool erase(key: Variant) 🔗

Удаляет запись словаря по ключу, если она существует. Возвращает true, если заданный key существовал в словаре, в противном случае false.

Примечание: Не удаляйте записи при итерации по словарю. Вместо этого вы можете итерировать по массиву keys().

Variant find_key(value: Variant) const 🔗

Находит и возвращает первый ключ, связанное значение которого равно value или null, если он не найден.

Примечание: null также является допустимым ключом. Если внутри словаря, find_key() может дать вводящие в заблуждение результаты.

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

Возвращает соответствующее значение для заданного key в словаре. Если key не существует, возвращает default или null, если параметр опущен.

Примечание: Если аргумент default является вычислительно затратным или имеет нежелательные побочные эффекты, рассмотрите возможность использования метода has() вместо него:

# Всегда вызывает `expensive_function()`.
dict.get("key", expensive_function())
# Вызывает `expensive_function()` только если ключ не существует.
dict.get("key") if dict.has("key") else expensive_function()

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

Получает значение и обеспечивает установку ключа. Если key существует в словаре, это ведет себя как get(). В противном случае значение default вставляется в словарь и возвращается.

int get_typed_key_builtin() const 🔗

Возвращает встроенный тип Variant ключей типизированного словаря как константу Variant.Type. Если ключи не типизированы, возвращает @GlobalScope.TYPE_NIL. См. также is_typed_key().

StringName get_typed_key_class_name() const 🔗

Возвращает встроенное имя класса ключей типизированного словаря, если встроенный тип Variant — @GlobalScope.TYPE_OBJECT. В противном случае возвращает пустой StringName. См. также is_typed_key() и Object.get_class().

Variant get_typed_key_script() const 🔗

Возвращает экземпляр Script, связанный с ключами этого типизированного словаря, или null, если он не существует. См. также is_typed_key().

int get_typed_value_builtin() const 🔗

Возвращает встроенный тип Variant значений типизированного словаря как константу Variant.Type. Если значения не типизированы, возвращает @GlobalScope.TYPE_NIL. См. также is_typed_value().

StringName get_typed_value_class_name() const 🔗

Возвращает встроенное имя класса значений типизированного словаря, если встроенный тип Variant — @GlobalScope.TYPE_OBJECT. В противном случае возвращает пустой StringName. См. также is_typed_value() и Object.get_class().

Variant get_typed_value_script() const 🔗

Возвращает экземпляр Script, связанный со значениями этого типизированного словаря, или null, если он не существует. См. также is_typed_value().

bool has(key: Variant) const 🔗

Возвращает true, если словарь содержит запись с заданным key.

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

print(my_dict.has("Godot")) # Выводит true
print(my_dict.has(210))     # Выводит true
print(my_dict.has(4))       # Выводит false

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

GD.Print(myDict.ContainsKey("Godot")); // Выводит True
GD.Print(myDict.ContainsKey(210));     // Выводит True
GD.Print(myDict.ContainsKey(4));       // Выводит False

В GDScript это эквивалентно оператору in:

if "Godot" in { "Godot": 4 }:
    print("Ключ здесь!") # Будет напечатано.

Примечание: Этот метод возвращает true до тех пор, пока существует key, даже если его соответствующее значение равно null.

bool has_all(keys: Array) const 🔗

Возвращает true, если словарь содержит все ключи в заданном массиве keys.

var data = { "width": 10, "height": 20 }
data.has_all(["height", "width"]) # Возвращает true

int hash() const 🔗

Возвращает хешированное 32-битное целое значение, представляющее содержимое словаря.

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

print(dict1.hash() == dict2.hash()) # Выводит true

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

// В Godot.Collections.Dictionary нет метода Hash(). Вместо него используйте GD.Hash().
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Выводит True

Примечание: Словари с одинаковыми записями, но в разном порядке, будут иметь разные хэши.

Примечание: Словари с одинаковыми значениями хэшей не гарантированно будут одинаковыми из-за коллизий хэшей. Напротив, словари с разными значениями хэшей гарантированно будут разными.

bool is_empty() const 🔗

Возвращает true, если словарь пуст (его размер 0). См. также size().

bool is_read_only() const 🔗

Возвращает true, если словарь доступен только для чтения. См. make_read_only(). Словари автоматически доступны только для чтения, если объявлены с ключевым словом const.

bool is_same_typed(dictionary: Dictionary) const 🔗

Возвращает true, если словарь имеет тот же тип, что и dictionary.

bool is_same_typed_key(dictionary: Dictionary) const 🔗

Возвращает true, если ключи словаря введены так же, как ключи dictionary.

bool is_same_typed_value(dictionary: Dictionary) const 🔗

Возвращает true, если значения словаря типизированы так же, как значения dictionary.

bool is_typed() const 🔗

Возвращает true, если словарь типизирован. Типизированные словари могут хранить только ключи/значения своего связанного типа и обеспечивают безопасность типов для оператора []. Методы типизированного словаря по-прежнему возвращают Variant.

bool is_typed_key() const 🔗

Возвращает true, если введены ключи словаря.

bool is_typed_value() const 🔗

Возвращает true, если значения словаря типизированы.

Array keys() const 🔗

Возвращает список ключей в словаре.

void make_read_only() 🔗

Делает словарь доступным только для чтения, т. е. отключает возможность изменения содержимого словаря. Не применяется к вложенному содержимому, например, содержимому вложенных словарей.

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

Добавляет записи из dictionary в этот словарь. По умолчанию дублирующиеся ключи не копируются, если только overwrite не равен true.

var dict = { "item": "sword", "quantity": 2 }
var other_dict = { "quantity": 15, "color": "silver" }

# Перезапись существующих ключей по умолчанию отключена.
dict.merge(other_dict)
print(dict)  # { "item": "sword", "quantity": 2, "color": "silver" }

# С возможностью перезаписи существующих ключей.
dict.merge(other_dict, true)
print(dict)  # { "item": "sword", "quantity": 15, "color": "silver" }

var dict = new Godot.Collections.Dictionary
{
    ["item"] = "sword",
    ["quantity"] = 2,
};

var otherDict = new Godot.Collections.Dictionary
{
    ["quantity"] = 15,
    ["color"] = "silver",
};

// Перезапись существующих ключей по умолчанию отключена.
dict.Merge(otherDict);
GD.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" }

// С возможностью перезаписи существующих ключей.
dict.Merge(otherDict, true);
GD.Print(dict); // { "item": "sword", "quantity": 15, "color": "silver" }

Примечание: merge() не рекурсивен. Вложенные словари рассматриваются как ключи, которые могут быть перезаписаны или нет в зависимости от значения overwrite, но они никогда не будут объединены вместе.

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

Возвращает копию этого словаря, объединенную с другим dictionary. По умолчанию дублирующиеся ключи не копируются, если только overwrite не равна true. См. также merge().

Этот метод полезен для быстрого создания словарей со значениями по умолчанию:

var base = { "fruit": "apple", "vegetable": "potato" }
var extra = { "fruit": "orange", "dressing": "vinegar" }
# Выводит { "fruit": "orange", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base))
# Выводит { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base, true))

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

Возвращает true, если два словаря содержат одинаковые ключи и значения, внутренние ключи и значения Dictionary и Array сравниваются рекурсивно.

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

Устанавливает значение элемента по заданному ключу key равным заданному значению value. Возвращает true, если значение установлено успешно. В случае ошибки возвращает false, если словарь доступен только для чтения или если key и value не соответствуют типам словаря. Это аналогично использованию оператора [] (dict[key] = value).

int size() const 🔗

Возвращает количество записей в словаре. Пустые словари ({ }) всегда возвращают 0. См. также is_empty().

void sort() 🔗

Сортирует словарь в порядке возрастания по ключу. Окончательный порядок зависит от сравнения «меньше чем» (<) между ключами.

var numbers = { "c": 2, "a": 0, "b": 1 }
numbers.sort()
print(numbers) # Выводит { "a": 0, "b": 1, "c": 2 }

Этот метод гарантирует, что записи словаря будут упорядочены последовательно, когда вызываются keys() или values(), или когда словарь необходимо преобразовать в строку с помощью @GlobalScope.str() или JSON.stringify().

Array values() const 🔗

Возвращает список значений в этом словаре.

Описания оператора

bool operator !=(right: Dictionary) 🔗

Возвращает true, если два словаря не содержат одинаковые ключи и значения.

bool operator ==(right: Dictionary) 🔗

Возвращает true, если два словаря содержат одинаковые ключи и значения. Порядок записей не имеет значения.

Примечание: В C# по соглашению этот оператор сравнивает по ссылке. Если вам нужно сравнить по значению, выполните итерацию по обоим словарям.

Variant operator [](key: Variant) 🔗

Возвращает соответствующее значение для указанного key в словаре. Если запись не существует, происходит сбой и возвращается null. Для безопасного доступа используйте get() или has().