quest-spatial

Meta Spatial SDK：Horizon OS への Android 向けルート

Spatial SDK を使えば、Android チームは Kotlin でイマーシブアプリをリリースできます。Android Studio、Gradle、Jetpack Compose、すでに使っているライブラリをそのまま活用し、基盤には OpenXR、 その上には ECS データモデルを使用します。シーン内のパネルは、誰かが描いてテクスチャにしたものではなく、本物の Android ビューです。

製品全体のロードマップや段階監査には quest-lifecycle を使用してください。単一の技術的なタスクは、このオーナーの担当です。見当たらない場合は、現在の段階、その根拠、次の前提条件をその場で特定してください。

パネルアクティビティとイマーシブアクティビティを組み合わせる場合は、references/hybrid-activities.md を読んでください。排他的／協調モード、状態の所有権、遷移テストについて説明しています。

Step 0 — このルートが適切か確認する

チームとアプリ	ルート
Android 開発者。パネル、2D UI、メディア、または2Dアプリとしても使えるアプリ	Spatial SDK — このスキル
レンダラーを最大限に制御したい、独自の Vulkan、独自のゲームエンジン	quest-native（C/C++ OpenXR）
既存の Unity コンテンツ、Unity チーム、アセットストアのパイプライン	Meta の hz-unity-* スキル
ウェブでリリースする、またはヘッドセット以外でも動作させる必要がある	quest-webxr
Quest で動かすだけでよい既存の2D Android アプリ	Meta の hz-android-2d-porting — 再構築ではなく移植

Spatial SDK は、パネルと ECS シーンを中心に構築されています。代表的なワークロードを早い段階で選ぶために、以下の実行時の目安を使用してください。これらは API の厳格な上限ではありません。プロジェクトを実装または監査する場合は references/build-and-audit.md を読んでください。Meta のコンパニオンがない場合の、その場で実行できる手順が記載されています。

Step 1 — 実際のツールチェーンを確認する

2026-09-20 に読み取ったスナップショットのサンプル（meta-quest/Meta-Spatial-SDK-Samples、MIT）。 コンシューマー用ラッパー／カタログを最初に確認してください。SDK とビルドの互換性を確かめずに、既存のプロジェクトを以下のバージョンへ更新しないでください。

項目	バージョン
ヘッドセット	Horizon OS v69 以降の Quest 2 / 3 / 3S / Pro
Android Studio	Narwhal (2025.1.1) 以降 — AGP 8.11 で必要
Gradle	9.4.1（ラッパー）
Android Gradle Plugin	8.11.1
Kotlin	2.1.0
JDK	17（Android Studio に同梱。コマンドラインビルドの場合のみ別途必要）
Meta Spatial Editor	MrukSample と PremiumMediaSample を除く、すべてのサンプルで必須
NDK	カスタムシェーダーの場合のみ（MediaPlayerSample、PremiumMediaSample）

Meta が明示するアップグレード時の落とし穴： Gradle 9.x ラッパーを使用しているときに AGP 8.5 以前を実行すると、ネイティブ／CMake モデルの同期中に失敗します。AGP が Gradle 9 で削除された Gradle API を呼び出すためです。AGP を 8.11.1 に上げると解決しますが、エラーメッセージからは原因を特定できません。

依存関係はモジュール化されています。アプリで使うものを選んでください。 com.meta.spatial:meta-spatial-sdk（コア。常に必要）、-vr（イマーシブ機能。ほとんどのアプリで必要）、-toolkit（共通コンポーネントとシステム）、-physics、-ovrmetrics、および documentation/spatial-sdk/spatial-sdk-packages に記載されたその他の依存関係を使用できます。

Step 2 — アーキテクチャを考える前に、予算を確認する

Meta がワークロードの見積もりと推奨事項を公開しています （spatial-sdk-runtime-guidelines、2026-09-21に再確認済み）。最初の 設計案でこれらを使い、デバイス／コンテンツ／更新頻度に関する前提を維持してください。

測定／推奨項目	スナップショットでの見積もり
ティックあたりのエンティティ操作数（システム内での読み取りまたは書き込み）	2,000
物理オブジェクト	500
視野内の3D GLBオブジェクト	ビューポートの50%超を占める場合は100。占有率がそれより低ければ、さらに増やせます
シーングラフのエンティティ	約1,000
パネルの解像度コスト	追加の480,000ピクセルごとにGPU負荷が約**+1%**

パネルの表は、種類ごとの個別テストワークロードを示しています。

パネルの種類	FPSが90を下回る	FPSが90を下回り続ける
空のビュー	20	40
UIのみのビュー	15	40
画像ビュー	15	40
Webビュー	5	30
動画ビュー	3	5
アクティビティベース	2	2
レイヤー付きパネル	5	15

これらの測定結果は、動画パネル3つ／アクティビティ2つという厳密な上限を定めるものでも、混在したワークロードが収まることを保証するものでもありません。リリースビルドで実際のパネル／メディア／オブジェクトの組み合わせをテストしてください。アイテム数に合わせてパネルを増やすのではなく、再利用や仮想化を検討してください。

Step 3 — 1日を無駄にする落とし穴

全文と回避策については、references/budgets-and-traps.mdを参照してください。

• デバッグビルドはリリースより大幅に遅い — Meta が既知の問題として挙げており、意外なことではありません。パフォーマンスはリリースバリアントで評価してください。そうしなければ、数値に意味はありません。
• イマーシブモードに入ると、他のアプリの音声が停止することがあります。 音声の独占が本当に必要な場合を除き、AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCKをリクエストし、OnAudioFocusChangeListenerを処理してください。
• イマーシブアクティビティでfinish()を呼び出しても、2Dパネルが戻らないことがあります。また、パネルでenableLayer = trueを使うと、libMetaSpatialSDK.so内でクラッシュすることがあります。 enableLayerは非推奨です。layerConfigを使用してください。
• PanelRenderMode.Mesh()でもコンポジターレイヤーが作成されます。 回避策は、設定を変換した後にpanelConfig.layerConfig = nullを設定することです。
• 1つのSceneSwapchainを共有するレイヤーでは、レイヤーごとのsetClip()が無視されます — すべてのレイヤーに最後に設定したクリップが表示されます。

Step 4 — 参照先

インデックスはdocumentation/spatial-sdk/llms.txt/にあり、各ページには documentation/spatial-sdk/<slug>.mdにMarkdown版があります。プレフィックスは、各ページがどの質問に答えるかを示します。以下の件数は、日付付きのソーススナップショットに基づくもので、現在の全件数ではありません。

プレフィックス	件数	内容
spatial-sdk-*	97	SDKそのもの：-ecs、-component、-systems、-queries、-2dpanel-*（8件）、-isdk-*（5件、インタラクション）、-ui-*（10件、Horizon OS UI Set）、-mruk、-physics、-animations、-glxf、-gltfs、-custom-shaders、-hot-reload、-known-issues、-runtime-guidelines
spatial-editor-*	20	ビジュアルエディター、そのCLI、アセットライブラリ、コンポジション
ps-*	43	プラットフォームサービス：エンタイトルメント、IAP、リーダーボード、実績、クラウドバックアップ、アテステーション
ts-*	24	トラブルシューティング：adb、logcat、プロファイラー、デバイスのセットアップ
os-*、po-*、platform-*	5	コンポジター、CPU/GPUレベル、メモリ、音声
hybrid-*、horizon-billing-*、add-spatial-sdk-to-app	5	ハイブリッドアプリとGoogle Play Billingの互換性

手元に開いておくと便利なスラッグ一覧：references/docs-map.md。

Step 5 — サンプルは説明文より早く答えを示す

github.com/meta-quest/Meta-Spatial-SDK-Samples（MIT）。説明文の件数に頼らず、現在のサンプルディレクトリを列挙してください。構築中のものをすでに実装しているサンプルを開きましょう。references/samples-map.mdでは、各サンプルが答える質問を対応付けており、リポジトリに独自のAGENTS.md、.mcp.json、エージェントごとの設定が含まれていることも記載しています。そのため、エージェントにクローン先を直接指定できます。

ハイブリッドアプリを1段落で

ハイブリッドアプリでは、1つのパッケージ内で2Dパネルアクティビティと没入型アクティビティを切り替えられます。パネルアクティビティは、Home、Overlay（Questボタンメニュー）、没入型アクティビティ内のEmbeddedという3つのコンテキストで実行されます。インタラクションモデルは2種類あります。排他的（同時に1つのみ。新しいアクティビティを開始した後に古いアクティビティを終了）と、協調的（複数を同時に実行）です。 HybridSample はリファレンス実装です。

このスキルの引き継ぎ先

次の質問	場所
ECSコード、パネル、Gradleの配線を書く	Meta の hz-spatial-sdk が利用可能な場合はそれを使用し、利用できない場合はこのスキルのビルド／監査手順を使用します
実行はできるがフレーム落ちする	quest-perf
ヘッドセットにインストールし、ログを読み取り、キャプチャする	quest-tooling
リリースする	quest-store

上記のバージョン、予算、既知の問題は、2026-09-20にサンプルリポジトリと developers.meta.com を参照したものです。どちらも更新されるため、数値を引用する前に metavr docs search "spatial sdk runtime guidelines" で再確認してください。

トリガー

ここに振り分けるその他のフレーズ：「spatial panels」／「панели в VR」、「Meta Spatial SDK」、「Spatial Editor」、「hybrid app」／「гибридное приложение」、「glXF」、「com.meta.spatial」、「how many panels can I open」／「сколько панелей выдержит」、「Spatial SDK samples」／「примеры Spatial SDK」。

0.4.4の説明から移動した項目：「Kotlin app for Quest」、「приложение на Kotlin для Quest」。