This page documents the runtime layer of the GDScript system: the GDScript resource class that holds compiled script data, GDScriptInstance for per-object runtime state, GDScriptCache for managing shared parsed and compiled scripts across dependencies, GDScriptParserRef for staged script analysis, GDScriptLanguage as the engine-wide language singleton, GDScriptNativeClass for native type wrapping, and GDScriptFunction for bytecode execution.
For tokenization and AST construction, see GDScript Parser. For semantic analysis and type checking, see GDScript Analyzer. For bytecode generation and VM execution, see GDScript Compiler & VM. For how resources are loaded in general, see ResourceLoader.
| File | Primary Classes |
|---|---|
modules/gdscript/gdscript.h/.cpp | GDScript, GDScriptInstance, GDScriptNativeClass, GDScriptLanguage |
modules/gdscript/gdscript_cache.h/.cpp | GDScriptCache, GDScriptParserRef |
modules/gdscript/gdscript_function.h/.cpp | GDScriptFunction, GDScriptDataType |
modules/gdscript/gdscript_vm.cpp | GDScriptFunction (VM Implementation) |
GDScript extends Script (which extends Resource). One GDScript object represents one .gd file and stores all compiled class data. Multiple engine objects can share the same GDScript; per-object state lives in GDScriptInstance.
modules/gdscript/gdscript.h57-185
| Field | Type | Description |
|---|---|---|
valid | bool | Whether the script compiled without errors modules/gdscript/gdscript.h60 |
tool | bool | Whether @tool is present modules/gdscript/gdscript.h59 |
_is_abstract | bool | Whether @abstract is present modules/gdscript/gdscript.h62 |
member_indices | HashMap<StringName, MemberInfo> | All instance variables (including inherited) mapped to index and metadata modules/gdscript/gdscript.h87 |
members | HashSet<StringName> | Only variables declared in this class (not inherited) modules/gdscript/gdscript.h88 |
static_variables_indices | HashMap<StringName, MemberInfo> | Static variable slot descriptors modules/gdscript/gdscript.h91 |
static_variables | Vector<Variant> | Live values of static variables modules/gdscript/gdscript.h92 |
constants | HashMap<StringName, Variant> | Compile-time constant values modules/gdscript/gdscript.h94 |
member_functions | HashMap<StringName, GDScriptFunction *> | All compiled methods modules/gdscript/gdscript.h95 |
subclasses | HashMap<StringName, Ref<GDScript>> | Inner class scripts modules/gdscript/gdscript.h96 |
_signals | HashMap<StringName, MethodInfo> | Signal definitions modules/gdscript/gdscript.h97 |
native | Ref<GDScriptNativeClass> | Root native base type modules/gdscript/gdscript.h82 |
base | Ref<GDScript> | Parent GDScript (if extends another .gd) modules/gdscript/gdscript.h83 |
instances | SelfList<GDScriptInstance>::List | All live objects currently using this script modules/gdscript/gdscript.h165 |
Each GDScript holds direct pointers to compiler-generated functions for initialization and lifecycle:
| Field | Called When |
|---|---|
implicit_initializer | Before _init(), initializes member variable default values modules/gdscript/gdscript.cpp139-153 |
initializer | The user's _init() method modules/gdscript/gdscript.cpp193-197 |
implicit_ready | Processes @onready annotations when the node enters the tree modules/gdscript/gdscript.h159 |
static_initializer | Initializes static variables at class load time modules/gdscript/gdscript.h160 |
modules/gdscript/gdscript.cpp155-206
When MyScript.new() is called, it routes through GDScriptNativeClass::_new(), which instantiates the native object via ClassDB::instantiate_no_placeholders() modules/gdscript/gdscript.cpp107-109 and then triggers _create_instance() to build and attach a GDScriptInstance.
_create_instance() performs these steps:
GDScriptInstance and sizes its members vector to match member_indices.size() modules/gdscript/gdscript.cpp158-159_super_implicit_constructor() recursively up the base chain, running each implicit_initializer to set up initial variable values modules/gdscript/gdscript.cpp177initializer (_init) if one exists and arguments were passed modules/gdscript/gdscript.cpp195Sources: modules/gdscript/gdscript.cpp68-206 modules/gdscript/gdscript.h40-185
GDScriptInstance implements ScriptInstance and holds per-object data for any engine Object that has a GDScript attached. It is created by GDScript::_create_instance() and attached via Object::set_script_instance().
modules/gdscript/gdscript.cpp155-206
| Field | Type | Description |
|---|---|---|
script | Ref<GDScript> | The class definition this instance belongs to modules/gdscript/gdscript.cpp160 |
owner | Object * | The host engine object (e.g. a Node) modules/gdscript/gdscript.cpp161 |
owner_id | ObjectID | Stable ID for validity checks across frames modules/gdscript/gdscript.cpp162 |
members | Vector<Variant> | Indexed storage of instance variable values modules/gdscript/gdscript.cpp159 |
Member values are accessed by integer index rather than name for performance. The VM uses these indices to resolve member variables during execution.
Sources: modules/gdscript/gdscript.cpp155-206 modules/gdscript/gdscript.h72-81
Diagram: GDScript Runtime Object Graph
Sources: modules/gdscript/gdscript.h57-185 modules/gdscript/gdscript.cpp155-206
GDScriptCache is a global singleton (GDScriptCache::singleton) that manages shared parser state and compiled scripts. It prevents redundant parsing and resolves cross-script dependencies.
modules/gdscript/gdscript_cache.cpp151-400
| Field | Type | Description |
|---|---|---|
parser_map | HashMap<String, Ref<GDScriptParserRef>> | Active parser state keyed by script path modules/gdscript/gdscript_cache.h80 |
shallow_gdscript_cache | HashMap<String, Ref<GDScript>> | Scripts compiled to interface level modules/gdscript/gdscript_cache.h83 |
full_gdscript_cache | HashMap<String, Ref<GDScript>> | Fully compiled scripts modules/gdscript/gdscript_cache.h84 |
mutex | Mutex | Protects all cache maps for thread safety modules/gdscript/gdscript_cache.cpp166 |
| Method | Description |
|---|---|
get_parser() | Gets or creates a GDScriptParserRef, advancing it to a status modules/gdscript/gdscript_cache.cpp278-316 |
get_shallow_script() | Returns a GDScript compiled through the interface stage modules/gdscript/gdscript_cache.cpp333-356 |
get_full_script() | Returns a fully compiled GDScript modules/gdscript/gdscript_cache.cpp358-390 |
remove_script() | Evicts a script from all caches modules/gdscript/gdscript_cache.cpp185-215 |
Sources: modules/gdscript/gdscript_cache.h1-90 modules/gdscript/gdscript_cache.cpp151-400
GDScriptParserRef wraps the parsing and analysis state for a script file. It advances through statuses via raise_status(), allowing the engine to solve circular dependencies by resolving inheritance and interfaces before method bodies.
modules/gdscript/gdscript_cache.cpp69-114
Diagram: GDScriptParserRef Status Machine
| Status | Implementation Step |
|---|---|
EMPTY | Initial state modules/gdscript/gdscript_cache.h17 |
PARSED | GDScriptParser::parse() converts source to AST modules/gdscript/gdscript_cache.cpp82-94 |
INHERITANCE_SOLVED | GDScriptAnalyzer::resolve_inheritance() modules/gdscript/gdscript_cache.cpp96-98 |
INTERFACE_SOLVED | GDScriptAnalyzer::resolve_interface() solves member signatures modules/gdscript/gdscript_cache.cpp100-102 |
FULLY_SOLVED | GDScriptAnalyzer::resolve_body() solves method logic modules/gdscript/gdscript_cache.cpp104-106 |
Sources: modules/gdscript/gdscript_cache.h15-75 modules/gdscript/gdscript_cache.cpp43-147
Diagram: Script Loading Sequence
Sources: modules/gdscript/gdscript_cache.cpp69-400 modules/gdscript/gdscript_compiler.cpp154-176
GDScriptLanguage is the engine-wide singleton managing the language lifecycle and editor integration.
modules/gdscript/gdscript.h430-600
| Responsibility | Description |
|---|---|
| Global Map | Manages indices for singletons and native types modules/gdscript/gdscript.h435-436 |
| Validation | Implements validate() for syntax checking modules/gdscript/gdscript_editor.cpp155-180 |
| Templates | Generates script templates via make_template() modules/gdscript/gdscript_editor.cpp92-129 |
| Profiling | Tracks native calls during execution modules/gdscript/gdscript_vm.cpp107-116 |
Sources: modules/gdscript/gdscript.h430-600 modules/gdscript/gdscript_editor.cpp58-180
Wraps native engine classes (e.g., Node, Sprite2D) so they can be treated as objects in GDScript for instantiation and static access.
modules/gdscript/gdscript.cpp68-124
| Method | Role |
|---|---|
_new() | Calls instantiate() to create the native object modules/gdscript/gdscript.cpp95-105 |
instantiate() | Uses ClassDB to create a native instance modules/gdscript/gdscript.cpp107-109 |
callp() | Handles static method calls for the native class modules/gdscript/gdscript.cpp111-124 |
Sources: modules/gdscript/gdscript.cpp68-124 modules/gdscript/gdscript.h40-55
Stores the compiled bytecode and metadata for a single function.
modules/gdscript/gdscript_function.h150-340
| Field | Description |
|---|---|
code | Bytecode instruction stream modules/gdscript/gdscript_function.h258 |
constants | Constant pool for literals modules/gdscript/gdscript_function.h260 |
argument_types | Type descriptors for parameters modules/gdscript/gdscript_function.h252 |
Runtime type descriptor used for type checking and validation.
modules/gdscript/gdscript_function.h46-148
| Field | Kind |
|---|---|
kind | VARIANT, BUILTIN, NATIVE, SCRIPT, or GDSCRIPT modules/gdscript/gdscript_parser.h105-114 |
is_type() | Validates a Variant against this type modules/gdscript/gdscript_function.cpp37-150 |
Sources: modules/gdscript/gdscript_function.h46-340 modules/gdscript/gdscript_function.cpp31-180
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.