Как использовать возможности EasyAR на Apple Vision Pro

Это руководство проведет вас через настройку проектов Unity и Xcode, чтобы открыть для приложений Apple Vision Pro все основные возможности EasyAR, включая облачную локализацию Mega.

Перед началом

• Изучите, как использовать примеры для гарнитур
• Убедитесь, что среда разработки соответствует следующим требованиям:
  • visionOS 2.0 и выше
  • Xcode 16.0 и выше, соответствующий версии visionOS, с установленным visionOS simulator
  • рекомендуемая версия Unity: LTS-версия 6000.0.23 или выше

Запрос enterprise-level API license у Apple Inc.

Поскольку получение изображения камеры и параметров на Apple Vision Pro является enterprise-level API, требующим entitlement, вам нужно запросить у Apple Inc. файл license, содержащий этот entitlement. Способ запроса и использования этого license см. в Building spatial experiences for business apps with enterprise APIs for visionOS.

Важно

Bundle ID в entitlement, полученном от Apple, должен полностью совпадать с тем, который был указан при создании EasyAR Sense License Key.

Как выбрать visionOS App Mode

App, работающий на visionOS, может получать данные ARKit только в Immersive Space. Для App, собранного Unity Editor, в Immersive Space нужно выбрать режим RealityKit with PolySpatial или Metal Rendering with Compositor Services в зависимости от различий в процессе рендеринга и API.

Определение Immersive Space можно посмотреть в официальной документации Apple.

Подробное описание Unity App Mode см. в документе Unity PolySpatial visionOS Platform Overview.

Совет

Рекомендации по выбору App Mode

• Предпочтительная рекомендация: RealityKit with PolySpatial

  Если вы впервые работаете с visionOS, рекомендуется выбрать этот режим в первую очередь. Его преимущество в глубокой интеграции с системными возможностями рендеринга visionOS, высокой стабильности и хорошем качестве рендеринга. Этот режим не поддерживает пользовательские кодовые шейдеры (HLSL/ShaderLab): необходимо использовать Shader Graph, и поддерживаются только возможности, прошедшие проверку совместимости PolySpatial (они преобразуются в MaterialX).

  Встроенные в Unity шейдеры Standard (Built-in) и Lit (URP) уже заранее адаптированы официально и могут использоваться напрямую.

• Продвинутые/особые требования: Metal Rendering with Compositor Services

  Подходит для сложных проектов, где нужно перенести большое количество существующих 3D-ресурсов или обязательно использовать пользовательские шейдеры. Поскольку в этом режиме Unity отвечает за всю логику рендеринга и обходит системный конвейер RealityKit, качество рендеринга обычно уступает RealityKit, а также могут возникать непредвиденные проблемы рендеринга.

Рекомендация по подключению EasyAR:

При попытке подключить EasyAR сначала обязательно запустите базовый процесс в режиме RealityKit with PolySpatial. Это помогает эффективно изолировать переменные и избежать ситуации, когда проблемы низкоуровневой адаптации Metal смешиваются с AR-проблемами, из-за чего становится трудно найти причину сбоя.

Настройка в проекте Unity

В проекте Unity нужно выполнить следующие настройки:

Импорт необходимых Package в проект Unity

Unity 6 (рекомендуется):

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (2.0.4+)
• com.unity.polyspatial (2.0.4+)
• com.unity.polyspatial.visionos (2.0.4+)

Важно

Номера версий всех Package должны строго совпадать.

Рекомендуется в первую очередь использовать Unity 6; некоторые ранние версии Unity 2023.x еще не поддерживают visionOS.

Unity 2022.3:

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (1.2.3)
• com.unity.polyspatial (1.2.3)
• com.unity.polyspatial.visionos (1.2.3)

Важно

Номера версий всех Package должны строго совпадать.

Версии 1.3.x не поддерживаются, обязательно зафиксируйте 1.2.3.

Выбор Build Platform

В меню нажмите File > Build Profiles и переключите Platform на visionOS.

Настройка Input System

Убедитесь, что используется новый Input System Package:

В меню нажмите Edit > Project Settings > Player и установите слот Active Input Handling в Input System Package(New).

После этого Unity может запросить перезапуск проекта; нажмите Apply, чтобы изменения вступили в силу.

Настройка XR Plug-in Management

В меню нажмите Edit > Project Settings > XR Plug-in Management, на вкладке visionOS в Plug-in Providers отметьте Apple visionOS.

Настройка плагина Apple visionOS

В меню нажмите Edit > Project Settings > XR Plug-in Management > Apple visionOS.

Выберите подходящий App Mode согласно описанию выше.

Примечание

Режим Windowed не работает в Immersive Space, поэтому не может использовать AR-возможности.

Режим Hybrid означает, что разработчику нужно вручную переключаться между режимами Metal и RealityKit. Из-за сравнительно сложного использования он не рекомендуется; подробнее см. официальное описание этого режима Unity.

Далее на той же странице выполните следующие изменения:

• Добавьте описание в слот World Sensing Usage Description.

• Установите Metal Immersion Style в Mixed.

• Установите Reality Kit Immersion Style в Mixed.

• Отметьте IL2CPP Large Exe Workaround.

[Только для режима RealityKit] Импорт TextMesh Pro Essentials

В меню нажмите Edit > Project Settings > TextMesh Pro > нажмите Import TMP Essentials

Примечание

В настоящее время режим RealityKit with PolySpatial поддерживает только текст TextMesh Pro; если не импортировать этот пакет, текст не будет отображаться.

[Только для режима RealityKit] Настройки PolySpatial

В меню нажмите Edit > Project Settings > PolySpatial и выполните на этой странице следующие изменения:

• Установите Default Volume Camera Window Config в Default Unbounded Configuration.

• Отметьте Auto-Create Volume Camera

Если нужно указать другой Default Volume Camera Window Config, обязательно убедитесь, что его Mode установлен в Unbounded.

Если в сцене есть Volume Camera, удалите его.

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

• Volume Camera, у которого значение World Transform не равно identity, не поддерживается.
• Если по особым причинам нужно добавить в сцену единственный пользовательский Volume Camera, обязательно:
  • установите его World Transform в identity;
  • убедитесь, что Mode его Volume Camera Window Configuration установлен в Unbounded;
  • используйте его только при полном понимании смысла и назначения, описанных в официальной документации Unity.

[При использовании Mega] Добавление Location Usage Description

Осторожно

Если в настройках EasyAR включено разрешение Location (при использовании функции Mega), необходимо добавить описание разрешения, иначе Build завершится ошибкой.

Поскольку сейчас поле Location Usage Description не отображается во вкладке Project Settings > Player > visionOS в Unity, выполните настройку так:

1. Переключите вкладку платформы: временно переключите вкладку на iOS.
2. Введите описание: в слот Location Usage Description введите необходимое описание назначения разрешения.
3. Вернитесь на visionOS: переключите вкладку обратно на visionOS; введенная настройка автоматически сохранится и вступит в силу.

Настройка в проекте Xcode

В Xcode-проекте, полученном сборкой Unity, нужно выполнить следующие настройки:

Настройка entitlement для данных камеры

• Скопируйте полученный файл Enterprise.license в каталог файлов Xcode-проекта.

  

• Перетащите Enterprise.license из каталога файлов Xcode-проекта в Xcode-проект.

  

Изменение info.plist, чтобы приложение могло сохранять и передавать файлы

Если нужно записывать EIF в приложении и передавать его на компьютер или другие устройства через приложение Files в visionOS, добавьте и измените в Info.plist следующие поля:

• Добавьте LSSupportsOpeningDocumentsInPlace и установите значение true.

• Добавьте UIFileSharingEnabled и установите значение true.

Совет

После добавления полей Key, отображаемый в интерфейсе Xcode, может отличаться от строки, добавленной вручную (например, вы ввели LSSupportsOpeningDocumentsInPlace, а отображается Supports opening documents in place). Это нормально.