为Android平台编译

注意

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

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

需求

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

  • Python 3.5+.
  • SCons 3.0+ 构建系统。
  • 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 回答所有提示来完成：

  1. 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-sdk 和 export 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:

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

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

  • 调试模板（用于在导出时选中“启用调试”的情况下使用）
  1. scons platform=android target=release_debug android_arch=armv7
  2. scons platform=android target=release_debug android_arch=arm64v8
  3. cd platform/android/java
  4. # On Windows
  5. .\gradlew generateGodotTemplates
  6. # On Linux and macOS
  7. ./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:

  1. scons platform=android target=release android_arch=armv7
  2. scons platform=android target=release android_arch=arm64v8
  3. scons platform=android target=release android_arch=x86
  4. scons platform=android target=release android_arch=x86_64
  5. cd platform/android/java
  6. # On Windows
  7. .\gradlew generateGodotTemplates
  8. # On Linux and macOS
  9. ./gradlew generateGodotTemplates

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

Cleaning the generated export templates

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

  1. cd platform/android/java
  2. # On Windows
  3. .\gradlew cleanGodotTemplates
  4. # On Linux and macOS
  5. ./gradlew cleanGodotTemplates

使用导出模板

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

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

安装模板

新编译的模板（android_debug.apk 和 android_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.stable 或 3.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：

  1. adb logcat

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

应用程序秒退

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

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

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