Como usar recursos EasyAR no Apple Vision Pro

Este guia orientará você pela configuração de projetos Unity e Xcode para desbloquear todos os recursos principais do EasyAR, incluindo o posicionamento em nuvem Mega, para aplicativos Apple Vision Pro.

Antes de começar

• Aprenda como usar amostras de headset
• Garanta que o ambiente de desenvolvimento atenda aos seguintes requisitos:
  • visionOS 2.0 ou superior
  • Xcode 16.0 ou superior para a versão visionOS correspondente, com o simulador visionOS instalado
  • Versão recomendada do Unity: 6000.0.23 ou superior nas versões LTS

Solicitar licença corporativa de API junto à Apple Inc.

Como a captura de imagens e parâmetros da câmera no Apple Vision Pro requer uma permissão (entitlement) de API corporativa, você precisa solicitar um arquivo de licença contendo essa permissão junto à Apple Inc. A forma de solicitar e usar essa licença pode ser encontrada em Building spatial experiences for business apps with enterprise APIs for visionOS.

Importante

O Bundle ID na permissão (entitlement) obtida da Apple deve corresponder exatamente ao preenchido durante a criação da EasyAR Sense License Key.

Como escolher visionOS app mode

Os aplicativos executados no visionOS só podem obter dados do ARKit em Immersive Space. Já os aplicativos exportados pelo editor Unity, quando em Immersive Space, exigem a escolha entre os modos RealityKit with PolySpatial ou Metal rendering with compositor services, dependendo do fluxo de renderização e das APIs utilizadas.

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

Para uma explicação detalhada dos modos de aplicativo no Unity, consulte o documento Unity PolySpatial: visionOS platform overview.

Dica

Recomendação de escolha do app mode

• Primeira recomendação: RealityKit with PolySpatial

  Se você é novo no visionOS, priorize este modo. Sua vantagem é a integração profunda com os recursos de renderização de nível de sistema do visionOS, oferecendo alta estabilidade e qualidade de renderização. Este modo não suporta shaders de código personalizado (HLSL/ShaderLab), exigindo o uso de Shader Graph, e só funciona com recursos compatíveis após verificação do PolySpatial (convertidos para MaterialX).

  Os shaders internos do Unity, Standard (Built-in) e Lit (URP), já foram pré-adaptados oficialmente e podem ser usados diretamente.

• Avançado/necessidades específicas: Metal rendering with compositor services

  Ideal para projetos com necessidade de migração de grandes quantidades de ativos 3D existentes ou que exijam shaders personalizados complexos. Neste modo, o Unity gerencia toda a lógica de renderização, contornando o pipeline do RealityKit do sistema, o que geralmente resulta em qualidade inferior e possíveis problemas de renderização imprevistos.

Recomendação para integração com EasyAR:

Ao integrar o EasyAR, comece sempre com o modo RealityKit with PolySpatial para validar o fluxo básico. Isso ajuda a isolar variáveis, evitando que problemas de adaptação de baixo nível do Metal se misturem a questões relacionadas à realidade aumentada, dificultando a identificação de falhas.

Configuração em projetos Unity

O projeto Unity requer as seguintes configurações:

Importar pacotes 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

Todas as versões dos pacotes devem ser rigorosamente idênticas.

Priorize o uso do Unity 6, pois algumas versões anteriores do Unity 2023.x ainda não suportam 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

Todas as versões dos pacotes devem ser rigorosamente idênticas.

Versões 1.3.x não são suportadas; utilize estritamente a 1.2.3.

Selecionar build platform

No menu, clique em File > Build Profiles e altere a Platform para visionOS.

Configurar input system

Garanta o uso do novo Input System Package:

No menu, clique em Edit > Project Settings > Player e defina Active Input Handling como Input System Package(New).

O Unity pode solicitar reinicialização do projeto; clique em Apply para confirmar as alterações.

Configurar XR plug-in management

No menu, clique em Edit > Project Settings > XR Plug-in Management e, na aba visionOS, marque Apple visionOS em Plug-in Providers.

Configurar plug-in Apple visionOS

No menu, clique em Edit > Project Settings > XR Plug-in Management > Apple visionOS.

Selecione o App Mode apropriado conforme explicado anteriormente.

Nota

O modo Windowed não é executado em Immersive Space, impossibilitando o uso de recursos de RA.

O modo Hybrid exige alternância manual entre Metal e RealityKit, sendo complexo e não recomendado. Consulte a explicação oficial da Unity.

Na mesma página, faça as seguintes alterações:

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

• Defina Metal Immersion Style como Mixed.

• Defina Reality Kit Immersion Style como Mixed.

• Marque IL2CPP Large Exe Workaround.

[Somente modo RealityKit] Importar TextMesh Pro essentials

No menu, clique em Edit > Project Settings > TextMesh Pro > Import TMP Essentials

Nota

Atualmente, o modo RealityKit with PolySpatial só suporta texto com TextMesh Pro. Sem essa importação, textos não serão renderizados.

[Somente modo RealityKit] Configurações relacionadas ao PolySpatial

No menu, clique em Edit > Project Settings > PolySpatial e faça:

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

• Marque Auto-Create Volume Camera

Se precisar especificar outro Default Volume Camera Window Config, garanta que seu Mode seja Unbounded.

Remova qualquer Volume Camera existente na cena.

Aviso

• Volume Camera com World Transform diferente de identity não é suportado.
• Se, por motivos específicos, for necessário adicionar um Volume Camera único e personalizado à cena:
  • Defina seu World Transform como identity.
  • Garanta que Volume Camera Window Configuration esteja com Mode definido como Unbounded.
  • Utilize-o apenas após compreender plenamente seu propósito e funcionalidade conforme a documentação oficial da Unity.

[Ao usar Mega] Adicionar location usage description

Cuidado

Se a permissão Location estiver habilitada nas configurações do EasyAR (para uso do Mega), você deve adicionar uma descrição de uso, caso contrário, o build falhará.

Como o campo Location Usage Description não é exibido em Project Settings > Player > visionOS no Unity atualmente, siga estas etapas:

1. Alternar aba da plataforma: Mude temporariamente para iOS.
2. Inserir descrição: Preencha a descrição necessária em Location Usage Description.
3. Voltar para visionOS: Retorne à aba visionOS; a configuração inserida será mantida e aplicada automaticamente.

Configuração em projetos Xcode

O projeto Xcode exportado pelo Unity requer as seguintes configurações:

Configurar permissão (entitlement) para dados da câmera

• Copie o arquivo Enterprise.license obtido para a pasta do projeto Xcode.

  

• Arraste o Enterprise.license da pasta do projeto Xcode para dentro do projeto no Xcode.

  

Modificar info.plist para permitir salvamento e compartilhamento de arquivos

Se seu aplicativo precisa gravar arquivos EIF e compartilhá-los via app Files do visionOS para computadores ou outros dispositivos, adicione/modifique estes campos no Info.plist:

• Adicione LSSupportsOpeningDocumentsInPlace e defina seu valor como true.

• Adicione UIFileSharingEnabled e defina seu valor como true.

Dica

Após adicionados, o Xcode pode exibir o Key de forma diferente da string inserida manualmente (ex: LSSupportsOpeningDocumentsInPlace aparece como Supports opening documents in place). Isso é normal.