Up to date

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

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

  • Do you need a Godot collection that represents a list or sequential set of data?

    • Godot arrays are similar to the C# collection List<T>.

    • Godot packed arrays are more memory-efficient arrays, in C# use one of the supported System.Array types.

  • Do you need a Godot collection that maps a set of keys to a set of values?

    • Godot dictionaries store pairs of keys and values and allow easy access to the values by their associated key.

Godot 合集

PackedArray

Godot 中的紧缩数组以指定类型的数组形式实现，这样就能够更加紧实，每个元素都只有各自类型的大小，而不是 Variant 的大小。

在 C# 中，紧缩数组由 System.Array 代替：

GDScript

C#

PackedInt32Array

int[]

PackedInt64Array

long[]

PackedByteArray

byte[]

PackedFloat32Array

float[]

PackedFloat64Array

double[]

PackedStringArray

string[]

PackedColorArray

Color[]

PackedVector2Array

Vector2[]

PackedVector3Array

Vector3[]

Other C# arrays are not supported by the Godot C# API since a packed array equivalent does not exist. See Variant for a list of all the compatible types.

数组

Godot arrays are implemented as an array of Variant and can contain several elements of any type. In C#, the equivalent type is Godot.Collections.Array.

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

An untyped Godot.Collections.Array can be converted to a typed array using the Godot.Collections.Array<T>(Godot.Collections.Array) constructor.

备注

Despite the name, Godot arrays are more similar to the C# collection List<T> than System.Array. Their size is not fixed and can grow or shrink as elements are added/removed from the collection.

List of Godot's Array methods and their equivalent in C#:

GDScript

C#

all

System.Linq.Enumerable.All

any

System.Linq.Enumerable.Any

append

Add

append_array

AddRange

assign

Clear 和 AddRange

back

Array[^1] 或 System.Linq.Enumerable.Last 或 System.Linq.Enumerable.LastOrDefault

bsearch

BinarySearch

bsearch_custom

N/A

clear（明显）

Clear

count

System.Linq.Enumerable.Count

duplicate

创建副本

erase

Remove

fill

Fill

filter

使用 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

Use 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 (Consider using System.Random)

pop_at

Array[i] with RemoveAt(i)

pop_back

Array[^1] with RemoveAt(Count - 1)

pop_front

Array[0] with 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

字典

Godot dictionaries are implemented as a dictionary with Variant keys and values. In C#, the equivalent type is Godot.Collections.Dictionary.

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

An untyped Godot.Collections.Dictionary can be converted to a typed dictionary using the Godot.Collections.Dictionary<TKey, TValue>(Godot.Collections.Dictionary) constructor.

小技巧

If you need a dictionary where the key is typed but not the value, use Variant as the TValue generic parameter of the typed dictionary.

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

List of Godot's Dictionary methods and their equivalent in C#:

GDScript

C#

clear（明显）

Clear

duplicate

创建副本

erase

Remove

find_key

N/A

get

Dictionary[Variant] indexer or TryGetValue

has

ContainsKey

has_all

N/A

hash

GD.Hash

is_empty

Use Count == 0

is_read_only

IsReadOnly

键

Keys

make_read_only

MakeReadOnly

merge

Merge

size

Count

values

Values

operator !=

!RecursiveEqual

operator ==

RecursiveEqual

operator []

Dictionary[Variant] indexer, Add or TryGetValue