about_godot_cpp.rst 4.1 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
  1. .. _doc_about_godot_cpp:
  2. About godot-cpp
  3. ===============
  4. `godot-cpp <https://github.com/godotengine/godot-cpp>`__ are the official C++ GDExtension bindings, maintained
  5. as part of the Godot project.
  6. godot-cpp is built with the :ref:`GDExtension system <doc_gdextension>`, which allows access to Godot in almost the
  7. same way as :ref:`modules <doc_custom_modules_in_cpp>`: A lot of `engine code <https://github.com/godotengine/godot>`__
  8. can be used in your godot-cpp project almost exactly as it is.
  9. In particular, godot-cpp has access to all functions that :ref:`GDScript <doc_gdscript>` and :ref:`C# <doc_c_sharp>`
  10. have, and additional access to a few more for fast low-level access of data, or deeper integration with Godot.
  11. Differences between godot-cpp and C++ modules
  12. ---------------------------------------------
  13. You can use both `godot-cpp <https://github.com/godotengine/godot-cpp>`__
  14. and :ref:`C++ modules <doc_custom_modules_in_cpp>` to run C or C++ code in a Godot project.
  15. They also both allow you to integrate third-party libraries into Godot. The one
  16. you should choose depends on your needs.
  17. Advantages of godot-cpp
  18. ~~~~~~~~~~~~~~~~~~~~~~~
  19. Unlike modules, godot-cpp (and GDExtensions, in general) don't require
  20. compiling the engine's source code, making it easier to distribute your work.
  21. It gives you access to most of the API available to GDScript and C#, allowing
  22. you to code game logic with full control regarding performance. It's ideal if
  23. you need high-performance code you'd like to distribute as an add-on in the
  24. :ref:`asset library <doc_what_is_assetlib>`.
  25. Also:
  26. - You can use the same compiled godot-cpp library in the editor and exported
  27. project. With C++ modules, you have to recompile all the export templates you
  28. plan to use if you require its functionality at runtime.
  29. - godot-cpp only requires you to compile your library, not the whole engine.
  30. That's unlike C++ modules, which are statically compiled into the engine.
  31. Every time you change a module, you need to recompile the engine. Even with
  32. incremental builds, this process is slower than using godot-cpp.
  33. Advantages of C++ modules
  34. ~~~~~~~~~~~~~~~~~~~~~~~~~
  35. We recommend :ref:`C++ modules <doc_custom_modules_in_cpp>` in cases where
  36. godot-cpp (or another GDExtension system) isn't enough:
  37. - C++ modules provide deeper integration into the engine. GDExtension's access
  38. is not as deep as static modules.
  39. - You can use C++ modules to provide additional features in a project without
  40. carrying native library files around. This extends to exported projects.
  41. .. note::
  42. If you notice that specific systems are not accessible via godot-cpp
  43. but are via custom modules, feel free to open an issue on the
  44. `godot-cpp repository <https://github.com/godotengine/godot-cpp>`__
  45. to discuss implementation options for exposing the missing functionality.
  46. .. _doc_what_is_gdextension_version_compatibility:
  47. Version compatibility
  48. ---------------------
  49. GDExtensions targeting an earlier version of Godot should work in later
  50. minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2
  51. should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
  52. For this reason, when creating GDExtensions, you may want to target the lowest version of
  53. Godot that has the features you need, *not* the most recent version of Godot. This can
  54. save you from needing to create multiple builds for different versions of Godot.
  55. There is one exception to this: extensions targeting Godot 4.0 will **not** work with
  56. Godot 4.1 and later (see :ref:`updating_your_gdextension_for_godot_4_1`).
  57. GDExtensions are also only compatible with engine builds that use the same
  58. level of floating-point precision the extension was compiled for. This means
  59. that if you use an engine build with double-precision floats, the extension must
  60. also be compiled for double-precision floats and use an ``extension_api.json``
  61. file generated by your custom engine build. See :ref:`doc_large_world_coordinates`
  62. for details.
  63. Generally speaking, if you build a custom version of Godot, you should generate an
  64. ``extension_api.json`` from it for your GDExtensions, because it may have some differences
  65. from official Godot builds.