Guía de migración de MRTK2 a MRTK3

Cuando empiece a usar MRTK3, observará que varios conceptos de MRTK v2 se han cambiado, reemplazado o quitado. Este documento ayuda a salvar la brecha entre los conceptos de MRTK v2 y sus homólogos de MRTK3.

Interacciones

MRTK3 usa el marco XR Interaction Toolkit (XRI) de Unity para controlar la interacción y el sistema de entrada de Unity y OpenXR para la entrada.

Importante

Para los desarrolladores que no están familiarizados con XRI, se recomienda revisar primero la documentación de arquitectura XRI de Unity. Toda la documentación de XRI también se aplica a MRTK3, ya que la mayoría de las características de interacción y entrada simplemente se heredan de XRI.

Terminología

Término de MRTK v2	Término MRTK3	Descripción
Puntero	Interactor	Los interactuantes realizan interacciones en interactables. Algunos interactúantes (pero no todos) están controlados por controladores, desde los que reciben acciones de entrada y poses. Otros interactuadores funcionan independientemente de los controladores. MRTK incluye varios interactores personalizados que proporcionan interacciones útiles de realidad mixta además de los interactores básicos que Unity ya proporciona. Los interactores personalizados se pueden crear a través de la herencia o implementando las interfaces interactor (IXRHoverInteractor, IXRSelectInteractor, etc.). Para obtener más información, consulte la documentación de arquitectura de Interactor.
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler	Interactable	Los interactables son los destinatarios de las interacciones. MRTK incluye varios interactables personalizados que proporcionan interacciones útiles de realidad mixta además de las funciones básicas que Unity ya proporciona. Los elementos interactables se pueden crear a través de la herencia o implementando las interfaces interactables (IXRHoverInteractable, IXRSelectInteractable, etc.). Para obtener más información sobre cómo MRTK amplía los elementos interactables de XRI, consulte la documentación de la arquitectura interactable.
Controlador	Controlador	ActionBasedController es una colección de acciones de entrada de Unity que representan los enlaces asociados a un dispositivo determinado. La colección de acciones de entrada se puede derivar de varios dispositivos, ya que no hay una relación 1:1 entre ActionBasedControllers los dispositivos de entrada subyacentes. (A DeviceBasedController es una asignación 1:1 de un dispositivo de entrada, pero no los usamos). Muchos interactuadores (ControllerBasedInteractoren concreto) escuchan a los controladores para las acciones de entrada; es decir, todos los ControllerBasedInteractorque están debajo de un XRController comparten la misma acción de selección.
Sistema de teletransporte	Sistema de locomoción	El sistema Locomotion permite al usuario moverse por la escena durante una experiencia XR. El sistema MRTK v2 permite teleportaciones básicas y puntos de acceso de teletransporte, con un alto grado de personalización para el comportamiento de cursor y puntero de teletransporte. XRI ofrece las siguientes funcionalidades agregadas para la locomoción: Un proveedor de giro de ajuste que gira la plataforma por ángulos fijos Un proveedor de turnos continuo que gira sin problemas el equipo a lo largo del tiempo Un proveedor de movimiento continuo que mueve sin problemas el equipo a lo largo del tiempo
Proveedor de foco	Administrador de interacción de XR	XRInteractionManager es el mecanismo de Unity que actúa como intermediario entre los interactuadores e interactables de la escena. Unity XRInteractionManager sincroniza y arbitra todas las interacciones entre interactuadores e interactables, y permite una flexibilidad significativamente mayor en comparación con el proveedor de foco heredado.
Mediador de puntero	Administrador del modo de interacción	El nuevo Administrador de modo de interacción se usa para habilitar o deshabilitar conjuntos de interactuantes en función del contexto dentro de la escena. Consulte la documentación del administrador de modo para obtener más información.
SceneQuerymask	Capas de interacción	Las capas de interacción de XRI permiten a los desarrolladores filtrar qué interactuadores pueden actuar sobre los que interactables. Estas capas son distintas de las capas de física de Unity.
Foco	Cernerse	El problema de los interactuantes mantiene el puntero sobre interactables cuando interactable es un destino válido para el interactor. Por lo general, un puntero indica la intención del interactuador, como el destino con un rayo, la proximidad de la mano para la toma o si el usuario está mirando el objeto.
Seleccione/Poke/Grab/Voice, etc.	Seleccionar	Problema de los interactuantes Selecciona en Interactables cuando interactable es un destino válido y el interactor elige hacerlo. ControllerBasedInteractors suele emitir Selecciones cuando se activa la acción de entrada de selección del controlador correspondiente. Otros interactuantes pueden tener una lógica más compleja para determinar cuándo se deben emitir selecciones al interactable de destino. MRTK v2 controlaba diferentes tipos de interacciones con eventos y rutas de código independientes; es decir, una toma era una interacción fundamentalmente diferente de un clic o un poke de rayos, generados por sistemas independientes. En MRTK3, todas estas formas de "seleccionar" un objeto se unifican en la misma interacción Seleccionar . Desaconsejamos encarecidamente a los desarrolladores crear lógica de interacción que se base en un tipo específico de interacción; en su lugar, escriba código generalizable que responda genéricamente a todas las selecciones. De este modo, las interacciones funcionan en todas las modalidades de entrada e incluso en los tipos de interacciones que aún no se han desarrollado. Consulte la arquitectura interactable para obtener más información sobre por qué desaconsejamos este curso.
N/D	Activar	Activar es una acción adicional que se puede generar en un objeto que ya se ha seleccionado. Por ejemplo, si un usuario selecciona una pistola de chorro con el agarre del controlador, el desencadenador la activa con una acción Activar.
Data Provider	XRSubsystem + Provider	La mayoría de los proveedores de datos ya no son necesarios en MRTK3, ya que el sistema de entrada de Unity y OpenXR controlan la mayoría de las tareas de entrada multiplataforma. Sin embargo, para algunos valores atípicos que aún no están cubiertos por Unity, proporcionamos XRSubsystems que pueden proporcionar datos en distintas plataformas( por ejemplo, HandsAggregatorSubsystem y SpeechSubsystem. Consulte la documentación de arquitectura de subsistemas para obtener más lectura conceptual sobre nuestro enfoque de subsistemas.

Eventos

Término de MRTK v2	Término XRI	Notas
OnFocusEnter/Exit	FirstHoverEnter LastHoverExit	Anote los First prefijos y Last . Estos prefijos se incluyen en los nombres de evento porque cualquier número de interactuadores puede mantener el puntero al mismo tiempo sobre un interactable. También puede escuchar cada puntero individual entrar o salir con HoverEnter y HoverExit, aunque es menos útil que supervisar el estado general del mouse.
OnPointerDown/Up	FirstSelectEnter LastSelectExit	Anote los First prefijos y Last . Estos prefijos se incluyen en los nombres de evento porque cualquier número de interactuadores puede seleccionar simultáneamente un interactable (dependiendo del modo de selección). También puede escuchar a cada selección individual entrar o salir con SelectEnter y SelectExit, aunque es menos útil que supervisar el estado de selección general.
OnPointerDragged	N/D	Basta con sondear las interactorsSelecting transformaciones de asociación con GetAttachTransform durante una selección. Tenga en cuenta que, en función del modo de selección de Interactable, un número ilimitado de interactuadores puede seleccionar (y manipular) un Interactable.
OnSourcePoseChanged, OnSourceDetected, OnSourceLost	N/D	XRI no genera estos eventos. Se controlan a través de la supervisión de XRController de su dispositivo de entrada asociado.

Componentes de la experiencia de usuario

Para obtener documentación completa sobre los componentes de la experiencia de usuario de MRTK3, consulte la información general de los paquetes de experiencia de usuario: UX Core, UX Componentsy UX Components (Non-Canvas). Un cambio importante en MRTK3 es el énfasis en los componentes de experiencia de usuario de Canvas, que usan la interfaz de usuario de Unity. También hay un paquete para componentes de experiencia de usuario que no son de Canvas. Puede encontrar una comparación entre canvas y experiencia de usuario que no sea de Canvas aquí.

Nota

Hand CoachLos componentes , Tooltips, Object Collection, AppBary Progress Indicator aún no existen en MRTK3. Además, Toolbox no se implementan y se optimizan Text Prefabs . Este documento se actualizará a medida que se agreguen componentes de experiencia de usuario de MRTK3 adicionales.

MRTK2	MRTK3	Notas
Buttons	Canvas Button Non-Canvas Button	En MRTK3, los botones basados en la interfaz de usuario de Unity y los botones basados en collider se renuevan como botones canvas y no canvas. Las herramientas integradas para agrupar botones en MRTK3 incluyen Button Group y ToggleCollection. Se pueden encontrar ejemplos en las CanvasUITearsheet escenas y NonCanvasUITearsheet .
Slider	Canvas Slider Non-Canvas Slider	Se puede encontrar un ejemplo en la HandInteractionExamples escena.
Dialog	Dialog Dialog API	Se puede encontrar un ejemplo en la DialogExample escena.
Scrolling Collection	VirtualizedScrollRectList	Se puede encontrar un ejemplo en la VirtualizedScrollRectList escena. La documentación de MRTK3 está en curso.
Slate	Slate (Non-Canvas)	Se puede encontrar un ejemplo en la SlateDrawingExample escena.
See-it, Say-it Label	See-it, Say-it Label	Se puede encontrar un ejemplo en la SeeItSayItExample escena.
Hand Menu	Hand Menu	Se puede encontrar un ejemplo en la HandMenuExamples escena.
Near Menu	Near Menu	Se puede encontrar un ejemplo en la NearMenuExamples escena.
System Keyboard	System Keyboard	Se puede encontrar un ejemplo en la HandInteractionExamples escena.
Fingertip Visualization	Fingertip Visualization	El FingerCursor script y el objeto prefabricado se reemplazan en MRTK3 y el índice se visualiza a través de los MRTKPokeReticleVisualscripts , RingReticley ReticleMagnetism . El MRTK LeftHand Controller objeto prefabricado contiene un ejemplo de cómo usar estos componentes.
Constraint Manager	Constraint Manager	Se puede encontrar un ejemplo en la BoundsControlExamples escena.
Bounds Control Bounding Box	Bounds Control	Se ha reemplazado el BoundingBox script. BoundsControl proporciona un cuadro delimitador de tamaño automático, cuyos objetos visuales se pueden personalizar. Hay varios BoundingBox objetos prefabricados que se pueden usar para objetos visuales. Se puede encontrar un ejemplo en la BoundsControlExamples escena.
Object Manipulator Manipulation Handler	Object Manipulator	Manipulation Handler está en desuso. Use Object Manipulator para la manipulación (movimiento, rotación, escala) de un objeto por parte de cualquier interactor con una transformación de asociación válida. Se puede encontrar un ejemplo en la HandInteractionExamples escena.
Interactable	StatefulInteractable	Se puede encontrar un ejemplo en la InteractableButtonExamples escena.
Dwell	InteractorDwellManager	En MRTK2, DwellHandler se adjuntaba a objetos y se proporcionaba eventos para controlar el inicio y el final de la permanencia. En MRTK3, hay un InteractorDwellManager en GazeInteractor y Far Rays en , MRTK XR Rigque usa StatefulInteractable para determinar si el objeto permite la permanencia o no, y si lo hace selecciona el objeto durante el período de permanencia. La documentación de MRTK3 está en curso.
Solvers	Solvers	Las escenas de ejemplo de MRTK3 están actualmente en curso.
Visual Theming	Data Binding and Theming	MrTK3 Data Binding and Theming Framework está diseñado para facilitar la creación de elementos visuales que se pueden rellenar y actualizar dinámicamente en tiempo de ejecución. Aún no se ha integrado con la experiencia de usuario de Canvas.

Configuraciones de entrada

Acciones de entrada

MRTK 3 usa el nuevo paquete del sistema de entrada de Unity para las acciones de entrada. La mayoría de la configuración se puede configurar a través de un Input Action recurso.

Tarea	MRTK 2	MRTK 3
Creación de un objeto Input Action	Perfil de acciones de entrada	Use un mapa de acciones dentro del Input Action recurso.
Enlazar un Input Action objeto a un Controller	Perfil de asignación de entrada del controlador	Establezca el enlace de una acción con el Input Action recurso.

Punteros

Los punteros se adjuntan a los interactuantes en MRTK3. En el valor predeterminado MRTK XR Rig, los interactuantes se colocan debajo de MRTK RightHand Controller y MRTK LeftHand Controller.

Tarea	MRTK 2	MRTK 3
Establecimiento de un objeto prefabricado visual para un puntero	Pointer Prefab propiedad en mrtk 2 perfil de configuración de puntero.	MonoBehaviours en MRTK RightHand Controller y MRTK LeftHand Controller en .MRTK XR Rig Por ejemplo, MRTKPokeReticleVisual, MRTKLineVisualy MRTKRayReticleVisual.
Límite de las capas con las que se puede interactuar	Pointing Raycast Layer Masks propiedad en MRTK Pointer Profile. Esto se aplica a todos los punteros.	raycastMask en el Interactor script.
Establecer la extensión de un raycast de puntero	Pointing Extent propiedad en MRTK Pointer Profile. Esto se aplica a todos los punteros.	maxRaycastDistance en el Interactor script.
Establecer la prioridad de los punteros	Controlado por DefaultPointerMediator o una invalidación.	Configurado a través de InteractionModeManager (un MonoBehaviour de MRTK3).

Gestualidad

Input Actionsse puede asignar a varios métodos de entrada de gestos (actualmente solo se admite para el reconocimiento de Windows en HoloLens 2).

Tarea	MRTK 2	MRTK 3
Asignación de una acción a un gesto	Asigne gestos a Input Action en MixedRealityGesturesProfile.	Los gestos en HoloLens 2 ahora se reconocen a través del complemento OpenXR.

Comandos de voz

KeywordRecognitionSubsystem se puede habilitar para permitir comandos de voz en MRTK 3. Puede encontrar más información en la documentación sobre la entrada de voz.

Tarea	MRTK 2	MRTK 3
Asignación de comandos de voz a Input Actions	Speech Commands Profileen .Input System Profile	Llame a CreateOrGetEventForKeyword con la KeywordRecongitionSubsystem palabra clave y la acción.

Configuración del controlador

Tarea	MRTK 2	MRTK 3
Configuración del comportamiento de los botones del controlador	ControllerMappingProfile	Mapa de acciones dentro del Input Action recurso.
Establecimiento de un objeto prefabricado para la visualización del controlador	ControllerMappingProfile	Configurado en la XRController configuración. Por ejemplo, la Model Prefab propiedad en ArticulatedHandController.