为Android平台编译

注意

对于大多数情况,使用内置部署程序和导出模板就足够了。手动编译Android APK对于部署程序的自定义版本或自定义程序包最有用。

此外,在尝试构建自定义导出模板之前,您仍然需要按照 为Android导出 教程中提到的步骤进行操作。

需求

要在Windows、Linux或macOS下进行编译,需要以下内容:

  • Python 2.7+ 或 Python 3.5+
  • SCons 构建系统
  • Android SDK (命令行工具就足够了)
    • 所需的SDK组件将由Gradle自动安装(NDK除外)
  • Android NDK r17 或高级版本
  • Gradle(如果缺少,将自动下载并安装)
  • JDK 8 ( OpenJDK 或 Oracle JDK)
    • 目前不支持JDK 9或更高版本
    • 您可以从 ojdkbuild 下载一个版本

参见

有关Godot的SCons用法的一般概述,请参阅 构建系统介绍

设置构建系统

将环境变量 ANDROID_HOME 指向Android SDK。如果您下载了Android命令行工具,那么这将是您解压缩ZIP存档内容的文件夹。稍后,gradlew 将在此文件夹中安装必要的SDK组件。但是,您需要接受SDK组件许可证才能通过Gradle下载。这可以通过从SDK目录的根目录运行以下命令,然后用 y 回答所有提示来完成:

tools/bin/sdkmanager --licenses

设置环境变量 ANDROID_NDK_ROOT 指向Android NDK。您还可能需要将变量 ANDROID_NDK_HOME 设置为相同的路径,尤其是在使用自定义Android模块的情况下,因为某些Gradle插件依赖NDK并使用此变量来确定其位置。

要在Windows上设置这些环境变量,请按 Windows + R,键入“控制系统”,然后单击左窗格中的 高级系统设置 ,然后在出现的窗口中单击 环境变量

要在Linux或macOS上设置这些环境变量,请使用 export ANDROID_HOME=/path/to/android-sdkexport ANDROID_NDK_ROOT=/path/to/android-ndk,其中 /path/to/android-sdk/path/to/android-ndk 是Android SDK和Android NDK目录的根路径。

构建导出模板

Godot需要两个Android导出模板:优化的“发布”模板(android_release.apk)和调试模板(android_debug.apk)。 由于Google将要求所有APK从2019年8月开始包含ARMv8(64位)库,因此以下命令将构建包含ARMv7和ARMv8库的APK。

通过使用以下参数调用SCons来完成标准导出模板的编译:

  • 发布模板(在导出时未选中“启用调试”的情况下使用)
scons platform=android target=release android_arch=armv7
scons platform=android target=release android_arch=arm64v8
cd platform/android/java
# On Windows
.\gradlew generateGodotTemplates
# On Linux and macOS
./gradlew generateGodotTemplates

生成的APK将位于 bin/android_release.apk

  • 调试模板(用于在导出时选中“启用调试”的情况下使用)
scons platform=android target=release_debug android_arch=armv7
scons platform=android target=release_debug android_arch=arm64v8
cd platform/android/java
# On Windows
.\gradlew generateGodotTemplates
# On Linux and macOS
./gradlew generateGodotTemplates

生成的APK将位于 bin/android_debug.apk

添加对x86设备的支持

如果您还想包含对x86设备的支持,请在使用Gradle构建APK之前,第三次使用 android_arch=x86 参数运行Scons命令。 例如,对于发布模板:

scons platform=android target=release android_arch=armv7
scons platform=android target=release android_arch=arm64v8
scons platform=android target=release android_arch=x86
cd platform/android/java
# On Windows
.\gradlew generateGodotTemplates
# On Linux and macOS
./gradlew generateGodotTemplates

这将创建一个适用于所有平台的胖二进制文件。导出项目的最终APK大小取决于您在导出时选择支持的平台;换句话说,未使用的平台将从APK中删除。

Cleaning the generated export templates

You can use the following commands to remove the generated export templates:

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

使用导出模板

作为Android的导出模板,Godot需根据与编辑器相同的版本/提交编译发布版和调试版APK。如果您使用官方二进制文件作为编辑器,请确保安装匹配的导出模板,或者从相同版本构建自己的模板。

导出游戏时,Godot将打开APK,更改其中的一些内容并添加文件。

安装模板

新编译的模板(android_debug.apkandroid_release.apk)必须使用各自的名称复制到Godot的模板文件夹中。模板文件夹可以位于:

  • Windows: %APPDATA%\Godot\templates\<version>\
  • Linux: $HOME/.local/share/godot/templates/<version>/
  • macOS: $HOME/Library/Application Support/Godot/templates/<version>/

<version> 的格式为 major.minor[.patch].status ,使用Godot源代码库中 version.py 的值(例如 3.0.5.stable3.1.dev)。您还需要将此相同的版本字符串写入到导出模板旁边的 version.txt 文件中。

但是,如果要编写自定义模块或自定义C++代码,则可能需要在此处将APK配置为自定义导出模板:

../../_images/andtemplates.png

您甚至不需要复制它们,只需引用在Godot源文件夹的 bin\ 目录中生成的文件,因此下次构建时,将自动引用自定义模板。

故障排除

应用程序未安装

Android可能会抱怨该应用程序未正确安装。 如果是这样的话:

  • 检查是否正确生成了调试密钥库。
  • 检查jarsigner可执行文件是否来自JDK 8。

如果仍然失败,请打开命令行并运行 logcat

adb logcat

然后在安装应用程序时检查输出;错误消息应该在此处显示。 如果无法解决,请寻求帮助。

应用程序秒退

如果应用程序运行但秒退,则可能是以下原因之一:

  • 确保使用与您的编辑器版本匹配的导出模板;如果您使用的是新版Godot,则还 必须 更新模板。
  • libgodot_android.so 不在 libs/<android_arch>/ 中,其中 <android_arch> 是设备的架构。
  • 设备的体系结构与导出的体系结构不匹配。确保您的模板是针对该设备的体系结构构建的,并且导出设置包括对该体系结构的支持。

无论如何,adb logcat 也应显示错误原因。