unity-xr

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターでスキルを呼び出そうとしている場合は、いったん停止してください。まずこのファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend/schema からパラメーター定義をすでに取得している場合は、そのまま dryRun に進めます。

トリガー

• VR/AR インタラクションの構築
• XR リグのセットアップ
• グラブ／ソケット／レイインタラクターの設定
• VR/AR インタラクションの構築、XR リグのセットアップ、グラブ／ソケット／レイインタラクターの設定

Unity XR Interaction Toolkit スキル

XR Interaction Toolkit のセットアップと設定には、このモジュールを使用してください。すべての xr_* スキルはリフレクションベースで、Unity 2022 の XRI 2.x および Unity 6 以降の XRI 3.x に対応しています。

必要要件：com.unity.xr.interaction.toolkit。 厳守事項：セッションで最初の xr_* 呼び出しを行う前に、このファイルを読んでください。ブリッジがリフレクションベースのため、プロパティ名が間違っていてもエラーにならず、処理が失敗することがあります。

ガードレール

動作モード（v1.9 の3段階）：

• Approval（デフォルト）：クエリ／一覧／情報取得スキル（xr_check_setup、xr_get_scene_report、xr_list_interactors、xr_list_interactables）は直接実行されます。作成／変更スキルは FullAuto です。MODE_RESTRICTED の場合は許可プロトコルを実行してください。/permission/grant が成功すると、スキルがサーバー側で実行され、同じ応答内で結果が返されます。
• Auto／Bypass：SemiAuto と FullAuto は直接実行されます。
• このモジュールには Delete／PlayMode／Reload／RiskLevel="high" のスキルは含まれていないため、禁止対象として自動分類されるものはありません。すべてのスキルが許可によって利用できます。
• com.unity.xr.interaction.toolkit がない場合、すべての xr_* スキルは実行されず、代わりに NoXRI() のインストール手順を返します。
• リフレクション依存：XRI コンポーネントのプロパティ名は、XRI 2.x／3.x の定義と正確に一致している必要があります。xr_configure_interactable／xr_configure_haptics で誤ったフィールド名を指定しても、無視されるだけです。xr_configure_interaction_layers はレイヤー名または整数マスクを受け取り、未定義の名前は拒否します。詳細なプロパティを編集する前に、API_REFERENCE.md を読み込んでください。

しないこと（よくある誤り）：

• XRHand、XRPlayer、XRTeleporter、GrabInteractor、VRController、XRLocomotion、XRManager は、ここで使用するランタイムクラスではありません。
• interactable.OnGrab()／OnRelease() は XRI のイベントモデルではありません。selectEntered／selectExited を使用してください。
• controller.vibrate() はここで説明されている方法ではありません。xr_configure_haptics で触覚を設定してください。
• 物理レイヤーやタグが InteractionLayerMask の代わりになると考えないでください。
• コンポーネントのプロパティ名を推測しないでください。詳細な XR コンポーネントのプロパティを設定する前に、API_REFERENCE.md を読み込んでください。

基準となる正しいクラス名：

• XRInteractionManager
• XROrigin
• XRRayInteractor
• XRDirectInteractor
• XRSocketInteractor
• XRGrabInteractable
• XRSimpleInteractable
• TeleportationProvider
• TeleportationArea
• TeleportationAnchor
• ContinuousMoveProvider
• SnapTurnProvider
• ContinuousTurnProvider
• TrackedDeviceGraphicRaycaster
• XRUIInputModule
• TrackedPoseDriver

振り分け：

• XR 以外の Canvas UI の作成には、ui を使用してください。
• XR ゲームプレイコードのアーキテクチャやライフサイクルの判断には、architecture、patterns、async、scriptdesign などの助言モジュールを読み込んでください。
• 正確なコンポーネントプロパティ名やワークフローの全例については、API_REFERENCE.md を読み込んでください。

スキル

セットアップと診断

スキル	用途	主なパラメーター
xr_check_setup	XR パッケージ、リグ、マネージャー、シーンの前提条件を検証	verbose?
xr_setup_rig	XR Origin、カメラ、コントローラーを作成	name、cameraYOffset?
xr_setup_interaction_manager	マネージャーを追加または検索	なし
xr_setup_event_system	XR UI 入力スタックを置き換え／追加	なし
xr_get_scene_report	シーン側の XR 状態をレポート	なし

インタラクターとインタラクタブル

スキル	用途	主なパラメーター
xr_add_ray_interactor	遠距離からのポインティング／レイ操作	name、maxDistance?、lineType?
xr_add_direct_interactor	近距離での手によるつかみ	name、radius?
xr_add_socket_interactor	スロットへのスナップ配置	name、showHoverMesh?、recycleDelay?
xr_add_grab_interactable	Rigidbody + コライダー + つかみ設定	name、movementType?、throwOnDetach?
xr_add_simple_interactable	つかまずにホバー／選択	name
xr_configure_interactable	インタラクタブルの動作を詳細に調整	対象 + 変更するフィールドのみ
xr_list_interactors	シーン内のすべてのインタラクターを一覧表示	なし
xr_list_interactables	シーン内のすべてのインタラクタブルを一覧表示	なし

移動と XR UI

スキル	用途	主なパラメーター
xr_setup_teleportation	XR Origin にテレポートプロバイダーを追加	なし
xr_add_teleport_area	サーフェスをテレポート可能として設定	name、matchOrientation?
xr_add_teleport_anchor	固定のテレポート先を作成	name、x/y/z、rotY?、matchOrientation?
xr_setup_continuous_move	スティックによる移動を追加	moveSpeed?、enableStrafe?、enableFly?
xr_setup_turn_provider	スナップターンまたはスムーズターンを追加	turnType、turnAmount?、turnSpeed?
xr_setup_ui_canvas	Canvas を XR 操作用に変換	name

フィードバックとフィルタリング

スキル	用途	主なパラメーター
xr_configure_haptics	ホバー／選択時の振動を設定	name、強度、持続時間
xr_add_interaction_event	インタラクションのコールバックを対象メソッドに接続	name、eventType、targetName、targetMethod
xr_configure_interaction_layers	InteractionLayerMask を設定	name、layers、isInteractor

クイックスタート

import unity_skills as u

u.call_skill("xr_check_setup")
u.call_skill("xr_setup_rig", name="XR Origin")
u.call_skill("xr_add_ray_interactor", name="Right Controller")
u.call_skill("xr_add_direct_interactor", name="Left Controller")
u.call_skill("xr_setup_teleportation")
u.call_skill("xr_setup_turn_provider", turnType="Snap", turnAmount=45)
u.call_skill("xr_add_grab_interactable", name="MyCube", movementType="VelocityTracking")

ワークフローの概要

リグのセットアップ

1. xr_check_setup を実行します。
2. xr_setup_rig でリグを作成します。
3. xr_setup_event_system で XR UI 入力が存在することを確認します。
4. 各コントローラーに少なくとも 1 つのインタラクターを追加します。

つかみのセットアップ

• 直接手でつかむ：xr_add_direct_interactor + xr_add_grab_interactable
• 距離を置いてつかむ：xr_add_ray_interactor + xr_add_grab_interactable
• ソケットに配置：xr_add_socket_interactor + つかみ可能なオブジェクト

movementType のデフォルト設定は重要です：

• VelocityTracking：汎用的な物理つかみに最適です
• Kinematic：引っかからないようにしたいハンドル／ツールに使用します
• Instantaneous：正確な遠距離つかみに最適です

移動のセットアップ

• テレポート：xr_setup_teleportation + xr_add_ray_interactor + xr_add_teleport_area／xr_add_teleport_anchor
• 連続移動：xr_setup_continuous_move
• 旋回：xr_setup_turn_provider

快適性を考慮したデフォルト設定：スナップターン + 中程度の移動速度（~2.0 m/s）。

XR UI

1. xr_setup_ui_canvas で Canvas を変換します
2. xr_setup_event_system が設定されていることを確認します
3. UI をクリックするコントローラーにレイインタラクターを追加します

Collider Configuration Matrix

これは、このリポジトリで最も重要な XR の誤った情報を防ぐための表です。

コンポーネント	Collider が必要	isTrigger	推奨 Collider	理由
XRDirectInteractor	はい	True	SphereCollider（0.1-0.25）	重なりの検出
XRRayInteractor	いいえ	-	なし	レイキャストを使用
XRSocketInteractor	はい	True	SphereCollider（0.1-0.3）	スナップゾーン
XRGrabInteractable	はい	False	BoxCollider または convex MeshCollider	物理演算 + レイの対象
XRSimpleInteractable	はい	False	BoxCollider	選択の検出
TeleportationArea	はい	False	MeshCollider または BoxCollider	サーフェスのレイキャスト対象
TeleportationAnchor	はい	False	薄い BoxCollider	ポイントのレイキャスト対象

重要なルール：

1. XRGrabInteractable には Rigidbody が必要です。
2. つかめるオブジェクトの Collider はトリガーにしてはいけません。
3. ダイレクトインタラクターの Collider は必ずトリガーにしてください。
4. 動的なメッシュ Collider は凸形状である必要があります。
5. ソケットの Collider は、トリガー専用の重なり判定領域にしてください。

バージョン互換性

トピック	XRI 2.x	XRI 3.x
主な名前空間の形式	ルート名前空間	分割されたサブ名前空間
リグの種類	XROrigin	XROrigin
ロコモーションの中核	LocomotionSystem	LocomotionMediator
コントローラーの種類	ActionBasedController	ActionBasedController
ブリッジの動作	リフレクションヘルパーが自動的にフォールバック	リフレクションヘルパーが 3.x を優先

重要な注意事項

1. 通常、シーンには XRInteractionManager をちょうど 1 つ配置してください。
2. ほとんどのロコモーションスキルは、XROrigin がすでに存在することを前提としています。
3. パッケージのインストールや再設定によって、Domain Reload が発生することがあります。XR 呼び出しを再試行する前にお待ちください。
4. インタラクターとインタラクタブルのフィルタリングには InteractionLayerMask を使用してください。
5. カスタム XR スクリプトでは、可能な場合は Update() によるポーリングよりも XRI のライフサイクルフックとイベントを優先してください。

最小限の例

import unity_skills as u

u.call_skill("xr_setup_rig", name="XR Origin", cameraYOffset=1.36)
u.call_skill("xr_setup_event_system")
u.call_skill("xr_add_ray_interactor", name="Right Controller", maxDistance=30, lineType="StraightLine")
u.call_skill("xr_add_grab_interactable", name="Tool", movementType="VelocityTracking", throwOnDetach=True)
u.call_skill("xr_configure_haptics", name="Right Controller", selectIntensity=0.7, selectDuration=0.15)

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値は、このファイルではなく、GET /skills/schema または unity_skills.get_skill_schema() で定義されています。 XR コンポーネントのプロパティを詳細に設定する前に、API_REFERENCE.md を読み込んでください。XR のプロパティ名はリフレクションの影響を受けます。