hz-vr-debug

VR デバッグスキル

metavr コマンドラインインターフェースを使用して、Meta VR、MR、および Android アプリケーションをデバッグします。このスキルでは、アプリケーションログの表示、デバイスの状態のキャプチャ、クラッシュの診断、Meta VR 開発でよく発生する問題の解決方法を説明します。

このスキルを使う場面

次のような場合に、このスキルを使用します。

• 接続されている Meta VR デバイスで実行中のアプリケーションをデバッグする
• アプリケーションログ（logcat）をリアルタイムまたは過去の分について表示する
• VR/MR ビューのスクリーンショットをキャプチャする
• アプリケーションのクラッシュ、レンダリングの不具合、パフォーマンスの問題を診断する
• トラッキング、コントローラー、オーディオ、権限に関する問題を調査する
• オフライン分析のために、デバイスから診断ファイルを取得する

このスキルは、Horizon OS を実行する Meta VR Glasses および Meta Quest ヘッドセット（Quest 2、Quest 3、Quest 3S、Quest Pro）に関連します。

前提条件

このスキルを使用する前に、次の準備が整っていることを確認してください。

1. metavr CLI がインストールされている -- スタンドアロンの metavr CLI バイナリを PATH にインストールするか（metavr-cli スキルを参照）、インストールせずに npx 経由で必要に応じて実行します。

   metavr --version
   

   metavr は ADB をラップし、Meta VR 固有のデバイス管理、ログ表示、スクリーンショットのキャプチャ、ファイル管理機能を追加します。以下の例では、metavr コマンドをそのまま使用しています。metavr が PATH にない場合は、同じ CLI を npx -y metavr <args> 経由で実行してください（npm パッケージ metavr として公開されています）。
2. Meta VR デバイスが USB 経由で接続されている -- 充電専用ではなく、データ転送に対応した USB-C ケーブルを使用します。
3. 開発者モードが有効になっている -- スマートフォンの Meta Horizon アプリで、ヘッドセットの設定から開発者モードをオンにする必要があります。
4. ADB の認証が承認されている -- 初めて接続するときは、ヘッドセットを装着し、「USBデバッグを許可」のプロンプトを承認する必要があります。

クイックスタートのワークフロー

Meta VR アプリケーションのデバッグを開始する最も速い方法は次のとおりです。

# 1. Verify the device is connected and recognized
metavr device list

# 2. List applications currently installed
metavr app list

# 3. View live logs (most recent 100 lines)
metavr log

# 4. Capture a screenshot of the current VR view
metavr capture screenshot

metavr device list でデバイスが見つからない場合は、USB ケーブル、開発者モード、ADB の認証を確認してください。

主なデバッグコマンド

デバイスコマンド

コマンド	説明
metavr device list	接続されているすべての Meta VR デバイスを一覧表示します
metavr device info <id>	デバイスのモデル、OS バージョンなどを表示します
metavr device battery	バッテリー残量と充電状態を表示します
metavr device wake	スリープ状態のデバイスを起動します
metavr device reboot	デバイスを再起動します
metavr device connect <ip>	WiFi 経由でデバイスに接続します

ログコマンド

コマンド	説明
metavr log	直近のログを 100 行表示します
metavr log -n 500	直近のログを 500 行表示します
metavr log --tag Unity	タグでログをフィルタリングします
metavr log --level E	重要度（V、D、I、W、E、F）でフィルタリングします
metavr adb logcat	高度なフィルタリングオプションを使用して logcat 全体を表示します
metavr adb logcat --follow	ログを継続的にストリーミングします

アプリケーションコマンド

コマンド	説明
metavr app list	インストール済みアプリケーションを一覧表示します
metavr app info <package>	アプリケーションの詳細情報を表示します
metavr app launch <package>	パッケージ名を指定してアプリケーションを起動します
metavr app stop <package>	実行中のアプリケーションを強制停止します
metavr app clear <package>	アプリケーションのデータとキャッシュを消去します
metavr app install <apk>	APK をデバイスにインストールします
metavr app uninstall <package>	アプリケーションをアンインストールします

キャプチャコマンド

コマンド	説明
metavr capture screenshot	現在の VR/MR ビューのスクリーンショットを撮影します
metavr capture screenshot -o file.png	スクリーンショットを指定したファイルに保存します

ファイルコマンド

コマンド	説明
metavr files ls /sdcard/	デバイス上のファイルを一覧表示します
metavr files pull /sdcard/path/file ./local/	デバイスからファイルを取得します
metavr files push ./local/file /sdcard/path/	デバイスにファイルを送信します
metavr files rm /sdcard/path/file	デバイス上のファイルを削除します
metavr files mkdir /sdcard/path/dir	デバイス上にディレクトリを作成します

一般的なデバッグワークフロー

一般的なデバッグセッションは、次の手順で進めます。

1. 接続して確認する

metavr device list
metavr device info <device_id>

デバイスが認識されていることを確認し、OS のバージョンをチェックして、バッテリー残量を記録します。バッテリー残量が少ないと、パフォーマンステストに影響するサーマルスロットリングが発生することがあります。

2. アプリケーションを特定する

metavr app list

デバッグするアプリケーションのパッケージ名を確認します。パッケージ名は通常、com.company.appname の形式です。

3. 問題を再現してログを取得する

# Start logging before reproducing the issue
metavr adb logcat --follow

ヘッドセットを装着して問題を再現します。ログはリアルタイムでターミナルに出力されます。停止するには Ctrl+C を押します。

4. 視覚的な状態をキャプチャする

# Take a screenshot at the moment of the issue
metavr capture screenshot

5. 分析して診断する

取得したログを確認し、エラー、警告、クラッシュのシグネチャを探します。次の項目を確認してください。

• FATAL EXCEPTION -- 処理されていない Java/Kotlin 例外
• native crash または SIGABRT / SIGSEGV -- ネイティブコードのクラッシュ
• ANR -- アプリケーションが応答していません（UI スレッドがフリーズ）
• OOM または OutOfMemoryError -- メモリ不足

6. 繰り返す

コードを変更して再ビルド、デプロイし、もう一度テストします。

metavr app stop com.example.myapp
metavr app launch com.example.myapp
metavr log --tag Unity --level W

症状から診断するための決定木

開発者から問題の報告があった場合は、これらの決定木を使って根本原因を体系的に診断します。報告された症状から開始し、分岐をたどってください。

Android のクラッシュ、ANR、メモリ、logcat に関する一般的な分岐は、すべてのビルドパスに適用されます。VrApi、OpenXR セッション、イマーシブフレームレート、トラッキング、コントローラー、空間オーディオに関する分岐は、イマーシブ VR アプリまたは MR アプリでのみ使用してください。Standard Android パネルアプリでは、Android アプリケーション、レンダリング、レイアウト、入力に関する分岐を使用してください。

アプリケーションの起動時にクラッシュする

App crashes on launch
├── Does `metavr app launch <pkg>` show "Error: Activity not found"?
│   └── YES → Package name is wrong or app is not installed.
│       Run `metavr app list` to verify the correct package name.
├── Does logcat show `FATAL EXCEPTION` in the first 5 seconds?
│   ├── YES, with `ClassNotFoundException` or `NoClassDefFoundError`
│   │   └── Missing native library or wrong ABI. Check the APK is built for ARM64.
│   │       Run: `metavr adb shell getprop ro.product.cpu.abi` → must show "arm64-v8a"
│   ├── YES, with `SecurityException` or `Permission denied`
│   │   └── Missing manifest permission. Check the logcat message for which permission.
│   │       Common: hand tracking, scene, camera permissions not declared.
│   └── YES, with `NullPointerException` or other Java exception
│       └── Application code bug. Read the stack trace for the failing class and method.
├── Does logcat show `native crash` / `SIGSEGV` / `SIGABRT`?
│   ├── Check if the crash is in a Unity/Unreal library (libunity.so, libUE4.so)
│   │   └── Engine bug or incompatible SDK version. Check Meta XR SDK release notes
│   │       for known issues with your engine version.
│   └── Check if the crash is in your own native code
│       └── Debug with `metavr adb logcat --buffer crash` for the tombstone, then use
│           `addr2line` or `ndk-stack` on the crash address.
└── No crash visible in logs?
    └── Check if the app is being killed by the system.
        Run: `metavr adb logcat --tag ActivityManager --level W`
        Look for "Force stopping" or "Process died" messages. Common cause: OOM killer
        triggered by excessive memory usage on launch.

アプリケーションがフリーズする／ANR（アプリケーションが応答していません）

App freezes or ANR dialog appears
├── Does logcat show "ANR in <package>"?
│   ├── YES, with "Reason: Input dispatching timed out"
│   │   └── The main/UI thread is blocked. Check for:
│   │       - Synchronous network calls on the main thread
│   │       - Large file I/O on the main thread
│   │       - Deadlocks between threads
│   │       Run: `metavr adb shell kill -3 <pid>` to dump thread stacks, then
│   │       `metavr files pull /data/anr/traces.txt ./` to retrieve the ANR trace.
│   └── YES, with "Reason: executing service"
│       └── A background service is taking too long. Check the service implementation.
└── No ANR, but app appears frozen?
    ├── Is the render loop still running? (Check VrApi logs for frame submission)
    │   ├── YES → The app is rendering but not processing input. Check input system.
    │   └── NO → The render thread is blocked or crashed silently.
    │       Check: `metavr adb logcat --tag VrApi` for "FPS" lines stopping.
    └── Is the device overheating?
        Run: `metavr device battery` — if battery temperature > 40°C, thermal
        throttling may have halted the app. Let device cool down and retry.

ヘッドセットに黒い画面が表示される

Black screen after app launch
├── Is the app actually running?
│   Run: `metavr adb shell pidof <package>` — if empty, app crashed silently.
│   └── Check crash logs: `metavr adb logcat --buffer crash`
├── Is VrApi initialized?
│   Check: `metavr adb logcat --tag VrApi | grep "VrApi" | head -20`
│   ├── No VrApi output → XR session never started. Check OpenXR/OVR initialization code.
│   └── VrApi output exists → Frames are being submitted but may be empty.
│       └── Check: rendering pipeline, camera setup, shader compilation errors.
├── Unity-specific: "Shader compiler" or "Compiling shaders" in logs?
│   └── Shader warmup can cause a black screen for several seconds on first launch.
│       Use shader prewarming/variant preloading to avoid this.
└── Is the correct rendering API being used?
    Check: `metavr adb logcat --tag Unity --level E` for Vulkan/GLES errors.
    Quest requires OpenGL ES 3.0 minimum. Vulkan is preferred on Quest 3.

フレーム落ち／カクつき

App stutters or drops frames
├── Check current FPS:
│   `metavr adb logcat --tag VrApi | grep FPS`
│   ├── FPS consistently below 72 → GPU or CPU bottleneck.
│   │   ├── Check GPU: use Perfetto or OVR Metrics Tool. Look for GPU completion
│   │   │   time > 13.8ms (72Hz) or > 11.1ms (90Hz).
│   │   └── Check CPU: look for game thread or render thread exceeding frame budget.
│   └── FPS mostly stable but periodic drops
│       ├── Check for GC pauses: `metavr adb logcat --tag dalvikvm --level D`
│       │   or `metavr adb logcat --regex "GC_|clamp"` → reduce allocations per frame.
│       ├── Check for thermal throttling: `metavr adb logcat --tag ThermalService --level W`
│       │   → sustained heavy load causes CPU/GPU frequency reduction.
│       └── Check for asset loading on main thread: large textures or models loaded
│           synchronously will cause frame spikes. Use async loading.
└── Only stutters in specific scenes?
    └── Profile that scene. Common causes: too many draw calls (>100), unculled
        off-screen geometry, expensive shaders, excessive overdraw, uncompressed textures.

トラッキングの問題

Controllers or hands not tracking correctly
├── Are controllers paired and connected?
│   `metavr device info <id>` — check controller connection status.
├── Is hand tracking enabled in device settings?
│   Check: Settings > Movement Tracking > Hand and Body Tracking.
├── Does the app request the correct tracking mode?
│   ├── For hand tracking: manifest must include
│   │   `com.oculus.permission.HAND_TRACKING` and
│   │   `com.oculus.handtracking.frequency` set to "HIGH" if needed.
│   └── For controller tracking: ensure the app is not forcing hand-tracking-only mode.
└── Tracking works but is jittery or delayed?
    ├── Check lighting: tracking cameras need adequate, even lighting. Very bright
    │   or very dim environments degrade tracking quality.
    └── Check for occlusion: hands or controllers held outside the tracking camera
        FOV will lose tracking. The camera FOV is approximately 110 degrees.

オーディオの問題

No audio or wrong audio output
├── Is audio playing through the headset speakers?
│   └── Check: Settings > Sound — ensure headset speakers are selected, not Bluetooth.
├── Does the app use spatial audio?
│   ├── Check for FMOD/Wwise initialization errors in logcat.
│   └── Check that audio sources have correct 3D settings and are not muted.
├── Audio is distorted or crackling?
│   └── Audio buffer underruns. Check for CPU overload causing audio thread starvation.
│       Reduce audio complexity or increase buffer size.
└── Audio plays from wrong position?
    └── Check spatial audio source positions match visual object positions.
        Common issue: audio listener not attached to the camera/head transform.

注意点

Meta VR 開発特有の、よくあるデバッグ上の落とし穴です。

• Logcat バッファーのオーバーフロー -- Meta VR デバイスでは、OS やほかのアプリが継続的に出力を生成するため、logcat のリングバッファーがすぐにいっぱいになります。問題を再現する前にログ記録を開始しないと、クラッシュログがすでに消去されている場合があります。再現する前に metavr adb logcat --follow を開始してください。
• USB ケーブルの品質が重要です -- 多くの USB-C ケーブルは充電専用で、データを転送できません。metavr device list に何も表示されない場合は、ソフトウェアのトラブルシューティングを行う前に別のケーブルを試してください。Quest に付属のケーブルはデータ転送に対応しています。
• WiFi デバッグの切断 -- WiFi ADB 接続（metavr device connect <ip>）は、デバイスがスリープすると切断されます。デバイスを起動した後、再接続する必要があります。継続的なデバッグセッションには USB の方が信頼性が高いです。
• リリースビルドではログが除去されます -- アプリで android:debuggable="false"（リリースビルド）を使用すると、一部のログ出力が抑制されます。問題を調査するときは、デバッグビルドを使用してください。デバッグ可能なビルドをストアに公開しないでください。
• 同じコンポーネントに複数の logcat タグがあります -- Unity では、スクリプティングバックエンドに応じて Unity、il2cpp、mono のタグが使われます。Unreal では UE、LogVR、LogOnline が使われます。まず広くフィルターし、その後対象を絞り込んでください。
• OVR Metrics Tool のオーバーレイとの競合 -- OVR Metrics Tool のオーバーレイは、アプリのレンダリングや入力を妨げることがあります。アプリの動作がおかしい場合は、バグを報告する前にメトリクスオーバーレイを無効にして再テストしてください。

ヒントとベストプラクティス

ログを効果的にフィルタリングする

重大度フィルターを使用して、不要な情報を除外します。

# Show only errors
metavr log --level E

# Show warnings and above
metavr log --level W

タグでフィルターして、特定のサブシステムに絞り込みます。

metavr adb logcat --tag VrApi
metavr adb logcat --tag Unity

metavr adb logcat で高度なフィルターを使用します。

# Complex filter expressions
metavr adb logcat --filter "Unity:W ActivityManager:I"

# Regex pattern matching
metavr adb logcat --regex "error|exception"

# Specific log buffer
metavr adb logcat --buffer crash

ログのフィルタリング手法について詳しくは、logcat-filtering.md を参照してください。

クラッシュシグネチャを検索する

クラッシュを調査するときは、ログ出力から既知のパターンを検索します。

metavr log | grep -i "fatal\|crash\|exception\|anr"

クラッシュに関連する一般的なタグには、AndroidRuntime、DEBUG、libc があります。

権限を確認する

Horizon OS の多くの機能では、特定のマニフェスト権限が必要です。機能が何も通知せずに失敗する場合は、アプリケーションマニフェストに必要な権限が含まれていることを確認してください。一般的な権限は次のとおりです。

• com.oculus.permission.HAND_TRACKING -- ハンドトラッキングへのアクセス
• com.oculus.permission.USE_SCENE -- Scene API の空間データへのアクセス
• android.permission.RECORD_AUDIO -- マイクへのアクセス
• android.permission.CAMERA -- カメラへのアクセス（複合現実向け）

パフォーマンスのデバッグ

アプリケーションがカクついたり、フレームが落ちたりする場合は、次を確認してください。

# Check device battery and thermal state
metavr device battery

# Watch for thermal throttling messages in logs
metavr adb logcat --tag ThermalService --level W

# Check VrApi frame timing
metavr adb logcat --tag VrApi | grep FPS

既知の問題とその解決策の一覧については、common-issues.md を参照してください。

参考資料

スキルの参考資料

• Logcat フィルタリングガイド -- デバイスログのフィルタリングと解釈に関する詳細ガイド
• スクリーンショットと動画のキャプチャ -- デバイスの表示状態をキャプチャする方法
• 一般的な問題と診断 -- Meta VR 開発でよくある問題と解決策の一覧