hz-xr-simulator-control

XR 模拟器控制

metavr 几乎完全是面向实体 Quest 或眼镜的 CLI：device、app、capture、input、log、 files 和 ui 都通过 ADB 与头显通信。xrsim 是其中一个命令组，用于驱动模拟的头显。选错命令组是 这里最常见的失败，而且不易察觉：metavr device list 会输出 No devices connected 并以 0 退出，因此错误的 答案看起来比正确的还正常。

此技能用于控制已存在的模拟器。安装模拟器或将其接入项目，属于 hz-xr-simulator-install-and-configure 的范围。

使用哪个命令组

目标涉及	使用	不要使用
模拟头显型号、IPD、刷新率	metavr xrsim device …	metavr device …（实体设备，ADB）
模拟器前端进程	metavr xrsim app …	metavr app …（头显上的 APK）
模拟的手部和控制器	metavr xrsim input …	metavr input …（向硬件发送按键事件）
模拟器的合成房间	metavr xrsim env …	—
合成器图层、模拟帧率	metavr xrsim layer / xrsim runtime fps	—
模拟器自身的日志	metavr xrsim runtime logs	metavr log / metavr adb logcat（设备 logcat）
模拟头显渲染的内容	metavr xrsim record	metavr capture（实体设备屏幕）
在实体头显上录制并回放应用的 OpenXR 调用	metavr tapedeck	metavr xrsim record（合成器像素，而非调用流）
SpatialSim 仿真器	metavr ssim	metavr xrsim（另一种模拟器）

将 Use 列理解为实现目标的正确工具，将 Not 列理解为你可能会误用的工具。最后两行列在此表中，是因为它们容易被混淆，而不是因为它们属于此技能的工作范围。

有三点值得明确说明，因为两边都有看似合理的命令：

• **“录制 OpenXR 会话”**是 CLI 中最容易混淆的意图。xrsim record 会将模拟器的合成器输出录制为 MP4；tapedeck 则会在实体设备上录制并回放应用的 OpenXR 调用流。两者不能互相替代。
• **“模拟器”**在此二进制程序中含义不明确。ssim 是 SpatialSim 仿真器，xrsim 是 Meta XR Simulator。
• 顶层和 xrsim 下都存在 device、app 和 input，所以同一个动词在不同命令组下含义不同。capture 则没有这种情况：不存在 xrsim capture，对应的模拟器命令是 xrsim record。

三个连接层级

进入 xrsim 后，命令需要什么决定了你会遇到哪种错误。

层级	命令	所需条件
本地	readme、runtime logs，以及 Linux 上不带参数的 record --output … --duration …	无需任何程序运行
生命周期	app launch/quit/ensure-running	无需任何程序运行——这些命令用于管理前端
前端	runtime activate/deactivate/list、env set/list	前端应用
运行时	runtime ping/status/info/fps、device *、input *、layer *、record start/stop/status	前端以及已连接的 XR 应用

device list 和 device refresh-rates 看起来像静态目录，但数据来自实时运行时。 input sources 会打印固定列表，但仍需要连接，因为 input 命令组会先建立连接， 再分派命令。

有两种情况，按常理猜测会得出相反的结论：

• app 命令组用于修复已停止的前端，而不是会被前端停止所阻挡。 app launch 和 app ensure-running 会在前端不存在时启动它。app quit 会请求 --port 上的前端关闭； 而 --force 会直接终止同一个进程，--all 则是明确用于停止主机上所有 MetaXRSimulator 的 选项。如果把生命周期命令视为前端层级，就会无法执行恢复操作。
• 在 Linux 上，不带参数的 record 属于本地操作。 不指定 --runtime-addr 时，它从不建立连接——它通过 ffmpeg 捕获帧缓冲区，因此需要 PATH 中有 ffmpeg，但不需要满足任何层级条件。record start / stop / status 子命令属于运行时层级，并且在 Linux 上若未指定 --runtime-addr，也会拒绝运行。

每条错误消息都准确指出一个连接环节，因此不要盲目重试。

消息	故障原因	修复方法
XR Simulator is not running…	前端端口上没有程序监听	启动应用，或传入 --port
XR Simulator is running but no app is connected…	前端已启动，但没有 OpenXR 应用连接	启动待测应用
Runtime at <addr> is no longer responding…	已连接的应用已退出	重启应用；过时的端点会自动清除
Meta XR Simulator is not installed in a registered system or MQDH location	未找到前端二进制文件	安装问题——请参阅 hz-xr-simulator-install-and-configure
native recording subcommands require --runtime-addr on Linux	在 Linux 上运行 record start/stop/status	传入 --runtime-addr，或使用不带子命令的 record --output … --duration …
ffmpeg is required to record XR Simulator MP4s	Linux 的 record 路径中没有 ffmpeg	安装 ffmpeg

在询问运行时层级的问题前，先用前端层级的命令检查是否在线。 如果连接被拒绝，会立即返回 XR Simulator is not running；而 --timeout 是整个连接过程的总时限，不会在每次重试时重新计时。runtime list 还能区分可访问但没有应用连接的前端和缺失的前端，而 runtime status 则要求已连接运行时。

因此，按层级顺序诊断——先检查成本最低的项，并在首次失败时停止：

metavr xrsim runtime logs                             # local: paths resolve with nothing running
metavr xrsim runtime list --format json --timeout 2   # frontend reachable? how many runtimes?
metavr xrsim runtime status --format json             # only once a runtime is attached

runtime logs 之所以排在第一位，正是因为当其他一切都已停止时，它仍然可以响应：如果 runtime list 失败，日志路径会告诉你前端为何无法启动，而上方的 XR Simulator is not running 条目无法提供这些信息。

runtime list 返回 [] 表示前端已启动但没有应用连接——这与前端已停止是不同的故障，需要不同的修复方法。如果返回多个条目，则还有另一个容易踩坑的地方：运行时层级的命令组会使用前端的当前端点，因此应通过 --runtime-addr 指定一个，而不要猜测哪个端点有响应。

安全关闭前端

将常规关闭操作限定在前端的端口。默认情况下会发送关闭请求，以便正在运行的 OpenXR 会话能够正常结束；只有在此范围内的关闭失败后，才使用 --force。切勿将 --all 用作常规清理操作，因为它会停止主机上的所有 MetaXRSimulator。

metavr xrsim --port 33794 app quit
metavr xrsim --port 33794 app quit --force  # only after graceful close fails
metavr xrsim app quit --all                 # only when every instance must stop

退出报告会列出限定范围内的 pid，以及操作是否为 forced，同时还会列出 was_running、killed 和 confirmed_stopped。对于 --all，表格会在 PID 列中显示 all；JSON 负载会省略内部范围标记。

两个容易踩坑的地方

1. 设置器报告的是运行时持有的值，而不仅仅是请求的值。 device set、device ipd 和 device refresh-rate 会将设置读回 OBSERVED 列。未使用 --wait 时，只会立即读取一次，可能仍显示旧值；使用 --wait 时，命令会等待值收敛，否则超时退出。将 unknown 视为读取回来的值无效，绝不能将其视为请求值已生效的确认。
2. runtime status 默认可容错。 某个分区失败后，它仍可能以 0 退出，因此要检查 device_error / input_error / fps_error。在自动化中，传入 --strict：此时任何查询失败都会导致非零退出，但仍会打印报告以便诊断。

XR Operator 端口一致性

当 Meta XR Operator 通过非默认端口控制应用时，请将 AGENTICXR_MCP_PORT 设置为相同的值，用于应用内层以及运行 metavr 的进程。代理会从 metavr 接收生成的后端 URL；环境配置不一致时，代理会指向不同的端口。更改变量后，请重启受影响的应用和 MCP 服务。

其他所有内容——精确的标志、输出格式、两种录制引擎——均以 metavr xrsim readme 和 metavr xrsim --help 为准，且始终保持最新。请查询二进制文件，而不要猜测。

参考资料

• references/commands.md — 各组的层级、表面接口中不规则的部分，以及输出含义
• GitHub：https://github.com/meta-quest/agentic-tools/tree/main/skills/hz-xr-simulator-control
• hz-xr-simulator-install-and-configure — 安装模拟器并将其配置到项目中
• hz-vr-debug — 针对实体设备进行调试