/hz-xr-simulator-control

name: hz-xr-simulator-control
license: Apache-2.0
description: Routes Meta VR and Horizon OS simulator work to the right `metavr` command group, and drives a running Meta XR Simulator via `metavr xrsim` — runtime, device, input, compositor layers and MP4 recording. Use when a goal concerns a simulated headset rather than a physical one, when choosing between `xrsim`, `ssim`, `capture` and `tapedeck`, or when a `metavr xrsim` command returns a connection error. For installing the simulator or configuring it into a Unity, Unreal or native OpenXR project, use hz-xr-simulator-install-and-configure instead.
allowed-tools: Bash(metavr:*), Bash(hzdb:*)

XR Simulator Control

`metavr` is overwhelmingly a **physical Quest or Glasses** CLI: `device`, `app`, `capture`, `input`, `log`, `files` and `ui` all talk to a headset over ADB. `xrsim` is one group among them and drives a **simulated** headset instead. Choosing the wrong group is the most common failure here, and it is quiet: `metavr device list` prints `No devices connected` and exits 0, so the wrong answer looks healthier than the right one.

This skill drives a simulator that already exists. Installing one, or wiring it into a project, belongs to `hz-xr-simulator-install-and-configure`.

Which Command Group

| The goal concerns | Use | Not | |---|---|---| | The simulated headset model, IPD, refresh rate | `metavr xrsim device …` | `metavr device …` (physical, ADB) | | The simulator frontend process | `metavr xrsim app …` | `metavr app …` (APKs on a headset) | | Simulated hands and controllers | `metavr xrsim input …` | `metavr input …` (keyevents to hardware) | | The simulator's synthetic room | `metavr xrsim env …` | — | | Compositor layers, simulated frame rate | `metavr xrsim layer` / `xrsim runtime fps` | — | | The simulator's own logs | `metavr xrsim runtime logs` | `metavr log` / `metavr adb logcat` (device logcat) | | What the simulated headset renders | `metavr xrsim record` | `metavr capture` (physical device screen) | | Recording and replaying an app's OpenXR calls on a real headset | `metavr tapedeck` | `metavr xrsim record` (compositor pixels, not a call stream) | | The SpatialSim emulator | `metavr ssim` | `metavr xrsim` (a **different** simulator) |

Read the `Use` column as the right tool for that goal and `Not` as the one you might reach for by mistake. The last two rows are in this table because they are the mistakes, not because they are this skill's job.

Three are worth stating outright, because a plausible command exists on both sides:

• **"Record an OpenXR session"** is the most confusable intent in the CLI. `xrsim record` captures

the simulator's compositor output to MP4; `tapedeck` captures and replays an app's OpenXR call stream on a physical device. They are not substitutes.

• **"The simulator"** is ambiguous inside this binary. `ssim` is the SpatialSim emulator, `xrsim`

is the Meta XR Simulator.

• **`device`, `app` and `input` exist both at the top level and under `xrsim`**, so the same verb

means different things depending on the group. `capture` does not: there is no `xrsim capture`, and the simulator equivalent is `xrsim record`.

The Three Connection Tiers

Once you are inside `xrsim`, what a command needs decides which error you get.

| Tier | Commands | Needs | |---|---|---| | Local | `readme`, `runtime logs`, and on Linux bare `record --output … --duration …` | nothing running | | Lifecycle | `app launch`/`quit`/`ensure-running` | nothing running — these *manage* the frontend | | Frontend | `runtime activate`/`deactivate`/`list`, `env set`/`list` | the frontend app | | Runtime | `runtime ping`/`status`/`info`/`fps`, `device *`, `input *`, `layer *`, `record start`/`stop`/`status` | the frontend **and** a connected XR app |

`device list` and `device refresh-rates` read like static catalogs but come from the live runtime. `input sources` prints a fixed list yet still needs a connection, because the `input` group opens one before it dispatches.

Two that a reasonable guess gets wrong in the other direction:

• **The `app` group is how you fix a down frontend, not something blocked by one.** `app launch`

and `app ensure-running` start it if it is absent. `app quit` asks the frontend on `--port` to close; `--force` terminates that same process instead, and `--all` is the explicit escape hatch for stopping every MetaXRSimulator on the host. Treating lifecycle commands as frontend-tier rules out the recovery.

• **Bare `record` is local on Linux.** Without `--runtime-addr` it never connects — it captures the

framebuffer through `ffmpeg`, so it needs `ffmpeg` on `PATH` but neither tier. The `record start` / `stop` / `status` subcommands are runtime-tier and additionally refuse to run on Linux without `--runtime-addr`.

Each error names exactly one hop, so do not retry blindly.

| Message | What broke | Fix | |---|---|---| | `XR Simulator is not running…` | nothing listening on the frontend port | start the app, or pass `--port` | | `XR Simulator is running but no app is connected…` | frontend up, no OpenXR app attached | launch the app under test | | `Runtime at <addr> is no longer responding…` | the attached app died | restart it; the stale endpoint clears itself | | `Meta XR Simulator is not installed in a registered system or MQDH location` | the frontend binary was never found | an install problem — see `hz-xr-simulator-install-and-configure` | | `native recording subcommands require --runtime-addr on Linux` | `record start`/`stop`/`status` on Linux | pass `--runtime-addr`, or use bare `record --output … --duration …` | | `ffmpeg is required to record XR Simulator MP4s` | the Linux `record` path has no `ffmpeg` | install `ffmpeg` |

**Check liveness with a frontend-tier command before asking runtime-tier questions.** A refused connection returns `XR Simulator is not running` immediately, and `--timeout` is the total connection budget rather than a fresh budget for every