Table of Contents

Guia de migração do EasyAR Sense Unity Plugin

Este artigo explica como migrar de versões antigas do EasyAR Sense Unity Plugin para versões novas.

Explicação de compatibilidade

A partir da versão 4000, o EasyAR Sense Unity Plugin segue o controle de versão de pacotes exigido pelo Unity (Semantic Versioning), então a compatibilidade pode ser avaliada pelo número da versão.

A versão 4.7 é uma versão de atualização gradual; quaisquer duas versões 4.7 são incompatíveis.

Antes da 4.7, apenas o terceiro número da versão indica compatibilidade retroativa. Mudanças nos dois primeiros números significam incompatibilidade. Por exemplo, 4.6.2 é compatível com 4.6.1, mas 4.6.0 não é compatível com 4.5.0.

Aviso

Modificar o arquivo tgz ou atualizar apenas parte do plugin após extrair causará incompatibilidade.

Guia geral de migração

Para migrar para uma versão nova, primeiro remova o pacote do plugin antigo pela Package Manager window e adicione o novo pacote.

Recomenda-se seguir os passos abaixo:

  1. Feche o Unity em uso.
  2. Exclua o diretório de build da plataforma gerado quando o Unity compila o aplicativo.
  3. Reabra o project Unity e remova a versão antiga do EasyAR Sense Unity Plugin do project.
  4. Importe a nova versão do EasyAR Sense Unity Plugin.

Nota

Os arquivos de exemplo fornecidos pelo plugin não garantem compatibilidade entre versões. Depois da atualização do plugin, os exemplos importados no project podem deixar de funcionar corretamente. Recomenda-se excluir os exemplos antigos antes de continuar.

O EasyAR inclui arquivos de biblioteca nativa. Se esses arquivos já tiverem sido usados antes de serem excluídos ou substituídos, o sistema os bloqueará e não será possível apagá-los nem substituí-los.

Importante

Antes de excluir a versão antiga, certifique-se de que nenhuma scene esteja em execução no editor e que nenhum aplicativo de plataforma esteja sendo compilado. Normalmente é recomendável fechar o Unity antes de excluir ou substituir o package e substituí-lo logo após reabrir.

Antes de compilar novamente com o plugin da nova versão, exclua primeiro os diretórios de build da plataforma gerados pelo Unity, incluindo o diretório Gradle do Android e o diretório Xcode do iOS.

Dica

Normalmente esses diretórios ficam na pasta Library do project Unity, por exemplo Library/Bee/Android/Prj/IL2CPP/Gradle, mas isso pode variar conforme a versão do Unity.

Se você já compilou e não encontra o diretório correspondente da plataforma, recomenda-se excluir toda a pasta Library.

Se após a migração aparecer a exception SchemaHashNotMatched, normalmente há duas possibilidades:

  1. Os passos anteriores não foram executados corretamente, então a atualização falhou ou ficou incompleta, ou o diretório de build gerado pelo Unity não foi atualizado corretamente. Se não for excluído manualmente, a chance de erro é alta. Recomenda-se seguir os passos sugeridos ou compilar novamente usando um project sem cache Library.
  2. O arquivo tgz do EasyAR foi modificado manualmente ou o plugin inteiro não foi atualizado completamente após a extração. Nesse caso, o EasyAR não pode garantir o uso correto, então é necessário baixar novamente o pacote correto e importá-lo.
Importante

Como os arquivos de biblioteca do EasyAR Sense e a localização desses arquivos após a build podem mudar, se você mantiver o project Gradle ou Xcode gerado pelo Unity, deve excluir antes todos os arquivos relacionados ao EasyAR, como EasyAR.aar, libEasyAR.so, easyar.framework e assim por diante.

Migrar para a versão 4003

Dica

Somente ao usar Mega existem mudanças incompatíveis; o uso de outras funções não é afetado.

Ao migrar da versão 4002 para 4003, além do guia geral acima, você também precisa observar o seguinte.

Mudanças no workflow de desenvolvimento Mega

Na versão 4003, o workflow de desenvolvimento Mega mudou bastante. Se antes você já usava outras funções do EasyAR Sense Unity Plugin, esse workflow parecerá mais familiar.

As principais mudanças incluem:

  • Mudanças nas funções do pacote com.easyar.mega
    • Para usar Mega, esse pacote não é mais obrigatório; mas para carregar model block no editor e ajudar a posicionar conteúdo, ele ainda é necessário.
    • Foi adicionada a opção de configuração Mega Block/Landmark support: ative antes da build.
  • Mudanças nas funções do editor
    • O carregamento de block mesh e outros dados não exige mais a tool Mega Studio, e mesmo que uma tool de anotação seja adicionada à scene, ela não pode ser usada para Unity development.
    • O painel do componente MegaBlockController fornece diretamente as funções de editor para block, tornando a gestão mais direta.
    • session verification tool oferece mais opções úteis de controle do Mega, substituindo as funções anteriores do Mega Studio e a área de teste do editor do MegaTrackerFrameFilter.
  • Mudanças no comportamento do target

Ao migrar da versão 4002 para 4003, o mais importante é reorganizar os block object na scene e substituir o grupo de node gerado anteriormente pelo Mega Studio pelo componente MegaBlockController:

  1. Exclua na scene o grupo de node gerado anteriormente pelo Mega Studio, incluindo o objeto MegaBlocks e todos os block object abaixo dele.
    • Se houver annotation node, eles também devem ser excluídos.
    • Se os block object tiverem content object abaixo deles, recomenda-se mover primeiro esses content object para outros node e manter o local transform inalterado.
  2. Adicione target tracking do Mega na scene.
    • Se a scene original tiver vários block object, será preciso criar vários target tracking do Mega.
    • Mova os content object que antes ficavam abaixo dos block object para os novos target tracking do Mega e mantenha o local transform inalterado.
    • Observe a configuração do id em MegaBlockController.Source; esse id deve ser igual ao id do block object original para que o runtime carregue corretamente.
    • Observe a configuração de MegaBlockController.Tracker para usar o MegaTrackerFrameFilter correto.
  3. Se a scene original tiver annotation node, você precisará criar manualmente node semelhantes para substituí-los.
  4. Se o project original tiver lógica para criar block no script, use em vez disso o método de Adicionar target tracking do Mega.
  5. Remova o script inválido do node filho Mega Tracker (MegaTrackerFrameFilter) sob AR Session (EasyAR).

Na maioria dos casos, depois de substituir os block node, o restante do content da scene não precisa ser alterado e pode funcionar normalmente.

Mudanças de API

Módulo API v4002 API v4003 Descrição
Mega MegaTrackerFrameFilter.BlockHolder MegaBlockController.Tracker Adicionar target tracking do Mega
No block node, o loader é configurado no lugar do block root que antes era configurado no tracker node.
Mega MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) MegaTrackerFrameFilter.SwitchEndPoint Controlar o processo de tracking do Mega
Mega MegaTrackerFrameFilter.SimulatorLocation MegaTrackerFrameFilter.SimulatorLocation
Mega CloudLocalizerFrameFilter.BlockHolder MegaBlockController.Tracker Adicionar target tracking do Mega
No block node, o loader é configurado no lugar do block root que antes era configurado no tracker node.
Mega CloudLocalizerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) CloudLocalizerFrameFilter.SwitchEndPoint Controlar o processo de tracking do Mega
Mega CloudLocalizerFrameFilter.SimulatorLocation CloudLocalizerFrameFilter.SimulatorLocation
Mega MegaLocalizationResponse.Blocks MegaLocalizationResponse.Blocks Controlar o processo de tracking do Mega
Mega Support EasyAR.Mega.Scene.BlockHolder - Função removida
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlock - Função removida
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRoot MegaBlockController.Tracker Adicionar target tracking do Mega
No block node, o loader é configurado no lugar do block root que antes era configurado no tracker node.
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType - Função removida
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy - Função removida
Mega Support EasyAR.Mega.Scene.BlockActiveController ActiveController Estratégia de active control aplicável a targets
Mega Support EasyAR.Mega.Scene.BlockController MegaBlockController Adicionar target tracking do Mega
Mega Support EasyAR.Mega.Scene.BlockRootController - Função removida
Mega Support EasyAR.Mega.Scene.LocalTransform LocalTransform
Mega Support EasyAR.Mega.Scene.Location Location
Mega Support EasyAR.Mega.Scene.LocationConverter - Função removida
Mega Support EasyAR.Mega.Scene.AnnotationNode - Função removida
Mega Support EasyAR.Mega.Scene.AnnotationGroup - Função removida
Mega Support EasyAR.Mega.Scene.NavPointGraph - Função removida

Migrar para a versão 4002

Ao migrar da versão 4001 para 4002, além do guia geral acima, você também precisa observar o seguinte.

Mudanças de API

Módulo API v4001 API v4002 Descrição
Função auxiliar Image.Image(Buffer, PixelFormat, int, int) Image.create

Migrar para a versão 4001

Dica

Somente ao usar Mega existem mudanças incompatíveis; o uso de outras funções não é afetado.

Ao migrar da versão 4000 para 4001, além do guia geral acima, você também precisa observar o seguinte.

Mudanças de API

Módulo API v4000 API v4001 Descrição
Mega MegaTrackerFrameFilter.ResultPoseType.EnableLocalization MegaTrackerFrameFilter.EnableLocalization Controlar o processo de tracking do Mega
Mega MegaTrackerFrameFilter.ResultPoseType.EnableStabilization - Função removida

Migração histórica

Ao migrar de versões anteriores a 4000, consulte:

Tópicos relacionados