godot-platform-vr

プラットフォーム：VR

90 FPS 以上、快適さを優先した設計、正確なモーションコントロールが VR 開発の要です。

禁止事項（VR のエキスパートルール）

レンダリングと快適さ

• 90 FPS を下回ってはいけません — VR では、72 FPS 以下になるとすぐに吐き気を引き起こします。少なくとも 90 FPS（Meta Quest 2/3 の標準値）を維持し、レンダリングのカクつきを最小限に抑える必要があります。
• ビネット（快適性マスク）なしでスムーズな回転を使用してはいけません — スムーズな回転は乗り物酔いを引き起こします。必ずスナップターンまたは動的ビネットを用意してください。
• フォービエイテッドレンダリングが有効な場合、3D MSAA を強制してはいけません — 一部のハードウェアでは、OpenXR パイプライン上でフォービエーションと MSAA が本質的に競合することがあります。

移動とインタラクション

• テレポート移動の選択肢を省略してはいけません — 多くの人にとって、スムーズな移動は耐えがたいものです。アクセシビリティの代替手段として、必ずテレポートを用意してください。
• VR UI にビルボードを使用してはいけません — BILLBOARD_ENABLED は立体視の奥行きの手がかりを損ないます。SubViewports を使った静的な MeshInstance3D の平面を使用してください。
• UI を近すぎる場所や遠すぎる場所に配置してはいけません — 0.5m では眼精疲労を起こし、10m では読み取れません。プレイヤーから 1～3 メートルの距離が最適です。

安全性とシステム

• 物理的なプレイエリアの境界を必ず考慮してください — 現実の物体にぶつかることは安全上のリスクです。XRServer を使ってガーディアンの境界を取得してください。
• focus_lost または session_ended シグナルを無視してはいけません — シミュレーションを一時停止して、切断やシステムメニューのオーバーレイに適切に対処してください。
• XRControllerTracker の名前をハードコードしてはいけません — ゲームプレイを特定のハードウェアラベルから切り離すために、OpenXR アクションマップシステムを使用してください。

---

快適性の判断フロー（ここから開始）

1. プレイヤーは継続的な移動を無効にできますか？ → できない場合は、スムーズな移動のコードを書く前に作業を中断し、テレポートと着席モードを追加してください。
2. 回転： デフォルトはスナップターン → vr_locomotion_handler.gd を読み込みます。スムーズターンを使う場合は、ビネットと快適性切り替え機能を必ず組み合わせてください。
3. プレイエリア／フォーカス： 移動をリリースする前に vr_safety_guardian_warner.gd と vr_headset_focus_guard.gd を読み込みます。
4. セッションの初期化／アクション／FPS： 続いて、vr_openxr_initializer.gd、vr_input_action_mapper.gd、vr_performance_config.gd を読み込みます。

利用可能なスクリプト

必須：快適性の判断フローを確認した後、該当するパターンを実装する前に対応するスクリプトを読んでください。use_xr = true や XRController3D.is_button_pressed だけのデモを作らず、以下のスクリプトを起点にしてください。

vr_openxr_initializer.gd

ドライバーのサポートと機能の検証を備えた、エキスパート向けの OpenXR 初期化です。

vr_hand_gesture_detector.gd

ハンドトラッキングに XRHandModifier3D を使用した、ピンチとグラブの認識です。

vr_locomotion_handler.gd

スナップターン、快適性ビネット、ガーディアン／フォーカス喪失時の処理を備えた、アクセシビリティ対応の teleport_to() です。

vr_passthrough_manager.gd

複合現実（AR/VR）への移行に向けた、アルファブレンディングとアンダーレイの設定です。

vr_performance_config.gd

エキスパート向けのフォービエイテッドレンダリングと可変レートシェーディング（VRS）の設定です。

vr_haptic_sequencer.gd

XRController3D のトリガーを使用した、複雑な触覚パルスのシーケンス制御です。

vr_physics_hand_controller.gd

環境の固体オブジェクトを考慮する、めり込みのない物理追従型の手です。

vr_safety_guardian_warner.gd

XRServer を使用した、ガーディアン／シェイプロン境界までの距離の警告ロジックです。

vr_headset_focus_guard.gd

フォーカス喪失時（システムメニュー／ヘッドセット未装着）の、ヘッドセットの状態を考慮した一時停止ロジックです。

vr_input_action_mapper.gd

ロジックをハードウェアのボタンから切り離す、OpenXR アクションマップの抽象化です。

テレポートによるアクセシビリティ経路

スムーズな移動の代替手段として、テレポート（またはルームスケールのみ）を必ず用意してください。

1. 必ず読んでください：vr_locomotion_handler.gd — teleport_to(target_global)。
2. レイキャストでコントローラーの照準から床／ナビメッシュを狙い、ヒット位置を teleport_to に渡してください。
3. 失敗モード（必ず対処してください）：
   • ガーディアン境界への侵入 — プレイエリアの境界外にあるターゲットを拒否し、vr_safety_guardian_warner.gd を介して警告してください。
   • フォーカス時の一時停止 — シーンツリーが一時停止中、またはヘッドセットのフォーカスが失われている間は、決してテレポートさせないでください。一時停止／ミュートは vr_headset_focus_guard.gd が管理します。
4. 同じロコモーションハンドラーのスナップターン＋ビネットをテレポートと組み合わせてください。

快適性の必須条件（妥協不可）

これらは、単なる希望ではなく、必ず満たすべき快適性の条件です。

1. オプションの VFX を追加する前に 90 FPS 以上を確保してください。見栄えよりも、吐き気のリスクを避けることが優先です。
2. テレポートまたはスナップターンの経路を常に利用可能にしてください。スムーズな移動のみでリリースしてはいけません。
3. 最初の一般公開プレイテストまでに、ガーディアンとフォーカスのハンドラーを導入してください。
4. UI はコンポジションレイヤー／静的クワッド上の 1～3 m に配置してください。近距離の HUD をビルボード表示してはいけません。

エキスパート向けパターン（スクリプトの参照先）

1. 複合現実パススルー（Quest 3） — environment_blend_mode = ALPHA_BLEND と transparent_bg により、シーンのアルファを通してカメラ映像を表示できます → mixed_reality_manager.gd / vr_passthrough_manager.gd。
2. コンポジションレイヤー UI — OpenXRCompositionLayerQuad と SubViewport でレンズのぼやけを回避できます → xr_performance_overlay.gd。
3. 汎用グラブ — OpenXR アクションマップと一元管理された再親化マネージャーを使用します → universal_grab_manager.gd + vr_input_action_mapper.gd。

詳細情報（必要に応じて）

• OpenXR のブートストラップの詳細、モーションコントロールのサンプル → xr-comfort-patterns.md

リファレンス

段階的開示：特定の API を調べる場合にのみ公式ドキュメントへのリンクを開いてください。関連するスキルを読み込むのは、隣接ドメインへルーティングする場合に限り、スキル群全体を事前に読み込まないでください。

公式ドキュメント

• XR のセットアップ — OpenXR プロジェクトの有効化、XROrigin3D／XRCamera3D のツリー、初回のヘッドセットセッションの開始。
• より優れた XR 起動スクリプト — 堅牢な initialize → use_xr の順序、フォーカスシグナル、ビューポートの XR モードを有効にする前の失敗時の処理。
• XR アクションマップ — ハードウェアに依存しないアクションにより、ゲームプレイでコントローラーボタンの文字列を直接指定せずに済みます。
• XR の基本的な移動 — テレポートと連続移動の違い、快適さを重視した旋回パターン。
• OpenXR のハンドトラッキング — XRHandModifier3D／関節のトラッキングと、コントローラーへのフォールバックに関する想定事項。
• OpenXR のコンポジションレイヤー — ビルボード化した 3D クアッドの代わりに OpenXRCompositionLayerQuad を使い、SubViewport UI を鮮明に表示します。
• AR／パススルー — 環境ブレンドモードと、複合現実向けの透過ビューポートの設定。
• OpenXR の設定 — フォビエーション、レンダーターゲット倍率、その他のヘッドセットのパフォーマンス設定。
• XR のルームスケール — XRServer を使ったプレイエリア／ガーディアンの境界設定による物理的な安全確保。
• Android への XR のデプロイ — Quest クラスの Android エクスポート、権限、OpenXR ローダーのパッケージ化。
• 可変レートシェーディング — 90 FPS 以上を実現するために OpenXR のフォビエーションと組み合わせる VRS／フォビエーションシェーディングのトレードオフ。
• XRInterface — OpenXR／WebXR で共通の、初期化、フォーカス、パススルー、ハプティクス、ブレンドモードの API。

関連スキル

前提条件

• godot-project-foundations — OpenXR と use_xr を有効にする前に必要な、プロジェクト設定、シーンツリー、ビューポートの基本。
• godot-input-handling — モーションコントローラー向けに OpenXR アクションマップが拡張する、アクション／イベントの考え方。
• godot-gdscript-mastery — 型付き XR スクリプト、スナップターンの快適性を高める await タイマー、フォーカス／ハプティクス用のシグナル接続。

補完

• godot-camera-systems — XRCamera3DもCamera3Dであり、快適なUIの距離や頭部基準のフレーミングには、カメラ配置のルールを再利用します。
• godot-performance-optimization — フォビエーションやVRSを適用した状態で90/120 Hzを維持できるかを左右する、ドローコールとGPUの予算です。
• godot-physics-3d — 静的なワールドジオメトリをすり抜けてはならない、CharacterBody3D/RigidBody3Dによるつかんで投げる動作です。
• godot-audio-systems — ヘッドセットのフォーカスが失われたときにバスをミュート／ダッキングし、システムメニュー表示中にゲーム音が鳴り続けないようにします。
• godot-shaders-basics — XRコンポジターと干渉せずに、移動中の快適性を高めるビネットや空間オーバーレイを適用します。
• godot-ui-containers — 1～3 m先にコンポジションレイヤーで投影されるSubViewport内のレイアウトです。
• godot-export-builds — QuestとPCVR向けのAndroid／デスクトップ用エクスポートプリセットとOpenXRローダーのパッケージングです。
• godot-platform-mobile — Quest向けの出荷にも関わる、スタンドアロンヘッドセットのAndroid制約（熱、解像度スケール、タッチレスUX）です。

下流／利用側

• godot-platform-web — ブラウザーVR向けに、同じXRServerインターフェースのパターンを再利用するWebXRのsession_started／endedフローです。
• godot-scene-management — 体験の途中でfocus_lostまたはsession_endedが発生したときの、ツリーの一時停止とシーンの切り替えです。

マスター

• godot-master — スキルを横断して発見するためのライブラリールーター兼、ミラー化されたモジュールエントリーです。