Read this manual in English

Разработка для Android

Устройства Android позволяют свободно запускать на них собственные приложения. Очень легко создать версию вашей игры и скопировать ее на устройство Android. В этом руководстве описаны шаги, связанные с созданием вашей игры для Android. В процессе разработки рекомендуется запускать игру через development app, так как оно позволяет осуществлять горячую перезагрузку контента и кода по беспроводной связи прямо на устройство.

Android и процесс подписания Google Play

Android требует, чтобы все APK были подписаны цифровым сертификатом перед установкой на устройство или обновлением. Если вы используете Android App Bundles, вам нужно подписать только ваш пакет приложений перед загрузкой в Play Console, а Play App Signing позаботится обо всем остальном. Однако вы также можете вручную подписать свое приложение для загрузки в Google Play, других магазинов приложений и для распространения вне магазинов.

При создании пакета Android-приложений в редакторе Defold или с помощью development app, вы можете указать файл keystore (содержащий ваш сертификат и ключ) и пароль keystore, который будет использоваться при подписании вашего приложения. Если вы этого не сделаете, Defold создаст отладочное keystore и будет использовать его при подписании пакета приложений.

Создание хранилища ключей

Вы можете создать хранилище ключей с помощью Android Studio или из терминала/командной строки:

keytool -genkey -v -noprompt -dname "CN=John Smith, OU=Area 51, O=US Air Force, L=Unknown, ST=Nevada, C=US" -keystore mykeystore.keystore -storepass 5Up3r_53cR3t -alias myAlias -keyalg RSA -validity 9125

В результате будет создан файл keystore с именем mykeystore.keystore, содержащий ключ и сертификат. Доступ к ключу и сертификату будет защищен паролем 5Up3r_53cR3t. Ключ и сертификат будут действительны в течение 25 лет (9125 дней). Сгенерированные ключ и сертификат будут идентифицированы псевдонимом myAlias.

Создание пакета приложений для Android

Редактор позволяет легко создать отдельный пакет приложений для вашей игры. Перед созданием пакета вы можете указать, какую иконку (иконки) использовать для приложения, установить код версии и т.д. в game.project файл настроек проекта.

Для создания пакета выберите в меню Project ▸ Bundle... ▸ Android Application....

Если вы хотите, чтобы редактор автоматически создавал случайные отладочные сертификаты, оставьте поля Keystore и Keystore password пустыми:

Если вы хотите подписать свой пакет определенным хранилищем ключей, укажите Keystore и Keystore password. Ожидается, что Keystore будет иметь расширение файла .keystore, а пароль будет храниться в текстовом файле с расширением .txt:

Defold поддерживает создание файлов APK и AAB. Выберите APK или AAB из выпадающего списка Bundle Format.

Нажмите Create Bundle, когда вы настроите параметры пакета приложений. Затем вам будет предложено указать, где на вашем компьютере будет создан пакет.

Build variants

When you bundle a game, you need to choose what type of engine you wish to use. You have three basic options:

• Debug
• Release
• Headless

These different versions are also referred to as Build variants

Debug

This type of executable is typically used during development of a game as it has several useful debugging features included:

• Profiler - Used for gathering performance and usage counters. Learn how to use the profiler in the Profiling manual.
• Logging - The engine will log system information, warnings and errors when logging is enabled. The engine will also output logs from the Lua print() function and from native extensions logging using dmLogInfo(), dmLogError() and so on. Learn how to read these logs in the Game and System Logs manual.
• Hot reload - Hot-reload is a powerful feature which lets a developer reload resource while the game is running. Learn how to use this in the Hot-Reload manual.
• Engine services - It is possible to connect to and interact with a debug version of a game through a number of different open TCP ports and services. The services include the hot-reload feature, remote log access and the profiler mentioned above, but also other services to remotely interact with the engine. Learn more about the engine services in the developer documentation.

Release

This variant has the debugging features disabled. This options should be chosen when the game is ready to be released to the app store or in other ways shared with players. It is not recommended to release a game with the debugging features enabled for a number of reasons:

• The debugging features take up a little bit of size in the binary, and it is a best practice to try to keep the binary size of a released game as small as possible.
• The debugging features takes a little bit of CPU time as well. This can impact the performance of the game if a user has a low-end hardware. On mobile phones the increased CPU usage will also contribute to heating and battery drain.
• The debugging features may expose information about the game that is not intended for the eyes of the players, either from a security, cheating or fraud perspective.

Headless

This executable runs without any graphics and sound. It means that you can run the game unit/smoke tests on a CI server, or even have it as a game server in the cloud.

Установка пакета приложений для Android

Установка APK

Файл .apk можно скопировать на устройство с помощью инструмента adb (см. ниже) или в Google Play через консоль разработчика Google Play.

$ adb install Defold\ examples.apk
4826 КБ/с (18774344 байта за 3,798 с)
  pkg: /data/local/tmp/my_app.apk
Успех

Установка AAB

Файл .aab можно загрузить в Google Play через консоль разработчика Google Play. Также можно сгенерировать .apk файл из .aab файла для локальной установки с помощью Android bundletool.

Разрешения

Движок Defold требует ряд различных разрешений для работы всех функций движка. Разрешения определяются в AndroidManifest.xml, указанном в game.project файл настроек проекта. Подробнее о разрешениях Android можно прочитать в официальных документах. В манифесте по умолчанию запрашиваются следующие разрешения:

android.permission.INTERNET и android.permission.ACCESS_NETWORK_STATE (Уровень защиты: нормальный)

Позволяет приложениям открывать сетевые сокеты и получать доступ к информации о сетях. Эти разрешения необходимы для доступа в Интернет. (Android official docs) и (Android official docs).

android.permission.WRITE_EXTERNAL_STORAGE (Уровень защиты: опасный)

Позволяет приложению записывать данные во внешнее хранилище. Начиная с уровня API 19, это разрешение не требуется для чтения/записи файлов в специфических для вашего приложения каталогах, возвращаемых Context.getExternalFilesDir(String) и Context.getExternalCacheDir(). Это разрешение необходимо, если вы собираетесь сохранять/загружать файлы с диска (используя io.* или sys.save/load) за пределами папки, указанной sys.get_save_file() и имеете android:minSdkVersion, установленный уровень менее 19 в манифесте Android. (Официальные документы Android).

android.permission.WAKE_LOCK (Уровень защиты: нормальный)

Позволяет использовать блокировку PowerManager WakeLocks для предотвращения засыпания процессора или затемнения экрана. Это разрешение необходимо для временного предотвращения засыпания устройства при получении push-уведомления. (Официальные документы Android)

Android Debug Bridge

Инструмент командной строки adb - это простая в использовании и универсальная программа, которая используется для взаимодействия с устройствами Android. Вы можете загрузить и установить adb как часть Android SDK Platform-Tools, для Mac, Linux или Windows.

Загрузите Android SDK Platform-Tools с сайта: https://developer.android.com/studio/releases/platform-tools. Вы найдете инструмент adb в /platform-tools/. Также, пакеты для конкретной платформы можно установить через соответствующие менеджеры пакетов.

Ubuntu Linux:

$ sudo apt-get install android-tools-adb

Fedora 18/19:

$ sudo yum install android-tools

macOS (Homebrew)

$ brew cask install android-platform-tools

Вы можете убедиться, что adb работает, подключив устройство Android к компьютеру через USB и выполнив следующую команду:

$ adb devices
List of devices attached
31002535c90ef000    device

Если устройство не отображается, убедитесь, что на устройстве Android включена USB-отладка. Откройте Настройки устройства и найдите Опции разработчика (или Разработка).

Отладка пакета приложений

Пакет, собранный в режиме отладки (т.е. “Debug” выбран в качестве варианта при сборке), будет отправлять весь свой консольный вывод в системный журнал Android. Получите доступ к журналу с помощью инструмента adb и дайте команду logcat. Возможно, вы захотите отфильтровать вывод по тегу (-s [tagname]):

$ adb logcat -s "defold"
--------- beginning of /dev/log/system
--------- beginning of /dev/log/main
I/defold  ( 6210): INFO:DLIB: SSDP started (ssdp://192.168.0.97:58089, http://0.0.0.0:38637)
I/defold  ( 6210): INFO:ENGINE: Defold Engine 1.2.50 (8d1b912)
I/defold  ( 6210): INFO:ENGINE: Loading data from:
I/defold  ( 6210): INFO:ENGINE: Initialised sound device 'default'
I/defold  ( 6210):
D/defold  ( 6210): DEBUG:SCRIPT: Hello there, log!
...

Использование AndroidX

AndroidX - это значительное улучшение оригинальной библиотеки поддержки Android, которая больше не поддерживается. Пакеты AndroidX полностью заменяют библиотеку поддержки, предоставляя паритет возможностей и новые библиотеки. Большинство расширений Android на портале ассетов поддерживают AndroidX. Если вы не хотите использовать AndroidX, вы можете отключить его в пользу старой библиотеки поддержки Android:

1. Если у вас уже есть манифест приложения, добавьте jetifier: false в armv7-android и arm64-android.

2. Если у вас нет файла манифеста приложения, перейдите по ссылке Defold App Manifest generator и установите флажок “Use Android Support lib”.

FAQ

Q: Is it possible to hide the navigation and status bars on Android?

A: Yes, set the immersive_mode setting in the Android section of your game.project file. This lets your app take over the whole screen and capture all touch events on the screen.

Q: Why am I’m getting “Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]” when installing a Defold game on device?

A: Android detects that you try to install the app with a new certificate. When bundling debug builds, each build will be signed with a temporary certificate. Uninstall the old app before installing the new version:

$ adb uninstall com.defold.examples
Success
$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
      pkg: /data/local/tmp/Defold examples.apk
Success

Q: Why am I getting errors about conflicting properties in AndroidManifest.xml when building with certain extensions?

A: This can happen when two or more extensions provide an Android Manifest stub containing the same property tag but with different values. This has for instance happened with Firebase and AdMob. The build error looks similar to this:

SEVERE: /tmp/job4531953598647135356/upload/AndroidManifest.xml:32:13-58
Error: Attribute property#android.adservices.AD_SERVICES_CONFIG@resource
value=(@xml/ga_ad_services_config) from AndroidManifest.xml:32:13-58 is also
present at AndroidManifest.xml:92:13-59 value=(@xml/gma_ad_services_config).
Suggestion: add 'tools:replace="android:resource"' to <property> element at
AndroidManifest.xml to override. 

You can read more about the issue and the workaround in reported Defold issue #9453 and Google issue #327696048.