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

C# 集合

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

選擇集合類型

.NET 集合 與 Godot 集合的主要差異在於 .NET 集合是以 C# 實作，而 Godot 集合是以 C++ 實作，Godot 的 C# API 則是對其的包裝。這是一個重要的區別，因為這代表對 Godot 集合的每一個操作都需要資料編組（marshaling），這在迴圈中尤其會產生成本。

由於效能上的考量，僅在絕對必要時（如與 Godot API 互動時）才建議使用 Godot 集合。Godot 只認得自己的集合型別，因此在與引擎溝通時必須使用這些型別。

如果你的資料不需傳遞給 Godot API，建議使用 .NET 集合以獲得更佳效能。

小訣竅

你也可以在 .NET 集合與 Godot 集合之間互相轉換。Godot 集合提供從泛型 .NET 集合介面複製元素的建構子，且 Godot 集合能搭配 LINQ 的 ToList、ToArray 與 ToDictionary 方法一起使用。但請注意，這些轉換會對每個元素進行資料編組並複製到新集合，成本不低。

儘管如此，Godot 集合已經盡量最佳化以避免不必要的資料編組，例如 Sort 與 Reverse 這類方法只需透過單一跨語言呼叫執行，不會針對每一個元素做編組。但若使用像 LINQ 這類泛型 API，每次方法呼叫都會遍歷集合並對每個元素進行編組。建議盡量優先使用 Godot 集合的實體方法。

要選擇適合的集合型別，請考慮下列問題：

• 你的集合是否需要與 Godot 引擎互動？（例如：作為匯出屬性的型別、呼叫 Godot 方法等）。

  • 如果需要，因為 Godot 只支援 Variant 相容型別，請使用 Godot 集合型別。

  • 如果不需要，請考慮 選擇合適的 .NET 集合 。

• 你是否需要一個代表清單或序列資料的 Godot 集合？

  • Godot 陣列 類似於 C# 的 List<T> 集合。

  • Godot 打包陣列 是記憶體使用更有效率的陣列；在 C# 中可以用對應的 System.Array 型別。

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

  • Godot 字典 能儲存鍵值對，並可透過鍵快速存取對應的值。

Godot 集合

打包陣列

Godot 的打包陣列是以特定型別的陣列實作，因此每個元素都僅佔據該型別的大小，而不是 Variant，能更有效率使用記憶體。

在 C# 中，打包陣列可用 System.Array 來取代：

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

Godot C# API 不支援其他 C# 陣列，因為沒有對應的打包陣列型別。請參考 Variant 相容型別 取得支援型別列表。

陣列

Godot 陣列以 Variant 為元素型別，可以存放任何型別的多個元素。在 C# 中，對應型別為 Godot.Collections.Array。

泛型 Godot.Collections.Array<T> 可限制元素型別為 Variant-compatible type。

未指定型別的 Godot.Collections.Array 可以用 Godot.Collections.Array<T>(Godot.Collections.Array) 建構子轉換為指定型別的陣列。

備註

雖然名稱為「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
清除	清除
count	System.Linq.Enumerable.Count
duplicate	重複
erase	移除
fill	填入
filter	Use System.Linq.Enumerable.Where
find	IndexOf
front	Array[0] 或 System.Linq.Enumerable.First 或 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。

泛型 Godot.Collections.Dictionary<TKey, TValue> 可限制鍵和值的型別為 Variant-compatible type。

未指定型別的 Godot.Collections.Dictionary 可以用 Godot.Collections.Dictionary<TKey, TValue>(Godot.Collections.Dictionary) 建構子轉換為指定型別的字典。

小訣竅

如果你需要鍵有型別但值無型別的字典，可將 TValue 泛型參數設為 Variant。

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

Godot 字典方法及其在 C# 的對應方法列表：

GDScript	C#
清除	清除
duplicate	重複
erase	移除
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