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...

Колекції C#

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

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

Основна відмінність між колекціями .NET і колекціями Godot полягає в тому, що колекції .NET реалізовано на C#, тоді як Godot Колекції реалізовано в C++, а Godot C# API є її оболонкою, це важлива відмінність, оскільки це означає, що кожна операція над колекцією Godot потребує маршалінгу, який може бути дорогим, особливо всередині циклу.

Через вплив на продуктивність використання колекцій Godot рекомендовано лише за крайньої необхідності (наприклад, під час взаємодії з Godot API). Godot розуміє лише власні типи колекцій, тому потрібно використовувати їх під час спілкування з двигуном.

Якщо у вас є колекція елементів, які не потрібно передавати в Godot API, використання колекції .NET буде більш продуктивним.

Порада

Також можна конвертувати між колекціями .NET і Godot. Колекції Godot містять конструктори із загальних інтерфейсів колекцій .NET, які копіюють їхні елементи, а колекції Godot можна використовувати з LINQ Методи ToList, ToArray і ToDictionary. Але майте на увазі, що це перетворення вимагає маршалінгу кожного елемента в колекції та копіювання його в нову колекцію, тому це може бути дорогим.

Незважаючи на це, колекції Godot оптимізовано, щоб спробувати уникнути непотрібного маршалінгу, тому такі методи, як Sort або Reverse, реалізуються за допомогою одного виклику взаємодії, і не потрібно маршалювати кожен елемент. Слідкуйте за загальними API, які використовують інтерфейси колекції, як-от LINQ, оскільки кожен метод вимагає ітерації колекції та, отже, маршалінгу кожного елемент. Віддавайте перевагу використанню методів екземплярів колекцій Godot, коли це можливо.

Щоб вибрати, який тип колекції використовувати для кожної ситуації, розгляньте такі запитання:

Чи потрібна ваша колекція взаємодії з механізмом Godot? (наприклад: тип експортованої властивості, виклик методу Godot).
- Якщо так, оскільки Godot підтримує лише Типи, сумісні з варіантами, використовуйте колекцію Godot.
- Якщо ні, спробуйте вибрати відповідну колекцію .NET.
Вам потрібна колекція Godot, яка представляє список або послідовний набір даних?
- Godot arrays подібні до колекції C# List<T>.
- Godot packed arrays є більш ефективними масивами, у C# використовуйте один із підтримуваних типів System.Array.
Вам потрібна колекція Godot, яка зіставляє набір ключів із набором значень?
- Godot dictionaries зберігають пари ключів і значень і дозволяють легко отримати доступ до значень за відповідним ключем.

Колекції Godot

PackedArray

Упаковані масиви Godot реалізовані як масив певного типу, що дозволяє його більш щільно упаковувати, оскільки кожен елемент має розмір певного типу, а не Variant.

У C# упаковані масиви замінено на System.Array:

Скрипт	C#
`PackedByteArray`	`byte[]`
`PackedInt32Array`	`int[]`
`PackedInt64Array`	`long[]`
`PackedFloat32Array`	`float[]`
`PackedFloat64Array`	`double[]`
`PackedStringArray`	`string[]`
`PackedVector2Array`	`Vector2[]`
`PackedVector3Array`	`Vector3[]`
`PackedVector4Array`	`Vector4[]`
`PackedColorArray`	`Color[]`

Інші масиви C# не підтримуються Godot C# API, оскільки еквівалент упакованого масиву не існує. Перегляньте список Типи, сумісні з варіантами.

Масив

Масиви Godot реалізовані як масив Variant і можуть містити декілька елементів будь-якого типу. У C# еквівалентним типом є Godot.Collections.Array.

Загальний тип Godot.Collections.Array<T> дозволяє обмежити тип елемента до Variant-сумісного типу.

Нетиповий Godot.Collections.Array можна перетворити на типізований масив за допомогою конструктора Godot.Collections.Array<T>(Godot.Collections.Array) конструктора.

Примітка

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

Список методів масиву Godotта їх еквівалентів у C#:

Скрипт	C#
all	System.Linq.Enumerable.All
any	System.Linq.Enumerable.Any
append	Add
append_array	AddRange
assign	Clear і AddRange
back	`Array[^1]` або System.Linq.Enumerable.Last або System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/A
clear	Clear
count	System.Linq.Enumerable.Count
duplicate	Дублювати
erase	Remove
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
min	Min
pick_random	PickRandom (розгляньте можливість використання System.Random)
pop_at	`Array[i]` з `RemoveAt(i)`
pop_back	`Масив[^1]` з `RemoveAt(Count - 1)`
pop_front	`Array[0]` with `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] Indexer

Словник

Словники Godot реалізовані як словник із ключами та значеннями Variant. У C# еквівалентним типом є Godot.Collections.Dictionary.

Загальний тип Godot.Collections.Dictionary<TKey, TValue> дозволяє обмежити типи ключів і значень до Variant-сумісного типу.

Нетиповий 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#:

Скрипт	C#
clear	Clear
duplicate	Дублювати
erase	Remove
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 []	Індексатор словника [Варіант], Add або TryGetValue