Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Die .gdextension-Datei

Einführung

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 GDExtension C++ Example.

Abschnitt „Konfiguration“

Propertys	Typ	Beschreibung
entry_symbol	String	Name der Einstiegsfunktion zum Initialisieren der GDExtension. Diese Funktion sollte bei Verwendung von godot-cpp in der Datei `register_types.cpp` definiert werden. Das Hinzufügen ist erforderlich, damit die Erweiterung funktioniert.
compatibility_minimum	String	Minimale kompatible Version. Dies verhindert, dass ältere Versionen von Godot Erweiterungen laden, die von Funktionen neuerer Versionen von Godot abhängen. Wird nur in Godot 4.1 oder höher unterstützt
compatibility_maximum	String	Maximal kompatible Version. Dies verhindert, dass neuere Versionen von Godot die Erweiterung laden. Wird nur in Godot 4.3 oder höher unterstützt
reloadable	Boolean	Lädt die Erweiterung beim Neukompilieren neu. Das Neuladen wird für die Godot-CPP-Bindung in Godot 4.2 oder höher unterstützt. Andere Sprachbindungen unterstützen dies möglicherweise auch, müssen es aber nicht. Dieses Flag sollte hauptsächlich zum Entwickeln oder Debuggen einer Erweiterung verwendet werden.
android_aar_plugin	Boolean	Die GDExtension ist Teil eines v2 Android-Plugins. Während des Exports zeigt dieses Flag dem Editor an, dass die nativen gemeinsam genutzten Bibliotheken von GDExtension von den AAR-Binärdateien des Android-Plugins exportiert werden.

Abschnitt „Bibliotheken“

In diesem Abschnitt können Sie die Pfade zu den kompilierten Binärdateien Ihrer GDExtension-Bibliotheken festlegen. Durch die Angabe von Feature-Flags können Sie filtern, welche Version mit Ihrem Spiel geladen und exportiert werden soll, je nachdem, welche Feature-Flags aktiv sind. Jedes Feature-Flag muss mit den Feature-Flags von Godot oder Ihren benutzerdefinierten Export-Flags übereinstimmen, um in ein exportiertes Spiel geladen zu werden. Beispielsweise bedeutet „macos.debug“, dass es geladen wird, wenn in Godot sowohl das Flag „macos“ als auch das Flag „debug“ aktiv ist. Jede Zeile des Abschnitts wird von oben nach unten ausgewertet.

Hier ist ein Beispiel, wie das aussehen kann:

; 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:

[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"

Hier sind Listen einiger der verfügbaren integrierten Optionen (weitere finden Sie in den Feature-Tags):

Laufendes System

Flag	Beschreibung
windows	Windows-Betriebssystem
macos	Mac-Betriebssystem
linux	Linux-Betriebssystem
bsd	BSD-Betriebssystem
linuxbsd	Linux- oder BSD-Betriebssystem
android	Android-Betriebssystem
ios	iOS-Betriebssystem
web	Webbrowser

Builds

Flag	Beschreibung
debug	Build with debugging features (editor builds always have debugging features)
release	Optimized build without debugging features
editor	Editor-Build

Architektur

Flag	Beschreibung
double	Doppelt präziser Aufbau
single	Einfachpräziser Aufbau
x86_64	64-Bit x86-Build
arm64	64-Bit-ARM-Build
rv64	64-Bit-RISC-V-Build
riscv	RISC-V-Build (beliebige Bitanzahl)
wasm32	32-Bit-WebAssembly-Build

Abschnitt „Symbole“

Standardmäßig verwendet Godot das Node-Icon im Szenendock für GDExtension-Nodes. Das eigene Icon kann über die Datei gdextension hinzugefügt werden. Das Icon des Nodes wird durch Bezugnahme auf seinen Namen und den Ressourcenpfad einer SVG-Datei festgelegt.

Zum Beispiel:

[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 creating icons for more information.

Abschnitt „Abhängigkeiten“

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.

Warnung

On macOS, it is necessary to have shared libraries inside a folder called Frameworks with a directory structure like this: Game.app/Contents/Frameworks.

[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" : ""
}