hz-spatial-sdk

Spatial SDK スキル

Meta Spatial SDK を使用して、Meta VR 向けのネイティブ Android 空間アプリケーションを構築します。このスキルでは、Entity-Component-System アーキテクチャ、2D パネルのレンダリング、3D オブジェクトの配置、ハイブリッドアプリの開発、Horizon OS デバイスへのデプロイについて説明します。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• Spatial SDK と Kotlin を使用して、Meta VR 向けのネイティブ Android アプリを構築する
• 2D Android UI パネルと 3D コンテンツを組み合わせたハイブリッド体験を作成する
• Spatial SDK の Entity-Component-System（ECS）アーキテクチャを使用する
• Meta VR アプリケーションに 3D オブジェクト、アニメーション、または空間インタラクションを追加する
• 空間レンダリング用のパネルを Jetpack Compose または Android Views で設定する
• Spatial Editor を使用して 3D シーンを視覚的に構成する
• Meta VR デバイスに Spatial SDK アプリケーションをデプロイしてテストする

このスキルは、Horizon OS を実行するすべての Meta Quest ヘッドセット（Quest 2、Quest 3、Quest 3S、Quest Pro）に適用されます。

Meta Spatial SDK とは

Meta Spatial SDK は、Horizon OS 向けの空間アプリケーションを構築するための、Meta のネイティブ Android フレームワークです。標準的な Android 開発モデルを空間機能で拡張しており、開発者は Kotlin でアプリを作成し、3D 空間に 2D UI パネルをレンダリングしたり、glTF モデルを表示したり、空間入力を処理したり、パススルー、シーン理解、ハンドトラッキングなどの Horizon OS 機能を統合したりできます。

Unity や Unreal Engine とは異なり、Spatial SDK は Android Activity のライフサイクルを基盤としています。アプリケーションは標準的な Android APK であり、Spatial SDK ライブラリを使用して空間レンダリングとインタラクション機能を利用します。

主な特徴：

• Kotlin を優先：すべてのアプリケーションロジックを Kotlin で記述します
• Android ネイティブ：標準の Android Activity、Gradle、Jetpack ライブラリを基盤としています
• ECS アーキテクチャ：エンティティ、コンポーネント、システムで 3D シーンの状態を管理します
• パネルのレンダリング：Android UI フレームワーク（Jetpack Compose、Views）を空間パネルとしてレンダリングします
• Gradle との統合：Spatial SDK は、Gradle 依存関係を介して取得する AAR ライブラリとして提供されます

主な概念

Entity-Component-System（ECS）

Spatial SDK は ECS アーキテクチャを使用して、3D シーングラフを管理します。これにより、データ（コンポーネント）と動作（システム）を分離します。

• エンティティ：コンポーネントをまとめる軽量な識別子（ID）です。エンティティ自体には動作がありません。
• コンポーネント：エンティティにアタッチされるデータコンテナーです。コンポーネントは XML 属性スキーマで定義され、型付きフィールド（浮動小数点数、ベクトル、参照、列挙値）を保持します。例：Transform、Mesh、Panel、Grabbable。
• システム：コンポーネントに基づいてエンティティを検索し、各フレームでロジックを実行する Kotlin クラスです。システムは SystemBase を拡張し、execute() メソッドをオーバーライドします。

// Example: a simple system that rotates all entities with a Spinner component
class SpinnerSystem : SystemBase() {
  private var previousTime = 0L

  override fun execute() {
    val currentTime = System.currentTimeMillis()
    if (previousTime == 0L) previousTime = currentTime
    val timeDeltaInSeconds = (currentTime - previousTime) / 1000f
    previousTime = currentTime

    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.transform.q =
        transform.transform.q * Quaternion(0f, spinner.speed * timeDeltaInSeconds, 0f)
      entity.setComponent(transform)
    }
  }
}

2D パネル

パネルは、空間アプリで Android UI を表示する主な方法です。型付きの PanelRegistration により、整数のリソース ID を Jetpack Compose のコンポーザブル、 Android View、Activity、またはメディアサーフェスに対応付けます。パネルは 3D シーン内に配置されたサーフェスとしてレンダリングされます。

override fun registerPanels(): List<PanelRegistration> {
  return listOf(
    ComposeViewPanelRegistration(
      registrationId = R.id.main_panel,
      composeViewCreator = { _, context ->
        ComposeView(context).apply { setContent { MainScreen() } }
      },
      settingsCreator = {
        UIPanelSettings(
          shape = QuadShapeOptions(width = 0.8f, height = 0.6f),
          display = DpDisplayOptions(width = 592f, height = 444f),
        )
      },
    )
  )
}

3D オブジェクト

glTF モデルをメッシュとして読み込み、Transform コンポーネントと Mesh コンポーネントを使用してシーンに配置します。

val modelEntity = Entity.create()
modelEntity.setComponent(
  Mesh(Uri.parse("apk:///models/robot.glb"))
)
modelEntity.setComponent(
  Transform(Pose(Vector3(0f, 1f, 2f)))
)

ハイブリッドアプリ

Spatial SDK は、2D パネルと 3D コンテンツを組み合わせたハイブリッドアプリケーションに適しています。1 つの Activity で、3D モデルと並べて Android UI パネルを表示できます。これにより、ユーザーは空間コンテンツに囲まれながら、使い慣れた 2D インターフェースを操作できます。

Activity の構成

ほとんどの Spatial SDK アプリでは、1 つの AppSystemActivity サブクラスを、体験全体のルートシェルとして使用してください。ツール形式のアプリでは通常、その単一の Activity がシーン、登録済みパネル、ECS システムを所有し、そのシェル内で UI の状態を切り替える構成が最適です。

特定のプラットフォーム上の理由がない限り、Quest ネイティブのツールアプリを標準的な複数 Activity の Android アプリのように構成するのは避けてください。複数のパネルや異なる UI 状態は、通常、同じ空間 Activity 内で表現する方が適しています。

Scene

Sceneクラスは、スカイボックス、イメージベースドライティング（IBL）、ビューの原点、基準空間など、3D環境を管理します。各AppSystemActivityには、対応するシーンがあります。

Spatial Editor

Spatial Editorは、3Dシーンを構成するためのビジュアルツールです（Meta Horizonプラグインを介してAndroid Studioに統合されています）。エンティティの配置、パネルの配置、3Dオブジェクトの位置を定義する.glxfファイルを生成します。これらのファイルは実行時に読み込まれます。

クイックスタート

前提条件

1. Meta Horizon Android Studio PluginをインストールしたAndroid Studio
2. Gradleプロジェクトに追加されたMeta Spatial SDKの依存関係
3. 開発者モードを有効にしてUSB接続したMeta VRデバイス

手順

1. Android StudioでSpatial SDKテンプレートから新しいプロジェクトを作成します（または既存のプロジェクトにSpatial SDKの依存関係を追加します）。

2. AppSystemActivityを拡張して、現在の型付きパネル登録APIを使用し、アクティビティを定義します。

class MyActivity : AppSystemActivity() {

  override fun registerPanels(): List<PanelRegistration> {
    return listOf(
      ComposeViewPanelRegistration(
        registrationId = R.id.home_panel,
        composeViewCreator = { _, context ->
          ComposeView(context).apply { setContent { HomeScreen() } }
        },
        settingsCreator = {
          UIPanelSettings(
            shape = QuadShapeOptions(width = 0.8f, height = 0.6f),
            display = DpDisplayOptions(width = 592f, height = 444f),
          )
        },
      )
    )
  }

  override fun registerFeatures(): List<SpatialFeature> {
    return listOf(VRFeature(this), ComposeFeature())
  }

  override fun onSceneReady() {
    super.onSceneReady()
    scene.setReferenceSpace(ReferenceSpace.LOCAL_FLOOR)
    Entity.create(
      Panel(panelRegistrationId = R.id.home_panel),
      Transform(Pose(Vector3(0f, 1.2f, 2f))),
      Visible(true),
    )
  }
}

3. Spatial Editorまたはプログラムから3Dコンテンツを追加します。

// Load a 3D model
val robot = Entity.create(
  Mesh(Uri.parse("apk:///models/robot.glb")),
  Transform(Pose(Vector3(0f, 0.5f, 1.5f)))
)

4. metavrを使用して、接続したMeta VRデバイスにビルドしてデプロイします（metavr <args>で実行するか、PATHにない場合はnpx -y metavr <args>で実行します）。

# Build the APK via Gradle
./gradlew assembleDebug

# Install using metavr
metavr app install app/build/outputs/apk/debug/app-debug.apk

# Launch the app
metavr app launch com.example.myspatialapp

# View logs
metavr log

アーキテクチャの概要

Spatial SDKアプリケーションの大まかなアーキテクチャは次のとおりです。

Android Activity
  └── AppSystemActivity
        ├── Scene (environment, lighting, viewer)
        ├── DataModel (entity-component store)
        │     ├── Entity: Panel (R.id.home_panel)
        │     │     ├── Transform
        │     │     ├── PanelComponent
        │     │     └── Grabbable
        │     ├── Entity: 3D Object ("robot")
        │     │     ├── Transform
        │     │     └── Mesh
        │     └── Entity: Light
        │           ├── Transform
        │           └── PointLight
        ├── Features
        │     ├── VRFeature (includes ISDK input by default)
        │     └── PhysicsFeature
        ├── Systems
        │     └── SpinnerSystem
        └── PanelRegistrations
              └── R.id.home_panel → Jetpack Compose UI

• AppSystemActivityはAndroidのActivityを拡張し、SceneとDataModelのライフサイクルを管理します。
• DataModelは、すべてのエンティティとコンポーネントが格納される中心的なECSストアです。
• Sceneは、3D環境（スカイボックス、IBL、基準空間）を設定します。
• Systemsは各フレームで実行され、クエリに一致するエンティティを操作します。
• PanelRegistrationsは、安定した整数リソースIDをUIコンテンツにバインドします。

Gradleの依存関係

現在の公式テンプレートからSpatial SDKのエイリアスをコピーし、プロジェクトのバージョンカタログに追加します。使用時点で最新の安定版を解決し、プラグインとすべてのモジュールで同じspatialsdkバージョンを使用してください。

# gradle/libs.versions.toml
[versions]
spatialsdk = "<latest-stable-version>"

[libraries]
meta-spatial-sdk-base = { module = "com.meta.spatial:meta-spatial-sdk", version.ref = "spatialsdk" }
meta-spatial-sdk-toolkit = { module = "com.meta.spatial:meta-spatial-sdk-toolkit", version.ref = "spatialsdk" }
meta-spatial-sdk-vr = { module = "com.meta.spatial:meta-spatial-sdk-vr", version.ref = "spatialsdk" }
meta-spatial-sdk-compose = { module = "com.meta.spatial:meta-spatial-sdk-compose", version.ref = "spatialsdk" }

[plugins]
meta-spatial-plugin = { id = "com.meta.spatial.plugin", version.ref = "spatialsdk" }

アプリモジュールでは、これらのエイリアスを使用します。

plugins {
  alias(libs.plugins.meta.spatial.plugin)
}

dependencies {
  implementation(libs.meta.spatial.sdk.base)
  implementation(libs.meta.spatial.sdk.toolkit)
  implementation(libs.meta.spatial.sdk.vr)
  implementation(libs.meta.spatial.sdk.compose)
}

meta-spatial-sdk-isdk、meta-spatial-sdk-physics、meta-spatial-sdk-mruk、meta-spatial-sdk-spatialaudioなどのオプションモジュールは、アプリで使用する場合にのみ追加し、libs.versions.tomlでは同じspatialsdkバージョンを指定してください。

マニフェストの設定

Spatial SDKアプリには、特定のマニフェストエントリが必要です。

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


<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://を優先してください。

参考資料

スキルの参考資料

• アーキテクチャガイド -- ECSモデル、カスタムコンポーネントとシステム、シーン管理、アクティビティのライフサイクル
• パネルと3Dオブジェクト -- 2Dパネルのレンダリング、3Dオブジェクトの読み込み、ハイブリッドアプリ開発
• Interaction SDK -- 入力処理、つかめるオブジェクト、ハンドトラッキング、コントローラー入力、触覚フィードバック
• デバッグ -- Data Model Inspector、OVR Metrics Tool、logcatのフィルタリング、よくある問題