瀏覽代碼

Add documentation about .gdextension file

Update tutorials/scripting/gdextension/gdextension_file.rst
Patrick Exner 1 年之前
父節點
當前提交
7695474656

+ 0 - 17
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 <doc_editor_icons>`
-for more information.
-
 Adding properties
 -----------------
 

+ 143 - 0
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 <doc_gdextension_cpp_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 <doc_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 <doc_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 <doc_editor_icons>`
+for more information.

+ 1 - 0
tutorials/scripting/gdextension/index.rst

@@ -9,3 +9,4 @@ GDExtension
 
    what_is_gdextension
    gdextension_cpp_example
+   gdextension_file