Настройка проекта OpenXR — документация

Настройки запуска, XR-риг, tracker и pose, карта действий и диагностика.

Этот раздел настраивает проект OpenXR и минимальный XR-риг. Нужны сборка движка с OpenXR и runtime целевого устройства. Зарегистрированный XRInterface ещё не означает, что гарнитура подключена или сеанс может быть создан.

Настройки до запуска

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

Project Settings	Значение
`xr/openxr/enabled`	true
`xr/shaders/enabled`	true для описанного XR-рендеринга
`xr/openxr/default_action_map`	Путь к подготовленной карте; исходно `asset://openxr_action_map.rdata`

Примените требуемый перезапуск редактора. Это параметры запуска и графической подготовки: их изменение в _Ready() не заменяет запуск с нужной конфигурацией. На ПК проверьте активный OpenXR runtime устройства до старта проекта.

В примере можно использовать Mobile либо Forward+ в зависимости от целевого бюджета и нужных эффектов. Поддержка выбранного графического пути нужна также runtime и устройству. Не считайте один renderer универсально самым быстрым для всех гарнитур; оцените проект на целевом устройстве. Настройка OpenXR не является настройкой WebXR.

Для отдельного обычного запуска есть CLI --xr-mode off. Это отключение XR на этапе запуска, а не команда подключения гарнитуры. --xr-mode on также не устанавливает отсутствующий runtime и не гарантирует успешную инициализацию.

Соберите риг

Пример иерархии Entity:

Main (Entity3D)
├── XRSession (Entity, XrStartup.cs, ProcessMode=Always)
├── XROrigin3D (ProcessMode=Always)
│   ├── XRCamera3D
│   ├── LeftHand (XRController3D)
│   └── RightHand (XRController3D)
├── Gameplay (Entity3D, ProcessMode=Pausable)
└── Interface (CanvasLayer, ProcessMode=Always)

XROrigin3D задаёт начало XR-пространства в игровом мире. Камера и контроллеры должны быть его непосредственными дочерними Entity. Для перемещения игрока перемещайте origin или управляющий им объект, а не перезаписывайте отслеживаемую позу головы каждый кадр.

У LeftHand задайте Tracker=left_hand, у RightHand — right_hand. Для стандартной карты выберите Pose=grip. Имена Entity LeftHand/RightHand сами по себе tracker не выбирают. В стандартной карте pose-действия grip_pose, aim_pose, default_pose публикуются в tracker как grip, aim, default. Для собственного pose-действия учитывайте его имя.

Начальные координаты для удобства редактирования не доказывают tracking. Без данных XRController3D остаётся неактивным; не используйте неподвижную модель контроллера как признак успешного подключения.

Карта и запуск

Подготовьте карту действий до создания XR-сеанса. Минимальная карта select из того руководства содержит только кнопку выбора. Для отслеживания рук добавьте нужные Pose-действия и их привязки либо настройте стандартную карту; одна кнопка не создаёт pose tracking.

Прикрепите полный скрипт запуска к XRSession. Один такой контроллер должен обслуживать один выбранный Viewport. После успешной инициализации он устанавливает UseXR у своего Viewport. Исходное значение восстанавливается при удалении контроллера из дерева. Полученные от XRServer интерфейс и Viewport скрипт не освобождает.

Initialize()==true и IsInitialized()==true не означают, что игра уже получила фокус. Ждите состояния Focused для игровых действий. Visible означает, что изображение видно, но XR-ввод недоступен; этот переход не равен отключению гарнитуры. Состояния сеанса OpenXR.

Что проверить на устройстве

Изображение поступает в гарнитуру; UseXR установлен у того Viewport, который выводит XR.
Поворот и перемещение головы меняют вид без ручного движения камеры скриптом.
Обе руки получают tracking; их tracker и pose соответствуют карте.
select читается в Focused; при системном меню игра обрабатывает потерю фокуса и не продолжает опасные игровые действия.
Повторное получение фокуса не снимает независимую паузу меню. Остановка сеанса приводит к предусмотренному завершению XR или обычному режиму.

Чёрный экран: проверьте ошибку запуска, камеру, нужный Viewport, UseXR, runtime и графический путь. Нет рук: проверьте tracker, pose, действия карты и наличие tracking, затем видимость моделей. Нет нажатий: проверьте фокус, активный набор и привязки. Изменения карты не появились: проверьте её путь и перезапустите сеанс.

В текущем движке без гарнитуры проверены создание рига, свойства tracker/pose и отказ скрипта при выключенном XR. Положительная инициализация, стереовывод, tracking, редакторские действия и перечисленные проверки на устройстве не выполнены. Эти пункты нужно пройти на целевом runtime.