This page provides an overview of the foundational systems that every Godot process depends on: the startup sequence, OS abstraction, project configuration, and fundamental data types and object model. These systems live primarily in the core/ and main/ directories.
For deeper coverage of individual subsystems, see:
The engine core is not a monolith — it is a set of cooperating singletons and registries that are initialized in a strict order before any scene logic runs. The diagram below shows which major classes exist, where they live in the source tree, and how they relate to each other.
Engine Core — Major Classes and Their Source Locations
Sources: main/main.cpp155-194 core/os/os.h45-300 core/config/project_settings.h1-100 core/object/object.h1-100 core/object/class_db.h1-100 core/string/ustring.h1-80
The Main class in main/main.cpp is a static class with no instances. It exposes three public entry points called by the platform-specific main() function: Main::setup(), Main::setup2(), and Main::start(). These run in sequence before the main loop begins.
Engine Startup Sequence
Sources: main/main.cpp155-194 main/main.h1-80
| Subsystem | Key Class(es) | Source Path | Role |
|---|---|---|---|
| Initialization | Main | main/main.cpp | Orchestrates startup/shutdown |
| OS Abstraction | OS | core/os/os.h | Platform-independent OS interface |
| Configuration | ProjectSettings | core/config/project_settings.h | project.godot key-value store |
| Engine Singleton | Engine | core/config/engine.h | Version info, frame counters |
| Object System | Object, ClassDB | core/object/object.h, core/object/class_db.h | Base class, reflection, signals |
| Type System | Variant | core/variant/variant.h | Dynamic polymorphic value container |
| Strings | String, StringName, NodePath | core/string/ | Unicode strings, interned names, paths |
| Input | Input, InputMap | core/input/ | Event collection and action mapping |
| Messaging | MessageQueue | core/object/message_queue.h | Deferred method calls |
| Images | Image | core/io/image.h | CPU-side pixel data |
Sources: main/main.cpp154-194 core/os/os.h45-140 core/config/project_settings.h1-80 core/object/object.h44-200 core/object/class_db.h1-100
OS (core/os/os.h) is an abstract singleton. Platform-specific subclasses implement its pure virtual methods. The two primary implementations are:
OS_Windows — platform/windows/os_windows.h / platform/windows/os_windows.cppOS_Unix — drivers/unix/os_unix.h / drivers/unix/os_unix.cpp (base for Linux, macOS, Android, iOS)OS Class Hierarchy
Sources: core/os/os.h45-300 platform/windows/os_windows.h30-120 drivers/unix/os_unix.h1-80
Key responsibilities of OS:
execute, create_process, kill)open_dynamic_library, close_dynamic_library, get_dynamic_library_symbol_handle)get_entropy) — used for cryptographic purposesCompositeLoggeruse_benchmark, benchmark_marks_from)_current_rendering_driver_name, _current_rendering_method)ProjectSettings (core/config/project_settings.cpp) is a global singleton that loads and stores settings from project.godot. It provides a typed key-value store keyed by StringName paths in category/property_name format.
Key behaviors:
. triggers platform-specific override lookup. For example, "application/run/max_fps.web" overrides the value on the web platform. Implemented in _set() at core/config/project_settings.cpp320-336globalize_path() converts res:// and user:// virtual paths to native OS paths. localize_path() does the reverse._custom_features key populates an internal custom_features set used by the feature tag system._queue_changed() fires the settings_changed signal after any write.autoload/ or global_group/ keys has side effects — _set() calls add_autoload() or add_global_group() automatically.The GLOBAL_GET(name) macro (used throughout the engine) is the standard way to read a setting at runtime.
Sources: core/config/project_settings.cpp53-376 core/config/project_settings.h1-100
Object (core/object/object.h) is the base class for virtually everything in the scene system, scripting, and servers. It provides:
_set, _get, and _get_property_list virtual methodsnotification(int)set_script, get_script_instance)ObjectID / ObjectDBClassDB (core/object/class_db.h) is a static compile-time registry. All classes derived from Object register themselves with ClassDB using the GDCLASS macro. This registration records:
ClassDB::bind_method)ADD_PROPERTY)ADD_SIGNAL)BIND_CONSTANT)This registration is what enables GDScript, C#, and GDExtensions to introspect and call engine classes at runtime.
Object System Relationships
Sources: core/object/object.h44-400 core/object/class_db.h1-200 core/object/object.cpp85-200 core/object/script_language.h1-100
Variant is the universal dynamic value type used throughout Godot's scripting interface, signals, and property system. It can hold any of the following types without heap allocation for small types:
| Category | Types |
|---|---|
| Primitives | bool, int (64-bit), float (32 or 64-bit) |
| Strings | String, StringName, NodePath |
| Math | Vector2, Vector3, Vector4, Quaternion, Transform2D, Transform3D, AABB, Basis, Plane, Color, Rect2 |
| Objects | Object* (weak reference) |
| Containers | Array, Dictionary |
| Packed arrays | PackedByteArray, PackedInt32Array, PackedFloat32Array, PackedStringArray, PackedVector2Array, etc. |
| Callable/Signal | Callable, Signal |
String (core/string/ustring.h) stores Unicode text internally as char32_t. It supports Latin-1, UTF-8, and UTF-16 conversion, and implements rich comparison operators including case-insensitive (nocasecmp_to), natural-sort (naturalcasecmp_to), and file-sort (filecasecmp_to) variants.
StringName is an interned string. Two StringName values holding the same text share the same underlying storage, making equality checks an O(1) pointer comparison. This is used extensively for property names, method names, and signal names.
NodePath represents a pre-parsed scene tree path such as "../Sibling/Child:property". It stores path components as StringName values.
Sources: core/string/ustring.h1-100 core/string/ustring.cpp1-100 core/variant/variant_call.cpp1-50
MessageQueue (core/object/message_queue.h) provides a deferred method call mechanism. Calls enqueued with call_deferred are held in a ring buffer and flushed at safe synchronization points during the frame. This prevents re-entrancy issues when modifying scene state from within a signal callback or _process. The singleton is allocated early in Main::setup() at main/main.cpp169
setup() vs setup2()The Main class carefully separates initialization into two phases because some systems (e.g., DisplayServer, RenderingServer) require ProjectSettings to already be populated.
Phase 1 — setup(): Core-only singletons
| Variable | Type | Role |
|---|---|---|
engine | Engine* | Version info, engine flags |
globals | ProjectSettings* | Project config |
input | Input* | Raw input state |
input_map | InputMap* | Action-to-event mapping |
translation_server | TranslationServer* | Localization |
performance | Performance* | Performance counters |
packed_data | PackedData* | .pck file system |
message_queue | MessageQueue* | Deferred calls |
Phase 2 — setup2(): Server singletons (require display)
| Variable | Type | Role |
|---|---|---|
display_server | DisplayServer* | Window/input server |
rendering_server | RenderingServer* | GPU rendering API |
audio_server | AudioServer* | Audio mixing |
physics_server_2d | PhysicsServer2D* | 2D physics |
physics_server_3d | PhysicsServer3D* | 3D physics |
tsman | TextServerManager* | Font/text shaping |
theme_db | ThemeDB* | UI theme data |
Sources: main/main.cpp154-194 main/main.cpp734-800
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.