Back to Details

hz-spatial-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spatial SDK Skill

Spatial SDK 技能

Build native Android spatial applications for Meta Quest using the Meta Spatial SDK. This skill covers the Entity-Component-System architecture, 2D panel rendering, 3D object placement, hybrid app development, and deployment to Horizon OS devices.
使用Meta Spatial SDK为Meta Quest构建原生Android空间应用。本技能涵盖实体组件系统（ECS）架构、2D面板渲染、3D对象放置、混合应用开发以及向Horizon OS设备部署应用的相关内容。

When to Use This Skill

适用场景

Use this skill when you need to:
  • Build a native Android app for Meta Quest using the Spatial SDK and Kotlin
  • Create hybrid experiences that combine 2D Android UI panels with 3D content
  • Work with the Entity-Component-System (ECS) architecture in Spatial SDK
  • Add 3D objects, animations, or spatial interactions to a Quest application
  • Configure panels using Jetpack Compose or Android Views for spatial rendering
  • Use the Spatial Editor to compose 3D scenes visually
  • Deploy and test Spatial SDK applications on a Quest device
This skill applies to all Meta Quest headsets running Horizon OS (Quest 2, Quest 3, Quest 3S, Quest Pro).
当你需要以下操作时，可使用本技能：
  • 使用Spatial SDK和Kotlin为Meta Quest构建原生Android应用
  • 创建融合2D Android UI面板与3D内容的混合体验
  • 在Spatial SDK中使用实体组件系统（ECS）架构
  • 为Quest应用添加3D对象、动画或空间交互功能
  • 使用Jetpack Compose或Android Views配置面板以实现空间渲染
  • 使用Spatial Editor可视化构建3D场景
  • 在Quest设备上部署并测试Spatial SDK应用
本技能适用于所有运行Horizon OS的Meta Quest头戴设备（Quest 2、Quest 3、Quest 3S、Quest Pro）。

What is Meta Spatial SDK

什么是Meta Spatial SDK

Meta Spatial SDK is Meta's native Android framework for building spatial applications on Horizon OS. It extends the standard Android development model with spatial capabilities, allowing developers to write apps in Kotlin that render 2D UI panels in 3D space, display glTF models, handle spatial input, and integrate with Horizon OS features like passthrough, scene understanding, and hand tracking.
Unlike Unity or Unreal Engine, Spatial SDK builds on top of the Android Activity lifecycle. Applications are standard Android APKs that use Spatial SDK libraries to gain spatial rendering and interaction capabilities.
Meta Spatial SDK是Meta推出的原生Android框架，用于在Horizon OS上构建空间应用。它在标准Android开发模型基础上扩展了空间能力，允许开发者使用Kotlin编写应用，在3D空间中渲染2D UI面板、显示glTF模型、处理空间输入，并与Horizon OS的透视显示、场景理解、手部追踪等功能集成。
与Unity或Unreal Engine不同，Spatial SDK基于Android Activity生命周期构建。应用是标准的Android APK，通过引入Spatial SDK库获得空间渲染和交互能力。

Key characteristics:

核心特性：

  • Kotlin-first: all application logic is written in Kotlin
  • Android-native: builds on standard Android Activity, Gradle, and Jetpack libraries
  • ECS architecture: entities, components, and systems manage 3D scene state
  • Panel rendering: Android UI frameworks (Jetpack Compose, Views) render as spatial panels
  • Gradle integration: Spatial SDK ships as AAR libraries pulled via Gradle dependencies
  • 优先支持Kotlin：所有应用逻辑均使用Kotlin编写
  • 原生Android支持：基于标准Android Activity、Gradle和Jetpack库构建
  • ECS架构：通过实体、组件和系统管理3D场景状态
  • 面板渲染：Android UI框架（Jetpack Compose、Views）可渲染为空间面板
  • Gradle集成：Spatial SDK以AAR库形式提供，可通过Gradle依赖引入

Key Concepts

核心概念

Entity-Component-System (ECS)

实体组件系统（ECS）

The Spatial SDK uses an ECS architecture to manage the 3D scene graph. This separates data (components) from behavior (systems):
  • Entity: a lightweight identifier (ID) that groups components together. An entity has no behavior on its own.
  • Component: a data container attached to an entity. Components are defined via XML attribute schemas and hold typed fields (floats, vectors, references, enums). Examples: 
    Transform
    , 
    Mesh
    , 
    Panel
    , 
    Grabbable
    .
  • System: a Kotlin class that queries entities by their components and executes logic each frame. Systems extend 
    SystemBase
    and override the 
    execute()
    method.
kotlin
// Example: a simple system that rotates all entities with a Spinner component
class SpinnerSystem : SystemBase() {
  override fun execute() {
    val query = Query.where { has(Spinner.id, Transform.id) }
    for (entity in query.eval()) {
      val transform = entity.getComponent<Transform>()
      val spinner = entity.getComponent<Spinner>()
      transform.rotation *= Quaternion.fromAxisAngle(Vector3.UP, spinner.speed * getDeltaTime())
      entity.setComponent(transform)
    }
  }
}
Spatial SDK采用ECS架构管理3D场景图。它将数据（组件）与行为（系统）分离：
  • 实体（Entity）：轻量级标识符（ID），用于将组件分组。实体本身无行为。
  • 组件（Component）：附加到实体的数据容器。组件通过XML属性模式定义，包含类型化字段（浮点数、向量、引用、枚举）。例如：
    Transform
    、
    Mesh
    、
    Panel
    、
    Grabbable
    。
  • 系统（System）：Kotlin类，通过组件查询实体并在每一帧执行逻辑。系统继承自
    SystemBase
    并覆盖
    execute()
    方法。
kotlin
// Example: a simple system that rotates all entities with a Spinner component
class SpinnerSystem : SystemBase() {
  override fun execute() {
    val query = Query.where { has(Spinner.id, Transform.id) }
    for (entity in query.eval()) {
      val transform = entity.getComponent<Transform>()
      val spinner = entity.getComponent<Spinner>()
      transform.rotation *= Quaternion.fromAxisAngle(Vector3.UP, spinner.speed * getDeltaTime())
      entity.setComponent(transform)
    }
  }
}

2D Panels

2D面板

Panels are the primary way to display Android UI in spatial apps. A 
PanelRegistration
maps a panel name to a Jetpack Compose composable or an Android View. Panels render as flat rectangles positioned in 3D space.
kotlin
override fun registerPanels(): List<PanelRegistration> {
  return listOf(
    PanelRegistration("main_panel") {
      layoutParams = LayoutParams(592f, 592f, SpatialPanelLayoutParams.HORIZONTAL)
      panel {
        MainScreen()  // Jetpack Compose composable
      }
    }
  )
}
面板是在空间应用中显示Android UI的主要方式。
PanelRegistration
将面板名称映射到Jetpack Compose可组合项或Android View。面板渲染为放置在3D空间中的平面矩形。
kotlin
override fun registerPanels(): List<PanelRegistration> {
  return listOf(
    PanelRegistration("main_panel") {
      layoutParams = LayoutParams(592f, 592f, SpatialPanelLayoutParams.HORIZONTAL)
      panel {
        MainScreen()  // Jetpack Compose composable
      }
    }
  )
}

3D Objects

3D对象

Load glTF models as meshes and place them in the scene using 
Transform
and 
Mesh
components:
kotlin
val modelEntity = Entity.create()
modelEntity.setComponent(
  Mesh(Uri.parse("apk:///models/robot.glb"))
)
modelEntity.setComponent(
  Transform(Pose(Vector3(0f, 1f, -2f)))
)
加载glTF模型作为网格，并使用
Transform
和
Mesh
组件将其放置在场景中：
kotlin
val modelEntity = Entity.create()
modelEntity.setComponent(
  Mesh(Uri.parse("apk:///models/robot.glb"))
)
modelEntity.setComponent(
  Transform(Pose(Vector3(0f, 1f, -2f)))
)

Hybrid Apps

混合应用

Spatial SDK excels at hybrid applications that combine 2D panels with 3D content. A single activity can display Android UI panels alongside 3D models, allowing users to interact with familiar 2D interfaces while surrounded by spatial content.
Spatial SDK擅长构建融合2D面板与3D内容的混合应用。单个Activity可同时显示Android UI面板和3D模型，允许用户在空间内容环绕的同时与熟悉的2D界面交互。

Activity Structure

Activity结构

For most Spatial SDK apps, keep one 
SpatialActivity
subclass as the root shell for the whole experience. Tool-style apps usually work best when that single activity owns the scene, registered panels, and ECS systems while UI states change inside that shell.
Avoid structuring a Quest-native tool app like a standard multi-activity Android app unless you have a specific platform reason. Multiple panels or different UI states are usually better expressed inside the same spatial activity.
对于大多数Spatial SDK应用，保留一个
SpatialActivity
子类作为整个体验的根容器。工具类应用通常在单个Activity中管理场景、已注册面板和ECS系统，UI状态在该容器内切换。
除非有特定平台需求，否则避免将Quest原生工具应用设计为标准的多Activity Android应用。多个面板或不同UI状态通常更适合在同一个空间Activity内实现。

Scene

场景（Scene）

The 
Scene
class manages the 3D environment, including the skybox, image-based lighting (IBL), viewer position, and the reference space. Each 
SpatialActivity
has an associated scene.
Scene
类管理3D环境，包括天空盒、基于图像的照明（IBL）、观察者位置和参考空间。每个
SpatialActivity
都关联一个场景。

Spatial Editor

Spatial Editor

The Spatial Editor is a visual tool (integrated into Android Studio via the Meta Horizon plugin) for composing 3D scenes. It produces 
.glxf
files that define entity arrangements, panel placements, and 3D object positions. These files are loaded at runtime.
Spatial Editor是一个可视化工具（通过Meta Horizon插件集成到Android Studio中），用于构建3D场景。它生成
.glxf
文件，定义实体布局、面板位置和3D对象位置。这些文件在运行时加载。

Quick Start

快速开始

Prerequisites

前提条件

  1. Android Studio with the Meta Horizon Android Studio Plugin installed
  2. Meta Spatial SDK dependencies added to your Gradle project
  3. A Meta Quest device connected via USB with developer mode enabled
  1. 安装了Meta Horizon Android Studio插件的Android Studio
  2. Gradle项目中已添加Meta Spatial SDK依赖
  3. 通过USB连接并启用开发者模式的Meta Quest设备

Step-by-step

步骤

  1. Create a new project from the Spatial SDK template in Android Studio (or add Spatial SDK dependencies to an existing project).
  2. Define your activity by extending 
    SpatialActivity
    :
kotlin
class MyActivity : SpatialActivity() {

  override fun registerPanels(): List<PanelRegistration> {
    return listOf(
      PanelRegistration("home_panel") {
        layoutParams = LayoutParams(592f, 592f, SpatialPanelLayoutParams.HORIZONTAL)
        panel {
          HomeScreen()
        }
      }
    )
  }

  override fun registerSystems(): List<SystemBase> {
    return listOf(
      SpinnerSystem()
    )
  }

  override fun onSceneReady(scene: Scene) {
    super.onSceneReady(scene)
    scene.setViewerPosition(Vector3(0f, 0f, 0f))
    // Spawn panels and 3D objects here
    Entity.createPanelEntity("home_panel")
  }
}
  1. Add 3D content via the Spatial Editor or programmatically:
kotlin
// Load a 3D model
val robot = Entity.create(
  Mesh(Uri.parse("apk:///models/robot.glb")),
  Transform(Pose(Vector3(0f, 0.5f, -1.5f)))
)
  1. Build and deploy to your connected Quest device using metavr (invoke via 
    metavr <args>
    , or 
    npx -y metavr <args>
    if not on PATH):
bash
undefined
  1. 创建新项目：在Android Studio中从Spatial SDK模板创建项目（或向现有项目添加Spatial SDK依赖）。
  2. 定义Activity：继承
    SpatialActivity
    ：
kotlin
class MyActivity : SpatialActivity() {

  override fun registerPanels(): List<PanelRegistration> {
    return listOf(
      PanelRegistration("home_panel") {
        layoutParams = LayoutParams(592f, 592f, SpatialPanelLayoutParams.HORIZONTAL)
        panel {
          HomeScreen()
        }
      }
    )
  }

  override fun registerSystems(): List<SystemBase> {
    return listOf(
      SpinnerSystem()
    )
  }

  override fun onSceneReady(scene: Scene) {
    super.onSceneReady(scene)
    scene.setViewerPosition(Vector3(0f, 0f, 0f))
    // Spawn panels and 3D objects here
    Entity.createPanelEntity("home_panel")
  }
}
  1. 添加3D内容：通过Spatial Editor或编程方式添加：
kotlin
// Load a 3D model
val robot = Entity.create(
  Mesh(Uri.parse("apk:///models/robot.glb")),
  Transform(Pose(Vector3(0f, 0.5f, -1.5f)))
)
  1. 构建并部署到已连接的Quest设备（使用metavr，可通过
    metavr <args>
    调用，若未在PATH中则使用
    npx -y metavr <args>
    ）：
bash
undefined

Build the APK via Gradle

Build the APK via Gradle

./gradlew assembleDebug
./gradlew assembleDebug

Install using metavr

Install using metavr

metavr app install app/build/outputs/apk/debug/app-debug.apk
metavr app install app/build/outputs/apk/debug/app-debug.apk

Launch the app

Launch the app

metavr app launch com.example.myspatialapp
metavr app launch com.example.myspatialapp

View logs

View logs

metavr log
undefined
metavr log
undefined

Architecture Overview

架构概述

The high-level architecture of a Spatial SDK application:
Android Activity
  └── SpatialActivity
        ├── Scene (environment, lighting, viewer)
        ├── DataModel (entity-component store)
        │     ├── Entity: Panel ("home_panel")
        │     │     ├── Transform
        │     │     ├── PanelComponent
        │     │     └── Grabbable
        │     ├── Entity: 3D Object ("robot")
        │     │     ├── Transform
        │     │     └── Mesh
        │     └── Entity: Light
        │           ├── Transform
        │           └── PointLight
        ├── Systems
        │     ├── SpinnerSystem
        │     ├── IsdkSupportingSystems (input)
        │     └── PhysicsSystem
        └── PanelRegistrations
              └── "home_panel" → Jetpack Compose UI
  • SpatialActivity extends Android 
    Activity
    and manages the Scene and DataModel lifecycle.
  • DataModel is the central ECS store where all entities and components live.
  • Scene configures the 3D environment (skybox, IBL, reference space).
  • Systems run each frame and operate on entities matching their queries.
  • PanelRegistrations bind panel names to UI content.
Spatial SDK应用的高级架构：
Android Activity
  └── SpatialActivity
        ├── Scene (environment, lighting, viewer)
        ├── DataModel (entity-component store)
        │     ├── Entity: Panel ("home_panel")
        │     │     ├── Transform
        │     │     ├── PanelComponent
        │     │     └── Grabbable
        │     ├── Entity: 3D Object ("robot")
        │     │     ├── Transform
        │     │     └── Mesh
        │     └── Entity: Light
        │           ├── Transform
        │           └── PointLight
        ├── Systems
        │     ├── SpinnerSystem
        │     ├── IsdkSupportingSystems (input)
        │     └── PhysicsSystem
        └── PanelRegistrations
              └── "home_panel" → Jetpack Compose UI
  • SpatialActivity继承自Android 
    Activity
    ，管理Scene和DataModel的生命周期。
  • DataModel是ECS的中央存储，所有实体和组件都存储于此。
  • Scene配置3D环境（天空盒、IBL、参考空间）。
  • Systems在每一帧运行，对符合查询条件的实体执行操作。
  • PanelRegistrations将面板名称绑定到UI内容。

Gradle Dependencies

Gradle依赖

Add the Spatial SDK to your 
build.gradle.kts
:
kotlin
dependencies {
  implementation("com.meta.spatial:meta-spatial-sdk:latest")
  implementation("com.meta.spatial:meta-spatial-sdk-physics:latest")
  implementation("com.meta.spatial:meta-spatial-sdk-isdk:latest")
  implementation("com.meta.spatial:meta-spatial-sdk-mruk:latest")
}
Apply the Spatial SDK Gradle plugin for code generation:
kotlin
plugins {
  id("com.meta.spatial.plugin") version "latest"
}
在
build.gradle.kts
中添加Spatial SDK：
kotlin
dependencies {
  implementation("com.meta.spatial:meta-spatial-sdk:latest")
  implementation("com.meta.spatial:meta-spatial-sdk-physics:latest")
  implementation("com.meta.spatial:meta-spatial-sdk-isdk:latest")
  implementation("com.meta.spatial:meta-spatial-sdk-mruk:latest")
}
应用Spatial SDK Gradle插件以生成代码：
kotlin
plugins {
  id("com.meta.spatial.plugin") version "latest"
}

Manifest Configuration

清单配置

Spatial SDK apps require specific manifest entries:
xml
<uses-feature
  android:name="android.hardware.vr.headtracking"
  android:required="true" />

<!-- Include these when the app should launch and remain usable with hands,
     not only paired controllers. -->
<uses-feature
  android:name="oculus.software.handtracking"
  android:required="false" />
<uses-permission android:name="com.oculus.permission.HAND_TRACKING" />

<application>
  <activity
    android:name=".MyActivity"
    android:exported="true">
    <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>
  </activity>
</application>
For panel or hybrid apps that should work without controllers, declare hand tracking support and make sure the experience handles switching between hands and controllers cleanly. Meta's VRC guidance applies to panel apps as well as immersive apps.
If your app needs to talk to a local development service over 
http://
or 
ws://
, you may also need debug-only cleartext traffic settings or a network security config. Keep that scoped to development builds and prefer 
https://
and 
wss://
in release builds.
Spatial SDK应用需要特定的清单条目：
xml
<uses-feature
  android:name="android.hardware.vr.headtracking"
  android:required="true" />

<!-- Include these when the app should launch and remain usable with hands,
     not only paired controllers. -->
<uses-feature
  android:name="oculus.software.handtracking"
  android:required="false" />
<uses-permission android:name="com.oculus.permission.HAND_TRACKING" />

<application>
  <activity
    android:name=".MyActivity"
    android:exported="true">
    <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>
  </activity>
</application>
对于无需控制器即可运行的面板或混合应用，需声明手部追踪支持，并确保体验能在手部和控制器之间顺畅切换。Meta的VRC指南同样适用于面板应用和沉浸式应用。
如果应用需要通过
http://
或
ws://
与本地开发服务通信，可能还需要仅调试模式下的明文流量设置或网络安全配置。请将其限定在开发构建中，发布构建优先使用
https://
和
wss://
。

References

参考资料

Skill References

技能参考

  • Architecture Guide -- ECS model, custom components and systems, scene management, and activity lifecycle
  • Panels and 3D Objects -- 2D panel rendering, 3D object loading, hybrid app development
  • Interaction SDK -- Input handling, grabbables, hand tracking, controller input, haptics
  • Debugging -- Data Model Inspector, OVR Metrics Tool, logcat filtering, common issues
  • 架构指南 —— ECS模型、自定义组件与系统、场景管理及Activity生命周期
  • 面板与3D对象 —— 2D面板渲染、3D对象加载、混合应用开发
  • 交互SDK —— 输入处理、可抓取对象、手部追踪、控制器输入、触觉反馈
  • 调试 —— 数据模型检查器、OVR指标工具、logcat过滤、常见问题