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

Raccolte di C#

La libreria di classi base .NET contiene diversi tipi di collezioni che si possono utilizzare per archiviare e manipolare dati. Godot fornisce anche alcuni tipi di collezioni che sono strettamente integrati con il resto del motore.

Scegli una raccolta

La differenza principale tra le raccolte .NET e le raccolte Godot è che le raccolte .NET sono implementate in C# mentre le raccolte Godot sono implementate in C++ e l'API per C# di Godot è un wrapper su di esse. Questa è un'importante distinzione, poiché significa che ogni operazione su una raccolta Godot richiede il marshalling, il che può essere costoso soprattutto all'interno di un ciclo.

A causa delle implicazioni sulle prestazioni, è consigliato utilizzare le raccolte Godot solo quando assolutamente necessario (ad esempio, per interagire con l'API di Godot). Godot riconosce solo i propri tipi di raccolte, quindi è necessario utilizzarle quando si comunica con il motore.

Se si dispone di una raccolta di elementi che non è necessario passare a un'API in Godot, utilizzare una raccolta .NET sarebbe più performante.

Suggerimento

È anche possibile convertire tra raccolte .NET e raccolte Godot. Le raccolte Godot contengono costruttori di interfacce di raccolte .NET generiche che ne copiano gli elementi, e si possono utilizzare con i metodi LINQ ToList, ToArray e ToDictionary. Tuttavia, è importante tenere presente che questa conversione richiede il marshalling di ogni elemento nella raccolta e la sua copia in una nuova raccolta, quindi può essere costosa.

Nonostante ciò, le raccolte Godot sono ottimizzate per cercare di evitare operazioni di marshalling non necessarie, quindi metodi come Sort o Reverse sono implementati con una singola chiamata di interoperabilità e non necessitano di effettuare il marshalling di ogni elemento. Si consiglia di tenere d'occhio le API generiche che accettano interfacce di raccolte come LINQ, poiché ogni metodo richiede di iterare la raccolta e, pertanto, il marshalling di ogni elemento. Quando possibile, è preferibile utilizzare i metodi di istanza delle raccolte Godot.

Per scegliere quale tipo di raccolta utilizzare per ogni situazione, considerare le seguenti domande:

La propria raccolta deve interagire con il motore Godot? (ad esempio: il tipo di una proprietà esportata, la chiamata a un metodo di Godot).
- Se sì, poiché Godot supporta solo Tipi compatibili con Variant, utilizzare una raccolta Godot.
- Se non, si consideri di scegliere una raccolta .NET appropriata.
C'è bisogno di una raccolta Godot che rappresenti un elenco o un insieme sequenziale di dati?
- Gli array di Godot sono simili alla raccolta C# List<T>.
- Gli array impacchettati di Godot sono array più efficienti in memoria; in C# utilizzare uno dei tipi di System.Array supportati.
C'è bisogno di una raccolta Godot che associa un insieme di chiavi a un insieme di valori?
- I dizionari di Godot memorizzano coppie di chiavi e valori e permettono di accedere facilmente ai valori tramite le chiavi associate.

Raccolte di Godot

PackedArray

Gli array impacchettati di Godot sono implementati come array di un tipo specifico, impacchettando meglio la memoria poiché ogni elemento ha le dimensioni del tipo specifico, non Variant.

In C#, gli array impacchettati sono sostituiti da System.Array:

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

Altri array C# non sono supportati dall'API per C# di Godot, poiché non esiste un equivalente per gli array impacchettati. Consultare l'elenco di Tipi compatibili con Variant.

Array

Gli array di Godot sono implementati come array di tipo Variant e possono contenere diversi elementi di qualsiasi tipo. In C#, il tipo equivalente è Godot.Collections.Array.

Il tipo generico Godot.Collections.Array<T> consente di limitare il tipo di elemento a un tipo compatibile con Variant.

Un Godot.Collections.Array non tipizzato si può convertire in un array tipizzato attraverso il costruttore Godot.Collections.Array<T>(Godot.Collections.Array).

Nota

Nonostante il nome, gli array Godot sono più simili alla raccolta C# List<T> che a System.Array. La loro dimensione non è fissa e può aumentare o diminuire man mano che elementi sono aggiunti/rimossi dalla raccolta.

Elenco dei metodi di Array in Godot e dei loro equivalenti in 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]` o System.Linq.Enumerable.Last o System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/A
clear	Clear
count	System.Linq.Enumerable.Count
duplicate	Duplica
erase	Remove
fill	Fill
filter	Usa System.Linq.Enumerable.Where
find	IndexOf
front	`Array[0]` o System.Linq.Enumerable.First o 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	Usa `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 (Si consiglia di usare System.Random)
pop_at	`Array[i]` con `RemoveAt(i)`
pop_back	`Array[^1]` con `RemoveAt(Count - 1)`
pop_front	`Array[0]` con `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
Operatore !=	!RecursiveEqual
Operatore +	Operatore +
Operatore <	N/A
Operatore <=	N/A
Operatore ==	RecursiveEqual
Operatore >	N/A
Operatore >=	N/A
Operatore []	Indicizzatore Array[int]

Dizionario

I dizionari in Godot sono implementati come un dizionario con chiavi e valori Variant. In C#, il tipo equivalente è Godot.Collections.Dictionary.

Il tipo generico Godot.Collections.Dictionary<TKey, TValue> consente di limitare i tipi chiave e valore a un tipo compatibile con Variant.

Un Godot.Collections.Dictionary non tipizzato può essere convertito in un dizionario tipizzato attraverso il costruttore Godot.Collections.Dictionary<TKey, TValue>(Godot.Collections.Dictionary).

Suggerimento

Se è necessario un dizionario in cui è tipizzata la chiave ma non il valore, utilizzare Variant come parametro generico TValue del dizionario tipizzato.

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

Elenco dei metodi di Dictionary di Godot e dei loro equivalenti in C#:

GDScript	C#
clear	Clear
duplicate	Duplica
erase	Remove
find_key	N/A
get	Indicizzatore Dictionary[Variant] o TryGetValue
has	ContainsKey
has_all	N/A
hash	GD.Hash
is_empty	Usa `Count == 0`
is_read_only	IsReadOnly
chiavi	Keys
make_read_only	MakeReadOnly
merge	Merge
size	Count
values	Values
Operatore !=	!RecursiveEqual
Operatore ==	RecursiveEqual
Operatore []	Indicizzatore Dictionary[Variant], Add o TryGetValue