Up to date

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

連接

.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 方法）。

  • 如果是，由於 Godot 僅支援 Variant 相容的 <doc_c_sharp_variant>` 型別，因此使用 Godot 集合。

  • 如果沒有，請考慮「選擇適當的 .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#
PoolIntArray	int[]
PoolIntArray	float[]
PoolByteArray	byte[]
PoolFloatArray	float[]
PoolFloatArray	byte[]
PoolStringArray	String[]
PoolColorArray	Color[]
PoolVector2Array	Vector2[]
PoolVector3Array	Vector3[]

Godot C# API 不支援其他 C# 陣列，因為不存在等效的打包陣列。有關所有相容型別的列表，請參閱 Variant <doc_c_sharp_variant>`。

陣列

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

通用的 Godot.Collections.Array<T> 型別允許將元素型別限制為 Variant 相容的 <doc_c_sharp_variant> 型別。

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」。

通用的 Godot.Collections.Dictionary<TKey, TValue> 型別允許將鍵和值型別限制為 Variant 相容的 <doc_c_sharp_variant> 型別。

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