hz-xr-simulator-install-and-configure
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMeta XR Simulator Installation and Configuration
Meta XR Simulator 安装与配置
When to Use This Skill
何时使用此 Skill
- You need to test a Meta VR 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 Meta VR apps
- You want to validate core interactions, UI, and locomotion before deploying to hardware
- 需要在未连接物理头显的情况下测试 Meta VR 应用
- 希望在开发过程中快速迭代，而无需每次都部署到设备
- 正在设置需要对 Meta VR 应用进行自动化测试的 CI/CD 流水线
- 希望在部署到硬件前验证核心交互、UI 和移动逻辑
What is Meta XR Simulator
Meta XR Simulator 是什么
Meta XR Simulator is a desktop tool that simulates a Meta VR 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 Meta VR hardware performance. It runs on your desktop GPU and CPU. Its purpose is functional testing, not performance profiling.
Meta XR Simulator 是一款桌面工具，可在开发计算机上模拟 Meta VR 环境。它会拦截应用程序发起的 OpenXR runtime 调用，并提供模拟的头显追踪、控制器输入、手部追踪和环境数据，使你能够直接在引擎编辑器中运行和测试 VR/MR 应用，或将其作为独立的桌面构建运行。
该模拟器不会复现 Meta VR 硬件的性能。它运行在桌面 GPU 和 CPU 上，其用途是功能测试，而非性能分析。
Supported Platforms
支持的平台
| Platform | Support Level |
|---|---|
| Windows 10/11 (64-bit) | Full support |
| macOS | Limited support |
| 平台 | 支持级别 |
|---|---|
| Windows 10/11（64 位） | 完全支持 |
| macOS | 有限支持 |
Supported App Types
支持的应用类型
- Unity via Meta XR SDK (com.meta.xr.sdk.core and related packages)
- Unreal Engine via Meta XR Plugin (formerly Oculus VR Plugin)
- Native OpenXR applications using Meta XR Simulator as the active OpenXR runtime
- Unity：通过 Meta XR SDK（com.meta.xr.sdk.core 及相关包）
- Unreal Engine：通过 Meta XR Plugin（ formerly Oculus VR Plugin）
- Native OpenXR：将 Meta XR Simulator 配置为当前生效的 OpenXR runtime
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 控制器按钮、摇杆和扳机键，像手持实体控制器一样测试交互。
- 模拟手部追踪：触发预设的手部姿势和手势序列，无需真实手部追踪即可测试捏合、抓取、戳击和自定义手势。
- 房间设置与 guardian 模拟：定义具有可配置房间尺寸、家具位置和 guardian 边界的虚拟活动空间，用于测试边界感知行为。
- Passthrough 模拟：为混合现实应用测试提供合成的 Passthrough 摄像头画面，用于验证场景理解和平面检测逻辑。
- 可编写脚本的测试场景：自动执行输入序列、录制和回放会话，并与 CI/CD 集成以进行回归测试。
Quick Start
快速开始
- Download XR Simulator from Meta Quest Developer Hub (MQDH) under Tools, from the Meta developer downloads page, or straight from the CLI with .
metavr tools install xrsim - 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.
- Native OpenXR: Configure Meta XR Simulator as the active OpenXR runtime, then launch the desktop OpenXR build.
- Press Play in the editor. Your application runs in the simulator instead of requiring a connected headset.
For detailed steps, see Installation Guide.
After the simulator is installed and integrated with the project, use
to launch it, inspect runtime state, change simulated
device or input settings, manage layers, and record compositor output.
hz-xr-simulator-control- 从 Meta Quest Developer Hub（MQDH）的 Tools 菜单、Meta 开发者下载页面下载 XR Simulator，或直接通过 CLI 执行 。
metavr tools install xrsim - 在 Windows 上运行安装程序或在 macOS 上解压压缩包，以完成安装和配置。
- 在引擎中启用 XR Simulator：
- Unity：打开 Edit > Project Settings > XR Plug-in Management，将 Meta XR Simulator 启用为当前生效的 runtime。
- Unreal：打开 Project Settings > Plugins > Meta XR，启用 XR Simulator 选项。
- Native OpenXR：将 Meta XR Simulator 配置为当前生效的 OpenXR runtime，然后启动桌面 OpenXR 构建。
- 在编辑器中按 Play。应用将在模拟器中运行，不再需要连接头显。
有关详细步骤，请参阅安装指南。
模拟器安装并与项目集成后，使用
启动模拟器、检查运行时状态、更改模拟设备或输入设置、管理图层并录制合成器输出。
hz-xr-simulator-controlControls 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 the device'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 app），模拟器将不会拦截应用的 OpenXR 调用。必须通过全局方式或按引擎将 Meta XR Simulator 设置为当前生效的 OpenXR runtime。在 Windows 上，检查 以查看当前生效的 runtime。
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\ActiveRuntime - Unity XR Plug-in Management 配置混淆 -- 在 Unity 中启用“Meta XR Simulator”并不会自动禁用“Oculus”或“OpenXR” loader。如果同时启用多个 loader，Unity 可能会选择错误的 loader。请先禁用所有其他 XR loader，再启用模拟器。
- 模拟器并不等同于设备表现 -- 模拟器使用桌面 GPU 和桌面驱动程序进行渲染。在桌面上可以正常编译的 Shader，在 Quest 的 Adreno GPU 上可能编译失败或表现不同。绝不要将“在模拟器中可用”等同于“在设备上可用”。
- 手部追踪姿势是预设的，而非连续追踪 -- 模拟器使用通过键盘快捷键触发的离散手部姿势，而不是连续的手指追踪。因此，你无法测试精细的捏合距离阈值、抓取物理效果或手势识别质量。手部追踪验证应使用物理设备。
- Passthrough 是合成内容，而非基于摄像头的画面 -- 模拟器提供合成环境用于 Passthrough 测试。场景理解结果（平面、网格、语义标签）基于已配置的房间，而非真实传感器数据。反射表面、透明物体或低光照等边缘情况无法复现。
- 不支持热性能或性能分析 -- 模拟器无法复现设备的温度降频、CPU/GPU 频率调节或内存压力行为。在模拟器中进行的性能测试不能用于验证设备端性能。
- 防火墙和杀毒软件干扰 -- 某些企业级杀毒软件会阻止模拟器的本地 IPC。如果模拟器连接后立即断开，或无法启动 XR 会话，请检查模拟器可执行文件的防火墙规则。
- macOS 支持有限 -- 在 macOS 上仅可使用部分功能。控制器模拟可正常工作，但手部追踪、Passthrough 和房间设置未得到完整支持。如需完整的模拟器体验，请使用 Windows。
Limitations
限制
- No GPU performance profiling: Your desktop GPU has different characteristics than the device'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 device's thermal management behavior is not simulated.
- Rendering differences: Resolution, foveated rendering, and display refresh rate do not match Meta VR hardware.
Always perform final validation on physical Meta VR hardware before submission or release.
- 不支持 GPU 性能分析：桌面 GPU 的特性与设备的移动 GPU 不同。帧时间、Shader 性能和填充率不会与设备表现一致。
- 不提供真实传感器数据：IMU、摄像头和深度传感器数据均为合成数据，追踪中的边缘情况可能无法复现。
- API 行为差异：某些平台 API（例如系统键盘、社交、IAP）在模拟器中会返回模拟或桩数据。
- 无触觉反馈：无法在模拟器中感受控制器触觉反馈。
- 无温度降频：不会模拟设备的温度管理行为。
- 渲染差异：分辨率、注视点渲染和显示刷新率与 Meta VR 硬件不一致。
提交或发布前，务必在物理 Meta VR 硬件上进行最终验证。
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 集成