Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

為 Android 匯出

也參考

這個頁面描述的是如何將 Godot 專案匯出到 Android。如果你想要找的是從源碼編譯編輯器或匯出範本二進位檔案,請閱讀 為 Android 進行編譯

匯出至 Android 的需求比為 Android 編譯 Godot 還來得少。下列為設定 SDK 與 Godot 所需的詳細步驟。

注意

Projects written in C# can be exported to Android as of Godot 4.2, but support is experimental and some limitations apply.

Install OpenJDK 17

Download and install OpenJDK 17.

下載 Android SDK

下載與安裝 Android SDK。

  • 可以從 Android Studio 上下載並安裝 Android Studio。

    • 依照這裡的 指示 執行一次 Android Studio 來完成設定 SDK。

    • 請確保有一併安裝 必要的套件

      • Android SDK Platform-Tools 30.0.5 或更高版本

      • Android SDK Build-Tools version 33.0.2

      • Android SDK Platform 33

      • 安裝 Android SDK (命令行版本)

      • CMake 版本 3.10.2.4988404

      • NDK 版本 r23c(23.2.8568313)

  • 可以通過 命令行工具 來安裝。

    • 安裝好命令行工具後,執行 sdkmanager 指令來完成安裝程式:

sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;33.0.2" "platforms;android-33" "cmdline-tools;latest" "cmake;3.10.2.4988404" "ndk;23.2.8568313"

備註

如果你使用的是 Linux,請勿使用發行版本軟體庫提供的 Android SDK,因為它通常是過時的

建立 debug.keystore

必須有除錯用金鑰儲存區,才可在 Android 上將非發行版本的 APK 安裝到裝置上。若曾使用過 SDK 且曾建置過專案,則 ant 或 eclipse 可能有自動產生過金鑰儲存區 (在 Linux 與 macOS 上,可以在 ~/.android 目錄中找到,Windows 上則在 C:\Users\<使用者>\.android\ 目錄中)。

若找不到金鑰儲存區或需要產生,則可以使用 JDK 中的 keytool 指令:

keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999 -deststoretype pkcs12

This will create a debug.keystore file in your current directory. You should move it to a memorable location such as %USERPROFILE%\.android\, because you will need its location in a later step. For more information on keytool usage, see this Q&A article.

備註

金鑰庫和金鑰的密碼必須相同,這一點很重要。這是一個“已知的 Android studio 問題 <https://developer.android.com/studio/known-issues#ki-key-keystore-warning>”,也會影響 Godot 專案。

在 Godot 中設定

開啟 [編輯器設定] 畫面。該畫面中包含了用於該電腦上目前使用者帳號的設定 (編輯器設定獨立於專案)。

../../_images/editorsettings.png

下拉至 Android 設定的部分:

../../_images/androidsdk.png

在此畫面中,需要設定 2 個路徑:

  • Android Sdk Path 應設為 Android SDK 安裝的位置。—— 如 Windows 上可能是 %LOCALAPPDATA%\Android\Sdk\ ,macOS 上可能是 /Users/$USER/Library/Android/sdk/

  • 除錯用的 .keystore 檔案 - 可以剛才建立並放置 debug.keystore 檔案的資料夾中找到。

設定好了之後,就準備好能匯出到 Android 了!

備註

如果你遇到 “Could not install to device” 的錯誤,請確認裝置上未安裝使用了相同Android包名(但使用不同金鑰進行簽章)的應用。

如果裝置上安裝了 Android 包名相同但簽章金鑰不同的應用,你**必須**先在該 Android 裝置詢問時選擇刪除該應用,但後再重新匯出到 Android。

提供起動器圖示

啟動器圖示是給 Android 起動器應用程式將程式顯示給使用者看的圖示。Godot 中只需要提供高解析度圖示 (用於 xxxhdpi 密度螢幕),就會自動產生各個低解析度的版本。

Godot 中需要的圖示有兩種型別:

  • 主圖示: 即「經典」的圖示。會用於最高至 Android 8 (Orea) 的 Android 版本。必須至少有 192×192 px。

  • 調適性圖示: 自 Android 8 版 (不含) 開始開始引入了 調適性圖示 (英文) 。應用程式需要包含分開的背景與前景圖示來提供原生外觀。使用者的起動器會控制圖示的動畫與遮罩。必須至少有 432×432 px。

也參考

在設計調適性圖示時,遵守一些規則也很重要。Google Design 發表了一篇很棒的文章 (英文) ,有助於瞭解這些規則以及調適性圖示的一些限制。

警示

調適性圖示設計規則中最重要的一點是要將圖示的關鍵元素放在安全區域內,即為正中間有直徑 66dp 的圓圈 (xxxhdpi 下為 264 像素),才可避免圖示被起動器給剪裁。

若不提供需要的圖示,則 Godot 會自動在遞補鏈中以下一個專案來代替,當遞補鏈中目前專案失敗時,則往下遞補:

  • Main Icon: 提供的主圖示 -> 專案圖示 -> 預設 Godot 主圖示。

  • Adaptive Icon Foregrond: 提供的前景圖示 -> 提供的主圖示 -> 專案圖示 -> 預設 Godot 前景圖示。

  • Adaptive Icon Background: 提供的背景圖示 -> 預設 Godot 背景圖示。

強烈建議提供所有需要的圖示,並至少要有指定的解析度。只有這樣才能讓應用程式在所有 Android 裝置與版本中看起來好看。

為 Google Play Store 匯出

要將 APK 上傳至 Google Play Store 需要以非除錯用金鑰儲存區來簽署 APK。該檔案可如此產生:

keytool -v -genkey -keystore mygame.keystore -alias mygame -keyalg RSA -validity 10000

該金鑰儲存區會用來驗證開發人員身份,請記住密碼並保存在安全處!請在 Google 的 Android 開發人員指南中瞭解有關 簽署 APK 的詳情。

接著在 Android 匯出預設中填寫下列表格:

../../_images/editor-export-presets-android.png
  • Release: 輸入剛才產生的金鑰儲存區檔案位置。

  • Release User: 以金鑰別名取代。

  • Release Password: 金鑰密碼,請注意,目前金鑰儲存區密碼與金鑰的密碼必須相同。

設定 APK 名稱時也別忘了取消勾選 [Export With Debug] 勾選框。

../../_images/export-with-debug-button.png

最佳化 APK 大小

預設情況下,APK 會同時包含 ARMv7 與 ARMv8 架構的原生函式庫。這樣一來會大幅增加檔案大小。要建立比較小的 APK,請於專案 Android 匯出預設中取消勾選 Armeabi-v 7aArm 64 -v 8a。這樣產生的 APK 只會包含單一架構的函式庫。請注意,為 ARMv7 所製作的應用程式一樣可以在 ARMv8 裝置上執行,但反過來則不行。

自 2019 年 8 月起,Google Play 中所有的應用程式都必須支援 64 位元。這表示無法上傳裡面 只有 ARMv7 函式庫的 APK。為此,可以通過 多 APK 支援 來上傳多個 APK 到 Google Play 上。每個 APK 都應至為單一重架建構置。為 ARMv7 與 ARMv8 建立 APK 應該可涵蓋當今大多數的裝置。

還可以進一步通過編譯只有所需功能的 Android 匯出樣板來進一步最佳化大小。更多資訊請參考 最佳化建置檔案大小

環境變數

您可以使用下列環境變數在編輯器外部設定匯出選項。在匯出過程中,這些值會覆寫您在匯出選單中設定的值。

Android匯出環境變數

匯出選項

環境變數

加密/加密金鑰

GODOT_SCRIPT_ENCRYPTION_KEY

選項/金鑰庫/除錯

GODOT_ANDROID_KEYSTORE_DEBUG_PATH

選項/金鑰庫/除錯使用者

GODOT_ANDROID_KEYSTORE_DEBUG_USER

選項/金鑰庫/除錯密碼

GODOT_ANDROID_KEYSTORE_DEBUG_PASSWORD

選項/金鑰庫/發布

GODOT_ANDROID_KEYSTORE_RELEASE_PATH

選項/金鑰庫/釋放使用者

GODOT_ANDROID_KEYSTORE_RELEASE_USER

選項/金鑰庫/釋放密碼

GODOT_ANDROID_KEYSTORE_RELEASE_PASSWORD