Unreal Engine Meta Quest build: сборка, запуск и проверка на гарнитуре

Unreal Engine Meta Quest build — это Android-сборка VR-проекта, которую запускают непосредственно на гарнитуре. Она отличается от PC VR не только форматом пакета: меняются графический API, набор поддерживаемых функций, бюджет производительности, подпись и способ доставки приложения.

Не начинайте диагностику с случайной замены SDK. Сначала зафиксируйте версию Unreal Engine, ветку движка, Meta XR Plugin, Android SDK/NDK и целевую модель Quest. Совместимость этих компонентов меняется, поэтому точные номера нужно брать из документации для используемой версии, а не из старого видео.

Что подготовить

• подтверждённый аккаунт разработчика Meta и организацию;
• Meta Quest с включённым режимом разработчика;
• USB-C кабель для первого запуска и ADB;
• совместимую версию Unreal Engine;
• Android SDK, NDK и JDK требуемых версий;
• OpenXR и/или Meta XR Plugin согласно функциям проекта;
• уникальное имя Android-пакета;
• keystore для release-сборки.

Meta рекомендует сверять способ установки Unreal Engine и плагина с матрицей совместимости. Некоторые возможности раньше появляются в ветке Meta, но для кроссплатформенного проекта может быть удобнее стандартная сборка Epic с подходящим плагином.

Зафиксируйте версии

Создайте короткую таблицу в репозитории проекта:

Если сборка перестала работать после обновления, эта запись позволяет сравнить окружение, а не восстанавливать его по памяти.

Подготовка гарнитуры

1. Добавьте аккаунт в организацию разработчика.
2. Включите developer mode через приложение Meta.
3. Подключите гарнитуру по USB.
4. Наденьте её и подтвердите запрос отладки USB.
5. Проверьте устройство командой adb devices.

Статус unauthorized означает, что разрешение не подтверждено в гарнитуре. Отсутствие устройства указывает на кабель, драйвер, порт или режим подключения. Пока ADB не видит Quest, настройки packaging в Unreal не помогут.

Создание проекта

Для первого теста используйте VR Template. Он уже содержит базовую камеру, контроллеры и локомоцию, поэтому помогает отделить проблему окружения от ошибки собственного проекта.

В рабочем проекте проверьте:

• выбран ли mobile/scalable профиль там, где он требуется;
• отключены ли функции рендера, недоступные на мобильной платформе;
• настроены ли OpenXR и нужные расширения;
• нет ли одновременно активных конфликтующих XR-плагинов;
• корректно ли заданы package name и version code.

Общая архитектура проекта рассмотрена в материале Unreal Engine VR: с чего начать.

Meta XR Project Setup Tool

Project Setup Tool проверяет параметры проекта, связанные с Quest, и предлагает исправления. Используйте его как диагностический список, а не кнопку, которая гарантирует готовность.

После автоматического изменения просмотрите diff конфигурации. Зафиксируйте строки, попавшие в DefaultEngine.ini и другие файлы, чтобы обновление плагина не создало незаметный конфликт.

Android-настройки

В Project Settings проверьте раздел Android:

• package name в обратной доменной записи;
• минимальный и целевой SDK согласно актуальным требованиям;
• архитектуры, необходимые целевой платформе;
• Vulkan и другие параметры рендера;
• ориентацию и полноэкранный режим;
• подпись distribution-сборки;
• store version, который увеличивается для нового загружаемого билда.

Не копируйте готовый DefaultEngine.ini из чужого проекта целиком. Вместе с полезной строкой можно перенести App ID, устаревший API level и настройки другого плагина.

Первый запуск через Launch

Для быстрой проверки подключите Quest, выберите устройство рядом с кнопкой Launch и дождитесь установки. Первый цикл занимает больше времени: движок готовит Android-данные и компилирует шейдеры.

Проверяйте в гарнитуре:

1. приложение стартует без возврата в системное меню;
2. голова и контроллеры отслеживаются;
3. уровень загружается;
4. ввод соответствует рукам;
5. нет критических сообщений в логах;
6. время кадра соответствует целевой частоте.

Запуск через USB подтверждает только development-сборку. Для распространения нужен отдельный тест упакованного и подписанного пакета.

Packaging

Выберите Android как целевую платформу и создайте пакет в чистую папку. Перед release-сборкой:

• очистите тестовые App ID и секреты;
• задайте версию;
• включите distribution/signing;
• проверьте keystore и alias;
• отключите ускоряющие разработку режимы, которые не предназначены для магазина;
• сохраните логи сборки.

Meta указывает, что для публикации нужен Android Distribution Keystore. Храните его и пароль вне публичного репозитория, с резервной копией и ограниченным доступом. Потеря ключа осложняет обновление существующего приложения.

APK, данные приложения и размер

Формат и разбиение пакета зависят от требований площадки, размера проекта и версии инструментов. Не выбирайте схему по старой инструкции. Сверяйте актуальный раздел packaging и правила загрузки Meta.

Большие текстуры, дублированные ассеты и неиспользуемые карты увеличивают время сборки и установки. Используйте Size Map, Asset Audit и списки включаемых уровней. Не оптимизируйте только итоговый размер архива: важны память, время загрузки и производительность на устройстве.

Логи устройства

При падении сразу после запуска снимите adb logcat. Ищите первые ошибки своего процесса, а не последнюю строку после его завершения.

Частые группы причин:

• отсутствующая библиотека или ABI;
• несовместимый плагин;
• ошибка манифеста;
• неверный package name или App ID;
• недоступная функция рендера;
• нехватка памяти;
• исключение в нативном коде.

Сохраняйте лог вместе с версией билда и конфигурацией. Фраза «на Quest вылетает» без этих данных почти не помогает воспроизвести проблему.

Ошибка SDK или NDK

Если Unreal не принимает toolchain:

1. откройте требования именно для вашей версии движка;
2. проверьте пути SDK/NDK/JDK;
3. исключите несколько конфликтующих установок;
4. перезапустите редактор после изменения переменных;
5. соберите пустой VR Template в том же окружении.

Если шаблон собирается, окружение в целом исправно, а причина находится в плагинах или конфигурации рабочего проекта.

Чёрный экран

За чёрным экраном скрываются разные ошибки: падение процесса, незагруженная карта, неподдерживаемый шейдер, неверный режим XR или камера вне сцены.

Проверьте лог, default map, запуск VR mode и простой уровень без тяжёлых материалов. Затем возвращайте системы по одной. Такой контрольный проект быстрее случайного переключения параметров Android.

Производительность нужно проверять на Quest

Play in Editor на ПК не показывает реальную стоимость мобильного GPU, тепловые ограничения и память гарнитуры. После функционального запуска измеряйте packaged development build на устройстве.

Начните с общей оптимизации VR в Unreal Engine, а CPU-всплески разбирайте через Unreal Insights. Профилирование должно предшествовать снижению качества «на глаз».

Перед загрузкой

• создать страницу приложения и проверить идентификаторы;
• увеличить version code;
• подписать пакет правильным ключом;
• пройти требования платформы и валидацию загрузчика;
• проверить контроллеры и права доступа;
• протестировать чистую установку;
• проверить запуск без подключённого ПК;
• сохранить артефакт, символы и конфигурацию релиза.

Рабочий процесс разделяет три результата: проект запускается из редактора, упакованный билд устанавливается вручную, релизный пакет проходит проверку площадки. У каждого этапа свои ошибки, поэтому их не стоит смешивать в одну команду «собрать для Quest».