hz-xr-simulator-setup

Meta XR Simulator 设置

何时使用此技能

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

什么是 Meta XR Simulator

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

模拟器不会复现 Quest 硬件的性能。它运行在桌面 GPU 和 CPU 上，目的是进行功能测试，而非性能分析。

支持的平台

平台	支持级别
Windows 10/11 (64-bit)	完全支持
macOS	有限支持

支持的引擎

• Unity：通过 Meta XR SDK（com.meta.xr.sdk.core 及相关软件包）
• Unreal Engine：通过 Meta XR Plugin（前身为 Oculus VR Plugin）

主要功能

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

快速入门

1. 从 Meta Quest Developer Hub (MQDH) 的 Tools 下，或从 Meta 开发者下载页面下载 XR Simulator。
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 选项。
4. 在编辑器中按下 Play。应用将在模拟器中运行，无需连接头显。

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

控制概览

操作	输入
环顾四周	按住鼠标右键并移动鼠标
向前/后/左/右移动	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 上可能会失败或表现不同。切勿把“在模拟器中正常运行”当作“在设备上正常运行”。
• 手部追踪姿势是预定义的，并非连续追踪 -- 模拟器使用键盘快捷键触发离散的手部姿势，而非连续手指追踪。因此，你无法测试精细的捏合距离阈值、抓握物理效果或手势识别质量。请使用实体设备验证手部追踪。
• 透视效果是合成的，并非基于摄像头 -- 模拟器为透视测试提供合成环境。场景理解结果（平面、网格、语义标签）基于配置的房间，而非真实传感器数据。反光表面、透明物体或低光照条件等边缘情况无法复现。
• 无法进行热管理或性能分析 -- 模拟器无法复现 Quest 的热降频、CPU/GPU 频率缩放或内存压力行为。在模拟器中进行的性能测试无法用于验证设备上的性能。
• 防火墙和防病毒软件干扰 -- 某些企业防病毒软件会阻止模拟器的本地 IPC。如果模拟器已连接却立即断开，或无法启动 XR 会话，请检查模拟器可执行文件的防火墙规则。
• macOS 支持有限 -- 在 macOS 上，只有部分功能可用。控制器模拟可以正常工作，但不完全支持手部追踪、透视效果和房间设置。要体验完整的模拟器功能，请使用 Windows。

限制

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

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

参考资料

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