Migrar um projeto do Unity 2019 para o Unity 2020 + OpenXR

Artigo
01/11/2025

Para uma migração mais tranquila, recomendamos que você conclua todas as etapas deste artigo na ordem apresentada. Aqui está uma visão geral das principais etapas:

Atualize o MRTK para a versão estável mais recente.
Mova seu projeto para o Unity 2019 XR Plug-in Management.
Escolha "Windows Mixed Reality".
Atualize para o Unity 2020.3 LTS.
Use a Ferramenta de Recursos de Realidade Misturada para instalar mais pacotes.
Configure o gerenciamento de plug-ins XR para OpenXR.

1. Atualize o MRTK para a versão estável mais recente

Se você já estiver usando o MRTK, sugerimos que a primeira etapa da migração seja executar a Ferramenta de Recursos de Realidade Misturada e atualizar para a versão estável mais recente do MRTK.

Selecione os recursos desejados

Observação

As descrições e imagens nesta seção são baseadas na versão mais recente da Ferramenta. Se as instruções não corresponderem ao que você está vendo, verifique se você não está usando uma versão mais antiga da ferramenta.

Abra a Ferramenta de Recursos de Realidade Misturada da Microsoft e clique no botão Iniciar .
Selecione o botão Procurar (é o botão de "três pontos" na imagem abaixo), navegue até o seu projeto e abra-o.
Selecione Descobrir Recursos.

Observação: talvez seja necessário aguardar alguns segundos enquanto a ferramenta atualiza os pacotes dos feeds.
Na página descobrir Recursos observe que há uma lista de seis grupos de pacotes.
Clique no botão "+" à esquerda do Realidade Misturada Toolkit e selecione a versão mais recente do Realidade Misturada Toolkit Foundation.

Importar os recursos

Depois de fazer suas seleções, clique em obter Recursos.
Na página importar Recursos, a coluna do lado esquerdo, Recursos, exibe os pacotes que você acabou de selecionar. A coluna do lado direito, Dependências Necessárias, exibe as dependências. Você pode clicar no link Detalhes em qualquer um desses itens para saber mais sobre eles.
Quando estiver pronto para continuar, selecione Importar. Na página Examinar e Aprovar, você pode revisar as informações sobre os pacotes.
Selecione Aprovar. A Ferramenta de Feição exibe uma mensagem informando que seu projeto foi atualizado.
Retorne ao editor do Unity e clique em uma área em branco na interface do usuário. Você verá uma mensagem informando que seus pacotes estão sendo importados.

Ao fazer essa atualização enquanto ainda usa o Unity 2019, você pode exibir o Configurador de Projetos do MRTK e ver todos os avisos de "API preterida" sobre como ficar atualizado. Os avisos lhe dirão o que mudar. Se você não fizer essa atualização do MRTK primeiro, a API antiga poderá ter desaparecido e você não terá esses avisos.

Saiba mais sobre a Ferramenta de Recursos de Realidade Misturada.

2. Mova seu projeto para o gerenciamento de plug-ins XR do Unity 2019

Depois de atualizar o MRTK, você pode instruir o Unity 2019 a usar o Gerenciamento de Plug-in XR.

No editor do Unity na barra de menus, selecione Editar>configurações do projeto.
Na coluna do lado esquerdo da janela Configurações do projeto, selecione Gerenciamento de plug-ins XR.

Neste ponto, você pode ver um botão rotulado Instalar o botão Gerenciamento de Plug-ins XR. Em caso afirmativo, continue com as etapas abaixo. Se você já tiver o sistema de gerenciamento XR instalado, poderá ignorar o restante das etapas nesta seção e continuar para a próxima seção, "Escolher 'Windows Mixed Reality'".

Clique no botão Instalar o Gerenciamento de Plug-in XR.
Uma caixa de diálogo chamada VR Detectado Integrado é exibida e pergunta se você deseja remover o pacote de VR integrado. Clique em OK.
A caixa de diálogo Builtin VR Enabled é exibida. Clique em OK. Isso desativa a RV integrada.
A janela Configurador de Projetos do MRTK é exibida e solicita que você habilite um pipeline XR. Selecione a segunda opção, Gerenciamento de XR SDK/SR.
Na próxima página do Configurador, clique em Mostrar configurações.

3. Escolha "Windows Mixed Reality"

Ainda não estamos prontos para instalar o OpenXR, mas este próximo conjunto de etapas ajuda você a limpar todas as APIs que estavam disponíveis e com suporte apenas no caminho "XR interno". (Se você estiver usando o MRTK, a maior parte disso será abstraída para você.)

Na janela Configurações do projeto do Unity Editor, verifique se você está na página Gerenciamento de plug-ins XR.
Realize um dos seguintes procedimentos:
- Se você estiver direcionando o HoloLens 2:
  Verifique se você está na guia Plataforma Universal do Windows (é a segunda guia e exibe o logotipo do Windows) e, em seguida, em Provedores de Plug-in, selecione Windows Mixed Reality.
- Se você estiver segmentando a RV para desktop:
  Verifique se você está na guia Área de Trabalho (é a primeira guia e exibe uma imagem de um monitor) e, em seguida, em Provedores de Plug-in, selecione Windows Mixed Reality.
A janela Configurador de Projetos do MRTK aparece novamente. Clique no botão Avançar e, em seguida, clique em Avançar novamente. (Você pode reservar um momento para ler as explicações nestas páginas antes de prosseguir.)
Selecione Importar TMP Essentials.
Selecione Concluído. Isso fecha o Configurador.
Feche a janela Configurações do projeto, salve seu projeto e saia do Unity.

4. Atualize para o Unity 2020.3 LTS

Instale a versão mais recente do patch LTS do Unity 2020.3.
Abra seu projeto do Unity 2019 no Unity 2020.3.

Você verá uma caixa de diálogo perguntando se deseja atualizar seu projeto para uma versão mais recente do Unity. Clique em CONFIRMAR.

Se você estava usando anteriormente o AR Foundation 2.0, o projeto o moverá automaticamente para o AR Foundation 4.0.

5. Use a Ferramenta de Recursos de Realidade Misturada para instalar mais pacotes

Use a Ferramenta de Recursos de Realidade Misturada para importar os pacotes abaixo.

Abra a lista suspensa Suporte à Plataforma e selecione a versão mais recente do Plug-in OpenXR de Realidade Misturada.
Depois que os pacotes são carregados, uma caixa de diálogo de aviso é exibida perguntando se você deseja reiniciar o editor do Unity para habilitar back-ends. Selecione Sim.
Quando o Unity é reaberto, o Configurador de Projetos do MRTK é exibido. Reserve um momento para ler as explicações na janela e selecione Aplicar.
Uma caixa de diálogo é exibida informando que o Unity deve ser reiniciado para que o sistema de entrada entre em vigor. Escolha Aplicar.

6. Configurar o gerenciamento de plug-ins XR para OpenXR

Depois que o Unity reabrir novamente, você poderá definir o OpenXR como o runtime:

Na barra de menu, selecione Editar>Configurações do projeto.

Examine a coluna do lado esquerdo e verifique se você está na página Gerenciamento de Plug-in XR e na guia Plataforma Universal do Windows (há uma imagem do logotipo do Windows na guia).
Na lista Provedores de Plug-in, selecione OpenXR.
Na mesma seção, selecione o grupo de recursos do Microsoft HoloLens.
Observe que agora há um triângulo amarelo de aviso ao lado de OpenXR. Focalize o cursor sobre o triângulo, leia a mensagem no pop-up e selecione o triângulo.
Na janela de Validação do Projeto do OpenXR , há vários problemas listados. Selecione o botão corrigir Tudo.
Um problema permanece e informa que você deve adicionar pelo menos um perfil de interação. Para fazer isso, clique em Editar. Isso leva você às configurações do plug-in OpenXR na janela Configurações do projeto.
Selecione o botão de sinal de mais (+) três vezes, cada vez escolhendo um perfil diferente:

Perfil de Interação do Foco Ocular

Perfil de Interação Manual da Microsoft

Perfil do Controlador de Movimento da Microsoft

Se o Perfil de Interação de Foco Ocular, ou qualquer outro perfil, aparecer com um triângulo amarelo ao lado dele, selecione o triângulo e, na janela Validação do Projeto do OpenXR, clique em Corrigir.
Na seção Grupos de Recursos do OpenXR, selecione Microsoft HoloLens e, em seguida, selecione Acompanhamento Manual e Modelo de Controlador de Movimento se eles ainda não estiverem selecionados.
Clique no menu suspenso Modo de Envio em Profundidade e selecione Profundidade de 16 bits.
Feche a janela Configurações do Projeto e todas as outras janelas que ainda estejam abertas.