hz-xr-simulator-setup
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMeta XR Simulator Setup
Meta XR Simulator 设置指南
When to Use This Skill
适用场景
- You need to test a Quest VR or MR application without a physical headset connected
- You want rapid iteration during development without deploying to device each time
- You are setting up CI/CD pipelines that need automated testing of Quest apps
- You want to validate core interactions, UI, and locomotion before deploying to hardware
- 需在未连接物理头显的情况下测试Quest VR或MR应用
- 希望在开发过程中快速迭代,无需每次部署到设备
- 正在搭建需要自动测试Quest应用的CI/CD流水线
- 希望在部署到硬件前验证核心交互、UI和移动逻辑
What is Meta XR Simulator
什么是Meta XR Simulator
Meta XR Simulator is a desktop tool that simulates a Meta Quest environment on your development machine. It intercepts the OpenXR runtime calls your application makes and provides simulated headset tracking, controller input, hand tracking, and environment data, allowing you to run and test VR/MR applications directly in your engine's editor or as standalone desktop builds.
The simulator does not replicate Quest hardware performance. It runs on your desktop GPU and CPU. Its purpose is functional testing, not performance profiling.
Meta XR Simulator是一款桌面工具,可在开发机器上模拟Meta Quest环境。它会拦截应用发出的OpenXR runtime调用,并提供模拟的头显追踪、控制器输入、手部追踪和环境数据,让你能够直接在引擎编辑器中或作为独立桌面构建运行并测试VR/MR应用。
该模拟器不会复刻Quest硬件性能,它运行在你的桌面GPU和CPU上,其用途是功能测试,而非性能分析。
Supported Platforms
支持平台
| Platform | Support Level |
|---|---|
| Windows 10/11 (64-bit) | Full support |
| macOS | Limited support |
| 平台 | 支持等级 |
|---|---|
| Windows 10/11(64位) | 完全支持 |
| macOS | 有限支持 |
Supported Engines
支持引擎
- Unity via Meta XR SDK (com.meta.xr.sdk.core and related packages)
- Unreal Engine via Meta XR Plugin (formerly Oculus VR Plugin)
- Unity:通过Meta XR SDK(com.meta.xr.sdk.core及相关包)
- Unreal Engine:通过Meta XR Plugin(前身为Oculus VR Plugin)
Key Features
核心功能
- Simulated headset tracking: Control head position and rotation with mouse and keyboard. Move through your virtual scene without wearing a headset.
- Simulated controller input: Map keyboard keys to Quest Touch controller buttons, thumbsticks, and triggers. Test interactions as if holding physical controllers.
- Simulated hand tracking: Trigger predefined hand poses and gesture sequences. Test pinch, grab, poke, and custom gestures without real hand tracking.
- Room setup and guardian simulation: Define a virtual play space with configurable room dimensions, furniture placement, and guardian boundaries. Test boundary-aware behavior.
- Passthrough simulation: Provide synthetic passthrough camera feeds for mixed reality application testing. Validate scene understanding and plane detection logic.
- Scriptable testing scenarios: Automate input sequences, record and replay sessions, and integrate with CI/CD for regression testing.
- 模拟头显追踪:通过鼠标和键盘控制头部位置与旋转,无需佩戴头显即可在虚拟场景中移动。
- 模拟控制器输入:将键盘按键映射到Quest Touch控制器的按钮、摇杆和扳机键,如同握持物理控制器般测试交互。
- 模拟手部追踪:触发预定义的手部姿势和手势序列,无需真实手部追踪即可测试捏取、抓取、戳击及自定义手势。
- 房间设置与安全边界模拟:定义具有可配置房间尺寸、家具布局和安全边界的虚拟游戏空间,测试边界感知行为。
- 透视模拟:为混合现实应用测试提供合成透视相机画面,验证场景理解和平面检测逻辑。
- 可脚本化测试场景:自动化输入序列,录制和重放会话,并与CI/CD集成以进行回归测试。
Quick Start
快速开始
- Download XR Simulator from Meta Quest Developer Hub (MQDH) under Tools, or from the Meta developer downloads page.
- Install and configure by running the installer on Windows or extracting the archive on macOS.
- Enable XR Simulator in your engine:
- Unity: Open Edit > Project Settings > XR Plug-in Management, and enable Meta XR Simulator as the active runtime.
- Unreal: Open Project Settings > Plugins > Meta XR, and enable the XR Simulator option.
- Press Play in the editor. Your application runs in the simulator instead of requiring a connected headset.
For detailed steps, see Installation Guide.
- 下载XR Simulator:从Meta Quest Developer Hub(MQDH)的工具板块,或Meta开发者下载页面获取。
- 安装与配置:在Windows上运行安装程序,在macOS上解压归档文件。
- 在引擎中启用XR Simulator:
- Unity:打开Edit > Project Settings > XR Plug-in Management,将Meta XR Simulator设为活跃运行时。
- Unreal:打开Project Settings > Plugins > Meta XR,启用XR Simulator选项。
- 在编辑器中点击Play:应用将在模拟器中运行,无需连接头显。
如需详细步骤,请查看安装指南。
Controls Overview
控制概览
| Action | Input |
|---|---|
| Look around | Hold right mouse button + move mouse |
| Move forward/back/left/right | W / S / A / D |
| Move up/down | E / Q |
| Simulate controller buttons | Mapped keyboard keys (see configuration) |
| Trigger hand poses | Number keys or configured shortcuts |
For full input mapping details, see Configuration Guide.
| 操作 | 输入方式 |
|---|---|
| 环顾四周 | 按住右键 + 移动鼠标 |
| 前后左右移动 | W / S / A / D |
| 上下移动 | E / Q |
| 模拟控制器按钮 | 映射的键盘按键(详见配置) |
| 触发手部姿势 | 数字键或配置的快捷键 |
如需完整的输入映射详情,请查看配置指南。
Testing Workflows
测试工作流
The simulator supports several testing patterns:
- Interactive testing: Manually navigate your scene and test interactions
- Automated testing: Script input sequences for regression testing
- CI/CD integration: Run headless simulator builds in automated pipelines
For detailed workflows, see Testing Workflows.
模拟器支持多种测试模式:
- 交互式测试:手动导航场景并测试交互
- 自动化测试:编写输入序列脚本以进行回归测试
- CI/CD集成:在自动化流水线中运行无头模拟器构建
如需详细工作流,请查看测试工作流。
Gotchas
常见陷阱
These are common pitfalls when setting up and using the Meta XR Simulator.
- OpenXR runtime conflict -- If another OpenXR runtime is set as the system default (SteamVR, Windows Mixed Reality, Oculus PC app), the simulator will not intercept your app's OpenXR calls. You must set Meta XR Simulator as the active OpenXR runtime, either globally or per-engine. On Windows, check to see which runtime is active.
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\ActiveRuntime - Unity XR Plug-in Management confusion -- In Unity, enabling "Meta XR Simulator" in XR Plug-in Management does not automatically disable "Oculus" or "OpenXR" loaders. If multiple loaders are enabled, Unity may pick the wrong one. Disable all other XR loaders before enabling the simulator.
- Simulator does not mean device parity -- The simulator renders on your desktop GPU with desktop drivers. Shaders that compile fine on desktop may fail or behave differently on Quest's Adreno GPU. Never treat "works in simulator" as "works on device."
- Hand tracking poses are predefined, not continuous -- The simulator uses discrete hand poses triggered by keyboard shortcuts, not continuous finger tracking. This means you cannot test fine-grained pinch distance thresholds, grasp physics, or gesture recognition quality. Use a physical device for hand tracking validation.
- Passthrough is synthetic, not camera-based -- The simulator provides a synthetic environment for passthrough testing. Scene understanding results (planes, meshes, semantic labels) are based on the configured room, not real sensor data. Edge cases like reflective surfaces, transparent objects, or low-light conditions will not reproduce.
- No thermal or performance profiling -- The simulator cannot reproduce Quest's thermal throttling, CPU/GPU frequency scaling, or memory pressure behavior. Performance tests in the simulator are not meaningful for on-device performance validation.
- Firewall and antivirus interference -- Some enterprise antivirus software blocks the simulator's local IPC. If the simulator connects but immediately disconnects or fails to start the XR session, check firewall rules for the simulator executable.
- macOS support is limited -- On macOS, only a subset of features is available. Controller simulation works, but hand tracking, passthrough, and room setup are not fully supported. Use Windows for the complete simulator experience.
以下是设置和使用Meta XR Simulator时的常见误区:
- OpenXR runtime冲突:如果其他OpenXR runtime(如SteamVR、Windows Mixed Reality、Oculus PC应用)被设为系统默认,模拟器将无法拦截应用的OpenXR调用。你必须将Meta XR Simulator设为活跃OpenXR runtime,可全局设置或按引擎设置。在Windows上,可查看来确认当前活跃的runtime。
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\ActiveRuntime - Unity XR插件管理混淆:在Unity中,在XR Plug-in Management中启用“Meta XR Simulator”不会自动禁用“Oculus”或“OpenXR”加载器。如果启用了多个加载器,Unity可能会选择错误的加载器。在启用模拟器前,请禁用所有其他XR加载器。
- 模拟器不等于设备一致性:模拟器在桌面GPU和桌面驱动上渲染。在桌面编译正常的着色器在Quest的Adreno GPU上可能会失败或表现不同。切勿将“在模拟器中可用”等同于“在设备上可用”。
- 手部追踪姿势为预定义,非连续追踪:模拟器使用通过键盘快捷键触发的离散手部姿势,而非连续手指追踪。这意味着你无法测试精细的捏取距离阈值、抓取物理效果或手势识别质量。需使用物理设备进行手部追踪验证。
- 透视为合成效果,非基于相机:模拟器为透视测试提供合成环境。场景理解结果(平面、网格、语义标签)基于配置的房间,而非真实传感器数据。反光表面、透明物体或低光照条件等边缘情况无法复现。
- 无热或性能分析功能:模拟器无法复现Quest的热节流、CPU/GPU频率缩放或内存压力行为。模拟器中的性能测试对设备性能验证无意义。
- 防火墙和杀毒软件干扰:部分企业杀毒软件会阻止模拟器的本地IPC。如果模拟器连接后立即断开或无法启动XR会话,请检查模拟器可执行文件的防火墙规则。
- macOS支持有限:在macOS上,仅部分功能可用。控制器模拟正常工作,但手部追踪、透视和房间设置未完全支持。如需完整的模拟器体验,请使用Windows系统。
Limitations
局限性
- No GPU performance profiling: Your desktop GPU has different characteristics than the Quest's mobile GPU. Frame timing, shader performance, and fill rate will not match device behavior.
- No actual sensor data: IMU, camera, and depth sensor data is synthesized. Edge cases in tracking may not reproduce.
- API behavior differences: Some platform APIs (e.g., system keyboard, social, IAP) return mock or stub data in the simulator.
- No haptic feedback: Controller haptics cannot be felt in the simulator.
- No thermal throttling: The Quest's thermal management behavior is not simulated.
- Rendering differences: Resolution, foveated rendering, and display refresh rate do not match Quest hardware.
Always perform final validation on physical Quest hardware before submission or release.
- 无GPU性能分析:你的桌面GPU与Quest的移动GPU特性不同。帧时序、着色器性能和填充率与设备行为不匹配。
- 无真实传感器数据:IMU、相机和深度传感器数据为合成数据。追踪中的边缘情况无法复现。
- API行为差异:部分平台API(如系统键盘、社交、IAP)在模拟器中返回模拟或存根数据。
- 无触觉反馈:无法在模拟器中感受到控制器的触觉反馈。
- 无热节流模拟:未模拟Quest的热管理行为。
- 渲染差异:分辨率、注视点渲染和显示刷新率与Quest硬件不匹配。
在提交或发布前,务必在物理Quest硬件上进行最终验证。
References
参考资料
- Installation Guide -- System requirements, download, and engine-specific setup
- Configuration Guide -- Environment, input mapping, feature flags, and JSON config
- Testing Workflows -- Testing patterns, scripting, debugging, and CI/CD integration
- 安装指南 -- 系统要求、下载及引擎专属设置
- 配置指南 -- 环境、输入映射、功能标志及JSON配置
- 测试工作流 -- 测试模式、脚本编写、调试及CI/CD集成