为Android平台编译

注意

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

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

需求

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

  • Python 3.5+.
  • SCons 3.0+ build system.
  • Android SDK (command-line tools are sufficient).
    • Required SDK components will be automatically installed by Gradle (except the NDK).
  • Android NDK r17 or later.
  • Gradle (will be downloaded and installed automatically if missing).
  • JDK 8 (either OpenJDK or Oracle JDK).
    • JDK 9 or later are not currently supported.
    • You can download a build from 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并使用此变量来确定其位置。

To set those environment variables on 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或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。

Compiling the standard export templates is done by calling SCons from the Godot root directory with the following arguments:

  • 发布模板(在导出时未选中“启用调试”的情况下使用)
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设备的支持

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

scons platform=android target=release android_arch=armv7
scons platform=android target=release android_arch=arm64v8
scons platform=android target=release android_arch=x86
scons platform=android target=release android_arch=x86_64
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\ 目录中生成的文件,因此下次构建时,将自动引用自定义模板。

故障排除

Platform doesn't appear in SCons

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

应用程序未安装

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

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

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

adb logcat

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

应用程序秒退

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

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

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