為 Android 進行編譯

請注意

在大多數情況下,使用內建的部署工具與匯出樣板就勾勒。手動編譯 Android APK 通常適用於自定建置或為部署工具自定套件的情況。

另外,在建置自定匯出樣板前,依然必須依照 為 Android 匯出 中所提到的步驟進行。

系統需求

要在 Windows, Linux 或 macOS 下進行編譯,則必須滿足下列條件:

  • Python 3.5+

  • SCons 3.0+ 建置系統。

  • Android SDK (命令行工具即可)。

    • Required SDK components will be automatically installed.

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

  • Gradle (若尚未安裝,會自動下載並安裝)。

  • JDK 8 (OpenJDK 或 Oracle JDK 擇一)。

    • JDK 9 或更新版本目前尚不支援。

    • 可以從 ojdkbuild 中下載。

也參考

有關配合 Godot 使用 SCons 的一般說明,請參考 建置系統簡介

設定建置系統

  • Set the environment variable ANDROID_SDK_ROOT 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.

  • Install the necessary SDK components in this folder:

    • Accept the SDK component licenses by running the following command where android_sdk_path is the path to the Android SDK, then answering all the prompts with y:

    tools/bin/sdkmanager --sdk_root=<android_sdk_path> --licenses
    
    • Complete setup by running the following command where android_sdk_path is the path to the Android SDK.

    tools/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;30.0.3" "platforms;android-29" "cmdline-tools;latest" "cmake;3.10.2.4988404"
    

也參考

To set the environment variable 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.

也參考

To set the environment variable on Linux or macOS, use export ANDROID_SDK_ROOT=/path/to/android-sdk where /path/to/android-sdk points to the root of the SDK directories.

建置匯出樣板

Godot 會需要兩個 Android 匯出樣板:一個經過最佳化的「release」樣板 (android_release.apk) 以及除錯樣板 (android_debug.apk)。由於 Google 自 2019 年八月開始要求所有 APK 都必須包含 ARMv8 (64 位元) 函式庫,因此下方的指令會建置同時包含 ARMv7 與 ARMv8 函式庫的 APK。

可以通過在 Godot 根目錄以下列引數來呼叫 SCons 來編譯標準匯出樣板:

  • 釋出樣板 (用於匯出時有勾選 Debugging Enabled 時)

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

  • 除錯樣板 (用於匯出時有勾選 Debugging Enabled 時)

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 與 x86-64 裝置的支援,則請在使用 Gradle 建置 APK 前以 android_arch=x86android_arch=x86_64 引數來執行第三次與第四次 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
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 中被移除。

清理產生的匯出樣板

可以使用下列指令來移除產生的匯出樣板:

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

使用匯出樣板

Godot 需要使用與編輯器相同版本/Commit 編譯的釋出與除錯 APK。若使用官方的編輯器執行檔,請確定與安裝的匯出樣板版本相同,或是自行以相同的版本建置。

匯出遊戲時,Godot 會開啟 APK,並在 APK 內部修改一些東西,然後加上專案檔案。

安裝樣板

必須將新編譯的樣板 (android_debug.apk and android_release.apk) 複製到 Godot 的樣板路徑中,並命名為對應的名稱。樣板資料夾位於:

  • Windows: %APPDATA%\Godot\templates\<版本>\

  • Linux: $HOME/.local/share/godot/templates/<版本>/

  • macOS: $HOME/Library/Application Support/Godot/templates/<版本>/

<版本> 的格式是與 Godot 原始碼儲存庫中 version.py 相同的值,為 major.minor[.patch].status 這樣的格式 (如 3.0.5.stable3.1.dev)。另外還必須在匯出樣板旁放置一個寫著相同版本的 version.txt 檔案。

但若你使用自定模組或自定 C++ 程式碼,可能需要在此處將自定匯出樣板設為自定 APK:

../../_images/andtemplates.png

這種情況下甚至不需要複製這些檔案,只需要將這些檔案參照至 Godot 原始碼目錄中的 bin\ 資料夾即可。這樣一來下次建置時就會自動參照到自定樣板。

疑難排解

SCons 中未顯示平台

Double-check that you've set the ANDROID_SDK_ROOT 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 可能會提示應用程式未正確安裝。這時:

  • 請檢查除錯 (Debug) 金鑰儲存區是否有正確產生。

  • 請檢查 jarsigner 執行檔是否為 JDK 8 中的。

若依然失敗,請開啟命令行並執行 logcat

adb logcat

接著在應用程式安裝時檢查輸出。錯誤訊息應該會顯示在此處。若無法解決,請尋找支援。

應用程式馬上退出

若應用程式可執行,但會馬上退出的話,可能是由於下列原因導致:

  • 請確保匯出樣板的版本符合編輯器版本。若使用較新的 Godot 版本,則 必須 一併更新樣板的版本。

  • libs/<android_arch>/ 中沒有 libgodot_android.so 。其中,<android_arch> 是裝置的架構。

  • 專案的架構與匯出樣板的架構不同。請確定有使用裝置的架構來建置樣板,並確認匯出設定有包含對該架構的支援。

不論哪種情況,adb logcat 應該也會顯示錯誤的原因。