This page documents the Object base class, the ClassDB registration system, the property and method dispatch pipelines, the signal and connection mechanism, and the notification system. These systems collectively form the runtime object model for all engine types.
For the Variant, StringName, and Array types that are used throughout this system, see page 3.4 For how Node builds on top of Object, see page 4.1 For how Resource specializes Object, see page 5.2
Object (core/object/object.h) is the root class of Godot's type hierarchy. Every class registered with ClassDB ultimately inherits from it. It provides:
ObjectID)ScriptInstanceObjectGDExtension instanceEvery Object stores the following key members:
| Field | Type | Purpose |
|---|---|---|
_instance_id | ObjectID | Unique stable ID, used by ObjectDB |
signal_map | HashMap<StringName, SignalData> | All connected signals on this object |
connections | List<Connection> | Connections from this object to signals on others |
script_instance | ScriptInstance* | Attached script, if any |
_extension | ObjectGDExtension* | Attached GDExtension class, if any |
_extension_instance | GDExtensionClassInstancePtr | Extension-side instance data |
metadata | HashMap<StringName, Variant> | Arbitrary per-object key-value store |
_ancestry | uint32_t (bitfield) | Fast ancestor type checks |
_gdtype_ptr | const GDType* | Cached pointer to the class type info |
Sources: core/object/object.h620-672
Every C++ class that participates in the engine's type system declares itself with the GDCLASS(ClassName, ParentClass) macro core/object/object.h489-556 This macro generates:
get_class_static() — returns the StringName of the classget_gdtype_static() — returns a GDType reference, lazily initializedinitialize_class() — called once to register the class into ClassDB_setv, _getv, _get_property_listv, _notification_forwardv, _notification_backwardv, _validate_propertyv, and related virtualsinitialize_class() performs the following in order:
initialize_class() (recursive, up to Object)_add_class_to_classdb() to register the class in ClassDB_bind_methods() if this class overrides it from its parentEach class implements static void _bind_methods() to register its API. The following macros are the main tools:
| Macro | What it does |
|---|---|
ClassDB::bind_method(D_METHOD(...), ...) | Registers a method |
ADD_SIGNAL(MethodInfo(...)) | Registers a signal |
ADD_PROPERTY(PropertyInfo(...), setter, getter) | Registers a property with setter/getter names |
ADD_GROUP(name, prefix) | Adds a property grouping in the inspector |
ADD_SUBGROUP(name, prefix) | Adds a subgrouping |
BIND_ENUM_CONSTANT(value) | Registers an enum constant |
Sources: core/object/object.h135-154 core/object/class_db.h253-334
Class Registration Pipeline
Sources: core/object/object.h519-556 core/object/class_db.h255-312 core/object/class_db.cpp55-66
ClassDB (core/object/class_db.h core/object/class_db.cpp) is a global static registry. Its main data is:
ClassDB::classes : HashMap<StringName, ClassInfo>
Each ClassInfo contains:
| Field | Type | Contents |
|---|---|---|
method_map | HashMap<StringName, MethodBind*> | Bound methods |
signal_map | AHashMap<StringName, MethodInfo> | Declared signals |
property_list | List<PropertyInfo> | Ordered property metadata |
property_setget | AHashMap<StringName, PropertySetGet> | Property setter/getter bindings |
constant_map | AHashMap<StringName, int64_t> | Enum and constant values |
enum_map | HashMap<StringName, EnumInfo> | Enum groupings |
creation_func | Object*(*)(bool) | Factory function for instantiate() |
inherits_ptr | ClassInfo* | Direct parent |
Key ClassDB functions:
| Function | Purpose |
|---|---|
ClassDB::instantiate(name) | Create an instance of a named class |
ClassDB::get_method(class, name) | Retrieve a MethodBind* |
ClassDB::has_signal(class, name) | Check if signal exists in hierarchy |
ClassDB::get_property(obj, name, ret) | Invoke getter for a named property |
ClassDB::set_property(obj, name, val) | Invoke setter for a named property |
ClassDB::is_parent_class(A, B) | Check inheritance |
ClassDB::get_class_list(out) | Enumerate all registered classes |
Sources: core/object/class_db.h122-170 core/object/class_db.cpp226-320
PropertyInfo (core/object/object.h159-218) describes a single property:
| Field | Type | Meaning |
|---|---|---|
type | Variant::Type | Data type |
name | String | Property name |
class_name | StringName | Class name (for OBJECT types) |
hint | PropertyHint | How the editor should present the property |
hint_string | String | Hint-specific data (e.g. enum values, file filter) |
usage | uint32_t | Combination of PropertyUsageFlags |
Selected values from the PropertyHint enum core/object/object.h50-97:
| Value | Meaning |
|---|---|
PROPERTY_HINT_NONE | No editor hint |
PROPERTY_HINT_RANGE | Numeric range ("min,max[,step]") |
PROPERTY_HINT_ENUM | Dropdown list ("A,B,C") |
PROPERTY_HINT_FLAGS | Bitmask editor |
PROPERTY_HINT_RESOURCE_TYPE | Object must be a specific Resource subtype |
PROPERTY_HINT_FILE | File path picker |
PROPERTY_HINT_MULTILINE_TEXT | Multiline text editor |
Selected flags from PropertyUsageFlags core/object/object.h99-133:
| Flag | Bit | Meaning |
|---|---|---|
PROPERTY_USAGE_STORAGE | 1<<1 | Save to file |
PROPERTY_USAGE_EDITOR | 1<<2 | Show in inspector |
PROPERTY_USAGE_INTERNAL | 1<<3 | Hidden from scripts |
PROPERTY_USAGE_GROUP | 1<<6 | Start a group in inspector |
PROPERTY_USAGE_CATEGORY | 1<<7 | Section category header |
PROPERTY_USAGE_SCRIPT_VARIABLE | 1<<12 | Defined by a script |
PROPERTY_USAGE_READ_ONLY | 1<<28 | Not editable in inspector |
PROPERTY_USAGE_DEFAULT | STORAGE|EDITOR | Standard exported property |
When Object::set(name, value) is called, it walks through layers in order core/object/object.cpp335-416:
Object::get() follows the same layers in the same order core/object/object.cpp418-492
A class can add dynamic properties by overriding _get_property_list(), _get(), and _set(). This is how script variables appear as properties on objects at runtime. The GDCLASS macro wires these as virtual dispatch chains (_get_property_listv, _getv, _setv) so each class in the hierarchy can contribute properties.
Sources: core/object/object.cpp335-575 core/object/object.h729-735
Object::callp(method, args, argcount, error) core/object/object.cpp870-931 is the core method dispatch entry point:
method == "free", delete the object immediately.script_instance->callp().MethodBind* = ClassDB::get_method(class_name, method) and call it.MethodBind (in core/object/method_bind.h) is a type-erased wrapper around a C++ member function pointer. ClassDB::bind_method() creates one and stores it in ClassInfo::method_map.
Object::call_deferred() core/object/object.cpp734-755 instead pushes to MessageQueue for execution at idle time.
Sources: core/object/object.cpp870-931
Each Object has a signal_map field of type HashMap<StringName, SignalData> core/object/object.h643 SignalData stores:
user: MethodInfo — present only for user-defined signals added with add_user_signal()slot_map: HashMap<Callable, Slot> — one entry per connected callableSlot contains: conn (Connection), cE (iterator into connections list), reference_countThe connections list on Object tracks all connections from this object to signals on other objects, enabling cleanup when the object is freed.
Signal Data Layout
Sources: core/object/object.h630-644
Flags that modify connection behavior core/object/object.h573-580:
| Flag | Value | Effect |
|---|---|---|
CONNECT_DEFERRED | 1 | Callable is called via MessageQueue at idle time |
CONNECT_PERSIST | 2 | Connection is saved with the scene |
CONNECT_ONE_SHOT | 4 | Automatically disconnects after one emission |
CONNECT_REFERENCE_COUNTED | 8 | Disconnect only when reference count reaches zero |
CONNECT_APPEND_SOURCE_OBJECT | 16 | Append emitting object as last argument |
CONNECT_INHERITED | 32 | Used internally by the editor |
Object::emit_signalp(name, args, argcount) core/object/object.cpp1273:
The callables are copied under the signal lock before the lock is released. This ensures that connecting or disconnecting from within a signal handler, or deleting the emitting object, does not corrupt the iteration core/object/object.cpp1278-1313
_bind_methods() using ADD_SIGNAL(MethodInfo(...)). They exist in ClassDB::ClassInfo::signal_map and are shared across all instances.Object::add_user_signal() core/object/object.cpp1208-1218 They are stored in the instance's own signal_map.Object::notification(int what, bool reversed) dispatches an integer notification code through the class hierarchy. Two dispatch orders exist:
reversed == false): From Object toward the most-derived class. Used by most notifications (e.g. NOTIFICATION_READY).reversed == true): From most-derived class toward Object. Used by some cleanup notifications (e.g. NOTIFICATION_PREDELETE).Forward notification dispatch core/object/object.cpp1009-1027:
_notification_forwardv(what) — walks the C++ class chain from base to derived via virtual dispatch generated by GDSOFTCLASS/GDCLASS_extension->notification2(...) — GDExtension notificationscript_instance->notification(what, false) — script notificationBackward notification dispatch core/object/object.cpp1029-1047:
script_instance->notification(what, true)_extension->notification2(...)_notification_backwardv(what) — walks chain from derived to baseBuilt-in Object notifications:
| Constant | Value | When sent |
|---|---|---|
NOTIFICATION_POSTINITIALIZE | 0 | After object construction completes |
NOTIFICATION_PREDELETE | 1 | Before object destruction begins |
NOTIFICATION_PREDELETE_CLEANUP | 2 | After script/extension cleanup in destruction |
Sources: core/object/object.cpp1009-1047
Every Object receives a unique ObjectID at construction time. ObjectDB maintains a global map from ObjectID to Object*, enabling safe lookup by ID. The canonical pattern for validating a stored reference is:
This is used internally in _ObjectDebugLock core/object/object.cpp46-58 and in deferred call dispatching. ObjectID values are never reused within a session.
The AncestralClass bitfield core/object/object.h585-603 provides fast O(1) is_class() checks for a fixed set of frequently-tested ancestor types (NODE, REF_COUNTED, RESOURCE, CANVAS_ITEM, etc.) without string comparison or class hierarchy traversal.
Sources: core/object/object.h582-605 core/object/object.cpp46-58
When a Script is attached via Object::set_script() core/object/object.cpp1069-1097 a ScriptInstance is created and stored in script_instance. The ScriptInstance interface is defined in core/object/script_language.h.
At every layer of property access, method dispatch, and notification dispatch, the script instance is checked first core/object/object.cpp335-416 This means script properties, methods, and notifications shadow or extend their C++ counterparts.
Property and method lookup priority:
Sources: core/object/object.cpp335-416 core/object/object.cpp870-931
ObjectGDExtension (core/object/object.h316-380) is the struct that GDExtension registers for each class it exposes. It stores function pointers for every Object operation:
| Field | Role |
|---|---|
set / get | Property access |
get_property_list | Enumerate properties |
notification2 | Receive notifications |
create_instance2 | Factory |
free_instance | Destructor |
get_virtual2 | Resolve virtual method override |
call_virtual_with_data | Call a GDExtension virtual method |
When an Object has _extension != nullptr, these function pointers are invoked at each stage of the dispatch chains.
ClassDB::register_extension_class() core/object/class_db.cpp614 takes an ObjectGDExtension* and inserts it into ClassDB::classes with a ClassInfo that references it, making the extension class fully participatory in ClassDB::instantiate(), has_signal(), get_method(), etc.
Sources: core/object/object.h316-380 core/extension/gdextension.cpp240-330
Object provides a per-instance key-value store via set_meta() / get_meta() / has_meta() core/object/object.cpp1119-1206 Metadata is stored in HashMap<StringName, Variant> metadata. Keys must be valid ASCII identifiers. Metadata that does not begin with _ is surfaced in the inspector as metadata/<key> properties.
This store is intended for tooling and editor use — storing auxiliary data on objects without modifying the class definition. It is separate from exported class properties and is serialized independently.
Sources: core/object/object.cpp1115-1206
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.