The .gdextension file

Introduzione

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

Sezione di configurazione

Proprietà	Tipo	Descrizione
entry_symbol	Stringa	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	Stringa	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	Stringa	Maximum compatible version. This prevents newer versions of Godot from loading the extension. Only supported in Godot 4.3 or later
reloadable	Booleano	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	Booleano	The GDExtension is part of a 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.

Sezione di librerie

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.

Ecco un esempio di come potrebbe apparire:

[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 feature tags):

Sistema in esecuzione

Flag	Descrizione
windows	Sistema operativo Windows
macos	Sistema operativo Mac
linux	Sistema operativo Linux
bsd	Sistema operativo BSD
linuxbsd	Sistema operativo Linux o BSD
android	Sistema operativo Android
ios	Sistema operativo iOS
web	Web browser

Compilazione

Flag	Descrizione
debug	Compila con simboli di debug
release	Optimized build without debug symbols
editor	Compilazione di editor

Architettura

Flag	Descrizione
double	Compilazione a doppia precisione
single	Compilazione a singola precisione
x86_64	64-bit x86 build
arm64	64-bit ARM build
rv64	Compilazione a 64-bit RISC-V
riscv	Compilazione RISC-V (qualsiasi bit)
wasm32	Compilazione WebAssembly a 32 bit

Sezione icone

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.

Per esempio:

[icons]

GDExample = "res://icons/gd_example.svg"

The path should point to a 16 by 16 pixel SVG image. Read the guide for creating icons for more information.

Sezione di dipendenze

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.

Avvertimento

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