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

Coleções C#

A biblioteca de classes base do .NET contém múltiplos tipos de coleções que podem ser usados para armazenar e manipular dados. O Godot também fornece alguns tipos de coleções que são fortemente integrados com o restante do motor.

Escolha uma coleção

A principal diferença entre as coleções do .NET e as coleções do Godot é que os tipos do .NET são implementados em C#, enquanto as coleções do Godot são implementadas em C++ e a API C# do Godot funciona como uma camada de encapsulamento (wrapper) sobre elas. Essa é uma distinção importante, pois significa que cada operação em uma coleção do Godot exige marshalling, o que pode ser caro, especialmente dentro de um loop.

Devido às implicações de desempenho, o uso de coleções do Godot só é recomendado quando for absolutamente necessário (como ao interagir com a API do Godot). O Godot só entende seus próprios tipos de coleção, portanto, é obrigatório usá-los ao se comunicar com o motor.

Se você tem uma coleção de elementos que não precisa ser passada para uma API do Godot, usar uma coleção do .NET será mais eficiente em termos de desempenho.

Dica

Também é possível fazer conversões entre coleções do .NET e coleções do Godot. As coleções do Godot contêm construtores a partir de interfaces de coleções genéricas do .NET que copiam seus elementos, e as coleções do Godot podem ser usadas com os métodos ToList, ToArray e ToDictionary do LINQ. Mas tenha em mente que essa conversão exige o marshalling de cada elemento na coleção e o copia para uma nova coleção, o que pode ser caro.

Apesar disso, as coleções do Godot são otimizadas para tentar evitar marshalling desnecessário, de modo que métodos como Sort ou Reverse são implementados com uma única chamada de interop e não precisam realizar o marshalling de cada elemento. Fique atento a APIs genéricas que aceitam interfaces de coleção, como o LINQ, pois cada método exige a iteração da coleção e, portanto, o marshalling de cada elemento. Prefira usar os métodos de instância das coleções do Godot quando possível.

Para escolher qual tipo de coleção usar em cada situação, considere as seguintes perguntas:

Sua coleção precisa interagir com o motor do Godot? (ex.: o tipo de uma propriedade exportada, a chamada de um método do Godot).
- Se sim, como o Godot suporta apenas Tipos compatíveis com Variant, use uma coleção do Godot.
- Se não, considere escolher uma coleção do .NET adequada.
Você precisa de uma coleção do Godot que represente uma lista ou um conjunto sequencial de dados?
- Os arrays do Godot são semelhantes à coleção C# List<T>.
- Os packed arrays do Godot são arrays mais eficientes em termos de memória; no C#, use um dos tipos suportados de System.Array.
Você precisa de uma coleção do Godot que mapeie um conjunto de chaves para um conjunto de valores?
- Os dicionários do Godot armazenam pares de chaves e valores e permitem fácil acesso aos valores por meio de sua chave associada.

Coleções Godot

PackedArray

Os packed arrays do Godot são implementados como um array de um tipo específico, permitindo que fiquem mais compactados na memória, já que cada elemento tem o tamanho do tipo específico, e não de um Variant.

No C#, os packed arrays são substituídos por System.Array:

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

Outros arrays do C# não são suportados pela API C# do Godot, pois não existe um equivalente em packed array. Veja a lista de Tipos compatíveis com Variant.

Vetor

Os arrays do Godot são implementados como um array de Variant e podem conter vários elementos de qualquer tipo. No C#, o tipo equivalente é Godot.Collections.Array.

O tipo genérico Godot.Collections.Array<T> permite restringir o tipo do elemento a um tipo compatível com Variant.

Um Godot.Collections.Array sem tipo pode ser convertido para um array tipado usando o construtor Godot.Collections.Array<T>(Godot.Collections.Array).

Nota

Apesar do nome, os arrays do Godot são mais semelhantes à coleção C# List<T> do que ao System.Array. O tamanho deles não é fixo e pode crescer ou diminuir conforme os elementos são adicionados/removidos da coleção.

Lista de métodos de Array do Godot e seus equivalentes em C#:

GDScript	C#
all	System.Linq.Enumerable.All
any	System.Linq.Enumerable.Any
append	Add
append_array	AddRange
assign	Clear e AddRange
back	`Array[^1]` ou System.Linq.Enumerable.Last ou System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/D
limpo	Clear
count	System.Linq.Enumerable.Count
duplicate	Duplicar
erase	Remove
fill	Preencher
filter	Use System.Linq.Enumerable.Where
find	IndexOf
front	`Array[0]` ou System.Linq.Enumerable.First ou System.Linq.Enumerable.FirstOrDefault
get_typed_builtin	N/D
get_typed_class_name	N/D
get_typed_script	N/D
has	Contains
hash	GD.Hash
insert	Insert
is_empty	Use `Count == 0`
is_read_only	IsReadOnly
is_same_typed	N/D
is_typed	N/D
make_read_only	MakeReadOnly
map	System.Linq.Enumerable.Select
max	Max
min	Min
pick_random	PickRandom (Considere usar System.Random)
pop_at	`Array[i]` com `RemoveAt(i)`
pop_back	`Array[^1]` com `RemoveAt(Count - 1)`
pop_front	`Array[0]` com `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
operador !=	!RecursiveEqual
operador +	operador +
operador <	N/D
operador <=	N/D
operador ==	RecursiveEqual
operador >	N/D
operador >=	N/D
operador []	Indexador Array[int]

Dicionário

Os dicionários do Godot são implementados como um dicionário com chaves e valores Variant. No C#, o tipo equivalente é Godot.Collections.Dictionary.

O tipo genérico Godot.Collections.Dictionary<TKey, TValue> permite restringir os tipos de chave e valor a um tipo compatível com Variant.

Um Godot.Collections.Dictionary sem tipo pode ser convertido para um dicionário tipado usando o construtor Godot.Collections.Dictionary<TKey, TValue>(Godot.Collections.Dictionary).

Dica

Se precisar de um dicionário onde a chave seja tipada, mas o valor não, use Variant como o parâmetro genérico TValue do dicionário tipado.

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

Lista de métodos de Dicionário do Godot e seus equivalentes em C#:

GDScript	C#
limpo	Clear
duplicate	Duplicar
erase	Remove
find_key	N/D
get	Indexador Dictionary[Variant] ou TryGetValue
has	ContainsKey
has_all	N/D
hash	GD.Hash
is_empty	Use `Count == 0`
is_read_only	IsReadOnly
chaves	Keys
make_read_only	MakeReadOnly
merge	Merge
size	Count
values	Values
operador !=	!RecursiveEqual
operador ==	RecursiveEqual
operador []	Indexador Dictionary[Variant], Add ou TryGetValue