Compilar para Android

Ver también

Esta página describe cómo compilar binarios de plantillas de exportación de Android desde el código fuente. Si estás buscando exportar tu proyecto a Android, lee Exportación para Android.

Nota

En la mayoría de los casos, usar el desplegador incorporado y las plantillas de exportación es suficiente. Compilar el APK de Android manualmente es principalmente útil para compilaciones personalizadas o paquetes personalizados para el desplegador.

También es necesario seguir los pasos mencionados en el tutorial Exportación para Android antes de intentar construir una plantilla de exportación personalizada.

Requerimientos

Para compilar en Windows, Linux o macOS, se requiere lo siguiente:

  • Python 3.8+.

  • SCons 4.0+ build system.

  • Android SDK (las herramientas de línea de comandos son suficiente).

    • Los componentes del SDK necesarios se instalarán automáticamente.

    • On Linux, do not use an Android SDK provided by your distribution's repositories as it will often be outdated.

    • On macOS, do not use an Android SDK provided by Homebrew as it will not be installed in a unified location.

  • Gradle (se descargará e instalará automáticamente si falta).

  • JDK 17 (puede ser OpenJDK u Oracle JDK).

    • You can download a build from Adoptium.

Ver también

Para obtener el código fuente de Godot para compilarlo, consulta la sección Consiguiendo el código fuente.

Para obtener una visión general del uso de SCons para Godot, consulta la sección Introducción al sistema de compilación.

Configurando el sistema de construcción

  • Set the environment variable ANDROID_HOME to point to the Android SDK. If you downloaded the Android command-line tools, this would be the folder where you extracted the contents of the ZIP archive.

    • 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 or macOS: Add the text export ANDROID_HOME="/path/to/android-sdk" to your .bashrc or .zshrc where /path/to/android-sdk points to the root of the SDK directories.

  • Instala los componentes necesarios del SDK en esta carpeta:

    • Acepta las licencias de los componentes del SDK ejecutando el siguiente comando donde android_sdk_path es la ruta al SDK de Android y luego respondiendo todas las solicitudes con y:

    cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> --licenses

    • Completa la configuración ejecutando el siguiente comando donde android_sdk_path es la ruta al SDK de Android.

    cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;35.0.0" "platforms;android-35" "cmdline-tools;latest" "cmake;3.10.2.4988404" "ndk;28.1.13356709"

  • Después de configurar el SDK y las variables de entorno, asegúrate de reiniciar tu terminal para aplicar los cambios. Si estás utilizando un IDE con un terminal integrado, debes reiniciar el IDE.

  • Ejecuta scons platform=android. Si esto falla, vuelva atrás y repase los pasos. Si completó la configuración correctamente, el NDK comenzará a descargarse. Si estás intentando compilar GDExtension, primero debe compilar el motor para descargar el NDK y luego podrá compilar GDExtension.

Construyendo las plantillas de exportación

Godot needs three export templates for Android: the optimized "release" template (android_release.apk), the debug template (android_debug.apk), and the Gradle build template (android_source.zip). As Google requires all APKs to include ARMv8 (64-bit) libraries since August 2019, the commands below build templates containing both ARMv7 and ARMv8 libraries.

La compilación de las plantillas de exportación estándar se realiza llamando a SCons desde el directorio raíz de Godot con los siguientes argumentos:

  • Release template (se utiliza al exportar con Debugging Enabled apagado)

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

  • Debug template (se utiliza cuando se exporta con Debugging Enabled encendido)

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

  • (Opcional) Plantilla de desarrollo (se utiliza para solucionar problemas)

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

Las plantillas resultantes se ubicarán en el directorio bin:

  • bin/android_release.apk para la plantilla de versión final

  • bin/android_debug.apk para la plantilla de desarrollo

  • bin/android_dev.apk para la plantilla de desarrollo

  • bin/android_source.zip para la plantilla de desarrollo

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 include debug symbols in the generated templates, add the debug_symbols=yes parameters to the SCons command.

    • Note that you can include separate_debug_symbols=yes to generate the debug symbols in a separate *-native-debug-symbols.zip file.

Ver también

Si deseas habilitar las capas de validación de Vulkan, consulta Capas de validación de Vulkan en Android.

Añadir soporte para dispositivos x86

If you also want to include support for x86 and x86_64 devices, run the SCons command a third and fourth time with the arch=x86_32, and arch=x86_64 arguments before building the APK with Gradle. For example, for the release template:

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.

Limpiando las plantillas de exportación generada

Puedes utilizar los siguientes comandos para eliminar las plantillas de exportación generadas:

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

Usando las plantillas de exportación

Godot needs release and debug binaries that were compiled against the same version/commit as the editor. If you are using official binaries for the editor, make sure to install the matching export templates, or build your own from the same version.

When exporting your game, Godot uses the templates as a base, and updates their content as needed.

Instalando las plantillas

The newly-compiled templates (android_debug.apk , android_release.apk, and android_source.zip) must be copied to Godot's templates folder with their respective names. The templates folder can be located 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> is of the form major.minor[.patch].status using values from version.py in your Godot source repository (e.g. 4.1.3.stable or 4.2.dev). You also need to write this same version string to a version.txt file located next to your export templates.

Sin embargo, si estás escribiendo tus propios módulos personalizados o código C++ personalizado, es posible que desees configurar tus plantillas de binarios como plantillas de exportación personalizadas en el menú de exportación del proyecto. Debes tener Opciones Avanzadas activadas para activar esto.

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

No es necesario ni siquiera copiarlos, simplemente puedes hacer referencia al archivo resultante en el directorio bin\ de la carpeta de origen de Godot, de modo que la próxima vez que construyas, tendrás automáticamente las plantillas personalizadas referenciadas.

Building the Godot editor

Compiling the editor is done by calling SCons from the Godot root directory with the following arguments:

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

  • Puedes agregar el parámetro dev_build=yes para generar una compilación de desarrollo del editor Godot.

  • You can add the debug_symbols=yes parameters to include the debug symbols in the generated build.

    • Note that you can include separate_debug_symbols=yes to generate the debug symbols in a separate *-native-debug-symbols.zip file.

  • Puedes omitir ciertas arquitecturas según su dispositivo de destino para acelerar la compilación.

Remember to add generate_android_binaries=yes to the last architecture you're building, so that binaries are generated after the build.

The resulting binaries will be located under bin/android_editor_builds/.

Removing the Editor binaries

You can use the following commands to remove the generated editor binaries:

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

Installing the Godot editor APK

Con un dispositivo Android con las Opciones de Desarrollador habilitadas, conecta el dispositivo Android a tu computadora a través de su cable de carga a un puerto USB/USB-C. Abre una terminal o un símbolo del sistema y ejecuta los siguientes comandos desde el directorio raíz con los siguientes argumentos:

adb install ./bin/android_editor_builds/android_editor-release.apk

Solución De Problemas

Plataforma no aparece en SCons

Double-check that you've set the ANDROID_HOME environment variable. This is required for the platform to appear in SCons' list of detected platforms. See Setting up the buildsystem for more information.

Aplicación no instalada

Android podría mostrar un mensaje indicando que la aplicación no está instalada correctamente. Si esto sucede:

  • Verifica que el almacén de claves de depuración (debug keystore) esté correctamente generado.

  • Revisar que el ejecutable jarsigner es de JDK 8.

Si aún falla, abre una línea de comandos y ejecuta logcat:

adb logcat

Luego, revisa la salida mientras la aplicación está instalada; el mensaje de error debería aparecer allí. Si no puedes resolverlo, busca ayuda para solucionar el problema.

La aplicación se cierra inmediatamente

Si la aplicación se ejecuta pero se cierra inmediatamente, esto podría deberse a una de las siguientes razones:

  • Asegúrate de utilizar plantillas de exportación que coincidan con la versión de tu editor; si utilizas una nueva versión de Godot, debes actualizar también las plantillas.

  • libgodot_android.so is not in libs/<arch>/ where <arch> is the device's architecture.

  • La arquitectura del dispositivo no coincide con la(s) arquitectura(s) exportada(s). Asegúrate de que tus plantillas hayan sido compiladas para la arquitectura del dispositivo y que la configuración de exportación incluya soporte para esa arquitectura.

En cualquier caso, adb logcat también debería mostrar la causa del error.