Engine Core

Relevant source files

• core/config/project_settings.cpp
• core/config/project_settings.h
• core/core_bind.cpp
• core/core_bind.h
• core/core_constants.cpp
• core/extension/gdextension.cpp
• core/extension/gdextension.h
• core/extension/gdextension_interface.cpp
• core/extension/gdextension_interface.json
• core/extension/gdextension_interface.schema.json
• core/extension/gdextension_interface_header_generator.cpp
• core/extension/gdextension_interface_header_generator.h
• core/extension/gdextension_manager.cpp
• core/extension/gdextension_manager.h
• core/extension/make_interface_header.py
• core/input/input_enums.h
• core/math/math_funcs.cpp
• core/math/math_funcs.h
• core/object/class_db.cpp
• core/object/class_db.h
• core/object/make_virtuals.py
• core/object/method_bind.cpp
• core/object/method_bind.h
• core/object/method_bind_common.h
• core/object/object.cpp
• core/object/object.h
• core/os/os.cpp
• core/os/os.h
• core/variant/variant_utility.cpp
• core/variant/variant_utility.h
• doc/classes/@GlobalScope.xml
• doc/classes/ClassDB.xml
• doc/classes/GDExtension.xml
• doc/classes/GDExtensionManager.xml
• doc/classes/OS.xml
• doc/classes/Object.xml
• doc/classes/ProjectSettings.xml
• doc/classes/ResourceLoader.xml
• drivers/unix/os_unix.cpp
• drivers/unix/os_unix.h
• editor/editor_data.cpp
• editor/editor_data.h
• editor/editor_node.cpp
• editor/editor_node.h
• main/main.cpp
• main/main.h
• modules/gdscript/doc_classes/@GDScript.xml
• modules/gdscript/gdscript_utility_functions.cpp
• platform/windows/os_windows.cpp
• platform/windows/os_windows.h

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:

• Engine Initialization — Document the Main class and the engine startup sequence including setup phases, the main loop iteration, and cleanup.
• OS Abstraction Layer — Document the OS abstract class and its platform-specific implementations for process management, file access, environment variables, and timekeeping.
• ProjectSettings & EditorSettings — Document ProjectSettings for project-level configuration stored in project.godot and EditorSettings for project-independent editor configuration.
• Core Types & String System — Document the String, StringName, NodePath, Array, Dictionary, and Variant types that form the foundation of Godot's data model.
• Object & Signal System — Document the base Object class, its property system, signals and connections, ClassDB registration, and the notification system.
• Input System — Document the Input singleton, InputEvent hierarchy, and how input is collected and dispatched through the engine.
• Image & Texture System — Document the Image class for CPU-side pixel manipulation, supported formats, and the texture resource classes that wrap GPU-side images.
• Math & Geometry Utilities — Document the core math types (Vector2, Vector3, Basis, Transform, Quaternion, Color), geometry utilities, A* pathfinding, and expression evaluation used throughout the engine.

---

System Map

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.cpp164-176 core/os/os.h46-78 core/config/project_settings.h31-34 core/object/class_db.h37-51 core/io/image.h47-48

---

Initialization Order

The Main class in main/main.cpp is a static class with no instances. It exposes 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.cpp164-180 core/os/os.h132-141 platform/windows/os_windows.cpp163-180

---

Core Subsystems at a Glance

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.cpp164-176 core/os/os.h46-116 core/config/project_settings.h31-35 doc/classes/ProjectSettings.xml2-10

---

OS Abstraction

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.cpp
• OS_Unix — drivers/unix/os_unix.h / drivers/unix/os_unix.cpp (base for Linux, macOS, Android, iOS)

OS Class Hierarchy

Sources: core/os/os.h46-146 platform/windows/os_windows.cpp163-180 drivers/unix/os_unix.cpp166-186 doc/classes/OS.xml44-103

Key responsibilities of OS:

• Process management: Handled via execute, create_process, and kill doc/classes/OS.xml44-103
• Dynamic library loading: Platform implementations handle library handles via open_dynamic_library.
• Entropy source: Used for cryptographic purposes via get_entropy platform/windows/os_windows.cpp172
• Logging: OS provides the CompositeLogger used by the engine for output core/os/os.h100
• Benchmark tracking: Core support for timing benchmarks via use_benchmark and benchmark_marks_from core/os/os.h114-117
• Rendering driver tracking: Tracks the current driver and source (Project Setting, Command Line, etc.) core/os/os.h105-108

For details, see OS Abstraction Layer.

---

ProjectSettings

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.

Key behaviors:

• Feature overrides: Settings can be overridden based on platform or configuration using feature tags (e.g., application/config/name.windows) doc/classes/ProjectSettings.xml9-10
• Path virtualization: The localize_path() method converts native OS paths to res:// virtual paths core/config/project_settings.cpp157-185
• Feature Detection: Supports checking for required features (e.g., "Double Precision" or "C#") based on the build configuration core/config/project_settings.cpp81-116
• Change notification: Emits the settings_changed signal when configuration values are modified doc/classes/ProjectSettings.xml74

Sources: core/config/project_settings.cpp57-185 doc/classes/ProjectSettings.xml2-115

For details, see ProjectSettings & EditorSettings.

---

Object System and ClassDB

Object is the base class for virtually everything in the scene system and servers. It provides:

• Property system: Access to members via set and get core/object/object.cpp231-237
• Signal system: Support for signal emission and connection core/object/object.cpp109-115
• Notification dispatch: Internal messaging via notification(int) core/object/object.cpp173-179
• Lifecycle management: Handles cleanup through _predelete and initialization via _initialize core/object/object.cpp171-224

ClassDB is a static registry. All engine classes register themselves to record:

• Bound methods: Registered via ClassDB::bind_method core/core_bind.cpp150-156
• Signals and Properties: Macros like ADD_SIGNAL and ADD_PROPERTY register metadata with the database core/object/object.h46-50
• GDExtension Integration: ObjectGDExtension allows native extensions to hook into the object system core/object/object.h74-116

Sources: core/object/object.cpp171-237 core/object/object.h46-116 core/core_bind.cpp150-156

For details, see Object & Signal System.

---

Variant and Core Types

Variant is the universal dynamic value type used throughout Godot. It can hold primitives, math types, and complex containers.

Category	Types
Primitives	bool, int (64-bit), float
Strings	String, StringName, NodePath
Math	Vector2, Vector3, Color, Transform3D
Containers	Array, Dictionary, PackedByteArray

String stores Unicode text internally. StringName is an interned string used for performance-critical lookups where equality checks are pointer comparisons. ResourceLoader utilizes these types for file operations core/core_bind.cpp55-150

For details, see Core Types & String System.

---

MessageQueue

MessageQueue (core/object/message_queue.h) provides a deferred method call mechanism. Calls enqueued with call_deferred are held in a buffer and flushed during the main loop iteration. The singleton is allocated early in Main::setup() main/main.cpp176

---

Singletons Initialized in setup() vs setup2()

The Main class separates initialization into two phases because some systems require ProjectSettings to already be populated.

Phase 1 — setup(): Core-only singletons

Variable	Type	Role
engine	Engine*	Version info, engine flags main/main.cpp166
globals	ProjectSettings*	Project config main/main.cpp167
input	Input*	Raw input state main/main.cpp168
message_queue	MessageQueue*	Deferred calls main/main.cpp176

Phase 2 — setup2(): Server singletons

Variable	Type	Role
display_server	DisplayServer*	Window/input server main/main.cpp77
rendering_server	RenderingServer*	GPU rendering API main/main.cpp81
audio_server	AudioServer*	Audio mixing main/main.cpp74

Sources: main/main.cpp164-180 main/main.cpp74-85