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

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

Прежде чем начать

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

Запрос корпоративной лицензии API у Apple Inc.

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

Важно

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

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

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

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

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

Совет

Рекомендации по выбору 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 необходимо выполнить следующие настройки:

Импорт необходимых пакетов в проект 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+)

Важно

Все номера версий пакетов должны строго совпадать.

Рекомендуется в первую очередь использовать 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)

Важно

Все номера версий пакетов должны строго совпадать.

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

Выбор платформы сборки

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

Настройка системы ввода

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

В меню выберите Edit > Project Settings > Player, установите для слота Active Input Handling значение Input System Package(New).

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

Настройка управления плагинами XR

В меню выберите 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] Добавление описания использования местоположения

Осторожно

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

Поскольку в настоящее время в Project Settings > Player > visionOS не отображается поле Location Usage Description, выполните следующие шаги:

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

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

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

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

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

  

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

  

Изменение info.plist для сохранения и передачи файлов

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

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

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

Совет

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