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

  • SCons 4.0+ build system.

  • Android SDK (достатньо інструментів командного рядка).

    • Необхідні компоненти SDK будуть встановлені автоматично.

    • У Linux не використовуйте Android SDK, наданий у сховищах вашого дистрибутива, оскільки він часто буде застарілим.

    • У macOS не використовуйте Android SDK від Homebrew, оскільки його не буде встановлено в єдиному місці.

  • Gradle (буде завантажено та встановлено автоматично, якщо його немає).

  • JDK 17 (або OpenJDK, або Oracle JDK).

    • Ви можете завантажити збірку з Adoptium.

Дивись також

Щоб отримати вихідний код Godot для компіляції, перегляньте Отримання джерела.

Для загального огляду використання SCons для Godot див. Знайомство з системою побудови.

Налаштування системи збірки

  • Установіть змінну середовища ANDROID_HOME так, щоб вона вказувала на Android SDK. Якщо ви завантажили інструменти командного рядка Android, це буде папка, куди ви розпакували вміст ZIP-архіву.

    • Windows: натисніть Windows + R, введіть «система керування», потім натисніть Додаткові параметри системи на лівій панелі, а потім натисніть Змінні середовища у вікні, що з’явиться.

    • Linux або macOS: додайте текст export ANDROID_HOME="/path/to/android-sdk" до .bashrc або .zshrc, to/path/to/android-sdk `` вказує на корінь каталогів SDK.

  • Встановіть необхідні компоненти 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"

  • Після налаштування SDK і змінних середовища обов’язково перезапустіть термінал, щоб застосувати зміни. Якщо ви використовуєте IDE із вбудованим терміналом, вам потрібно перезапустити IDE.

  • Запустіть scons platform=android. Якщо це не вдається, поверніться назад і перевірте кроки. Якщо ви виконали налаштування правильно, NDK почне завантаження. Якщо ви намагаєтеся скомпілювати GDExtension, вам потрібно спочатку скомпілювати механізм, щоб завантажити NDK, а потім ви зможете скомпілювати GDExtension.

Створення шаблонів експорту

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

Компіляція стандартних шаблонів експорту здійснюється шляхом виклику SCons із кореневого каталогу Godot із такими аргументами:

  • Шаблон випуску (використовується під час експорту зі знятим прапорцем Debugging Enabled)

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

  • Шаблон налагодження (використовується під час експорту з прапорцем Налагодження ввімкнено)

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

  • (Optional) Dev template (used when troubleshooting)

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

The resulting templates will be located under the bin directory:

  • bin/android_release.apk for the release template

  • bin/android_debug.apk for the debug template

  • bin/android_dev.apk for the dev template

  • bin/android_source.zip for the Gradle build template

Примітка

  • 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 the template files are generated after the build.

  • To include debug symbols in the generated templates, add the debug_symbols=yes parameter to the SCons command.

Дивись також

Якщо ви хочете ввімкнути шари перевірки Vulkan, перегляньте Шари перевірки Vulkan на Android.

Додано підтримку пристроїв x86

Якщо ви також хочете включити підтримку для пристроїв x86 і x86_64, запустіть команду SCons втретє та вчетверте з аргументами arch=x86_32 і arch=x86_64 перед створенням APK за допомогою Gradle. Наприклад, для шаблону випуску:

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

This will create template binaries that works on all platforms. The final binary size of exported projects will depend on the platforms you choose to support when exporting; in other words, unused platforms will be removed from the binary.

Очищення створених шаблонів експорту

Щоб видалити згенеровані шаблони експорту, можна скористатися такими командами:

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

Використання шаблонів експорту

Godot needs release and debug binaries that were compiled against the same version/commit as the editor. If you are using official binaries for the editor, make sure to install the matching export templates, or build your own from the same version.

When exporting your game, Godot uses the templates as a base, and updates their content as needed.

Встановлення шаблонів

The newly-compiled templates (android_debug.apk , android_release.apk, and android_source.zip) must be copied to Godot's templates folder with their respective names. The templates folder can be located in:

  • Windows: %APPDATA%\Godot\export_templates\<версія>\

  • Linux: $HOME/.local/share/godot/export_templates/<версія>/

  • macOS: $HOME/Library/Application Support/Godot/export_templates/<version>/

<version> має форму major.minor[.patch].status, використовуючи значення з version.py у вашому вихідному репозиторії Godot (наприклад, 4.1.3.stable або 4.2.dev). Вам також потрібно записати цей самий рядок версії у файл version.txt, розташований поруч із вашими шаблонами експорту.

However, if you are writing your custom modules or custom C++ code, you might instead want to configure your template binaries as custom export templates here:

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

Вам навіть не потрібно копіювати їх, ви можете просто посилатися на отриманий файл у каталозі bin\ вихідної папки Godot, щоб наступного разу, коли ви створите, ви автоматично матимете посилання на спеціальні шаблони.

Створення редактора Godot

Компіляція редактора виконується викликом SCons із кореневого каталогу Godot із такими аргументами:

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 add the dev_build=yes parameter to generate a dev build of the Godot editor.

  • You can add the debug_symbols=yes parameter to include the debug symbols in the generated build.

  • 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 binaries are generated after the build.

The resulting binaries will be located under bin/android_editor_builds/.

Removing the Editor binaries

You can use the following commands to remove the generated editor binaries:

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

Installing the Godot editor APK

На пристрої Android із увімкненими параметрами розробника під’єднайте пристрій Android до комп’ютера за допомогою зарядного кабелю до порту USB/USB-C. Відкрийте термінал/командний рядок і виконайте такі команди з кореневого каталогу з такими аргументами:

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

Вирішення проблем

Платформа не відображається в SCons

Ще раз перевірте, чи встановлено змінну середовища ANDROID_HOME. Це потрібно, щоб платформа з’явилася в списку виявлених платформ SCons. Перегляньте Налаштування системи збірки для отримання додаткової інформації.

Програма не встановлена

Android може скаржитися, що програму встановлено неправильно. Якщо так:

  • Перевірте, чи правильно згенеровано сховище ключів налагодження.

  • Переконайтеся, що виконуваний файл jarsigner належить до JDK 8.

Якщо це все одно не вдається, відкрийте командний рядок і запустіть logcat:

adb logcat

Потім перевірте результат під час встановлення програми; там повинно бути представлено повідомлення про помилку. Зверніться по допомогу, якщо ви не можете це зрозуміти.

Програма негайно завершує роботу

Якщо програма запускається, але негайно завершує роботу, це може бути спричинено однією з таких причин:

  • Обов’язково використовуйте шаблони експорту, які відповідають вашій версії редактора; якщо ви використовуєте нову версію Godot, ви також повинні оновити шаблони.

  • libgodot_android.so не міститься в libs/<arch>/, де <arch> – це архітектура пристрою.

  • Архітектура пристрою не збігається з експортованим(ими). Переконайтеся, що ваші шаблони створено для архітектури цього пристрою, а параметри експорту включали підтримку цієї архітектури.

У будь-якому випадку adb logcat має також показати причину помилки.