hz-xr-simulator-install-and-configure

Meta XR Simulator 安装与配置

何时使用此技能

• 需要在未连接实体头显的情况下测试 Meta VR 应用
• 希望在开发过程中快速迭代，无需每次都部署到设备
• 正在设置需要自动测试 Meta VR 应用的 CI/CD 流水线
• 希望在部署到硬件之前验证核心交互、UI 和移动方式

什么是 Meta XR Simulator

Meta XR Simulator 是一款桌面工具，可在开发计算机上模拟 Meta VR 环境。它会拦截应用发出的 OpenXR 运行时调用，并提供模拟的头显追踪、控制器输入、手部追踪和环境数据，让你能够直接在引擎编辑器中运行和测试 VR/MR 应用，或将其作为独立桌面版本运行。

模拟器无法复现 Meta VR 硬件的性能。它运行在桌面 GPU 和 CPU 上，旨在进行功能测试，而非性能分析。

支持的平台

平台	支持级别
Windows 10/11（64 位）	完全支持
macOS	有限支持

支持的应用类型

• Unity，通过 Meta XR SDK（com.meta.xr.sdk.core 及相关软件包）
• Unreal Engine，通过 Meta XR Plugin（原 Oculus VR Plugin）
• 原生 OpenXR 应用，将 Meta XR Simulator 用作活动的 OpenXR 运行时

主要功能

• 模拟头显追踪：通过鼠标和键盘控制头部位置和旋转。无需佩戴头显即可在虚拟场景中移动。
• 模拟控制器输入：将键盘按键映射到 Quest Touch 控制器按钮、摇杆和扳机。像使用实体控制器一样测试交互。
• 模拟手部追踪：触发预定义的手势和手势序列。无需真实手部追踪即可测试捏合、抓取、戳点和自定义手势。
• 房间设置和边界系统模拟：定义虚拟游玩空间，可配置房间尺寸、家具摆放和边界。测试依赖边界的行为。
• 透视模拟：提供合成透视摄像头画面，用于混合现实应用测试。验证场景理解和平面检测逻辑。
• 可编写脚本的测试场景：自动执行输入序列、录制和回放会话，并集成到 CI/CD 中进行回归测试。

快速入门

1. 从 Meta Quest Developer Hub（MQDH）的 Tools 中下载 XR Simulator，也可从 Meta 开发者下载页面获取，或直接通过 CLI 运行 metavr tools install xrsim。
2. 安装并配置：在 Windows 上运行安装程序，或在 macOS 上解压归档文件。
3. 在引擎中启用 XR Simulator：
   • Unity：打开 Edit > Project Settings > XR Plug-in Management，并启用 Meta XR Simulator 作为活动运行时。
   • Unreal：打开 Project Settings > Plugins > Meta XR，并启用 XR Simulator 选项。
   • 原生 OpenXR：将 Meta XR Simulator 配置为活动的 OpenXR 运行时，然后启动桌面 OpenXR 版本。
4. 在编辑器中按下 Play。应用将在模拟器中运行，无需连接头显。

详细步骤请参阅安装指南。

安装模拟器并将其集成到项目后，使用 hz-xr-simulator-control 启动模拟器、检查运行时状态、更改模拟设备或输入设置、管理图层，以及录制合成器输出。

控件概览

操作	输入
环顾四周	按住鼠标右键并移动鼠标
前进/后退/向左/向右移动	W / S / A / D
向上/向下移动	E / Q
模拟控制器按钮	已映射的键盘按键（参见配置）
触发手势	数字键或已配置的快捷键

完整的输入映射详情请参阅配置指南。

测试工作流

模拟器支持多种测试模式：

• 交互式测试：手动浏览场景并测试交互
• 自动化测试：编写输入序列脚本，用于回归测试
• CI/CD 集成：在自动化流水线中运行无头模拟器构建

详细工作流请参阅 测试工作流。

注意事项

设置和使用 Meta XR Simulator 时，常见的陷阱包括：

• OpenXR 运行时冲突——如果将其他 OpenXR 运行时设为系统默认运行时（SteamVR、Windows Mixed Reality、Oculus PC app），模拟器将无法拦截应用的 OpenXR 调用。必须将 Meta XR Simulator 设为活动的 OpenXR 运行时，可以全局设置，也可以按引擎设置。在 Windows 上，检查 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\ActiveRuntime，查看当前活动的运行时。
• Unity XR Plug-in Management 易引起混淆——在 Unity 中，在 XR Plug-in Management 里启用“Meta XR Simulator”不会自动禁用“Oculus”或“OpenXR”加载器。如果启用了多个加载器，Unity 可能会选择错误的加载器。启用模拟器之前，请禁用所有其他 XR 加载器。
• 模拟器不代表与设备表现一致——模拟器使用桌面 GPU 和桌面驱动程序进行渲染。在桌面上编译正常的着色器，在 Quest 的 Adreno GPU 上可能会失败或表现不同。切勿将“在模拟器中运行正常”等同于“在设备上运行正常”。
• 手部追踪姿势是预定义的，并非连续变化——模拟器使用键盘快捷键触发离散的手部姿势，而非连续的手指追踪。这意味着你无法测试精细的捏合距离阈值、抓握物理效果或手势识别质量。请使用实体设备验证手部追踪。
• 透视画面为合成内容，并非基于摄像头——模拟器提供合成环境用于透视测试。场景理解结果（平面、网格、语义标签）基于配置的房间，而非真实传感器数据。反光表面、透明物体或弱光环境等边缘情况无法复现。
• 无法进行热管理或性能分析——模拟器无法复现设备的热降频、CPU/GPU 频率缩放或内存压力行为。在模拟器中进行的性能测试无法用于有意义的设备端性能验证。
• 防火墙和防病毒软件干扰——某些企业防病毒软件会阻止模拟器的本地 IPC。如果模拟器连接后立即断开，或无法启动 XR 会话，请检查模拟器可执行文件的防火墙规则。
• macOS 支持有限——在 macOS 上，只有部分功能可用。控制器模拟可正常工作，但不完全支持手部追踪、透视和房间设置。若要获得完整的模拟器体验，请使用 Windows。

限制

• 无法分析 GPU 性能：桌面 GPU 的特性与设备的移动 GPU 不同。帧时间、着色器性能和填充率都无法反映设备上的表现。
• 没有实际传感器数据：IMU、摄像头和深度传感器数据均为合成数据。追踪中的边缘情况可能无法复现。
• API 行为存在差异：某些平台 API（例如系统键盘、社交和 IAP）在模拟器中会返回模拟数据或存根数据。
• 没有触觉反馈：在模拟器中无法感受到控制器的触觉反馈。
• 没有热降频：不会模拟设备的热管理行为。
• 渲染效果存在差异：分辨率、注视点渲染和显示刷新率与 Meta VR 硬件不一致。

提交或发布前，务必在 Meta VR 实体硬件上进行最终验证。

参考资料

• 安装指南——系统要求、下载和特定引擎的设置
• 配置指南——环境、输入映射、功能标志和 JSON 配置
• 测试工作流——测试模式、脚本编写、调试和 CI/CD 集成