開発

Immersive Debugger

更新日時: 2025/12/16

概要

Unity用Immersive Debuggerは、ヘッドセットからアプリケーションのゲームプレイに対してモニタリング、視覚化、トラブルシューティング、イテレーションができるツールです。以下が含まれます。
  • ヘッドセット内でのデバッグのためのUIパネル
    パネルには、コントロールパーコンソールパネル、アプリ特有のデバッグオプションが含まれるインスペクターパネルがあります。
  • ヘッドセット内のデバッグエクスペリエンスをカスタマイズできる、オプションのUnityエディターフレームワーク
    デバッガーは、スクリプト属性[DebugMember]またはインスペクターコンポーネントDebugInspectorを使用してカスタマイズできます。
Overview of Immersive Debugger in-headset UI panel
Immersive Debuggerを使えば、ヘッドセットを外すことなく以下のことを行えます。
  • コンソールログパネルからUnityのログを確認する
  • [v74 SDKから使用可能] アプリのシーン階層と選択されたゲームオブジェクトの詳細をインスペクターパネルで表示します。
  • インスペクターパネルで、指定したアプリの変数を確認する
  • インスペクターパネルで、指定したfloat/int/boolean/Enumの変数を微調整する
  • ヘッドセット内インスペクターパネルから、指定された関数に対するアクションを呼び出す
  • 指定されたアプリデータをギズモ描画機能を使用して3Dスペースに視覚化する
これらのツールにより以下のことが可能になり、開発プロセスの時間を短縮できます。
  • ヘッドセット内で空間要素やビジュアル要素のためのイテレーションを素早く実行する
  • シーンなどの機能に依存するMR (複合現実)エクスペリエンスをデバッグする
  • (特に時間限定イベントについての)状態変更をモニタリングし、コンソールログを使用して問題点を突き止める

クイックスタート

前提条件

このチュートリアルを始める前に、XR開発用にUnityを設定するセクションで概説されている手順を完了し、必要な依存関係を含むプロジェクトを作成してください。

Unityエディターでツールを有効にする

メニューバーから、[Meta] > [Tools (ツール)] > [Immersive Debugger]を選択します。
[Project Settings (プロジェクトの設定)]ウィンドウで[Immersive Debugger]タブが開きます。[Enable (有効にする)]を選択します。
Entry point of Meta XR Tools menuSettings page for Immersive Debugger

Unityエディターからデバッグオプションを追加する

: Immersive Debuggerを有効にしたときに[DebugMember]属性が追加されていると、Immersive Debuggerはトラッキング対象メンバーをコンパイル時に増分式にキャッシュに入れられます。
独自のデバッグオプションをヘッドセット内インスペクターパネルに追加することにより、Immersive Debuggerエクスペリエンスを調整できます。
次のいずれかまたは両方の方法を使用して、任意のプログラミング要素を追加できます。
  • スクリプト属性
    プロパティ、フィールド、アクション関数のいずれかに[DebugMember]属性を追加し、その属性のパラメーターを通じてカスタマイズします。
    注: IDEで自動的に処理されない場合、Meta.XR.ImmersiveDebugger.Interfaceに対するアセンブリー依存関係が必要です。
  • 任意のゲームオブジェクトにDebugInspectorコンポーネントを追加して、デバッグオプションを構成します。
DebugInspector component that's used to add debug options without code
More detailed configuration option in the DebugInspector for each member
: DebugInspectorを使って追加された一部の属性が、ヘッドセット内のパネルに正しく表示されない場合があります。これは、Unityランタイムが未使用と判断したプロパティや関数を削除するためです。これを回避するには、代わりに[DebugMember]スクリプト属性を使ってアクセスします。これによりメンバーの保存が保証されます。

ヘッドセットでImmersive Debuggerを使う

このツールはLinkと連動でき、ヘッドセット内のapkビルド内にデプロイすることもできます。テキストの表示を鮮明にするために、apkビルドではOVROverlayコンポジターレイヤーを使っています。
Development Build is not required when using v77 or later
v77以降では、Immersive Debuggerは、ヘッドセットで開発ビルドを必要としなくなりました。Immersive Debuggerを開発ビルドでのみ表示する必要がある場合は、[Immersive Debugger Settings (Immersive Debuggerの設定)] > [Advanced (詳細)] > [Integration (統合)] > [Enable Only In Debug Build (デバッグビルドでのみ有効にする)]を選択します。
(v77より前のバージョンの場合)ビルドをヘッドセットにデプロイする前に、[File (ファイル)] > [Build Profiles (ビルドプロファイル)]に移動します。Androidを選択してから、[Development Build (開発ビルド)]を有効にします。
注: ツールを実稼働用ビルドで使うには、高度なユースケースを参照してください。
Development build is by default required for enabling the tool in headset

機能の詳細

このセクションでは、Immersive Debuggerの要素に関する詳細情報を説明します。

ヘッドセット内パネル

ヘッドセット内UIには、コントロールバーコンソールパネルインスペクターパネルがあります。

コントロールバー

Immersive Debuggerが有効な場合、コントロールバーがゲームワールドに自動的に表示されます([Project Settings (プロジェクト設定)]で[Display at Startup (起動時に表示)]が有効になっている場合)。選択済みの[Toggle Display Input Button (表示入力ボタンを切り替える)]を使用した場合も表示されます。
In-headset Control Bar panel UI of Immersive Debugger
パネルの左上には、アプリを実行している時間が表示されます。
左から右の順に、アイコンの機能は以下のとおりです。
  • パネルの透明/不透明表示を切り替える
  • パネルを特定の位置に固定表示するか、ヘッドセットと共に移動させる
  • 頭のヨーによるパネルの回転を有効/無効にする
  • パネルの距離を変更する
右側のボタンで、インスペクターパネルとコンソールパネルを切り替えます。

コンソールパネル

このパネルにはUnityからのすべてのコンソールログが表示され、重大度の切り替え、ログの消去、同一ログの折りたたみと展開ができます。
In-headset Console panel UI of Immersive Debugger
ログの特定の項目をクリックすると、フルスタックトレースパネルが表示され、右上隅でオフにすることができます。
In-headset Console panel UI with log stacktrace opened of Immersive Debugger

インスペクターパネル

このパネルでは以下のことが行えます。
  • シーン階層を確認し、ゲームオブジェクトをチェックする
  • 変数の実行時の値を監視する
  • ボタンをクリックして機能を呼び出す
  • 目のアイコンを選択してギズモの表示/非表示を切り替える
  • 変数の実行時の値を微調整する
左上のアイコンで、[Custom Inspectors (カスタムインスペクター)]モードまたは[Hierarchy View (階層ビュー)]モードを選択できます。
[Hierarchy View (階層ビュー)]モードを選択すると、アプリからすべてのシーンを読み込み、その中のゲームオブジェクトをクリックしてモノビヘイビアコンポーネントとそのメンバーを調べることができます。デフォルトでは公開メンバーのみが表示されますが、ImmersiveDebuggerの設定で[Advanced (詳細)] > [Hierarchy View (階層ビュー)] > [Inspect Private Members (非公開メンバーを調べる)]をオンにすることで変更できます。
In-headset Inspector panel - Hierarchy View UI of Immersive Debugger
[Custom Inspectors (カスタムインスペクター)]モードを選択すると、左側のサイドバーにデバッグ項目のカテゴリが表示されます。そこで、DebugMember属性またはインスペクターパネル内での項目のカテゴリを指定できます。事前設定済みのMeta XRデバッグ項目の選択も、すぐに利用可能な状態になっています([Settings (設定)]でオフにすることが可能)。詳しくはMetaの事前構築デバッグ機能をご覧ください。
In-headset Inspector panel - Custom Inspectors UI of Immersive Debugger

デバッグ機能

デバッグのさまざまな機能とそのサポートステータスは、以下のとおりです。
機能サポートの状態
Watch
ToString()をサポートしているものをすべてサポートしています。ベクトルには、別個のフィールドを表示するための特別なUIがあります。さらに、Textureデータタイプがプレビューレンダリングでサポートされます。
Action
パラメーターなしの関数だけをサポートしています。
Gizmos
GizmoTypesRegistryクラスでチェックできるさまざまなDebugGizmoTypesをサポートします。Axisを除くすべてのギズモでは、[DebugMember]で追加のColorパラメーターを指定してその色を描画することができます。
Tweak
[DebugMember(Tweakable = true, Min = xxx, Max = xx)]によるスライダーUIでfloat/intの微調整をサポートします。UIトグルでブーリアンの微調整をサポートし、ドロップダウンUIで列挙の微調整もサポートします。

スクリプト属性の例

Immersive Debuggerが有効になっている場合、コンパイル時にフレームワークにより、エディターの中で注釈の付いたシンボルが自動的に収集されます。実行時に、パイプ処理によってヘッドセット内パネルにシンボルが渡されます。それらのシンボルを見つけることでパフォーマンスが下がることがないよう、デバッグメンバークラスは、Assets/Resources/ImmersiveDebuggerSettings.assetにあるScriptableオブジェクトによりプロジェクトの中にあらかじめ含められています。
using Meta.XR.ImmersiveDebugger;
public class ExampleClass : MonoBehaviour
{
 // gizmo drawing, specifying a category
 [DebugMember(GizmoType = DebugGizmoType.Axis, Category = "MyDebugCategory")]
 private Pose _gameObjectPos;

 [DebugMember(GizmoType = DebugGizmoType.Line, Color = DebugColor.Red)]
 private Tuple<Vector3,Vector3> _direction;

 // just watch, note Tweakable is by default true for all supported types
 [DebugMember(Tweakable = false)]
 private bool _gameState;

 // tweak the value within a range
 [DebugMember(Min = 0.0, Max = 1.0)]
 private float _param;

 // action / call function, static members are also supproted
 [DebugMember]
 private void SpawnObject() {/* some code here */}
 private void Update()
 {
  // Update and consume all the debug options, e.g.:
  _gameObjectPos = new Pose(transform.position, transform.rotation);
 }
}

Metaの事前構築デバッグ機能

Immersive DebuggerとMeta XR SDKを使いやすくするために、SDKのいくつかの機能に対してデバッグ機能を事前に組み込んでいます。具体的には以下のとおりです。
  • カメラリグ
  • パススルー
  • シーンデバッガー(Mixed Reality Utility Kit / MRUK)
これらの組み込みデバッグオプションは、デフォルトでMetaが提供するカテゴリで利用可能です。[Immersive Debugger Settings (Immersive Debuggerの設定)] > [Inspected Data Sets (調査済みデータセット)]でオフにできます。

高度なユースケース

このセクションでは、より具体的なユースケースを紹介します。

実稼働用ビルドでImmersive Debuggerを使う

(: この手順はv77以降では不要です)開発ビルドではなく実稼働用ビルドでツールを使うには、プロジェクト設定でIMMERSIVE_DEBUGGER_ALLOW_USE_IN_PRODをスクリプトプリプロセッサー定義として追加します。それにより、ツールを非開発ビルドでも使えるようになります。

OVRCameraRigの代わりに自分のカメラを使う

Immersive Debuggerで使うカメラをオーバーライドする、カスタム統合設定があります。スクリプトを指定するには、CustomIntegrationConfigBaseをオーバーライドし( ExampleCustomIntegrationConfigを参照)、設定セクションでmonoスクリプトのデータを設定し、[Use Custom Integration Config (カスタム統合設定を使う)]を有効にします。この設定をするには、[Project Settings (プロジェクト設定)]ページで、[Meta XR] > [Immersive Debugger] > [Advanced (詳細)] > [Integration (統合)] > [Use Custom Integration Config (カスタム統合設定を使う)]をクリックします。
Immersive Debugger Editor settings allows custom integration

実行時にインスペクターをコンポーネントに追加する

(v83以降で利用可能) RuntimeAPIsクラスは、コンポーネントのインスペクターパネルをImmersive Debuggerに追加するためのランタイムメソッドを提供します。これにより、DebugMember属性を使用せずに、ランタイムでコンポーネントをデバッグできます。これは、動的に作成されるコンポーネントをデバッグしたり、ソースにアクセスできないコンポーネントにインスペクターを追加したりするのに便利です。

Immersive Debuggerにカスタムパネルを追加する

(v83以降利用可能) IPanelRegistrarインターフェイスを実装することで、Immersive Debuggerにカスタムパネルを追加できます。このインターフェイスを使って、実行時にImmersive Debuggerに登録されるカスタムパネルを作成できます。

既知の問題

問題説明
OVRManager依存関係(OVROverlay)
Immersive Debuggerでは、OVROverlayコンポジターレイヤーを使ってテキスト表示の鮮明度を上げているので、プロジェクトでOVRManagerを使っていることが必要です。
HDR (カメラとデバイスのグラフィック設定に含まれる)がまだサポートされていない
HDRを使う場合、Immersive Debuggerのパネルの表示に不具合が発生する可能性があります。
ナビゲーションロゴ
日本語
© 2026 Meta