quest-native

Horizon OS 向けネイティブ OpenXR

C または C++ で書かれた Quest アプリは、ヘッドセットとは OpenXR を通じて、その下で動作するスマートフォン向け OS とは Android を通じて通信します。問題のほとんどは、その境界で発生します。サイドロードには適法でもストアでは認められないマニフェスト、機能を制限する代わりにクラッシュするローダーのバージョン、フォーカスを失った途端に描画を停止するフレームループなどです。

プロジェクトの調査、ターゲット／バージョンの契約、エンジンへの引き継ぎ、垂直スライス、監査については references/project-playbook.md をお読みください。機能／権限の決定、トラッキング／ルームのライフサイクル、コロケーション、カメラまたは AI の入力については references/mixed-reality.md をお読みください。

製品全体のロードマップやステージ監査には quest-lifecycle を使用してください。単一の技術的なタスクは、このスキルの担当です。存在しない場合は、現在のステージ、その証拠、次の前提条件をインラインで特定してください。

ステップ 0 — そもそもこのプロジェクトは対象レーンに該当しますか？

プロジェクト	担当
OpenXR を使用する C / C++、Gradle + NDK	このスキル
Unity	Meta の hz-unity-* スキル（12 種類：コア SDK、MRUK、移動／リターゲティング、quest-ui、パススルーカメラ、配置、プラットフォーム SDK、プロジェクトアナライザー、TMP、FBX インポート、フェイストラッキング、コードレビュー）
Unreal	https://developers.meta.com/horizon/llmstxt/documentation/unreal/llms.txt/
Kotlin / Spatial SDK	Meta の hz-spatial-sdk
WebXR、IWSDK、PWA	このパックの quest-webxr
既存の 2D Android アプリ	Meta の hz-android-2d-porting

対象レーンを誤ると、このファイル内のどの単一のバグよりも大きな損失につながります。Unity 向けの回答は NativeActivity には適用できず、OpenXR の拡張機能名は Unity の OVR ラッパーには適用できません。

ステップ 1 — 検証してから回答する

Horizon OS は独自のサイクルでリリースされ、API の仕様も変化します。Quest API、必須 SDK レベル、マニフェスト要素に関する主張は、コードに反映する前に必ず Meta の公式ドキュメントで確認します。

metavr docs search "openxr swapchain"          # the CLI; the MCP server exposes the same search

すべてのドキュメントページには Markdown 版があります。HTML のスクレイピングもログインも不要です。

index:  https://developers.meta.com/horizon/llmstxt/documentation/native/llms.txt/
page:   https://developers.meta.com/horizon/llmstxt/documentation/native/android/<slug>.md

references/doc-map.md には、覚えておく価値のあるスラッグがまとめられています。Meta の hz-quest-verify-first スキルがインストールされている場合、この確認は自動的に実行されます。検索を繰り返すのではなく、その結果をお読みください。

ステップ 2 — マニフェストは 2 種類あります

開発時とリリース時では要件が異なり、レビュー時に適用されるのはリリース要件のみです（VRC.Quest.Packaging.1、.4）。開発用マニフェストを作成しても、リリースとの差分を確認せずに提出すると、レビューに不合格となることがあります。

没入型 OpenXR アプリ向けの現在の Meta マニフェスト要素（2026-09-21 に再確認済み）：

<uses-feature android:name="android.hardware.vr.headtracking"
              android:required="true" android:version="1" />

<intent-filter>
  <action   android:name="android.intent.action.MAIN" />
  <category android:name="android.intent.category.LAUNCHER" />
  <category android:name="com.oculus.intent.category.VR" />
</intent-filter>

• android.hardware.vr.headtracking に required="true" を設定すると、アプリは没入型アプリになります。2D パネルアプリでは、この要素を省略するか、required="false" に設定します。
• android:screenOrientation="landscape"、テーマ Theme.Black.NoTitleBar.Fullscreen、およびマニフェストのドキュメントに記載されている長い configChanges のリストを設定します。noHistory は絶対に使用しないでください。
• リリース時のみ：android:debuggable を false にするか省略し、installLocation="auto" を設定し、一意の android:label を指定し、com.oculus.supportedDevices に quest2|questpro|quest3|quest3s を列挙します。このリストにないデバイスでは互換モードで実行され、旧世代のデバイスとして報告されます。
• 純粋な NativeActivity アプリでは、android:hasCode="false" を指定してリリースできます。Platform SDK は Java ライブラリであるため、追加するとこのオプションは使用できなくなります。

両方のマニフェストを並べた、要素ごとの完全な契約については references/manifest-and-gradle.md をご覧ください。

ステップ 3 — 2026 年に変更された SDK レベル

サポート対象期間内のデバイス（Quest 2、Pro、3 ファミリー）向けの推奨値は、minSdk 32、targetSdk 34、compileSdk ≥ targetSdk です。法的な範囲は、イマーシブアプリでは minSdk 29～34、targetSdk 32～34（2D パネルアプリでは 32～36）ですが、2026 年 3 月 1 日以降に作成されたアプリは targetSdk を 34 にする必要があります。値を固定する前に、元資料の 2 つの表を確認してください。日付とともに references/manifest-and-gradle.md に引用されています。

ロックファイルはビルドそのものではありません。 build.gradle と、プロジェクトで使用している依存関係ロックファイルを両方 grep してください。2026-09-20、ある Quest プロジェクトでは Gradle が targetSdk 34 と示す一方、dependencies.lock.json はまだ 32 を示していました。これは、存在しないビルドを前提に書かれたリリースノートです。

ステップ 4 — ローダーと、コードを実行する前に必要な 2 つの拡張機能

android { buildFeatures { prefab true } }
dependencies { implementation 'org.khronos.openxr:openxr_loader_for_android:<ver>' }

• Meta がサポートするのは Khronos Android ローダーです。独自ローダーはもう存在しません。1.0.34 未満ではアプリがクラッシュし、フォールバックはありません。
• Khronos ローダーを使うアプリは、v62 より古い Horizon OS ではクラッシュします。また、v62 未満の Quest 1 以外のユーザーには、ストアでアップデートが表示されません。
• XR_KHR_loader_init_android：xrGetInstanceProcAddress を使ってインスタンスを null にして xrInitializeLoaderKHR を取得し、XrLoaderInitInfoAndroidKHR を渡して呼び出してから、何かを作成します。
• XR_KHR_android_create_instance：Android 固有のパラメーターは、この拡張機能を介して xrCreateInstance に渡されます。

ステップ 5 — レビューに合格するフレームループ

• セッションは xrPollEvent を基準に進めます。セッションの開始と終了を決めるのはブール値ではなく、状態機械です。
• xrWaitFrame → xrBeginFrame → 描画 → xrEndFrame の順に実行し、待機処理が返した予測表示時刻にすべてのポーズを適用します。プロファイルが正常でも、「現在」の時刻に描画するとジャダーが発生します。
• フォーカス対応は VRC の要件であり、単なる配慮ではありません（VRC.Quest.Input.4）。アプリはフォーカスを失っても描画を続け、手とコントローラーを非表示にし、入力を無視します。システムメニューでフリーズするアプリはレビューに合格しません。
• xrEnumerateSwapchainFormats でスワップチェーン形式を列挙し、返された形式から選びます。形式をハードコードすると、次のヘッドセットで問題が発生しかねません。色空間は明示的に指定します（XR_FB_color_space）。仮定してはいけません。
• 64 ビットバイナリのみです（VRC.Quest.Packaging.6）。APK は 1 GB 未満、OBB は 4 GB 未満にしてください（.5）。

セッション状態、フレームペーシング、フォーカスのルールについて詳しくは、references/frame-loop.md を参照してください。

このスキルから引き継ぐ内容

次の質問	場所
動作するがフレームが落ちる	quest-perf（フレーム予算、GPU% の落とし穴、キャプチャツール）
ヘッドセットにインストールする方法／ログを読む方法	quest-tooling（metavr CLI + MCP、adb、シミュレーター）
リリースする方法	quest-store（チャンネル、VRC、DUC、アップロード）
代わりに WebXR または PWA ビルドを使う場合	quest-webxr

デバッグを一巡余計に要する落とし穴

• 開発用マニフェストはサイドローディングに通るのに、レビューで失敗します。 2つのドキュメントにはそれぞれ異なる要件があり、リリース用は resources/publish-mobile-manifest です。
• 起動カテゴリが間違っていると、レンダリングのバグに見えることがあります。 現在のMetaのリリースページには com.oculus.intent.category.VR と記載されています。汎用的なOpenXRのスニペットではなく、そのページと選択したSDKに照らして、マージ後のAPKを確認してください。
• 1.0.34未満のLoaderは、起動時にクラッシュします。 Loaderを指し示す診断情報はありません。
• hasCode="false" とPlatform SDKは併用できません ― エンタイトルメントチェック（VRC.Quest.Security.1 は要件ではなく推奨事項です）によって、ネイティブアプリにJavaが取り込まれます。
• 最も手早く正しい答えを得られるのはサンプルです。 hello_xr（Khronos）とMetaのOpenXR SDKサンプル ― XrPassthrough、XrSceneModel、XrHandsAndControllers、XrSpaceWarp、XrSpatialAnchor、XrVirtualKeyboard ― は、それぞれ1つの拡張機能をエンドツーエンドで実演しています。拡張機能を手書きする前に、サンプルを読んでください。

上記のドキュメント情報は2026-09-20にdevelopers.meta.comから確認しました。数値を誰かに伝える前に、metavr docs search で再確認してください。

トリガー

ここに誘導するその他のフレーズ：「Quest C++」／「QuestのC++開発」、「VR用AndroidManifest」／ 「VR用マニフェスト」、「openxr_loader_for_android」、「xrWaitFrame」、「QuestのtargetSdk」／ 「QuestのtargetSdkは何か」、「IMMERSIVE_HMD」、「hello_xr」、「ネイティブでのpassthrough」／ 「ネイティブでpassthrough」。

0.4.4の説明からこちらに移動しました：「Quest向けネイティブアプリ」。