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 per Windows

Vedi anche

Questa pagina descrive come compilare i binari dell'editor e dei modelli di esportazione per Windows dal codice sorgente. Se invece si desidera esportare il proprio progetto su Windows, consultare Esportazione per Windows.

Requisiti

Per compilare su Windows, è necessario quanto segue:

  • Un compilatore per C++. Usa uno dei seguenti:

    • Visual Studio Community, versione 2019 o successiva. Si consiglia Visual Studio 2022. Durante l'installazione, assicurarsi di selezionare C++ nell'elenco dei flussi di lavoro e di selezionare i seguenti componenti individuali:

      • MSVC v142 - VS 2019 C++ {arch} build tools (Latest) per le architetture di destinazione.

      • Windows 11 SDK (10.0.22621.0) (versione esatta).

      Se hai già installato Visual Studio senza il supporto di C++ per l'architettura di destinazione o senza l'SDK di Windows, eseguire di nuovo il programma di installazione; dovrebbe comparire un pulsante Modifica. Supporta x86_64, x86_32 e arm64.

    • MinGW-w64 con GCC può essere utilizzato come alternativa a Visual Studio. Assicurarsi di installarlo/configurarlo per utilizzare il modello di thread posix. Importante: Quando si utilizza MinGW per compilare il branch master, è necessario GCC 12 o versione successiva. Supporta solo x86_64 e x86_32.

    • MinGW-LLVM con clang può essere utilizzato come alternativa a Visual Studio e MinGW-w64. Supporta x86_64, x86_32 e arm64. Importante: Quando si utilizza MinGW per compilare il branch master, è necessario GCC 14 o versione successiva. Supporta solo x86_64, x86_32 e arm64.

  • Python 3.9+. Assicurarsi di abilitare l'opzione per aggiungere Python al PATH nel programma di installazione.

  • Sistema di compilazione SCons 4.4+. Si consiglia di utilizzare la versione più recente, soprattutto per un corretto supporto delle versioni più recenti di Visual Studio.

  • Dipendenze di Direct3D 12 (è possibile ometterle con l'opzione SCons d3d12=no se non è necessario supportare Direct3D 12).

Nota

Se Scoop è stato installato, è possibile facilmente installare MinGW e altre dipendenze tramite il seguente comando:

scoop install python mingw

Scons dovrà comunque essere installato tramite pip

Nota

Se MSYS2 è stato installato, è possibile facilmente installare MinGW e altre dipendenze tramite il seguente comando:

pacman -S mingw-w64-x86_64-gcc mingw-w64-i686-gcc make python-pip

Per ogni sottosistema MSYS2 MinGW, si dovrebbe poi eseguire pip3 install scons nella sua shell.

Vedi anche

Per ottenere il codice sorgente di Godot per la compilazione, consultare Ottenere il codice sorgente.

Per una panoramica generale sull'utilizzo di SCons per Godot, consultare Introduzione al sistema di compilazione.

Configurare SCons

Per installare SCons, aprire il prompt dei comandi ed eseguire il seguente comando:

python -m pip install scons

Se appare il messaggio Defaulting to user installation because normal site-packages is not writeable, potrebbe essere necessario eseguire nuovamente il comando con autorizzazioni elevate. Aprire un nuovo prompt dei comandi come amministratore, poi eseguire nuovamente il comando per assicurarsi che SCons sia disponibile dalla variabile d'ambiente PATH.

Per verificare se Python e SCons sono stati installati correttamente, si può digitare python --version e scons --version in un prompt dei comandi (cmd.exe).

Se i comandi precedenti non funzionano, assicurarsi di aggiungere Python alla variabile d'ambiente PATH dopo l'installazione, quindi riverificare. Si può fare eseguendo nuovamente il programma di installazione di Python e abilitando l'opzione per aggiungere Python alla variabile d'ambiente PATH.

Se SCons non riesce a rilevare l'installazione di Visual Studio, potrebbe essere che la versione di SCons sia troppo vecchia. Aggiornarla all'ultima versione con python -m pip install --upgrade scons.

Scaricare il codice sorgente di Godot

Consultare Ottenere il codice sorgente per istruzioni dettagliate.

D'ora in poi il tutorial darà per scontato che il codice sorgente sia stato inserito in C:\godot.

Avvertimento

Per evitare rallentamenti causati dalla continua scansione di virus durante la compilazione, aggiungere la cartella sorgente di Godot alla lista di eccezioni del proprio software antivirus.

Per Windows Defender, premere il tasto Windows, digitare "Sicurezza di Windows" e premere Enter. Cliccare su Protezione da virus e minacce nel pannello sinistro. In Impostazioni di protezione da virus e minacce, cliccare su Gestisci impostazioni e scorrere verso il basso fino a Esclusioni. Cliccare su Aggiungi o rimuovi esclusioni, quindi aggiungere la cartella sorgente di Godot.

Compilazione

Selezionare un compilatore

SCons troverà e utilizzerà automaticamente un'installazione di Visual Studio esistente. Se Visual Studio non è installato, tenterà di utilizzare MinGW. Se Visual Studio è già installato e si desidera utilizzare MinGW-w64, passare use_mingw=yes alla riga di comando di SCons. Si noti che non è possibile eseguire le build MSVC dalle shell MSYS2 o MinGW. Utilizzare invece cmd.exe o PowerShell. Se si utilizza MinGW-LLVM, passare sia use_mingw=yes sia use_llvm=yes alla riga di comando di SCons.

Suggerimento

Durante lo sviluppo, utilizzare il compilatore di Visual Studio è solitamente una scelta migliore, poiché collega il binario Godot molto più velocemente di MinGW. Tuttavia, MinGW può produrre binari più ottimizzati tramite link-time optimization (vedi sotto), rendendolo una scelta migliore per l'uso in produzione. Ciò è particolarmente il caso per la VM di GDScript, che offre prestazioni molto migliori con MinGW rispetto a MSVC. Pertanto, si consiglia di utilizzare MinGW per produrre build da distribuire ai giocatori.

Tutti i binari ufficiali di Godot sono compilati in contenitori personalizzati utilizzando MinGW.

Eseguire SCons

Dopo aver aperto un prompt dei comandi, passare alla cartella radice del codice sorgente del motore (tramite cd) e digitare:

C:\godot> scons platform=windows

Nota

Durante la compilazione con più thread della CPU, SCons potrebbe segnalare la mancanza di pywin32. Si può tranquillamente ignorare questo avviso.

Suggerimento

Se si sta compilando Godot per apportare modifiche o contribuire al motore, si consiglia di usare le opzioni di SCons dev_build=yes o dev_mode=yes. Consultare Alias di sviluppo e produzione per maggiori informazioni.

Se tutto va bene, il file binario eseguibile risultante sarà posizionato in C:\godot\bin\ con il nome godot.windows.editor.x86_32.exe o godot.windows.editor.x86_64.exe. Normalmente, SCons creerà un file binario corrispondente all'architettura della CPU, ma è possibile sovrascrivere questa impostazione utilizzando arch=x86_64, arch=x86_32 o arch=arm64.

Questo file eseguibile contiene l'intero motore e funziona senza alcuna dipendenza. Eseguirlo farà apparire il Gestore dei progetti.

Suggerimento

Se si compila Godot per uso in produzione, è possibile rendere l'eseguibile finale più piccolo e veloce aggiungendo l'opzione di SCons production=yes. Ciò abilita ulteriori ottimizzazioni del compilatore e in link-time.

L'esecuzione di LTO richiede un po' di tempo e fino a 30 GB di RAM disponibile durante la compilazione (a seconda della toolchain). Se si esaurisce la memoria con l'opzione precedente, utilizzare production=yes lto=none o production=yes lto=thin (solo LLVM) per una versione di LTO più leggera ma meno efficace.

Nota

Se si vogliono usare impostazioni separate dell'editor per le proprie build di Godot e le versioni ufficiali, è possibile abilitare Modalità autonoma creando un file chiamato ._sc_ o _sc_ nella cartella bin/.

Installare requisiti di Direct3D 12

Normalmente, le versioni di Godot per Windows includono il supporto per l'API grafica Direct3D 12. Compilare con il supporto per Direct3D 12 richiede l'installazione di dipendenze aggiuntive. Se si desidera saltare questo passaggio, è possibile utilizzare l'opzione SCons d3d12=no; in tal caso, il supporto per Vulkan e OpenGL rimarrà comunque disponibile.

È possibile installare le dipendenze richieste eseguendo python misc/scripts/install_d3d12_sdk_windows.py nel repository sorgente di Godot. Dopo aver eseguito questo script, compilare Godot come al solito. Ciò utilizzerà i percorsi predefiniti per le varie dipendenze, che corrispondono a quelli utilizzati nello script.

Di seguito sono riportati i passaggi dettagliati se si desidera configurare manualmente le dipendenze, ma lo script precedente gestisce tutto automaticamente (inclusi i componenti opzionali PIX e Agility SDK).

  • Libreria godot-nir-static. Compiliamo le librerie Mesa di cui avrai bisogno in una libreria statica. Scaricarla ovunque, decomprimerla e ricordare il percorso della cartella decompressa, servirà più avanti.

Nota

Facoltativamente, è possibile compilare autonomamente le librerie godot-nir-static seguendo i seguenti passaggi:

  1. Installare il pacchetto Python mako, necessario per generare alcuni file.

  2. Clonare la cartella godot-nir-static e accedervi.

  3. Eseguire il seguente:

git submodule update --init
./update_mesa.sh
scons

Se si sta compilando con MinGW-w64, aggiungere use_mingw=yes al comando scons; è possibile anche specificare l'architettura di compilazione usando arch={architecture}. Se si sta compilando con MinGW-LLVM, aggiungere entrambi use_mingw=yes e use_llvm=yes al comando scons.

Se si sta compilando con MinGW e i file binari non si trovano nel PATH, aggiungere mingw_prefix="/path/to/mingw" al comando scons.

La libreria statica Mesa deve essere compilata attraverso lo stesso compilatore e la stessa CRT (se si utilizza MinGW) che si sta usando per compilare Godot.

Facoltativamente, è possibile compilare con i seguenti per funzionalità aggiuntive:

  • PIX è un'applicazione di debug e ottimizzazione delle prestazioni per applicazioni Direct3D12. Se ne si compila il supporto, è possibile ottenere informazioni molto più dettagliate tramite PIX, che aiuteranno a ottimizzare il gioco e a risolvere i bug grafici. Per utilizzarlo, scaricare il pacchetto WinPixEventRuntime. Verrà visualizzata una pagina del pacchetto NuGet, dove è possibile cliccare su "Download package" per scaricarlo. Una volta scaricato, cambiare l'estensione del file in .zip e decomprimerlo da qualche parte..

  • Agility SDK può servire per fornire accesso alle funzionalità Direct3D 12 più recenti senza dover ricorrere agli aggiornamenti dei driver. Per utilizzarlo, scaricare l'ultimo pacchetto Agility SDK. Verrà visualizzata una pagina NuGet contenente il pacchetto, dove è possibile cliccare su "Scarica pacchetto" per scaricarlo. Una volta scaricato, cambiare l'estensione del file in .zip e decomprimerlo da qualche parte.

Nota

Se si utilizza una versione di anteprima di Agility SDK, assicurarsi di abilitare la modalità sviluppatore in Windows; altrimenti non sarà utilizzata.

Nota

Se si desidera utilizzare una build PIX con MinGW, accedere alla cartella di runtime di PIX e usare i seguenti comandi per generare la libreria di importazione:

# For x86-64:
gendef ./bin/x64/WinPixEventRuntime.dll
dlltool --machine i386:x86-64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/x64/libWinPixEventRuntime.a

# For ARM64:
gendef ./bin/ARM64/WinPixEventRuntime.dll
dlltool --machine arm64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/ARM64/libWinPixEventRuntime.a

Durante la compilazione di Godot, sarà necessario indicare a SCon dove cercare le librerie aggiuntive:

C:\godot> scons platform=windows mesa_libs=<...>

O, con tutte le opzioni abilitate:

C:\godot> scons platform=windows mesa_libs=<...> agility_sdk_path=<...> pix_path=<...>

Nota

Il supporto per PIX è normalmente disabilitato, anche se è installato. Per abilitarlo, passare use_pix=yes a SCons.

Nota

Per le DLL di SDK Agility è necessario scegliere esplicitamente il tipo di flusso di lavoro. Single-arch è la scelta predefinita (DLL copiate in bin/). Passando agility_sdk_multi_arch=yes a SCons, si opterà per multi-arch. Le DLL verranno copiate nelle sottocartelle bin/<arch>/ appropriate e in fase di esecuzione verrà caricata quella corretta.

Compilare con supporto AccessKit

AccessKit offre supporto per i lettori dello schermo.

La compilazione con AccessKit richiede di installare ulteriori dipendenze. Se si desidera saltare questo passaggio, è possibile usare l'opzione SCons accesskit=no.

È possibile installare le dipendenze richieste eseguendo python misc/scripts/install_accesskit.py nel repository sorgente di Godot. Dopo aver eseguito questo script, compilare Godot come al solito.

Nota

Facoltativamente, è possibile compilare autonomamente le librerie AccessKit seguendo i seguenti passaggi:

  1. Clonare la cartella godot-accesskit-c-static e accedervi.

  2. Eseguire il seguente comando:

cd accesskit-c
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build

La libreria statica AccessKit deve essere compilata attraverso lo stesso compilatore e la stessa CRT (se si utilizza MinGW) che si sta usando per compilare Godot.

Per compilare Godot con una build personalizzata di AccessKit, aggiungere accesskit_sdk_path={percorso} per indicare a SCons dove cercare le librerie AccessKit:

scons platform=windows accesskit_sdk_path=<...>

Compilare con supporto WinRT

WinRT offre supporto per OneCore TTS (accesso alle voci di Windows 10+), il monitoraggio delle informazioni sul colore HDR e il selettore di emoji.

Se si sta compilando con MinGW, la compilazione con WinRT richiede di installare ulteriori dipendenze. Se si desidera saltare questo passaggio, è possibile usare l'opzione SCons winrt=no.

È possibile installare le dipendenze richieste eseguendo python misc/scripts/install_winrt.py nel repository sorgente di Godot. Dopo aver eseguito questo script, compilare Godot come al solito.

Nota

Facoltativamente, è possibile compilare autonomamente gli header WinRT seguendo i seguenti passaggi:

  1. Clonare la cartella winrt-mingw e accedervi.

  2. Eseguire il seguente comando:

cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCPPWINRT_BUILD_VERSION=2.0.250303.1 -DBUILD_TESTING=OFF cppwinrt/
echo "" > build/app.manifest.rc
cmake --build build
./build/cppwinrt.exe -input windows-rs/crates/libs/bindgen/default/ -output include/

Per compilare Godot con una build personalizzata di WinRT, aggiungere winrt_path={percorso} per indicare a SCons dove cercare le librerie AccessKit:

scons platform=windows winrt_path=<...>

Compilare con supporto ANGLE

ANGLE fornisce un livello di traduzione da OpenGL ES 3.x a Direct3D 11 e si può utilizzare per migliorare il supporto per il renderer Compatibilità su alcune vecchie GPU con driver OpenGL obsoleti e su Windows per ARM.

La compilazione con ANGLE richiede di installare ulteriori dipendenze. Se si desidera saltare questo passaggio, è possibile usare l'opzione SCons angle=no.

È possibile installare le dipendenze richieste eseguendo python misc/scripts/install_angle.py nel repository sorgente di Godot. Dopo aver eseguito questo script, compilare Godot come al solito.

Nota

Facoltativamente, è possibile compilare autonomamente le librerie godot-angle-static seguendo i seguenti passaggi:

  1. Clonare la cartella godot-angle-static e accedervi.

  2. Eseguire il seguente comando:

git submodule update --init
./update_angle.sh
scons

Se si sta compilando con MinGW, aggiungere use_mingw=yes al comando; è possibile anche specificare l'architettura di compilazione usando arch={architecture}. Se si sta compilando con MinGW-LLVM, aggiungere entrambi use_mingw=yes e use_llvm=yes al comando scons.

Se si sta compilando con MinGW e i file binari non si trovano nel PATH, aggiungere mingw_prefix="/path/to/mingw" al comando scons.

La libreria statica ANGLE deve essere compilata attraverso lo stesso compilatore e la stessa CRT (se si utilizza MinGW) che si sta usando per compilare Godot.

Per compilare Godot con una build personalizzata di ANGLE, aggiungere angle_libs={percorso} per indicare a SCons dove cercare le librerie ANGLE:

scons platform=windows angle_libs=<...>

Sviluppo in Visual Studio

Non è necessario utilizzare un IDE per compilare Godot, poiché SCons si occupa di tutto. Tuttavia, se si intende sviluppare il motore o effettuare il debug del codice C++ del motore, potrebbe essere interessante configurare un editor di codice o un IDE.

Gli editor basati su cartelle non richiedono alcuna configurazione particolare per cominciare a lavorare con il codice sorgente di Godot. Per modificare i progetti con Visual Studio, si devono configurare come soluzione.

È possibile creare una soluzione Visual Studio tramite SCons eseguendo SCons con il parametro vsproj=yes, in questo modo:

scons platform=windows vsproj=yes

Ora sarà possibile aprire il codice sorgente di Godot in una soluzione di Visual Studio e compilare Godot tramite il pulsante Build di Visual Studio.

Vedi anche

Consultare Visual Studio per istruzioni dettagliate.

Risoluzione dei problemi

Se la compilazione fallisce utilizzando MSVC, assicurarsi di applicare gli ultimi aggiornamenti. È possibile farlo avviando l'IDE di Visual Studio e selezionando Continue without code, quindi Help > Check for Updates nella barra del menu in alto. Installare tutti gli aggiornamenti, quindi riprovare a compilare.

Cross-compiling for Windows from other operating systems

Se si usa Linux o macOS, è necessario installare MinGW-w64, che in genere è disponibile nelle varianti a 32 e 64 bit, oppure MinGW-LLVM, che è fornito come archivio unico per tutte le architetture di destinazione. I nomi dei pacchetti possono variare in base alla distribuzione, ecco alcuni dei più noti:

Arch Linux

 
pacman -S mingw-w64

Debian / Ubuntu

 
apt install mingw-w64

Fedora

 
dnf install mingw64-gcc-c++ mingw64-winpthreads-static \
            mingw32-gcc-c++ mingw32-winpthreads-static

macOS

 
brew install mingw-w64

Mageia

 
urpmi mingw64-gcc-c++ mingw64-winpthreads-static \
      mingw32-gcc-c++ mingw32-winpthreads-static

Prima di tentare la compilazione, SCons verificherà la presenza dei seguenti file binari nella variabile d'ambiente PATH:

# for MinGW-w64
i686-w64-mingw32-gcc
x86_64-w64-mingw32-gcc

# for MinGW-LLVM
aarch64-w64-mingw32-clang
i686-w64-mingw32-clang
x86_64-w64-mingw32-clang

Se i file binari non si trovano in PATH (ad esempio /usr/bin), è possibile definire la seguente variabile d'ambiente per fornire un suggerimento al sistema di compilazione:

export MINGW_PREFIX="/path/to/mingw"

Dove /path/to/mingw è il percorso contenente la cartella bin in cui si trovano i686-w64-mingw32-gcc e x86_64-w64-mingw32-gcc (ad esempio /opt/mingw-w64 se i file binari si trovano in /opt/mingw-w64/bin).

Per assicurarsi di star procedendo correttamente, eseguire quanto segue nella shell dovrebbe risultare in un compilatore funzionante (l'output della versione potrebbe variare in base al sistema):

${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version
# x86_64-w64-mingw32-gcc (GCC) 13.2.0

Nota

Se si sta compilando con MinGW-LLVM, aggiungere use_llvm=yes al comando scons.

Nota

Quando si esegue una cross-compilazione per Windows tramite MinGW-w64, tenere presente che sono supportate solo le architetture x86_64 e x86_32. MinGW-LLVM supporta anche arm64. Assicurarsi di specificare l'opzione arch= corretta quando si invoca SCons se si compila da un'architettura diversa.

Risoluzione dei problemi

La cross-compilazione da alcune versioni di Ubuntu potrebbe causare questo bug, dovuto a una configurazione predefinita che non supporta il threading POSIX.

È possibile modificare tale configurazione seguendo le istruzioni riportate di seguito, per 64 bit:

sudo update-alternatives --config x86_64-w64-mingw32-gcc
<choose x86_64-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config x86_64-w64-mingw32-g++
<choose x86_64-w64-mingw32-g++-posix from the list>

E per 32 bit:

sudo update-alternatives --config i686-w64-mingw32-gcc
<choose i686-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config i686-w64-mingw32-g++
<choose i686-w64-mingw32-g++-posix from the list>

Creare modelli di esportazione per Windows

I modelli di esportazione per Windows vengono creati compilando Godot senza l'editor, con i seguenti flag:

C:\godot> scons platform=windows target=template_debug arch=x86_32
C:\godot> scons platform=windows target=template_release arch=x86_32
C:\godot> scons platform=windows target=template_debug arch=x86_64
C:\godot> scons platform=windows target=template_release arch=x86_64
C:\godot> scons platform=windows target=template_debug arch=arm64
C:\godot> scons platform=windows target=template_release arch=arm64

Se si prevede di sostituire i modelli di esportazione standard, copiarli nel seguente percorso, sostituendo <version> con l'identificatore della versione (ad esempio 4.2.1.stable o 4.3.dev):

%APPDATA%\Godot\export_templates\<version>\

Con i seguenti nomi:

windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe

Tuttavia, se si stanno utilizzando moduli personalizzati o codice personalizzato per il motore, si potrebbe voler configurare i binari come modelli di esportazione personalizzati nel menu di esportazione. È necessario abilitare Opzioni avanzate per impostarlo.

../../../_images/wintemplates.webp

In questo caso non è necessario copiarli, basta fare riferimento ai file risultanti nella cartella bin\ della propria cartella sorgente di Godot, così la prossima volta che si compilerà, si avranno riferiti automaticamente i modelli personalizzati.