Leitfaden zur Migration von MRTK2 zu MRTK3
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 , IXRSelectInteractable usw.) 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. (A DeviceBasedController ist eine 1:1-Zuordnung eines Eingabegeräts, aber wir verwenden sie nicht.) Viele Interaktionspartner ( ControllerBasedInteractor s, insbesondere) hören Controller für Eingabeaktionen an; anders ausgedrückt bedeutet das, dass alle ControllerBasedInteractor s 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 zusätzlichen Funktionen für die Lokomotion:
|
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 XRSubsystem s 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 |
Nicht zutreffend | 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 MRTKPokeReticleVisual , RingReticle und ReticleMagnetism Skripts 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 MixedRealityGesturesProfile Input 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. |