Leitfaden zur Migration von MRTK2 zu MRTK3

  • Artikel

Beim Verwenden von MRTK3 werden Sie feststellen, dass mehrere Konzepte in MRTK v2 geändert, ersetzt oder entfernt wurden. Dieses Dokument hilft, die Lücke zwischen MRTK v2-Konzepten und ihren MRTK3-Gegenstücken zu schließen.

Interaktionen

MRTK3 verwendet das XR Interaction Toolkit (XRI) Framework von Unity für die Interaktion und das Unity Input System plus OpenXR für die Eingabe.

Wichtig

Wir empfehlen für Entwickler, die XRI noch nicht kennen, dass Sie zunächst die Dokumentation zur XRI-Architektur von Unity lesen. Alle XRI-Dokumentationen gelten auch für MRTK3, da die meisten Interaktions- und Eingabefeatures einfach von XRI geerbt werden.

Begriff

MRTK v2-Begriff MRTK3-Begriff BESCHREIBUNG
Zeiger Interaktor Interaktoren führen Interaktionen auf Interagierbaren aus. Einige (aber nicht alle) Interaktoren werden von Controllern gesteuert, von denen sie Eingabeaktionen und Posen erhalten. Andere Interaktoren funktionieren unabhängig von Controllern.

MRTK liefert mehrere benutzerdefinierte Interaktoren, die zusätzlich zu den grundlegenden von Unity bereitgestellten Interaktoren nützliche Mixed Reality-Interaktionen ermöglichen. Benutzerdefinierte Interaktoren können entweder durch Vererbung oder durch Implementieren der Interaktionsschnittstellen (IXRHoverInteractor, IXRSelectInteractor, usw.) erstellt werden. Weitere Informationen finden Sie in der Dokumentation zur Interaktorarchitektur.
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler Interaktionsfähig Interaktionsfähige Elemente sind die Empfänger von Interaktionen. MRTK liefert mehrere benutzerdefinierte interaktionsfähige Objekte, die zusätzlich zu den grundlegenden von Unity bereitgestellten interaktionsfähigen Objekten nützliche Mixed Reality-Interaktionen ermöglichen. Interaktionsfähige Objekte können entweder durch Vererbung oder durch Implementieren der interagierbaren Schnittstellen (IXRHoverInteractable, IXRSelectInteractableusw.) erstellt werden. Weitere Informationen dazu, wie MRTK interaktive XRI-Objekte erweitert, finden Sie in der Dokumentation zur interaktiven Architektur.
Controller Controller Ein ActionBasedController ist eine Sammlung von Unity-Eingabeaktionen, die die Bindungen darstellen, die einem bestimmten Gerät zugeordnet sind. Die Sammlung von Eingabeaktionen kann von mehreren Geräten abgeleitet werden, da es keine 1:1-Beziehung zwischen ActionBasedControllers und zugrunde liegenden Eingabegeräten gibt. (DeviceBasedController ist eine 1:1-Zuordnung eines Eingabegeräts, aber wir verwenden sie nicht.)

Viele Interaktionspartner (ControllerBasedInteractors, insbesondere) hören Controller für Eingabeaktionen an; anders ausgedrückt bedeutet das, dass alle ControllerBasedInteractors unter einem XRController dieselbe Auswahlaktion teilen.
Teleportiersystem Locomotion-System Das Locomotion-System ermöglicht es dem Benutzer, sich während eines XR-Ereignisses in der Szene zu bewegen. Das System von MRTK v2 ermöglicht grundlegende Teleportation und Teleport-Hotspots mit einem hohen Maß an Anpassungsmöglichkeiten für den Teleport-Cursor und das Zeigerverhalten. XRI bietet die folgenden hinzugefügten Funktionen für Locomotion:
  • Ein Snap-Drehanbieter, der das Rig durch feste Winkel dreht
  • Ein kontinuierlicher Drehanbieter, der das Rig im Laufe der Zeit reibungslos dreht
  • Ein kontinuierlicher Bewegungsanbieter, der das Rig während der Zeit reibungslos bewegt
Fokusanbieter XR-Interaktionsmanager Der XRInteractionManager ist der Unity-Mechanismus, der als Vermittler zwischen den Interaktoren und interaktionsfähigen Elementen in der Szene dient. Die Unity XRInteractionManager synchronisiert und vermittelt alle Interaktionen zwischen Interaktoren und interaktionsfähigen Elementen und bietet im Vergleich zum alten Fokusanbieter eine wesentlich größere Flexibilität.
Zeigervermittler Interaktionsmodus-Manager Der neue Interaktionsmodus-Manager wird verwendet, um Interaktionssätze je nach Kontext in der Szene zu aktivieren/deaktivieren. Weitere Informationen finden Sie in der Dokumentation zum Modus-Manager.
SceneQuerymask Interaktionsebenen XRI-Interaktionsebenen können Entwickler filtern, welche Interaktoren auf welche interaktionsfähigen Elementen reagieren können. Diese Ebenen unterscheiden sich von Unity-Physikebenen.
Fokus Darauf zeigen (Hover) Interaktoren zeigen Hover auf interaktionsfähigen Elementen an, wenn das interaktionsfähige Element ein gültiges Ziel für den Interaktor ist. Im Allgemeinen zeigt ein Hover die Absicht des Interaktors an, z. B. das Zielen mit einem Strahl, die Nähe der Hand zum Greifen oder ob der Benutzer das Objekt betrachtet.
Wählen/Poke/Greifen/Stimme usw. Select Interaktoren geben eine Auswahl auf interaktionsfähige Elemente aus, wenn das interaktionsfähige Element ein gültiges Ziel ist und der Interaktor dies so will. ControllerBasedInteractors geben im Allgemeinen eine Auswahl aus, wenn die Auswahl-Eingabeaktion des entsprechenden Controllers ausgelöst wird. Andere Interaktoren können eine komplexere Logik haben, um zu bestimmen, wann eine Auswahl an das gewünschte interaktionsfähige Element ausgegeben werden soll.

MRTK v2 behandelt verschiedene Arten von Interaktionen mit separaten Ereignissen und Codepfaden; in anderen Worten bedeutet das, dass eine Greifaktion eine grundlegend andere Interaktion als ein Ray Click oder Poke war, das durch separate Systeme generiert wird. In MRTK3 werden alle diese Methoden zum Auswählen eines Objekts unter derselben Auswahlinteraktion vereinheitlicht.

Wir empfehlen Entwicklern dringend, keine Interaktionslogik zu entwickeln, die auf einer bestimmten Art von Interaktion beruht. Schreiben Sie stattdessen verallgemeinerbaren Code, der generisch auf alle Auswahlen antwortet. Auf diese Weise funktionieren Ihre Interaktionen über alle Eingabemodalitäten hinweg. Sogar für Arten von Interaktionen, die noch entwickelt werden müssen. Lesen Sie im Abschnitt Interaktionsfähige Architektur nach, warum wir von diesem Kurs abraten.
Nicht zutreffend Aktivieren Aktivieren ist eine zusätzliche Aktion, die bei einem Objekt ausgelöst werden kann, das bereits ausgewählt wurde. Wenn ein Benutzer beispielsweise mit dem Griff des Controllers eine Wasserpistole auswählt, löst der Trigger diese mit einer Aktivieren-Aktion aus.
Datenanbieter XRSubsystem + Anbieter Die meisten Datenanbieter sind in MRTK3 nicht mehr notwendig, weil das Unity Input System und OpenXR die meisten plattformübergreifenden Eingabeaufgaben übernehmen. Für einige Ausreißer, die noch nicht von Unity abgedeckt werden, bieten wir jedoch XRSubsystems an, die Daten über verschiedene Plattformen hinweg liefern können, wie z. B. HandsAggregatorSubsystem und SpeechSubsystem. Weitere konzeptionelle Leseinformationen zu unserem Subsystems-Ansatz finden Sie in der Architekturdokumentation der Subsysteme.

Ereignisse

MRTK v2-Begriff XRI-Begriff Notizen
OnFocusEnter/Exit FirstHoverEnter
LastHoverExit		 Notieren Sie sich die First und Last Präfixe. Diese Präfixe sind in den Ereignisnamen enthalten, da eine beliebige Anzahl von Interaktoren gleichzeitig auf ein interaktionsfähiges Objekt zeigen kann. Sie können auch jeden einzelnen Mauszeiger mit HoverEnter und HoverExit abhören, obwohl dies weniger nützlich ist als die Überwachung des gesamten Mauszeigerstatus.
OnPointerDown/Up FirstSelectEnter
LastSelectExit		 Notieren Sie sich die First und Last Präfixe. Diese Präfixe sind in den Ereignisnamen enthalten, da eine beliebige Anzahl von Interaktoren gleichzeitig ein interaktionsfähiges Objekt auswählen kann (abhängig vom Auswahlmodus). Sie können auch jede einzelne Auswahl mit SelectEnter und SelectExit abhören, obwohl dies weniger nützlich ist als die Überwachung des gesamten Auswahlstatus.
OnPointerDragged – Rufen Sie bei einer Auswahl einfach die interactorsSelecting angehängten Transformationen mit GetAttachTransform ab. Beachten Sie, dass je nach Auswahlmodus des interaktionsfähigen Elements eine unbegrenzte Anzahl von Interaktoren ein interaktionsfähiges Element auswählen (und bearbeiten) kann.
OnSourcePoseChanged, OnSourceDetected, OnSourceLost – XRI löst diese Ereignisse nicht aus. Sie werden über die XRController-Überwachung ihres zugeordneten Eingabegeräts behandelt.

UX-Komponenten

Eine vollständige Dokumentation zu MRTK3-UX-Komponenten finden Sie in den Übersichten für die UX-Pakete: UX Core, UX Components und UX Components (Non-Canvas). Eine wichtige Änderung in MRTK3 ist der Schwerpunkt auf Canvas-UX-Komponenten, die die Unity-Benutzeroberfläche verwenden. Es gibt auch ein Paket für Nicht-Canvas-UX-Komponenten. Einen Vergleich zwischen Canvas- und Nicht-Canvas-UX finden Sie hier.

Hinweis

Die Komponenten Hand Coach, Tooltips, Object Collection, AppBar und Progress Indicator sind in MRTK3 noch nicht vorhanden. Außerdem werden Toolbox und optimierte Text Prefabs nicht implementiert. Dieses Dokument wird aktualisiert, wenn zusätzliche MRTK3-UX-Komponenten hinzugefügt werden.


MRTK2 MRTK3 Notizen
Buttons Canvas Button
Non-Canvas Button		 In MRTK3 werden Schaltflächen, die auf der Unity-Benutzeroberfläche basieren, und Collider-basierte Schaltflächen als Canvas- und Nicht-Canvas-Schaltflächen überarbeitet.

Integrierte Tools zum Gruppieren von Schaltflächen in MRTK3 umfassen Button Group und ToggleCollection.

Beispiele finden Sie in den CanvasUITearsheet- und NonCanvasUITearsheet-Szenen.
Slider Canvas Slider
Non-Canvas Slider		 Ein Beispiel finden Sie in der HandInteractionExamples-Szene.
Dialog Dialog
Dialog API		 Ein Beispiel finden Sie in der DialogExample-Szene.
Scrolling Collection VirtualizedScrollRectList Ein Beispiel finden Sie in der VirtualizedScrollRectList-Szene. Die MRTK3-Dokumentation wird derzeit ausgeführt.
Slate Slate (Non-Canvas) Ein Beispiel finden Sie in der SlateDrawingExample-Szene.
See-it, Say-it Label See-it, Say-it Label Ein Beispiel finden Sie in der SeeItSayItExample-Szene.
Hand Menu Hand Menu Ein Beispiel finden Sie in der HandMenuExamples-Szene.
Near Menu Near Menu Ein Beispiel finden Sie in der NearMenuExamples-Szene.
System Keyboard System Keyboard Ein Beispiel finden Sie in der HandInteractionExamples-Szene.
Fingertip Visualization Fingertip Visualization Das FingerCursor Skript und das Prefab werden in MRTK3 ersetzt, und die Indexspitze wird über die MRTKPokeReticleVisualSkripts , RingReticleund ReticleMagnetism visualisiert. Das MRTK LeftHand Controller-Prefab enthält ein Beispiel für die Verwendung dieser Komponenten.
Constraint Manager Constraint Manager Ein Beispiel finden Sie in der BoundsControlExamples-Szene.
Bounds Control Bounding Box Bounds Control Das BoundingBox-Skript wurde ersetzt. BoundsControl stellt einen automatisch skalierten Begrenzungsrahmen bereit, dessen Visuals angepasst werden können. Es gibt mehrere BoundingBox-Prefabs, die für Visuals verwendet werden können.

Ein Beispiel finden Sie in der BoundsControlExamples-Szene.
Object Manipulator Manipulation Handler Object Manipulator Manipulation Handler ist veraltet. Verwenden Sie Object Manipulator für die Bearbeitung (Verschieben, Drehen, Skalieren) eines Objekts durch einen beliebigen Interaktor mit einer gültigen Anfügungstransformation.

Ein Beispiel finden Sie in der HandInteractionExamples-Szene.
Interactable StatefulInteractable Ein Beispiel finden Sie in der InteractableButtonExamples-Szene.
Dwell InteractorDwellManager In MRTK2 wurde ein DwellHandler Objekten angefügt, und Ereignisse wurden für die Behandlung des Anfangs- und Endes des Verweilens bereitgestellt. In MRTK3 gibt es einen InteractorDwellManager auf dem GazeInteractor und Far Rays im MRTK XR Rig, das StatefulInteractable verwendet, um zu bestimmen, ob das Objekt das Verweilen aktiviert oder nicht, und wenn dies der Fall ist, wird das Objekt für die Dauer des Verweilens ausgewählt.

Die MRTK3-Dokumentation wird derzeit ausgeführt.
Solvers Solvers MRTK3-Beispielszenen werden derzeit ausgeführt.
Visual Theming Data Binding and Theming Das MRTK3-Datenbindungs- und Themen-Framework ist so konzipiert, dass visuelle Elemente leicht erstellt werden können, die dynamisch während der Laufzeit aufgefüllt und aktualisiert werden können. Noch nicht in Canvas UX integriert.

Eingabekonfigurationen

Eingabeaktionen

MRTK 3 verwendet das neue Unity-Eingabesystempaket für Eingabeaktionen. Die meisten Einstellungen können über eine Input Action-Ressource konfiguriert werden.

Aufgabe MRTK 2 MRTK 3
Erstellen Sie einen Input Action. Eingabeaktionsprofil Verwenden Sie eine Aktionszuordnung innerhalb der Input Action-Ressource.
Binden einer Input Action an einen Controller Profil für die Controllereingabezuordnung Legen Sie die Bindung für eine Aktion mit der Input Action-Ressource fest.

Zeiger

Zeiger werden an Interaktoren in MRTK 3 angefügt. Im Standard-MRTK XR Rig befinden sich die Interaktoren unter MRTK RightHand Controller und MRTK LeftHand Controller.

Aufgabe MRTK 2 MRTK 3
Festlegen eines visuellen Prefabs für einen Zeiger Eigenschaft Pointer Prefab im Profil für die MRTK 2-Zeigerkonfiguration. MonoBehaviours auf dem MRTK RightHand Controller und MRTK LeftHand Controller im MRTK XR Rig. Beispiel: MRTKPokeReticleVisual, MRTKLineVisual und MRTKRayReticleVisual.
Einschränken der Ebenen, mit denen interagiert werden kann Pointing Raycast Layer Masks-Eigenschaft in MRTK Pointer Profile. Dies gilt für alle Zeiger. raycastMask-Eigenschaft im Interactor-Skript.
Festlegen der Ausdehnung eines Zeigerraycasts Pointing Extent-Eigenschaft in MRTK Pointer Profile. Dies gilt für alle Zeiger. maxRaycastDistance-Eigenschaft im Interactor-Skript.
Festlegen der Priorität von Zeigern Gesteuert durch DefaultPointerMediator oder eine Außerkraftsetzung. Konfiguriert über den InteractionModeManager (ein MRTK3-MonoBehaviour).

Gesten

Input Actions kann verschiedenen Gesteneingabemethoden zugewiesen werden (derzeit nur für die Windows-Erkennung auf HoloLens 2 unterstützt).

Aufgabe MRTK 2 MRTK 3
Zuweisen einer Aktion zu einer Geste Weisen Sie Gesten im MixedRealityGesturesProfileInput Action zu. Gesten auf HoloLens 2 werden jetzt über das OpenXR-Plug-In erkannt.

Sprachbefehle

Das KeywordRecognitionSubsystem kann aktiviert werden, um Sprachbefehle in MRTK 3 zuzulassen. Weitere Informationen finden Sie in der Dokumentation zur Spracheingabe.

Aufgabe MRTK 2 MRTK 3
Zuordnen von Sprachbefehlen zu Input Actions Speech Commands Profile im Input System Profile. Rufen Sie CreateOrGetEventForKeyword im KeywordRecongitionSubsystem mit Ihrem Schlüsselwort und Ihrer Aktion auf.

Controller-Konfiguration

Aufgabe MRTK 2 MRTK 3
Konfigurieren des Verhaltens der Controllertasten ControllerMappingProfile Aktionszuordnung innerhalb der Input Action-Ressource.
Festlegen eines Prefabs für die Controllervisualisierung ControllerMappingProfile In den XRController-Einstellungen konfiguriert. Beispielsweise die Model Prefab-Eigenschaft in ArticulatedHandController.