Integrating Any C++ Library into Godot

Published: September 29, 2026 | Reading Time: $\approx 17$ minutes

Godot has surged in popularity recently, largely because it is free, open-source (MIT license), and incredibly lightweight, allowing developers to go from download to development in a matter of minutes.

While the majority of Godot projects rely on GDScript—the engine's native scripting language—complex projects eventually hit a wall. Whether you need a high-performance simulation library, a robust database, a specific networking protocol, or a machine learning runtime, you will eventually need to leverage existing C or C++ libraries.

Since GDScript cannot communicate with native code directly, Godot utilizes GDExtension. By using godot-cpp (the official C++ bindings), developers can expose native C++ code as standard engine classes.

The Challenge: The Build Process

The primary hurdle isn't the code itself, but the build pipeline. You must ensure that godot-cpp matches your specific Godot version, and every external library must be compiled for every target platform you intend to support.

In this guide, we will explore:

1. A brief overview of Godot's architecture.
2. How C++ extensions function.
3. How to streamline the process using Conan and godot-cpp 10 (now hosted on ConanCenter).

Case Study: To demonstrate this, we will use flecs, an Entity Component System (ECS) library, to simulate $10^5$ (100,000) particles within a Godot scene.

![Image: A visualization of 100,000 particles fleeing from a mouse cursor in a Godot scene]

---

🚀 A Quick Introduction to Godot

Godot is a versatile engine capable of handling both 2D and 3D environments. Its architecture is centered around two primary concepts:

• Nodes: The fundamental building blocks. Every node has a specific type (e.g., Sprite2D, Camera3D, Timer, or AudioStreamPlayer), editable properties in the Inspector, and lifecycle callbacks like _ready() and _process().
• Scenes: Collections of nodes that can represent anything from a single character to a complex level. Scenes can be nested (instanced) within other scenes.

GDScript is a Python-like language optimized for the engine. It is ideal for gameplay logic because it allows for rapid iteration without waiting for compilation.

For C++ developers, the real draw is that the engine is written in C++ and supports loading extensions at runtime without requiring a full engine recompile. Once a C++ class is integrated, it behaves like any other built-in node: it appears in the editor, its properties are visible in the Inspector, and it can be manipulated via GDScript.

---

🛠️ Extending Godot with C++

There are two primary pathways for adding C++ functionality to your project:

Understanding GDExtension and godot-cpp

GDExtension loads shared libraries (such as .dll, .so, .dylib, or .wasm) into the engine. Because the underlying C interface is quite verbose, the Godot team provides godot-cpp. This library wraps the C API into a C++ interface that mirrors the engine's internal API.

For example, a custom node created with godot-cpp looks like this:

#include godot_cpp/classes/node2d.hpp

namespace godot {
    class MyNode : public Node2D {
        GDCLASS( MyNode, Node2D )

    protected:
        static void _bind_methods() {}

    public:
        void _process(double p_delta) override {
            // This logic executes every single frame
        }
    };
} // namespace godot

Versioning and Compatibility

Starting with version 10.0, a single godot-cpp release is compatible with any Godot version from 4.3 onwards. You specify the target version using the api_version build option.

Note: An extension built for 4.3 will work in 4.7, but an extension built for 4.7 will not work in 4.3.

---

🏗️ Build Targets and Feature Tags

Before compiling, you must understand the three primary build targets:

1. template_debug: The standard development build.
2. template_release: Optimized for production; removes debug checks.
3. editor: Specifically for editor-integrated tools.

The engine determines which library to load via a .gdextension configuration file.

[configuration]
entry_symbol = "gdexample_library_init"
compatibility_minimum = "4.7"

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

---

📦 Managing Dependencies with Conan

The traditional workflow suggested by Godot documentation involves:

• Adding godot-cpp as a git submodule.
• Building it manually using SCons.
• Manually compiling every third-party library for every platform.

This approach is tedious because every project ends up recompiling godot-cpp and its dependencies repeatedly. Conan solves this by treating godot-cpp as a standard package.

The Conan Advantage

With the godot-cpp recipe in ConanCenter, the build process is simplified into two main options:

• api_version: Targets the Godot API (from 4.3 up to 4.7).
• target: Chooses between template_debug, template_release, or editor.

By using Conan, each combination of version and target is built once and cached, transforming your GDExtension into a standard C++ project. You can now easily integrate any of the 1,900+ libraries available in the Conan ecosystem.