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

Compilando para Android

Ver também

Esta página descreve como compilar binários de modelos de exportação do Android a partir do código-fonte. Se você deseja exportar seu projeto para o Android, leia Exportando para Android.

Observação

Na maioria dos casos, usar o implantador integrado e os modelos de exportação é suficiente. Compilar o APK do Android manualmente é útil principalmente para builds personalizados ou pacotes personalizados para o implantador.

Além disso, você ainda precisa seguir as etapas mencionadas no tutorial Exportando para Android antes de tentar buildar um modelo de exportação personalizado.

Requisitos

Para compilar no Windows, Linux ou macOS, é necessário o seguinte:

  • Python 3.9+.

  • Sistema de build SCons 4.4+.

  • Android SDK

    • To instalar o SDK do Android, siga as etapas aqui.

    • No Linux, não use um Android SDK fornecido pelos repositórios da sua distribuição, pois ele geralmente estará desatualizado.

    • No macOS, não use um Android SDK fornecido pelo Homebrew, pois ele não será instalado em um local unificado.

  • Gradle (será baixado e instalado automaticamente se estiver ausente).

  • JDK 17 (seja OpenJDK ou Oracle JDK).

    • Você pode baixar uma build do Adoptium.

Ver também

Para obter o código-fonte do Godot para compilação, consulte Adquirindo o código fonte.

Para uma visão geral do uso do SCons no Godot, veja Introdução ao sistema de compilação.

Configurando o sistema de build

  • Defina a variável de ambiente ANDROID_HOME para apontar para o SDK do Android. Se você baixou as ferramentas de linha de comando do Android, esta seria a pasta onde você extraiu o conteúdo do arquivo ZIP.

    • Windows: Pressione Windows + R, digite "control system", depois clique em Configurações avançadas do sistema no painel esquerdo e clique em Variáveis de ambiente na janela que aparece.

    • Linux ou macOS: Adicione o texto export ANDROID_HOME="/path/to/android-sdk" ao seu .bashrc ou .zshrc onde /path/to/android-sdk aponta para a raiz dos diretórios do SDK.

  • Depois de configurar o SDK e as variáveis de ambiente, certifique-se de reiniciar seu terminal para aplicar as alterações. Se você estiver usando uma IDE com um terminal integrado, será necessário reiniciar a IDE.

  • Execute scons platform=android. Se isso falhar, volte e verifique as etapas. Se você concluiu a configuração corretamente, o NDK começará a ser baixado. Se você estiver tentando compilar a GDExtension, precisará primeiro compilar a engine para baixar o NDK e, em seguida, poderá compilar a GDExtension.

Buildando os modelos de exportação

O Godot precisa de três modelos de exportação para o Android: o modelo "release" otimizado (android_release.apk), o modelo de debug (android_debug.apk) e o modelo de build do Gradle (android_source.zip). Como a Google exige que todos os APKs incluam bibliotecas ARMv8 (64 bits) desde agosto de 2019, os comandos abaixo buildam modelos que contêm as bibliotecas ARMv7 e ARMv8.

A compilação dos modelos de exportação padrão é feita chamando o SCons a partir do diretório raiz do Godot com os seguintes argumentos:

  • Modelo de release (usado ao exportar com Habilitar Depuração desmarcado)

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

  • Modelo de debug (usado ao exportar com Habilitar Depuração marcado)

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

Os modelos resultantes estarão localizados no diretório bin:

  • bin/android_release.apk para o modelo de release

  • bin/android_debug.apk para o modelo de debug

  • bin/android_source.zip para o modelo de build do Gradle

Nota

  • Se você estiver alterando a lista de arquiteturas que está buildando, lembre-se de adicionar generate_android_binaries=yes à última arquitetura que está buildando, para que os arquivos de modelo sejam gerados após o build.

  • Para habilitar o build de desenvolvimento (para uso na resolução de problemas) nos modelos gerados, adicione os parâmetros dev_build=yes ao comando SCons.

  • Para incluir símbolos de depuração nos modelos gerados, adicione os parâmetros debug_symbols=yes ao comando SCons.

    • Observe que você pode incluir separate_debug_symbols=yes para gerar os símbolos de depuração em um arquivo *-native-debug-symbols.zip separado.

Ver também

Se você quiser habilitar as camadas de validação do Vulkan, consulte Vulkan validation layers on Android.

Adicionando suporte para dispositivos x86

Se você também quiser incluir suporte para dispositivos x86 e x86_64, execute o comando SCons uma terceira e quarta vez com os argumentos arch=x86_32 e arch=x86_64 antes de buildar o APK com o Gradle. Por exemplo, para o modelo de release:

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

Limpando os modelos de exportação gerados

Você pode usar os seguintes comandos para remover os modelos de exportação gerados:

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

Usando os modelos de exportação

O Godot precisa de binários de release e debug que foram compilados na mesma versão/commit que o editor. Se você estiver usando binários oficiais para o editor, certifique-se de instalar os modelos de exportação correspondentes ou buildar os seus próprios a partir da mesma versão.

Ao exportar seu jogo, o Godot usa os modelos como base e atualiza seu conteúdo conforme necessário.

Instalando os modelos

Os modelos recém-compilados (android_debug.apk, android_release.apk e android_source.zip) devem ser copiados para a pasta de modelos do Godot com seus respectivos nomes. A pasta de modelos pode ser localizada em:

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

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

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

<version> é da forma major.minor[.patch].status usando valores de version.py no seu repositório de origem do Godot (ex. 4.1.3.stable ou 4.2.dev). Você também precisa escrever essa mesma string de versão em um arquivo version.txt localizado ao lado de seus modelos de exportação.

No entanto, se você estiver escrevendo seus módulos personalizados ou código C++ personalizado, talvez prefira configurar seus binários de modelo como modelos de exportação personalizados no menu de exportação do projeto. Você deve ter as Opções Avançadas habilitadas para definir isso.

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

Você nem precisa copiá-los, pode apenas referenciar o arquivo resultante no diretório bin\ da sua pasta de código-fonte do Godot, para que na próxima vez que você buildar, os modelos personalizados sejam referenciados automaticamente.

Construindo o editor Godot

A compilação do editor é feita chamando o SCons a partir do diretório raiz do Godot com os seguintes argumentos:

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

  • Você pode adicionar o parâmetro dev_build=yes para gerar um build de desenvolvimento do editor do Godot.

  • Você pode adicionar os parâmetros debug_symbols=yes para incluir os símbolos de depuração no build gerado.

    • Observe que você pode incluir separate_debug_symbols=yes na última arquitetura que está buildando, para gerar os símbolos de depuração em um arquivo *-native-debug-symbols.zip separado.

  • Você pode pular certas arquiteturas dependendo do seu dispositivo de destino para acelerar a compilação.

Lembre-se de adicionar generate_android_binaries=yes à última arquitetura que está buildando, para que os binários sejam gerados após o build.

Os binários resultantes estarão localizados em bin/android_editor_builds/.

Removendo os binários do Editor

Você pode usar os seguintes comandos para remover os binários do editor gerados:

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

Instalando o APK do editor Godot

Com um dispositivo Android com as Opções do Desenvolvedor ativadas, conecte o dispositivo Android ao seu computador através do cabo de carregamento a uma porta USB/USB-C. Abra um Terminal/Prompt de Comando e execute os seguintes comandos a partir do diretório raiz com os seguintes argumentos:

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

Solução de problemas

Plataforma não aparece no SCons

Verifique novamente se você configurou a variável de ambiente ANDROID_HOME. Isso é necessário para que a plataforma apareça na lista de plataformas detectadas do SCons. Consulte Setting up the buildsystem para mais informações.

Aplicação não instalada

O Android pode reclamar que o aplicativo não foi instalado corretamente. Se for o caso:

  • Verifique se o keystore de debug foi gerado corretamente.

  • Verifique se o executável jarsigner é do JDK 8.

Se ainda assim falhar, abra uma linha de comando e execute o logcat:

adb logcat

Em seguida, verifique a saída enquanto o aplicativo é instalado; a mensagem de erro deve ser apresentada ali. Procure ajuda se não conseguir descobrir o motivo.

A aplicação fecha imediatamente

Se o aplicativo for executado, mas fechar imediatamente, isso pode ser devido a um dos seguintes motivos:

  • Certifique-se de usar modelos de exportação que correspondam à versão do seu editor; se você usar uma nova versão do Godot, precisará atualizar os modelos também.

  • libgodot_android.so não está em libs/<arch>/ onde <arch> é a arquitetura do dispositivo.

  • A arquitetura do dispositivo não corresponde à(s) exportada(s). Certifique-se de que seus modelos foram buildados para a arquitetura desse dispositivo e que as configurações de exportação incluíam o suporte para essa arquitetura.

Em qualquer caso, o adb logcat também deve mostrar a causa do erro.