diff --git a/tutorials/plugins/gdnative/index.rst b/tutorials/plugins/gdnative/index.rst index 211f1dd70..2c6a2bc58 100644 --- a/tutorials/plugins/gdnative/index.rst +++ b/tutorials/plugins/gdnative/index.rst @@ -5,5 +5,6 @@ GDNative :maxdepth: 1 :name: toc-tutorials-gdnative + what_is_gdnative gdnative-c-example gdnative-cpp-example diff --git a/tutorials/plugins/gdnative/what_is_gdnative.rst b/tutorials/plugins/gdnative/what_is_gdnative.rst new file mode 100644 index 000000000..2aa192345 --- /dev/null +++ b/tutorials/plugins/gdnative/what_is_gdnative.rst @@ -0,0 +1,97 @@ +.. _doc_what_is_gdnative: + +What is GDNative? +================= + +Introduction +------------ + +**GDNative** is a Godot-specific technology that lets the engine interact with + native `shared libraries + `__ at + run-time. You can use it to run native code without compiling it with the + engine. + +.. note:: GDNative is *not* a scripting language and has no relation to + :ref:`GDScript `. + +Differences between GDNative and C++ modules +-------------------------------------------- + +You can use both GDNative 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. + +Advantages of GDNative +^^^^^^^^^^^^^^^^^^^^^^ + +Unlike modules, GDNative 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 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: + +- GDNative 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 GDNative 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 run-time. +- GDNative 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 GDNative. + +Advantages of C++ modules +^^^^^^^^^^^^^^^^^^^^^^^^^ + +We recommend :ref:`C++ modules ` in cases where +GDNative isn't enough: + +- C++ modules provide deeper integration into the engine. GDNative's access is + limited to what the scripting API exposes. +- You can use C++ modules to provide additional features in a project without + carrying native library files around. This extends to exported projects. +- C++ modules are supported on all platforms. In contrast, GDNative isn't + supported on HTML5 and the Universal Windows Platform (UWP) yet. +- C++ modules can be faster than GDNative, especially when the code requires a + lot of communication through the scripting API. + +Supported languages +------------------- + +The Godot developers officially support the following language bindings for +GDNative: + +- C++ :ref:`(tutorial) ` +- C :ref:`(tutorial) ` + +.. note:: + + There are no plans to support additional languages with GDNative 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 `__ +- `Kotlin `__ +- `Nim `__ +- `Python `__ +- `Rust `__ + +.. 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.