Android

Ren'Py поддерживает устройства под управлением операционной системы Android, такие как смартфоны и планшеты. Хотя эти устройства не поддерживают 100% функциональности Ren'Py, с минимальными изменениями визуальные новеллы можно упаковать и перенести на эти устройства.

RAPT – the Ren'Py Android Packaging Tool (Инструмент для сборки Android-пакетов Ren'Py) – это программа, загружаемая отдельно от Ren'Py, которая создаёт пакет Android для тестирования или релиза.

Ren'Py работает на Android 5.0 и выше, хотя более старым устройствам может не хватать ресурсов для корректной работы больших игр.

Правовая информация

Некоторые из библиотек, используемых RAPT, лицензируются на условиях GNU Lesser/Library General Public License. Вам потребуется соблюдать условия этой лицензии для распространения Ren'Py. Мы считаем, что включения следующего текста в описание вашего приложения будет достаточно, но для полной уверенности проконсультируйтесь с юристом.

Эта программа содержит свободное программное обеспечение, лицензированное по нескольким лицензиям, включая GNU Lesser General Public License. Полный список программного обеспечения доступен по адресу https://www.renpy.org/l/license/.

Инструкции для пользователя

Когда игра Ren'Py запущена на Android, работают следующие привязки клавиш:

Home

Возвращает на главный экран Android, приостанавливая игру Ren'Py. В процессе приостановки Ren'Py автоматически сохранит игру. При необходимости сохранение будет автоматически загружено, когда пользователь вернётся в игру.

Volume Up, Volume Down

Управляет громкостью медиа в Android.

Различия платформ

Существует много важных различий между сенсорной платформой Android и платформами с использованием мыши, которые поддерживает Ren'Py. Изменения, связанные с программным и аппаратным обеспечением Android:

  • Сенсорный экран рассматривается как мышь. Однако он будет генерировать события мыши только тогда, когда пользователь активно касается экрана.

  • Ввод текста (например, renpy.input()) ограничен методами ввода, которые не требуют для работы автодополнения. (Западные языки, вероятно, будут работать, в то время как другие языки могут не работать).

Кроме того, есть несколько изменений, которые могут потребоваться из-за человеческого фактора:

  • Поскольку смартфоны на Android могут быть меньше компьютерного монитора, может потребоваться увеличить размер текста.

  • Поскольку сенсорный ввод менее точен, чем ввод с помощью мыши, кнопки, рассчитанные на касание, должны быть больше, чем кнопки для мыши.

Чтобы помочь вам адаптироваться к этим различиям, Ren'Py для Android автоматически выбирает варианты экрана на основе размера экрана и возможностей устройства. Смотрите Варианты экранов для дополнительной информации.

Из-за политики безопасности мобильных устройств функциональность MultiPersistent ограничена только этой игрой и её обновлениями, т.е. она не может быть разделена с другой игрой.

Тестирование и эмуляция

Для целей тестирования Ren'Py поддерживает три режима эмуляции Android. Доступ к ним осуществляется с экрана Android в лаунчере.

Phone

Этот режим эмулирует телефон на Android. Эмуляция касания выполняется с помощью мыши, но только когда кнопка мыши зажата. Клавиша Escape назначена на кнопку меню, а Page Up — на кнопку «Назад».

Tablet

Этот режим эмулирует планшет на Android. Эмуляция касания выполняется с помощью мыши, но только когда кнопка мыши зажата. Клавиша Escape назначена на кнопку меню, а Page Up — на кнопку «Назад».

Television

Этот режим эмулирует Android-устройство телевизионного типа. Клавиатура сопоставляется с вводом с пульта или контроллера, а навигация осуществляется с помощью клавиш со стрелками. Enter — это выбор, Escape — меню, а Page Up — «Назад».

Этот режим также отображает оверлей, показывающий небезопасную для телевизора область. Содержимое в этой небезопасной области может отображаться не на всех телевизорах.

Хотя эти эмуляторы можно использовать для быстрого тестирования вашего проекта, лучше всего также проводить тестирование на реальном оборудовании. Эмуляторы не учитывают некоторые человеческие факторы, такие как размер пальцев пользователя.

Сборка Android-приложений

Ren'Py содержит инструменты, которые помогают вам применять ориентированный на сборку пакетов подход к разработке игр для Android. В этом подходе вы будете использовать ПК для сборки пакета Android и его загрузки на ваше устройство. Затем вы сможете запустить игру, как любое другое Android-приложение. Когда всё будет работать правильно, вы сможете загрузить созданный пакет в Google Play и другие магазины приложений.

Сборка Android-приложения состоит из пяти шагов:

  1. Скачайте и установите Java Development Kit и USB-драйверы для Android (ссылки ниже).

  2. Используйте лаунчер для установки Android SDK.

  3. Используйте лаунчер для генерации ключей.

  4. Используйте лаунчер для настройки сборки под Android.

  5. Используйте лаунчер для сборки Android-приложения.

После выполнения этих шагов у вас будет готовый к запуску пакет Android. Вам нужно будет выполнять шаг 3 только тогда, когда вы решите внести изменения в конфигурацию вашей игры или при настройке новой игры; шаг 5 вы будете выполнять чаще всего, когда вам потребуется создать новую сборку вашей игры.

Шаг 1: Установка зависимостей

Перед тем, как вы сможете собирать пакеты, вам может потребоваться вручную скачать и установить три компонента:

Java Development Kit. Java Development Kit (JDK) содержит несколько инструментов, используемых RAPT, включая инструменты для генерации ключей и подписи пакетов. Его можно скачать по ссылкам:

Вам понадобится JDK версии 21.

Обратите внимание, что ориентированный на разработчиков JDK отличается от ориентированного на пользователей JRE, и вам понадобится именно JDK для создания пакетов Android.

Android-устройство. Вам также потребуется настроить ваше устройство для разработки. Вам нужно будет включить режим разработчика на вашем устройстве и настроить ваш компьютер для разработки под Android. Инструкции по настройке компьютера можно найти по адресу:

Вы также можете запустить своё приложение в образе x86_64 в эмуляторе Android (обратите внимание, что x86 не поддерживается). Настройка эмулятора выходит за рамки этого документа.

Шаг 2: Настройка Android SDK и среды разработки

Следующий шаг — это настройка Android SDK и остальной среды разработки. Этот шаг выполнит следующее:

  • Проверит, что JDK установлен правильно.

  • Установит Android SDK.

  • Использует Android SDK для установки необходимых пакетов для разработки.

Этот шаг требует доступа к Интернету.

Чтобы выполнить этот шаг, выберите «Install SDK» на экране Android в лаунчере Ren'Py. RAPT будет сообщать о том, что он делает. Он также попросит вас принять лицензионные соглашения.

Если вы не хотите загружать SDK каждый раз, вы можете создать файл с именем sdk.txt, содержащий одну строку с путём к уже установленному SDK.

Шаг 3: Генерация ключей

После этого выберите «Generate Keys», чтобы сгенерировать ключи Android и Bundle для вашего пакета.

Предупреждение

Ключи, генерируемые RAPT, создаются со стандартной парольной фразой. Вы должны убедиться, что не потеряете доступ к этим файлам.

Вам следует хранить файлы android.keystore и bundle.keystore в безопасном месте. Вам также следует сделать их резервную копию, потому что без ключа вы не сможете загружать сгенерированные приложения.

Вы должны убедиться, что эти файлы никогда не станут общедоступными, особенно если используется система контроля версий.

При создании ключей Android Ren'Py создаст их резервную копию в том же месте, где хранятся резервные копии файлов скриптов. Это не заменяет создание ваших собственных резервных копий.

Шаг 4: Настройка вашей игры

Перед сборкой пакета вы должны предоставить Ren'Py некоторую информацию о сборке вашей игры для Android. Для этого выберите «Configure» на экране Android в лаунчере Ren'Py.

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

Шаг 5: Сборка и установка пакета

Наконец, вы можете собрать и установить пакет. Сначала вам нужно выбрать один из двух режимов релиза:

Play Bundle

Релизы в формате Play Bundle (Android App Bundle, AAB) подходят только для загрузки в магазин Google Play, хотя такие релизы также можно устанавливать на Android-устройства с поддержкой Play.

Размер Play Bundle может достигать 2 ГБ, но он разделяется на 4 файла пакетов быстрой загрузки по 500 МБ, и каждый файл вашей игры приписывается к одному из четырёх бандлов. Это может стать проблемой с распределением файлов — игра не сможет вместить 5 файлов по 300 МБ, так как для каждого из них будет место только в одном из четырёх файлов пакетов.

Universal APK

Релизы в формате Universal APK подходят для прямой установки на Android-устройства, либо через Ren'Py, ADB, сторонние магазины приложений или загрузку через веб.

Universal APK могут быть размером до 2 ГБ без ограничений по содержимому.

Существуют три команды, которые позволяют вам выполнять различные комбинации сборки пакета, его установки на ваше устройство и запуска приложения для тестирования.

Вам может потребоваться удалить приложение при переключении между режимами релиза.

Очень большие игры

Можно создавать игры размером более 2 ГБ. Это делается с помощью Загрузчик для больших игр на мобильных устройствах, при этом небольшая игра включается в Play Bundle или Universal APK, а остальная часть игры загружается с подходящего веб-сервера.

Иконка и изображения для предзагрузки

Иконка

Ren'Py создаст иконку для вашего приложения из двух файлов в базовой директории игры:

android-icon_foreground.png

Передний слой иконки. Должен быть размером 432x432 пикселя и прозрачным.

android-icon_background.png

Фоновый слой иконки. Должен быть размером 432x432 пикселя и непрозрачным.

Адаптивные иконки Android работают путём маскирования двух слоёв иконки в области, которая составляет не менее 132x132 пикселя в центре. Область за пределами этого безопасного пространства может отображаться, но также может быть обрезана. Выход за пределы безопасной области приветствуется. Два слоя могут немного смещаться относительно друг друга при перетаскивании иконки.

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

Обратите внимание, что 1dp соответствует 4 реальным пикселям.

При генерации приложения Ren'Py преобразует эти файлы в соответствующий размер для каждого устройства и создаст статичные иконки для устройств, которые не поддерживают адаптивные иконки.

Предзагрузочный экран (Presplash)

Предзагрузочный экран отображается до полной загрузки Ren'Py, перед началом основного сплэш-скрина. Это особенно важно на Android, так как при первом запуске Ren'Py распаковывает вспомогательные файлы, что может занять некоторое время.

android-presplash.jpg

Изображение, которое используется при загрузке приложения. Оно должно быть окружено рамкой толщиной 1 пиксель одного цвета. При отображении изображение масштабируется, чтобы соответствовать доступному пространству с сохранением соотношения сторон, а остальная часть экрана заполняется цветом рамки.

android-downloading.jpg

Изображение, которое используется, когда приложение загружает ассеты через Google Play Asset Delivery. Оно должно быть окружено рамкой толщиной 1 пиксель одного цвета. При отображении изображение масштабируется, чтобы соответствовать доступному пространству с сохранением соотношения сторон, а остальная часть экрана заполняется цветом рамки.

Индикатор выполнения высотой 20 пикселей отображается на расстоянии 20 пикселей от нижнего, левого и правого краёв экрана, показывая прогресс загрузки.

Pyjnius

При запуске на Android доступна версия библиотеки Pyjnius. Это позволяет опытным разработчикам обращаться к библиотекам Android.

Может потребоваться получить главную activity. Её можно найти в поле mActivity в классе org.renpy.android.PythonSDLActivity. Например:

init python:
    if renpy.android:
        import jnius
        mActivity = jnius.autoclass("org.renpy.android.PythonSDLActivity").mActivity
    else:
        mActivity = None

Разрешения

Хотя Ren'Py не требует дополнительных разрешений для работы, если ваша игра использует Pyjnius для вызова функций Android, может потребоваться запросить разрешения. В Ren'Py есть переменная и две функции для взаимодействия с системой разрешений Android.

build.android_permissions = [ ]

Это список строк, где каждая строка содержит полное имя разрешения Android. Например, "android.permission.WRITE_EXTERNAL_STORAGE". Это просто объявляет, что приложение может запрашивать эти разрешения; для запроса разрешения необходимо использовать renpy.check_permission и renpy.request_permission по мере необходимости.

renpy.check_permission(permission)

Проверяет, было ли предоставлено приложению разрешение Android.

permission

Строка, содержащая имя разрешения, например, "android.permission.WRITE_EXTERNAL_STORAGE".

Возвращает true, если разрешение было предоставлено, и false, если нет, или если функция вызвана на платформе, отличной от Android.

renpy.request_permission(permission)

Запрашивает у Android разрешение для этого приложения. Пользователю может быть предложено предоставить разрешение.

permission

Строка, содержащая имя разрешения, например, "android.permission.WRITE_EXTERNAL_STORAGE".

Возвращает true, если разрешение было предоставлено, и false, если нет, или если функция вызвана на платформе, отличной от Android.