hz-xr-simulator-control

XR Simulator Control

metavr は圧倒的に 実機の Quest または Glasses 向け CLI です。device、app、capture、input、log、 files、ui はすべて ADB 経由でヘッドセットと通信します。xrsim はその中の 1 つのグループで、代わりに シミュレーションされたヘッドセットを操作します。グループの選択を間違えることが、ここで最もよくある失敗です。しかも気づきにくく、 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 …（ハードウェアへの keyevents）
シミュレーターの合成ルーム	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 列は間違えて選びがちなツールとして読んでください。最後の 2 行は、 このスキルの担当範囲だからではなく、よくある間違いを示すためにこの表に含めています。

両方のグループにもっともらしいコマンドが存在するため、特に注意すべき点が 3 つあります。

• **「OpenXR セッションを記録する」**は、この CLI で最も混同しやすい意図です。xrsim record は シミュレーターのコンポジター出力を MP4 に記録します。一方、tapedeck は実機でアプリの OpenXR 呼び出しストリームを 記録して再生します。これらは代替手段ではありません。
• **「シミュレーター」**は、このバイナリ内では曖昧な呼び方です。ssim は SpatialSim エミュレーター、xrsim は Meta XR Simulator です。
• device、app、input はトップレベルと xrsim の両方に存在するため、同じ動詞でもグループによって意味が異なります。 capture は異なります。xrsim capture は存在せず、シミュレーターで相当するコマンドは xrsim record です。

3 つの接続階層

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 グループは各コマンドを実行する前に接続を確立するためです。

もっともな推測とは逆の結果になるものが 2 つあります。

• app グループは停止したフロントエンドを修復するためのものであり、フロントエンドによって実行を妨げられるものではありません。 app launch と app ensure-running は、アプリが存在しない場合に起動します。app quit は --port 上のフロントエンドに終了を要求します。--force を指定すると、代わりに同じプロセスを終了します。また、--all はホスト上のすべての MetaXRSimulator を停止するための明示的な手段です。ライフサイクルコマンドをフロントエンド階層のルールに当てはめると、復旧できなくなります。
• 引数なしの record は Linux ではローカルコマンドです。 --runtime-addr を指定しない場合、接続は行いません。ffmpeg を通じてフレームバッファーをキャプチャするため、PATH 上に ffmpeg が必要ですが、どちらの階層も必要ありません。record start ／stop／status サブコマンドはランタイム階層に属し、Linux では --runtime-addr を指定しないと実行できません。

各エラーが示すのは、ちょうど 1 つの接続段階です。やみくもに再試行しないでください。

メッセージ	問題の内容	対処方法
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 で 1 つに指定してください。

安全なフロントエンドの終了

終了処理はフロントエンドのポートに限定してください。デフォルトでは終了リクエストを送信し、実行中の OpenXR セッションを正常に終了できるようにします。--force は、この対象を限定した終了処理に失敗した場合にのみ使用してください。ホスト上のすべての MetaXRSimulator を停止するため、通常のクリーンアップに --all は使用しないでください。

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 ペイロードでは内部のスコープマーカーは省略されます。

注意すべき 2 つの点

1. セッターが報告するのは、要求された値だけではなく、ランタイムが保持している値です。 device set、device ipd、device refresh-rate は、設定値を読み戻して OBSERVED 列に表示します。--wait を指定しない場合、読み戻しは即時に 1 回だけ行われるため、古い値が表示されることがあります。--wait を指定すると、コマンドは値が収束するまで待機するか、タイムアウトして終了します。unknown は読み戻しの失敗を意味し、要求した値が適用されたことの確認ではありません。
2. runtime status はデフォルトで障害に耐える動作をします。 セクションの取得に失敗しても終了コード 0 で終了することがあるため、device_error / input_error / fps_error を確認してください。自動化では --strict を指定してください。クエリが失敗すると、診断用にレポートを出力したうえで、ゼロ以外の終了コードを返します。

XR Operator のポート整合性

Meta XR Operator がデフォルト以外のポートを使ってアプリを制御する場合は、アプリ内レイヤーと metavr を実行するプロセスの両方で、AGENTICXR_MCP_PORT を同じ値に設定してください。プロキシは metavr から結果のバックエンド URL を受け取ります。環境設定が一致していないと、レイヤーとは異なるポートをプロキシが参照します。この変数を変更した後は、該当するアプリと MCP サーバーを再起動してください。

その他の詳細、つまり正確なフラグ、出力形式、2 つの記録エンジンについては、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 — 実機でのデバッグ