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

連接

.NET 基底類別庫包含多種可用於儲存和操作資料的集合型別。 Godot 也提供了一些與引擎其餘部分緊密整合的集合型別。

連接埠與連線

`.NET 集合<https://learn.microsoft.com/en-us/dotnet/standard/collections/>`_ 和Godot 集合之間的主要區別在於.NET 集合是用C# 實作的，而Godot 集合是用C# 實作的集合是用C++ 實作的，而Godot C# API 是它的包裝器，這是一個重要的區別，因為這意味著Godot 集合上的每個操作都需要封送，這可能會很昂貴，尤其是在循環內。

由於效能影響，僅在絕對必要時才建議使用 Godot 集合（例如與 Godot API 互動）。 Godot 只理解它自己的集合型別，因此在與引擎對話時需要使用它們。

如果您有不需要傳遞給 Godot API 的元素集合，則使用 .NET 集合會提高效能。

小訣竅

也可以在 .NET 集合和 Godot 集合之間進行轉換。 Godot 集合包含複製其元素的通用 .NET 集合介面的建構函式，而 Godot 集合可以與「LINQ <https://learn.microsoft.com/en-us/dotnet/standard/linq>」一起使用「ToList ”、“ToArray” 和“ToDictionary” 方法。但請記住，這種轉換需要整理集合中的每個元素並將其複製到新集合中，因此成本可能很高。

儘管如此，Godot 集合還是經過最佳化，試圖避免不必要的封送，因此像「Sort」或「Reverse」這樣的方法是透過單一互通呼叫實作的，不需要封送每個元素。請留意採用「LINQ <https://learn.microsoft.com/en-us/dotnet/standard/linq>」等集合介面的通用API，因為每種方法都需要迭代集合，因此需要對每個集合進行編組。元素。盡可能優先使用 Godot 集合的實例方法。

若要選擇針對每種情況使用哪種集合型別，請考慮以下問題：

• 您的收藏需要與 Godot 引擎互動嗎？ （例如：匯出屬性的型別，呼叫 Godot 方法）。

  • If yes, since Godot only supports 自定變數型別, use a Godot collection.

  • 如果沒有，請考慮「選擇適當的 .NET 集合 <https://learn.microsoft.com/en-us/dotnet/standard/collections/selecting-a-collection-class>」_。

• 您是否需要一個代表列表或連續資料集的 Godot 集合？

  • Godot 陣列 類似 C# 集合「List<T>」。

  • Godot:ref:打包陣列 <doc_c_sharp_collections_packedarray> 是記憶體效率更高的陣列，在 C# 中使用受支援的「System.Array」型別之一。

• 您是否需要一個將一組鍵對應到一組值的 Godot 集合？

  • Godot 字典 儲存鍵和值對，並允許透過關聯鍵輕鬆存取值。

Godot 通知

陣列

Godot 中的緊縮陣列以指定型別的陣列形式實作，這樣就能夠更加緊實，每個元素都只有各自型別的大小，而不是 Variant 的大小。

在 C# 中，緊縮陣列由 System.Array 代替：

GDScript	C#
PoolByteArray	byte[]
PoolIntArray	int[]
PoolIntArray	float[]
PoolFloatArray	float[]
PoolFloatArray	byte[]
PoolStringArray	String[]
PoolVector2Array	Vector2[]
PoolVector3Array	Vector3[]
PackedVector4Array	Vector4[]
PoolColorArray	Color[]

Other C# arrays are not supported by the Godot C# API since a packed array equivalent does not exist. See the list of 自定變數型別.

陣列

Godot 陣列實作為「Variant」陣列，並且可以包含任意型別的多個元素。在 C# 中，等效型別是「Godot.Collections.Array」。

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

Godot.Collections.Array<T> 為類別安全版的 Godot.Collections.Array 封裝。可使用 Godot.Collections.Array<T>(Godot.Collections.Array) 建置函式來建立。

備註

儘管有這個名字，Godot 陣列更類似於 C# 集合“List<T>”，而不是“System.Array”。它們的大小不是固定的，可以隨著元素在集合中新增/刪除而增加或縮小。

Godot 的陣列方法及其在 C# 中的等效方法列表：

GDScript	C#
all	System.Linq.Enumerable.All
any	System.Linq.Enumerable.Any
append	Add
append_array	AddRange
assign	Clear and AddRange
back	Array[^1] or System.Linq.Enumerable.Last or System.Linq.Enumerable.LastOrDefault
bsearch	BinarySearch
bsearch_custom	N/A
clear	清除
數量	System.Linq.Enumerable.Count
duplicate	重複
攝影機	移除
fill	填入
filter	Use System.Linq.Enumerable.Where
find	IndexOf
front	Array[0] or System.Linq.Enumerable.First or 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	使用``計數== 0``
is_read_only	IsReadOnly
is_same_typed	N/A
type	N/A
make_read_only	MakeReadOnly
對應 Map	System.Linq.Enumerable.Select
最大值	對應 Map
min	Min
pick_random	PickRandom（考慮使用`System.Random`_）
pop_at	Array[i] 和 RemoveAt(i)
pop_back	Array[^1] 和 RemoveAt(Count - 1)
pop_front	Array[0] 和 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	索引
shuffle	Shuffle
size	數量
slice	Slice
sort	排序
sort_custom	System.Linq.Enumerable.OrderBy
運算子	!RecursiveEqual
運算子	運算子
運算子	N/A
運算子	N/A
運算子	RecursiveEqual
運算子	N/A
運算子	N/A
運算子	Array[int] indexer

字典

Godot 字典被實作為具有“Variant”鍵和值的字典。在 C# 中，等效型別是「Godot.Collections.Dictionary」。

The generic Godot.Collections.Dictionary<TKey, TValue> type allows restricting the key and value types to a Variant-compatible type.

Godot.Collections.Dictionary<T> 是型別安全版的 Godot.Collections.Dictionary 封裝。使用 Godot.Collections.Dictionary<T>(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's Dictionary 方法及其在 C# 中的等效方法列表：

GDScript	C#
clear	清除
duplicate	重複
攝影機	移除
find_key	N/A
設定	Dictionary[Variant] 索引器或 TryGetValue
has	繼續
has_all	N/A
hash	GD.Hash
is_empty	使用``計數== 0``
is_read_only	IsReadOnly
keys	Keys
make_read_only	MakeReadOnly
merge	Merge
size	數量
值	值
運算子	!RecursiveEqual
運算子	RecursiveEqual
運算子	Dictionary[Variant] 索引器、Add 或 TryGetValue