【OpenXR】OpenXR接入MRTK笔记

引言

OpenXR 是 Khronos Group 推出的开放标准 XR（扩展现实）API，旨在提供跨平台、跨设备的统一接口，支持 HoloLens 2、Quest、Pico 等设备。MRTK（Mixed Reality Toolkit）是 Microsoft 开发的开源 Unity 工具包，用于简化混合现实（MR）应用开发，包括输入系统、UI 交互、空间感知等。OpenXR 接入 MRTK 允许开发者使用统一的 XR 后端构建跨平台应用，避免平台特定 SDK 的碎片化。

本笔记基于 MRTK3（最新稳定版，2025 年 10 月更新支持 Unity 2022.3 LTS 和 OpenXR 1.1），聚焦 Unity 项目集成。MRTK3 构建在 Unity XR Interaction Toolkit 上，提供更好的 OpenXR 支持，包括手势、控制器可视化和眼动追踪。 适用于 HoloLens 2、Quest Pro 等设备，推荐 Unity 2020.3+ 和 OpenXR Plugin 1.9+。

注意：MRTK2 已过时（仅支持 OpenXR 实验性），优先使用 MRTK3。跨平台时，确保设备支持 OpenXR 扩展（如手追踪）。

环境准备

硬件与软件要求

要求	推荐配置	说明
Unity 版本	2022.3 LTS 或更高	支持 Render Graph 和 URP/HDRP
MRTK 版本	3.2.0+	通过 Mixed Reality Feature Tool 安装
OpenXR Plugin	1.9.1+	Unity Package Manager (UPM) 导入
设备	HoloLens 2 / Quest 2+ / PC VR	启用开发者模式
其他	Windows 10/11, Visual Studio 2022	UWP/IL2CPP 构建

• 安装 Unity Hub：下载最新版，创建 3D Core 项目模板。
• 启用开发者模式：设备设置 > 开发者选项 > OpenXR 运行时。

接入步骤详解

1. 创建新项目

1. 打开 Unity Hub > New Project > 选择 Unity 2022.3+ > 3D (Core) 模板。
2. 项目名称：如 “OpenXR_MRTK_Demo”。
3. 打开项目，确保 Platform 为 PC/Standalone（后续切换）。

2. 安装 OpenXR Plugin

1. Window > Package Manager > Unity Registry > 搜索 “OpenXR Plugin” > Install（最新版 1.9+）。
2. Edit > Project Settings > XR Plug-in Management：

• 启用 Initialize XR on Startup。
• PC Standalone 标签：勾选 OpenXR。
• Android（Quest）：勾选 OpenXR（需 Oculus App Lab 权限）。

1. 添加交互配置文件：

• Project Settings > XR Plug-in Management > OpenXR > Android/Standalone。
• Interactions Profiles > + > 添加 “Microsoft Motion Controller Profile” 和 “Hand Tracking Profile”（手追踪）。

3. 安装 MRTK3

1. 下载 Mixed Reality Feature Tool（从 Microsoft Store 或 GitHub）。
2. 运行工具 > Install MRTK3 > 选择项目 > Install（包含 Foundation、XR Interaction Toolkit 等）。

• 核心包：Mixed Reality Toolkit Foundation（必需）。

1. Project Settings > XR Plug-in Management > OpenXR > Feature Groups：

• 添加 “Hand Tracking” 和 “Plane Detection” 等扩展。

4. 配置 MRTK Profile

1. GameObject > MRTK > Add MRTK to Scene（自动添加 MRTK Manager）。
2. Project Settings > MRTK3：

• Subsystem Profiles > XR Rig > DefaultOpenXRConfigProfile（克隆自定义）。

1. MRTK Manager Inspector：

• Mixed Reality UX Provider：启用手势、控制器。
• Input：Rail View（手势）、Articulated Hand（控制器）。

1. 验证设置：

• Mixed Reality > OpenXR Project Validation > Fix All（修复交互配置文件、权限等）。
• 常见修复：添加 AndroidManifest.xml 修改（Quest 键盘支持）。

5. 场景设置与测试

1. 添加 XR Rig：Hierarchy > XR > Room-Scale XR Rig（MRTK 预制体）。
2. 相机配置：Main Camera > 添加 Tracked Pose Driver（OpenXR 追踪）。
3. 构建与部署：

• File > Build Settings > Android/UWP > Switch Platform。
• Quest：连接 USB > Build and Run（启用 Meta Quest Link 快速迭代）。
• HoloLens：UWP 构建 > Device Portal 部署。

1. 测试：

• 运行编辑器：Play Mode > XR Device Simulator（Window > XR > Mock HMD）。
• 设备测试：手势交互（捏合选择）、控制器可视化。

代码示例（C# 脚本，附加到 XR Rig）：

using Microsoft.MixedReality.Toolkit;
using Microsoft.MixedReality.Toolkit.Input;
using UnityEngine;

public class OpenXRInputTest : MonoBehaviour
{
    private IMixedRealityInputSystem inputSystem;

    void Start()
    {
        inputSystem = CoreServices.InputSystem;
        inputSystem.RaiseActionInputPerformed(InputActionEventData.Create(new Vector3(1,0,0), HandEventData.InputHandType.Left));
    }

    void Update()
    {
        // 检测手追踪
        if (inputSystem.DetectedInputSources.Count > 0)
        {
            var source = inputSystem.DetectedInputSources[0];
            Debug.Log($"Hand Position: {source.Position}");
        }
    }
}

核心功能配置

输入系统

• 手势：MRTK > Input > Gesture Provider > OpenXR Hand Tracking。
• 控制器：OpenXR Controller Model Provider（系统模型支持）。
• 眼动：Eye Gaze Provider（HoloLens 专用）。

空间感知

• 平面检测：AR Plane Manager（AR Foundation + OpenXR）。
• 锚点：AR Anchor Manager（持久化位置）。

UI 与交互

• MRTK UI：Canvas > MRTK > Standard Button（支持空气手势）。
• Ray Interactor：Poke/Hand Ray（Quest 手追踪）。

功能	OpenXR 扩展	MRTK 配置
手追踪	XR_HAND_TRACKING	HandTrackingFeature
控制器	Motion Controller Profile	ArticulatedHandController
平面	PLANE_DETECTION	SpatialAwarenessSystem
网格	MESH_DETECTION	ARMeshManager

优化与常见问题

性能优化

• LOD：使用 MRTK Spatial Awareness LOD。
• 分辨率：Project Settings > XR > Render Scale 0.8（移动端）。
• 批处理：启用 Dynamic Batching。

常见问题解决

问题	原因	解决方案
构建失败	缺少交互 Profile	OpenXR Settings > Add Microsoft Hand Profile
手追踪无效	扩展未启用	Feature Groups > Hand Tracking > Enable
Quest 部署黑屏	AndroidManifest 未改	添加 <uses-feature android:name="android.hardware.vr.high_performance" />
控制器模型缺失	包未导入	UPM > Oculus XR Plugin（可选，Quest 兼容）
验证工具报错	旧插件	Update OpenXR to 1.9+，Fix All

调试提示：使用 XR Device Simulator 测试输入；OpenXR Developer Tools（Windows）监控追踪。

高级扩展

• Quest 部署：避免 Oculus Integration，使用纯 OpenXR；启用 Link for 热重载。
• 多模态：结合手/控制器（OpenXR 多 Profile）。
• 自定义 Provider：继承 OpenXRRuntimeSubsystem 扩展功能。

资源链接

• 官方文档：https://learn.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/ （MRTK3 OpenXR 指南）
• 示例项目：GitHub microsoft/OpenXR-Unity-MixedReality-Samples
• 中文教程：https://learn.microsoft.com/zh-cn/windows/mixed-reality/develop/unity/new-openxr-project-with-mrtk
• 社区：Reddit r/Unity3D、MRTK GitHub Discussions
• 视频：YouTube “MRTK3 OpenXR Tutorial”（搜索）。

此笔记聚焦实用接入，实际项目中测试设备兼容性。如需特定功能代码或 Quest/HoloLens 深度部署，请补充细节！