核心类型

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

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

内存分配

Godot has many tricks for ensuring memory safety and tracking memory usage. Because of this, the regular C and C++ library calls should not be used. Instead, a few replacements are provided.

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

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

These are equivalent to the usual malloc(), realloc(), and free() of the C standard library.

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

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

memnew_arr(Class, amount)
memdelete_arr(pointer_to_array)

These are equivalent to new, delete, new[], and delete[] respectively.

memnew/memdelete also use a little C++ magic to automatically call post-init and pre-release functions. For example, this is used to notify Objects right after they are created, and right before they are deleted.

• core/os/memory.h

容器

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

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

Godot 数据类型	最接近的 C++ STL 数据类型	注释
String 📜	std::string	Use this as the "default" string type. String uses UTF-32 encoding to simplify processing thanks to its fixed character size.
Vector	std::vector	请作为“默认”动态数组类型使用。采用写时复制（COW）机制。这意味着速度通常较慢，但可以几乎零成本地进行复制操作。不需要 COW、性能敏感时请改用 LocalVector。
HashSet	std::unordered_set	请作为“默认”集合类型使用。
AHashMap	std::unordered_map	请作为“默认”映射类型使用。不保持插入顺序。请注意，指向映射内部的指针和迭代器在映射发生修改后均不稳定。如果需要支持这些功能，请改用 HashMap。
StringName 📜	std::string	Uses string interning for fast comparisons. Use this for static strings that are referenced frequently and used in multiple locations in the engine.
LocalVector	std::vector	语义上接近 std::vector，不使用写时复制（COW），因此比 Vector 快。不需要用到轻量复制时优先于 Vector 使用。
Array 📜	std::vector	Values can be of any Variant type. No static typing is imposed. Uses shared reference counting, similar to std::shared_ptr. Uses Vector<Variant> internally.
TypedArray 📜	std::vector	Subclass of Array but with static typing for its elements. Not to be confused with Packed*Array, which is internally a Vector.
Packed*Array 📜	std::vector	Alias of Vector, e.g. PackedColorArray = Vector<Color>. Only a limited list of packed array types are available (use TypedArray otherwise).
List	std::list	链表类型。通常比其他数组/向量类型更慢。在新代码中建议优先使用其他类型，除非使用 List 能避免类型转换需求。
FixedVector	std::array	Vector with a fixed capacity (more similar to boost::container::static_vector). This container type is more efficient than other vector-like types because it makes no heap allocations.
Span	std::span	Represents read-only access to a contiguous array without needing to copy any data. Note that Span is designed to be a high performance API: It does not perform parameter correctness checks in the same way you might be used to with other Godot containers. Use with care. Span can be constructed from most array-like containers (e.g. vector.span()).
RBSet	std::set	使用红黑树实现快速访问。
VSet	std::flat_set	Uses copy-on-write (COW) semantics. This means it's generally slower but can be copied around almost for free. The performance benefits of VSet aren't established, so prefer using other types.
HashMap	std::unordered_map	Defensive (robust but slow) map type. Preserves insertion order. Pointers to keys and values, as well as iterators, are stable under mutation. Use this map type when either of these affordances are needed. Use AHashMap otherwise.
RBMap	std::map	Map type that uses a red-black tree to find keys. The performance benefits of RBMap aren't established, so prefer using other types.
Dictionary 📜	std::unordered_map	Keys and values can be of any Variant type. No static typing is imposed. Uses shared reference counting, similar to std::shared_ptr. Preserves insertion order. Uses HashMap<Variant> internally.
TypedDictionary 📜	std::unordered_map	Dictionary 的子类，对键和值进行了静态类型约束。
Pair	std::pair	Stores a single pair. See also KeyValue in the same file, which uses read-only keys.

Relocation safety

Godot's containers assume their elements are trivially relocatable.

This means that, if you store data types in it that have pointers to themselves, or are otherwise not trivially relocatable, Godot might crash. Note that storing pointers to objects that are not trivially relocatable, such as some Object subclasses, is unproblematic and supported.

The reason to assume trivial relocatability is that it allows us to make use of important optimization techniques, such as relocation by memcpy or realloc.

GH-100509 tracks this decision.

Multithreading / Concurrency

参见

You can find more information on multithreading strategies at 使用多线程.

None of Godot's containers are thread-safe. When you expect multiple threads to access them, you must use multithread protections.

Note that some of the types listed here are also available through the bindings, but the binding types are wrapped with RefCounted (found in the CoreBind:: namespace). Prefer the primitives listed here when possible, for efficiency reasons.

Godot 数据类型	最接近的 C++ STL 数据类型	注释
Mutex	std::recursive_mutex	Recursive mutex type. Use MutexLock lock(mutex) to lock it.
BinaryMutex	std::mutex	Non-recursive mutex type. Use MutexLock lock(mutex) to lock it.
RWLock	std::shared_timed_mutex	Read-write aware mutex type. Use RWLockRead lock(mutex) or RWLockWrite lock(mutex) to lock it.
SafeBinaryMutex	std::mutex	Recursive mutex type that can be used with ConditionVariable. Use MutexLock lock(mutex) to lock it.
ConditionVariable	std::condition_variable	Condition variable type, used with SafeBinaryMutex.
Semaphore	std::counting_semaphore	Counting semaphore type.
SafeNumeric	std::atomic	Templated atomic type, designed for numbers.
SafeFlag	std::atomic_bool	Bool atomic type.
SafeRefCount	std::atomic	Atomic type designed for reference counting. Will refuse to increment the reference count if it is 0.

数学类型

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

• core/math

节点路径

This is a special datatype used for storing paths in a scene tree and referencing them in an optimized manner:

• core/string/node_path.h

RID

RIDs are Resource IDs. Servers use these to reference data stored in them. RIDs are opaque, meaning that the data they reference can't be accessed directly. RIDs are unique, even for different types of referenced data:

• core/templates/rid.h