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

为 Android 平台编译

参见

这个页面描述的是如何从源码编译 Android 导出模板二进制。如果你想要找的是导出项目到 Android，请阅读 为 Android 导出。

注意

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

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

需求

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

  • Python 3.6+.

  • SCons 3.1.2+ build system.

  • Android SDK (命令行工具就足够了).

    • 所需的 SDK 组件将被自动安装。

    • 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（如果缺少，将自动下载并安装）。

  • JDK 17 (either OpenJDK or Oracle JDK).

    • You can download a build from Adoptium.

参见

要获取编译所需的 Godot 源码，请参阅 获取源代码。

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

设置构建系统

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

  • 在此文件夹中安装必要的SDK组件:

    • 通过运行以下命令接受SDK组件许可证, 其中 android_sdk_path 是android SDK的路径, 然后用 y 回答所有提示:

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

    • 运行以下命令完成安装, 其中 android_sdk_path 是Android SDK的路径.

    cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;34.0.0" "platforms;android-34" "cmdline-tools;latest" "cmake;3.10.2.4988404" "ndk;23.2.8568313"

  • After setting up the SDK and environment variables, be sure to restart your terminal to apply the changes. If you are using an IDE with an integrated terminal, you need to restart the IDE.

  • Run scons platform=android. If this fails, go back and check the steps. If you completed the setup correctly, the NDK will begin downloading. If you are trying to compile GDExtension, you need to first compile the engine to download the NDK, then you can compile GDExtension.

构建导出模板

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

编译标准导出模板的方法是在Godot根目录下调用SCons, 参数如下:

  • 发布模板(在导出时未选中 "启用调试" 的情况下使用)

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

备注

If you are changing the list of architectures you're building, remember to add generate_apk=yes to the last architecture you're building, so that an APK file is generated after the build.

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

  • 调试模板(用于在导出时选中 "启用调试" 的情况下使用)

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

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

参见

如果你想启用 Vulkan 验证层，查看 Vulkan validation layers on Android。

添加对 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_apk=yes

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

清理生成的导出模板

你可以使用以下命令删除生成的导出模板:

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

使用导出模板

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

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

安装模板

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

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

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

../../../_images/andtemplates.png

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

构建 Godot 编辑器

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_apk=yes

You can skip certain architectures depending on your target device to speed up compilation. Remember to add generate_apk=yes to the last architecture you're building, so that an APK file is generated after the build.

The resulting APK will be located at bin/android_editor_builds/android_editor-release.apk.

移除编辑器模板

你可以使用以下命令移除生成的编辑器模板：

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

安装 Godot 编辑器

在启用了开发者选项的 Android 设备上，通过 USB/USB-C 端口的充电线将 Android 设备连接到你的计算机。打开终端/命令提示符并在根目录使用以下参数运行命令：

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

故障排除

平台未在 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.

应用程序未安装

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

  • 检查是否正确生成了调试密钥库。

  • 检查jarsigner可执行文件是否来自JDK 8.

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

adb logcat

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

应用程序秒退

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

  • 确保使用与你的编辑器版本匹配的导出模板；如果你使用的是新版Godot, 则还 必须 更新模板.

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

  • 设备的体系结构与导出的体系结构不匹配. 确保你的模板是针对该设备的体系结构构建的, 并且导出设置包括对该体系结构的支持.

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