Como usar os recursos do EasyAR no Apple Vision Pro

Este guia orienta você na configuração de projetos Unity e Xcode para desbloquear todos os recursos principais do EasyAR, incluindo a localização em nuvem do Mega, em aplicativos para Apple Vision Pro.

Antes de começar

• Aprenda como usar os exemplos de headset
• Certifique-se de que o ambiente de desenvolvimento atenda aos seguintes requisitos:
  • visionOS 2.0 ou superior
  • Xcode 16.0 ou superior correspondente à versão do visionOS, com o visionOS simulator instalado
  • Versão recomendada do Unity: versão LTS 6000.0.23 ou superior

Solicitar à Apple Inc. uma licença de API empresarial

Como obter a imagem e os parâmetros da câmera no Apple Vision Pro requer um entitlement de uma API empresarial, você precisa solicitar à Apple Inc. um arquivo de license que inclua esse entitlement. Para saber como solicitar e usar essa license, consulte Building spatial experiences for business apps with enterprise APIs for visionOS.

Importante

O Bundle ID no entitlement obtido junto à Apple deve ser exatamente igual ao preenchido ao criar a EasyAR Sense License Key.

Como escolher o visionOS App Mode

Apps executados no visionOS só conseguem obter dados do ARKit em Immersive Space. Apps empacotados pelo Unity Editor em Immersive Space precisam escolher entre os modos RealityKit with PolySpatial ou Metal Rendering with Compositor Services, de acordo com o fluxo de renderização e as APIs usadas.

Para a definição de Immersive Space, consulte a documentação oficial da Apple.

Para uma apresentação detalhada do App Mode do Unity, consulte visionOS Platform Overview na documentação do Unity PolySpatial.

Dica

Sugestão para escolher o App Mode

• Recomendação principal: RealityKit with PolySpatial

  Se você está entrando em contato com visionOS pela primeira vez, recomenda-se priorizar este modo. Sua vantagem é a integração profunda com os recursos de renderização em nível de sistema do visionOS, com alta estabilidade e bom efeito de renderização. Este modo não oferece suporte a shaders de código personalizado (HLSL/ShaderLab). É obrigatório usar Shader Graph, e somente recursos aprovados pela verificação de compatibilidade do PolySpatial são suportados (eles serão convertidos para MaterialX).

  Os shaders integrados do Unity Standard (Built-in) e Lit (URP) já foram adaptados oficialmente com antecedência e podem ser usados diretamente.

• Avançado/necessidades específicas: Metal Rendering with Compositor Services

  Adequado para projetos complexos com grande quantidade de assets 3D existentes a migrar ou que precisam obrigatoriamente usar shaders personalizados. Como, nesse modo, o Unity é responsável por toda a lógica de renderização e contorna o pipeline RealityKit do sistema, o efeito de renderização geralmente é inferior ao RealityKit e podem ocorrer problemas de renderização imprevisíveis.

Sugestão de integração do EasyAR:

Ao tentar integrar o EasyAR, execute primeiro o fluxo básico usando o modo RealityKit with PolySpatial. Isso isola variáveis de forma eficaz e evita que problemas de adaptação de baixo nível do Metal se misturem a problemas relacionados a AR, dificultando a localização da causa da falha.

Configuração no projeto Unity

As seguintes configurações são necessárias no projeto Unity:

Importar os Packages necessários para o projeto Unity

Unity 6 (recomendado):

• RealityKit/Hybrid
• Metal

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

Importante

Os números de versão de todos os Packages devem permanecer estritamente iguais.

Recomenda-se priorizar o Unity 6. Algumas versões iniciais do Unity 2023.x ainda não oferecem suporte ao 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)

Importante

Os números de versão de todos os Packages devem permanecer estritamente iguais.

A versão 1.3.x não é suportada. Bloqueie obrigatoriamente em 1.2.3.

Selecionar Build Platform

Clique em File > Build Profiles na barra de menu e altere Platform para visionOS.

Configurar Input System

Certifique-se de usar o novo Input System Package:

Clique em Edit > Project Settings > Player na barra de menu e defina o campo Active Input Handling como Input System Package(New).

Depois disso, o Unity pode solicitar a reinicialização do projeto. Clique em Apply para que a alteração entre em vigor.

Configurar XR Plug-in Management

Clique em Edit > Project Settings > XR Plug-in Management na barra de menu e, na guia visionOS, marque Apple visionOS em Plug-in Providers.

Configurar o plug-in Apple visionOS

Clique em Edit > Project Settings > XR Plug-in Management > Apple visionOS na barra de menu.

Escolha o App Mode adequado de acordo com a introdução anterior.

Nota

O modo Windowed não pode usar recursos de AR porque não é executado em Immersive Space.

O modo Hybrid significa que o desenvolvedor precisa alternar manualmente entre os modos Metal e RealityKit. Como seu uso é relativamente complexo, ele não é recomendado. Para detalhes, consulte a explicação oficial da Unity sobre esse modo.

Em seguida, faça as seguintes alterações na mesma página:

• Adicione uma descrição no campo World Sensing Usage Description.

• Defina Metal Immersion Style como Mixed.

• Defina Reality Kit Immersion Style como Mixed.

• Marque IL2CPP Large Exe Workaround.

[Necessário apenas no modo RealityKit] Importar TextMesh Pro Essentials

Clique em Edit > Project Settings > TextMesh Pro na barra de menu > clique em Import TMP Essentials

Nota

No momento, o modo RealityKit with PolySpatial oferece suporte apenas a textos TextMesh Pro. Se eles não forem importados, o texto não poderá ser renderizado.

[Necessário apenas no modo RealityKit] Configurações relacionadas ao PolySpatial

Clique em Edit > Project Settings > PolySpatial na barra de menu e faça as seguintes alterações nessa página:

• Defina Default Volume Camera Window Config como Default Unbounded Configuration.

• Marque Auto-Create Volume Camera

Se precisar especificar outro Default Volume Camera Window Config, certifique-se de que seu Mode seja Unbounded.

Se houver uma Volume Camera na cena, exclua-a.

Aviso

• Volume Camera cujo valor de World Transform não seja identity não é suportada.
• Se, por motivos especiais, for necessário adicionar à cena uma Volume Camera personalizada e única, certifique-se de:
  • Definir seu World Transform como identity.
  • Garantir que o Mode de sua Volume Camera Window Configuration esteja definido como Unbounded.
  • Usá-la somente com total compreensão do significado e da finalidade descritos na documentação oficial da Unity.

[Ao usar Mega] Adicionar Location Usage Description

Cuidado

Se a permissão Location estiver habilitada na configuração do EasyAR (ao usar o recurso Mega), é obrigatório adicionar uma descrição de permissão. Caso contrário, o Build falhará.

Como atualmente o campo Location Usage Description não é exibido na guia Project Settings > Player > visionOS do Unity, configure seguindo as etapas abaixo:

1. Alternar a guia da plataforma: altere temporariamente a guia para iOS.
2. Preencher a descrição: preencha o campo Location Usage Description com a descrição necessária do uso da permissão.
3. Voltar para visionOS: altere a guia de volta para visionOS. A configuração preenchida agora será preservada e entrará em vigor automaticamente.

Configuração no projeto Xcode

As seguintes configurações são necessárias no projeto Xcode gerado pelo build do Unity:

Configurar o entitlement de dados da câmera

• Copie o arquivo Enterprise.license obtido para o diretório do projeto Xcode.

  

• Arraste o Enterprise.license no diretório do projeto Xcode para dentro do projeto Xcode.

  

Modificar info.plist para permitir que o aplicativo salve e entregue arquivos

Se for necessário gravar EIF no aplicativo e enviá-lo ao computador ou a outros dispositivos por meio do app Arquivos do visionOS, adicione e modifique os seguintes campos em Info.plist:

• Adicione LSSupportsOpeningDocumentsInPlace e defina o valor como true.

• Adicione UIFileSharingEnabled e defina o valor como true.

Dica

Após adicionar os campos, o Key exibido na interface do Xcode será diferente da string adicionada manualmente. Por exemplo, você pode inserir LSSupportsOpeningDocumentsInPlace, mas a interface mostrar Supports opening documents in place. Isso é normal.