Compartilhar via

Guia de migração do MRTK2 para o MRTK3

  • Artigo

Ao começar a usar o MRTK3, você observará que vários conceitos no MRTK v2 foram alterados, substituídos ou removidos. Este documento ajuda a preencher a lacuna entre os conceitos do MRTK v2 e os equivalentes do MRTK3.

Interações

O MRTK3 usa a estrutura do XRI (Kit de Ferramentas de Interação XR) do Unity para lidar com a interação e o Sistema de Entrada do Unity mais o OpenXR para a entrada.

Importante

Para desenvolvedores iniciantes no XRI, é recomendável examinar primeiro a Documentação de arquitetura do XRI do Unity. Toda a documentação do XRI também se aplica ao MRTK3, pois a maioria dos recursos de interação e entrada são simplesmente herdados do XRI.

Terminologia

Termo do MRTK v2 Termo do MRTK3 Descrição
Ponteiro Interagente Os interagentes executam interações em interativos. Alguns interagentes (mas não todos) são controlados por controladores, dos quais recebem ações de entrada e poses. Outros interagentes operam independentemente dos controladores.

O MRTK envia vários Interagentes personalizados que fornecem interações úteis de realidade misturada, além dos Interagentes básicos que o Unity já fornece. Os interagentes personalizados podem ser criados por meio da herança ou implementando as interfaces do Interagente (IXRHoverInteractor, IXRSelectInteractor etc.). Para obter mais informações, consulte a Documentação de arquitetura do interagente.
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler Interativo Os interativos são os destinatários das interações. O MRTK envia vários Interativos personalizados que fornecem interações úteis de realidade misturada, além dos Interativos básicos que o Unity já fornece. Os interativos personalizados podem ser criados por meio da herança ou implementando as interfaces do interativo (IXRHoverInteractable, IXRSelectInteractable etc.). Consulte a Documentação de arquitetura do interativo para obter mais informações sobre como o MRTK estende interativos do XRI.
Controller Controller Um ActionBasedController é uma coleção de ações de entrada do Unity que representa as associações relacionadas a um dispositivo específico. A coleção de ações de entrada pode ser derivada de vários dispositivos, pois não há uma relação direta entre ActionBasedControllers e dispositivos de entrada subjacentes. (A DeviceBasedController é um mapeamento 1:1 de um dispositivo de entrada, mas não os usamos.)

Muitos interagentes (ControllerBasedInteractors, especificamente) ouvem os controladores em busca de ações de entrada, ou seja, todos os ControllerBasedInteractors abaixo de um XRController terão a mesma ação de seleção.
Sistema de teletransporte Sistema de locomoção O Sistema de locomoção permite que o usuário se mova sobre a cena durante uma experiência do XR. O sistema do MRTK v2 permite hotspots básicos de teletransporte e teleportação, com alto grau de personalização para o cursor de teleportação e o comportamento do ponteiro. O XRI oferece os seguintes recursos adicionais para locomoção:
  • Um Snap Turn Provider que gira a plataforma em ângulos fixos
  • Um provedor de giro contínuo que gira suavemente a plataforma ao longo do tempo
  • Um provedor de movimentação contínua que move suavemente a sonda ao longo do tempo
Provedor de foco XR Interaction Manager O XRInteractionManager é o mecanismo do Unity que serve como intermediário entre os interagentes e interativos na cena. O XRInteractionManager do Unity sincroniza e arbitra todas as interações entre interagentes e interativos e permite maior flexibilidade quando comparado ao Provedor de foco herdado.
Mediador de ponteiro Gerenciador de modo de interação O novo Gerenciador de modo de interação é usado para habilitar/desabilitar conjuntos de interagentes, dependendo do contexto dentro da cena. Consulte a documentação do gerenciador de modos para obter mais informações.
SceneQuerymask Camadas de interação As camadas de interação do XRI permitem que os desenvolvedores filtrem quais interagentes podem agir sobre quais interativos. Essas camadas são distintas das camadas físicas do Unity.
Foco Passar o mouse Os interagentes emitem Hovers em interativos quando o interativo é um destino válido para o interagente. Geralmente, um Hover indica a intenção do interagente, como direcionamento com um raio, proximidade da mão para captura ou se o usuário estiver olhando para o objeto.
Selecionar/cutucar/agarrar/voz etc. Selecionar Os interagentes emitem Selects em interativos quando o interativo é um destino válido e o interagente opta por fazê-lo. Os ControllerBasedInteractors geralmente emitem Selects quando a ação de entrada selecionada do controlador correspondente é disparada. Outros interagentes podem ter uma lógica mais complexa para determinar quando as seleções devem ser emitidas para o interativo de destino.

O MRTK v2 lidou com diferentes tipos de interações com eventos e caminhos de códigos separados – ou seja, uma captação foi uma interação fundamentalmente diferente de um clique de raio ou uma cutucada, gerada por sistemas separados. No MRTK3, todas essas maneiras de "selecionar" um objeto são unificadas sob a mesma interação Select.

Desencorajamos fortemente os desenvolvedores de criar uma lógica de interação que dependa de um tipo específico de interação; em vez disso, escreva um código generalizável que responda genericamente a todos os Selects. Dessa forma, suas interações funcionam em todas as modalidades de entrada e, até mesmo, para tipos de interações que ainda não foram desenvolvidos. Consulte a Arquitetura do interativo para ler mais informações sobre o motivo pelo qual não recomendamos isso.
N/D Ativar Ativar é uma ação extra que pode ser gerada em um objeto que já foi selecionado. Por exemplo, se um usuário Selecionar uma arma de esguicho com a alça do controlador, o gatilho vai disparar com uma ação Ativar.
Provedor de Dados XRSubsystem + Provedor A maioria dos provedores de dados não é mais necessária no MRTK3, pois o Sistema de Entrada do Unity e o OpenXR lidam com a maioria das tarefas de entrada multiplataforma. No entanto, para algumas exceções ainda não cobertas pelo Unity, fornecemos XRSubsystems que podem fornecer dados em diferentes plataformas – por exemplo, a HandsAggregatorSubsystem e a SpeechSubsystem. Consulte a documentação de arquitetura de subsistemas para obter uma leitura mais conceitual em nossa abordagem de subsistemas.

Eventos

Termo do MRTK v2 Termo do XRI Observações
OnFocusEnter/Exit FirstHoverEnter
LastHoverExit		 Observe os prefixos First e Last. Esses prefixos estão incluídos nos nomes de eventos, porque qualquer número de Interagentes pode focalizar simultaneamente um Interativo. Você também pode ouvir cada foco individual entrar/sair com HoverEnter e HoverExit, embora, geralmente, seja menos útil do que monitorar o status geral de foco.
OnPointerDown/Up FirstSelectEnter
LastSelectExit		 Observe os prefixos First e Last. Esses prefixos estão incluídos nos nomes de eventos, porque qualquer número de Interagentes pode selecionar simultaneamente um Interativo (dependendo do modo de seleção). Você também pode ouvir cada seleção individual entrar/sair com SelectEnter e SelectExit, embora, geralmente, seja menos útil do que monitorar o status geral de seleção.
OnPointerDragged N/D Basta sondar as transformações de anexação interactorsSelecting com GetAttachTransform durante uma seleção. Tenha em mente que, dependendo do modo de seleção do interativo, um número não associado de interagentes pode selecionar (e manipular) um interativo.
OnSourcePoseChanged, OnSourceDetected, OnSourceLost N/D O XRI não gera esses eventos. Eles são tratados por meio do XRController monitorando seu dispositivo de entrada associado.

Componentes UX

Para ver a documentação completa sobre os componentes da experiência do usuário do MRTK3, confira as visões gerais dos pacotes de experiência do usuário: UX Core, UX Components e UX Components (Non-Canvas). Uma alteração importante no MRTK3 é a ênfase nos componentes de experiência do usuário de tela, que utilizam a interface do usuário do Unity. Também há um pacote para os componentes de experiência do usuário que não é de tela. Uma comparação entre a experiência do usuário de tela e que não é de tela pode ser encontrada aqui.

Observação

Os componentes Hand Coach, Tooltips, Object Collection, AppBar e Progress Indicator ainda não existem no MRTK3. Além disso, uma Toolbox e Text Prefabs otimizados não foram implementados. Este documento será atualizado à medida que componentes adicionais da experiência do usuário do MRTK3 forem adicionados


MRTK2 MRTK3 Observações
Buttons Canvas Button
Non-Canvas Button		 No MRTK3, os botões baseados na interface do usuário do Unity e os botões baseados no Colisor são renovados como botões de tela e que não são de tela.

As ferramentas internas para agrupar botões no MRTK3 incluem Button Group e ToggleCollection.

Encontre exemplos nas cenas CanvasUITearsheet e NonCanvasUITearsheet.
Slider Canvas Slider
Non-Canvas Slider		 Encontre um exemplo na cena HandInteractionExamples.
Dialog Dialog
Dialog API		 Encontre um exemplo na cena DialogExample.
Scrolling Collection VirtualizedScrollRectList Encontre um exemplo na cena VirtualizedScrollRectList. Atualmente, a documentação do MRTK3 está em andamento.
Slate Slate (Non-Canvas) Encontre um exemplo na cena SlateDrawingExample.
See-it, Say-it Label See-it, Say-it Label Encontre um exemplo na cena SeeItSayItExample.
Hand Menu Hand Menu Encontre um exemplo na cena HandMenuExamples.
Near Menu Near Menu Encontre um exemplo na cena NearMenuExamples.
System Keyboard System Keyboard Encontre um exemplo na cena HandInteractionExamples.
Fingertip Visualization Fingertip Visualization O FingerCursor script e o pré-fabricado são substituídos no MRTK3 e a ponta do dedo indicador é visualizada por meio dos MRTKPokeReticleVisualscripts , RingReticlee ReticleMagnetism . O pré-fabricado MRTK LeftHand Controller contém um exemplo de como usar esses componentes.
Constraint Manager Constraint Manager Encontre um exemplo na cena BoundsControlExamples.
Bounds Control Bounding Box Bounds Control O script BoundingBox foi substituído. BoundsControl fornece uma caixa delimitadora de tamanho automático, cujos visuais podem ser personalizados. Há vários pré-fabricados BoundingBox que podem ser usados em visuais.

Encontre um exemplo na cena BoundsControlExamples.
Object Manipulator Manipulation Handler Object Manipulator O Manipulation Handler foi preterido. Use Object Manipulator para a manipulação (mover, girar, dimensionar) de um objeto por qualquer interagente com uma transformação de anexação válida.

Encontre um exemplo na cena HandInteractionExamples.
Interactable StatefulInteractable Encontre um exemplo na cena InteractableButtonExamples.
Dwell InteractorDwellManager No MRTK2, um DwellHandler foi anexado aos objetos e fornecia eventos para tratar o início e o fim da espera. No MRTK3, há um InteractorDwellManager no GazeInteractor e um Far Rays no MRTK XR Rig, que usa StatefulInteractable para determinar se o objeto habilita a espera e, caso ele a habilite, ele seleciona o objeto durante o tempo de duração da espera.

Atualmente, a documentação do MRTK3 está em andamento.
Solvers Solvers Atualmente, os exemplos de cenas do MRTK3 estão em andamento.
Visual Theming Data Binding and Theming A estrutura de Associação de Dados e Temas do MRTK3 foi projetada para facilitar a criação de elementos visuais que possam ser preenchidos e atualizados de maneira dinâmica em runtime. Ainda não integrado à experiência do usuário de tela.

Configurações de entrada

Ações de entrada

O MRTK 3 usa o novo Pacote do Sistema de Entrada do Unity para ações de entrada. A maioria das configurações pode ser definida por meio de um ativo Input Action.

Tarefa MRTK 2 MRTK 3
Criar uma Input Action Perfil de Ações de Entrada Use um Mapa de Ações dentro do ativo Input Action.
Associe uma Input Action a um Controller Perfil de Mapeamento de Entrada do Controlador Defina a associação para uma ação com o ativo Input Action.

Ponteiros

Os ponteiros são anexados a interagentes no MRTK3. No MRTK XR Rig padrão, os interagentes são posicionados abaixo do MRTK RightHand Controller e do MRTK LeftHand Controller.

Tarefa MRTK 2 MRTK 3
Definir um pré-fabricado de visual para um ponteiro Propriedade Pointer Prefab no Perfil de Configuração de Ponteiro do MRTK 2. MonoBehaviours no MRTK RightHand Controller e MRTK LeftHand Controller no MRTK XR Rig. Por exemplo, MRTKPokeReticleVisual, MRTKLineVisual e MRTKRayReticleVisual.
Limitar as camadas com as quais podem ser feitas interações Propriedade Pointing Raycast Layer Masks no MRTK Pointer Profile. Isso se aplica a todos os ponteiros. Propriedade raycastMask no script Interactor.
Definir a extensão do raycast de ponteiro Propriedade Pointing Extent no MRTK Pointer Profile. Isso se aplica a todos os ponteiros. Propriedade maxRaycastDistance no script Interactor.
Definir a prioridade de ponteiros Controlado pelo DefaultPointerMediator ou por uma substituição. Configurado por meio do InteractionModeManager (um MonoBehaviour do MRTK3).

Gestos

Input Actions pode ser atribuído a vários métodos de entrada de gesto (atualmente, só há suporte para o Reconhecimento do Windows no HoloLens 2).

Tarefa MRTK 2 MRTK 3
Atribuir uma ação a um gesto Atribuir gestos à Input Action em MixedRealityGesturesProfile. Os gestos do HoloLens 2 já são reconhecidos por meio do plug-in do OpenXR.

Comandos de Fala

O KeywordRecognitionSubsystem pode ser habilitado para permitir comandos de fala no MRTK 3. Encontre mais informações na documentação sobre a Entrada de fala.

Tarefa MRTK 2 MRTK 3
Mapear os comandos de fala para Input Actions Speech Commands Profile no Input System Profile. Chame CreateOrGetEventForKeyword no KeywordRecongitionSubsystem com a palavra-chave e a ação.

Configuração do Controlador

Tarefa MRTK 2 MRTK 3
Configurar o comportamento do botão do controlador ControllerMappingProfile Mapa de ações no ativo Input Action.
Definir um pré-fabricado para visualização do controlador ControllerMappingProfile Definido nas configurações XRController. Por exemplo, a propriedade Model Prefab em ArticulatedHandController.