Коллекции C#

Библиотека базовых классов .NET содержит несколько типов коллекций, которые можно использовать для хранения и обработки данных. Godot также предоставляет несколько типов коллекций, тесно интегрированных с остальной частью движка.

Выберите коллекцию

Главное различие между коллекциями .NET и коллекциями Godot заключается в том, что коллекции .NET реализованы на языке C#, тогда как коллекции Godot реализованы на языке C++, а API Godot C# является оболочкой над ними. Это важное различие, поскольку оно означает, что каждая операция над коллекцией Godot требует маршалинга, который может быть затратным, особенно внутри цикла.

Из-за влияния на производительность использование коллекций Godot рекомендуется только в случае крайней необходимости (например, для взаимодействия с API Godot). Godot распознаёт только собственные типы коллекций, поэтому при взаимодействии с движком необходимо использовать именно их.

Если у вас есть коллекция элементов, которые не нужно передавать в API Godot, использование коллекции .NET будет более производительным.

Совет

Также возможно преобразование между коллекциями .NET и коллекциями Godot. Коллекции Godot содержат конструкторы из универсальных интерфейсов коллекций .NET, которые копируют их элементы, а коллекции Godot можно использовать с методами LINQ ToList, ToArray и ToDictionary. Но имейте в виду, что это преобразование требует маршалинга (marshaling) каждого элемента коллекции и копирования его в новую коллекцию, поэтому может быть затратным.

Несмотря на это, коллекции Godot оптимизированы для избежания ненужного маршалинга, поэтому такие методы, как Sort или Reverse, реализуются одним вызовом взаимодействия и не требуют маршалинга каждого элемента. Обратите внимание на универсальные API, принимающие интерфейсы коллекций, такие как LINQ, поскольку каждый метод требует итерации коллекции и, следовательно, маршалинга каждого элемента. По возможности предпочитайте использовать методы экземпляра коллекций Godot.

Чтобы выбрать, какой тип сбора использовать в каждой ситуации, рассмотрите следующие вопросы:

Должна ли ваша коллекция взаимодействовать с Godot engine? (например: тип экспортируемого свойства, вызов метода Godot).
- Если да, то, поскольку Godot поддерживает только Variant-compatible типы, используйте коллекцию Godot.
- Если нет, рассмотрите возможность выбора подходящей коллекции .NET.
Вам нужна коллекция Godot, представляющая собой список или последовательный набор данных?
- Godot arrays похожи на коллекцию C# List<T>.
- Godot packed arrays являются более эффективными по памяти массивами, в C# используйте один из поддерживаемых типов System.Array.
Вам нужна коллекция Godot, которая сопоставляет набор ключей с набором значений?
- Godot dictionaries хранят пары ключей и значений и обеспечивают легкий доступ к значениям по связанному с ними ключу.

Коллекции Godot

PackedArray

Упакованные массивы Godot реализованы как массив определенного типа, что позволяет упаковывать их более плотно, поскольку каждый элемент имеет размер определенного типа, а не Variant.

В C# упакованные массивы заменяются на System.Array:

GDScript	C#
`PackedByteArray`	`byte[]`
`PackedInt32Array`	`int[]`
`PackedInt64Array`	`long[]`
`PackedFloat32Array`	`float[]`
`PackedFloat64Array`	`double[]`
`PackedStringArray`	`string[]`
`PackedVector2Array`	`Vector2[]`
`PackedVector3Array`	`Vector3[]`
`PackedVector4Array`	`Vector4[]`
`PackedColorArray`	`Color[]`

Другие массивы C# не поддерживаются API Godot C#, поскольку для них не существует эквивалента упакованного массива. См. список Variant-compatible типы.

Массив

Массивы Godot реализованы как массив Variant и могут содержать несколько элементов любого типа. В C# эквивалентный тип — Godot.Collections.Array.

Универсальный тип Godot.Collections.Array<T> позволяет ограничить тип элемента до Variant-compatible type.

Нетипизированный Godot.Collections.Array можно преобразовать в типизированный массив с помощью конструктора Godot.Collections.Array<T>(Godot.Collections.Array).

Примечание

Несмотря на название, массивы Godot больше похожи на коллекцию List<T> в C#, чем на System.Array. Их размер не фиксирован и может увеличиваться или уменьшаться по мере добавления/удаления элементов в коллекцию.

Список методов массива Godot и их эквиваленты в C#:

GDScript	C#
all )все(	System.Linq.Enumerable.All
any (любой)	System.Linq.Enumerable.Any
append	Add
append_array	AddRange
assign	Очистить и AddRange (добавить диапазон)
back	`Array[^1]` или System.Linq.Enumerable.Last или System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/A
чисто	Clear
count	System.Linq.Enumerable.Count
duplicate	Дублировать
erase	Удалить
fill (заполнять)	Fill
filter	Используйте System.Linq.Enumerable.Where
find	IndexOf
front	`Array[0]` или System.Linq.Enumerable.First или System.Linq.Enumerable.FirstOrDefault
get_typed_builtin	N/A
get_typed_class_name	N/A
get_typed_script	N/A
has (имеет)	Contains (Содержит)
hash	GD.Hash
insert	Insert
is_empty	Использовать `Count == 0`
is_read_only	IsReadOnly
is_same_typed	N/A
is_typed	N/A
make_read_only	MakeReadOnly
map (карта)	System.Linq.Enumerable.Select
max	Max
min	Min
pick_random	PickRandom (Рассмотрите возможность использования System.Random)
pop_at	`Array[i]` с `RemoveAt(i)`
pop_back	`Array[^1]` с `RemoveAt(Count - 1)`
pop_front	`Array[0]` с `RemoveAt(0)`
push_back	`Insert(Count, item)`
push_front	`Insert(0, item)`
reduce (уменьшать)	System.Linq.Enumerable.Aggregate
remove_at	RemoveAt
resize (изменить размер)	Resize
reverse	Reverse
rfind	LastIndexOf
shuffle (перетасовка)	Shuffle
size (размер)	Count
slice (часть)	Slice
sort	Sort (Сортировать)
sort_custom	System.Linq.Enumerable.OrderBy
operator !=	!RecursiveEqual
operator +	operator +
operator <	N/A
operator <=	N/A
operator ==	RecursiveEqual
operator >	N/A
operator >=	N/A
operator []	Индексатор Array[int]

Словарь

Словари Godot реализованы как словарь с ключами и значениями типа Variant. В C# эквивалентный тип — Godot.Collections.Dictionary.

Универсальный тип Godot.Collections.Dictionary<TKey, TValue> позволяет ограничить типы ключей и значений до Variant-compatible type.

Нетипизированный Godot.Collections.Dictionary можно преобразовать в типизированный словарь с помощью конструктора Godot.Collections.Dictionary<TKey, TValue>(Godot.Collections.Dictionary).

Совет

Если вам нужен словарь, в котором типизирован ключ, но не значение, используйте Variant в качестве универсального параметра TValue типизированного словаря.

// The keys must be string, but the values can be any Variant-compatible type.
var dictionary = new Godot.Collections.Dictionary<string, Variant>();

Список методов словаря Godot и их эквиваленты в C#:

GDScript	C#
чисто	Clear
duplicate	Дублировать
erase	Удалить
find_key	N/A
get	Индексатор Dictionary[Variant] или TryGetValue
has (имеет)	ContainsKey (Содержит ключ)
has_all (есть все)	N/A
hash	GD.Hash
is_empty	Использовать `Count == 0`
is_read_only	IsReadOnly
ключи	Keys (ключи)
make_read_only	MakeReadOnly
merge (слияние)	Merge
size (размер)	Count
values (ценности)	Values
operator !=	!RecursiveEqual
operator ==	RecursiveEqual
operator []	Индексатор Dictionary[Variant], Add или TryGetValue