SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场quest-spatial

quest-spatial

智能体与模型

查看项目

更新于 10-16 02:44

技能介绍

用途

Meta Spatial SDK 是 Android 团队进入 Horizon OS 的沉浸式应用开发路径。它允许使用 Kotlin 编写沉浸式应用，沿用 Android Studio、Gradle、Jetpack Compose 以及团队已有的库，底层由 OpenXR 支撑，上层采用 ECS 数据模型。场景中的面板是真实的 Android 视图，而不是绘制成面板样式的纹理。

本技能用于判断某个 Meta Quest 应用是否适合采用 Meta Spatial SDK（即 Kotlin + Android 路线，而非 Unity 或原生 OpenXR），并覆盖其工具链、运行时预算、常见陷阱、文档索引与示例。

路线选择

资料给出如下判断依据：

  • 团队是 Android 开发者；应用包含面板、2D UI、媒体，或本身也是一个 2D 应用：选择 Spatial SDK（本技能）。
  • 需要最大程度控制渲染器、自定义 Vulkan、自研游戏引擎：选择 quest-native（C/C++ OpenXR）。
  • 已有 Unity 内容、Unity 团队、资产商店管线：选择 Meta 的 hz-unity-* 技能。
  • 需要发布到 Web，或必须也能在头显之外运行：选择 quest-webxr。
  • 已有 2D Android 应用，只需在 Quest 上运行：选择 Meta 的 hz-android-2d-porting（属于移植，而非重建）。

Spatial SDK 围绕面板和 ECS 场景构建。资料建议尽早用运行时估算选择代表性工作负载，但这些数字不是硬性 API 上限。

工具链

资料给出 2026-09-20 读取的示例快照（meta-quest/Meta-Spatial-SDK-Samples，MIT）。建议先阅读消费方包装/目录，不要在未检查 SDK 与构建兼容性的情况下将现有项目升级到这些值：

  • 头显：Quest 2 / 3 / 3S / Pro，Horizon OS v69 或更新。
  • Android Studio：Narwhal（2025.1.1）或更新——AGP 8.11 要求。
  • Gradle：9.4.1（wrapper）。
  • 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 wrapper 时，会在原生/CMake 模型同步阶段失败，因为该 AGP 调用了 Gradle 9 中已移除的 API。将 AGP 升级到 8.11.1 可解决，但错误信息不会指向这一点。

依赖是模块化的，按应用实际使用选取：com.meta.spatial:meta-spatial-sdk（核心，始终需要）、-vr（沉浸式功能，多数应用需要）、-toolkit（常用组件与系统）、-physics、-ovrmetrics，以及 documentation/spatial-sdk/spatial-sdk-packages 中列出的其余包。

运行时预算

资料引用 Meta 发布的工作负载估算与建议（spatial-sdk-runtime-guidelines，2026-09-21 复核），建议在最初设计时使用，并保留其设备/内容/刷新率假设：

  • 每 tick 实体操作（系统中一次读或写）：2,000。
  • 物理对象：500。
  • 视口内 3D GLB 对象：覆盖视口超过 50% 时为 100；覆盖更少时可更多。
  • 场景图实体：约 1,000。
  • 面板分辨率成本：每增加 480,000 像素约增加 1% GPU。

面板表格描述的是隔离测试工作负载，且因类型而异：

  • 空视图：FPS 低于 90 出现在 20，持续低于 90 出现在 40。
  • 仅 UI 视图：15 / 40。
  • 图像视图：15 / 40。
  • Web 视图：5 / 30。
  • 视频视图：3 / 5。
  • 基于 Activity：2 / 2。
  • 带图层的面板：5 / 15。

资料强调，这些测量并不构成硬性的“三个视频/两个 Activity”限制，也不保证混合工作负载一定适配。应在 release 构建中测试真实的面板/媒体/对象组合；考虑复用/虚拟化，而不是随项目数量扩展面板。

常见陷阱

资料列出若干“每个都要花一天”的陷阱，完整内容与规避方法见 references/budgets-and-traps.md：

  • Debug 构建比 release 慢得多——Meta 将其列为已知问题，而非意外。性能判断应基于 release 变体，否则数字没有意义。
  • 进入沉浸式可能终止其他应用的音频。除非确实需要独占音频，否则请求 AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK，并处理 OnAudioFocusChangeListener。
  • 在沉浸式 Activity 上调用 finish() 可能不会让 2D 面板回来；当面板使用 enableLayer = true 时，可能在 libMetaSpatialSDK.so 内崩溃。enableLayer 已弃用——应使用 layerConfig。
  • PanelRenderMode.Mesh() 仍会创建合成器图层；规避方法是在转换设置后将 panelConfig.layerConfig = null。
  • 共享同一个 SceneSwapchain 的多个图层会忽略每图层的 setClip()——所有图层都显示最后设置的裁剪。

文档与示例

文档索引位于 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 个，平台服务：entitlement、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。

示例仓库为 github.com/meta-quest/Meta-Spatial-SDK-Samples（MIT）。资料建议枚举其当前示例目录，而不是依赖文字描述的数量；打开已经实现目标功能的示例。references/samples-map.md 将每个示例映射到它回答的问题，并指出该仓库自带 AGENTS.md、.mcp.json 和按代理的配置，因此可以直接把代理指向克隆副本。

混合应用

混合应用在一个包内于 2D 面板 Activity 与沉浸式 Activity 之间切换。面板 Activity 运行在三种上下文中——Home、Overlay（Quest 按钮菜单）以及嵌入沉浸式 Activity 内。有两种交互模型：独占（一次一个；启动新 Activity 后终止旧 Activity）和协作（多个并发）。HybridSample 是参考实现。

交接

资料给出如下交接指引：

  • 编写 ECS 代码、面板、Gradle 接线：Meta 的 hz-spatial-sdk（若存在）；否则使用本技能的构建/审计流程。
  • 能运行但掉帧：quest-perf。
  • 部署到头显、读取日志、捕获：quest-tooling。
  • 发布：quest-store。

资料注明，上述版本、预算与已知问题读取自示例仓库和 developers.meta.com（2026-09-20）；两者都会变化，引用数字前应通过 metavr docs search "spatial sdk runtime guidelines" 重新核对。

限制

资料未提供该 SDK 的收费、价格、平台支持范围之外的信息，也未提供具体功能清单或效果保证。所有版本、预算与已知问题均为特定日期的快照，可能已变化。