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

Compilare con .NET

Requisiti

  • SDK .NET 8.0+

    È possibile utilizzare dotnet --info per verificare quali versioni di .NET SDK sono installate.

Abilitare il modulo .NET

Nota

In passato, il supporto C# per Godot ha utilizzato il runtime Mono <https://www.mono-project.com/>`_ anziché ``.NET Runtime <https://github.com/dotnet/runtime>`_ e internamente molte cose sono ancora chiamate ``mono anziché dotnet o altrimenti riferite come mono.

Per impostazione predefinita, il modulo .NET è disabilitato durante la compilazione. Per abilitarlo, aggiungere l'opzione module_mono_enabled=yes alla riga di comando di SCons, altrimenti seguire le istruzioni per compilare i binari di Godot desiderati.

Generare il collante

Parti dei sorgenti delle librerie gestite sono generate da ClassDB. Questi file sorgente si devono generare prima di compilare le librerie gestite. Si possono generare da qualsiasi editor Godot binario abilitato per .NET, eseguendolo con i parametri --headless --generate-mono-glue seguiti dal percorso di una cartella di output. Questo percorso deve essere modules/mono/glue nella cartella di Godot:

<godot_binary> --headless --generate-mono-glue modules/mono/glue

Questo comando indicherà a Godot di generare i binding C# per l'API di Godot in modules/mono/glue/GodotSharp/GodotSharp/Generated, e i binding C# per gli strumenti dell'editor in modules/mono/glue/GodotSharp/GodotSharpEditor/Generated. Una volta generati questi file, è possibile compilare le librerie gestite da Godot per tutti i target desiderati senza dover ripetere questo processo.

<godot_binary> si riferisce al binario dell'editor compilato con il modulo .NET abilitato. Il suo nome esatto varia in base al sistema e alla configurazione, ma dovrebbe essere nel formato bin/godot.<piattaforma>.editor.<arch>.mono, ad esempio bin/godot.linuxbsd.editor.x86_64.mono o bin/godot.windows.editor.x86_32.mono.exe. Prestare particolare attenzione al suffisso .mono! Se è stato già compilato Godot senza il supporto .NET, si potrebbe aver creato binari con nomi simili, ma senza tale suffisso. Questi binari non si possono utilizzare per generare il collante .NET.

Nota

Le sorgenti di collante si devono rigenerate ogni volta che l'API registrata in ClassDB cambia. Ad esempio, quando un nuovo metodo è registrato nell'API di scripting o quando uno dei parametri di tale metodo cambia. Godot visualizzerà un errore all'avvio se non c'è corrispondenza nell'API tra ClassDB e le sorgenti di collante.

Compilare le librerie gestite

Una volta generato il collante .NET, è possibile creare le librerie gestite, con lo script build_assemblies.py:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin

Se tutto è andato bene, la cartella GodotSharp, contenente le librerie gestite, si dovrebbe trovare nella cartella bin.

Nota

Per impostazione predefinita, tutte le build di sviluppo condividono un numero di versione, il che può causare problemi con la cache dei pacchetti NuGet. Per risolvere questo problema, utilizzare GODOT_VERSION_STATUS per assegnare a ogni build una versione univoca, oppure eliminare GodotNuGetFallbackFolder dopo ogni build per svuotare la cache dei pacchetti.

A differenza delle build "classiche" di Godot, quando si compila con il modulo .NET abilitato (e a seconda della piattaforma di destinazione), è possibile che venga creata una cartella di dati sia per l'editor sia per i progetti esportati. Questa cartella è importante per il corretto funzionamento e si deve distribuire insieme a Godot. Maggiori dettagli su questa cartella sono disponibili in Cartella di dati directory.

Build Platform

Specificare l'argomento --godot-platform=<piattaforma> per specificare la piattaforma per cui vengono compilate le librerie. Omettere questo argomento per compilare per il sistema attuale.

Al momento questo controlla solo l'inclusione del supporto per Visual Studio come editor esterno, per il resto le librerie sono identiche.

Pacchetti NuGet

Gli assembly dell'API, i generatori di codice sorgente e l'SDK personalizzato del progetto MSBuild sono distribuiti come pacchetti NuGet. Tutto ciò è trasparente per l'utente, ma può complicare le cose durante lo sviluppo.

Per poter utilizzare Godot con una versione di sviluppo di tali pacchetti, è necessario creare una sorgente NuGet locale in cui MSBuild possa trovarli.

Per prima cosa, scegliere una posizione per la sorgente NuGet locale. Se non si hanno preferenze specifiche, creare una cartella vuota in una di queste posizioni raccomandate:

  • Su Windows, C:\Users\<nomeutente>\MyLocalNugetSource

  • Su Linux, *BSD, ecc., ~/MyLocalNugetSource

Questo percorso verrà riferito in seguito come <my_local_source>.

Dopo aver scelto una cartella, eseguire questo comando .NET CLI per configurare NuGet in modo che utilizzi la propria sorgente locale:

dotnet nuget add source <my_local_source> --name MyLocalNugetSource

Quando si esegue lo script build_assemblies.py, passare <my_local_source> all'opzione --push-nupkgs-local:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source>

Questa opzione garantisce che i pacchetti siano aggiunti alla sorgente NuGet locale specificata e che le versioni in conflitto del pacchetto vengano rimosse dalla cache NuGet. Si consiglia di utilizzare sempre questa opzione quando si creano soluzioni C# durante lo sviluppo per evitare sbagli.

Compilare senza dipendere da funzionalità deprecate (NO_DEPRECATED)

Quando si compila Godot senza classi e funzioni deprecate, ovvero con l'argomento deprecated=no per scons, anche le librerie gestite si devono compilare senza dipendenze da codice deprecato. Ciò si ottiene passando l'argomento --no-deprecated:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --no-deprecated

Supporto per la doppia precisione (REAL_T_IS_DOUBLE)

Quando si crea Godot con il supporto per la doppia precisione, ovvero con l'argomento precision=double per scons, le librerie gestite si devono aggiustare per corrispondere passando l'argomento --precision=double:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --precision=double

Esempi

Esempio (Windows)

# Build editor binary
scons platform=windows target=editor module_mono_enabled=yes
# Build export templates
scons platform=windows target=template_debug module_mono_enabled=yes
scons platform=windows target=template_release module_mono_enabled=yes

# Generate glue sources
bin/godot.windows.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Build .NET assemblies
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=windows

Esempio (Linux, *BSD)

# Build editor binary
scons platform=linuxbsd target=editor module_mono_enabled=yes
# Build export templates
scons platform=linuxbsd target=template_debug module_mono_enabled=yes
scons platform=linuxbsd target=template_release module_mono_enabled=yes

# Generate glue sources
bin/godot.linuxbsd.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Generate binaries
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=linuxbsd

Cartella di dati

La cartella di dati è una dipendenza per i binari di Godot creati con il modulo .NET abilitato. Contiene file importanti per il corretto funzionamento di Godot. Deve essere distribuita insieme all'eseguibile di Godot.

Editor

Il nome della cartella di dati per l'editor Godot sarà sempre GodotSharp. Questa cartella contiene una sottocartella Api con gli assembly dell'API di Godot e una sottocartella Tools con gli strumenti necessari all'editor, come gli assembly GodotTools e le relative dipendenze.

Su macOS, se l'editor Godot è distribuito come pacchetto, la cartella GodotSharp potrebbe essere situata nella cartella <bundle_name>.app/Contents/Resources/ all'interno del pacchetto.

Modelli di esportazione

La cartella di dati per i progetti esportati è generata dall'editor durante l'esportazione. Si chiama data_<APPNAME>_<ARCH>, dove <APPNAME> è il nome dell'applicazione specificato nell'impostazione del progetto application/config/name e <ARCH> è l'architettura attuale dell'esportazione.

Nel caso di esportazioni con più architetture saranno generate più cartelle di dati di questo tipo.

Opzioni della riga di comando

Di seguito è riportato la lista di opzioni della riga di comando disponibili per compilare con il modulo .NET:

  • module_mono_enabled=yes | no

    • Compilare Godot con il modulo .NET abilitato.