# Godot Engine — Administrator & Developer Guide

This guide provides exhaustive technical reference for building, configuring, deploying, and maintaining the Godot Engine (v4.x). It covers the server-based architecture, the SCons build system, every platform target, the module system, rendering backends, physics engines, text servers, the export pipeline, and operational concerns including debugging, profiling, and security. For basic usage, installation of pre-built binaries, and GDScript/editor workflows, see the User Guide.

---

## Table of Contents

- [1. Architecture Overview](#1-architecture-overview)
- [2. System Requirements](#2-system-requirements)
- [3. Configuration Reference](#3-configuration-reference)
- [4. Deployment & Scaling (Building from Source)](#4-deployment--scaling-building-from-source)
- [5. Operations](#5-operations)
- [6. Performance](#6-performance)
- [7. Security](#7-security)
- [8. Developer Internals](#8-developer-internals)
- [9. Integration Points](#9-integration-points)
- [10. Module Reference](#10-module-reference)
- [11. Platform Reference](#11-platform-reference)
- [12. Driver Reference](#12-driver-reference)
- [13. Troubleshooting](#13-troubleshooting)
- [14. Quick Reference](#14-quick-reference)

---

## 1. Architecture Overview

Godot Engine follows a **server-based architecture**. Every major subsystem is implemented as a "server" — a singleton manager that owns its domain's state and logic. Game code (GDScript, C#, GDExtension) communicates with servers through well-defined APIs. This separation allows rendering, physics, audio, and other subsystems to run on different threads and to be swapped out via alternative implementations.

### 1.1 High-Level Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│                        main/main.cpp                                │
│           Engine Initialization (setup → setup2 → start)            │
└──────────┬──────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       core/ — Foundation Layer                      │
│  ┌──────────┐ ┌────────┐ ┌─────────┐ ┌──────┐ ┌──────────────────┐│
│  │ Object   │ │Variant │ │   I/O   │ │ Math │ │   GDExtension    ││
│  │ ClassDB  │ │37 files│ │103 files│ │75 fl │ │   26 files       ││
│  │ MsgQueue │ │ 982K   │ │ 1.15M   │ │ 890K │ │   696K           ││
│  └──────────┘ └────────┘ └─────────┘ └──────┘ └──────────────────┘│
│  ┌──────────┐ ┌────────┐ ┌─────────┐ ┌──────┐ ┌──────────────────┐│
│  │  Config  │ │ String │ │  Input  │ │Crypto│ │    OS Abstraction││
│  │ ProjSets │ │ 563K   │ │ 268K    │ │ 55K  │ │    182K          ││
│  └──────────┘ └────────┘ └─────────┘ └──────┘ └──────────────────┘│
└──────────┬──────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    servers/ — Server Subsystems                      │
│  ┌───────────────┐ ┌──────────────┐ ┌────────────────────────────┐ │
│  │RenderingServer│ │ AudioServer  │ │     DisplayServer          │ │
│  │  59 files     │ │  12 files    │ │  + AccessibilityServer     │ │
│  │  2.64M chars  │ │  181K chars  │ │     271K chars             │ │
│  └───────────────┘ └──────────────┘ └────────────────────────────┘ │
│  ┌───────────────┐ ┌──────────────┐ ┌────────────────────────────┐ │
│  │PhysicsServer  │ │NavServer 2D/3│ │     TextServer             │ │
│  │ 2D (160K)     │ │  2D: 106K    │ │     273K chars             │ │
│  │ 3D (199K)     │ │  3D: 142K    │ │                            │ │
│  └───────────────┘ └──────────────┘ └────────────────────────────┘ │
│  ┌───────────────┐ ┌──────────────┐ ┌────────────────────────────┐ │
│  │   XRServer    │ │ CameraServer │ │     MovieWriter            │ │
│  │  21 files     │ │   4 files    │ │      4 files               │ │
│  │  165K chars   │ │   30K chars  │ │      28K chars             │ │
│  └───────────────┘ └──────────────┘ └────────────────────────────┘ │
└──────────┬──────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      scene/ — Scene System                          │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────────┐ │
│  │  GUI   │ │   3D   │ │   2D   │ │ SceneTree│ │  Animation     │ │
│  │118 files│ │110 fl  │ │ 56 fl  │ │  Window  │ │  21 files      │ │
│  │ 3.28M  │ │ 1.58M  │ │ 797K   │ │  945K    │ │  557K          │ │
│  └────────┘ └────────┘ └────────┘ └──────────┘ └────────────────┘ │
│  ┌────────┐ ┌────────┐                                             │
│  │ Theme  │ │Debugger│                                             │
│  │ 130K   │ │ 167K   │                                             │
│  └────────┘ └────────┘                                             │
└──────────┬──────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│              editor/ — Integrated Editor (TOOLS_ENABLED)            │
│  Animation(1.03M) | Scene(856K) | Inspector(783K) | Export(703K)    │
│  Docks(601K) | Settings(503K) | Themes(479K) | Script(468K)        │
│  Debugger+DAP(350K) | Import(341K) | ProjectUpgrade(291K)          │
│  ProjectManager(250K) | Shader(217K) | FileSystem(214K)            │
│  Run/Play(197K) | Translations(131K) | AssetLib(124K) | Audio(112K)│
│  VCS(101K) | Plugins(92K) | GUI(451K)                              │
└─────────────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│            modules/ — Optional, Compile-Time Selectable             │
│  gdscript(1.50M) | mono/.NET(1.07M) | godot_physics_3d(597K)       │
│  gltf(419K) | godot_physics_2d(410K) | text_server_adv(390K)       │
│  openxr(336K) | visual_shader(263K) | text_server_fb(242K)         │
│  multiplayer(198K) | jolt_physics(118K) | csg(119K) | fbx(114K)    │
│  + 20 more modules (image formats, noise, websocket, webrtc, etc.) │
└──────────┬──────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│             drivers/ — Platform-Specific Implementations            │
│  vulkan(472K) | metal(523K) | d3d12(432K) | gles3(1.16M total)     │
│  pulseaudio(298K) | alsa(413K) | wasapi(39K) | coreaudio(5K)       │
│  xaudio2(11K) | accesskit(87K) | sdl(23K) | unix(152K)             │
│  windows(96K) | apple(22K)                                          │
└──────────┬──────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────┐
│             platform/ — Platform Entry Points & Shells              │
│  windows(727K) | linuxbsd(630K) | android(429K+Java) | web(270K)    │
│  macos(163K) | ios(30K) | visionos(24K)                            │
└─────────────────────────────────────────────────────────────────────┘
```

### 1.2 Server-Based Design

The server pattern decouples high-level game logic from low-level subsystem implementation:

| Server | Singleton | Domain |
|--------|-----------|--------|
| `RenderingServer` | `RS` | All rendering: meshes, textures, shaders, viewports, environments |
| `AudioServer` | `AS` | Audio buses, effects, stream playback |
| `DisplayServer` | `DS` | Window management, input forwarding, clipboard, screen info |
| `PhysicsServer2D` | `PS2D` | 2D collision detection, rigid/static/area bodies |
| `PhysicsServer3D` | `PS3D` | 3D collision detection, joints, soft bodies |
| `NavigationServer2D` | `NS2D` | 2D pathfinding, avoidance |
| `NavigationServer3D` | `NS3D` | 3D pathfinding, navmesh |
| `TextServer` | `TS` | Font loading, text shaping, BiDi |
| `XRServer` | `XRS` | VR/AR device tracking, interfaces |
| `CameraServer` | `CS` | Camera feed management |
| `AccessibilityServer` | `ACS` | Screen reader integration |

Each server has a base class (abstract interface) in `servers/` and one or more concrete implementations either in `drivers/` or `modules/`. For example, `PhysicsServer3D` has both `GodotPhysicsServer3D` (built-in, in `modules/godot_physics_3d/`) and `JoltPhysicsServer3D` (in `modules/jolt_physics/`).

### 1.3 Initialization Flow

Engine startup in `main/main.cpp` follows three strictly ordered phases:

**Phase 1 — `Main::setup()`**
- Registers core types (Object, Variant, etc.)
- Initializes `Engine`, `ProjectSettings`, `Input`, `InputMap`, `TranslationServer`, `Performance`, `PackedData`, `MessageQueue`
- Parses command-line arguments
- Loads `project.godot` (ProjectSettings)
- Configures logging, locale, input mappings

**Phase 2 — `Main::setup2()`**
- Creates `DisplayServer` (platform-specific)
- Creates `RenderingServer` (with selected backend)
- Creates `AudioServer`, `CameraServer`, `AccessibilityServer`
- Initializes `TextServerManager`, `ThemeDB`
- Creates `PhysicsServer2D`, `PhysicsServer3D`
- Creates `XRServer`
- Registers scene types, resources, editor types (if `TOOLS_ENABLED`)
- Initializes platform-specific APIs

**Phase 3 — `Main::start()`**
- If CLI tool mode: executes tool and exits (e.g., `--export-release`, `--doctool`, `--test`)
- Otherwise: creates MainLoop (SceneTree), loads main scene or editor

> [!IMPORTANT]
> The three-phase initialization is critical for understanding startup failures. If the engine crashes during startup, identifying which phase failed (core registration vs. server creation vs. scene loading) narrows the root cause significantly. Check the log for the last successfully initialized server.

### 1.4 Object System and ClassDB

Every engine class inherits from `Object`. The `ClassDB` singleton maintains a registry of all classes, their methods, properties, signals, and constants. This registry powers:

- GDScript autocompletion and type checking
- Editor inspector property display
- Serialization/deserialization of scenes and resources
- GDExtension bindings generation

Registration happens at module initialization time via `register_types.cpp` in each module, using macros like `GDREGISTER_CLASS()`, `ClassDB::bind_method()`, and `ADD_PROPERTY()`.

### 1.5 Module Initialization Levels

Modules register their types at specific initialization levels, ensuring dependency ordering:

| Level | Constant | Purpose |
|-------|----------|---------|
| 0 | `MODULE_INITIALIZATION_LEVEL_CORE` | Core types, no server dependencies |
| 1 | `MODULE_INITIALIZATION_LEVEL_SERVERS` | Server-dependent types |
| 2 | `MODULE_INITIALIZATION_LEVEL_SCENE` | Scene node types |
| 3 | `MODULE_INITIALIZATION_LEVEL_EDITOR` | Editor-only types |

---

## 2. System Requirements

### 2.1 Build Host Requirements

| Platform Target | Host OS | Toolchain | Additional Dependencies |
|-----------------|---------|-----------|------------------------|
| Windows | Windows 10+, Linux (MinGW cross) | MSVC 2022+, MinGW-w64, or LLVM/Clang | Python 3.6+, SCons 4.0+ |
| Linux/BSD | Linux (any distro) | GCC 9+, or LLVM/Clang 6+ | Python 3.6+, SCons 4.0+, X11/Wayland dev libs |
| macOS | macOS 11+ | Xcode command-line tools or LLVM | Python 3.6+, SCons 4.0+ |
| Android | Any (cross-compile) | Android SDK + NDK, Gradle | `ANDROID_HOME` or `ANDROID_SDK_ROOT` env var |
| iOS | macOS | Xcode | Python 3.6+, SCons 4.0+ |
| Web | Any | Emscripten SDK | Python 3.6+, SCons 4.0+ |
| visionOS | macOS | Xcode 15+ with visionOS SDK | Swift frontend (`SWIFT_FRONTEND` env var) |
| macOS (cross from Linux) | Linux | OSXCross | `OSXCROSS_ROOT` env var |

### 2.2 Runtime Requirements

| Component | Requirement |
|-----------|-------------|
| **Rendering (Forward+)** | Vulkan 1.0+ capable GPU |
| **Rendering (Mobile)** | Vulkan 1.0+ or Metal |
| **Rendering (Compatibility)** | OpenGL ES 3.0 / WebGL 2.0 |
| **Direct3D 12** | Windows 10 (version 1607+), D3D12-capable GPU |
| **Metal** | macOS 10.15+ or iOS 13+ |
| **Android Editor** | Android API 29+ (Vulkan 1.1 required) |
| **C#/.NET** | .NET 8.0+ SDK and runtime |
| **Audio (Linux)** | PulseAudio or ALSA |
| **Audio (Windows)** | WASAPI (default) or XAudio2 |
| **Audio (macOS)** | CoreAudio |
| **XR** | OpenXR-compatible runtime |

### 2.3 Disk Space

| Build Configuration | Approximate Size |
|---------------------|-----------------|
| Source checkout | ~600 MB |
| Editor build (debug, all modules) | ~200-400 MB binary |
| Template release build | ~50-80 MB binary |
| SCons cache (recommended) | 2-10 GB |
| Full Android export templates | ~400 MB |

---

## 3. Configuration Reference

### 3.1 Project Configuration — `project.godot`

The `project.godot` file is the root configuration for every Godot project. It uses the TSCN (text scene) format. The `ProjectSettings` singleton manages access at runtime.

Key sections and settings:

| Section | Setting | Type | Description |
|---------|---------|------|-------------|
| `application` | `config/name` | String | Project name |
| `application` | `run/main_scene` | String | Main scene path |
| `application` | `config/features` | PackedStringArray | Required Godot features |
| `application` | `config/icon` | String | Application icon path |
| `display` | `window/size/viewport_width` | int | Default viewport width |
| `display` | `window/size/viewport_height` | int | Default viewport height |
| `display` | `window/stretch/mode` | String | Stretch mode (`disabled`, `canvas_items`, `viewport`) |
| `display` | `window/stretch/aspect` | String | Aspect ratio handling |
| `display` | `window/vsync/vsync_mode` | int | V-Sync mode |
| `rendering` | `renderer/rendering_method` | String | `forward_plus`, `mobile`, `gl_compatibility` |
| `rendering` | `renderer/rendering_method.mobile` | String | Override for mobile |
| `rendering` | `renderer/rendering_method.web` | String | Override for web |
| `physics` | `3d/physics_engine` | String | Physics backend (`GodotPhysics3D`, `JoltPhysics3D`) |
| `physics` | `2d/physics_engine` | String | Physics backend (`GodotPhysics2D`) |
| `internationalization` | `locale/translations` | PackedStringArray | Translation file paths |
| `input` | `<action_name>` | Dictionary | Input action definitions |
| `autoload` | `<name>` | String | Autoloaded scenes/scripts |
| `layer_names` | `2d_physics/layer_*` | String | Named physics layers |
| `layer_names` | `2d_render/layer_*` | String | Named render layers |
| `audio` | `buses/default_bus_layout` | String | Default audio bus layout path |

> [!NOTE]
> ProjectSettings supports platform-specific overrides using dot-notation suffixes. For example, `rendering/renderer/rendering_method.mobile` overrides the rendering method only when running on mobile platforms. This applies to any setting.

### 3.2 Editor Configuration — `editor_settings-4.tres`

Editor settings are stored per-user, not per-project:

| OS | Path |
|----|------|
| Windows | `%APPDATA%\Godot\editor_settings-4.tres` |
| macOS | `~/Library/Application Support/Godot/editor_settings-4.tres` |
| Linux | `~/.config/godot/editor_settings-4.tres` |

Key editor settings:

| Category | Setting | Description |
|----------|---------|-------------|
| `interface/editor` | `code_font_size` | Script editor font size |
| `interface/editor` | `display_scale` | Editor UI scale factor |
| `interface/theme` | `preset` | Theme preset (`Default`, `Breeze Dark`, etc.) |
| `filesystem/directories` | `autoscan_project_path` | Path auto-scanned for projects |
| `filesystem/directories` | `default_project_path` | Default new-project location |
| `network/debug` | `remote_host` | Remote debug host |
| `network/debug` | `remote_port` | Remote debug port |
| `text_editor/behavior` | `indent/type` | Indentation type (tabs/spaces) |
| `text_editor/behavior` | `indent/size` | Indentation size |
| `run` | `auto_save/save_before_running` | Auto-save on run |
| `export/android` | `java_sdk_path` | Path to Java SDK |
| `export/android` | `android_sdk_path` | Path to Android SDK |

### 3.3 Export Presets — `export_presets.cfg`

Export presets live in `export_presets.cfg` at the project root. Each preset section defines:

| Field | Description |
|-------|-------------|
| `name` | Preset display name |
| `platform` | Target platform identifier |
| `runnable` | Whether this preset is the "one-click deploy" target |
| `custom_features` | Comma-separated custom feature tags |
| `export_filter` | `all_resources`, `selected_resources`, or `customized` |
| `include_filter` | Glob pattern for included files |
| `exclude_filter` | Glob pattern for excluded files |
| `export_path` | Default output path |
| `encryption` | PCK encryption settings |
| `script_export_mode` | Script handling (text, compiled, encrypted) |

### 3.4 Project Data Directory — `.godot/`

The `.godot/` directory inside each project stores:

| Subdirectory | Contents |
|--------------|----------|
| `imported/` | Imported and cached resources |
| `editor/` | Editor-specific state (layout, breakpoints) |
| `uid_cache.bin` | Resource UID cache |
| `global_script_class_cache.cfg` | Cached script class information |

> [!WARNING]
> The `.godot/` directory should be added to `.gitignore`. It contains machine-specific import caches and editor state. Committing it causes conflicts in multi-developer projects and wastes repository space. If UID mismatches appear after cloning (see issue #117362), deleting `.godot/` and reopening the project forces a clean reimport.

### 3.5 Audio Bus Layout — `default_bus_layout.tres`

Audio bus configuration is stored as a resource file. The default layout is specified in `project.godot` under `audio/buses/default_bus_layout`. Buses are configured with:

- Volume (dB)
- Effects chain (reverb, delay, compressor, limiter, EQ, etc.)
- Solo/mute/bypass flags
- Send target bus

### 3.6 Input Map Configuration

Input actions are defined in `project.godot` under the `[input]` section. Each action maps a name to one or more input events:

```ini
[input]
move_forward={
"deadzone": 0.5,
"events": [Object(InputEventKey,"resource_local_to_scene":false,...,"keycode":87,...)]
}
```

Built-in actions (prefixed `ui_`) are defined in `InputMap::_setup_default_actions()` and can be overridden in project settings.

---

## 4. Deployment & Scaling (Building from Source)

### 4.1 Build System Overview

Godot uses **SCons** (Software Construction tool) for its build system. The build is configured through `SConstruct` at the repository root, with platform-specific configurations in `platform/<name>/detect.py` and module configurations in `modules/<name>/config.py`.

### 4.2 Core Build Commands

```bash
# Basic editor build (current platform)
scons platform=linuxbsd target=editor

# Release export template
scons platform=linuxbsd target=template_release

# Debug export template
scons platform=linuxbsd target=template_debug

# Build with tests enabled
scons platform=linuxbsd target=editor tests=yes

# Use Clang instead of GCC
scons platform=linuxbsd target=editor use_llvm=yes

# Generate compile_commands.json for IDE integration
scons platform=linuxbsd target=editor compiledb=yes

# Parallel build (8 jobs)
scons platform=linuxbsd target=editor -j8

# Custom modules from external directory
scons platform=linuxbsd target=editor custom_modules=/path/to/modules
```

### 4.3 Build Targets

| Target | Description | Use Case |
|--------|-------------|----------|
| `editor` | Full editor with tools | Development, content creation |
| `template_debug` | Debug export template | Testing exported projects with debugging |
| `template_release` | Release export template | Final distribution builds |

### 4.4 Build Options Reference

| Option | Values | Default | Description |
|--------|--------|---------|-------------|
| `platform` | `windows`, `linuxbsd`, `macos`, `android`, `ios`, `web`, `visionos` | Auto-detected | Target platform |
| `target` | `editor`, `template_debug`, `template_release` | `editor` | Build target |
| `use_llvm` | `yes`/`no` | `no` | Use LLVM/Clang compiler |
| `tests` | `yes`/`no` | `no` | Build with unit tests |
| `compiledb` | `yes`/`no` | `no` | Generate `compile_commands.json` |
| `custom_modules` | path | — | External modules directory |
| `precision` | `single`/`double` | `single` | Floating-point precision |
| `production` | `yes`/`no` | `no` | Production build (LTO, smaller binary) |
| `dev_build` | `yes`/`no` | `no` | Development build (extra assertions, verbose) |
| `debug_symbols` | `yes`/`no` | Varies | Include debug symbols |
| `optimize` | `speed`/`size`/`none`/`debug` | Varies by target | Optimization level |
| `use_static_cpp` | `yes`/`no` | Platform-dependent | Static C++ linking |
| `werror` | `yes`/`no` | `no` | Treat warnings as errors |
| `deprecated` | `yes`/`no` | `yes` | Include deprecated API |
| `minizip` | `yes`/`no` | `yes` | Minizip support |
| `vulkan` | `yes`/`no` | `yes` | Vulkan rendering backend |
| `opengl3` | `yes`/`no` | `yes` | OpenGL ES 3.0 backend |
| `d3d12` | `yes`/`no` | `yes` (Windows) | Direct3D 12 backend |
| `metal` | `yes`/`no` | `yes` (Apple) | Metal backend |

### 4.5 Environment Variables

| Variable | Purpose |
|----------|---------|
| `BUILD_NAME` | Custom build identifier (appears in editor "About") |
| `GODOT_VERSION_STATUS` | Override version status string |
| `SCONS_CACHE` | SCons cache directory path (speeds up rebuilds) |
| `SCONS_CACHE_LIMIT` | Maximum cache size in MB |
| `CCACHE` | Path to ccache binary for compiler caching |
| `ANDROID_HOME` | Android SDK root (also `ANDROID_SDK_ROOT`) |
| `GODOT_ANDROID_SIGN_KEYSTORE` | Path to Android signing keystore |
| `GODOT_ANDROID_KEYSTORE_ALIAS` | Android keystore alias |
| `GODOT_ANDROID_SIGN_PASSWORD` | Android signing password |
| `OSXCROSS_ROOT` | OSXCross root for macOS cross-compilation from Linux |
| `SWIFT_FRONTEND` | Swift frontend path (required for visionOS builds) |

> [!TIP]
> Set `SCONS_CACHE` to a persistent directory (e.g., `~/.scons_cache`) and `SCONS_CACHE_LIMIT` to `4096` (4 GB). This dramatically speeds up incremental rebuilds — especially useful when switching between branches or build configurations. Combined with `ccache`, typical incremental rebuilds drop from minutes to seconds.

### 4.6 Disabling Modules at Build Time

Any module in `modules/` can be disabled at build time by passing `module_<name>_enabled=no`:

```bash
# Build without C#/.NET support
scons platform=linuxbsd target=editor module_mono_enabled=no

# Build without GDScript (unusual, but possible)
scons platform=linuxbsd target=editor module_gdscript_enabled=no

# Minimal build: disable multiple modules
scons platform=linuxbsd target=template_release \
  module_mono_enabled=no \
  module_webrtc_enabled=no \
  module_websocket_enabled=no \
  module_upnp_enabled=no \
  module_camera_enabled=no
```

Each module's `config.py` defines:
- `can_build(env, platform)` — whether the module can build on the given platform
- `is_enabled()` — default enabled state
- `get_doc_classes()` — classes that have documentation XML
- `get_doc_path()` — path to documentation XML files

### 4.7 Android Build Pipeline

Android builds use Gradle on top of SCons. The pipeline:

1. SCons compiles native C++ code for target ABIs (`arm32`, `arm64`, `x86_32`, `x86_64`)
2. Native libraries are placed in the Gradle project at `platform/android/java/lib/`
3. Gradle builds the final APK/AAB

```bash
# Build Android editor (arm64)
scons platform=android target=editor arch=arm64

# Build Android export templates
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=arm32

# Install Android build template into a project
godot --install-android-build-template
```

Android-specific identifiers:

| Property | Value |
|----------|-------|
| Editor application ID | `org.godotengine.editor.v4` |
| Minimum SDK (editor) | API 29 (Android 10) — requires Vulkan 1.1 |
| Supported ABIs | `arm32`, `arm64`, `x86_32`, `x86_64` |
| Build flavors | `editor`, `template` |
| Build editions | `standard`, `mono` |
| Android distributions | `android`, `horizonos`, `picoos` |

### 4.8 Web Build Pipeline

Web builds require Emscripten:

```bash
# Source the Emscripten environment first
source /path/to/emsdk/emsdk_env.sh

# Build web export template
scons platform=web target=template_release

# Build web editor (experimental)
scons platform=web target=editor
```

The web development server is at `platform/web/serve.py`:

```bash
# Start dev server
python platform/web/serve.py --port 8060 --root ../../bin

# Don't auto-open browser
python platform/web/serve.py --no-browser
```

The dev server features:
- Dual-stack (IPv4+IPv6) via `DualStackServer`
- Proper CORS headers via `CORSRequestHandler`
- Configurable root directory (default: `../../bin`)
- Default port: 8060

### 4.9 Cross-Compilation

**macOS from Linux** (OSXCross):
```bash
export OSXCROSS_ROOT=/path/to/osxcross
scons platform=macos target=editor
```

**Windows from Linux** (MinGW):
```bash
scons platform=windows target=editor use_mingw=yes
```

### 4.10 Production Builds

For distribution-quality builds:

```bash
scons platform=linuxbsd target=template_release production=yes
```

The `production=yes` flag enables:
- Link-time optimization (LTO)
- Smaller binary size
- Stripped debug symbols
- Optimized for speed

---

## 5. Operations

### 5.1 Command-Line Interface

The Godot binary supports extensive CLI operations:

**Project execution:**

| Flag | Description |
|------|-------------|
| `--path <dir>` | Set the project path |
| `--main-pack <file>` | Load a specific PCK/ZIP pack |
| `--upwards` | Scan upward for `project.godot` |
| `-s, --script <script>` | Run a script (must extend MainLoop or SceneTree) |
| `--check-only` | Parse scripts only; do not run |
| `--quit` | Quit after the first iteration |
| `--quit-after <frames>` | Quit after N frames |
| `-e, --editor` | Open the editor |
| `-p, --project-manager` | Open the project manager |

**Export commands:**

| Flag | Description |
|------|-------------|
| `--export-release <preset> <path>` | Release export |
| `--export-debug <preset> <path>` | Debug export |
| `--export-pack <preset> <path>` | Export PCK/ZIP only |
| `--export-patch <preset> <path>` | Export changed files only |
| `--patches <paths>` | Comma-separated patch PCK list |
| `--install-android-build-template` | Install Android build template to project |

**Display and rendering:**

| Flag | Description |
|------|-------------|
| `-f, --fullscreen` | Fullscreen mode |
| `-m, --maximized` | Maximized window |
| `-w, --windowed` | Windowed mode |
| `--resolution <WxH>` | Window resolution |
| `--position <X,Y>` | Window position |
| `--single-window` | Single-window mode (editor) |
| `--rendering-method <method>` | Override rendering method |
| `--rendering-driver <driver>` | Override rendering driver |

**Debug and development:**

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Verbose output |
| `--debug-collisions` | Show collision shapes |
| `--debug-paths` | Show path nodes |
| `--debug-navigation` | Show navigation meshes |
| `--debug-avoidance` | Show avoidance obstacles |
| `--debug-canvas-item-redraw` | Show canvas item redraws |
| `--frame-delay <ms>` | Delay each frame by N ms |
| `--time-scale <scale>` | Time scale factor |
| `--disable-render-loop` | Disable automatic render loop |
| `--fixed-fps <fps>` | Fixed FPS (0 = disabled) |
| `--print-fps` | Print FPS to stdout |

**Network debugging:**

| Flag | Description |
|------|-------------|
| `--remote-debug <uri>` | Remote debugger URI |
| `--lsp-port <port>` | GDScript Language Server port (editor builds) |
| `--dap-port <port>` | Debug Adapter Protocol port |

**Tools:**

| Flag | Description |
|------|-------------|
| `--headless` | Run without display (server/CI use) |
| `--test` | Run unit tests (requires `tests=yes` build) |
| `--doctool <path>` | Generate XML class documentation |
| `--no-docbase` | Skip base class docs in doctool |
| `--gdscript-docs <path>` | Generate docs from GDScript files |
| `--dump-gdextension-interface` | Dump GDExtension interface header |
| `--dump-extension-api` | Dump extension API JSON |
| `--validate-extension-api <file>` | Validate extension API against file |
| `--benchmark` | Enable benchmarking |
| `--benchmark-file <file>` | Write benchmark results to file |

> [!TIP]
> For continuous integration, combine `--headless` with export commands to automate builds without a display server:
> ```bash
> godot --headless --export-release "Linux" /output/game.x86_64
> ```
> This is the standard approach for CI/CD pipelines (GitHub Actions, GitLab CI, etc.).

### 5.2 Running the Test Suite

Tests require a build with `tests=yes`:

```bash
# Build with tests
scons platform=linuxbsd target=editor tests=yes

# Run all tests
./bin/godot.linuxbsd.editor.x86_64 --test

# Run specific test suite
./bin/godot.linuxbsd.editor.x86_64 --test --test-case="[String]*"

# Run with verbose output
./bin/godot.linuxbsd.editor.x86_64 --test -v
```

Test directories:
- `tests/core/` — Core system tests (math, string, variant, containers)
- `tests/scene/` — Scene node tests
- `tests/servers/` — Server subsystem tests
- `tests/compatibility_test/` — Backward compatibility tests

### 5.3 Headless / Server Mode

For dedicated game servers or CI:

```bash
# Run project headless (no rendering, no audio)
godot --headless --path /path/to/project

# Export in headless mode
godot --headless --export-release "Linux" output/server
```

Headless mode disables:
- Display server (no window created)
- Audio output
- Editor functionality

This is suitable for dedicated game servers, automated testing, and CI pipelines.

### 5.4 Export Pipeline Operations

The export system (34 files, 703K characters in `editor/export/`) handles packaging projects for distribution.

**Export workflow:**

1. Configure export presets in `export_presets.cfg` (or via the editor UI)
2. Ensure export templates are installed (download via editor or `--export-release` auto-downloads)
3. Run export via CLI or editor

**Export template locations:**

| OS | Path |
|----|------|
| Windows | `%APPDATA%\Godot\export_templates\<version>/` |
| macOS | `~/Library/Application Support/Godot/export_templates/<version>/` |
| Linux | `~/.local/share/godot/export_templates/<version>/` |

> [!WARNING]
> Export template download failures are a known pain point (see issue #108952 with 63+ comments). If the built-in downloader fails, download templates manually from the Godot website and place them in the appropriate directory. The version string in the directory name must exactly match the engine version.

### 5.5 Project Upgrade (Godot 3 to 4)

The project upgrade system (6 files, 291K characters in `editor/project_upgrade/`) handles converting Godot 3.x projects:

```bash
# Open upgrade wizard
godot --editor --path /path/to/godot3/project
```

The converter handles:
- GDScript syntax changes (onready to @onready, export to @export, etc.)
- Node type renames
- Signal connection syntax
- API changes

> [!CAUTION]
> The 3-to-4 converter is best-effort. It cannot automatically handle all breaking changes between major versions. Always version-control your project before upgrading and manually review the converter's output. Complex projects will require manual intervention, particularly around rendering (GLES2/3 to Vulkan/Compatibility), physics (Bullet to GodotPhysics/Jolt), and GDScript class changes.

### 5.6 Documentation Generation

Generate class reference documentation:

```bash
# Generate XML docs for all classes
godot --doctool /path/to/output

# Generate without base class docs
godot --doctool /path/to/output --no-docbase

# Generate docs from GDScript files
godot --gdscript-docs /path/to/scripts
```

### 5.7 GDExtension API Generation

For GDExtension development:

```bash
# Dump the GDExtension interface header
godot --dump-gdextension-interface

# Dump the extension API JSON (for bindings generation)
godot --dump-extension-api

# Validate an extension API file
godot --validate-extension-api extension_api.json
```

---

## 6. Performance

### 6.1 Rendering Performance

The rendering pipeline is the largest subsystem (2.64M characters, 59 files). Performance characteristics vary by backend:

| Backend | Best For | Thread Model | GPU Requirement |
|---------|----------|--------------|-----------------|
| **Forward+** | Desktop/console, many lights | Multi-threaded | Vulkan 1.0+ / D3D12 / Metal |
| **Mobile** | Mobile, simpler scenes | Multi-threaded | Vulkan 1.0+ / Metal |
| **Compatibility** | Older hardware, web | Single-threaded rendering | OpenGL ES 3.0 / WebGL 2.0 |

**Forward+ renderer features:**
- Clustered lighting (unlimited dynamic lights)
- Volumetric fog
- Screen-space reflections (SSR)
- Screen-space ambient occlusion (SSAO)
- Screen-space indirect lighting (SSIL)
- Temporal anti-aliasing (TAA)
- GPU-based lightmapper (`modules/lightmapper_rd/`)

**Compatibility renderer limitations:**
- No compute shader support
- Limited post-processing
- No volumetric effects
- Fewer shadow options

### 6.2 Physics Performance

| Engine | Strengths | Weaknesses |
|--------|-----------|------------|
| **Godot Physics 3D** (597K) | Integrated, stable, deterministic | Fewer features, lower performance on complex scenes |
| **Jolt Physics 3D** (118K) | Higher performance, more features, better stacking | External dependency, newer integration |
| **Godot Physics 2D** (410K) | Integrated, well-tested | — |

Switch physics engines via `project.godot`:
```ini
[physics]
3d/physics_engine="JoltPhysics3D"
```

> [!NOTE]
> Jolt Physics may produce slightly different body enter/exit events compared to Godot Physics (see issue #118714). When switching physics engines in an existing project, test all collision detection and area overlap logic.

### 6.3 Text Rendering Performance

| Server | Features | Performance |
|--------|----------|-------------|
| **TextServerAdvanced** (390K) | Full ICU, complex text layout, BiDi, ligatures | Higher memory, slower for simple text |
| **TextServerFallback** (242K) | Basic text rendering, no ICU | Lower memory, faster for Latin/CJK |

For projects that only use Latin-script text and don't need bidirectional text or complex script shaping, `TextServerFallback` reduces binary size and memory usage.

### 6.4 SCons Build Performance

| Technique | Impact | How |
|-----------|--------|-----|
| Parallel jobs | Major | `scons -j$(nproc)` |
| SCons cache | Major | `SCONS_CACHE=/path/to/cache` |
| ccache | Major | Install ccache; set `CCACHE` env var |
| Disable unused modules | Moderate | `module_<name>_enabled=no` |
| Link-time optimization | Slower build, faster binary | `lto=auto` or `production=yes` |

### 6.5 Profiling

The engine includes built-in profiling infrastructure:

- **Performance singleton**: Exposes FPS, process time, physics time, memory usage
- **Engine profiler** (`core/profiling/`): Function-level timing
- **Scene debugger** (`scene/debugger/`): Scene tree inspection at runtime
- **Remote debugger**: Connect editor to running game for live profiling
- **Benchmarking**: `--benchmark` and `--benchmark-file` CLI flags for automated performance measurement

### 6.6 Memory Management

Key memory systems:
- **Object system**: Reference counting via `RefCounted` base class; `Object` itself is manually managed
- **Variant**: Value type with copy-on-write semantics for complex types
- **PackedArrays**: Contiguous memory for typed arrays (PackedVector3Array, PackedFloat64Array, etc.)
- **Resource caching**: ResourceLoader cache modes control whether resources are shared or duplicated

ResourceLoader cache modes:

| Mode | Behavior |
|------|----------|
| `CACHE_MODE_IGNORE` | Don't use cache |
| `CACHE_MODE_REUSE` | Return cached resource if available |
| `CACHE_MODE_REPLACE` | Load new, replace cache entry |
| `CACHE_MODE_IGNORE_DEEP` | Ignore cache for sub-resources too |
| `CACHE_MODE_REPLACE_DEEP` | Replace cache for sub-resources too |

### 6.7 Threaded Resource Loading

The engine supports threaded resource loading for smooth gameplay:

```gdscript
# Request threaded load
ResourceLoader.load_threaded_request("res://heavy_scene.tscn")

# Check status
var status = ResourceLoader.load_threaded_get_status("res://heavy_scene.tscn")
# Returns: THREAD_LOAD_IN_PROGRESS, THREAD_LOAD_LOADED, THREAD_LOAD_FAILED, THREAD_LOAD_INVALID_RESOURCE

# Get loaded resource
var scene = ResourceLoader.load_threaded_get("res://heavy_scene.tscn")
```

---

## 7. Security

### 7.1 Export Encryption

Godot supports PCK file encryption for protecting game assets:

- Script encryption key can be set in export presets
- PCK files can be encrypted with AES-256
- Script export modes: text (unprotected), compiled (bytecode), encrypted

### 7.2 Cryptographic Primitives

The `core/crypto/` subsystem (10 files, 55K characters) provides:

- AES encryption/decryption
- RSA key generation and operations
- X509 certificate handling
- HMAC computation
- Hashing (MD5, SHA-1, SHA-256)

These are exposed to GDScript via the `Crypto` and `CryptoKey` classes.

### 7.3 Network Security

- **TLS/SSL**: Built-in support via mbedTLS
- **DTLS**: For encrypted UDP (multiplayer)
- **Certificate pinning**: X509 certificate validation
- **WebSocket**: Supports WSS (TLS-encrypted WebSocket)

### 7.4 Sandboxing and Permissions

| Platform | Sandboxing |
|----------|------------|
| Android | Standard Android permission model, declared in AndroidManifest.xml |
| iOS | Standard iOS sandboxing and entitlements |
| macOS | Optional App Sandbox entitlements |
| Web | Browser sandbox (no filesystem access, CORS restrictions) |
| Windows/Linux | No sandboxing by default |

### 7.5 Editor Security Considerations

> [!CAUTION]
> The Godot editor executes GDScript `@tool` scripts at edit time. Opening a project from an untrusted source can execute arbitrary code on the developer's machine. This includes:
> - `@tool` scripts that run in the editor
> - Editor plugins
> - Custom resource importers
> - `EditorScript` instances
>
> Always review third-party projects and plugins before opening them. Consider running untrusted projects in a sandboxed environment (VM, container) for initial review.

### 7.6 GDExtension Security

GDExtensions are native shared libraries (`.dll`, `.so`, `.dylib`) loaded at runtime. They have full system access and are not sandboxed. Only load GDExtensions from trusted sources.

### 7.7 Android Signing

Release Android builds require proper signing:

```bash
export GODOT_ANDROID_SIGN_KEYSTORE=/path/to/keystore.jks
export GODOT_ANDROID_KEYSTORE_ALIAS=my-key-alias
export GODOT_ANDROID_SIGN_PASSWORD=mypassword
```

> [!WARNING]
> Never commit signing credentials to version control. Use environment variables or CI/CD secrets management. The Android signing password in `GODOT_ANDROID_SIGN_PASSWORD` is particularly sensitive — a leaked keystore and password allows anyone to publish updates to your app.

---

## 8. Developer Internals

### 8.1 Variant Type System

The Variant system (37 files, 982K characters in `core/variant/`) is the universal type used throughout the engine. Every value passed through the scripting API, signals, or the inspector is a Variant.

Variant types:
- Nil, Bool, Int, Float, String
- Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i
- Rect2, Rect2i, AABB, Plane, Quaternion
- Transform2D, Transform3D, Projection, Basis
- Color, StringName, NodePath, RID
- Object (pointer to any Object-derived instance)
- Callable, Signal
- Dictionary, Array
- PackedByteArray, PackedInt32Array, PackedInt64Array, PackedFloat32Array, PackedFloat64Array
- PackedStringArray, PackedVector2Array, PackedVector3Array, PackedVector4Array, PackedColorArray

### 8.2 GDExtension System

GDExtension (`core/extension/`, 26 files, 696K characters) allows writing engine extensions in C, C++, Rust, or any language with C FFI:

- `gdextension_interface.h` — C interface header
- `extension_api.json` — Machine-readable API description
- `GDExtensionManager` — Loads/unloads extensions at runtime
- Extensions register at specific initialization levels (CORE, SERVERS, SCENE, EDITOR)

Key GDExtension interface validation:
- API compatibility checking via `--validate-extension-api`
- Interface versioning for backward compatibility
- Opaque pointer types for ABI stability

### 8.3 ClassDB and Method Binding

`ClassDB` (`core/object/class_db.cpp`) maintains the global class registry:

```cpp
// Register a class
GDREGISTER_CLASS(MyNode);

// Bind a method
ClassDB::bind_method(D_METHOD("set_speed", "speed"), &MyNode::set_speed);
ClassDB::bind_method(D_METHOD("get_speed"), &MyNode::get_speed);

// Add a property (backed by getter/setter)
ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "speed"), "set_speed", "get_speed");

// Add a signal
ADD_SIGNAL(MethodInfo("health_changed", PropertyInfo(Variant::INT, "new_health")));
```

### 8.4 Scene System

The scene tree (`scene/main/`, 34 files, 945K characters) is the core game loop manager:

- **SceneTree** — main loop implementation, manages the tree of nodes
- **Node** — base class for all scene objects (process, input, lifecycle)
- **CanvasItem** — base for 2D rendering nodes
- **Node3D** — base for 3D spatial nodes
- **Window** — OS window abstraction
- **Viewport** — rendering target

Node lifecycle:
1. `_enter_tree()` — node added to tree
2. `_ready()` — node and all children are in tree
3. `_process(delta)` — called every frame
4. `_physics_process(delta)` — called every physics tick
5. `_exit_tree()` — node removed from tree
6. `_notification(what)` — general notification handler

### 8.5 Resource System

Resources are the data backbone:

- **Resource** — base class for all data assets
- **ResourceLoader** — loads resources from disk (with caching)
- **ResourceSaver** — saves resources to disk
- **ResourceUID** — unique resource identification system
- **ResourceImporter** — converts source assets to engine format

ResourceSaver flags:

| Flag | Purpose |
|------|---------|
| `FLAG_NONE` | Default behavior |
| `FLAG_RELATIVE_PATHS` | Use relative paths |
| `FLAG_BUNDLE_RESOURCES` | Bundle sub-resources inline |
| `FLAG_CHANGE_PATH` | Allow path changes |
| `FLAG_OMIT_EDITOR_PROPERTIES` | Strip editor-only properties |
| `FLAG_SAVE_BIG_ENDIAN` | Big-endian format |
| `FLAG_COMPRESS` | Compress data |
| `FLAG_REPLACE_SUBRESOURCE_PATHS` | Replace sub-resource paths |

### 8.6 MessageQueue

`MessageQueue` (`core/object/message_queue.cpp`) provides deferred method calls:

- Thread-safe call deferral
- Used by `call_deferred()`, `set_deferred()`, `emit_signal()` when called from threads
- Flushed once per frame in the main loop
- Prevents race conditions when modifying the scene tree from signal handlers

### 8.7 Editor Plugin System

Editor plugins (`editor/plugins/`, 10 files, 92K characters) extend the editor:

- **EditorPlugin** — base class for editor extensions
- **EditorInspectorPlugin** — custom inspector properties
- **EditorExportPlugin** — custom export processing
- **EditorImportPlugin** — custom resource importers
- **EditorSceneFormatImporter** — custom scene format importers
- **EditorScript** — one-shot editor scripts

Plugins can be project-local (`res://addons/`) or installed globally.

### 8.8 Animation System

The animation subsystem (21 files, 557K characters in `scene/animation/`) includes:

- **AnimationPlayer** — plays Animation resources
- **AnimationTree** — state machine / blend tree
- **AnimationMixer** — base for animation playback
- **Tween** — procedural animations
- **AnimatedSprite2D/3D** — frame-based sprite animation

The editor animation workspace (20 files, 1.03M characters) is the largest editor subsystem.

### 8.9 Import System

The asset import system (38 files, 341K characters in `editor/import/`) processes source assets:

- Textures — compressed GPU textures (BPTC, S3TC, ETC2, ASTC)
- 3D models (glTF, FBX) — scene resources
- Audio (WAV, OGG) — engine audio format
- Fonts (TTF, OTF) — font resources
- Translations (CSV, PO) — translation resources

Import settings are stored per-file in `.godot/imported/` and in `.import` sidecar files.

### 8.10 Scripting Architecture

The engine supports multiple scripting languages through the `ScriptLanguage` abstraction:

| Language | Module | Size | Features |
|----------|--------|------|----------|
| **GDScript** | `modules/gdscript/` | 37 files, 1.50M chars | Native, tightly integrated, LSP server |
| **C#/.NET** | `modules/mono/` | 20 files + GodotSharp (44 files), 1.07M chars | .NET 8+, NuGet packages |
| **GDExtension** | `core/extension/` | 26 files, 696K chars | C ABI, any native language |

GDScript includes:
- Compiler (bytecode generation)
- Analyzer (type checking, static analysis)
- Language Server Protocol (LSP) support (configurable port via `--lsp-port`)
- Debug Adapter Protocol (DAP) support (configurable port via `--dap-port`)
- Documentation generation from script comments

---

## 9. Integration Points

### 9.1 GDScript Language Server Protocol (LSP)

Editor builds expose a GDScript LSP server for external IDE integration:

```bash
# Start with custom LSP port
godot --editor --lsp-port 6008
```

The LSP server provides:
- Autocompletion
- Go-to-definition
- Symbol search
- Hover documentation
- Diagnostics (errors, warnings)

Recommended port range: 1024-49151.

### 9.2 Debug Adapter Protocol (DAP)

The DAP interface enables debugging from external IDEs (VS Code, etc.):

```bash
# Start with custom DAP port
godot --editor --dap-port 6007
```

DAP features:
- Breakpoints (line, conditional)
- Variable inspection
- Call stack navigation
- Step in/over/out
- Expression evaluation

### 9.3 Version Control Integration

The editor includes VCS integration (4 files, 101K characters in `editor/version_control/`):

- `EditorVCSInterface` — abstract VCS interface
- Built-in support for staging, committing, diffing
- Git integration via GDExtension plugin

### 9.4 Asset Library

The editor includes an integrated asset library client (4 files, 124K characters in `editor/asset_library/`):

- Browse and search the Godot Asset Library
- Download and install addons directly from the editor
- Asset categories: templates, projects, plugins, shaders, materials

### 9.5 Remote Debugging

Connect the editor to a running game instance for live debugging:

```bash
# Run game with remote debug
godot --remote-debug tcp://192.168.1.100:6007

# In editor: enable "Deploy with Remote Debug" in export preset
```

Features:
- Live scene tree inspection
- Remote property editing
- Performance monitoring
- GDScript debugger (breakpoints, stepping)

### 9.6 Movie Writer

The MovieWriter system (4 files, 28K characters) enables offline rendering:

```bash
# Record gameplay to video frames
godot --write-movie output.avi --fixed-fps 60 --quit-after 3600
```

This renders the game at exactly the specified FPS regardless of actual performance, producing deterministic output suitable for trailers and cinematics.

---

## 10. Module Reference

### 10.1 GDScript — `modules/gdscript/`

**37 files, 1.50M characters** — The primary scripting language.

| Component | Purpose |
|-----------|---------|
| `gdscript_compiler.cpp` | Bytecode compilation |
| `gdscript_analyzer.cpp` | Static type analysis |
| `gdscript_parser.cpp` | Syntax parsing |
| `gdscript_tokenizer.cpp` | Lexical analysis |
| `gdscript_byte_codegen.cpp` | Bytecode generation |
| `gdscript_vm.cpp` | Virtual machine execution |
| `language_server/` | LSP implementation |

Key features: typed variables, pattern matching, lambdas, coroutines (await), annotations (@export, @onready, @tool), enums, inner classes, signal declarations.

### 10.2 C#/.NET — `modules/mono/`

**20 files + GodotSharp (44 files), 1.07M characters** — C# scripting support.

Requires .NET 8.0+ SDK and runtime. The `GodotSharp` directory contains C# source for the engine bindings (source generators, interop, Godot API wrapper classes).

Build considerations:
- Adds significant build time and binary size
- Disable with `module_mono_enabled=no` if not needed
- Requires separate NuGet restore step for C# projects

### 10.3 Godot Physics 3D — `modules/godot_physics_3d/`

**36 files, 597K characters** — Built-in 3D physics engine.

Components:
- Rigid body dynamics
- Static and kinematic bodies
- Area detection
- Shape casting
- Joints (hinge, slider, cone twist, generic 6DOF)
- Soft body simulation

### 10.4 Godot Physics 2D — `modules/godot_physics_2d/`

**33 files, 410K characters** — Built-in 2D physics engine.

Components:
- Rigid body dynamics
- Static and kinematic bodies
- Area detection
- Shape casting (circle, rectangle, capsule, convex polygon, concave polygon, segment)
- Joints (pin, groove, damped spring)

### 10.5 Jolt Physics — `modules/jolt_physics/`

**9 files, 118K characters** — High-performance alternative 3D physics engine based on Jolt Physics.

Advantages over Godot Physics 3D:
- Better performance on complex scenes
- More robust stacking behavior
- Continuous collision detection
- Multi-threaded physics

Enable in `project.godot`:
```ini
[physics]
3d/physics_engine="JoltPhysics3D"
```

### 10.6 glTF — `modules/gltf/`

**11 files, 419K characters** — glTF 2.0 import and export.

Supports:
- glTF 2.0 binary (.glb) and text (.gltf)
- PBR materials
- Skeletal animation
- Morph targets (blend shapes)
- Multiple scenes
- Extensions (KHR_lights_punctual, KHR_materials_unlit, etc.)

### 10.7 FBX — `modules/fbx/`

**7 files, 114K characters** — FBX import support.

Uses ufbx library for parsing. Supports meshes, skeletons, animations, and materials from FBX files.

### 10.8 OpenXR — `modules/openxr/`

**16 files, 336K characters** — Virtual and augmented reality support via the OpenXR standard.

Requirements:
- OpenXR-compatible runtime (SteamVR, Oculus, WMR, Monado)
- Vulkan rendering backend (required for OpenXR)

Features:
- Head tracking
- Controller tracking
- Hand tracking
- Eye tracking
- Action-based input system

### 10.9 Text Server Advanced — `modules/text_server_adv/`

**10 files, 390K characters** — Full-featured text rendering with ICU.

Capabilities:
- Complex text layout (Arabic, Hebrew, Devanagari, Thai, etc.)
- Bidirectional text (BiDi)
- Line breaking (Unicode UAX #14)
- Font fallbacks
- Ligatures and kerning
- OpenType feature support

### 10.10 Text Server Fallback — `modules/text_server_fb/`

**7 files, 242K characters** — Lightweight text rendering without ICU.

Suitable for projects using only Latin, CJK, or other scripts that don't require complex shaping. Significantly smaller binary and lower memory footprint.

### 10.11 Visual Shader — `modules/visual_shader/`

**5 files, 263K characters** — Node-based visual shader editor.

Provides a graph-based interface for creating shaders without writing GLSL/Godot Shading Language code.

### 10.12 Multiplayer — `modules/multiplayer/`

**19 files, 198K characters** — High-level multiplayer networking.

Components:
- `MultiplayerAPI` — high-level multiplayer interface
- `MultiplayerPeer` — abstract peer interface
- `MultiplayerSpawner` — automated node spawning
- `MultiplayerSynchronizer` — property replication
- RPC (Remote Procedure Call) system

### 10.13 ENet — `modules/enet/`

**9 files, 71K characters** — Reliable UDP networking via ENet library.

Implements `MultiplayerPeer` for game networking. Features: reliable/unreliable channels, connection management, bandwidth limiting.

### 10.14 WebSocket — `modules/websocket/`

**15 files, 114K characters** — WebSocket client and server.

Supports WSS (TLS-encrypted WebSocket) for secure connections.

### 10.15 WebRTC — `modules/webrtc/`

**18 files, 98K characters** — Peer-to-peer networking via WebRTC.

Supports data channels for low-latency peer-to-peer communication. Native implementation uses libdatachannel.

### 10.16 Navigation 2D/3D — `modules/navigation_2d/`, `modules/navigation_3d/`

**2D: 18 files, 114K characters | 3D: 16 files, 119K characters**

Pathfinding and navigation mesh support:
- Navigation mesh baking
- Path queries
- Avoidance (RVO)
- Navigation regions and links
- Navigation obstacles

### 10.17 CSG — `modules/csg/`

**7 files, 119K characters** — Constructive Solid Geometry.

Boolean operations (union, intersection, subtraction) on 3D meshes for prototyping and level design.

### 10.18 GridMap — `modules/gridmap/`

**5 files, 86K characters** — 3D tile-based level editor.

Allows placing MeshLibrary items on a 3D grid for level construction.

### 10.19 Lightmapper RD — `modules/lightmapper_rd/`

**5 files, 113K characters** — GPU-accelerated lightmap baking.

Uses the RenderingDevice (compute shaders) for fast lightmap generation. Requires Vulkan/D3D12/Metal backend.

### 10.20 Noise — `modules/noise/`

**11 files, 90K characters** — Procedural noise generation.

Supports: Simplex, OpenSimplex2, OpenSimplex2S, Perlin, Value, ValueCubic. Used for terrain generation, textures, and procedural content.

### 10.21 Interactive Music — `modules/interactive_music/`

**9 files, 85K characters** — Adaptive music system.

Allows music that reacts to game state via beat-synced transitions, stingers, and layered playback.

### 10.22 UPnP — `modules/upnp/`

**11 files, 50K characters** — Universal Plug and Play.

Automatic port forwarding for multiplayer games behind NAT. Uses miniupnpc library.

### 10.23 Regex — `modules/regex/`

**5 files, 23K characters** — Regular expression support.

Wraps PCRE2 library for pattern matching in GDScript and C#.

### 10.24 Camera — `modules/camera/`

**14 files, 87K characters** — Camera device access.

Platform-specific camera feed support for augmented reality and other camera-dependent features.

### 10.25 WebXR — `modules/webxr/`

**8 files, 60K characters** — WebXR support for web exports.

Enables VR/AR experiences in web browsers via the WebXR Device API.

### 10.26 Image Format Modules

Codec modules for image import/export:

| Module | Format |
|--------|--------|
| `webp` | WebP |
| `jpg` | JPEG |
| `png` | PNG (via libpng) |
| `hdr` | HDR/RGBE |
| `bmp` | BMP |
| `tga` | TGA |
| `dds` | DirectDraw Surface |
| `tinyexr` | OpenEXR |
| `ktx` | Khronos Texture (KTX2) |
| `svg` | SVG (via ThorVG) |
| `astcenc` | ASTC compression |
| `bcdec` | BC texture decompression |
| `cvtt` | Convection Texture Tools |
| `etcpak` | ETC/EAC compression |
| `basis_universal` | Basis Universal supercompression |
| `msdfgen` | Multi-channel SDF generation |
| `betsy` | GPU texture compression |

---

## 11. Platform Reference

### 11.1 Windows — `platform/windows/`

**46 files, 727K characters** — The largest platform implementation.

- Native Win32 window management
- WASAPI audio driver (`drivers/wasapi/`)
- XAudio2 alternative (`drivers/xaudio2/`)
- XInput and DirectInput gamepad support
- Direct3D 12 rendering (`drivers/d3d12/`)
- Vulkan rendering (`drivers/vulkan/`)
- OpenGL ES 3.0 via ANGLE (`drivers/gles3/`)
- Native file dialogs
- Windows-specific crash handler
- UWP not supported (removed in Godot 4)

### 11.2 Linux/BSD — `platform/linuxbsd/`

**28 files, 630K characters**

- X11 and Wayland display backends
- PulseAudio (`drivers/pulseaudio/`) and ALSA (`drivers/alsa/`) audio
- SDL input integration (`drivers/sdl/`)
- Vulkan rendering
- OpenGL ES 3.0 (native)
- udev gamepad detection
- D-Bus integration
- FreeDesktop portal support
- AccessKit accessibility (`drivers/accesskit/`)
- Speech dispatcher integration

Known issue: Godot 4.6 may lock up Linux Mint after 2+ hours of use (issue #117714, 11 comments). If encountered, check GPU driver version and Vulkan configuration.

### 11.3 macOS — `platform/macos/`

**34 files, 163K characters**

- Cocoa window management
- Metal rendering backend (`drivers/metal/`, 523K characters)
- Vulkan via MoltenVK
- CoreAudio driver (`drivers/coreaudio/`)
- Native menus, notifications, file dialogs
- App Store requirements support (sandboxing, entitlements)
- Universal binary support (x86_64 + arm64)

### 11.4 Android — `platform/android/`

**42+ files, 429K characters (C++) + Java source**

- Gradle-based build system
- Vulkan and OpenGL ES 3.0 rendering
- Touch input, sensors, gamepad
- Custom build template support
- Multiple distribution targets: Android, HorizonOS, PicoOS
- Android export requires JDK and Android SDK

Key Gradle structure:
```
platform/android/java/
├── build.gradle              # Root build
├── editor/build.gradle       # Editor APK
├── lib/                      # Godot library AAR
│   ├── build.gradle
│   └── src/main/java/org/godotengine/godot/
└── app/                      # Export template app
```

### 11.5 iOS — `platform/ios/`

**11 files, 30K characters**

- Metal rendering
- Touch input
- Game controller support
- App Store packaging
- Xcode project generation

### 11.6 Web — `platform/web/`

**25 files, 270K characters**

- Emscripten-based compilation
- WebGL 2.0 (Compatibility renderer only)
- Web Audio API
- Gamepad API
- SharedArrayBuffer for threading (requires COOP/COEP headers)
- Progressive Web App (PWA) support
- Service worker for offline caching

Known issue: GLES3 shader compilation may fail on some WebGL 2.0 implementations (issue #118684). Test across browsers.

### 11.7 visionOS — `platform/visionos/`

**9 files, 24K characters**

- Apple Vision Pro support
- Requires Swift frontend (`SWIFT_FRONTEND` environment variable)
- Spatial computing features
- RealityKit integration

---

## 12. Driver Reference

### 12.1 Rendering Drivers

| Driver | Directory | Size | Backend |
|--------|-----------|------|---------|
| **Vulkan** | `drivers/vulkan/` | 9 files, 472K chars | Cross-platform (Windows, Linux, Android, macOS via MoltenVK) |
| **Metal** | `drivers/metal/` | 21 files, 523K chars | macOS, iOS, visionOS |
| **Direct3D 12** | `drivers/d3d12/` | 14 files, 432K chars | Windows |
| **OpenGL ES 3.0** | `drivers/gles3/` | 10+16 files, 1.16M chars total | Compatibility renderer (all platforms) |

The OpenGL ES 3.0 driver is split into:
- Core rendering code: 10 files, 455K characters
- Storage/resource management: 16 files, 702K characters

### 12.2 Audio Drivers

| Driver | Directory | Size | Platform |
|--------|-----------|------|----------|
| **PulseAudio** | `drivers/pulseaudio/` | 4 files, 298K chars | Linux |
| **ALSA** | `drivers/alsa/` | 3 files, 413K chars | Linux (fallback) |
| **WASAPI** | `drivers/wasapi/` | 2 files, 39K chars | Windows |
| **XAudio2** | `drivers/xaudio2/` | 2 files, 11K chars | Windows (alternative) |
| **CoreAudio** | `drivers/coreaudio/` | 1 file, 5K chars | macOS/iOS |

### 12.3 Input Drivers

| Driver | Directory | Size | Platform |
|--------|-----------|------|----------|
| **SDL** | `drivers/sdl/` | 3 files, 23K chars | Linux/BSD (gamepad) |
| **AccessKit** | `drivers/accesskit/` | 2 files, 87K chars | Screen reader integration |

### 12.4 OS Abstraction Drivers

| Driver | Directory | Size | Purpose |
|--------|-----------|------|---------|
| **Unix** | `drivers/unix/` | 16 files, 152K chars | POSIX abstractions (file, time, thread, network) |
| **Windows** | `drivers/windows/` | 12 files, 96K chars | Win32 abstractions |
| **Apple** | `drivers/apple/` | 5 files, 22K chars | macOS/iOS shared utilities |

---

## 13. Troubleshooting

### 13.1 Build Issues

| # | Problem | Cause | Solution |
|---|---------|-------|----------|
| 1 | `ValueError: Invalid custom modules path` | `custom_modules` points to non-existent directory or built-in `modules/` | Verify the path exists and does not point to the engine's own `modules/` directory |
| 2 | `RuntimeError: scu_builders.py must be run from the godot folder` | SCons invoked from wrong working directory | Run `scons` from the repository root containing `SConstruct` |
| 3 | `Exception: Swift frontend path is not set` | visionOS build missing Swift | Set `SWIFT_FRONTEND` environment variable to the Swift frontend binary path |
| 4 | SCons cache fills disk | No cache limit set | Set `SCONS_CACHE_LIMIT=4096` (MB) to cap cache size |
| 5 | Build fails with missing X11/Wayland headers | Development libraries not installed | Install `libx11-dev`, `libxrandr-dev`, `libwayland-dev`, etc. for your distro |
| 6 | Android build fails: SDK not found | `ANDROID_HOME` not set | Set `ANDROID_HOME` or `ANDROID_SDK_ROOT` to your Android SDK path |
| 7 | Linking fails with LTO errors | Incompatible compiler/linker versions | Ensure GCC and binutils versions match, or use `lto=none` |
| 8 | MinGW cross-compile fails on Linux | Missing MinGW-w64 toolchain | Install `mingw-w64` package for your distro |
| 9 | Mono/C# build fails | .NET SDK not found or wrong version | Install .NET 8.0+ SDK; verify `dotnet --version` |
| 10 | Emscripten build fails | emsdk not sourced | Run `source /path/to/emsdk/emsdk_env.sh` before building |

### 13.2 Runtime Issues

| # | Problem | Cause | Solution |
|---|---------|-------|----------|
| 11 | Engine crashes on startup (no window) | Incompatible GPU driver for selected renderer | Try `--rendering-driver opengl3` or update GPU drivers |
| 12 | `INTERNAL ERROR` when adding ReflectionProbe | Rendering edge case (issue #118619) | Check GPU driver version; try updating or switching rendering method |
| 13 | Voxel GI darkens with 32+ lights | Forward+ clustered lighting limit (issue #117297) | Reduce dynamic light count or switch to baked lighting |
| 14 | Sub-surface scattering not working in GDShader | Shader pipeline issue (issue #118119) | Verify shader syntax; this was a known issue now resolved |
| 15 | Audio bus meters wrong size at HiDPI | DPI scaling bug (issue #118650) | Update to latest version; this has been fixed |
| 16 | Linux system lockup after 2+ hours | GPU driver/Vulkan issue (issue #117714) | Update GPU drivers; try Compatibility renderer; check system logs |
| 17 | Editor freezes during scene reload with separate game window | Editor window management issue (issue #111175) | Close separate game window before reloading; issue is tracked |
| 18 | C# Color.FromOkHsl wrong values on Linux | Platform-specific math difference (issue #118685) | Fixed in latest builds; update engine version |

### 13.3 Export Issues

| # | Problem | Cause | Solution |
|---|---------|-------|----------|
| 19 | Unable to download export templates | Network/CDN issues (issue #108952, 63 comments) | Download templates manually from godotengine.org and place in the templates directory |
| 20 | Web export shader compilation fails | WebGL 2.0 incompatibility (issue #118684) | Test on multiple browsers; simplify shaders; use supported GLSL features |
| 21 | Android APK not signed | Signing environment variables not set | Set `GODOT_ANDROID_SIGN_KEYSTORE`, `GODOT_ANDROID_KEYSTORE_ALIAS`, `GODOT_ANDROID_SIGN_PASSWORD` |
| 22 | Export PCK too large | All resources included | Use `export_filter` to select specific resources; set exclude patterns |
| 23 | Export fails with "preset not found" | Preset name doesn't match `export_presets.cfg` | Verify preset name exactly matches (case-sensitive) |

### 13.4 Physics Issues

| # | Problem | Cause | Solution |
|---|---------|-------|----------|
| 24 | Area3D body_entered not firing | Monitoring/monitorable not set, or collision layers misconfigured (issue #74300) | Ensure `monitoring=true` on Area3D, `monitorable=true` on body; verify collision layer/mask overlap |
| 25 | Extra enter/exit events with Jolt Physics | Jolt event handling difference (issue #118714) | Known Jolt behavior; add deduplication logic or switch to Godot Physics |

### 13.5 Editor Issues

| # | Problem | Cause | Solution |
|---|---------|-------|----------|
| 26 | Unrecognized UID on editor start | Stale UID cache (issue #117362) | Delete `.godot/uid_cache.bin` and reopen project |
| 27 | TreeItem.set_custom_draw_callback draw issues | API behavior change (issue #116013) | Review callback signature; ensure proper canvas item drawing calls |
| 28 | Project manager can't find projects | `autoscan_project_path` not set | Configure autoscan path in editor settings |

> [!CAUTION]
> When encountering crashes or rendering artifacts, always check GPU driver versions first. Godot's Vulkan, Metal, and D3D12 backends rely on modern GPU driver features. Outdated drivers are the single most common cause of rendering-related crashes and visual glitches.

> [!TIP]
> For diagnosing startup crashes, run with `--verbose` to get detailed initialization logging. For rendering issues, try switching to the Compatibility renderer (`--rendering-method gl_compatibility`) to determine whether the issue is backend-specific.

---

## 14. Quick Reference

### 14.1 CLI Quick Reference

```bash
# Open editor for a project
godot --editor --path /path/to/project

# Run a project
godot --path /path/to/project

# Export release build (headless)
godot --headless --export-release "Linux" /output/game

# Run tests
godot --test

# Generate docs
godot --doctool /output/docs

# Dump GDExtension API
godot --dump-extension-api

# Start with specific renderer
godot --rendering-method gl_compatibility

# Record movie
godot --write-movie output.avi --fixed-fps 60
```

### 14.2 Build Quick Reference

```bash
# Linux editor
scons platform=linuxbsd target=editor -j$(nproc)

# Windows editor (MSVC)
scons platform=windows target=editor

# macOS editor
scons platform=macos target=editor

# Android template
scons platform=android target=template_release arch=arm64

# Web template
scons platform=web target=template_release

# Production build
scons platform=linuxbsd target=template_release production=yes

# Minimal build
scons platform=linuxbsd target=template_release \
  module_mono_enabled=no module_webrtc_enabled=no \
  module_websocket_enabled=no module_camera_enabled=no
```

### 14.3 Key Paths

| What | Path |
|------|------|
| Project settings | `<project>/project.godot` |
| Export presets | `<project>/export_presets.cfg` |
| Project cache | `<project>/.godot/` |
| Editor settings (Windows) | `%APPDATA%\Godot\editor_settings-4.tres` |
| Editor settings (macOS) | `~/Library/Application Support/Godot/editor_settings-4.tres` |
| Editor settings (Linux) | `~/.config/godot/editor_settings-4.tres` |
| Export templates (Windows) | `%APPDATA%\Godot\export_templates\<version>/` |
| Export templates (macOS) | `~/Library/Application Support/Godot/export_templates/<version>/` |
| Export templates (Linux) | `~/.local/share/godot/export_templates/<version>/` |

### 14.4 Server Singletons

| Singleton | Access | Domain |
|-----------|--------|--------|
| `Engine` | `Engine.get_singleton()` | Engine metadata, time scale |
| `ProjectSettings` | `ProjectSettings` | Project configuration |
| `Input` | `Input` | Input state queries |
| `InputMap` | `InputMap` | Action-to-event mappings |
| `TranslationServer` | `TranslationServer` | Localization |
| `Performance` | `Performance` | Runtime metrics |
| `ResourceLoader` | `ResourceLoader` | Load resources |
| `ResourceSaver` | `ResourceSaver` | Save resources |
| `DisplayServer` | `DisplayServer` | Window management |
| `RenderingServer` | `RenderingServer` | Low-level rendering |
| `AudioServer` | `AudioServer` | Audio buses, effects |
| `PhysicsServer2D` | `PhysicsServer2D` | 2D physics |
| `PhysicsServer3D` | `PhysicsServer3D` | 3D physics |
| `NavigationServer2D` | `NavigationServer2D` | 2D pathfinding |
| `NavigationServer3D` | `NavigationServer3D` | 3D pathfinding |
| `TextServer` | `TextServer` | Text shaping |
| `XRServer` | `XRServer` | VR/AR |
| `CameraServer` | `CameraServer` | Camera feeds |
| `ThemeDB` | `ThemeDB` | Default themes |

### 14.5 Pre-commit Hooks

The repository ships a comprehensive `.pre-commit-config.yaml`:

| Hook | Scope | Purpose |
|------|-------|---------|
| `clang-format` | C/C++/Java/GLSL | Code formatting |
| `ruff` | Python | Linting + formatting |
| `mypy` | Python | Type checking |
| `codespell` | All text | Spelling |
| `eslint` | JavaScript | JS linting |
| `svgo` | SVG | SVG optimization |
| `copyright-headers` | Source files | License header verification |
| `header-guards` | C/C++ headers | Include guard consistency |
| `file-format` | All | Line endings, trailing whitespace |
| `dotnet-format` | C# | C# formatting |
| `make-rst` | XML docs | Documentation XML validation |
| `doc-status` | XML docs | Documentation completeness |
| `validate-builders` | SCons files | Build script validation |
| `validate-xml` | XML | XML well-formedness |
| `validate-codeowners` | CODEOWNERS | Ownership file validation |
| `validate-includes` | C/C++ | Include directive validation |
| `jsdoc` | JavaScript | JSDoc validation |

### 14.6 Codebase Statistics

| Metric | Value |
|--------|-------|
| Total source characters | ~47.8M |
| Total source files | 8,953 |
| Primary language | C++ |
| Largest subsystem | RenderingServer (2.64M chars) |
| Second largest | GUI scene nodes (3.28M chars) |
| Largest editor subsystem | Animation editor (1.03M chars) |
| Largest module | GDScript (1.50M chars) |
| Supported platforms | 7 (Windows, Linux/BSD, macOS, Android, iOS, Web, visionOS) |
| Rendering backends | 4 (Vulkan, Metal, D3D12, GLES3) |
| Physics engines | 3 (Godot 2D, Godot 3D, Jolt 3D) |
| Text servers | 2 (Advanced/ICU, Fallback) |

---

_Generated May 2026 from godotengine/godot at caf1670. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._