GDScript System

Relevant source files

• core/extension/extension_api_dump.cpp
• core/object/script_language.cpp
• core/object/script_language.h
• core/object/script_language_extension.cpp
• core/object/script_language_extension.h
• doc/classes/Script.xml
• doc/classes/ScriptExtension.xml
• doc/classes/ScriptLanguageExtension.xml
• modules/gdscript/gdscript.cpp
• modules/gdscript/gdscript.h
• modules/gdscript/gdscript_analyzer.cpp
• modules/gdscript/gdscript_analyzer.h
• modules/gdscript/gdscript_byte_codegen.cpp
• modules/gdscript/gdscript_byte_codegen.h
• modules/gdscript/gdscript_cache.cpp
• modules/gdscript/gdscript_cache.h
• modules/gdscript/gdscript_codegen.h
• modules/gdscript/gdscript_compiler.cpp
• modules/gdscript/gdscript_compiler.h
• modules/gdscript/gdscript_disassembler.cpp
• modules/gdscript/gdscript_editor.cpp
• modules/gdscript/gdscript_function.cpp
• modules/gdscript/gdscript_function.h
• modules/gdscript/gdscript_parser.cpp
• modules/gdscript/gdscript_parser.h
• modules/gdscript/gdscript_tokenizer.cpp
• modules/gdscript/gdscript_tokenizer.h
• modules/gdscript/gdscript_vm.cpp
• modules/gdscript/gdscript_warning.cpp
• modules/gdscript/gdscript_warning.h
• modules/gdscript/tests/gdscript_test_runner.cpp
• modules/gdscript/tests/test_gdscript.cpp
• modules/mono/csharp_script.cpp
• modules/mono/csharp_script.h
• modules/mono/editor/bindings_generator.cpp
• modules/mono/editor/bindings_generator.h
• modules/mono/godotsharp_defs.h
• modules/mono/mono_gd/gd_mono.cpp
• modules/mono/mono_gd/gd_mono.h

GDScript is Godot's built-in dynamically-typed scripting language with optional static typing. This page covers the end-to-end processing pipeline: how .gd source files are transformed into executable bytecode and how scripts are instantiated at runtime. It also covers the language integration layer (GDScriptLanguage) and the script cache that manages dependencies between scripts.

For details on individual pipeline stages, see the child pages:

• Tokenizer and parser: GDScript Parser — Document the GDScriptParser and GDScriptTokenizer for converting GDScript source code into an Abstract Syntax Tree
• Semantic analysis and type checking: GDScript Analyzer — Document the GDScriptAnalyzer for semantic analysis including type checking, inheritance resolution, and member conflict detection
• Bytecode generation and VM execution: GDScript Compiler & VM — Document the GDScriptCompiler for bytecode generation and the GDScriptVM for executing compiled scripts
• Runtime objects and the script cache: GDScript Runtime & Cache — Document the GDScript resource class, GDScriptCache for managing script dependencies, and GDScriptInstance for runtime objects
• IDE integration and LSP: GDScript Language Server — Document the GDScript Language Server Protocol (LSP) implementation including the workspace, text document, and extend parser that power IDE integration features like code completion and go-to-definition

All GDScript source lives under modules/gdscript/.

---

Pipeline Overview

GDScript source code passes through four distinct stages before it can be executed. The process is orchestrated primarily through the GDScriptCache and GDScriptParserRef status levels.

Processing Pipeline — from source to execution

Sources: modules/gdscript/gdscript_parser.cpp1-30 modules/gdscript/gdscript_analyzer.cpp1-30 modules/gdscript/gdscript_compiler.cpp1-30 modules/gdscript/gdscript_vm.cpp1-30

---

Key Components

The GDScript system is divided into language registration, compilation utilities, runtime execution, and caching mechanisms.

Component Map — class names to files

Sources: modules/gdscript/gdscript.h31-82 modules/gdscript/gdscript_parser.h54-99 modules/gdscript/gdscript_analyzer.h31-50 modules/gdscript/gdscript_compiler.h31-50 modules/gdscript/gdscript_cache.h31-60

---

Stage 1: Tokenization

The GDScriptTokenizer base class (abstract) is implemented by concrete classes to handle different source formats. GDScriptTokenizer::Token structures represent the basic units of the language.

Class	File	Input	Use
GDScriptTokenizerText	gdscript_tokenizer.h	UTF-8 source string	Normal parsing and editor completion
GDScriptTokenizerBuffer	gdscript_tokenizer_buffer.h	Binary .gdc token stream	Pre-tokenized/exported scripts

The tokenizer handles Python-style block structure by synthesizing INDENT and DEDENT tokens. It also identifies keywords, literals, and punctuation.

Sources: modules/gdscript/gdscript_tokenizer.h31-50 modules/gdscript/gdscript_tokenizer_buffer.h1-30 modules/gdscript/gdscript_tokenizer.cpp1-50

---

Stage 2: Parsing

GDScriptParser (modules/gdscript/gdscript_parser.h54) consumes the token stream and produces an Abstract Syntax Tree (AST).

Entry Points

Method	Description
parse()	Parse source text; used for normal loading modules/gdscript/gdscript_parser.cpp159
parse_binary()	Parse a pre-built token buffer (.gdc files)

AST Node Types

Major structural nodes include ClassNode, FunctionNode, and VariableNode modules/gdscript/gdscript_parser.h59-99 The parser also manages annotations such as @tool, @icon, and @static_unload modules/gdscript/gdscript_parser.cpp146-148

DataType

GDScriptParser::DataType (modules/gdscript/gdscript_parser.h101-140) is the internal representation of types during parsing and analysis. It supports several kinds, including BUILTIN, NATIVE, SCRIPT, and CLASS modules/gdscript/gdscript_parser.h105-114

---

Stage 3: Semantic Analysis

GDScriptAnalyzer (modules/gdscript/gdscript_analyzer.cpp31) performs type checking and symbol resolution. It is driven by GDScriptParserRef status levels which transition the script through various solving states.

Analyzer State Transitions

The analyzer handles complex tasks like determining utility function return types modules/gdscript/gdscript_analyzer.cpp57-85 and creating metatypes for native classes modules/gdscript/gdscript_analyzer.cpp107-116

Sources: modules/gdscript/gdscript_analyzer.cpp31-130

---

Stage 4: Compilation

GDScriptCompiler (modules/gdscript/gdscript_compiler.cpp31) walks the analyzed AST and generates bytecode.

Key compilation tasks include:

• Type Conversion: Mapping parser DataType to runtime GDScriptDataType modules/gdscript/gdscript_compiler.cpp90-141
• Member Resolution: Checking if identifiers refer to local variables or class members modules/gdscript/gdscript_compiler.cpp44-69
• Bytecode Emission: Using GDScriptByteCodeGenerator to produce opcodes for the VM.

Sources: modules/gdscript/gdscript_compiler.cpp44-140

---

Stage 5: VM Execution

The GDScript Virtual Machine executes the generated bytecode. The VM is register-based, and the core execution logic resides in GDScriptFunction::call().

Runtime Data Types

GDScriptDataType at runtime validates whether a Variant matches a specific script or native type. The VM also handles default variant construction based on data types modules/gdscript/gdscript_vm.cpp120-153

Native Calls

The VM tracks native call performance and handles errors during cross-language or native calls modules/gdscript/gdscript_vm.cpp107-118

Sources: modules/gdscript/gdscript_vm.cpp1-153

---

The GDScript Resource

The GDScript class (modules/gdscript/gdscript.h57) is the Script resource that holds the compiled state.

Field	Purpose
member_indices	Layout of instance variables modules/gdscript/gdscript.h87
member_functions	Map of names to GDScriptFunction objects modules/gdscript/gdscript.h95
constants	Pool of script-level constants modules/gdscript/gdscript.h94
initializer	Pointer to the _init function modules/gdscript/gdscript.h156

When new() is called, GDScript::_create_instance() allocates a GDScriptInstance and runs the implicit and explicit constructor chains modules/gdscript/gdscript.cpp156-200

Sources: modules/gdscript/gdscript.h57-185 modules/gdscript/gdscript.cpp156-200

---

The Script Cache

GDScriptCache manages all loaded scripts to handle circular dependencies and avoid redundant parsing. It ensures scripts are correctly synchronized during loading and reloading.

Sources: modules/gdscript/gdscript_cache.cpp1-50

---

Editor Integration

GDScriptLanguage provides the interface for editor features, such as generating templates and validating scripts.

Feature	Implementation
Validation	Re-parses scripts to provide real-time error and warning reporting modules/gdscript/gdscript_editor.cpp155-170
Templates	Generates boilerplate code via make_template() modules/gdscript/gdscript_editor.cpp92-129
Warning System	Updates warning levels from project settings modules/gdscript/gdscript_parser.cpp96-140

Sources: modules/gdscript/gdscript_editor.cpp58-170 modules/gdscript/gdscript_parser.cpp96-140