Skip to content
Skills Library
Programming · Building & coding

gdextension

/gdextension

Use when building native extensions for Godot — godot-cpp (C++) or gdext (Rust), binding classes, building, and GDScript/C# interop

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when building native extensions for Godot — godot-cpp (C++) or gdext (Rust), binding classes, building, and GDScript/C# interop

Original author description

Use when building native extensions for Godot — godot-cpp (C++) or gdext (Rust), binding classes, building, and GDScript/C# interop

How it works

  1. 1. When to reach for GDExtension
  2. 2. Project & build setup
  3. 3. Binding a class (C++)
  4. 4. Entry point & the .gdextension file
  5. 5. Compatibility rules
  6. 6. Using it from GDScript and C
  7. Implementation Checklist
Original SKILL.md headings · 228 lines, 1,217 words
SKILL.md preview
---
name: gdextension
description: Use when building native extensions for Godot — godot-cpp (C++) or gdext (Rust), binding classes, building, and GDScript/C# interop
---

# 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](https://github.com/godotengine/godot/pull/117056).

---

## 2. Project & build setup

```bash
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)
└── src/
    ├── register_types.{h,cpp}
    └── gdexample.{h,cpp}
```

Build with `scons platform=<platform>` (omit the platform to target the current one; default build is **debug**). The official `SConstruct` is a downloadable file from the C++ tutorial rather than hand-rolled here — follow godot-cpp's build docs. SCons is the official path; godot-cpp also supports CMake.

> **Godot 4.7+:** Upstream's reference GDExtension interface files (e.g. `gdextension_interface.h`) now live in the godot-headers repository instead of godot-cpp ([GH-115401](https://github.com/godotengine/godot/pull/115401)). godot-cpp consumes them from there, so the submodule workflow above is unchanged — this only matters if you vendor the raw interface headers directly (e.g. for a custom language binding).

---

## 3. Binding a class (C++)

Header (`gdexample.h`):

```cpp
#pragma once
#include <godot_cpp/classes/sprite2d.hpp>

namespace godot {
class GDExample : public Sprite2D {
    GDCLASS(GDExample, Sprite2D)
private:
    double time_passed = 0.0;
    double amplitude = 10.0;
    double speed = 1.0;
protected:
    static void _bind_methods();
public:
    void _process(double delta) override;
    void set_amplitude(double p_amplitude);
    double get_amplitude() const;
    void set_speed(double p_speed);
    double get_speed() const;
};
}
```

Bindings (`gdexample.cpp` — `_bind_methods`):

```cpp
void GDExample::_bind_methods() {
    ClassDB::bind_method(D_METHOD("get_amplitude"), &GDExample::get_amplitude);
    ClassDB::bind_method(D_METHOD("set_amplitude", "p_amplitude"), &GDExample::set_amplitude);
    ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "amplitude"), "set_amplitude", "get_amplitude");

    ClassDB::bind_method(D_METHOD("get_speed"), &GDExample::get_speed);
    ClassDB::bind_method(D_METHOD("set_speed", "p_speed"), &GDExample::set_speed);
    ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "speed", PROPERTY_HINT_RANGE, "0,20,0.01"),
                 "set_speed", "get_speed");

    ADD_SIGNAL(MethodInfo("position_changed",
               PropertyInfo(Variant::OBJECT, "node"),
               PropertyInfo(Variant::VECTOR2, "new_pos")));
}
```

The patterns:

- **`GDCLASS(Class, Parent)`** — first line of every native class body; wires up the type into Godot's `ClassDB`.
- **`ClassDB::bind_method(D_METHOD("name", "arg"), &Class::method)`** — exposes a method (and names its arguments) so GDScript/C#/the editor can call it.
- **`ADD_PROPERTY(PropertyInfo(...), setter, getter)`** — registers an Inspector property; bind the getter and setter *first*, then reference them here by name.
- **`PROPERTY_HINT_RANGE`** with `"0,20,0.01"` turns the Inspector field into a slider (min, max, step).
- **`ADD_SIGNAL(MethodInfo("name", PropertyInfo(...), ...))`** — declares a signal with typed arguments; emit it from code with `emit_signal("position_changed", this, new_pos)`.

> ⚠️ **Changed in Godot 4.7:** The GDExtension interface functions `object_cast_to` and `classdb_get_class_tag` are deprecated in favor of `is_class`-based casts. Binding libraries such as godot-cpp handle this internally — but native code that calls these interface functions directly should migrate its cast paths. See [GH-119254](https://github.com/godotengine/godot/pull/119254).

---

## 4. Entry point & the .gdextension file

Entry point (`register_types.cpp`):

```cpp
void initialize_example_module(ModuleInitializationLevel p_level) {
    if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) return;
    GDREGISTER_CLASS(GDExample);
}
void uninitialize_example_module(ModuleInitializationLevel p_level) {
    if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) return;
}
extern "C" {
GDExtensionBool GDE_EXPORT example_library_init(
    GDExtensionInterfaceGetProcAddress p_get_proc_address,
    const GDExtensionClassLibraryPtr p_library,
    GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);
    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);
    return init_obj.init();
}
}
```

The `.gdextension` file (`project/bin/example.gdextension`):

```ini
[configuration]
entry_symbol = "example_library_init"
compatibility_minimum = "4.3"
reloadable = true

[libraries]
macos.debug = "res://bin/libgdexample.macos.template_debug.dylib"
macos.release = "res://bin/libgdexample.macos.template_release.dylib"
windows.debug.x86_64 = "res://bin/gdexample.windows.template_debug.x86_64.dll"
windows.release.x86_64 = "res://bin/gdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "res://bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so"
```

The exported `extern "C"` symbol name **must equal** `entry_symbol`, or the extension won't load. Register classes with `GDREGISTER_CLASS`, gated on `MODULE_INITIALIZATION_LEVEL_SCENE`. The `[libraries]` keys are `platform.feature.arch` tags; `template_debug` / `template_release` distinguish build configs. Optional sections: `[icons]` (per-node editor icon) and `[dependencies]` (extra libs copied on export).

> **Godot 4.7+:** The raw GDExtension interface adds refcount-aware construction and registration entry points — `classdb_construct_object3` and `classdb_register_extension_class6` ([GH-118214](https://github.com/godotengine/godot/pull/118214)). Binding libraries built against 4.7 headers use them automatically; they only concern code that calls the interface directly.

---

## 5. Compatibility rules

**Forward-but-not-backward.** An extension targeting 4.2 works in 4.3, but one targeting 4.3 will **not** load in 4.2. **Exception:** extensions targeting 4.0 do not work in 4.1+.

- The **godot-cpp branch must match** the engine version you build against.
- `reloadable = true` hot reload works in the **editor only** — exported games never reload.
- `compatibility_minimum` is required: set it to the lowest engine version you actually support. An older engine refuses to load the extension, and a value below `4.1` is rejected.
- Exported games need the matching `template_release` binaries present, or the native node type simply won't exist at runtime.

> ⚠️ **Changed in Godot 4.7:** `Object.is_class()` changed its `class` parameter type from `String` to `StringName` for performance. GDScript is unaffected and C# gained a compatibility method, but GDExtension binaries compiled against the old signature rely on the engine's compatibility mapping — rebuild against bindings matching your target version when updating to 4.7. See the [4.7 migration guide](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

---

## 6. Using it from GDScript and C#

After building and placing the `.gdextension` file, the native class appears as a normal node type: bound properties show up in the Inspector (range hints become sliders) and signals appear in the Node dock.

### GDScript

```gdscript
extends Node

func _ready():
    var node := GDExample.new()
    node.speed = 2.0
    node.position_changed.connect(_on_position_changed)
    add_child(node)

func _on_position_changed(node, new_pos):
    print("%s is now at %s" % [node.get_class(), new_pos])
```

### C# Equivalent

```csharp
using Godot;

public partial class Demo : Node
{
    public override void _Ready()
    {
        // No C# type exists for a GDExtension class: create it by name.
        var node = ClassDB.Instantiate("GDExample").As<Node>();
        node.Set("speed", 2.0);
        node.Connect("position_changed", Callable.From<Node, Vector2>(OnPositionChanged));
        AddChild(node);
    }

    private void OnPositionChanged(Node node, Vector2 newPos)
        => GD.Print($"{node.GetClass()} is now at {newPos}");
}
```

To get a strongly-typed C# wrapper you can ship a C# glue class, but the extension is fully usable via the dynamic `Set` / `Connect` / `Call` API shown above.

> **Other languages & debugging:** [Rust (gdext)](references/rust-gdext.md) · [Debugging native code](references/debugging-native.md)

---

## Implementation Checklist

- [ ] Confirmed native is actually needed (profiled; GDScript/C# insufficient — see **godot-optimization**)
- [ ] godot-cpp submodule on the branch matching the target engine version
- [ ] `_bind_methods` binds every exposed method/property/signal
- [ ] `entry_symbol` in `.gdextension` matches the exported `extern "C"` symbol
- [ ] `compatibility_minimum` set to the lowest engine version you support
- [ ] `[libraries]` has correct paths for every shipped platform/arch (debug + release)
- [ ] Release export includes the `template_release` binaries
Files in this package (3)
  • SKILL.md 11 KB
  • references/debugging-native.md 2 KB
  • references/rust-gdext.md 2 KB

Versions

RepositoryScoreLicence
This page · jame581/godotprompter100MIT
zenobi-us/dotfiles100MIT

Database snapshot: 13.11.2026 · package version 4b40456ca9d8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100godot
    Use this skill when the user says 'godot', 'godot 4', 'gdscript project', 'godot scenes', 'godot export', 'godot c#', 'gdextension'. Guides Godot 4 projects: scenes and nodes, GDScript/C#/GDExtension, renderers, physics (GodotPhysics/Jolt), animation, UI, exports and…
  • 100godot-development
    Single-agent Godot 4 work: write/debug GDScript or C# scripts, edit scenes and node systems, wire signals, physics, navigation, shaders, export builds, godot-rust (gdext) native extensions, and OpenXR/WebXR integration. Use for targeted Godot scripting without the full game-dev…
  • 100godot
    Use when writing, reviewing, or debugging Godot 4.x games in GDScript or C# — scenes, nodes, custom Resources, autoload/EventBus signals, typed GDScript, CharacterBody2D/3D movement, GUT/gdUnit4 — or porting Godot 3 APIs to 4. NOT Unity/Unreal (that is `unity`/`unreal`), NOT…
  • 100csharp-godot
    Use when working with C# in Godot — conventions, GodotSharp API differences from GDScript, project setup, and interop
  • 100godot-gdscript-patterns
    Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or learning GDScript best practices.
  • 100godot-gdscript-patterns
    Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or learning GDScript best practices.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.