godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-09-03 18:14:53 +03:00
Code Issues Packages Projects Releases Wiki Activity

Move GDExtension section to engine_details/engine_api. (#11652)

Browse Source
This commit is contained in:
Lukas Tenbrink
2026-04-15 12:40:47 +02:00
committed by GitHub
parent e006964cf6
commit 9b87e0148a
16 changed files with 8 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2159
engine_details/engine_api/gdextension/gdextension_c_example.rst Normal file
View File

File diff suppressed because it is too large Load Diff

206
engine_details/engine_api/gdextension/gdextension_file.rst Normal file
View File

@@ -0,0 +1,206 @@
.. _doc_gdextension_file:
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 C++ (godot-cpp), take a look at the :ref:`GDExtension C++ Example <doc_godot_cpp_getting_started>`.
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
; A comment line starts with a semicolon. This line is ignored by the engine.
[libraries]
macos.debug = "./bin/libgdexample.macos.template_debug.dylib" ; Inline comments are also allowed.
macos.release = "./bin/libgdexample.macos.template_release.dylib"
windows.debug.x86_32 = "./bin/libgdexample.windows.template_debug.x86_32.dll"
windows.release.x86_32 = "./bin/libgdexample.windows.template_release.x86_32.dll"
windows.debug.x86_64 = "./bin/libgdexample.windows.template_debug.x86_64.dll"
windows.release.x86_64 = "./bin/libgdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "./bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.debug.arm64 = "./bin/libgdexample.linux.template_debug.arm64.so"
linux.release.arm64 = "./bin/libgdexample.linux.template_release.arm64.so"
linux.debug.rv64 = "./bin/libgdexample.linux.template_debug.rv64.so"
linux.release.rv64 = "./bin/libgdexample.linux.template_release.rv64.so"
Paths can be relative or absolute (starting with ``res://``). Relative paths are recommended,
as they allow the extension to keep working if it's installed to a different folder than what's
specified in the path.
Entries are matched in order, so if two sets of feature tags could match
the same system, be sure to put the more specific ones first:
.. code-block:: none
[libraries]
linux.release.editor.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.release.x86_64 = "./bin/libgdexample.linux.noeditor.template_release.x86_64.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 debugging features (editor builds always have debugging features) |
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **release** | Optimized build without debugging features |
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **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 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×16 pixel SVG image, with two options enabled on the
image in the Import dock:
- **Editor > Scale with Editor Scale**.
- **Editor > Convert Colors with Editor Theme**.
Enabling both options ensures the icon behaves as closely as possible to
the stock editor icons. Read the guide for :ref:`creating icons <doc_editor_icons>`
for more information.
Dependencies section
--------------------
In this section, you set the paths of the GDExtension dependencies. This is used internally to export the dependencies
when exporting your game executable. You are able to set which dependency is loaded depending on the feature flags
of the exported executable. In addition, you are able to set an optional subdirectory to move your dependencies into.
If no path is supplied, Godot will move the libraries into the same directory as your game executable.
.. warning::
On macOS, it is necessary to have shared libraries inside a folder called ``Frameworks``
with a directory structure like this: ``Game.app/Contents/Frameworks``.
.. code-block:: none
[dependencies]
macos.debug = {
"res://bin/libdependency.macos.template_debug.framework" : "Contents/Frameworks"
}
macos.release = {
"res://bin/libdependency.macos.template_release.framework" : "Contents/Frameworks"
}
windows.debug = {
"res://bin/libdependency.windows.template_debug.x86_64.dll" : "",
"res://bin/libdependency.windows.template_debug.x86_32.dll" : ""
}
windows.release = {
"res://bin/libdependency.windows.template_release.x86_64.dll" : "",
"res://bin/libdependency.windows.template_release.x86_32.dll" : ""
}
linux.debug = {
"res://bin/libdependency.linux.template_debug.x86_64.so" : "",
"res://bin/libdependency.linux.template_debug.arm64.so" : "",
"res://bin/libdependency.linux.template_debug.rv64.so" : ""
}
linux.release = {
"res://bin/libdependency.linux.template_release.x86_64.so" : "",
"res://bin/libdependency.linux.template_release.arm64.so" : "",
"res://bin/libdependency.linux.template_release.rv64.so" : ""
}

344
engine_details/engine_api/gdextension/gdextension_interface_json_file.rst Normal file
View File

@@ -0,0 +1,344 @@
.. _doc_gdextension_interface_json_file:
The C interface JSON file
=========================
The ``gdextension_interface.json`` file is the "source of truth" for the C API that
Godot uses to communicate with GDExtensions.
You can use the Godot executable to dump the file by using the following command:
.. code-block:: shell
godot --headless --dump-gdextension-interface-json
This file is intended to be used by GDExtension language bindings to generate code for
using this API in whatever form makes the most sense for that language.
.. note::
This is not to be confused with the ``extension_api.json``, which is also used by
GDExtension language bindings, and contains information about the classes and
methods that are exposed by Godot. The ``gdextension_interface.json`` is more
low-level, and is used to interact with those higher-level classes and methods.
For languages that can be extended via C, or provide tools for interacting with C code,
it's also possible to use the Godot executable to dump a generated C header file:
.. code-block:: shell
godot --headless --dump-gdextension-interface
.. note::
The header file is compatible with earlier versions of the header file that were included
with Godot 4.5 and earlier, which means it preserves some typos in names in order to
ensure compatibility.
The goal of this page is to explain the JSON format for the GDExtension language bindings that
would like to do their own code generation from the JSON.
Overall structure
-----------------
The JSON file is broken up into 3 sections:
- The header, which includes some miscellaneous information at the top-level of the JSON file.
- The ``types`` key, which defines all the types used in the GDExtension interface.
- The ``interface`` key, which defines all the function pointers that can be loaded via the
``GDExtensionInterfaceGetProcAddress`` function pointer, which is passed to all GDExtensions
when they are loaded.
There is a complete `JSON schema <https://github.com/godotengine/godot/blob/master/core/extension/gdextension_interface.schema.json>`__
included in Godot's source code.
Even though we may add new types and interface functions with each minor release of Godot, we
strive to **never** change them in a backwards incompatible way, or remove them. Every
interface function is labeled with the version of Godot it was introduced in (the ``since``
key), so you can always use the latest version of the file, and simply refrain from using
anything in versions of Godot that are newer than the version you are targeting.
Header
------
The "header" is made up of 3 miscellaneous keys at the top-level of the file:
- ``_copyright``: The standard copyright and license text that Godot includes in all source
code files.
- ``$schema``: Points to the JSON schema relative to this file. It can be useful to place
the schema in the same directory, if you're viewing it with a code editor that understands
JSON schema.
- ``format_version``: An integer for the version of the file format (meaning the schema).
Right now, there is only one format version (``1``). If we ever change the file format in
an incompatible way, we will increment this number. This *doesn't* reflect the version
of the data in the file (so it won't change between Godot versions), only its format.
Hopefully, we'll never have to use it, but it allows code generators to error early if they
encounter an unexpected value here.
Types
-----
The ``types`` section is an array of types that will be used by other types, and the interface
functions that will be in the last section.
The types should be evaluated in order. Later types may refer to earlier types, but earlier
types will not refer to later types.
There is a small set of built-in types which aren't explicitly listed in the JSON:
- ``void``
- ``int8_t``
- ``uint8_t``
- ``int16_t``
- ``uint16_t``
- ``int32_t``
- ``uint32_t``
- ``int64_t``
- ``uint64_t``
- ``size_t`` (``uint32_t`` on 32-bit architectures, and ``uint64_t`` on 64-bit architectures)
- ``char``
- ``char16_t``
- ``char32_t``
- ``wchar_t``
- ``float``
- ``double``
These correspond to their equivalent C types.
Additionally, types can include modifiers such as:
- ``*`` (e.g. ``int8_t*``) to indicate a pointer to the type
- ``const`` (e.g. ``const int8_t*``) to indicate a const type
Each type defined in the JSON file falls into one of 5 "kinds":
- ``enum``
- ``handle``
- ``alias``
- ``struct``
- ``function``
Regardless of the "kind", all types can have the following keys:
- ``kind`` (required): The type's "kind".
- ``name`` (required): The name of the type, which could be used as a valid C identifier.
- ``description``: An array of strings documenting the type, where each string is a line of
documentation (this format for ``description`` is used throughout the JSON file).
- ``deprecated``: An object with its own keys for the Godot version the type was deprecated in
(``since``), a message explaining the deprecation (``message``), and optionally a replacement
to use instead (``replacement``).
Enums
~~~~~
Enums are 32-bit integers with a fixed set of possible values. In C, they could be represented
as an ``enum``.
They have the following keys:
- ``is_bitfield``: If true, this enum is a bitfield, where the enum values can be bitwise OR'd together.
It is false by default.
- ``values``: The array of fixed values for this enum, each with a ``name``, ``value``, and ``description``.
An enum should be represented as an ``int32_t``, unless ``is_bitfield`` is true, in which case a ``uint32_t``
should be used.
Example
+++++++
.. code-block:: json
{
"name": "GDExtensionInitializationLevel",
"kind": "enum",
"values": [
{
"name": "GDEXTENSION_INITIALIZATION_CORE",
"value": 0
},
{
"name": "GDEXTENSION_INITIALIZATION_SERVERS",
"value": 1
},
{
"name": "GDEXTENSION_INITIALIZATION_SCENE",
"value": 2
},
{
"name": "GDEXTENSION_INITIALIZATION_EDITOR",
"value": 3
},
{
"name": "GDEXTENSION_MAX_INITIALIZATION_LEVEL",
"value": 4
}
]
}
Handles
~~~~~~~
Handles are pointers to opaque structs. In C, they could be represented as ``void *`` or ``struct{} *``.
They have the following keys:
- ``is_const``: If true, this handle type is to be treated as a "const pointer", meaning its internal
data will not be changed. It is false by default.
- ``is_uninitialized``: If true, this handle type is to be treated as pointing to uninitialized memory
(which may be initialized using interface functions). It is false by default.
- ``parent``: The optional name of another handle type, if this handle type is the const or uninitialized
version of the parent type. This only makes sense if either ``is_const`` or ``is_uninitialized`` is true.
Handles are the size of pointers on the given architecture (so, 64-bit on x86_64 and 32-bit on x86_32,
for example).
Example
+++++++
.. code-block:: json
{
"name": "GDExtensionStringNamePtr",
"kind": "handle"
}
Aliases
~~~~~~~
Aliases are alternative names for a type. In C, they could be represented as a ``typedef``.
They have only one additional key:
- ``type``: The type the alias is an alternative name for. It may include modifiers as described above.
These should be represented using the same C type as the type they refer to.
Example
+++++++
.. code-block:: json
{
"name": "GDExtensionInt",
"kind": "alias",
"type": "int64_t"
}
Structs
~~~~~~~
Structs represent C ``struct``\ s (aka a block of memory made up of the given members in order), and should
follow all the same layout and alignment rules as C structs.
They have only one additional key:
- ``members``: An array of objects which have a ``name``, ``type`` (which may include modifiers), and
``description``.
Example
+++++++
.. code-block:: json
{
"name": "GDExtensionCallError",
"kind": "struct",
"members": [
{
"name": "error",
"type": "GDExtensionCallErrorType"
},
{
"name": "argument",
"type": "int32_t"
},
{
"name": "expected",
"type": "int32_t"
}
]
}
Functions
~~~~~~~~~
Functions represent C function pointer types, with a list of arguments and a return type, and should
follow the same size and alignment requirements as C function pointers.
They have the following members:
- ``return_value``: An object which has a ``type`` (which may include modifiers) and ``description``.
If the function has no return value, this will be omitted.
- ``arguments`` (required): An array of function arguments which each has a ``type`` (which may include modifiers),
``name``, and ``description``.
Example
+++++++
.. code-block:: json
{
"name": "GDExtensionPtrConstructor",
"kind": "function",
"arguments": [
{
"name": "p_base",
"type": "GDExtensionUninitializedTypePtr"
},
{
"name": "p_args",
"type": "const GDExtensionConstTypePtr*"
}
]
}
Interface
---------
The ``interface`` section of the JSON file is the list of interface functions, which can be loaded
by ``name`` using the ``GDExtensionInterfaceGetProcAddress`` function pointer, which is
passed to all GDExtensions when they are loaded.
Interface functions have some of the same keys as types, including ``name`` (required),
``deprecated``, and ``description``.
And they also have ``return_value`` and ``arguments`` (required) that have the same format
as the equivalent keys on function types (as described in the previous section).
There are only a handful of unique keys:
- ``since`` (required): The Godot version that introduced this interface function.
- ``see``: An array of strings describing external references with more information, for example,
names of classes or functions in the Godot source code, or URLs pointing to documentation.
- ``legacy_type_name``: The legacy name used for the function pointer type in the header generated
by Godot, when the legacy name doesn't match the pattern used for these type names. This field
only exists so that we can generate the header in a way that is backwards compatible with the
header from Godot 4.5 or earlier, and it shouldn't be used unless you also need to maintain
compatibility with the old header.
Example
~~~~~~~
.. code-block:: json
{
"name": "get_godot_version",
"arguments": [
{
"name": "r_godot_version",
"type": "GDExtensionGodotVersion*",
"description": [
"A pointer to the structure to write the version information into."
]
}
],
"description": [
"Gets the Godot version that the GDExtension was loaded into."
],
"since": "4.1",
"deprecated": {
"since": "4.5",
"replace_with": "get_godot_version2"
}
}

BIN
engine_details/engine_api/gdextension/img/gdextension_c_inspector_properties.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
engine_details/engine_api/gdextension/img/gdextension_c_methods_doc.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
engine_details/engine_api/gdextension/img/gdextension_c_moving_sprite.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 662 KiB

BIN
engine_details/engine_api/gdextension/img/gdextension_c_running.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
engine_details/engine_api/gdextension/img/gdextension_c_signal_doc.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
engine_details/engine_api/gdextension/img/gdextension_c_signal_print.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

27
engine_details/engine_api/gdextension/index.rst Normal file
View File

@@ -0,0 +1,27 @@
:allow_comments: False
.. _doc_gdextension:
The GDExtension system
======================
**GDExtension** is a Godot-specific technology that lets the engine interact with
native `shared libraries <https://en.wikipedia.org/wiki/Shared_library>`__
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 <doc_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) <doc_godot_cpp>` or one of the
:ref:`community-made ones <doc_what_is_gdnative_third_party_bindings>`.
.. toctree::
:maxdepth: 1
:name: toc-tutorials-gdextension
what_is_gdextension
gdextension_file
gdextension_interface_json_file
gdextension_c_example

22
engine_details/engine_api/gdextension/what_is_gdextension.rst Normal file
View File

@@ -0,0 +1,22 @@
.. _doc_what_is_gdextension:
What is GDExtension?
====================
**GDExtension** is a Godot-specific technology that lets the engine interact with
native `shared libraries <https://en.wikipedia.org/wiki/Shared_library>`__
at runtime. You can use it to run native code without compiling it with the engine.
There are three primary methods with which this is achieved:
* ``gdextension_interface.h``: A set of C functions that Godot and a GDExtension can use to communicate.
* ``extension_api.json``: A list of C functions that are exposed from Godot APIs (:ref:`Core Features <doc_scripting_core_features>`).
* :ref:`*.gdextension <doc_gdextension_file>`: A file format read by Godot to load a GDExtension.
Most people create GDExtensions with some existing language binding, such as :ref:`godot-cpp (for C++) <doc_godot_cpp>`,
or one of the :ref:`community-made ones <doc_what_is_gdnative_third_party_bindings>`.
Version compatibility
---------------------
See :ref:`godot-cpp Version Compatibility <doc_what_is_gdextension_version_compatibility>`, which applies to all GDExtensions.

1
engine_details/engine_api/index.rst
View File

@@ -21,6 +21,7 @@ that some aspects of the code or directory structures may be different in GDExte
:name: toc-devel-cpp-source-advanced
custom_modules_in_cpp
gdextension/index
binding_to_external_libraries
custom_godot_servers
custom_resource_format_loaders