Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

C#-Collections¶

Die .NET-Basisklassenbibliothek enthält mehrere Collection-Typen, die zum Speichern und Bearbeiten von Daten verwendet werden können. Godot bietet auch einige Collection-Typen, die eng in den Rest der Engine integriert sind.

Wählen Sie eine Collection¶

Der Hauptunterschied zwischen den .NET-Collections und den Godot-Collections besteht darin, dass die .NET-Collections in C# implementiert sind, während die Godot-Collections in C++ implementiert sind und die Godot-C#-API ein Wrapper darüber ist. Dies ist ein wichtiger Unterschied, da dies bedeutet, dass jede Operation an einer Godot-Collections ein Marshaling erfordert, das insbesondere innerhalb einer Schleife teuer sein kann.

Aufgrund der Auswirkungen auf die Performance wird die Verwendung von Godot-Collections nur empfohlen, wenn dies unbedingt erforderlich ist (z. B. bei der Interaktion mit der Godot-API). Godot versteht nur seine eigenen Collection-Typen, daher ist es erforderlich, diese zu verwenden, wenn man mit der Engine kommuniziert.

Wenn Sie eine Collection von Elementen haben, die nicht an eine Godot-API übergeben werden müssen, wäre die Verwendung einer .NET-Collection performanter.

Tipp

Es ist auch möglich, zwischen .NET-Collections und Godot-Collections zu konvertieren. Die Godot-Collections enthalten Konstruktoren von generischen .NET-Collection Interfaces, die ihre Elemente kopieren, und die Godot-Collections können mit den Methoden LINQ ToList, ToArray und ToDictionary verwendet werden. Aber bedenken Sie, dass diese Konvertierung ein Marshalling jedes Elements in der Collection erfordert und es in eine neue Collection kopiert, so dass es teuer werden kann.

Trotzdem sind die Godot-Collections optimiert, um unnötiges Marshalling zu vermeiden, so dass Methoden wie Sort oder Reverse mit einem einzigen Interop-Aufruf implementiert werden und nicht jedes Element marshallen müssen. Achten Sie auf generische APIs, die Collection-Schnittstellen wie LINQ verwenden, da jede Methode eine Iteration der Collection erfordert und somit jedes Element gemappt werden muss. Bevorzugen Sie, wenn möglich, die Instanzmethoden der Godot-Collections.

Um zu entscheiden, welche Art von Collection für die jeweilige Situation am besten geeignet ist, sollten Sie sich die folgenden Fragen stellen:

Muss Ihre Collection mit der Godot-Engine interagieren? (z. B.: Typ einer exportierten Property, Aufruf einer Godot-Methode).
- Wenn ja, verwenden Sie eine Godot Collection, da Godot nur Variant-kompatible-Typen unterstützt.
- Falls nicht, sollten Sie eine geeignete .NET Collection wählen.
Benötigen Sie eine Godot-Collection, die eine Liste oder einen sequentiellen Satz von Daten darstellt?
- Godot-Arrays sind ähnlich der C#-Collection List<T>.
- Godot-gepackte Arrays sind speichereffizientere Arrays, in C# verwenden Sie einen der unterstützten System.Array-Typen.
Benötigen Sie eine Godot-Collection, die einen Satz von Keys auf einen Satz von Values abbildet?
- Godot Dictionarys speichern Paare von Keys und Values und ermöglichen einen einfachen Zugriff auf die Values über den zugehörigen Key.

Godot-Collections¶

PackedArray¶

Gepackte Arrays in Godot sind als Array eines bestimmten Typs implementiert, was ein dichteres Packen ermöglicht, da jedes Element die Größe des spezifischen Typs und nicht die der Variante hat.

In C# werden gepackte Arrays durch System.Array ersetzt:

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

Weitere C#-Arrays werden von der Godot-C#-API nicht unterstützt, da ein gepacktes Array-Äquivalent nicht existiert. Siehe Variant für eine Liste aller kompatiblen Typen.

Array¶

Godot-Arrays sind als Array von Variant implementiert und können mehrere Elemente beliebigen Typs enthalten. In C# ist der entsprechende Typ Godot.Collections.Array.

Der generische Typ Godot.Collections.Array<T> erlaubt die Einschränkung des Elementtyps auf einen Variant-kompatiblen-Typ.

Ein untypisiertes Godot.Collections.Array kann mit dem Konstruktor Godot.Collections.Array<T>(Godot.Collections.Array) in ein typisiertes Array umgewandelt werden.

Bemerkung

Trotz des Namens ähneln Godot-Arrays eher der C#-Collection List<T> als System.Array. Ihre Größe ist nicht festgelegt und kann wachsen oder schrumpfen, wenn Elemente zur Collection hinzugefügt/entfernt werden.

Liste der Array-Methoden von Godot und ihre Entsprechung in C#:

GDScript	C#
all	System.Linq.Enumerable.All
any	System.Linq.Enumerable.Any
append	Add
append_array	AddRange
assign	Clear und AddRange
back	`Array[^1]` oder System.Linq.Enumerable.Last oder System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/A
clear	Clear
count	System.Linq.Enumerable.Count
duplicate	Duplicate
erase	Remove
fill	Fill
filter	Use System.Linq.Enumerable.Where
find	IndexOf
front	`Array[0]` oder System.Linq.Enumerable.First oder 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	Verwenden Sie `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 (Erwägen Sie die Verwendung von System.Random)
pop_at	`Array[i]` mit `RemoveAt(i)`
pop_back	`Array[^1]` mit `RemoveAt(Count - 1)`
pop_front	`Array[0]` mit `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

Dictionary¶

Godot Dictionarys sind als Dictionary mit Variant-Keys und -Values implementiert. In C# ist der entsprechende Typ Godot.Collections.Dictionary.

Der generische Typ Godot.Collections.Dictionary<TKey, TValue> erlaubt die Einschränkung der Key- und Value-Typen auf einen Variant-kompatiblen-Typ.

Ein untypisiertes Godot.Collections.Dictionary kann mit dem Konstruktor Godot.Collections.Dictionary<TKey, TValue>(Godot.Collections.Dictionary) in ein typisiertes Dictionary umgewandelt werden.

Tipp

Wenn Sie ein Dictionary benötigen, bei dem der Key typisiert ist, aber nicht der Value, verwenden Sie Variant als den generischen Parameter TValue des typisierten Dictionarys.

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

Liste der Dictionary-Methoden von Godot und ihre Entsprechung in C#:

GDScript	C#
clear	Clear
duplicate	Duplicate
erase	Remove
find_key	N/A
get	Dictionary[Variant]-Indexer oder TryGetValue
has	ContainsKey
has_all	N/A
hash	GD.Hash
is_empty	Verwenden Sie `Count == 0`
is_read_only	IsReadOnly
keys	Keys
make_read_only	MakeReadOnly
merge	Merge
size	Count
values	Values
operator !=	!RecursiveEqual
operator ==	RecursiveEqual
operator []	Dictionary[Variant]-Indexer, Add oder TryGetValue