mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
97 lines
4.4 KiB
ReStructuredText
97 lines
4.4 KiB
ReStructuredText
.. _doc_about_godot_cpp:
|
|
|
|
About godot-cpp
|
|
===============
|
|
|
|
`godot-cpp <https://github.com/godotengine/godot-cpp>`__ are the official C++ GDExtension bindings, maintained
|
|
as part of the Godot project.
|
|
|
|
godot-cpp is built with the :ref:`GDExtension system <doc_gdextension>`, which allows access to Godot in almost the
|
|
same way as :ref:`modules <doc_custom_modules_in_cpp>`: A lot of `engine code <https://github.com/godotengine/godot>`__
|
|
can be used in your godot-cpp project almost exactly as it is.
|
|
|
|
In particular, godot-cpp has access to all functions that :ref:`GDScript <doc_gdscript>` and :ref:`C# <doc_c_sharp>`
|
|
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 both `godot-cpp <https://github.com/godotengine/godot-cpp>`__
|
|
and :ref:`C++ modules <doc_custom_modules_in_cpp>` to run C or C++ code in a Godot project.
|
|
|
|
They also both allow you to integrate third-party libraries into Godot. The one
|
|
you should choose depends on your needs.
|
|
|
|
.. warning::
|
|
|
|
godot-cpp is currently *experimental*, which means that we may
|
|
break compatibility in order to fix major bugs or include critical features.
|
|
|
|
|
|
Advantages of 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
|
|
:ref:`asset library <doc_what_is_assetlib>`.
|
|
|
|
Also:
|
|
|
|
- You can use the same compiled godot-cpp library in the editor and exported
|
|
project. With C++ modules, you have to recompile all the export templates you
|
|
plan 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 with
|
|
incremental builds, this process is slower than using godot-cpp.
|
|
|
|
Advantages of C++ modules
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
We recommend :ref:`C++ modules <doc_custom_modules_in_cpp>` 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.
|
|
- You can use C++ modules to provide additional features in a project without
|
|
carrying native library files around. This extends to exported projects.
|
|
|
|
.. 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 <https://github.com/godotengine/godot-cpp>`__
|
|
to discuss implementation options for exposing the missing functionality.
|
|
|
|
.. _doc_what_is_gdextension_version_compatibility:
|
|
|
|
Version compatibility
|
|
---------------------
|
|
|
|
Usually, GDExtensions targeting an earlier version of Godot will 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.
|
|
|
|
However, GDExtension is currently *experimental*, which means that we may
|
|
break compatibility in order to fix major bugs or include critical features.
|
|
For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
|
|
4.1 (see :ref:`updating_your_gdextension_for_godot_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 :ref:`doc_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.
|