Migrar um projeto Unity 2019 para Unity 2020 + OpenXR

Artigo
01/11/2025

Para uma migração mais suave, 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 Mixed Reality Feature Tool para instalar mais pacotes.
Configure o gerenciamento de plug-ins XR para OpenXR.

1. Atualize o MRTK para a última versão estável

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

Selecione os recursos desejados

Nota

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 está a ver, verifique se não está a utilizar uma versão mais antiga da Ferramenta.

Abra a Microsoft Mixed Reality Feature Tool e clique no botão Iniciar .
Selecione o botão Procurar (é o botão "três pontos" na imagem abaixo), navegue até o seu projeto e abra-o.
Selecione Descobrir recursos.

Nota: Pode ser 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 Mixed Reality Toolkit e selecione a versão mais recente do Mixed Reality Toolkit Foundation.

Importar os recursos

Depois de fazer a(s) sua(s) seleção(õ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 todas as dependências. Você pode clicar no link Detalhes de qualquer um desses itens para saber mais sobre eles.
Quando estiver pronto para seguir em frente, selecione Importar. Na página Rever e Aprovar , pode rever as informações sobre os pacotes.
Selecione Aprovar. A Feature Tool exibe uma mensagem informando que seu projeto foi atualizado.
Retorne ao Editor 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 visualizar o Configurador de Projeto MRTK e ver quaisquer avisos de "API preterida" sobre como se atualizar. Os avisos indicar-lhe-ão o que deve mudar. Se você não fizer essa atualização do MRTK primeiro, a API antiga pode ter desaparecido e você não terá esses avisos.

Saiba mais sobre a Ferramenta de Recursos de Realidade Mista.

2. Mova seu projeto para o Unity 2019 XR Plug-in Management

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

No editor 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.

Como este ponto, você pode ver um botão chamado Instalar XR Plugin Management botão. Em caso afirmativo, continue com os passos abaixo. Se você já tiver o sistema de gerenciamento XR instalado, poderá pular o restante das etapas nesta seção e continuar para a próxima seção, "Escolha 'Windows Mixed Reality'".

Clique no botão Instalar gerenciamento de plug-ins XR.
Uma caixa de diálogo chamada Built in VR Detected (Construído em VR detetado) é exibida e pergunta se você deseja remover o pacote VR interno. Clique em OK.
A caixa de diálogo Builtin VR Enabled (Integrado em VR habilitado ) é exibida. Clique em OK. Isso desativa a RV integrada.
A janela MRTK Project Configurator é exibida e solicita que você habilite um pipeline XR. Selecione a segunda opção, XR SDK/SR Management.
Na página seguinte do Configurador, clique em Mostrar Definiçõ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 só estavam disponíveis e eram suportadas no caminho "XR integrado". (Se você estiver usando MRTK, a maior parte disso é abstraída para você.)

Na janela Configurações do projeto do Unity Editor, verifique se você está na página Gerenciamento de plug-in XR.
Proceda de uma das seguintes formas:
- Se você estiver segmentando o HoloLens 2:
  Certifique-se de que está no separador Plataforma Universal do Windows (é o segundo separador e apresenta o logótipo do Windows) e, em seguida, em Fornecedores de Plug-in, selecione Windows Mixed Reality.
- Se você estiver segmentando o Desktop VR:
  Certifique-se de que está no separador Ambiente de Trabalho (é o primeiro separador e apresenta uma imagem de um monitor) e, em seguida, em Fornecedores de Plug-ins, selecione Windows Mixed Reality.
A janela MRTK Project Configurator 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.
Selecionar 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 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 irá movê-lo automaticamente para o AR Foundation 4.0.

5. Use a ferramenta de recurso de realidade mista para instalar mais pacotes

Use a Mixed Reality Feature Tool para importar os pacotes abaixo.

Abra a lista suspensa Suporte à plataforma e selecione a versão mais recente do plug-in OpenXR de realidade mista.
Depois que os pacotes são carregados, uma caixa de diálogo Aviso é exibida perguntando se você deseja reiniciar o editor Unity para habilitar back-ends. Selecione Yes (Sim).
Quando o Unity reabre, o Configurador de Projeto MRTK é exibido. Reserve um momento para ler as explicações na janela e, em seguida, selecione Aplicar.
Uma caixa de diálogo é exibida informando que o Unity deve ser reiniciado para que o sistema de entrada entre em vigor. Selecione Aplicar.

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

Depois que o Unity reabrir novamente, você pode definir o OpenXR como o tempo de execução:

Na barra de menus, selecione Editar>configurações do projeto.

Procure na coluna do lado esquerdo e certifique-se de que está na página Gestão de Plug-ins XR e no separador Plataforma Universal do Windows (existe uma imagem do logótipo do Windows no separador).
Na lista Provedores de plug-in, selecione OpenXR.
Na mesma seção, selecione Microsoft HoloLens feature group.
Observe que agora há um triângulo de aviso amarelo ao lado do OpenXR. Passe o cursor sobre o triângulo, leia a mensagem no pop-up e selecione o triângulo.
Na janela Validação do projeto OpenXR, há vários problemas listados. Selecione o botão Corrigir tudo .
Um problema permanece e diz 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 adição (+) três vezes, cada vez escolhendo um perfil diferente:

Perfil de Interação do Olhar

Perfil de interação do Microsoft Hand

Perfil do controlador de movimento da Microsoft

Se o Perfil de Interação do Olhar Ocular, ou qualquer outro perfil, aparecer com um triângulo amarelo ao lado, selecione o triângulo e, na janela Validação do Projeto OpenXR, clique no botão Corrigir.
Na seção OpenXR Feature Groups, selecione Microsoft HoloLens e, em seguida, selecione Hand Tracking and Motion Controller Model se ainda não estiverem selecionados.
Clique na lista suspensa Modo de envio de profundidade e selecione Profundidade de 16 bits.
Feche a janela Configurações do projeto e quaisquer outras janelas que ainda estejam abertas.