Unity OpenXR VR: настройка первого проекта

Unity OpenXR VR-проект можно собрать без прямой привязки базового управления к одному производителю гарнитуры. OpenXR связывает приложение с XR-runtime, а Unity подключает стандарт через XR Plug-in Management. Для первого теста понадобятся OpenXR Plugin, Input System, XR Interaction Toolkit, профиль контроллеров и объект XR Origin в сцене.

Интерфейс Unity меняется между версиями редактора и пакетов. Перед началом выберите поддерживаемую LTS-версию, зафиксируйте номера пакетов и сверяйте предупреждения Project Validation с документацией именно этой версии.

Что делает OpenXR

Khronos определяет OpenXR как интерфейс между XR-приложением и runtime. Runtime получает данные трекинга, управляет периферией и принимает подготовленные кадры от приложения. Для разработчика это общий слой работы с положением головы, состоянием контроллеров и отправкой изображения.

Подробнее назначение стандарта разобрано в материале «Что такое OpenXR».

Шаг 1. Установите пакеты

Откройте Window → Package Manager. Установите XR Plug-in Management, OpenXR Plugin и XR Interaction Toolkit. Современный XRI работает с Input System, поэтому Unity может предложить включить новую систему ввода и перезапустить редактор.

После установки пакетов сохраните Packages/manifest.json в системе контроля версий. Это позволит воспроизвести окружение и понять, после какого обновления появилась ошибка.

Шаг 2. Включите OpenXR для нужной платформы

В меню Edit откройте Project Settings, затем раздел XR Plug-in Management. Unity показывает настройки отдельно для целевых платформ. На вкладке Windows, Mac, Linux выберите OpenXR для компьютерного теста. Для автономного Quest переключите Build Target на Android и включите провайдер там.

Перейдите в Project Validation. Исправьте ошибки, которые относятся к выбранной платформе. Кнопка Fix подходит для понятных настроек, но каждое изменение стоит просмотреть: автоматическое исправление может переключить графический API или параметры Player Settings.

Шаг 3. Добавьте профиль взаимодействия

OpenXR отделяет логические действия от конкретной формы контроллера. В настройках OpenXR откройте список Interaction Profiles и добавьте профиль используемого устройства, например Oculus Touch Controller Profile для контроллеров Quest.

Профиль сообщает runtime, какие пути ввода доступны. Он не создаёт игровую механику. Привязка кнопки, захват объекта и луч указателя настраиваются в Input Actions и компонентах XR Interaction Toolkit.

Если Project Validation сообщает об отсутствии профиля, приложение может запуститься с изображением, но не получить ввод. Для нескольких гарнитур добавляют соответствующие профили и проверяют каждую конфигурацию на реальном устройстве.

Шаг 4. Создайте XR Origin

Удалите или отключите обычную Main Camera, чтобы в сцене не осталось двух активных камер. Через меню GameObject → XR добавьте XR Origin для VR. Точное название пункта зависит от версии XRI и импортированных Starter Assets.

XR Origin задаёт связь между координатами физического пространства и сценой Unity. Внутри находятся Camera Offset, камера гарнитуры и объекты левой и правой руки. Tracked Pose Driver обновляет положение камеры по данным runtime.

Выберите Tracking Origin Mode:

• Floor подходит для room-scale и отсчитывает высоту от пола;
• Device использует начальное положение гарнитуры и требует корректного смещения камеры для сидячего режима.

Неверный режим часто проявляется как камера на уровне пола или слишком высокая капсула игрока. Не исправляйте такой эффект произвольным перемещением дочерней камеры: сначала проверьте origin и высоту пола.

Шаг 5. Настройте руки и ввод

XR Interaction Toolkit предлагает action-based управление. У левого и правого контроллера назначаются действия позиции, вращения, выбора, активации и интерфейсных кнопок. Starter Assets содержат готовый набор Input Actions, с которого удобно начать.

Для видимых рук можно использовать простые модели контроллеров. Сначала подтвердите, что оба объекта следуют за реальными устройствами и реагируют на trigger. Анимацию кистей и сложный захват добавляйте после этой проверки.

Лучевой интерфейс обычно строится на XR Ray Interactor. Прямой захват использует XR Direct Interactor и коллайдер около руки. Объекту, который можно взять, нужен Collider, Rigidbody и XR Grab Interactable. Кинематическое поведение, столкновения и точка захвата зависят от выбранного сценария.

Шаг 6. Соберите минимальную сцену

Создайте плоскость пола, источник света и несколько объектов на расстоянии вытянутой руки. Один куб сделайте статичным, второй подготовьте для захвата. Добавьте Capsule или стену, чтобы увидеть масштаб и проверить коллизии.

Минимальный тест должен отвечать на конкретные вопросы:

1. Камера повторяет движение головы без неверного смещения.
2. Левая и правая рука получают позу контроллера.
3. Кнопка выбора захватывает объект и отпускает его.
4. Интерфейс либо телепортация работают только там, где запланировано.

Если добавить графику и игровую логику раньше, источник ошибки станет сложнее найти.

Шаг 7. Запустите через правильный runtime

Для PC VR включите гарнитуру, запустите её системное приложение и выберите нужный OpenXR-runtime. Затем откройте сцену в Play Mode. Если стартует другой runtime или шлем остаётся в домашнем окружении, проверьте активный провайдер и порядок запуска программ.

Quest через Link должен определиться в приложении Meta Quest Link. SteamVR-гарнитуры используют активный runtime SteamVR. Не держите несколько систем XR открытыми без необходимости: они могут спорить за устройство и усложнять диагностику.

Для автономной проверки переключите проект на Android, настройте идентификатор приложения и требования выбранного SDK, затем соберите APK. Работа в редакторе подтверждает только компьютерный путь; ограничения мобильного GPU проявятся на гарнитуре.

Типовые ошибки

Изображение есть, контроллеров нет

Проверьте Interaction Profile, Input Actions и компоненты контроллеров внутри XR Origin. Убедитесь, что action asset включён. В старом и новом Input System одинаковая кнопка может иметь разные пути.

Камера находится на неправильной высоте

Сверьте Tracking Origin Mode и Camera Y Offset. Проверьте, не перемещена ли Main Camera вручную и не осталось ли второй камеры в сцене.

Проект запускается на мониторе

Откройте XR Plug-in Management для текущего Build Target. Провайдер, включённый только на Android, не активирует VR в Windows Play Mode. Убедитесь, что runtime видит шлем до запуска Unity.

Project Validation возвращает предупреждения

Откройте каждое сообщение и соотнесите его с платформой. Частые причины связаны с графическим API, interaction profile и настройками Input System. После Fix сохраните изменения и повторно откройте окно проверки.

Объект дрожит в руке

Проверьте Rigidbody, режим движения XR Grab Interactable и столкновения с телом игрока. Дрожание может появиться, когда физика и Transform одновременно пытаются переместить один объект.

Итог

Рабочая конфигурация Unity OpenXR строится по короткой цепочке: пакеты, провайдер для целевой платформы, профиль контроллеров, XR Origin и минимальная тестовая сцена. Сначала подтвердите трекинг головы и рук, затем добавляйте взаимодействие. Passthrough, hand tracking и другие платформенные функции подключайте по одной. Зафиксированные версии Unity и пакетов помогут повторить сборку и отделить ошибку проекта от изменения инструментария.