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