GDExtension

GDExtension

Run native C++ (or Rust) in Godot as a shared library without recompiling the engine. Use it for performance-critical code, wrapping existing C/C++ libraries, or language bindings.

Related skills: csharp-godot for when C# is enough, gdscript-advanced for GDScript performance idioms first, godot-optimization for profiling before going native, addon-development for distributing the result, export-pipeline for shipping the binaries.

1. When to reach for GDExtension

Reach for GDScript or C# for almost all game logic. Choose GDExtension only when you genuinely need it:

• Native speed in a hot loop that GDScript/C# can't keep up with (profile first — see godot-optimization).
• Wrapping a C/C++ library you must call directly.
• Building a language binding.

Contrast with C++ modules, which are compiled into the engine and therefore require shipping a custom engine binary. GDExtension's key advantage is that it runs against a stock Godot — you distribute just a shared library. It is "more complicated to use than GDScript and C#," so don't reach for it by default.

⚠️ Changed in Godot 4.7: The engine's built-in text servers (text_server_adv, text_server_fb) can no longer be built as GDExtensions — their gdextension_build/ scripts were removed. Writing your own text server as a GDExtension by subclassing TextServerExtension is unaffected. See GH-117056.

2. Project & build setup

mkdir gdextension_example && cd gdextension_example
git init
# IMPORTANT: use the godot-cpp branch matching your target engine version (e.g. 4.3),
# not the literal "4.x".
git submodule add -b 4.3 https://github.com/godotengine/godot-cpp
cd godot-cpp && git submodule update --init && cd ..

Directory layout:

gdextension_example/
├── project/                # demo project to test the extension
│   └── bin/example.gdextension
├── godot-cpp/              # C++ bindings (submodule)