About godot-cpp
godot-cpp are the official C++ GDExtension bindings, maintainedas part of the Godot project.
godot-cpp is built with theGDExtension system, which allows access to Godot in almost thesame way asmodules: A lot ofengine codecan be used in your godot-cpp project almost exactly as it is.
In particular, godot-cpp has access to all functions thatGDScript andC#have, and additional access to a few more for fast low-level access of data, or deeper integration with Godot.
Differences between godot-cpp and C++ modules
You can use bothgodot-cppandC++ modules to run C or C++ code in a Godot project.
They also both allow you to integrate third-party libraries into Godot. The oneyou should choose depends on your needs.
Advantages of godot-cpp
Unlike modules, godot-cpp (and GDExtensions, in general) don't requirecompiling the engine's source code, making it easier to distribute your work.It gives you access to most of the API available to GDScript and C#, allowingyou to code game logic with full control regarding performance. It's ideal ifyou need high-performance code you'd like to distribute as an add-on in theasset library.
Also:
You can use the same compiled godot-cpp library in the editor and exportedproject. With C++ modules, you have to recompile all the export templates youplan to use if you require its functionality at runtime.
godot-cpp only requires you to compile your library, not the whole engine.That's unlike C++ modules, which are statically compiled into the engine.Every time you change a module, you need to recompile the engine. Even withincremental builds, this process is slower than using godot-cpp.
Advantages of C++ modules
We recommendC++ modules in cases wheregodot-cpp (or another GDExtension system) isn't enough:
C++ modules provide deeper integration into the engine. GDExtension's accessis not as deep as static modules.
You can use C++ modules to provide additional features in a project withoutcarrying native library files around. This extends to exported projects.
Note
If you notice that specific systems are not accessible via godot-cppbut are via custom modules, feel free to open an issue on thegodot-cpp repositoryto discuss implementation options for exposing the missing functionality.
Version compatibility
GDExtensions targeting an earlier version of Godot should work in laterminor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
For this reason, when creating GDExtensions, you may want to target the lowest version ofGodot that has the features you need,not the most recent version of Godot. This cansave you from needing to create multiple builds for different versions of Godot.
There is one exception to this: extensions targeting Godot 4.0 willnot work withGodot 4.1 and later (seeUpdating your GDExtension for 4.1).
GDExtensions are also only compatible with engine builds that use the samelevel of floating-point precision the extension was compiled for. This meansthat if you use an engine build with double-precision floats, the extension mustalso be compiled for double-precision floats and use anextension_api.jsonfile generated by your custom engine build. SeeLarge world coordinatesfor details.
Generally speaking, if you build a custom version of Godot, you should generate anextension_api.json from it for your GDExtensions, because it may have some differencesfrom official Godot builds.