Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

À propos de godot-cpp

godot-cpp are the official C++ GDExtension bindings, maintained as part of the Godot project.

godot-cpp is built with the GDExtension system, which allows access to Godot in almost the same way as modules: A lot of engine code can be used in your godot-cpp project almost exactly as it is.

In particular, godot-cpp has access to all functions that GDScript and C# have, and additional access to a few more for fast low-level access of data, or deeper integration with Godot.

Différences entre les modules godot-cpp et C++

You can use both godot-cpp and C++ modules to run C or C++ code in a Godot project.

Ils vous permettent également tous deux d'intégrer des bibliothèques tierces dans Godot. Le choix de l'une ou l'autre dépend de vos besoins.

Avantages de godot-cpp

Unlike modules, godot-cpp (and GDExtensions, in general) don't require compiling 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#, allowing you to code game logic with full control regarding performance. It's ideal if you need high-performance code you'd like to distribute as an add-on in the Asset Store.

Aussi :

  • Vous pouvez utiliser la même bibliothèque godot-cpp compilée dans l'éditeur et dans le projet exporté. Avec les modules C++, vous devez recompiler tous les modèles d'export que vous prévoyez d'utiliser si vous avez besoin de leur fonctionnalité durant l'exécution.

  • godot-cpp vous oblige seulement à compiler votre bibliothèque, et non le moteur entier. C'est différent des modules C++, qui sont compilés statiquement dans le moteur. Chaque fois que vous modifiez un module, vous devez recompiler le moteur. Même avec des compilations incrémentales, ce processus est plus lent qu'utiliser godot-cpp.

Avantages des modules C++

We recommend C++ modules in cases where godot-cpp (or another GDExtension system) isn't enough:

  • C++ modules provide deeper integration into the engine. GDExtension's access is not as deep as static modules.

  • Vous pouvez utiliser des modules C++ pour fournir des fonctionnalités supplémentaires dans un projet sans avoir à transporter des fichiers de bibliothèque natifs. Ceci s'étend aux projets exportés.

Note

If you notice that specific systems are not accessible via godot-cpp but are via custom modules, feel free to open an issue on the godot-cpp repository to discuss implementation options for exposing the missing functionality.

Compatibilité des versions

GDExtensions targeting an earlier version of Godot should work in later minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2 should 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 of Godot that has the features you need, not the most recent version of Godot. This can save you from needing to create multiple builds for different versions of Godot.

There is one exception to this: extensions targeting Godot 4.0 will not work with Godot 4.1 and later (see Mise à jour de votre GDExtension pour la 4.1).

GDExtensions are also only compatible with engine builds that use the same level of floating-point precision the extension was compiled for. This means that if you use an engine build with double-precision floats, the extension must also be compiled for double-precision floats and use an extension_api.json file generated by your custom engine build. See Large world coordinates for details.

Generally speaking, if you build a custom version of Godot, you should generate an extension_api.json from it for your GDExtensions, because it may have some differences from official Godot builds. You can learn more about the process of using custom extension_api.json files in the build system section.