From fbea5593f84e97419efd8270b3eccb57233cb03b Mon Sep 17 00:00:00 2001 From: Lukas Tenbrink Date: Wed, 5 Feb 2025 00:06:58 +0100 Subject: [PATCH] Split C++ (godot-cpp) and GDExtension system info into separate categories, children of Scripting. --- .../gdextension/gdextension_c_example.rst | 2 +- .../gdextension/gdextension_file.rst | 2 +- tutorials/scripting/gdextension/index.rst | 24 +++- .../gdextension/what_is_gdextension.rst | 127 +----------------- .../scripting/godot_cpp/about_godot_cpp.rst | 96 +++++++++++++ .../docs_system.rst} | 4 +- .../files/cpp_example/SConstruct | 0 .../getting_started.rst} | 57 ++++---- .../img/gdextension_cpp_animated.webm | Bin .../img/gdextension_cpp_nodes.webp | Bin .../img/gdextension_cpp_sprite.webp | Bin .../img/gdextension_docs_generation.webp | Bin tutorials/scripting/godot_cpp/index.rst | 17 +++ tutorials/scripting/index.rst | 2 + tutorials/scripting/other_languages.rst | 33 +++++ 15 files changed, 204 insertions(+), 160 deletions(-) create mode 100644 tutorials/scripting/godot_cpp/about_godot_cpp.rst rename tutorials/scripting/{gdextension/gdextension_docs_system.rst => godot_cpp/docs_system.rst} (98%) rename tutorials/scripting/{gdextension => godot_cpp}/files/cpp_example/SConstruct (100%) rename tutorials/scripting/{gdextension/gdextension_cpp_example.rst => godot_cpp/getting_started.rst} (93%) rename tutorials/scripting/{gdextension => godot_cpp}/img/gdextension_cpp_animated.webm (100%) rename tutorials/scripting/{gdextension => godot_cpp}/img/gdextension_cpp_nodes.webp (100%) rename tutorials/scripting/{gdextension => godot_cpp}/img/gdextension_cpp_sprite.webp (100%) rename tutorials/scripting/{gdextension => godot_cpp}/img/gdextension_docs_generation.webp (100%) create mode 100644 tutorials/scripting/godot_cpp/index.rst create mode 100644 tutorials/scripting/other_languages.rst diff --git a/tutorials/scripting/gdextension/gdextension_c_example.rst b/tutorials/scripting/gdextension/gdextension_c_example.rst index 1f1ef7f17ab..a0ed27793a6 100644 --- a/tutorials/scripting/gdextension/gdextension_c_example.rst +++ b/tutorials/scripting/gdextension/gdextension_c_example.rst @@ -2162,5 +2162,5 @@ quite straightforward and not very verbose. If you want to create actual extensions, it is preferred to use the C++ bindings instead, as it takes away all of the boilerplate from your code. Check the -:ref:`GDExtension C++ example ` to see how you can +:ref:`GDExtension C++ example ` to see how you can do this. diff --git a/tutorials/scripting/gdextension/gdextension_file.rst b/tutorials/scripting/gdextension/gdextension_file.rst index 61e42a5b8fb..7c5ac03c0c6 100644 --- a/tutorials/scripting/gdextension/gdextension_file.rst +++ b/tutorials/scripting/gdextension/gdextension_file.rst @@ -9,7 +9,7 @@ Introduction The ``.gdextension`` file in your project contains the instructions for how to load the GDExtension. The instructions are separated into specific sections. This page should give you a quick overview of the different options available to you. For an introduction -how to get started with GDExtensions take a look at the :ref:`GDExtension C++ Example `. +how to get started with the C++ (godot-cpp), take a look at the :ref:`GDExtension C++ Example `. Configuration section --------------------- diff --git a/tutorials/scripting/gdextension/index.rst b/tutorials/scripting/gdextension/index.rst index 7aec6a9c749..76be9d8690b 100644 --- a/tutorials/scripting/gdextension/index.rst +++ b/tutorials/scripting/gdextension/index.rst @@ -1,14 +1,26 @@ :allow_comments: False -GDExtension -=========== +.. _doc_gdextension: + +The GDExtension system +====================== + +**GDExtension** is a Godot-specific technology that lets the engine interact with +native `shared libraries `__ +at runtime. You can use it to run native code without compiling it with the engine. + +.. note:: GDExtension is *not* a scripting language and has no relation to + :ref:`GDScript `. + +This section describes how GDExtension works, and is generally aimed at people wanting to make a GDExtension from +scratch, for example to create language bindings. If you want to use existing language bindings, please refer to other +articles instead, such as the articles about :ref:`C++ (godot-cpp) ` or one of the +:ref:`community-made ones `. .. toctree:: :maxdepth: 1 - :name: toc-tutorials-gdnative + :name: toc-tutorials-gdextension what_is_gdextension - gdextension_cpp_example - gdextension_c_example gdextension_file - gdextension_docs_system + gdextension_c_example diff --git a/tutorials/scripting/gdextension/what_is_gdextension.rst b/tutorials/scripting/gdextension/what_is_gdextension.rst index 2abd5319919..bf756eeb1f7 100644 --- a/tutorials/scripting/gdextension/what_is_gdextension.rst +++ b/tutorials/scripting/gdextension/what_is_gdextension.rst @@ -3,129 +3,4 @@ What is GDExtension? ==================== -Introduction ------------- - -**GDExtension** is a Godot-specific technology that lets the engine interact with -native `shared libraries `__ -at runtime. You can use it to run native code without compiling it with the engine. - -.. note:: GDExtension is *not* a scripting language and has no relation to - :ref:`GDScript `. - -Differences between GDExtension and C++ modules ------------------------------------------------ - -You can use both GDExtension and :ref:`C++ modules ` 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:: - - GDExtension is currently *experimental*, which means that we may - break compatibility in order to fix major bugs or include critical features. - -Advantages of GDExtension -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unlike modules, GDExtension doesn'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 `. - -Also: - -- GDExtension is not limited to C and C++. Thanks to :ref:`third-party bindings - `, you can use it with many other - languages. -- You can use the same compiled GDExtension 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. -- GDExtension 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 GDExtension. - -Advantages of C++ modules -~~~~~~~~~~~~~~~~~~~~~~~~~ - -We recommend :ref:`C++ modules ` in cases where -GDExtension 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 GDExtension - 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. - -Supported languages -------------------- - -The Godot developers officially support the following language bindings for -GDExtension: - -- C++ :ref:`(tutorial) ` - -.. note:: - - There are no plans to support additional languages with GDExtension officially. - That said, the community offers several bindings for other languages (see - below). - -.. _doc_what_is_gdnative_third_party_bindings: - -The bindings below are developed and maintained by the community: - -.. Binding developers: Feel free to open a pull request to add your binding if it's well-developed enough to be used in a project. -.. Please keep languages sorted in alphabetical order. - -- `D `__ -- `Go `__ -- `Nim `__ -- `Rust `__ -- `Swift `__ - -.. note:: - - Not all bindings mentioned here may be production-ready. Make sure to - research options thoroughly before starting a project with one of those. - Also, double-check whether the binding is compatible with the Godot version - you're using. - -.. _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. +Placeholder. diff --git a/tutorials/scripting/godot_cpp/about_godot_cpp.rst b/tutorials/scripting/godot_cpp/about_godot_cpp.rst new file mode 100644 index 00000000000..1da1a6c93db --- /dev/null +++ b/tutorials/scripting/godot_cpp/about_godot_cpp.rst @@ -0,0 +1,96 @@ +.. _doc_about_godot_cpp: + +About godot-cpp +=============== + +`godot-cpp `__ are the official C++ GDExtension bindings, maintained +as part of the Godot project. + +godot-cpp is built with the :ref:`GDExtension system `, which allows access to Godot in almost the +same way as :ref:`modules `: A lot of `engine code `__ +can be used in your godot-cpp project almost verbatim. + +In particular, godot-cpp has access to all functions that :ref:`GDScript ` and :ref:`C# ` +have, and additional access to a few more which are provided for fast low-level access of data. + +Differences between godot-cpp and C++ modules +----------------------------------------------- + +You can use both `godot-cpp `__ +and :ref:`C++ modules ` 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 GDExtension systems 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 `. + +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 ` 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 GDExtension + 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. + +.. _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. diff --git a/tutorials/scripting/gdextension/gdextension_docs_system.rst b/tutorials/scripting/godot_cpp/docs_system.rst similarity index 98% rename from tutorials/scripting/gdextension/gdextension_docs_system.rst rename to tutorials/scripting/godot_cpp/docs_system.rst index 046caba3824..15b8e9399e6 100644 --- a/tutorials/scripting/gdextension/gdextension_docs_system.rst +++ b/tutorials/scripting/godot_cpp/docs_system.rst @@ -1,4 +1,4 @@ -.. _doc_gdextension_docs_system: +.. _doc_godot_cpp_docs_system: GDExtension documentation system ================================ @@ -15,7 +15,7 @@ XML files (one per class) to document the exposed constructors, properties, meth .. note:: - We are assuming you are using the project files explained in the :ref:`GDExtension C++ Example ` + We are assuming you are using the project files explained in the :ref:`GDExtension C++ Example ` with the following structure: .. code-block:: none diff --git a/tutorials/scripting/gdextension/files/cpp_example/SConstruct b/tutorials/scripting/godot_cpp/files/cpp_example/SConstruct similarity index 100% rename from tutorials/scripting/gdextension/files/cpp_example/SConstruct rename to tutorials/scripting/godot_cpp/files/cpp_example/SConstruct diff --git a/tutorials/scripting/gdextension/gdextension_cpp_example.rst b/tutorials/scripting/godot_cpp/getting_started.rst similarity index 93% rename from tutorials/scripting/gdextension/gdextension_cpp_example.rst rename to tutorials/scripting/godot_cpp/getting_started.rst index 3be88431f0b..dcb2998317b 100644 --- a/tutorials/scripting/gdextension/gdextension_cpp_example.rst +++ b/tutorials/scripting/godot_cpp/getting_started.rst @@ -1,29 +1,38 @@ -.. _doc_gdextension_cpp_example: +.. _doc_godot_cpp_getting_started: -GDExtension C++ example -======================= +Getting Started +=============== -Introduction ------------- +Workflow Overview +----------------- + +As a GDExtension language binding, godot-cpp is more complicated to use than :ref:`GDScript ` and +:ref:`C# `. If you decide to work with it, here's what to expect your workflow to look like: -The C++ bindings for GDExtension are built on top of the C GDExtension API -and provide a nicer way to "extend" nodes and other built-in classes in Godot using C++. -This new system allows the extension of Godot to nearly the same -level as statically linked C++ modules. +* Create a new godot-cpp project (from the `template `__, or from scratch, as explained below) +* Develop your code with your favorite IDE locally. +* Build and test your code with the earliest compatible Godot version. +* Create builds for all platforms you want to support (e.g. using `GitHub Actions `__). +* Optional: Publish on the `Godot Asset Library `__. -You can download the included example in the test folder of the godot-cpp -repository `on GitHub `__. +Example Project +--------------- + +For you first godot-cpp project, we recommend starting with this guide to understand the technology involved with +godot-cpp. After you're done, you can use the +`godot-cpp template `__, which is usually more up to date and has +better coverage of features. However, the template does not explain itself to a high level of detail, which is why +we recommend going through this guide first. Setting up the project ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ There are a few prerequisites you'll need: -- a Godot 4 executable, -- a C++ compiler, -- SCons as a build tool, -- a copy of the `godot-cpp - repository `__. +- A Godot 4 executable. +- A C++ compiler. +- SCons as a build tool. +- A copy of the `godot-cpp repository `__. See also :ref:`Configuring an IDE ` and :ref:`Compiling ` as the build tools are identical @@ -91,7 +100,7 @@ following commands: This will initialize the repository in your project folder. Building the C++ bindings -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ Now that we've downloaded our prerequisites, it is time to build the C++ bindings. @@ -129,7 +138,7 @@ libraries that can be compiled into your project stored in ``godot-cpp/bin/``. You may need to add ``bits=64`` to the command on Windows or Linux. Creating a simple plugin ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ Now it's time to build an actual plugin. We'll start by creating an empty Godot project in which we'll place a few files. @@ -327,7 +336,7 @@ At last, we need the header file for the ``register_types.cpp`` named Compiling the plugin --------------------- +~~~~~~~~~~~~~~~~~~~~ To compile the project we need to define how SCons using should compile it using a ``SConstruct`` file which references the one in ``godot-cpp``. @@ -371,7 +380,7 @@ following commands to do so: ``target=template_release`` switch. Using the GDExtension module ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before we jump back into Godot, we need to create one more file in ``demo/bin/``. @@ -476,7 +485,7 @@ We're finally ready to run the project: :align: default Adding properties ------------------ +~~~~~~~~~~~~~~~~~ GDScript allows you to add properties to your script using the ``export`` keyword. In GDExtension you have to register the properties with a getter and @@ -610,7 +619,7 @@ The first two arguments are the minimum and maximum value and the third is the s further configure how properties are displayed and set on the Godot side. Signals -------- +~~~~~~~ Last but not least, signals fully work in GDExtension as well. Having your extension react to a signal given out by another object requires you to call ``connect`` @@ -717,7 +726,7 @@ our main node and implemented our signal like this: Every second, we output our position to the console. Next steps ----------- +~~~~~~~~~~ We hope the above example showed you the basics. You can build upon this example to create full-fledged scripts to control nodes in Godot diff --git a/tutorials/scripting/gdextension/img/gdextension_cpp_animated.webm b/tutorials/scripting/godot_cpp/img/gdextension_cpp_animated.webm similarity index 100% rename from tutorials/scripting/gdextension/img/gdextension_cpp_animated.webm rename to tutorials/scripting/godot_cpp/img/gdextension_cpp_animated.webm diff --git a/tutorials/scripting/gdextension/img/gdextension_cpp_nodes.webp b/tutorials/scripting/godot_cpp/img/gdextension_cpp_nodes.webp similarity index 100% rename from tutorials/scripting/gdextension/img/gdextension_cpp_nodes.webp rename to tutorials/scripting/godot_cpp/img/gdextension_cpp_nodes.webp diff --git a/tutorials/scripting/gdextension/img/gdextension_cpp_sprite.webp b/tutorials/scripting/godot_cpp/img/gdextension_cpp_sprite.webp similarity index 100% rename from tutorials/scripting/gdextension/img/gdextension_cpp_sprite.webp rename to tutorials/scripting/godot_cpp/img/gdextension_cpp_sprite.webp diff --git a/tutorials/scripting/gdextension/img/gdextension_docs_generation.webp b/tutorials/scripting/godot_cpp/img/gdextension_docs_generation.webp similarity index 100% rename from tutorials/scripting/gdextension/img/gdextension_docs_generation.webp rename to tutorials/scripting/godot_cpp/img/gdextension_docs_generation.webp diff --git a/tutorials/scripting/godot_cpp/index.rst b/tutorials/scripting/godot_cpp/index.rst new file mode 100644 index 00000000000..ced2c12ca45 --- /dev/null +++ b/tutorials/scripting/godot_cpp/index.rst @@ -0,0 +1,17 @@ +:allow_comments: False + +.. _doc_godot_cpp: + +C++ (godot-cpp) +=============== + +This section describes `godot-cpp `__, +the official C++ GDExtension bindings maintained as part of the Godot project. + +.. toctree:: + :maxdepth: 1 + :name: toc-tutorials-godot-cpp + + about_godot_cpp + getting_started + docs_system diff --git a/tutorials/scripting/index.rst b/tutorials/scripting/index.rst index 3df2ffc8b53..1497aef761a 100644 --- a/tutorials/scripting/index.rst +++ b/tutorials/scripting/index.rst @@ -21,6 +21,8 @@ The sections below each focus on a given programming language. gdscript/index c_sharp/index + godot_cpp/index + other_languages gdextension/index Core features diff --git a/tutorials/scripting/other_languages.rst b/tutorials/scripting/other_languages.rst new file mode 100644 index 00000000000..cfa1a499889 --- /dev/null +++ b/tutorials/scripting/other_languages.rst @@ -0,0 +1,33 @@ +Other languages +--------------- + +The Godot developers officially support the following languages for Godot: + +- :ref:`GDScript (all versions)` +- :ref:`C# (.NET version)` +- :ref:`C++ (via GDExtension) ` + +.. note:: + + There are no plans to support additional languages officially. + That said, the community offers several bindings for other languages (see below). + +.. _doc_what_is_gdnative_third_party_bindings: + +The bindings below are developed and maintained by the community: + +.. Binding developers: Feel free to open a pull request to add your binding if it's well-developed enough to be used in a project. +.. Please keep languages sorted in alphabetical order. + +- `D `__ +- `Go `__ +- `Nim `__ +- `Rust `__ +- `Swift `__ + +.. note:: + + Not all bindings mentioned here may be production-ready. Make sure to + research options thoroughly before starting a project with one of those. + Also, double-check whether the binding is compatible with the Godot version + you're using.