從 MRTK2 移轉至 MRTK3 的移轉指南

  • 發行項

當您開始使用 MRTK3 時，您會發現 MRTK v2 中的數個概念已變更、取代或移除。 本檔有助於橋接 MRTK v2 概念與其 MRTK3 對應專案之間的差距。

互動

MRTK3 使用 Unity 的 XR 互動工具組 (XRI) 架構來處理互動，以及 Unity 輸入系統加上 OpenXR 進行輸入。

重要

對於 XRI 新手的開發人員，建議您先檢閱 Unity 的 XRI 架構檔。 所有 XRI 檔也適用于 MRTK3，因為大部分的互動和輸入功能只會繼承自 XRI。

詞彙

MRTK v2 詞彙 MRTK3 字詞 描述
Pointer 互動器 互動者 會在 Interactionable 上執行互動。 有些 (但並非所有) 互動者都是由控制器所驅動，這些控制器會從中接收輸入動作和姿勢。 其他 Interactors 會獨立于控制器之外運作。

MRTK 隨附數個自訂 Interactors，在基本 Interactors Unity 已提供實用的混合實境互動。 您可以透過繼承或實作互動器介面來建置自訂互動專案， IXRHoverInteractor (、 IXRSelectInteractor 等等) 。 如需詳細資訊，請參閱 互動器架構檔。
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler 可互動 可互動是 互動的收件者。 MRTK 會提供數個自訂的 Interactionables，在基本的 Interactionables Unity 上提供實用的混合實境互動。 您可以透過繼承或實作可互動的介面， (IXRHoverInteractable 、 IXRSelectInteractable 等等來建置可互動) 。 如需 MRTK 如何擴充 XRI 互動的詳細資訊，請參閱 可互動架構檔。
控制器 控制器 ActionBasedController是 Unity 輸入動作的集合，代表與特定裝置相關聯的系結。 輸入動作的集合可以衍生自多個裝置，因為與基礎輸入裝置之間 ActionBasedControllers 沒有 1：1 關聯性。 (A DeviceBasedController 是輸入裝置的 1：1 對應，但我們不會使用它們。)

許多互動專案 (ControllerBasedInteractor s，特別是) 接聽控制器的輸入動作，換句話說，XRController 底下的全 ControllerBasedInteractor 都共用相同的選取動作。
Teleport 系統 Locomotion 系統 Locomotion 系統可讓使用者在 XR 體驗期間移動場景。 MRTK v2 的系統允許基本遠端傳送和遠端埠熱點，並高度可自訂遠端傳送資料指標和指標行為。 XRI 提供下列新增功能來尋找：
  • 固定角度旋轉鑽架的貼齊回合提供者
  • 連續回合提供者，可順暢旋轉一段時間的鑽機
  • 連續移動提供者，可順暢地隨著時間移動鑽架
焦點提供者 XR 互動管理員 XRInteractionManager是 Unity 機制，可作為場景中Interactors與Interactables之間的媒介。 Unity XRInteractionManager 會同步處理和仲裁 Interactors 與 Interactionables 之間的所有互動，而且相較于舊版焦點提供者，可大幅提升彈性。
指標媒體器 互動模式管理員 新的 互動模式管理員 可用來根據場景內的內容來啟用/停用動作專案集。 如需詳細資訊，請參閱 模式管理員檔 。
SceneQuery 遮罩 互動層 XRI 互動層 可讓開發人員篩選哪些 Interactors 可以處理哪些互動專案。 這些層與 Unity 實體層不同。
焦點 暫留 互動性問題當 Interactable 是 Interactor 的有效目標時，將 滑鼠停留 在 Interactable 上。 一般而言，Hover 會指出互動者的意圖，例如以光線為目標、抓取手部鄰近性，或使用者正在查看物件。
選取/Poke/擷取/語音等。 選取 互動者問題 當 Interactable 同時是有效的目標和互動者選擇這麼做時，選取 [互動]。 ControllerBasedInteractors 通常會在其對應的控制器選取輸入動作引發時發出 Selects。 其他互動者可以有更複雜的邏輯，以判斷何時應該發出選取專案給目標互動。

MRTK v2 處理了與不同事件和程式碼路徑的不同類型的互動，換句話說，抓取與個別系統所產生的光線點選或擷取基本上是不同的互動。 在 MRTK3 中，物件的所有「選取」方式都會在相同的 Select 互動下整合。

我們強烈建議開發人員建置依賴特定互動類型的互動邏輯;相反地，撰寫可一般回應所有 Selects 的一般化程式碼。 如此一來，您的互動會跨所有輸入形式運作，甚至是尚未開發的互動類型。 請參閱 互動架構 ，以進一步閱讀我們不建議本課程的原因。
N/A 啟動 Activate 是可以在已經選取的物件上引發的額外動作。 例如，如果使用者選取具有控制器底框的波浪杆，觸發程式就會以 Activate 動作引發它。
資料提供者 XRSubsystem + 提供者 由於 Unity 輸入系統和 OpenXR 處理大部分跨平臺輸入工作，因此 MRTK3 已不再需要大部分的資料提供者。 不過，針對 Unity 尚未涵蓋的一些極端值，我們會提供 XRSubsystem 可在不同平臺提供資料，例如 和 HandsAggregatorSubsystemSpeechSubsystem 。 如需子系統方法的概念性閱讀，請參閱 子系統架構檔 。

事件

MRTK v2 詞彙 XRI 字詞 注意
OnFocusEnter/Exit FirstHoverEnter
LastHoverExit		 First請注意 和 Last 前置詞。 這些前置詞會包含在事件名稱中，因為任意數目的 Interactors 可以同時暫留 Interactable。 您也可以使用 HoverEnter 和 HoverExit 接聽每個個別的暫留進入/結束，雖然它比監視整體暫留狀態還不實用。
OnPointerDown/Up FirstSelectEnter
LastSelectExit		 First請注意 和 Last 前置詞。 這些前置詞會包含在事件名稱中，因為任意數目的 Interactors 可以根據選取模式) 同時選取可互動 (。 您也可以使用 SelectEnter 和 SelectExit 來接聽每個個別的選取/結束，雖然它比監視整體選取狀態還不實用。
OnPointerDragged N/A 只要在 interactorsSelecting 選取期間使用 輪詢附加轉換 GetAttachTransform 即可。 請記住，視互動的選取模式而定，不系結的 Interactors 數目可以選取 (並操作互動) 。
OnSourcePoseChanged, OnSourceDetected, OnSourceLost N/A XRI 不會引發這些事件。 它們會透過 XRController 監視其相關聯的 輸入裝置來處理。

UX 元件

如需 MRTK3 UX 元件的完整檔，請參閱 UX 套件的概觀： UX Core 、 UX Components 和 UX Components (Non-Canvas) 。 MRTK3 的主要變更是強調使用 Unity UI 的 Canvas UX 元件。 也有非畫布 UX 元件的套件。 您可以 在這裡找到 Canvas 與非 Canvas UX 之間的比較。

注意

Hand Coach、 Tooltips 、 Object Collection 、 AppBar 和 Progress Indicator 元件尚未存在於 MRTK3 中。 此外， Toolbox 也不會實作優化 Text Prefabs 。 新增其他 MRTK3 UX 元件時，將會更新此檔


MRTK2 MRTK3 注意
Buttons Canvas Button
Non-Canvas Button		 在 MRTK3 中，Unity UI 型按鈕和以碰撞器為基礎的按鈕會以畫布和非畫布按鈕的形式來排列。

內建工具可將 MRTK3 中的按鈕分組，包括 Button Group 和 ToggleCollection 。

您可以在 和 NonCanvasUITearsheet 場景中找到 CanvasUITearsheet 範例。
Slider Canvas Slider
Non-Canvas Slider		 您可以在場景中找到 HandInteractionExamples 範例。
Dialog Dialog
Dialog API		 您可以在場景中找到 DialogExample 範例。
Scrolling Collection VirtualizedScrollRectList 您可以在場景中找到 VirtualizedScrollRectList 範例。 MRTK3 檔目前正在進行中。
Slate Slate (Non-Canvas) 您可以在場景中找到 SlateDrawingExample 範例。
See-it, Say-it Label See-it, Say-it Label 您可以在場景中找到 SeeItSayItExample 範例。
Hand Menu Hand Menu 您可以在場景中找到 HandMenuExamples 範例。
Near Menu Near Menu 您可以在場景中找到 NearMenuExamples 範例。
System Keyboard System Keyboard 您可以在場景中找到 HandInteractionExamples 範例。
Fingertip Visualization Fingertip Visualization FingerCursor腳本和預製專案會在 MRTK3 中取代，而且索引指尖會透過 MRTKPokeReticleVisual 、 RingReticle 和 ReticleMagnetism 腳本視覺化。 Prefab MRTK LeftHand Controller 包含如何使用這些元件的範例。
Constraint Manager Constraint Manager 您可以在場景中找到 BoundsControlExamples 範例。
Bounds Control Bounding Box Bounds Control BoundingBox已取代腳本。 BoundsControl 提供自動調整大小的周框方塊，其視覺效果可供自訂。 有數 BoundingBox 個預製專案可用於視覺效果。

您可以在場景中找到 BoundsControlExamples 範例。
Object Manipulator Manipulation Handler Object Manipulator Manipulation Handler 已被取代。 用於 Object Manipulator 操作 (透過任何與有效附加轉換互動者移動、旋轉、縮放物件) 。

您可以在場景中找到 HandInteractionExamples 範例。
Interactable StatefulInteractable 您可以在場景中找到 InteractableButtonExamples 範例。
Dwell InteractorDwellManager 在 MRTK2 中，已 DwellHandler 附加至 物件，並提供用來處理停留開始和結束的事件。 在 MRTK3 中，和 中有 MRTK XR Rig ， Far RaysInteractorDwellManagerGazeInteractor 其會使用 StatefulInteractable 來判斷物件是否啟用停留，以及它是否在停留期間選取物件。

MRTK3 檔目前正在進行中。
Solvers Solvers MRTK3 範例場景目前正在進行中。
Visual Theming Data Binding and Theming MRTK3 資料系結和主題架構的設計目的是讓您輕鬆地建立可在執行時間動態填入和更新的視覺元素。 尚未與 Canvas UX 整合。

輸入組態

輸入動作

MRTK 3 會使用新的 Unity 輸入系統套件 來執行輸入動作。 大部分的設定都可以透過資產進行 Input Action 設定。

Task MRTK 2 MRTK 3
建立 Input Action 輸入動作設定檔 使用資產內的 Input Action 動作對應。
Input Action將 系結至Controller 控制器輸入對應設定檔 使用資產設定動作的 Input Action 系結。

指標

指標會附加至 MRTK3 中的互動專案。 在預設 MRTK XR Rig 中，互動專案位於 和 MRTK LeftHand Controller 底下 MRTK RightHand Controller 。

Task MRTK 2 MRTK 3
設定指標的視覺預製專案 Pointer PrefabMRTK 2 指標組態設定檔中的 屬性。 和 中的 MRTK XR Rig MonoBehaviours。 MRTK LeftHand ControllerMRTK RightHand Controller 例如 MRTKPokeReticleVisual、MRTKLineVisual 與 MRTKRayReticleVisual。
限制可以與其互動的圖層 Pointing Raycast Layer Masks 中的 MRTK Pointer Profile 屬性。 這適用于所有指標。 raycastMask 腳本上的 Interactor 屬性。
設定指標光線傳播的範圍 Pointing Extent 中的 MRTK Pointer Profile 屬性。 這適用于所有指標。 maxRaycastDistance 腳本上的 Interactor 屬性。
設定指標的優先順序 由 DefaultPointerMediator 或 覆寫控制。 透過 InteractionModeManager (MRTK3 MonoBehaviour) 進行設定。

軌跡

Input Actions可以指派給各種手勢輸入法， (目前僅支援HoloLens 2) 上的 Windows 辨識。

Task MRTK 2 MRTK 3
將動作指派給手勢 在 中 MixedRealityGesturesProfile 將手勢指派給 Input Action 。 HoloLens 2上的手勢現在可透過 OpenXR 外掛程式辨識。

語音命令

KeywordRecognitionSubsystem可以啟用 以允許 MRTK 3 中的語音命令。 如需詳細資訊，請參閱 語音輸入檔。

Task MRTK 2 MRTK 3
將語音命令對應至 Input Actions Speech Commands Profile 在 中 Input System Profile 。 KeywordRecongitionSubsystem使用您的關鍵字和動作呼叫 CreateOrGetEventForKeyword 。

控制器設定

Task MRTK 2 MRTK 3
設定控制器按鈕行為 ControllerMappingProfile 資產內的 Input Action 動作對應。
設定控制器視覺效果的預製專案 ControllerMappingProfile 在設定中設定 XRController 。 例如， Model Prefab 中的 屬性 ArticulatedHandController.