hz-unity-meta-interaction-sdk

Meta XR Interaction SDK (com.meta.xr.sdk.interaction.ovr)

Meta VR でのインタラクションには ISDK を使用する

Core SDK（com.meta.xr.sdk.core）では、ヘッドセット、つまりカメラリグ、トラッキング、OVRManager が提供されます。 インタラクションは提供されません。インタラクション層は ISDK です。 OVRInput、レイキャスト、トリガーコライダーを使って独自にグラブを実装しないでください。ISDK には、ホバー／選択状態、ポーズへの適合、投げる速度、インタラクターの調停がすでにモデル化されており、独自実装ではプラットフォームの動作とのずれが生じます。

対象	対応方法
Meta VR／Horizon OS、またはプラットフォームの指定がない場合	OVR バックエンド（com.meta.xr.sdk.interaction.ovr）—このスキルの残りの部分を参照してください
クロスプラットフォームで、引き続き ISDK を使用する場合	UnityXR バックエンド（Essentials + Unity XR Hands）。モデルは同じですが、エントリーポイントが異なります。調べて使用し、OVR のものをそのまま使えると思い込まないでください
クロスプラットフォームで、ISDK を使用しない場合	中止してください。このスキルは適用されません。

クロスプラットフォームでの使用を推測しないでください。デフォルトでは OVR を使用し、ユーザーから指定があった場合にのみ切り替え、使用したバックエンドを明記してください。

インタラクションの設定には、手動ではなく Quick Actions API を使用してください。 OVRQuickActionsAPI はリグを構築し、QuickActionsAPI はオブジェクトをインタラクティブにして、インタラクターを設定します。Quick Action では必要な設定を表現できない場合に限り、プレハブを手動で組み立て、その理由を説明してください。

Meta の公式ガイダンスでも、Quick Actions はリグを追加する「最も迅速で推奨される方法」です （ドキュメント）。

クイックスタート

using Oculus.Interaction.Editor.QuickActions;         // QuickActionsAPI
using Oculus.Interaction.OVR.Editor.QuickActions;     // OVRQuickActionsAPI

// Delete the default Main Camera first - ISDK brings its own camera rig.

// 1. Rig: comprehensive interaction rig (hands + controllers + every interactor + visuals),
//    plus an OVRCameraRig if the scene has none.
OVRQuickActionsAPI.AddOVRInteractionRig();

// 2. Interactable: adds Rigidbody + Grabbable + a HandGrab/Grab interactable child.
var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
cube.transform.localScale = Vector3.one * 0.1f;
cube.transform.position = new Vector3(0f, 1.0f, 0.4f);   // in reach at a FloorLevel origin
QuickActionsAPI.AddGrabInteraction(cube);

すべてのメソッドが返すのは、渡したターゲットではなく、作成したルート GameObject です。これを使って、設定や名前変更の対象を特定してください。

インタラクションごとの呼び出し方法

機能	呼び出し
インタラクションリグ（+ カメラリグ）	OVRQuickActionsAPI.AddOVRInteractionRig()
ハンドグラブ（近距離）	QuickActionsAPI.AddGrabInteraction(go)
ディスタンスグラブ	QuickActionsAPI.AddDistanceGrabInteraction(go, mode)
レイグラブ	QuickActionsAPI.AddRayGrabInteraction(go)
ゲイズグラブ（アイトラッキング）	QuickActionsAPI.AddGazeInteraction(go)
テレポートサーフェス	QuickActionsAPI.AddTeleportInteraction(go, surfaceType)
Canvas へのポーク／レイ／ゲイズ	QuickActionsAPI.AddPokeCanvasInteraction(go) · AddRayCanvasInteraction · AddGazeCanvasInteraction
ハンド／コントローラー上のインタラクター	QuickActionsAPI.AddHandInteractors(go, types) · AddControllerInteractors · AddControllerHandInteractors
タッチハンドグラブ、プレーンポーク、プレーンレイ	API なし—メニュー項目のみ

これらはすべて GameObject target を受け取ります。コンポーネントは渡さないでください。Canvas の呼び出しに Canvas を渡すと、コンパイルエラー（cannot convert from 'UnityEngine.Canvas' to 'UnityEngine.GameObject'）になります。canvas.gameObject または GameObject.Find の結果を渡してください。同様に、インタラクターの呼び出しには、コンポーネントではなく Hand／Controller を持つ GameObject を渡します。

シグネチャ、パラメーター、各呼び出しで構築される内容については、以下を参照してください。 quick-actions-api.md · ovr-quick-actions-api.md。 機能ごとの Meta ドキュメント：documentation.md。

インタラクターの呼び出しは手作業で構築したリグ専用です。AddOVRInteractionRig() にはすべてのインタラクターが含まれるため、呼び出し後に追加しても重複になります。

リグがシーンにない場合

インタラクションには、読み込み済みのシーンセットに、実行時に対応するインタラクターが必要です。オーサリング時にリグが存在している必要はありません。

クイックアクション	シーン内にリグが必要ですか？
インタラクタブル（つかむ、距離つかみ、レイつかみ、視線、キャンバス、テレポート）	いいえ - 必要な要素はすべてターゲット自体にあります
インタラクター（AddHandInteractors など）	はい - target に Hand / Controller が必要です
AddOVRInteractionRig()	リグを作成します

したがって、リグを実行時にインスタンス化する、DontDestroyOnLoad を使ってブートストラップシーンに配置する、加算シーンから読み込む、またはプレハブをオーサリングする場合も、すべて問題ありません。

その結果。 インタラクタブルのクイックアクションは、対応するインタラクターも、リグが見つかった場合に追加します。リグがない場合は何も通知せずにスキップされます。何も壊れませんが、インタラクターも追加されていないため、最終的に読み込まれるリグには、インタラクタブルが必要とする種類のインタラクターがあらかじめ備わっている必要があります。実行時のリグに DistanceHandGrabInteractor がない DistanceHandGrabInteractable は機能せず、ログも出力されません。リグがない状態でオーサリングする場合は、実行時のリグで必要となるインタラクターの種類を明記してください。

インタラクションをプレハブにベイクする

検証済みの手順：シーンインスタンスでインタラクタブルの呼び出しを実行してから保存します。配線は自己完結しており、インタラクタブルの _pointableElement はプレハブ内の Grabbable を参照し、シーン参照が漏れることはありません。

var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
QuickActionsAPI.AddGrabInteraction(go);                       // no rig needed
PrefabUtility.SaveAsPrefabAsset(go, "Assets/Grabbable.prefab", out bool ok);
Object.DestroyImmediate(go);

• プレハブアセットの検証に interactable.PointableElement を使わないでください - これは Awake() で割り当てられますが、アセットでは Awake() が実行されないため、プレハブが正しくても常に null になります。シリアライズされたフィールドを読み取ってください： new SerializedObject(interactable).FindProperty("_pointableElement").objectReferenceValue。
• キャンバスの呼び出し： PointableCanvasModule がプレハブまたは未読み込みの加算シーンにある場合は、fixPointableCanvasModule: false を渡してください。そうしないと、開いているシーンに2つ目のモジュールが作成されます。

呼び出しの実行 - どちらの API も Editor 専用です

これらは Editor アセンブリにあり、MonoBehaviour やビルド内の要素から実行することはできません。

1. unity-cli 経由のライブ Editor（すでに開いている場合に推奨 - シーン YAML を編集せず、Editor を操作します）：

unity status --format json          # look for state "ready"
unity command run_script --project-path <proj> --file /abs/path/DoTheThing.cs --entry MyClass.Run --format json

eval ではなく、.cs ファイルを指定して run_script を使ってください。シェルの引用符処理によって C# の文字リテラル（' '）が壊れる場合がありますが、ファイルなら再実行でき、Assets/ の外にも配置でき、--timeout_ms によって非同期エントリポイントの完了を待機できます。

2. プロジェクトの Editor スクリプト：Assets/Editor/ 以下（または Oculus.Interaction.Editor と Oculus.Interaction.OVR.Editor を参照する Editor 専用 asmdef）に配置し、[MenuItem] として公開します。人がセットアップを再実行できるようにする場合に使用します。

3. MCP：Unity MCP サーバーに接続している場合に使用します。そのハーネスの制約（System.Reflection; の using は不可、BindingFlags のオーバーロードは不可、パッケージの Editor アセンブリは参照されない）はここでのみ適用され、unity-cli の Roslyn run_script には適用されません。詳細は unity-mcp-fallback.md を参照してください。

最後にシーンを保存します（EditorSceneManager.MarkSceneDirty + SaveScene）。その後、検証してください。

インストール

com.meta.xr.sdk.interaction.ovr をインストールしてください - Essentials と Core SDK もインストールされます。まず Packages/manifest.json を確認してください。すでに記載されている場合は、再追加しないでください。com.meta.xr.sdk.interaction だけをインストールするのは、よくある誤ったインストール方法です。インタラクションモデルは含まれますが、OVR バインディング、リグ、OVRQuickActionsAPI は含まれません。

using UnityEditor.PackageManager;
var request = Client.Add("com.meta.xr.sdk.interaction.ovr");   // async - poll request.IsCompleted

または、ライブ Editor に対して次を実行します：unity command package_add --identifier com.meta.xr.sdk.interaction.ovr --confirm true --wait true。

追加が成功すると、再コンパイルとドメインのリロードが必ず発生します - パッケージをインストールしたスクリプト内で、そのパッケージの API を使わないでください。詳細は installation.md を参照してください。

真実を見極める：まずソース、次にドキュメント

ISDK に関する質問には、記憶を頼りに回答しないでください。 動作についてはインストール済みのパッケージが、意図や設計指針については Meta のドキュメントが信頼できる情報源です。

API のソースはファイル名のパターンで検索してください。インストール方法（レジストリキャッシュ、埋め込み、ローカル）を問わず機能します。

**/com.meta.xr.sdk.interaction*/Editor/QuickActions/Scripts/QuickActionsAPI.cs
**/com.meta.xr.sdk.interaction.ovr*/Editor/QuickActions/Scripts/OVRQuickActionsAPI.cs

以降の検索では、解決したパッケージルートを使用してください。

Unity 内では、AssetDatabase のパスはインストール方法を問わず機能します。 Packages/com.meta.xr.sdk.interaction.ovr/Runtime/Prefabs/...。

ドキュメントを調べるには、metavr に問い合わせます。vr_docs_search(query, scope="unity") で doc_path を取得し、次に vr_docs_get_page、シグネチャについては vr_api_search(query, engine="unity") を使います。ドキュメントの URL を手作業で組み立てないでください。名前空間は変わることがあります。厳選したマップはこちらです： documentation.md。

この 2 つの API がサポートされているエントリーポイントです。その下の仕組みは公開 API ではありません。 ウィザードを呼び出すためにリフレクションを使おうとしているなら、メソッドを見落としている可能性が高いため、まず 2 つのファイルを読み直してください。同じ操作は GameObject > Interaction SDK メニューにもブロッキングウィザードウィンドウとして用意されています。呼び出しによって何が作成されるか確認したいときは、メニューから開いてください。

ドキュメントに書かれていないこと

以下は、ソースを確認するか実行時エラーが発生して初めてわかることです。

• オプションのコンポーネントも追加されます。 呼び出しはウィザードの Fix All と Add All をクリックするのと同じです。AddDistanceGrabInteraction はさらに、未操作のオブジェクトを元の位置に戻すルートの ISDK_SnapZone (<target>) を作成します。不要なら削除してください。詳細：quick-actions-api.md。
• Grab の呼び出しでは Rigidbody がキネマティックになります（useGravity = false; isKinematic = true）。オブジェクトは配置した位置に浮かんだままになります。これは意図された動作です。
• 作成される名前はウィザードによって決まります。ISDK_HandGrabInteraction、ISDK_SnapZone (...) などです。必要に応じて後から名前を変更してください。コンポーネントは参照で追跡するため、名前を変更しても問題ありません。
• Interactor の呼び出し対象は Hand／Controller オブジェクトそのものです。 子オブジェクト上の Hand 由来のコンポーネントでは Could not execute HandInteractorWizard がログに記録されます。.Where(h => h.GetType() == typeof(Hand)) で絞り込んでください。
• 列挙型の名前と、選択されるコンポーネントの名前は一致しません。 DistanceGrabMode、シーン内の Movement Provider、Meta のドキュメント上のラベルは、それぞれ異なる用語体系です。対応関係を推測しないでください。
• ウィザードには API で設定できない項目があります。 パラメーターにない設定が必要なら、メニュー項目を使うか、結果を後処理してください。リグの Smooth Locomotion がよくある例です。
• Building Blocks も同じ結果を得る方法ですが、より優れているわけではありません。 API を優先してください。ブロック追跡コンポーネントがなく、プロジェクト設定の追加処理もなく、名前も読みやすくなります。
• API がなければ、API はありません。 必要なメソッドがない場合は、メニュー項目を使うか、コンポーネントから構築してください。リフレクションでウィザードを呼び出さないでください。

必ず Play モードで検証する

ISDK は Start() で接続状態をアサートするため、Inspector では正しく見えるシーンでも例外が発生することがあります。編集時のコンポーネントチェックだけでは不十分です。

1. コンソールをクリアし、Play モードに入り、コンソールを確認してから終了します。
2. エラーが ゼロ、例外もゼロであることが基準です。各 AssertionException には該当するコンポーネントとフィールドが明記されるため、実際の不具合として扱ってください。
3. [MetaXRFeature]: ErrorFormFactorUnavailable xrGetSystem は、ヘッドセット／XRSIM が接続されていないことを意味するだけです。OpenXR のティアダウン警告は無害です。
4. エラーが表面化しない場合もあります。verification.md を参照してください。
5. Play モードで問題がないことを確認したら、実際のヘッドセットでも確認します。APK をビルドし、metavr app install <apk> を実行してから、各インタラクションを試しながら metavr adb logcat --follow --tag Unity をストリーミングします。

参考資料

• quick-actions-api.md - 各呼び出しのシグネチャ、列挙型、構築される内容
• ovr-quick-actions-api.md - リグの呼び出しと作成されるリグ
• interaction-model.md - インタラクター／インタラクタブルのモデル、リグの構造、配置
• installation.md - インストール先、依存関係の連鎖、アセンブリ
• verification.md - Play モードでの確認手順、アサーション表、サイレント失敗
• documentation.md - 厳選した Meta ドキュメントの一覧と検索手順
• unity-mcp-fallback.md - unity-cli の代わりに Unity MCP 経由で呼び出しを実行する方法

関連スキル

• hz-unity-meta-core-sdk - カメラリグ、OVRManager、トラッキング原点、ハンドトラッキングのサポート、 Project Setup Tool、AndroidManifest
• unity-cli - 実行中の Editor を操作
• hz-xr-simulator-install-and-configure / hz-vr-debug - Play モードの先の実行とデバッグ