quest-spatial

Meta Spatial SDK：通往 Horizon OS 的 Android 路径

Spatial SDK 让 Android 团队能够使用 Kotlin 开发沉浸式应用：Android Studio、Gradle、Jetpack Compose，以及他们已经在使用的库——底层采用 OpenXR， 上层采用 ECS 数据模型。场景中的面板是真正的 Android 视图，而不是别人绘制 出来、看起来像 Android 视图的纹理。

如需规划整个产品的路线图或进行阶段审查，请使用 quest-lifecycle；单项技术任务仍由此技能负责。如果该技能不存在，请在此处指出当前阶段、相关证据和下一项前置要求。

混合使用面板和沉浸式 Activity 时，请阅读 references/hybrid-activities.md：其中介绍独占／协作模式、状态归属和转换测试。

步骤 0 — 这是否是正确的路径？

团队和应用	路径
Android 开发者；面板、2D UI、媒体，或同时也是 2D 应用的应用	Spatial SDK — 此技能
需要最大限度控制渲染器、自定义 Vulkan，或使用自有游戏引擎	quest-native（C/C++ OpenXR）
现有 Unity 内容、Unity 团队、资源商店流水线	Meta 的 hz-unity-* 技能
在 Web 上发布，或也必须能在头显之外运行	quest-webxr
只需在 Quest 上运行的现有 2D Android 应用	Meta 的 hz-android-2d-porting — 迁移，而非重建

Spatial SDK 围绕面板和 ECS 场景构建。请尽早使用下方的运行时估算 选择有代表性的工作负载，不要将其视为硬性 API 上限。实现或审查项目时， 请阅读 references/build-and-audit.md；如果没有 Meta 的配套技能，其中会提供内联流程。

步骤 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 明确指出的升级陷阱： AGP 8.5 或更早版本使用 Gradle 9.x 包装器时，会在原生／CMake 模型同步期间失败，因为该 AGP 调用的 Gradle API 已在 Gradle 9 中移除。将 AGP 升级到 8.11.1 即可解决问题——错误消息 并未指明这一点。

依赖项采用模块化设计；按应用实际用途选取： com.meta.spatial:meta-spatial-sdk（核心，始终需要）、-vr（沉浸式 功能，大多数应用需要）、-toolkit（常见组件和系统）、 -physics、-ovrmetrics，以及 documentation/spatial-sdk/spatial-sdk-packages 中列出的其他依赖项。

第 2 步 — 架构设计前，先看预算

Meta 发布了工作负载估算和建议 （spatial-sdk-runtime-guidelines，于 2026-09-21 重新核查）。在初步设计中使用这些数据，并保留其设备、内容和刷新率假设：

测量/建议项目	快照估算
每个 tick 的实体操作数（系统中的一次读取或写入）	2,000
物理对象	500
视野中的 3D GLB 对象	100（当它们覆盖 >50% 的视口时；覆盖面积更小时才可以更多）
场景图实体	~1,000
面板分辨率开销	每增加 480,000 像素 ≈ +1% GPU

面板表格描述的是独立测试工作负载，并按类型区分：

面板类型	FPS 跌破 90	FPS 持续低于 90
空视图	20	40
仅 UI 视图	15	40
图像视图	15	40
Web 视图	5	30
视频视图	3	5
基于 Activity 的视图	2	2
带图层的面板	5	15

这些测量并未确立“最多 3 个视频/2 个 Activity”的硬性限制，也不能保证混合工作负载可正常运行。在发布版本中测试实际的面板、媒体和对象组合；与其按项目数量扩展面板，不如考虑复用/虚拟化。

第 3 步 — 每个都能浪费一天的陷阱

完整说明和规避方法：references/budgets-and-traps.md。

• 调试版本比发布版本慢得多 — Meta 将其列为已知问题，并非意外情况。请在发布版本中评估性能，否则这些数字毫无意义。
• 进入沉浸式模式可能会关闭其他应用的音频。 除非确实需要独占音频，否则请请求 AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK，并处理 OnAudioFocusChangeListener。
• 沉浸式 Activity 上调用 finish() 可能无法让 2D 面板重新显示，而且当面板使用 enableLayer = true 时，还可能在 libMetaSpatialSDK.so 内部崩溃。enableLayer 已弃用 — 请使用 layerConfig。
• PanelRenderMode.Mesh() 仍会创建合成器图层；规避方法是转换设置后，将 panelConfig.layerConfig = null。
• 共用一个 SceneSwapchain 的图层会忽略每层的 setClip() — 所有图层都会显示最后设置的剪辑。

第 4 步 — 阅读资料的位置

索引位于 documentation/spatial-sdk/llms.txt/，每个页面都有对应的 Markdown 副本，路径为 documentation/spatial-sdk/<slug>.md。前缀说明了页面回答的问题。以下数量对应注明日期的源快照，并非实时目录：

前缀	数量	内容
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 账单兼容性

值得保持打开的 slug 表：references/docs-map.md。

第 5 步 — 示例比文字说明更快给出答案

github.com/meta-quest/Meta-Spatial-SDK-Samples（MIT）。请枚举当前的示例目录，不要依赖文字说明中的数量。打开已经实现目标功能的示例 — references/samples-map.md 会将每个示例对应到它所回答的问题，并注明该仓库自带 AGENTS.md、.mcp.json 和针对各 Agent 的配置，因此可以直接将 Agent 指向克隆下来的仓库。

一段话了解混合应用

混合应用会在一个软件包中切换 2D 面板活动和沉浸式活动。面板活动运行于三种上下文中——主页、叠加层（Quest 按钮菜单）和沉浸式活动中的嵌入式上下文。两种交互模式：独占（一次运行一个；启动新活动后再终止旧活动）和协作（多个活动并发运行）。HybridSample 是参考实现。

此技能的后续指引

后续问题	去哪里
编写 ECS 代码、面板、Gradle 配置	如果有 Meta 的 hz-spatial-sdk，请使用它；否则使用此技能的构建/审计流程
应用能运行，但会掉帧	quest-perf
将应用安装到头显、读取日志、进行捕获	quest-tooling
发布应用	quest-store

上文中的版本、预算和已知问题来自 samples repository 和 developers.meta.com，读取日期为 2026-09-20；两者内容会变动——引用具体数字前，请用 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"、"适用于 Quest 的 Kotlin 应用"。