Guia de migração de MRTK2 para MRTK3

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

Interações

O MRTK3 usa a estrutura XR Interaction Toolkit (XRI) da Unity para lidar com a interação, e o Unity Input System mais OpenXR para entrada.

Importante

Para desenvolvedores novos no XRI, recomendamos que você primeiro revise a documentação da arquitetura 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 MRTK v2	Termo MRTK3	Description
Ponteiro	Interator	Os interatores realizam interações em Interactables. Alguns (mas não todos) Interatores são conduzidos por Controladores, dos quais recebem ações de entrada e poses. Outros intervenientes operam independentemente dos controladores. O MRTK envia vários Interatores personalizados que fornecem interações úteis de realidade mista além dos Interatores básicos que o Unity já oferece. Os interatores personalizados podem ser construídos por herança ou implementando as interfaces Interator (IXRHoverInteractor, IXRSelectInteractor, e assim por diante). Para obter mais informações, consulte a documentação da arquitetura Interactor.
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler	Interacionável	Os interactables são os destinatários das interações. O MRTK envia vários Interactables personalizados que fornecem interações úteis de realidade mista além dos Interactables básicos que o Unity já fornece. Interactables podem ser construídos através de herança ou implementando as interfaces interactable (IXRHoverInteractable, IXRSelectInteractable, e assim por diante). Para obter mais informações sobre como o MRTK estende as interactables XRI, consulte a documentação da arquitetura Interactable.
Comando	Comando	Um ActionBasedController é uma coleção de Unity Input Actions que representa as associações associadas 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 1:1 entre ActionBasedControllers os dispositivos de entrada subjacentes e os mesmos. (A DeviceBasedController é um mapeamento 1:1 de um dispositivo de entrada, mas não os usamos.) Muitos interatores (ControllerBasedInteractorespecificamente) ouvem os controladores para ações de entrada - em outras palavras, todos os ControllerBasedInteractors abaixo de um XRController compartilham 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 pela cena durante uma experiência XR. O sistema MRTK v2 permite o teletransporte básico e hotspots de teletransporte, com um alto grau de personalização para o cursor de teletransporte e comportamento do ponteiro. O XRI oferece os seguintes recursos adicionais para locomoção: Um Snap Turn Provider que gira o equipamento por ângulos fixos Um Provedor de Giro Contínuo que gira suavemente o equipamento ao longo do tempo Um Provedor de Movimentação Contínua que move suavemente a plataforma ao longo do tempo
Provedor de foco	Gerenciador de interação XR	O XRInteractionManager é o mecanismo Unity que serve como intermediário entre os Interactores e Interactables na cena. O Unity XRInteractionManager sincroniza e arbitra todas as interações entre Interatores e Interactables, e permite uma flexibilidade significativamente maior quando comparado ao Provedor de Foco legado.
Mediador de Ponteiros	Gestor do Modo de Interação	O novo Gerenciador de Modo de Interação é usado para ativar/desabilitar conjuntos de interatores, 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 XRI permitem que os desenvolvedores filtrem quais Interatores podem agir sobre quais Interactables. Essas camadas são distintas das camadas físicas de Unity.
Foco	Sensível à Passagem do Rato	Os interatores emitem Hovers em Interactables quando o Interactable é um alvo válido para o Interactor. Geralmente, um Hover indica a intenção do interator, como mirar com um raio, proximidade da mão para agarrar ou se o usuário está olhando para o objeto.
Selecionar/Cutucar/Agarrar/Voz, etc.	Selecione	Interactores emitem Selects on Interactables quando o Interactable é um destino válido e o Interactor escolhe fazê-lo. ControllerBasedInteractors geralmente emite Selects quando a ação de entrada select do controlador correspondente é acionada. Outros intervenientes podem ter uma lógica mais complexa para determinar quando devem ser emitidas seleções para o Interactable visado. O MRTK v2 lidava com diferentes tipos de interações com eventos e caminhos de código separados - em outras palavras, um grab era uma interação fundamentalmente diferente de um ray click ou poke, gerado 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 construir uma lógica de interação que dependa de um tipo específico de interação; em vez disso, escreva 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 precisam ser desenvolvidas. Veja a arquitetura interativa para ler mais sobre por que desencorajamos este curso.
N/A	Activar	Activate é uma ação extra que pode ser acionada em um objeto que já foi selecionado. Por exemplo, se um usuário seleciona uma arma de esguicho com o punho do controlador, o gatilho a dispara com uma ação Ativar.
Fornecedor de Dados	XRSubsystem + Provedor	A maioria dos provedores de dados não são mais necessários no MRTK3, uma vez que o Unity Input System e o OpenXR lidam com a maioria das tarefas de entrada entre plataformas. No entanto, para alguns outliers que ainda não são cobertos pelo Unity, fornecemos XRSubsystems que podem fornecer dados em diferentes plataformas - por exemplo, HandsAggregatorSubsystem e SpeechSubsystem. Consulte a documentação da arquitetura de subsistemas para obter uma leitura mais conceitual sobre nossa abordagem de subsistemas.

evento

Termo MRTK v2	Termo XRI	Notas
OnFocusEnter/Exit	FirstHoverEnter LastHoverExit	Observe os prefixos First e Last . Esses prefixos são incluídos nos nomes dos eventos porque qualquer número de Interatores pode pairar simultaneamente sobre um Interactable. Você também pode ouvir cada entrada/saída de foco individual com HoverEnter e HoverExit, embora seja menos útil do que monitorar o status geral do foco.
OnPointerDown/Up	FirstSelectEnter LastSelectExit	Observe os prefixos First e Last . Esses prefixos são incluídos nos nomes dos eventos porque qualquer número de Interatores pode selecionar simultaneamente um Interactable (dependendo do modo de seleção). Você também pode ouvir cada seleção individual entrar/sair com SelectEnter e SelectExit, embora seja menos útil do que monitorar o status geral da seleção.
OnPointerDragged	N/A	Basta sondar as interactorsSelecting transformações anexadas durante GetAttachTransform uma seleção. Tenha em mente que, dependendo do modo de seleção do Interactable, um número ilimitado de Interactores pode selecionar (e manipular) um Interactable.
OnSourcePoseChanged, OnSourceDetected, OnSourceLost	N/A	XRI não levanta esses eventos. Eles são manipulados através do XRController monitorando seu dispositivo de entrada associado.

Componentes UX

Para obter a documentação completa sobre os componentes MRTK3 UX, consulte as visões gerais dos pacotes UX: UX Core, UX Componentse UX Components (Non-Canvas). Uma grande mudança no MRTK3 é a ênfase nos componentes do Canvas UX, que utilizam a interface do usuário Unity. Há também um pacote para componentes UX não-Canvas. Uma comparação entre Canvas e Non-Canvas UX pode ser encontrada aqui.

Nota

Hand Coach, Tooltips, Object Collection, AppBar, e Progress Indicator componentes ainda não existem no MRTK3. Além disso, Toolbox e otimizado Text Prefabs não são implementados. Este documento será atualizado à medida que componentes MRTK3 UX adicionais forem adicionados

MRTK2	MRTK3	Notas
Buttons	Canvas Button Non-Canvas Button	No MRTK3, os botões baseados em Unity UI e Collider são renovados como botões Canvas e Non-Canvas. As ferramentas incorporadas para agrupar botões no MRTK3 incluem Button Group e ToggleCollection. Amostras podem ser encontradas nas CanvasUITearsheet NonCanvasUITearsheet e cenas.
Slider	Canvas Slider Non-Canvas Slider	Uma amostra pode ser encontrada na HandInteractionExamples cena.
Dialog	Dialog Dialog API	Uma amostra pode ser encontrada na DialogExample cena.
Scrolling Collection	VirtualizedScrollRectList	Uma amostra pode ser encontrada na VirtualizedScrollRectList cena. A documentação do MRTK3 está atualmente em andamento.
Slate	Slate (Non-Canvas)	Uma amostra pode ser encontrada na SlateDrawingExample cena.
See-it, Say-it Label	See-it, Say-it Label	Uma amostra pode ser encontrada na SeeItSayItExample cena.
Hand Menu	Hand Menu	Uma amostra pode ser encontrada na HandMenuExamples cena.
Near Menu	Near Menu	Uma amostra pode ser encontrada na NearMenuExamples cena.
System Keyboard	System Keyboard	Uma amostra pode ser encontrada na HandInteractionExamples cena.
Fingertip Visualization	Fingertip Visualization	O FingerCursor script e o pré-fabricado são substituídos no MRTK3 e a ponta do dedo indicador é visualizada através dos MRTKPokeReticleVisualscripts , RingReticlee ReticleMagnetism . O MRTK LeftHand Controller pré-fabricado contém um exemplo de como usar esses componentes.
Constraint Manager	Constraint Manager	Uma amostra pode ser encontrada na BoundsControlExamples cena.
Bounds Control Bounding Box	Bounds Control	O BoundingBox script foi substituído. BoundsControl fornece uma caixa delimitadora de tamanho automático, cujos elementos visuais podem ser personalizados. Existem vários BoundingBox pré-fabricados que podem ser usados para efeitos visuais. Uma amostra pode ser encontrada na BoundsControlExamples cena.
Object Manipulator Manipulation Handler	Object Manipulator	Manipulation Handler foi preterido. Use Object Manipulator para a manipulação (mover, girar, escalar) de um objeto por qualquer interator com uma transformação de anexação válida. Uma amostra pode ser encontrada na HandInteractionExamples cena.
Interactable	StatefulInteractable	Uma amostra pode ser encontrada na InteractableButtonExamples cena.
Dwell	InteractorDwellManager	No MRTK2, a DwellHandler foi anexado a objetos e forneceu eventos para lidar com o início e o fim da morada. No MRTK3, há um InteractorDwellManager on the GazeInteractor e Far Rays no MRTK XR Rig, que usa StatefulInteractable para determinar se o objeto permite habitar ou não, e se o faz seleciona o objeto para a duração da permanência. A documentação do MRTK3 está atualmente em andamento.
Solvers	Solvers	As cenas de amostra do MRTK3 estão atualmente em andamento.
Visual Theming	Data Binding and Theming	A estrutura MRTK3 Data Binding and Theming foi projetada para facilitar a criação de elementos visuais que podem ser preenchidos e atualizados dinamicamente em tempo de execução. Ainda não integrado com o Canvas UX.

Configurações de entrada

Ações de entrada

O MRTK 3 usa o novo Unity Input System Package para ações de entrada. A maioria das configurações pode ser configurada por meio de um Input Action ativo.

Task	MRTK 2	MRTK 3
Criar um Input Action	Perfil de ações de entrada	Use um Mapa de Ação dentro do Input Action ativo.
Vincular um Input Action a um Controller	Perfil de mapeamento de entrada do controlador	Defina a associação para uma ação com o Input Action ativo.

Sugestões

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

Task	MRTK 2	MRTK 3
Definir um pré-fabricado visual para um ponteiro	Pointer Prefabno MRTK 2 Pointer Configuration Profile.	MonoComportamentos no MRTK RightHand Controller e MRTK LeftHand Controller no MRTK XR Rig. Por exemplo, MRTKPokeReticleVisual, MRTKLineVisual, e MRTKRayReticleVisual.
Limitar com quais camadas podem ser interagidas	Pointing Raycast Layer Masks propriedade em MRTK Pointer Profile. Isto aplica-se a todos os indicadores.	raycastMaskInteractor no script.
Definir a extensão de um raycast de ponteiro	Pointing Extent propriedade em MRTK Pointer Profile. Isto aplica-se a todos os indicadores.	maxRaycastDistanceInteractor no script.
Definir a prioridade dos ponteiros	Controlado pelo DefaultPointerMediator ou uma substituição.	Configurado através do InteractionModeManager (um MRTK3 MonoBehaviour).

Gestos

Input Actions pode ser atribuído a vários métodos de entrada por gestos (atualmente apenas suportado para Reconhecimento do Windows no HoloLens 2).

Task	MRTK 2	MRTK 3
Atribuir uma ação a um gesto	Atribua gestos a Input Action em MixedRealityGesturesProfile.	Os gestos no HoloLens 2 são agora reconhecidos através do plugin OpenXR.

Comandos de fala

O KeywordRecognitionSubsystem pode ser ativado para permitir comandos de fala no MRTK 3. Mais informações podem ser encontradas na documentação sobre Speech Input.

Task	MRTK 2	MRTK 3
Mapeie comandos de fala para Input Actions	Speech Commands ProfileInput System Profileno .	Ligue CreateOrGetEventForKeyword para o com a KeywordRecongitionSubsystem sua palavra-chave e ação.

Configuração do controlador

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