Table of Contents

Cómo usar las capacidades de EasyAR en Apple Vision Pro

Esta guía le guiará a través de la configuración del proyecto de Unity y Xcode para desbloquear todas las capacidades principales de EasyAR, incluida la localización en la nube Mega, para aplicaciones de Apple Vision Pro.

Antes de comenzar

  • Aprenda a usar las muestras de visores
  • Asegúrese de que su entorno de desarrollo cumple con los siguientes requisitos:
    • visionOS 2.0 y superior
    • Xcode 16.0 y superior con la versión correspondiente de visionOS e instalado el simulador de visionOS
    • Versión recomendada de Unity 6000.0.23 o superior de la versión LTS

Solicitar una licencia de API empresarial a Apple Inc.

Dado que la obtención de imágenes y parámetros de la cámara en Apple Vision Pro es una API empresarial que requiere un entitlement, debe solicitar a Apple Inc. un archivo de licencia que incluya este entitlement. Para solicitar y utilizar esta licencia, consulte Building spatial experiences for business apps with enterprise APIs for visionOS.

Importante

El Bundle ID en el entitlement obtenido de Apple debe coincidir exactamente con el proporcionado al crear la EasyAR Sense License Key.

Cómo elegir el modo de aplicación visionOS

Las aplicaciones que se ejecutan en visionOS solo pueden obtener datos de ARKit en Immersive Space. La aplicación empaquetada por el editor de Unity en Immersive Space, según el flujo de renderizado y la API, debe elegir entre el modo RealityKit with PolySpatial o Metal Rendering with Compositor Services.

Para la definición de Immersive Space, consulte la documentación oficial de Apple.

Para obtener una descripción detallada de los modos de aplicación de Unity, consulte visionOS Platform Overview en la documentación de PolySpatial de Unity.

Consejo

Recomendaciones para elegir el modo de aplicación

  • Primera opción recomendada: RealityKit with PolySpatial

    Si es la primera vez que usa visionOS, se recomienda elegir este modo. Su ventaja es la integración profunda con las características de renderizado a nivel de sistema de visionOS, alta estabilidad y buen efecto de renderizado. Este modo no admite sombreadores de código personalizados (HLSL/ShaderLab), debe usar Shader Graph y solo admite características que hayan pasado la verificación de compatibilidad de PolySpatial (se convertirán a MaterialX).

    Los sombreadores integrados de Unity Standard (Built-in) y Lit (URP) ya han sido preadaptados oficialmente y se pueden usar directamente.

  • Avanzado/requisitos específicos: Metal Rendering with Compositor Services

    Adecuado para proyectos complejos con grandes necesidades de migración de activos 3D existentes o que deben usar sombreadores personalizados. Debido a que en este modo Unity es responsable de toda la lógica de renderizado, evitando la canalización del sistema RealityKit, el efecto de renderizado generalmente no es tan bueno como RealityKit y pueden surgir problemas de renderizado imprevistos.

Recomendación para integrar EasyAR:

Al intentar integrar EasyAR, asegúrese primero de ejecutar el flujo básico en modo RealityKit with PolySpatial. Esto puede aislar variables de manera efectiva, evitando que los problemas de adaptación subyacente de Metal se entrelacen con problemas relacionados con AR, lo que dificulta identificar la causa de la falla.

Configuración en el proyecto de Unity

En el proyecto de Unity, se requiere la siguiente configuración:

Importar paquetes necesarios al proyecto de Unity

Unity 6 (recomendado):

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

Los números de versión de todos los paquetes deben ser estrictamente consistentes.

Se recomienda priorizar Unity 6, ya que algunas versiones anteriores de Unity 2023.x aún no son compatibles con visionOS.

Unity 2022.3:

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

Los números de versión de todos los paquetes deben ser estrictamente consistentes.

No se admite la versión 1.3.x, asegúrese de bloquearse en 1.2.3.

Seleccionar plataforma de compilación

Haga clic en File > Build Profiles en la barra de menú y cambie la plataforma a visionOS.

Cambiar plataforma de compilación

Configurar el sistema de entrada

Asegúrese de usar la versión nueva de Input System Package:

Haga clic en Edit > Project Settings > Player en la barra de menú y establezca la ranura Active Input Handling en Input System Package(New).

Unity puede solicitar reiniciar el proyecto; haga clic en Apply para que los cambios surtan efecto.

Cambios en InputSystem surten efecto

Configurar XR Plug-in Management

Haga clic en Edit > Project Settings > XR Plug-in Management en la barra de menú y, en la pestaña visionOS, marque Apple visionOS en Plug-in Providers.

Seleccionar complemento visionOS

Configurar el complemento Apple visionOS

Haga clic en Edit > Project Settings > XR Plug-in Management > Apple visionOS en la barra de menú.

Según la introducción anterior, elija el App Mode adecuado.

Seleccionar modo de aplicación

Nota

El modo Windowed no se ejecuta en Immersive Space, por lo que no puede usar capacidades AR.

El modo Hybrid significa que el desarrollador debe cambiar manualmente entre los modos Metal y RealityKit. Dado que su uso es complejo, no se recomienda. Consulte la explicación oficial de Unity sobre este modo.

En la misma página, realice las siguientes modificaciones:

  • En la ranura World Sensing Usage Description, agregue una descripción.

  • Establezca Metal Immersion Style en Mixed.

  • Establezca Reality Kit Immersion Style en Mixed.

  • Marque IL2CPP Large Exe Workaround.

Modificar configuración del complemento visionOS

[Solo modo RealityKit] Importar TextMesh Pro Essentials

Haga clic en Edit > Project Settings > TextMesh Pro > haga clic en Import TMP Essentials en la barra de menú.

Importar TMP Essentials

Nota

Actualmente, el modo RealityKit with PolySpatial solo admite texto TextMesh Pro. Si no se importa, no se podrá renderizar texto.

[Solo modo RealityKit] Configuración relacionada con PolySpatial

Haga clic en Edit > Project Settings > PolySpatial en la barra de menú y en esta página realice las siguientes modificaciones:

  • Establezca Default Volume Camera Window Config en Default Unbounded Configuration.

  • Marque Auto-Create Volume Camera

Configurar PolySpatial

Si necesita especificar Default Volume Camera Window Config por separado, asegúrese de que su Mode sea Unbounded.

Confirmar que Mode es Unbounded

Si hay un Volume Camera en la escena, elimínelo.

Eliminar Volume Camera de la escena

Advertencia
  • No se admite Volume Camera cuyo valor World Transform no sea identity.
  • Si por razones especiales necesita agregar un Volume Camera personalizado único en la escena, asegúrese de:
    • Establecer su World Transform en identity.
    • Asegurarse de que el Mode de su Volume Camera Window Configuration esté configurado como Unbounded.
    • Usarlo solo después de comprender completamente su significado y propósito en la documentación oficial de Unity.

[Al usar Mega] Agregar descripción de uso de ubicación

Precaución

Si habilita el permiso Location en la configuración de EasyAR (al usar la función Mega), debe agregar información de descripción del permiso; de lo contrario, la compilación fallará.

Dado que actualmente el campo Location Usage Description no se muestra en Project Settings > Player > visionOS, configure de la siguiente manera:

  1. Cambiar pestaña de plataforma: cambie temporalmente a la pestaña iOS.
  2. Ingresar descripción: en la ranura Location Usage Description, ingrese una explicación necesaria del uso del permiso.
  3. Volver a visionOS: vuelva a la pestaña visionOS; la configuración ingresada se conservará y aplicará automáticamente.

Descripción de ubicación

Configuración en el proyecto de Xcode

En el proyecto de Xcode obtenido mediante el empaquetado de Unity, se requiere la siguiente configuración:

Configurar el entitlement de datos de cámara

  • Copie el archivo Enterprise.license obtenido en el directorio del proyecto de Xcode.

    Copiar al directorio del proyecto de Xcode

  • Arrastre Enterprise.license desde el directorio del proyecto de Xcode al proyecto de Xcode.

    Mover al proyecto de Xcode

Modificar info.plist para permitir guardar y enviar archivos

Si necesita grabar EIF en la aplicación y enviarlo a una computadora u otro dispositivo a través de la aplicación de archivos de visionOS, agregue los siguientes campos en Info.plist y modifíquelos:

  • Agregue LSSupportsOpeningDocumentsInPlace y establezca su valor en true.

  • Agregue UIFileSharingEnabled y establezca su valor en true.

Modificar Info.plist

Consejo

Después de agregar los campos, la Key mostrada en la interfaz de Xcode será diferente de la cadena agregada manualmente (por ejemplo, si ingresa LSSupportsOpeningDocumentsInPlace, se mostrará Supports opening documents in place, lo cual es normal).