RealityKitと空間的メンタルモデル

visionOSにおけるSwiftUIは3D空間にウィンドウを提供します。RealityKitは、その先にある部屋全体を提供するのです。違いはメンタルモデルにあり、メンタルモデルこそがアーキテクチャとなります。

SwiftUI開発者が初めてvisionOSに触れるとき、iOSと同じ形を作りがちです。つまり、内部にビューを持つWindowGroupです。結果として、空間に浮かぶ平面パネルが出来上がります。多くのアプリでは、このパネルで十分でしょう。しかし、パネルの周囲に広がる「部屋」こそvisionOSが追加するものであり、その「部屋」がRealityKitの領域なのです。

RealityKitは3D版のSwiftUIではありません。アーキテクチャは次元だけでなく、形そのものが異なります。SwiftUIは、観測システムの上に構築された結果ビルダーDSLを伴う値型のビューツリーです。フレームワークの役割は、現在の状態から次のレンダリングを計算することにあります。一方RealityKitは、仮想エンティティを現実世界の参照点に結びつけるアンカーをルートとするシーングラフを持つエンティティ・コンポーネント・システム（ECS）です。フレームワークの役割は、ユーザーや世界が動き回る中で3Dシーンを維持することにあります。同一のSwiftプロジェクトで両方を同時に使う場合もあり、両者の境界こそ、空間設計の誤りが最も発生しやすい場所となります。

本記事では、空間的なメンタルモデルを順に追っていきます。SwiftUIのウィンドウとモデルが異なる5つの具体的な側面、そして「どのフレームワークが正解か」というルーティングの問いです。

TL;DR

• RealityKitはエンティティ・コンポーネント・システム（ECS）です。エンティティはノード、コンポーネントはノードに付与される型付きデータ、システムは特定のコンポーネント組み合わせを持つエンティティに対してロジックを実行する仕組みとなります。
• アンカーは仮想エンティティを現実世界の参照点に結びつけます。RealityKitはAnchoringComponent.Target（.world、.head、.hand(_:location:)、.plane(...)、.image(...)、.referenceObject(...)）を通じてアンカーターゲットを公開します。visionOSでは、ARKitがアンカー更新ストリームを通じて報告するアンカー構造体（WorldAnchor、HandAnchor、ImageAnchor、ObjectAnchor、PlaneAnchor）を裏側で供給します。
• 3Dシーンはビューツリーではありません。レンダーループは連続的で、シーングラフは時間とともに変化し、レンダリング層は差分ベースではなくGPU駆動（内部的にはMetal）です。
• RealityViewはSwiftUIへの橋渡し役です。RealityKitのシーンをSwiftUIのビューツリー内に配置します。境界は一方向であり、SwiftUIがRealityKitをホストする側で、その逆ではありません。
• ルーティングのルール：ユーザーがウィンドウを求めるならSwiftUIで出荷します。ユーザーが部屋を求めるならRealityKitで出荷します。両方が必要なアプリは、SwiftUIウィンドウ内にRealityViewを配置し、両者が明示的に連携することを受け入れます。

SwiftUIのウィンドウとの5つの違い

パネルの外側に何かを配置した瞬間、形が変わります。重要な違いは5つあります。

1. View-Body-StateではなくEntity-Component-System

SwiftUIのビューは、body計算プロパティとプロパティラッパーが支える状態を持つ値型です。¹ 状態が変化するとフレームワークがbodyを再実行し、その差分がレンダラーに渡されます。

RealityKitのエンティティはシーングラフ内に存在する参照型オブジェクトです。コンポーネントはエンティティに付与される型付き構造体です（ModelComponent、Transform、CollisionComponent、PhysicsBodyComponent、自分で定義するカスタムComponent型など）。² システムはSystemプロトコルに準拠する型です。フレームワークは登録された各システムをフレームごとに1回実行し、System.update(context:)（通常は構造体上でmutating）が、クエリにマッチするエンティティのコンポーネントをシステムが読み書きする場所となります。

import RealityKit

let cube = Entity()
cube.components.set(ModelComponent(
    mesh: .generateBox(size: 0.1),
    materials: [SimpleMaterial(color: .blue, isMetallic: false)]
))
cube.components.set(InputTargetComponent())
cube.components.set(CollisionComponent(shapes: [.generateBox(size: [0.1, 0.1, 0.1])]))

このcubeにbodyはありません。cubeが持つのはコンポーネントのセットです。InputTargetComponentとCollisionComponentを追加することで、cubeはジェスチャーに反応するようになります。これらを取り除けば、ジェスチャーは背後のエンティティへ素通りします。PhysicsBodyComponentを追加すればcubeは重力で落下します。取り除けば浮かんだままです。コンポーネントの構成こそが、エンティティの振る舞いを決定するのです。

メンタルシフト：SwiftUIでは、状態の関数として画面に何があるべきかを記述します。RealityKitでは、エンティティが何であるか（そのコンポーネント）を記述し、何が起こるかはシステムに任せます。

2. 座標ではなくアンカー

SwiftUIビューの座標系はウィンドウです。位置0,0は左上隅で、位置はポイント単位、ビューのフレームがその空間となります。ウィンドウが宇宙です。

RealityKitシーンの座標系はアンカーに依存します。アンカリング層には2つの面があります。RealityKitのAnchorEntity（AnchoringComponent.Targetによって駆動される）はエンティティを配置する先であり、ARKitのアンカー構造体は、システムがターゲットを現実世界と同期させるために使う裏側のデータです。³

AnchorEntityまたはAnchoringComponent内部で利用するRealityKitのアンカリングターゲットは以下の通りです。

• .world(transform:)：transformで定義される現実世界空間内のポイント
• .head：ユーザーの頭部姿勢にロックされ、エンティティがユーザーの視線に追従する
• .hand(_:location:)：特定の手の関節（手のひら、指先、手首など）にロックされる
• .plane(...)：検出された水平または垂直の表面（テーブル、壁、床）にロックされる
• .image(...) / .referenceImage(...)：環境内で認識された2D画像にロックされる
• .referenceObject(...)：認識された現実世界の3Dオブジェクトにロックされる

visionOSでは、ARKitがARKitSessionのアンカー更新プロバイダーを通じて、WorldAnchor、HandAnchor、ImageAnchor、ObjectAnchor、PlaneAnchor構造体として裏側のアンカーデータを供給します。（ボディトラッキングはAppleのボディトラッキング面ではiOS/iPadOS限定であり、visionOSはRealityKitのアンカリングターゲットとして.bodyを公開しません。）

アンカーこそ、シーンを「リアル」にするものです。ユーザーのテーブルに対して.planeターゲット上に配置された仮想チェスボードは、ユーザーが周囲を歩いてもテーブル上に留まり続けます。一方、.headターゲットを基準とした固定座標に配置されたチェスボードは、ユーザーの頭に追従し、まるで幻覚のように感じられるでしょう。

メンタルシフト：位置は数値ではありません。位置とはアンカーが何で、エンティティがアンカーに対してどこにあるかということです。妥当なアンカーを持たない仮想オブジェクトは幻覚であり、アンカーこそがオブジェクトが部屋に属していることをユーザーに伝えるものとなります。

3. 差分ベースではなく連続的なレンダーループ

SwiftUIは状態が変化したときにレンダリングします。再レンダリングが必要な時期はフレームワークが判断し、最小限のツリー変更を計算するのです。レンダリングの合間、画面は静的です。

RealityKitはフレームベースのシミュレーションとレンダリングループを駆動します。物理、アニメーションシステム、入力ハンドラーがエンティティのトランスフォームとコンポーネント値を更新するにつれてシーングラフは時間とともに変化し、レンダラー（Metalベース）はフレームごとにアクティブなシーンを描画します。フレーム単位のロジックはSystem.update(context:)に置きます。このフックが、毎ティック単位でシーンを変更するためのフレームワークからの招待状なのです。⁴

メンタルシフト：時間はシーンの一部です。1回だけ実行されるSwiftUIのビューbodyで問題ありません。しかしRealityKitのエンティティは、フレームN+1、N+2、N+3で何が起こるかを考慮する必要があります。カスタムSystemのupdate(context:)メソッドは、フレーム単位のロジックを書く場所です。update内部で変更するComponentの値は、次のパスでレンダラーが読み取るものとなります。

4. RealityViewは一方向の橋渡し

SwiftUIビューは他のSwiftUIビューを構成します。RealityKitエンティティは他のRealityKitエンティティを構成します。両者の境界がRealityViewです。RealityKitシーンをホストするSwiftUIビュー型のことです。⁵

import SwiftUI
import RealityKit

struct ContentView: View {
    var body: some View {
        RealityView { content in
            // Build the scene
            let cube = Entity()
            cube.components.set(ModelComponent(
                mesh: .generateBox(size: 0.1),
                materials: [SimpleMaterial(color: .blue, isMetallic: false)]
            ))
            content.add(cube)
        } update: { content in
            // Mutate the scene in response to SwiftUI state changes
        }
    }
}

makeクロージャはビューが最初に表示されるとき1回だけ実行されます。updateクロージャはビューが依存するSwiftUI状態が変化するたびに実行されます。両クロージャ内では、contentパラメータを通じてRealityKitシーンにアクセスでき、エンティティの追加、トランスフォームの変更、システムの登録が可能です。

境界は一方向です。SwiftUIがRealityKitをホストします。RealityKitはSwiftUIをホストしません。エンティティの「内部」にSwiftUIビューを置き、SwiftUIサブビューが親内部でレンダリングされるのと同じように3Dシーンの一部としてレンダリングされることは期待できないのです。例外はアタッチメント（RealityViewのattachments:パラメータ内）です。名前付きSwiftUIビューを宣言し、ViewAttachmentEntity値として取得して、他のエンティティと同じように3Dシーン内で位置付け・スケーリングできます。⁵ アタッチメントはエンティティ内に埋め込まれたSwiftUIビューではなく、レンダラーが3D空間に配置できるエンティティとしてラップされた2D SwiftUIサーフェスです。デフォルトでは固定の向きを保持しますが、装着者の方を向かせたい場合はアタッチメントエンティティにBillboardComponentを付与してください。

5. 3Dにおけるジェスチャーは異なる

SwiftUIのジェスチャー（.onTapGesture、DragGestureなど）はスクリーン空間で動作します。指がビューに対してどこにあるかをシステムが把握しており、フレームワークは2Dでのヒットテストに基づいてディスパッチします。

RealityKitのジェスチャーはシーン空間で動作します。⁶ システムはユーザーがどこを見ているか（視線レイ）、ユーザーの手がどこにあるか（ハンドトラッキングの関節）、そして視線とタップが交差するエンティティを把握しています。ディスパッチモデルは「ユーザーがこのエンティティを見てピンチした」というもので、タップに相当します。

エンティティがジェスチャーを受け取るには、InputTargetComponentと、ヒットテストジオメトリを定義するCollisionComponentが必要です。InputTargetComponentがなければ、エンティティはジェスチャーシステムから見えません。CollisionComponentがなければ、ジェスチャーシステムにはヒットテスト対象の形状がありません。両方が揃っている必要があるのです。

メンタルシフト：ジェスチャーターゲットはスクリーン領域ではありません。ジェスチャーターゲットは入力に明示的にオプトインした3Dエンティティです。シーンの残りは「ユーザーが透視できる装飾」となります。

SwiftUIで十分なとき

一般的なvisionOSアプリにRealityKitは不要です。SwiftUI単独が正解となる3つのパターンは以下の通りです。

空間コンテンツのないウィンドウ形状アプリ。 瞑想タイマー、ノートブック、設定パネル、チャットインターフェース。アプリは2Dアフォーダンスを通じて読んだり操作したりする情報そのものです。WindowGroupに入れて平面のままにしておくのが正解です。visionOSはSwiftUIウィンドウをシステムクロームを伴う浮遊するガラスパネルとして扱うため、RealityKitの行を1行も書かずにユーザーに快適な閲覧体験を提供できます。

空間内で平面パネルを構成するマルチウィンドウアプリ。 エディター、ターミナル、ドキュメントのために別々のウィンドウを持つコードエディター。ユーザーはウィンドウを3D空間に配置したい（左、右、後方など）と望みますが、各ウィンドウ自体はSwiftUIビューです。3D配置はOSの仕事であり、パネルは平面のままです。

ドキュメントビューワー、フォトギャラリー、ビデオプレーヤー。 ユーザーがパネルを通じて消費するコンテンツです。パネルがレンダリングサーフェスであり、3次元目は単に部屋におけるパネルの空間的位置にすぎません。

ルール：コンテンツが2D（テキスト、画像、ビデオ、コントロール）なら、正解のフレームワークはSwiftUIです。3次元目はパネルの位置を表すもので、内部に何がレンダリングされるかではないのです。

RealityKitが必要なとき

SwiftUIでは不十分なケースを挙げます。

ユーザーが歩いて回り込める3Dコンテンツ。 ユーザーのテーブル上の仮想オブジェクト（モデルカー、彫刻、建物など）。オブジェクトには体積があり、ユーザーは周りを移動でき、オブジェクトは部屋と正しくオクルージョンするべきです。正解のフレームワークはRealityKitで、.planeターゲットにアンカリングします。

部屋に応答する空間UI。 現実世界のキーボード上に浮かぶボタン、現実世界のオブジェクトに付随する注釈、実際の壁に沿って配置された仮想メジャー。UIの位置はウィンドウの座標空間ではなく、世界ジオメトリによって決まります。RealityKitのアンカーがバインディングを担当し、RealityView内のSwiftUIアタッチメントが2Dアフォーダンスを提供します。

連続的な空間シミュレーション。 鳥の群れ、床を転がるボール、流体シミュレーション、シーンの状態が時間とともに変化するあらゆるもの。連続的なレンダーループが正解のツールです。SwiftUIの差分ベースレンダラーでは、フレーム落ちかバッテリー消費のいずれかが発生してしまうでしょう。

ハンドトラッキングインタラクション。 ピンチでつかむ、両手でのスケーリング、空中での描画。入力モデルにはARKitのHandTrackingProvider（HandAnchor更新付き）と.hand(_:location:)アンカーターゲットが必要です。SwiftUIはこの面を公開していません。

ボディトラッキングAR。 ユーザーの姿勢を仮想キャラクターにミラーリングする、フィットネスアプリのためにユーザーの体を追跡する、現実世界のオブジェクトを認識する。キャプチャと推論はARKit（RealityKitの低レベルコンパニオン）で行われ、RealityKitが結果をレンダリングします。

ルール：コンテンツが3Dで部屋に存在する（体積を持つ、アンカーされている、シミュレートされている、または手で操作される）なら、正解のフレームワークはRealityKitです。SwiftUIはその周囲のクロームとなります。

構成パターン

ほとんどの非自明なvisionOSアプリは両方を使うことになります。うまく出荷できるパターンは以下の通りです。

1. アプリのクローム（設定、ナビゲーション、リスト、フォーム、インスペクタパネル）はSwiftUIウィンドウに配置する。
2. 空間シーン（ユーザーが操作する体積コンテンツ）は独自のウィンドウまたはボリューム内のRealityViewに配置する。
3. 両者はSwiftUI状態を介して通信する。SwiftUIパネル内のボタンが@Stateブール値をトグルし、RealityViewのupdate:クロージャがそのブール値を読み取ってシーン内のエンティティを変更する。
4. SwiftUIへ伝える必要のあるRealityKit側の状態変化は、RealityViewのmake:クロージャが登録するコールバック（シーンのイベントパブリッシャー上でのsubscribe(to:)）を経由する。⁷

struct GalleryView: View {
    @State private var selectedSculpture: SculptureID?

    var body: some View {
        HStack {
            // SwiftUI side: list of sculptures
            List(allSculptures) { sculpture in
                Button(sculpture.name) {
                    selectedSculpture = sculpture.id
                }
            }
            .frame(width: 300)

            // RealityKit side: 3D rendering of the selected sculpture
            RealityView { content in
                // Build initial scene
            } update: { content in
                guard let id = selectedSculpture else {
                    content.entities.removeAll()
                    return
                }
                // Mutate scene to show the selected sculpture
                presentSculpture(id, in: content)
            }
        }
    }
}

この分離は、どのフレームワークがどの仕事を担うかについて率直です。SwiftUIはリスト、ボタン、レイアウト、状態を担当します。RealityKitは3Dレンダリング、エンティティ、連続シミュレーションを担当します。状態は単一の@State値として境界を越え、どちらのフレームワークも他方の内部に手を伸ばすことはありません。

自分のスタックで違うやり方をするなら

空間シーンを出荷した経験があれば認識しやすくなる3つのパターンを紹介します。

アンカーが先、エンティティは後。 機能を設計するとき、ジオメトリの前にアンカーを決めます。ユーザーの手にアンカーされた仮想楽器は、テーブル上の.planeターゲットにアンカーされた同じ楽器とは別の製品です。アンカーがオブジェクトとユーザーの関係を決定し、ジオメトリは実装の詳細に過ぎません。

サブクラスではなくコンポーネント。 Entityをサブクラス化してChessPiece: Entityのようなドメイン型を構築したくなります。しかし、構成パターンは継承に毎回勝ります。チェスの駒は、ChessPieceComponent（カスタムデータ：色、種類、位置）、ModelComponent（3Dメッシュ）、InputTargetComponent、CollisionComponentを持つEntityなのです。新しい振る舞いは新しいコンポーネントであり、新しいサブクラスではありません。

横断的ロジックにはシステムを。 10個のエンティティが同じ振る舞い（重力、衝突応答、オーディオ減衰、ジェスチャー状態）を必要とするとき、関連コンポーネントに対して動作するSystemを書きます。システムは該当するすべてのエンティティに対してフレームごとに1回実行されます。代替案（各エンティティにロジックを置く）は、ECSパターンが回避するために発明されたn倍nフレームのバグを生み出します。

RealityViewが間違った答えとなるとき

RealityViewに手を伸ばすのが間違いとなるケースをいくつか挙げます。

インタラクションのない単一の3D画像。 静的な3DロゴまたはプロダクトレンダリングならSwiftUIのModel3Dビューを使います。⁸ Model3Dは「USDZをロードして表示する」ための安価な経路であり、RealityViewは構築・変更するシーンのためのものです。

シンプルなARオーバーレイを持つiOSアプリ。 AR体験が大きなiOSアプリ内の機能である場合、ARKitのARView（古いサーフェス）またはRealityKitのiOS側ARView統合が正解となることが多くあります。RealityViewはSwiftおよびSwiftUIネイティブで、SwiftUI内によく馴染みます。一方、アプリの残りがUIKitであれば、古いARViewワークフローの方がシンプルな場合もあるのです。

パネル上での2D描画。 ホワイトボード、写真注釈ツール、平面シェイプエディター。正解のツールはCanvas（SwiftUIのMetalベース描画サーフェス）またはMetalViewです。3D空間で構築していないなら、RealityViewはオーバースペックとなります。

visionOS 2+で出荷するアプリにとってこのパターンが意味するもの

3つの要点があります。

1. RealityKitとSwiftUIは構成可能であり、融合するものではありません。 ウィンドウ形状のクロームと2DアフォーダンスにはSwiftUI、部屋形状の3DコンテンツにはRealityKitを使います。境界はRealityViewであり、その境界は一方向です。

2. メンタルモデルはECSとアンカーの組み合わせです。 エンティティはそれを構成するもので決まります。アンカーはエンティティがユーザーの実空間とどう関わるかを決定します。ペア（コンポーネント、アンカー）が設計単位なのです。

3. レンダーループは連続的です。 時間はシーンの一部です。フレーム単位のロジックはSystem.update(context:)に、状態変化単位のロジックはRealityView.update:に置きます。2つのレイヤーを混在させること（フレーム単位のロジックをSwiftUIのbodyに書き、状態駆動ロジックをSystem.updateに書くこと）は、最も一般的なアーキテクチャ上の誤りです。

Apple Ecosystemクラスター全体は以下の通りです。Apple Intelligenceのための型付きApp Intents、クロスLLMエージェントのためのMCPサーバー、両者間のルーティング問題、オンデバイスLLMとToolプロトコルのためのFoundation Models、iOSロックスクリーンの状態マシンのためのLive Activities、Apple WatchにおけるwatchOSランタイム契約、フレームワーク基盤のためのSwiftUI内部、ビジュアル層のためのLiquid Glassパターン、クロスデバイス展開のためのマルチプラットフォーム出荷。ハブはApple Ecosystem Seriesにあります。AIエージェントとiOSの広範な文脈については、iOS Agent Developmentガイドをご覧ください。

FAQ

RealityKitはvisionOSにおけるSwiftUIの代替ですか？

いいえ。RealityKitとSwiftUIは構成されるものです。SwiftUIは2Dウィンドウ、コントロール、クロームを担当し、RealityKitは現実世界の参照点にアンカーされた3Dシーンを担当します。ほとんどの非自明なvisionOSアプリは両方を使い、RealityViewがRealityKitシーンをSwiftUIビューツリー内に配置する橋渡し役となります。

RealityViewとModel3Dはいつ使い分けるべきですか？

単一の静的3Dアセット（USDZファイル、単一のプロダクトレンダリング）を表示するならModel3Dを使います。3Dシーンを時間とともに構築または変更する（複数エンティティ、物理、ジェスチャー、ハンドトラッキング、アンカー付きコンテンツ）ならRealityViewを使います。Model3Dは安価な経路で、RealityViewは完全なECSサーフェスとなります。

RealityKitにおけるEntityとComponentの違いは？

エンティティはシーングラフ内のノードです。コンポーネントはノードに付与される型付きデータです。ModelComponentはエンティティにメッシュを与え、InputTargetComponentはジェスチャー対象にし、CollisionComponentはヒットテストジオメトリを定義し、PhysicsBodyComponentは重力に応答するようにします。自分で定義するカスタムComponent型はドメインデータを保持します。振る舞いは継承よりも構成によって決まり、エンティティの振る舞いはそのコンポーネントの総和なのです。

アンカーとは何で、なぜ重要なのですか？

アンカーは仮想コンテンツを現実世界の参照点に結びつけます。ユーザーの頭、手、検出された表面、認識された画像、認識されたオブジェクト、または永続的な世界ポイントです。アンカーがエンティティとユーザーの関係を決定します。.planeターゲット（テーブル）上の仮想オブジェクトは、ユーザーが歩き回ってもその場に留まりますが、.headターゲット上の仮想オブジェクトはユーザーの頭に追従します。正しいアンカーを選ぶことが、空間機能における最初の設計判断となるのです。

RealityKitはvisionOSだけでなくiOSでも動作しますか？

はい。RealityKitはiOS、iPadOS、macOS、visionOSで出荷されています。ARKit駆動のAR体験はRealityKitのiOSサーフェスを使用します。visionOSサーフェスは、iOSが公開していない空間特有のアンカー型（頭、手、世界）を追加していますが、コアのECSパターンは共通です。

References