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

The main difference between the .NET collections and the Godot collections is that the .NET collections are implemented in C# while the Godot collections are implemented in C++ and the Godot C# API is a wrapper over it, this is an important distinction since it means every operation on a Godot collection requires marshaling which can be expensive especially inside a loop.

Due to the performance implications, using Godot collections is only recommended when absolutely necessary (such as interacting with the Godot API). Godot only understands its own collection types, so it's required to use them when talking to the engine.

If you have a collection of elements that don't need to be passed to a Godot API, using a .NET collection would be more performant.

Suggerimento

It's also possible to convert between .NET collections and Godot collections. The Godot collections contain constructors from generic .NET collection interfaces that copy their elements, and the Godot collections can be used with the LINQ ToList, ToArray and ToDictionary methods. But keep in mind this conversion requires marshaling every element in the collection and copies it to a new collection so it can be expensive.

Despite this, the Godot collections are optimized to try and avoid unnecessary marshaling, so methods like Sort or Reverse are implemented with a single interop call and don't need to marshal every element. Keep an eye out for generic APIs that take collection interfaces like LINQ because every method requires iterating the collection and, therefore, marshaling every element. Prefer using the instance methods of the Godot collections when possible.

To choose which collection type to use for each situation, consider the following questions:

• Does your collection need to interact with the Godot engine? (e.g.: the type of an exported property, calling a Godot method).

  • If yes, since Godot only supports Tipi compatibili con Variant, use a Godot collection.

  • If not, consider choosing an appropriate .NET collection.

• Do you need a Godot collection that represents a list or sequential set of data?

  • Godot arrays are similar to the C# collection List<T>.

  • Godot packed arrays are more memory-efficient arrays, in C# use one of the supported System.Array types.

• Do you need a Godot collection that maps a set of keys to a set of values?

  • Godot dictionaries store pairs of keys and values and allow easy access to the values by their associated key.

Raccolte di Godot

PackedArray

Godot packed arrays are implemented as an array of a specific type, allowing it to be more tightly packed as each element has the size of the specific type, not 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[]

Other C# arrays are not supported by the Godot C# API since a packed array equivalent does not exist. See the list of 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.

The generic Godot.Collections.Array<T> type allows restricting the element type to a Variant-compatible type.

An untyped Godot.Collections.Array can be converted to a typed array using the Godot.Collections.Array<T>(Godot.Collections.Array) constructor.

Nota

Despite the name, Godot arrays are more similar to the C# collection List<T> than System.Array. Their size is not fixed and can grow or shrink as elements are added/removed from the collection.

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