Using any C++ library in Godot with GDExtension and Conan

Godot is a free, open source game engine under the MIT license, and most projects on it are written in GDScript. Sooner or later one needs functionality that already exists as a C or C++ library: GDScript cannot call native code, but Godot loads it through GDExtension and godot-cpp, the official C++ bindings.

A tutorial on the Conan blog walks that route: godot-cpp 10 is now in ConanCenter, and its demo drives 100,000 particles in one scene.

How Godot takes C++ code

A Godot project is made of scenes, trees of nodes; behaviour comes from scripts attached to nodes. C++ enters the engine in one of two ways: engine modules are compiled into Godot itself but need your own engine build for every platform, while GDExtension loads a shared library into an official Godot build at runtime through a stable C interface.

Building is the hard part

godot-cpp wraps that verbose C interface in C++ classes. Since version 10.0 a single godot-cpp release works with any Godot version from 4.3 onwards, chosen with the api_version option, and it is compiled for three targets. The docs suggest a git submodule instead, but then every project compiles its libraries for each platform.

Conan handles the dependencies

With the godot-cpp recipe in ConanCenter, godot-cpp becomes a regular package and those parameters become Conan options: api_version (4.3 to 4.7, 4.7 by default) and target. Each combination is built once and reused by every project. More than 1,900 libraries live in ConanCenter, and Conan builds any of them beside godot-cpp.

A swarm of 100,000 particles

The example registers a new Swarm node simulating 100,000 particles that flee the mouse cursor and bounce off the window edges. In an ECS, entities are plain ids, components are plain data structs, and systems run over every entity holding a given set of components. Components of the same type sit together in memory, so iterating over many entities stays fast.

Every frame, _process() passes the mouse position to flecs, runs the systems with world.progress() and copies the positions into a MultiMesh buffer. A MultiMesh draws many instances of one mesh in a single draw call, far lighter than one node per particle. The class is registered with GDREGISTER_RUNTIME_CLASS, so in the editor it stays a placeholder.

Building it all takes one command, conan build . --build=missing: Conan resolves godot-cpp and flecs, downloads prebuilt binaries and builds the extension. godot-cpp needs C++17, so an older profile needs -s compiler.cppstd=17.