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 Android

Vedi anche

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

Nota

Nella maggior parte dei casi, basta utilizzare il deployer integrato e i modelli di esportazione. Compilare manualmente l'APK di Android è utile soprattutto per build personalizzate o pacchetti personalizzati per il deployer.

Inoltre, è comunque necessario seguire i passaggi indicati nel tutorial Esportazione per Android prima di provare a creare un modello di esportazione personalizzato.

Requisiti

Per compilare su Windows, Linux o macOS, è necessario quanto segue:

  • Python 3.9+.

  • SCons 4.4+ build system.

  • Android SDK

    • To install the Android SDK, follow the steps here.

    • Su Linux, non utilizzare un SDK di Android fornito dai repository della propria distribuzione perché spesso risulta obsoleto.

    • Su macOS, non utilizzare un SDK di Android fornito da Homebrew poiché non sarà installato in una posizione unificata.

  • Gradle (sarà scaricato e installato automaticamente se manca).

  • JDK 17 (OpenJDK o Oracle JDK).

    • You can download a build from Adoptium.

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 il sistema di compilazione

  • Impostare la variabile d'ambiente ANDROID_HOME in modo che punti all'SDK di Android. Se sono già stati scaricati gli strumenti da riga di comando di Android, questa sarà la cartella in cui è stato estratto il contenuto dell'archivio ZIP.

    • Windows: Press Windows + R, type "control system", then click on Advanced system settings in the left pane, then click on Environment variables on the window that appears.

    • Linux o macOS: aggiungere il testo export ANDROID_HOME="/path/to/android-sdk" al proprio file .bashrc o .zshrc dove /path/to/android-sdk punta alla radice delle cartelle dell'SDK.

  • Dopo aver configurato l'SDK e le variabili d'ambiente, assicurarsi di riavviare il terminale per applicare le modifiche. Se si utilizza un IDE con terminale integrato, è necessario riavviarlo.

  • Esegui scons platform=android. Se questo fallisce, tornare indietro e controllare i passaggi. Se la configurazione è stata completata correttamente, il download dell'NDK inizierà. Se si sta provando a compilare GDExtension, è necessario prima compilare il motore per scaricare l'NDK, dopodiché sarà possibile compilare GDExtension.

Compilare i modelli di esportazione

Godot necessita di tre modelli di esportazione per Android: il modello di "rilascio" ottimizzato (android_release.apk), il modello di debug (android_debug.apk) e il modello di build Gradle (android_source.zip). Poiché Google richiede che tutti gli APK includano librerie ARMv8 (64 bit) da agosto 2019, i comandi seguenti creano modelli di build contenenti sia librerie ARMv7 sia ARMv8.

La compilazione dei modelli di esportazione standard è eseguita chiamando SCons dalla cartella radice di Godot con i seguenti argomenti:

  • Modello di rilascio (utilizzato durante l'esportazione con l'opzione Debug abilitato deselezionata)

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_android_binaries=yes

  • Modello di debug (utilizzato durante l'esportazione con Debug abilitato selezionato)

scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_android_binaries=yes

I modelli risultanti saranno inseriti nella cartella bin:

  • bin/android_release.apk per il modello di rilascio

  • bin/android_debug.apk per il modello di debug

  • bin/android_source.zip per il modello di build Gradle

Nota

  • If you are changing the list of architectures you're building, remember to add generate_android_binaries=yes to the last architecture you're building, so that the template files are generated after the build.

  • To enable dev build (for use when troubleshooting) in the generated templates, add the dev_build=yes parameters to the SCons command.

  • Per includere i simboli di debug nei modelli generati, aggiungere il parametro debug_symbols=yes al comando SCons.

    • Si noti che possibile includere il parametro separate_debug_symbols=yes per generare i simboli di debug in un file *-native-debug-symbols.zip separato .

Vedi anche

If you want to enable Vulkan validation layers, see Vulkan validation layers on Android.

Aggiungere supporto per i dispositivi x86

Se si desidera includere anche il supporto per dispositivi x86 e x86_64, eseguire il comando SCons una terza e una quarta volta con gli argomenti arch=x86_32 e arch=x86_64 prima di compilare l'APK con Gradle. Ad esempio, per il modello di rilascio:

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=x86_32
scons platform=android target=template_release arch=x86_64 generate_android_binaries=yes

This will create template binaries that works on all platforms. The final binary size of exported projects will depend on the platforms you choose to support when exporting; in other words, unused platforms will be removed from the binary.

Pulizia dei modelli di esportazione generati

È possibile utilizzare i seguenti comandi per rimuovere i modelli di esportazione generati:

cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

Utilizzare i modelli di esportazione

Godot ha bisogno di binari di rilascio e di debug, compilati con la stessa versione/commit dell'editor. Se si utilizzano binari ufficiali per l'editor, assicurarsi di installare i modelli di esportazione corrispondenti o di crearne di propri a partire dalla stessa versione.

Quando viene esportato il proprio gioco, Godot usa i modelli come base e ne aggiorna il contenuto secondo le necessità.

Installare i modelli

I modelli nuovamente compilati (android_debug.apk, android_release.apk e android_source.zip) si devono copiare nella cartella dei modelli di Godot con i rispettivi nomi. La cartella dei modelli si trova in:

  • Windows: %APPDATA%\Godot\export_templates\<version>\

  • Linux: $HOME/.local/share/godot/export_templates/<version>/

  • macOS: $HOME/Library/Application Support/Godot/export_templates/<version>/

<version> ha il formato major.minor[.patch].status e utilizza i valori di version.py nel proprio repository sorgente di Godot (ad esempio 4.1.3.stable o 4.2.dev). È necessario anche scrivere la stessa stringa di versione in un file version.txt situato accanto ai propri modelli di esportazione.

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

../../../_images/andtemplates.webp

Non è nemmeno 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.

Compilare l'editor di Godot

La compilazione dell'editor avviene chiamando SCons dalla cartella radice di Godot con i seguenti argomenti:

scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_android_binaries=yes

  • È possibile aggiungere il parametro dev_build=yes per generare una compilazione di sviluppo dell'editor Godot.

  • È possibile aggiungere i parametri debug_symbols=yes per includere i simboli di debug nella build generata.

    • Note that you can include separate_debug_symbols=yes to the last architecture you're building, to generate the debug symbols in a separate *-native-debug-symbols.zip file.

  • È possibile ignorare determinate architetture, a seconda del dispositivo di destinazione, per velocizzare la compilazione.

Si ricordi di aggiungere generate_android_binaries=yes all'ultima architettura che si sta creando, in modo che i file binari vengano generati dopo la build.

I file binari risultanti si troveranno in bin/android_editor_builds/.

Rimuovere i binari dell'editor

Puoi utilizzare i seguenti comandi per rimuovere gli eseguibili generati dell'editor:

 cd platform/android/java
 # On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

Installare l'APK dell'editor di Godot

Con un dispositivo Android con le Opzioni per sviluppatori abilitate, collegare il dispositivo Android al computer tramite il cavo di ricarica a una porta USB/USB-C. Aprire un terminale o un prompt dei comandi e, dalla cartella principale, eseguire i seguenti comandi con i seguenti argomenti:

adb install ./bin/android_editor_builds/android_editor-android-debug.apk

Risoluzione dei problemi

La piattaforma non appare in SCons

Verificare di aver impostato la variabile d'ambiente ANDROID_HOME. Questo è necessario affinché la piattaforma appaia nell'elenco delle piattaforme rilevate da SCons. Consultare Configurazione del sistema di compilazione per ulteriori informazioni.

Applicazione non installata

Android potrebbe segnalare che l'applicazione non è installata correttamente. In tal caso:

  • Verificare che il keystore di debug sia generato correttamente.

  • Verificare che l'eseguibile jarsigner provenga da JDK 8.

Se il problema persiste, aprire una riga di comando ed eseguire logcat:

adb logcat

Successivamente controlla l'output durante l'installazione dell'applicazione; il messaggio di errore dovrebbe apparire lì. Chiedere aiuto se non si capisce.

L'applicazione si ferma immediatamente

Se l'applicazione viene eseguita ma termina immediatamente, ciò potrebbe essere dovuto a una delle seguenti ragioni:

  • Assicurarsi di utilizzare modelli di esportazione che corrispondano alla versione del proprio editor; se si utilizza una nuova versione di Godot, è necessario aggiornare anche i modelli.

  • libgodot_android.so non si trova in libs/<arch>/ dove <arch> è l'architettura del dispositivo.

  • L'architettura del dispositivo non corrisponde a quella esportata. Assicurarsi che i modelli siano stati creati per l'architettura di quel dispositivo e che le impostazioni di esportazione includano il supporto per quell'architettura.

In qualunque caso, adb logcat dovrebbe mostrare anche la causa dell'errore.