Microsoft 混合现实工具包 2.5 发行说明

  • 项目

重要

存在一个已知的编译器问题，该问题会影响使用 ARM64 为 Microsoft HoloLens 2 构建的应用程序。 此问题可通过将 Visual Studio 2019 更新到版本 16.8 或更高版本得以解决。 如果无法更新 Visual Studio，请导入 com.microsoft.mixedreality.toolkit.tools 包以应用替代方法。

2.5.4 版中的新增功能

修复了使用 UPM 时 Oculus 集成的 bug

使用 UPM 时，OculusXRSDKDeviceManagerProfile 会始终将其预制件在启动时设置为“无”。 此版本将设备管理器配置为在启动时指向一组备用预制件。

修复了通过 UPM 使用 OpenXR 时出现的问题

修复了默认情况下未将 OpenXR 提供程序添加到 link.xml 的问题，导致新项目在通过 Unity 的包管理器使用 OpenXR 和 MRTK 时未能在设备上运行。 升级的现有项目仍然需要手动添加。

2.5.3 版中的新增功能

修复了 2.5.2 版中引入的 Oculus 回归

2.5.2 版在集成 OCULUS SDK 时引入了一个生成问题。 此版本还原了该问题。

2.5.2 版中的新增功能

添加了对 OpenXR 的支持

添加了对 Unity 的 OpenXR 预览包和 Microsoft 的混合现实 OpenXR 包的初始支持。 有关详细信息，请参阅 MRTK/XRSDK 入门页、Unity 论坛文章或 Microsoft 文档。

重要

Unity 中的 OpenXR 仅在 Unity 2020.3 及更高版本上受支持。 它还仅支持 x64、ARM 和 ARM64 生成。

已修复边界可视化效果的错误

边界可视化效果（如地板或墙壁）现在将根据边界轮廓正确配置并在运行时可见。

MSBuild for Unity 支持

2.5.2 版中已删除对 MSBuild for Unity 的支持，以便与 Unity 的新包指南保持一致。

2.5.1 版中的新增功能

修复了程序包依赖关系错误

此版本修复了不正确的包间文件依赖关系（例如：标准资产中的文件不再错误地引用 Foundation 中的文件）。 版本 2.5.1 还在 Text Mesh Pro 上添加了显式依赖关系。

标准资产包着色器已复制到 Assets/MRTK/Shaders

通过 UPM 安装标准资产包时，着色器将被复制到 Assets/MRTK/Shaders 文件夹，以便它们不再不可变。 这解决了针对通用渲染管线 (URP) 更新的着色器在下次加载项目时还原旧行为的问题。

修复了传送光标粘在手部视觉对象上的问题

此版本修复了传送光标可能粘在手部视觉对象上的问题。

2.5.0 版中的新增功能

Unity 包管理器 (UPM) 支持

现在可使用 Unity 包管理器来管理混合现实工具包。

MRTK Foundation UPM Package

注意

导入 MRTK UPM 包需要一些手动步骤。 有关详细信息，请查看混合现实工具包和 Unity 包管理器。

Oculus Quest XR SDK 支持

MRTK 现在支持使用本机 XR SDK 管道运行 Oculus Quest 头戴显示设备和控制器。 Oculus Integration Unity 包还支持手部跟踪，这归功于 MRTK-Quest 上的 ERIC Provencher 功能！

有关如何使用新管道在 Oculus Quest 上部署设备的说明，请参阅 Oculus Quest 设置指南

滚动对象集合

MRTK UX 组件已从实验性功能升级，为布局不同大小的 3D 内容提供了更多自由，并添加了对未附加碰撞体的对象的支持。 还添加了一个禁用内容掩码的新选项，使原型制作更容易。

有关详细信息，请参阅滚动对象集合。

Scrolling Object Collection

传送指针动画、处理和声音改进

传送指针现在改进了动画效果和音频反馈。 我们还改进了对传送指针的处理，以便它在从指向附近图面转换到指向距离较远的图面时处理起来更平滑。

输入模拟速查表

HandInteractionExamples 场景现在具有可配置的快捷方式，用于显示输入模拟的帮助页

Input Simulation Cheat Sheet

使用鼠标进行输入模拟眼睛凝视

用户现在可以使用鼠标来模拟眼动跟踪。 查看输入模拟配置文件中的 Eye Simulation Mode 字段并将其设置为“鼠标”。 这将替换上一个 Simulate Eye Position 字段

Eye Gaze Mouse

编辑器播放模式下的输入模拟运动控制器

用户现在可以像在编辑器播放模式下一样模拟运动控制器。 当前支持触发器、抓取按钮和菜单按钮。

锥形抓取指针

现在可将抓取指针配置为使用抓取点中的圆锥体（而不是球体）查询附近的对象。 此行为更类似于默认 HoloLens 2 接口的行为，该接口使用圆锥体查询附近的对象。 DefaultHoloLens2InputSystemProfile 也已调整为使用新的 ConicalGrabPointer。

Conical Grab Pointer

TestUtilities 包

现在有一个包 (Microsoft.MixedReality.Toolkit.Unity.TestUtilities.2.5.0.unitypackage)，其中包含 MRTK 用于创建端到端测试的 PlayMode 和 TestMode 测试基础结构。 此基础结构对 MRTK 团队本身来说非常方便，我们很高兴让消费者使用它来为他们自己的项目添加测试覆盖率。

下面的代码展示了如何创建一个测试手，将它显示在某个位置，四处移动它，然后做捏合和张开手势。

TestHand leftHand = new TestHand(Handedness.Left);
yield return leftHand.Show(new Vector3(-0.1f, -0.1f, 0.5f));
yield return leftHand.SetGesture(ArticulatedHandPose.GestureId.Pinch);
yield return leftHand.Move(new Vector3(0.2f, 0.2f, 0));
yield return leftHand.SetGesture(ArticulatedHandPose.GestureId.Open);

有关如何使用这些 TestUtilities 编写测试的说明，请参阅此部分有关编写测试的内容。

有关使用此基础结构的现有测试的示例，请参阅 MRTK 的 PlayModeTests。

支持 Leap Motion 4.5.1 Unity 模块

添加了对 Leap Motion Unity 模块版本 4.5.1 的支持，并删除了对版本 4.4.0 资产的支持。 Leap Motion Unity 模块的当前支持版本为 4.5.0 和 4.5.1。

初始 Leap Motion 集成还有一个额外的步骤，有关详细信息，请参阅如何在 MRTK 中配置 Leap Motion 手部跟踪。

空间感知网格观察程序可以更好地处理材料自定义

在此版本中，Windows Mixed Reality Spatial Mesh Observer 和 Generic XR SDK Spatial Mesh Observer 组件改进了视觉对象处理。 现在，当观察程序更新网格后，材料将被保留，而在以前，它们会被重置为配置文件中配置的默认 VisibleMaterial。

这使开发人员能够更改网格材料，并且不会意外覆盖更改。

Link.xml 是在 MixedRealityToolkit.Generated 文件夹中创建的

引入 Unity 包管理器 MRTK 后，MRTK 现在会将 link.xml 文件写入 Assets/MixedRealityToolkit.Generated 文件夹（如果没有任何文件存在）。 建议将此文件（和 link.xml.meta）添加到源代码管理中。 Link.xml 用于影响 Unity 链接器的托管代码剥离功能。

有关 MRTK link.xml 文件的详细信息，请参阅 MRTK 和托管代码剥离一文。

Unity 2019.3+：MRTK 配置对话框不再尝试启用旧版 XR 支持

为了避免在使用 Unity 的 XR 平台时出现潜在冲突，已从 MRTK 配置对话框中删除启用旧版 XR 支持的选项。 如果需要，可以在 Unity 2019 中启用旧版 XR 支持，方法是使用“编辑”>“项目设置”>“播放器”>“XR 设置”>“支持的虚拟现实”。

减少 InitializeOnLoad 开销

我们一直在努力减少在 InitializeOnLoad 处理程序中运行的工作量，这应会提高内循环开发速度。 每次编译脚本、进入播放模式之前以及在编辑器启动时，都会运行 InitializeOnLoad 处理程序。 这些处理程序现在在更少的情况下运行，从而提高了 Unity 的总体响应能力。

在某些情况下，必须做出权衡：

边界控制已正式推出

Bounds control

边界控制已正式推出但未进行试验，它附带一系列新功能和大量 bug 修补程序。 下面是此更新的要点列表：

  • 属性拆分为多个配置，可以更轻松地设置边界控制
  • 可通过可编写脚本的对象共享配置
  • 每个属性/可脚本属性都是运行时可配置
  • 边界控制平台不再在属性更改时重新创建
  • 翻译句柄支持
  • 通过约束管理器实现完全约束支持
  • 弹性系统集成（试验性）

现在已弃用旧的边界框，可使用迁移工具或边界框检查器升级使用边界框的现有游戏对象。

约束管理器组件

现在，边界控制和对象操控器都可通过新的约束管理器组件来使用约束。 这两个组件将默认创建一个约束管理器，并自动处理任何附加的约束。

此外，自动行为约束管理器还附带了一种手动模式，允许用户决定应处理哪个约束。 因此，在属性检查器中显示约束的方式发生了一些更改。

Inspector view showing manual constraint manager selection

应用于组件的约束现在在约束管理器组件中显示为列表，而使用约束管理器（边界控制或对象操纵器）的组件现在将显示选定的约束管理器和模式（自动或手动）。 有关详细信息，请参阅文档中的约束管理器部分。

HoloLens 2 按钮材料更新

更新了 HoloLens 2 按钮的前固定架材料，删除了 MRC 中的黑色。

HoloLens 2 button material update

说明面板更新，可移动示例场景

更新了说明面板。 (SceneDescriptionPanelRev.prefab) 新设计提供了一个可抓取的顶部栏，允许用户调整/移动整个场景。

Description panel update

空间网格可视化效果 - 隔空敲击时脉冲

更新了空间网格的脉冲着色器示例，以匹配 HoloLens 2 的 shell 行为。

Pulse on air-tap

弹性系统（实验性）

Elastic System2

MRTK 现在附带了一个弹性模拟系统，该系统包含各种可扩展的灵活子类，为四维四元数弹簧、三维量弹簧和简单线性弹簧系统提供绑定。

目前，支持弹性管理器的以下 MRTK 组件可利用弹性功能：

Expanding an elastic menuGrabbing an elastic coffee cup

游戏杆（实验性）

可控制大型目标对象的游戏杆接口示例。

Joystick

颜色选取器（实验性）

一个实验性控件，可便于在运行时更改任何对象上的材料颜色。

Three different methods of color picker control

Four different methods of color picker control

中断性变更

程序集定义文件更改

某些 asmdef 文件已更改，现在仅支持 Unity 2018.4.13f1 或更高版本。 在早期版本的 Unity 中，更新到 MRTK 2.5 时将显示编译错误。 若要解决此情况，可转到项目窗口中的 Assets\MRTK\Providers\XRSDK\Microsoft.MixedReality.Toolkit.Providers.XRSDK.asmdef，并删除检查器中缺少的引用。 使用 Assets\MRTK\Providers\Oculus\XRSDK\Microsoft.MixedReality.Toolkit.Providers.XRSDK.Oculus.asmdef 和 Assets\MRTK\Providers\WindowsMixedReality\XRSDK\Microsoft.MixedReality.Toolkit.Providers.XRSDK.WMR.asmdef 重复这些步骤。 请注意，在升级到 Unity 2019 时，必须通过将这三个 asmdef 文件替换为原始（即未修改的）文件来还原更改。

IMixedRealityPointerMediator

此接口已更新为具有新函数：

void SetPointerPreferences(IPointerPreferences pointerPreferences);

如果你有一个不把 DefaultPointerMediator 编入子类的自定义指针介体，就需要实现这个新函数。 有关添加此对象的原因的更多背景信息，请参阅此问题。 添加此对象是为了确保将指针首选项显式传递给介体，而不是根据存在使用 IPointerPreferences 的构造函数隐式完成。

Rest/设备门户 API

UseSSL 静态属性已从 Rest 移动到 DevicePortal。

如果之前已这样做…

Rest.UseSSL = true

立即执行此操作…

DevicePortal.UseSSL = true

Link.xml

如果应用程序以前使用的是 MRTK 的 NuGet 发行版，则 link.xml 文件已从 Foundation 包中删除。 若要还原代码保存规则，请在 Unity 中打开项目一次，这将在 Assets/MixedRealityToolkit.Generated 中创建一个默认 link.xml 文件。 建议将此文件（和 link.xml.meta）添加到源代码管理中。

转换约束更改

TargetTransform 属性已被标记为过时，因为它没有被约束系统使用。 约束逻辑基于传递到 Initialize 和 Apply 方法的转换。 依赖此属性的派生用户约束可通过存储约束组件的转换，在其实现中缓存 TargetTransform 以实现相同的行为。

存储的初始世界构成 worldPoseOnManipulationStart 数据类型已从 MixedRealityPose 更改为 MixedRealityTransform，其中包括操作对象的本地缩放值。 进行此更改后，不再需要单独缓存任何初始缩放值。

IMixedRealityDictationSystem 中的新属性

新属性 AudioClip 已添加到 IMixedRealityDictationSystem 接口。 AudioClip 属性可访问与当前听写会话关联的音频剪辑。 用户必须在其实现接口的脚本中实现该属性。

已拒绝服务 facade

2.5 版中已拒绝服务 facade。 最初添加此功能是为了简化 MRTK 配置文件的配置（通过创建代表每个 MRTK 服务的虚假场景内 GameObject）。 从长远来看，我们希望避免创建虚假的游戏内对象并试图使它们保持同步（因为众所周知，数据同步和“真相来源”问题难以扩展和解决）。

版本 2.5 中保留了服务 facade 处理程序以确保项目升级顺利进行 - 项目中存在的任何 facade 都将被服务 facade 处理程序删除，以确保在版本 2.5 中打开的场景得到自动修复。

未来版本将删除与服务 facade 功能关联的其余代码。

向输入模拟服务添加运动控制器

现在，运动控制器模拟与现有的手部模拟一起以编辑器播放模式提供。 为了启用此更改，许多当前函数/字段/属性现已被标记为过时，其中 InputSimulationService.cs 和 MixedRealityInputSimulationProfile.cs 做出了重大更改。 相关代码的逻辑和行为在很大程度上保持不变，大多数过时的功能等都与将“手”的引用替换为更通用的术语“控制器”（例如将 DefaultHandSimulationMode 替换为 DefaultControllerSimulationMode）有关。 除获取新名称之外，某些新函数的返回类型也会更新以匹配名称/行为更改（例如，基于原始 GetHandDevice 的 GetControllerDevice 现在返回 BaseController 而不是 SimulatedHand）。

IInputSimulationService 现在具有新属性 MotionControllerDataLeft 和 MotionControllerDataRight。 MixedRealityInputSimulationProfile 现在包含用于特定运动控制器按钮的键盘映射的新字段。

已知问题

CameraCache 可能会在关闭时创建新的相机

在某些情况下（例如，在 Unity 编辑器中使用 LeapMotion 提供程序时），CameraCache 可能会在关闭时重新创建 MainCamera。 有关详细信息，请参阅此问题。

通过 Unity 包管理器导入示例时出现 FileNotFoundException

根据项目路径的长度，通过 Unity 包管理器导入示例可能会在 Unity 控制台中生成 FileNotFoundException 消息。 造成这种情况的原因是丢失文件的路径长于 MAX_PATH（256 个字符）。 要解决此问题，请缩短项目路径的长度。

未指定空间音响。 应用程序将不支持空间音效

如果未配置音频空间音响，则会出现“未指定空间音响”警告。 如果没有安装 XR 包，就会发生这种情况，因为 Unity 在这些包中包含空间音响。

要解决此问题，请确保：

  • “窗口”>“包管理器”中安装了一个或多个 XR 包

  • 转到“混合现实工具包”>“实用工具”>“配置 Unity 项目”，并选择“音频空间音响”

    Select Audio Spatializer

NullReferenceException：对象引用未设置为对象 (SceneTransitionService.Initialize) 的实例

在某些情况下，打开 EyeTrackingDemo-00-RootScene 可能会导致 SceneTransitionService 类的 Initialize 方法出现 NullReferenceException。 此错误是由于未设置场景转换服务的配置文件。 若要解决此问题，请使用以下步骤：

  • 导航到层次结构中的 MixedRealityToolkit 对象
  • 在“检查器”窗口中，选择“Extensions”
  • 如果未展开 Scene Transition Service，请将其展开
  • 将 Configuration Profile 值设置为 MRTKExamplesHubSceneTransitionServiceProfile

Fix Scene Transition

Oculus Quest

当前，在面向独立版平台时使用 Oculus XR 插件有一个已知问题。 查看 Oculus bug tracker/forums/release notes，了解更新。

此 bug 表示为以下 3 个错误：

Oculus XR Plugin Error

UnityUI 和 TextMeshPro

较新版本的 TextMeshPro（1.5.0+ 或 2.1.1+）存在一个已知问题，即下拉列表和粗体字符间距的默认字体大小已更改。

TMP image

可通过降级到早期版本的 TextMeshPro 来解决此问题。 有关更多详细信息，请参阅问题 #8556。