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

核心类型

Godot 具有构成其核心的丰富的类和模板集，并且所有内容都基于它们构建。

这份参考将试着按顺序列出它们，使之更容易被理解。

内存分配

Godot 有许多确保内存安全和跟踪内存使用情况的技巧。因此，不应使用常规的 C 和 C++ 库调用。取而代之的是几个替代方案。

Godot提供了一些宏可以用来处理C风格的内存分配:

memalloc(size)
memrealloc(pointer)
memfree(pointer)

这些等效于C标准库中惯用的 malloc()、realloc()和free()。

这些宏可以用来处理C++风格的内存分配:

memnew(Class)
memnew(Class(args))
memdelete(instance)

memnew_arr(Class, amount)
memdelete_arr(pointer_to_array)

这些分别等效于new、delete、new[]和delete[]。

memnew/memdelete 还利用了一些 C++ 的“魔法”来自动调用后初始化（post-init）和预释放（pre-release）函数。例如，这用于在对象刚创建后以及即将被删除前通知它们。

core/os/memory.h

容器

Godot 提供了自己的容器，代码库中通常不使用 std::string、std::vector 等 STL 容器。详见为什么 Godot 不使用 STL（标准模板库）？。

📜 图标表示该类型属于 Variant。这意味着它可以作为 API 的方法参数和返回值暴露给脚本。

Godot 数据类型	最接近的 C++ STL 数据类型	注释
String 📜	`std::string`	请作为“默认”字符串类型使用。`String` 使用 UTF-32 编码，字符大小固定，从而简化了处理过程。
Vector	`std::vector`	请作为“默认”动态数组类型使用。采用写时复制（COW）机制。这意味着速度通常较慢，但可以几乎零成本地进行复制操作。不需要 COW、性能敏感时请改用 `LocalVector`。
HashSet	`std::unordered_set`	请作为“默认”集合类型使用。
AHashMap	`std::unordered_map`	请作为“默认”映射类型使用。不保持插入顺序。请注意，指向映射内部的指针和迭代器在映射发生修改后均不稳定。如果需要支持这些功能，请改用 `HashMap`。
StringName 📜	`std::string`	采用了字符串驻留（string interning）技术，以实现快速的比较操作。推荐将其用于那些在引擎多个位置被频繁引用的静态字符串。
LocalVector	`std::vector`	语义上接近 `std::vector`，不使用写时复制（COW），因此比 `Vector` 快。不需要用到轻量复制时优先于 `Vector` 使用。
Array 📜	`std::vector`	值（Values）可以是任意的 Variant（变体）类型，不强制要求静态类型。采用共享引用计数机制，类似于 `std::shared_ptr` 。底层内部使用的是 Vector<Variant>。
TypedArray 📜	`std::vector`	它是 `Array` 的子类，但对其中的元素有静态类型限制。注意不要把它和 `PackedArray` 搞混了，PackedArray 在内部实际上是一个 `Vector` （向量/容器）。
Packed*Array 📜	`std::vector`	这是 `Vector` （向量/动态数组）的一个别名，比如 `PackedColorArray = Vector<Color>` 。目前只有有限种类的打包数组类型可供选择（如果需要其他类型，请使用 `TypedArray` ）。
List	`std::list`	链表类型。通常比其他数组/向量类型更慢。在新代码中建议优先使用其他类型，除非使用 `List` 能避免类型转换需求。
FixedVector	`std::array`	一种具有固定容量的向量（更类似于 `boost::container::static_vector` ）。这种容器类型比其他类似向量的类型更高效，因为它不会进行任何堆内存分配。
Span	`std::span`	表示对于一段内存连续的数组的只读访问，并且无需复制任何数据。注意 `Span` 被设计为高性能 API：它不像其它您可能使用过的 Godot 容器一样执行参数正确性检查。请小心使用。Span 可以基于大多数数组形式的容器进行创建（例如 `vector.span()`）。
RBSet	`std::set`	使用红黑树来实现更快的访问。
VSet	`std::flat_set`	采用了写时复制（COW）的语义。这意味着它在一般情况下速度会稍慢一些，但几乎可以零成本地进行复制。由于 `VSet` 的性能优势目前尚未得到证实，所以更推荐优先使用其他类型。
HashMap	`std::unordered_map`	一种防御性（稳健但速度较慢）的映射（map）类型。它会保留元素的插入顺序。在发生数据变动（mutation）时，指向键（keys）和值（values）的指针以及迭代器（iterators）都能保持稳定。当你需要用到上述这些特性时，请使用这种映射类型；在其他情况下，请使用 `AHashMap` 。
RBMap	`std::map`	一种使用红黑树来查找键（key）的 Map 类型。由于 `RBMap` 的性能优势尚未得到证实，因此建议优先使用其他类型。
Dictionary 📜	`std::unordered_map`	键（Keys）和值（values）可以是任意的 Variant（变体）类型，不强制要求静态类型。采用共享引用计数机制，类似于 C++ 标准库里的 `std::shared_ptr` 。会保留元素的插入顺序。底层内部使用的是 `HashMap<Variant>` （哈希表）。
TypedDictionary 📜	`std::unordered_map`	`Dictionary` 的子类，对键和值进行了静态类型约束。
Pair	`std::pair`	它用来存储单一的一对数据。另外也可以看看同一个文件里的 `KeyValue` ，不过 KeyValue 里的键（key）是只读的。

重定位安全性

Godot 的容器（Containers）假设其内部元素是`trivially relocatable <https://open-std.org/JTC1/SC22/WG21/docs/papers/2020/p1144r5.html>`__。

这意味着，如果你在里面存储的数据类型包含指向自身的指针，或者由于其他原因导致它不是 not trivially relocatable ，Godot 可能会崩溃。不过请注意，存储指向那些‘非简单可重定位’对象（比如某些 Object 的子类）的指针，则是完全没有问题的，并且受到支持。

之所以要假设（某类型）具备平凡可重定位性，是因为这样我们就能利用一些重要的优化技术，比如直接通过 memcpy 或 realloc 来进行重定位。

GH-100509 跟踪此决定。

多线程 / 并发

参见

你可以在这里找到更多关于多线程策略的信息使用多线程.

Godot 的所有容器（Containers）都不是线程安全的。如果你预计会有多个线程同时访问它们，就必须自行使用多线程保护机制。

请注意，这里列出的某些类型也可以通过绑定（bindings）来使用，但这些绑定类型都被 RefCounted (found in the CoreBind:: namespace)包裹了一层。出于效率考虑，请尽可能优先使用这里列出的原生基础类型。

Godot 数据类型	最接近的 C++ STL 数据类型	注释
Mutex	`std::recursive_mutex`	递归互斥锁（Recursive mutex）类型。请使用 `MutexLock lock(mutex)` 语法来对它进行加锁。
BinaryMutex	`std::mutex`	非递归互斥锁（Non-recursive mutex）类型。请使用 `MutexLock lock(mutex)` 语法来对它进行加锁。
RWLock	`std::shared_mutex`	一种能识别“读/写”状态的互斥锁类型。请使用 `RWLockRead lock(mutex)` 或者 `RWLockWrite lock(mutex)` 的语法来对它进行加锁。
SafeBinaryMutex	`std::mutex`	一种可以与 `ConditionVariable` 搭配使用的递归互斥锁类型。使用 `MutexLock lock(mutex)` 来对它进行加锁。
ConditionVariable	`std::condition_variable`	条件变量类型，需配合 `SafeBinaryMutex` 一起使用。
Semaphore	`std::counting_semaphore`	计数 semaphore 类型。
SafeNumeric	`std::atomic`	专为数字设计的、基于模板的原子类型。
SafeFlag	`std::atomic_bool`	布尔（Bool）原子类型。
SafeRefCount	`std::atomic`	这是一种专为引用计数设计的原子类型。如果当前的引用计数已经是 0，它将拒绝（或者说无法）再执行递增操作。

数学类型

在 core/math 目录中有一些线性代数相关的类型：

core/math

节点路径

这是一种特殊的数据类型，专门用来存储场景树中的路径，并以一种高度优化的方式来引用它们。

core/string/node_path.h

RID

RID 指的是 资源 ID（Resource IDs） 。服务器（Servers）使用它们来引用存储在内部的数据。RID 是‘不透明’的，这意味着它们所引用的数据无法被直接访问。此外，RID 是独一无二的，即使它们引用的数据类型完全不同，也不会重复。

core/templates/rid.h