从 MRTK2 迁移到 MRTK3 的迁移指南

  • 项目

在开始使用 MRTK3 时，你会发现 MRTK v2 中有几个概念已被更改、替换或删除。 本文档帮助弥补 MRTK v2 概念与其 MRTK3 对应概念之间的差距。

交互

MRTK3 使用 Unity 的 XR 交互工具包 (XRI) 框架来处理交互，并使用 Unity 输入系统和 OpenXR 来处理输入。

重要

对于不熟悉 XRI 的开发人员而言，建议先查看 Unity 的 XRI 体系结构文档。 所有 XRI 文档也适用于 MRTK3，因为大多数交互和输入功能都是直接从 XRI 继承的。

术语

MRTK v2 术语 MRTK3 术语 说明
指针 交互器 交互器在可交互对象上执行交互。 某些（但并非全部）交互器由控制器驱动，它们通过控制器接收输入操作和姿势。 其他交互器独立于控制器运行。

在 Unity 已提供的基本交互器之上，MRTK 随附了多个自定义交互器，它们提供有用的混合现实交互。 可以通过继承或通过实现交互器接口（IXRHoverInteractor、IXRSelectInteractor 等）来生成自定义交互器。 有关详细信息，请参阅交互器体系结构文档。
NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler 可交互 可交互对象是交互的接收方。 在 Unity 已提供的基本可交互对象之上，MRTK 随附了多个自定义可交互对象，它们提供有用的混合现实交互。 可以通过继承或通过实现可交互对象接口（IXRHoverInteractable、IXRSelectInteractable 等）来生成可交互对象。 有关 MRTK 如何扩展 XRI 可交互对象的详细信息，请参阅可交互对象体系结构文档。
控制器 控制器 ActionBasedController 是 Unity 输入操作的集合，代表与特定设备关联的绑定。 输入操作的集合可以派生自多个设备，因为 ActionBasedControllers 与基础输入设备之间不存在 1:1 的关系。 （DeviceBasedController 是输入设备的 1:1 映射，但我们不使用它们。）

许多交互器（特别是 ControllerBasedInteractor）在控制器上侦听输入操作，换句话说，XRController 下的所有 ControllerBasedInteractor 会共享同一个选择操作。
传送系统 位移系统 位移系统允许用户在 XR 体验中围绕场景移动。 MRTK v2 的系统允许基本的传送和位移热点，并针对传送光标和指针行为提供很高程度的可自定义性。 XRI 为位移提供以下附加功能：
  • 以固定角度旋转装备的贴靠旋转提供程序
  • 不断地平稳地旋转装备的连续旋转提供程序
  • 不断地平稳地移动装备的连续移动提供程序
聚焦提供程序 XR 交互管理器 XRInteractionManager 是在场景中充当交互器与可交互对象之间的中介的 Unity 机制。 Unity XRInteractionManager 同步并仲裁交互器与可交互对象之间的所有交互，与旧版聚焦提供程序相比，它可以实现更大的灵活性。
指针调解器 交互模式管理器 新的交互模式管理器用于根据场景中的上下文启用/禁用交互器集。 有关详细信息，请参阅模式管理器文档。
SceneQuerymask 交互层 XRI 交互层允许开发人员筛选哪些交互器可以对哪些可交互对象进行操作。 这些层与 Unity 物理层不同。
焦点 悬停 当可交互对象是交互器的有效目标时，交互器将针对可交互对象发出“悬停”。 一般情况下，“悬停”表示交互器的意图，例如用光线瞄准、用手靠近以抓取，或者用户是否正在注视对象。
选择/戳击/抓取/语音等。 Select 当可交互对象既是有效目标，也是交互器选择的目标时，交互器将针对可交互对象发出“选择”。 ControllerBasedInteractor 通常在其对应控制器的选择输入操作触发时发出“选择”。 其他交互器可能使用更复杂的逻辑来确定何时应向目标可交互对象发出“选择”。

MRTK v2 使用不同的事件和代码路径来处理不同类型的交互，换句话说，抓取是与光线单击或戳击根本不同的交互，它由不同的系统生成。 在 MRTK3 中，所有这些“选择”对象的方式都统一在同一个“选择”交互下。

我们强烈反对开发人员生成依赖于特定交互类型的交互逻辑；相反，应编写能够以常规方式响应所有“选择”的通用代码。 这样，交互就可以在所有输入模态下正常进行，甚至对于尚未开发的交互类型也是如此。 请参阅可交互对象体系结构，进一步了解我们不推荐此课程的原因。
空值 激活 “激活”是一个附加的操作，可以针对已选择的对象引发。 例如，如果用户使用控制器的手柄选择了喷枪，则触发器将使用“激活”操作发射喷枪。
数据提供程序 XRSubsystem + 提供程序 大部分数据提供程序在 MRTK3 中不再需要用到，因为 Unity 输入系统和 OpenXR 将处理大部分跨平台输入任务。 但是，对于 Unity 尚未涵盖的一些非寻常任务，我们提供了可以跨不同平台提供数据的 XRSubsystem，例如 HandsAggregatorSubsystem 和 SpeechSubsystem。 有关子系统方法的其他概念性阅读材料，请参阅子系统体系结构文档。

事件

MRTK v2 术语 XRI 术语 注释
OnFocusEnter/Exit FirstHoverEnter
LastHoverExit		 请注意 First 和 Last 前缀。 这些前缀包含在事件名称中，因为任意数量的交互器可以同时悬停在某个可交互对象上。 还可以使用 HoverEnter 和 HoverExit 侦听每个悬停进入/退出操作，不过，这不如监视整体悬停状态有用。
OnPointerDown/Up FirstSelectEnter
LastSelectExit		 请注意 First 和 Last 前缀。 这些前缀包含在事件名称中，因为任意数量的交互器可以同时选择某个可交互对象（根据选择模式）。 还可以使用 SelectEnter 和 SelectExit 侦听每个选择进入/退出操作，不过，这不如监视整体选择状态有用。
OnPointerDragged 空值 只需在选择期间使用 GetAttachTransform 轮询 interactorsSelecting 附加转换即可。 请记住，根据可交互对象的选择模式，无限数量的交互器可以选择（和操控）一个可交互对象。
OnSourcePoseChanged, OnSourceDetected, OnSourceLost 不适用 XRI 不会引发这些事件。 这些事件通过监视其关联的输入设备的 XRController 进行处理。

UX 组件

有关 MRTK3 UX 组件的完整文档，请参阅 UX 包的概述：UX Core、UX Components 和 UX Components (Non-Canvas)。 MRTK3 的一个主要更改是强调使用 Unity UI 的 Canvas UX 组件。 还有一个用于非画布 UX 组件的包。 可在此处找到画布与非画布 UX 之间的比较。

注意

MRTK3 中尚不存在 Hand CoachTooltips、Object Collection、AppBar 和 Progress Indicator 组件。 此外，未实现 Toolbox 和优化的 Text Prefabs。 添加其他 MRTK3 UX 组件后，本文档将更新


MRTK2 MRTK3 说明
Buttons Canvas Button
Non-Canvas Button		 在 MRTK3 中，基于 Unity UI 的按钮和基于 Collider 的按钮将作为画布和非画布按钮进行更新。

MRTK3 中用于对按钮进行分组的内置工具包括 Button Group 和 ToggleCollection。

可以在 CanvasUITearsheet 和 NonCanvasUITearsheet 场景中找到示例。
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 在 MRTK3 中替换 FingerCursor 脚本和预制件，并通过 MRTKPokeReticleVisual、RingReticle 和 ReticleMagnetism 脚本实现食指指尖可视化。 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 中，GazeInteractor 上有 InteractorDwellManager，MRTK XR Rig 中有 Far Rays，它使用 StatefulInteractable 来确定对象是否启用停留，如果启用停留，则它会选择停留期间的对象。

MRTK3 文档目前正在进行中。
Solvers Solvers MRTK3 示例场景目前正在进行中。
Visual Theming Data Binding and Theming MRTK3 数据绑定和主题框架旨在方便创建在运行时可以动态填充和更新的视觉元素。 尚未与 Canvas UX 集成。

输入配置

输入操作

MRTK 3 使用新的 Unity 输入系统包进行输入操作。 大多数设置都可以通过 Input Action 资产进行配置。

任务 MRTK 2 MRTK 3
创建 Input Action 输入操作配置文件 在 Input Action 资产中使用操作映射。
将 Input Action 绑定到 Controller 控制器输入映射配置文件 使用 Input Action 资产设置操作的绑定。

指针

指针附加到 MRTK 3 中的交互器。 在默认 MRTK XR Rig 中，交互组件位于 MRTK RightHand Controller 和 MRTK LeftHand Controller 下方。

任务 MRTK 2 MRTK 3
为指针设置视觉对象预制件 MRTK 2 指针配置文件中的 Pointer Prefab 属性。 MRTK XR Rig 中 MRTK RightHand Controller 和 MRTK LeftHand Controller 上的 MonoBehaviours。 例如 MRTKPokeReticleVisual、MRTKLineVisual 和 MRTKRayReticleVisual。
限制可以与之交互的层 MRTK Pointer Profile 中的 Pointing Raycast Layer Masks 属性。 这适用于所有指针。 Interactor 脚本上的 raycastMask 属性。
设置指针光线投射的范围 MRTK Pointer Profile 中的 Pointing Extent 属性。 这适用于所有指针。 Interactor 脚本上的 maxRaycastDistance 属性。
设置指针的优先级 由 DefaultPointerMediator 或替代控制。 通过 InteractionModeManager (MRTK3 MonoBehaviour) 进行配置。

笔势

Input Actions 可以分配给各种手势输入方法（当前仅支持 HoloLens 2 上的 Windows 识别）。

任务 MRTK 2 MRTK 3
为手势分配操作 将手势分配给 MixedRealityGesturesProfile 中的 Input Action。 现在可通过 OpenXR 插件识别 HoloLens 2 上的手势。

语音命令

可以启用 KeywordRecognitionSubsystem 以允许 MRTK 3 中的语音命令。 有关详细信息，请参阅有关语音输入的文档。

任务 MRTK 2 MRTK 3
将语音命令映射到 Input Actions Input System Profile 中的 Speech Commands Profile。 使用关键字和操作在 KeywordRecongitionSubsystem 上调用 CreateOrGetEventForKeyword。

控制器配置

任务 MRTK 2 MRTK 3
配置控制器按钮行为 ControllerMappingProfile Input Action 资产中的操作映射。
为控制器可视化设置预制件 ControllerMappingProfile 在 XRController 设置中配置。 例如，ArticulatedHandController. 中的 Model Prefab 属性