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...

Il file .gdextension

Introduzione

Il file .gdextension presente nel tuo progetto contiene le istruzioni per caricare GDExtension. Le istruzioni sono suddivise in sezioni specifiche. Questa pagina dovrebbe fornire una rapida panoramica delle diverse opzioni disponibili. Per un'introduzione su come iniziare a usare C++ (godot-cpp), consulta l'esempio C++ di GDExtension.

Sezione di configurazione

Proprietà	Tipo	Descrizione
entry_symbol	Stringa	Nome della funzione di ingresso per inizializzare GDExtension. Questa funzione deve essere definita nel file register_types.cpp quando si utilizza godot-cpp. È necessario aggiungere questa funzione affinché l'estensione funzioni.
compatibility_minimum	Stringa	Versione minima compatibile. Questo impedisce alle versioni precedenti di Godot di caricare estensioni che dipendono da funzionalità delle versioni più recenti di Godot. Supportato solo in Godot 4.1 o versioni successive
compatibility_maximum	Stringa	Versione massima compatibile. Ciò impedisce alle versioni più recenti di Godot di caricare l'estensione. Supportato solo in Godot 4.3 o versioni successive
reloadable	Booleano	Ricarica l'estensione dopo la sua ricompilazione. Il ricaricamento è supportato per il binding godot-cpp in Godot 4.2 o versioni successive. I binding per altri linguaggi potrebbero non supportarlo. Questo flag si dovrebbe utilizzare principalmente per lo sviluppo o il debug di un'estensione.
android_aar_plugin	Booleano	La GDExtension fa parte di un plugin Android v2. Durante l'esportazione, questo flag indicherà all'editor che le librerie condivise native di GDExtension sono esportate dai file binari AAR del plugin Android.

Sezione di librerie

In questa sezione è possibile impostare i percorsi dei file binari compilati delle librerie GDExtension. Specificando i flag di funzionalità, è possibile filtrare la versione da caricare ed esportare con il gioco a seconda dei flag di funzionalità attivi. Ogni flag di funzionalità deve corrispondere ai flag di funzionalità di Godot o ai flag di esportazione personalizzati per essere caricato in un gioco esportato. Ad esempio, macos.debug significa che sarà caricato se Godot ha attivi entrambi il flag macos e debug. Ogni riga della sezione è valutata dall'alto verso il basso.

Ecco un esempio di come potrebbe apparire:

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

I percorsi possono essere relativi o assoluti (iniziano con res://). Si consigliano i percorsi relativi, in quanto consentono all'estensione di continuare a funzionare anche se installata in una cartella diversa da quella specificata nel percorso.

Le voci sono abbinate in ordine, quindi se due serie di tag di funzionalità potrebbero corrispondere allo stesso sistema, assicurati di inserire prima quelli più specifici:

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

Ecco un elenco di alcune delle opzioni integrate disponibili (per ulteriori dettagli, consultare i tag di funzionalità):

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	Browser web

Compilazione

Flag	Descrizione
debug	Compilazione con funzionalità di debug (le build dell'editor includono sempre funzionalità di debug)
release	Compilazione ottimizzata con funzionalità di debug
editor	Compilazione di editor

Architettura

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

Sezione icone

Come predefinito, Godot utilizza l'icona Nodo nel pannello Scena per i nodi GDExtension. È possibile impostare un'icona personalizzata facendo riferimento al suo nome e al percorso di un file SVG.

Per esempio:

[icons]

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

Il percorso deve puntare a un'immagine SVG di 16×16 pixel, con due opzioni abilitate sull'immagine nel pannello Importazione:

• Editor > Scala con la scala dell'editor.

• Editor > Converti i colori con il tema dell'editor.

Abilitare entrambe le opzioni assicura che l'icona si comporti nel modo più simile possibile alle icone integrate dell'editor. Consultare la guida alla creazione di icone per ulteriori informazioni.

Sezione di dipendenze

In questa sezione, si impostano i percorsi delle dipendenze di GDExtension. Queste impostazioni servono internamente per esportare le dipendenze durante l'esportazione dell'eseguibile del gioco. È possibile specificare quali dipendenze sono caricate in base ai flag di funzionalità dell'eseguibile esportato. Inoltre, è possibile specificare una sottocartella facoltativa in cui spostare le dipendenze. Se non è specificato alcun percorso, Godot sposterà le librerie nella stessa cartella dell'eseguibile del gioco.

Avvertimento

Su macOS, è necessario che le librerie condivise si trovino all'interno di una cartella denominata Frameworks con una struttura di cartelle simile a questa: 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" : ""
}