From 22cfe0233cdd0fb7153347dd4cef7995139f3e1b Mon Sep 17 00:00:00 2001 From: Patrick Exner Date: Thu, 16 May 2024 01:50:58 +0200 Subject: [PATCH] Add documentation about .gdextension file Update tutorials/scripting/gdextension/gdextension_file.rst (cherry picked from commit 7695474656e16239288e828c45e6b5cd16c7231e) --- .../gdextension/gdextension_cpp_example.rst | 17 --- .../gdextension/gdextension_file.rst | 143 ++++++++++++++++++ tutorials/scripting/gdextension/index.rst | 1 + 3 files changed, 144 insertions(+), 17 deletions(-) create mode 100644 tutorials/scripting/gdextension/gdextension_file.rst diff --git a/tutorials/scripting/gdextension/gdextension_cpp_example.rst b/tutorials/scripting/gdextension/gdextension_cpp_example.rst index 3c3ba84d2..390306dd0 100644 --- a/tutorials/scripting/gdextension/gdextension_cpp_example.rst +++ b/tutorials/scripting/gdextension/gdextension_cpp_example.rst @@ -436,23 +436,6 @@ We're finally ready to run the project: .. image:: img/gdextension_cpp_animated.gif -Custom editor icon ------------------- -By default, Godot uses the node icon in the scene dock for GDExtension nodes. The custom icon can be -added via the ``gdextension`` file. The node's icon is set by reference to its name and resource path -of an SVG file. - -For example: - -.. code-block:: none - - [icons] - - GDExample = "res://icons/gd_example.svg" - -The path should point to a 16 by 16 pixel SVG image. Read the guide for :ref:`creating icons ` -for more information. - Adding properties ----------------- diff --git a/tutorials/scripting/gdextension/gdextension_file.rst b/tutorials/scripting/gdextension/gdextension_file.rst new file mode 100644 index 000000000..ec76b1862 --- /dev/null +++ b/tutorials/scripting/gdextension/gdextension_file.rst @@ -0,0 +1,143 @@ +.. _doc_gdextension_file_sections: + +The .gdextension file +===================== + +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 `. + +Configuration section +--------------------- + ++-------------------------------+------------+------------------------------------------------------------------------------------------------------+ +| Property | Type | Description | ++===============================+============+======================================================================================================+ +| **entry_symbol** | String | Name of the entry function for initializing the GDExtension. This function should be defined in | +| | | the ``register_types.cpp`` file when using godot-cpp. Adding this is necessary for the extension to | +| | | work. | ++-------------------------------+------------+------------------------------------------------------------------------------------------------------+ +| **compatibility_minimum** | String | Minimum compatible version. This prevents older versions of Godot from loading extensions that | +| | | depend on features from newer versions of Godot. **Only supported in Godot 4.1 or later** | ++-------------------------------+------------+------------------------------------------------------------------------------------------------------+ +| **compatibility_maximum** | String | Maximum compatible version. This prevents newer versions of Godot from loading the extension. | +| | | **Only supported in Godot 4.3 or later** | ++-------------------------------+------------+------------------------------------------------------------------------------------------------------+ +| **reloadable** | Boolean | Reloads the extension upon recompilation. Reloading is supported for the godot-cpp binding in | +| | | Godot 4.2 or later. Other language bindings may or may not support it as well. This flag should be | +| | | mainly used for developing or debugging an extension. | ++-------------------------------+------------+------------------------------------------------------------------------------------------------------+ +| **android_aar_plugin** | Boolean | The GDExtension is part of a :ref:`v2 Android plugin `. During export this flag | +| | | will indicate to the editor that the GDExtension native shared libraries are exported by the Android | +| | | plugin AAR binaries. | ++-------------------------------+------------+------------------------------------------------------------------------------------------------------+ + +Libraries section +----------------- + +In this section you can set the paths to the compiled binaries of your GDExtension libraries. +By specifying feature flags you can filter which version should be loaded and exported with your +game depending on which feature flags are active. Every feature flag must match to Godot's +feature flags or your custom export flags to be loaded in an exported game. For instance ``macos.debug`` +means that it will be loaded if Godot has both the ``macos`` and ``debug`` flag active. Each +line of the section is evaluated from top to bottom. + +Here is an example of what that can look like: + +.. code-block:: none + + [libraries] + + macos.debug = "res://bin/libgdexample.macos.template_debug.framework" + macos.release = "res://bin/libgdexample.macos.template_release.framework" + windows.debug.x86_32 = "res://bin/libgdexample.windows.template_debug.x86_32.dll" + windows.release.x86_32 = "res://bin/libgdexample.windows.template_release.x86_32.dll" + windows.debug.x86_64 = "res://bin/libgdexample.windows.template_debug.x86_64.dll" + windows.release.x86_64 = "res://bin/libgdexample.windows.template_release.x86_64.dll" + linux.debug.x86_64 = "res://bin/libgdexample.linux.template_debug.x86_64.so" + linux.release.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so" + linux.debug.arm64 = "res://bin/libgdexample.linux.template_debug.arm64.so" + linux.release.arm64 = "res://bin/libgdexample.linux.template_release.arm64.so" + linux.debug.rv64 = "res://bin/libgdexample.linux.template_debug.rv64.so" + linux.release.rv64 = "res://bin/libgdexample.linux.template_release.rv64.so" + + +Here are lists of some of the available built-in options (for more look at the :ref:`feature tags `): + +Running system +^^^^^^^^^^^^^^ + ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| Flag | Description | ++===============================+======================================================================================================+ +| **windows** | Windows operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **macos** | Mac operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **linux** | Linux operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **bsd** | BSD operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **linuxbsd** | Linux or BSD operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **android** | Android operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **ios** | iOS operating system | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **web** | Web browser | ++-------------------------------+------------------------------------------------------------------------------------------------------+ + +Build +^^^^^ + ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| Flag | Description | ++===============================+======================================================================================================+ +| **debug** | Build with debug symbols | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **release** | Optimized build without debug symbols | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **editor** | Editor build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ + +Architecture +^^^^^^^^^^^^ + ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| Flag | Description | ++===============================+======================================================================================================+ +| **double** | double-precision build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **single** | single-precision build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **x86_64** | 64-bit x86 build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **arm64** | 64-bit ARM build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **rv64** | 64-bit RISC-V build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **riscv** | RISC-V build (any bitness) | ++-------------------------------+------------------------------------------------------------------------------------------------------+ +| **wasm32** | 32-bit WebAssembly build | ++-------------------------------+------------------------------------------------------------------------------------------------------+ + +Icons section +------------- + +By default, Godot uses the Node icon in the scene dock for GDExtension nodes. A custom icon can be +set set by reference to its name and resource path of an SVG file. + +For example: + +.. code-block:: none + + [icons] + + GDExample = "res://icons/gd_example.svg" + +The path should point to a 16 by 16 pixel SVG image. Read the guide for :ref:`creating icons ` +for more information. diff --git a/tutorials/scripting/gdextension/index.rst b/tutorials/scripting/gdextension/index.rst index 963dcc31e..6de98ba8b 100644 --- a/tutorials/scripting/gdextension/index.rst +++ b/tutorials/scripting/gdextension/index.rst @@ -7,3 +7,4 @@ GDExtension what_is_gdextension gdextension_cpp_example + gdextension_file