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

  • SCons 4.4+ build system.

  • Android SDK

    • To install the Android SDK, follow the steps here.

    • У 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 і змінних середовища обов’язково перезапустіть термінал, щоб застосувати зміни. Якщо ви використовуєте IDE із вбудованим терміналом, вам потрібно перезапустити IDE.

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

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

Godot потребує трьох шаблонів експорту для Android: оптимізований шаблон «випуску» (android_release.apk), шаблон налагодження (android_debug.apk) і шаблон збірки Gradle (android_source.zip). Оскільки з серпня 2019 року Google вимагає, щоб усі APK містили бібліотеки ARMv8 (64-розрядні), наведені нижче команди створюють шаблони, що містять бібліотеки ARMv7 і ARMv8.

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

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

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

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

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

Отримані шаблони будуть розташовані в каталозі bin:

  • bin/android_release.apk для шаблону випуску

  • bin/android_debug.apk для шаблону налагодження

  • bin/android_source.zip для шаблону збірки Gradle

Примітка

  • Якщо ви змінюєте список архітектур, які створюєте, не забудьте додати generate_android_binaries=yes до останньої архітектури, яку ви створюєте, щоб файли шаблонів генерувалися після збірки.

  • To enable dev build (for use when troubleshooting) in the generated templates, add the dev_build=yes parameters to the SCons command.

  • Щоб включити символи налагодження до згенерованих шаблонів, додайте параметри debug_symbols=yes до команди SCons.

    • Зверніть увагу, що ви можете включити separate_debug_symbols=yes для генерації символів налагодження в окремому файлі *-native-debug-symbols.zip.

Дивись також

Якщо ви хочете ввімкнути шари перевірки Vulkan, перегляньте Vulkan validation layers on 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_android_binaries=yes

Це створить двійкові файли шаблону, які працюють на всіх платформах. Остаточний двійковий розмір експортованих проектів залежатиме від платформ, які ви вирішите підтримувати під час експорту; іншими словами, невикористовувані платформи буде видалено з двійкового файлу.

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

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

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

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

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

Експортуючи вашу гру, Godot використовує шаблони як основу та за потреби оновлює їхній вміст.

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

Щойно скомпільовані шаблони (android_debug.apk, android_release.apk і android_source.zip) потрібно скопіювати до папки шаблонів Godot з відповідними назвами. Папку з шаблонами можна розмістити в:

  • 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, розташований поруч із вашими шаблонами експорту.

Однак, якщо ви пишете власні модулі або власний код C++, можливо, вам варто налаштувати бінарні файли шаблонів як власні шаблони експорту в меню експорту проекту. Щоб налаштувати це, потрібно ввімкнути Додаткові параметри.

../../../_images/andtemplates.webp

Вам навіть не потрібно копіювати їх, ви можете просто посилатися на отриманий файл у каталозі 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_android_binaries=yes

  • Ви можете додати параметр dev_build=yes, щоб створити розробну збірку редактора Godot.

  • Ви можете додати параметри debug_symbols=yes, щоб включити символи налагодження у згенеровану збірку.

    • Зверніть увагу, що ви можете додати separate_debug_symbols=yes до останньої архітектури, яку ви будуєте, щоб згенерувати символи налагодження в окремому файлі *-native-debug-symbols.zip.

  • Ви можете пропустити певні архітектури залежно від вашого цільового пристрою, щоб пришвидшити компіляцію.

Не забудьте додати generate_android_binaries=yes до останньої архітектури, яку ви збираєте, щоб бінарні файли генерувалися після збірки.

Отримані двійкові файли будуть розташовані в папці bin/android_editor_builds/.

Видалення двійкових файлів редактора

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

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

Встановлення APK редактора Godot

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

adb install ./bin/android_editor_builds/android_editor-android-debug.apk

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

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

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

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

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

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

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

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

adb logcat

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

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

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

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

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

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

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