diff --git a/tutorials/scripting/gdextension/index.rst b/tutorials/scripting/gdextension/index.rst index 7aec6a9c749..edb165ed548 100644 --- a/tutorials/scripting/gdextension/index.rst +++ b/tutorials/scripting/gdextension/index.rst @@ -1,14 +1,25 @@ :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/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/gdextension_cpp_example.rst similarity index 100% rename from tutorials/scripting/gdextension/gdextension_cpp_example.rst rename to tutorials/scripting/godot_cpp/gdextension_cpp_example.rst diff --git a/tutorials/scripting/gdextension/gdextension_docs_system.rst b/tutorials/scripting/godot_cpp/gdextension_docs_system.rst similarity index 100% rename from tutorials/scripting/gdextension/gdextension_docs_system.rst rename to tutorials/scripting/godot_cpp/gdextension_docs_system.rst 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/gdextension/what_is_gdextension.rst b/tutorials/scripting/godot_cpp/index.rst similarity index 50% rename from tutorials/scripting/gdextension/what_is_gdextension.rst rename to tutorials/scripting/godot_cpp/index.rst index 2abd5319919..39cb1dcb566 100644 --- a/tutorials/scripting/gdextension/what_is_gdextension.rst +++ b/tutorials/scripting/godot_cpp/index.rst @@ -1,22 +1,23 @@ -.. _doc_what_is_gdextension: +:allow_comments: False +.. _doc_godot_cpp: -What is GDExtension? -==================== +C++ (godot-cpp) +=============== -Introduction ------------- +This section describes how to get started with `godot-cpp `__, +the official C++ GDExtension bindings maintained as part of the Godot project. -**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. +.. toctree:: + :maxdepth: 1 + :name: toc-tutorials-godot-cpp -.. note:: GDExtension is *not* a scripting language and has no relation to - :ref:`GDScript `. + gdextension_cpp_example + gdextension_docs_system -Differences between GDExtension and C++ modules +Differences between godot-cpp and C++ modules ----------------------------------------------- -You can use both GDExtension and :ref:`C++ modules ` to +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 @@ -24,36 +25,35 @@ you should choose depends on your needs. .. warning:: - GDExtension is currently *experimental*, which means that we may + godot-cpp 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 `. +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: -- 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 +- 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. -- GDExtension only requires you to compile your library, not the whole engine. +- 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 GDExtension. + incremental builds, this process is slower than using godot-cpp. Advantages of C++ modules ~~~~~~~~~~~~~~~~~~~~~~~~~ We recommend :ref:`C++ modules ` in cases where -GDExtension isn't enough: +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. @@ -67,40 +67,6 @@ GDExtension isn't enough: `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 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..0b49e445da3 --- /dev/null +++ b/tutorials/scripting/other_languages.rst @@ -0,0 +1,33 @@ +Other 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.