Guide de migration de MRTK2 vers MRTK3

  • Article

Lorsque vous commencez à utiliser MRTK3, vous remarquez que plusieurs concepts dans MRTK v2 ont été modifiés, remplacés ou supprimés. Ce document aide à comprendre les différences entre les concepts MRTK v2 et les équivalents MRTK3.

Interactions

MRTK3 utilise le framework XR Interaction Toolkit (XRI) d’Unity pour traiter l’interaction et le système d’entrée Unity plus OpenXR pour l’entrée.

Important

Pour les développeurs qui débutent avec XRI, nous vous recommandons de consulter d’abord la documentation de l’architecture XRI d’Unity. Toute la documentation XRI s’applique également à MRTK3, car la plupart des fonctionnalités d’interaction et d’entrée sont simplement héritées de XRI.

Terminologie

Terme MRTK v2 Terme MRTK3 Description
Pointeur Interaction Les interactions effectuent des interactions sur des éléments avec interaction. Certaines interactions (mais pas toutes) sont pilotées par des contrôleurs, desquels ils reçoivent des actions d’entrée et des postures. D’autres interactions fonctionnent indépendamment des contrôleurs.

MRTK fournit plusieurs interacteurs personnalisés qui offrent des interactions de réalité mixte utiles en plus des interacteurs de base qu’Unity fournit déjà. Les interacteurs personnalisés peuvent être générés par héritage ou en implémentant les interfaces Interactor (IXRHoverInteractor, IXRSelectInteractor, etc.). Pour plus d’informations, consultez la documentation de l’architecture des interacteurs.
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler Avec interaction Les éléments avec interaction sont les destinataires des interactions. MRTK fournit plusieurs interactables personnalisés qui offrent des interactions de réalité mixte utiles en plus des interactables de base qu’Unity fournit déjà. Les interactables peuvent être générés par héritage ou en implémentant les interfaces Interactable (IXRHoverInteractable, IXRSelectInteractable, etc.). Pour plus d’informations sur la façon dont MRTK étend les interactables XRI, consultez la documentation sur l’architecture des interactables.
Contrôleur Contrôleur Un ActionBasedController est une collection d’actions d’entrée Unity représentant les liaisons associées à un appareil particulier. La collection d’actions d’entrée peut être dérivée de plusieurs appareils, car il n’existe pas de relation 1:1 entre ActionBasedControllers et les appareils d’entrée sous-jacents. (Un DeviceBasedController est un mappage 1:1 d’un appareil d’entrée, mais nous ne les utilisons pas.)

De nombreux interacteurs (ControllerBasedInteractor en particulier) écoutent les actions d’entrée des contrôleurs. En d’autres termes, tous les ControllerBasedInteractor sous un XRController partagent la même action de sélection.
Système de téléportation Système Locomotion Le système Locomotion permet à l’utilisateur de se déplacer sur la scène pendant une expérience XR. Le système de MRTK v2 permet une téléportation de base et des points d’accès de téléportation, avec un degré élevé de personnalisation du comportement du curseur et du pointeur de téléportation. XRI offre les fonctionnalités de locomotion ajoutées suivantes :
  • Un Snap Turn Provider qui fait pivoter la plateforme à angles fixes
  • Un Continuous Turn Provider qui fait pivoter la plateforme de manière fluide au fil du temps
  • Un Continuous Move Provider qui déplace lentement la plateforme au fil du temps
Focus Provider Gestionnaire d’interaction XR XRInteractionManager est le mécanisme Unity qui sert d’intermédiaire entre les interactions et les éléments avec interaction dans la scène. Unity XRInteractionManager synchronise et arbitre toutes les interactions entre les interactions et les éléments avec interaction, et offre une plus grande flexibilité par rapport au Focus Provider hérité.
Pointer Mediator Gestionnaire du mode d’interaction Le nouveau Gestionnaire du mode d’interaction est utilisé pour activer/désactiver des ensembles d’interactions en fonction du contexte de la scène. Pour plus d’informations, consultez la documentation du gestionnaire de mode.
SceneQuerymask Couches d’interaction Les couches d’interaction XRI permettent aux développeurs de filtrer les interactions qui peuvent agir sur les éléments avec interaction. Ces couches sont distinctes des couches physiques Unity.
Priorité Pointage Les interactions génèrent des pointages sur les éléments avec interaction lorsque l’élément avec interaction est une cible valide pour l’interaction. En règle générale, un pointage indique l’intention de l’interaction, comme le ciblage avec un rayon, la proximité de la main pour saisir, ou si l’utilisateur examine l’objet.
Select/Poke/Grab/Voice etc. Sélectionnez Les interactions génèrent des sélections sur les éléments avec interaction lorsque l’élément avec interaction est une cible valide et que l’interaction choisit de le faire. Les ControllerBasedInteractors génèrent généralement des sélections lorsque l’action d’entrée de sélection du contrôleur correspondant est déclenchée. D’autres interactions peuvent avoir une logique plus complexe pour déterminer quand les sélections doivent être générées sur l’élément avec interaction ciblé.

MRTK v2 traitait différents types d’interactions avec des événements et des chemins de code distincts. En d’autres termes, une saisie était une interaction fondamentalement différente d’un clic ou d’un appui, généré par des systèmes distincts. Dans MRTK3, toutes ces méthodes de « sélection » d’un objet sont unifiées sous la même interaction Sélectionner.

Nous déconseillons vivement les développeurs de créer une logique d’interaction qui s’appuie sur un type d’interaction spécifique. Écrivez plutôt du code généralisable qui répond de façon générique à tous les sélections. De cette façon, vos interactions fonctionnent sur toutes les modalités d’entrée, et même pour les types d’interactions qui n’ont pas encore été développés. Pour plus d’informations sur la raison pour laquelle nous déconseillons ce cours, consultez l’architecture des interactables.
N/A Activer Activer est une action supplémentaire qui peut être déclenchée sur un objet qui a déjà été sélectionné. Par exemple, si un utilisateur sélectionne une arme avec la poignée du contrôleur, le déclencheur l’active avec une action Activate.
Fournisseur de données XRSubsystem + Provider La plupart des fournisseurs de données ne sont plus nécessaires dans MRTK3, car le système d’entrée Unity et OpenXR traitent la plupart des tâches d’entrée multiplateformes. Toutefois, pour certaines valeurs hors norme qui ne sont pas encore couvertes par Unity, nous proposons des XRSubsystems qui peuvent fournir des données sur différentes plateformes, comme HandsAggregatorSubsystem et SpeechSubsystem. Consultez la documentation de l’architecture des sous-systèmes pour une lecture plus conceptuelle de notre approche des sous-systèmes.

Événements

Terme MRTK v2 Terme XRI Notes
OnFocusEnter/Exit FirstHoverEnter
LastHoverExit		 Notez les préfixes First et Last. Ces préfixes sont ajoutés dans les noms d’événements, car n’importe quel nombre d’interacteurs peut pointer simultanément sur un élément interactif. Vous pouvez également écouter chaque entrée/sortie de pointage individuel avec HoverEnter et HoverExit, bien que cela soit moins utile que de monitorer l’état général du pointage.
OnPointerDown/Up FirstSelectEnter
LastSelectExit		 Notez les préfixes First et Last. Ces préfixes sont ajoutés dans les noms d’événements, car n’importe quel nombre d’interacteurs peut sélectionner simultanément un élément interactif (en fonction du mode de sélection). Vous pouvez également écouter chaque entrée/sortie de sélection individuelle avec SelectEnter et SelectExit, bien que cela soit moins utile que de monitorer l’état général de la sélection.
OnPointerDragged N/A Interrogez simplement les transformations d’attachement interactorsSelecting avec GetAttachTransform lors d’une sélection. N’oubliez pas que, selon le mode de sélection de l’élément avec interaction, un nombre illimité d’interactions peut sélectionner (et manipuler) un élément avec interaction.
OnSourcePoseChanged, OnSourceDetected, OnSourceLost N/A XRI ne déclenche pas ces événements. Ils sont traités par le biais de la surveillance XRController de son appareil d’entrée associé.

UX Components

Pour obtenir une documentation complète sur les composants d’expérience utilisateur MRTK3, reportez-vous aux vues d’ensemble des packages d’expérience utilisateur : UX Core, UX Components et UX Components (Non-Canvas). Un changement majeur dans MRTK3 concerne l’accent mis sur les composants de l’expérience utilisateur canevas qui utilisent l’interface utilisateur Unity. Il existe également un package pour les composants d’expérience utilisateur non canevas. Vous trouverez une comparaison entre l’expérience utilisateur canevas et non canevas ici.

Remarque

Les composants Hand Coach, Tooltips, Object Collection, AppBar et Progress Indicator n’existent pas encore dans MRTK3. En outre, Toolbox et Text Prefabs optimisé ne sont pas implémentés. Ce document sera mis à jour quand des composants d’expérience utilisateur MRTK3 UX supplémentaires seront ajoutés


MRTK2 MRTK3 Notes
Buttons Canvas Button
Non-Canvas Button		 Dans MRTK3, les boutons basés sur l’interface utilisateur Unity et les boutons basés sur les collisionneurs sont modifiés. Il s’agit désormais de boutons canevas et non canevas.

Les outils intégrés pour regrouper les boutons dans MRTK3 incluent Button Group et ToggleCollection.

Vous trouverez des exemples dans les scènes CanvasUITearsheet et NonCanvasUITearsheet.
Slider Canvas Slider
Non-Canvas Slider		 Vous trouverez un exemple dans la scène HandInteractionExamples.
Dialog Dialog
Dialog API		 Vous trouverez un exemple dans la scène DialogExample.
Scrolling Collection VirtualizedScrollRectList Vous trouverez un exemple dans la scène VirtualizedScrollRectList. La documentation MRTK3 est actuellement en cours.
Slate Slate (Non-Canvas) Vous trouverez un exemple dans la scène SlateDrawingExample.
See-it, Say-it Label See-it, Say-it Label Vous trouverez un exemple dans la scène SeeItSayItExample.
Hand Menu Hand Menu Vous trouverez un exemple dans la scène HandMenuExamples.
Near Menu Near Menu Vous trouverez un exemple dans la scène NearMenuExamples.
System Keyboard System Keyboard Vous trouverez un exemple dans la scène HandInteractionExamples.
Fingertip Visualization Fingertip Visualization Le FingerCursor script et le préfabriqué sont remplacés dans MRTK3 et le bout de l’index est visualisable via les MRTKPokeReticleVisualscripts , RingReticleet ReticleMagnetism . L’élément préfabriqué MRTK LeftHand Controller contient un exemple d’utilisation de ces composants.
Constraint Manager Constraint Manager Vous trouverez un exemple dans la scène BoundsControlExamples.
Bounds Control Bounding Box Bounds Control Le script BoundingBox a été remplacé. BoundsControl fournit un cadre englobant automatiquement dimensionné, dont les visuels peuvent être personnalisés. Il existe plusieurs éléments préfabriqués BoundingBox pouvant être utilisés pour les visuels.

Vous trouverez un exemple dans la scène BoundsControlExamples.
Object Manipulator Manipulation Handler Object Manipulator Manipulation Handler est déconseillé. Utiliser Object Manipulator pour la manipulation (déplacement, rotation, mise à l’échelle) d’un objet par n’importe quel interacteur avec une transformation d’attachement valide.

Vous trouverez un exemple dans la scène HandInteractionExamples.
Interactable StatefulInteractable Vous trouverez un exemple dans la scène InteractableButtonExamples.
Dwell InteractorDwellManager Dans MRTK2, un DwellHandler a été attaché à des objets et a fourni des événements pour gérer le début et la fin de la durée de fixation du regard. Dans MRTK3, il existe un InteractorDwellManager sur GazeInteractor et Far Rays dans le MRTK XR Rig, qui utilise StatefulInteractable pour déterminer si l’objet permet la fixation du regard ou non, et si oui, pour déterminer si l’objet est sélectionné pendant la durée de fixation du regard.

La documentation MRTK3 est actuellement en cours.
Solvers Solvers Des exemples de scènes MRTK3 sont actuellement en cours.
Visual Theming Data Binding and Theming L’infrastructure de liaison de données et de thématisation MRTK3 est conçue pour faciliter la création d’éléments visuels qui peuvent être remplis et mis à jour dynamiquement, au moment du runtime. Pas encore intégré à l’expérience utilisateur canevas.

Configurations d’entrée

Actions d’entrée

MRTK 3 utilise le nouveau package de système d’entrée Unity pour les actions d’entrée. La plupart des paramètres peuvent être configurés via une ressource Input Action.

Tâche MRTK2 MRTK3
Créer un Input Action Profil des actions d’entrée Utilisez un mappage d’actions dans la ressource Input Action.
Lier un Input Action à un Controller Profil de mappage d’entrée de contrôleur Définissez la liaison pour une action avec la ressource Input Action.

Pointeurs

Les pointeurs sont attachés aux interacteurs dans MRTK3. Dans la valeur par défaut MRTK XR Rig, les interacteurs sont positionnés en dessous de MRTK RightHand Controller et MRTK LeftHand Controller.

Tâche MRTK2 MRTK3
Définir un élément préfabriqué visuel pour un pointeur Propriété Pointer Prefab dans le profil de configuration de pointeur MRTK2. MonoBehaviours sur MRTK RightHand Controller et MRTK LeftHand Controller dans MRTK XR Rig. Par exemple, MRTKPokeReticleVisual, MRTKLineVisual et MRTKRayReticleVisual.
Limitez les couches qui peuvent interagir avec Propriété Pointing Raycast Layer Masks dans MRTK Pointer Profile. Cela s’applique à tous les pointeurs. Propriété raycastMask dans le script Interactor.
Définissez l’étendue de la propriété de raycast de pointeur Propriété Pointing Extent dans MRTK Pointer Profile. Cela s’applique à tous les pointeurs. Propriété maxRaycastDistance dans le script Interactor.
Définir la priorité des pointeurs Contrôlés par DefaultPointerMediator ou un remplacement. Configuré via InteractionModeManager (MonoBehaviour MRTK3).

Mouvements

Input Actions peut être attribué à différentes méthodes d’entrée de geste (actuellement pris en charge uniquement pour la reconnaissance Windows sur HoloLens 2).

Tâche MRTK2 MRTK3
Attribuer une action à un geste Attribuer des gestes à Input Action dans MixedRealityGesturesProfile. Les gestes sur HoloLens 2 sont désormais reconnus via le plug-in OpenXR.

Commandes vocales

KeywordRecognitionSubsystem peut être activé pour autoriser les commandes vocales dans MRTK3. Pour plus d’informations, consultez la documentation relative à la saisie vocale.

Tâche MRTK2 MRTK3
Mapper les commandes vocales à Input Actions Speech Commands Profile dans Input System Profile. Appelez CreateOrGetEventForKeyword sur le KeywordRecongitionSubsystem avec votre mot clé et votre action.

Configuration des contrôleurs

Tâche MRTK2 MRTK3
Configurer le comportement des boutons de contrôleur ControllerMappingProfile Mappage d’actions dans la ressource Input Action.
Définir l’élément préfabriqué pour la visualisation des contrôleurs ControllerMappingProfile Configuré dans les paramètres XRController. Par exemple, la propriété Model Prefab dans ArticulatedHandController.