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

對於 C 風格分配，Godot 提供了一些巨集：

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 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 提供自有的一套容器，表示在程式碼庫中一般不使用 STL 容器，如 std::string 與 std::vector。詳見為什麼Godot不使用STL(Standard Template Library)?。

📜 圖示表示該型別屬於 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`	將此作為「預設」對映（map）型別使用。不保留插入順序。請注意，映射中的指標以及反覆運算器在變異時都不是穩定的。若需要這些特性，請改用 `HashMap`。
StringName 📜	`std::string`	使用字串駐留以加速比較。適合用在經常被引用、且在引擎多處使用的靜態字串。
LocalVector	`std::vector`	語意更接近 `std::vector`，不使用 COW，因此比 `Vector` 更快。當不需要低成本複製時，優先於 `Vector` 使用它。
Array 📜	`std::vector`	元素可為任意 Variant 型別, 不強制靜態型別。使用共享參考計數, 類似 `std::shared_ptr`. 內部以 Vector<Variant> 實作。
TypedArray 📜	`std::vector`	`Array` 的子類別，但其元素具靜態型別。不要與 `Packed*Array` 混淆，後者在內部其實是 `Vector`。
Packed*Array 📜	`std::vector`	`Vector` 的別名，例如 `PackedColorArray = Vector<Color>`。僅提供有限幾種封包陣列型別（否則請使用 `TypedArray`）。
List	`std::list`	連結串列型別。一般比其他陣列/向量型別慢。除非能藉由使用 `List` 省去型別轉換，否則在新程式碼中應優先使用其它型別。
FixedVector	`std::array`	具有固定容量的向量（更接近 `boost::container::static_vector`）。由於不會進行堆積配置，這種容器比其他類向量型別更有效率。
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`	使用 COW 語意。因此一般較慢，但幾乎可以零成本地被複製。`VSet` 的效能優勢尚未明確，建議優先使用其他型別。
HashMap	`std::unordered_map`	具防禦性（穩健但較慢）的映射型別。保留插入順序。對鍵與值的指標，以及反覆運算器，在變異下皆是穩定的。當需要其中任一特性時請使用此型別。否則請使用 `AHashMap`。
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`	鍵與值可為任意 Variant 型別，不強制靜態型別。使用共享參考計數，類似 `std::shared_ptr`。保留插入順序。內部使用 `HashMap<Variant>`。
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_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

NodePath

這是一種特殊型別，用於在場景樹中儲存路徑，並以最佳化的方式進行參照：

core/string/node_path.h

RID

RID 是 Resource ID (資源識別碼)。伺服器使用這些 ID 來參照其內部儲存的資料。RID 為不透明型別, 無法直接存取其所參照的資料。即使對應的資料型別不同, RID 也保持唯一:

core/templates/rid.h