RealityKit i przestrzenny model myślowy

SwiftUI na visionOS daje okno w przestrzeni 3D. RealityKit daje resztę pomieszczenia. Różnica leży w modelu myślowym, a model myślowy to architektura.

Programista SwiftUI, który po raz pierwszy zaczyna pracę z visionOS, zazwyczaj buduje te same struktury, które tworzyłby na iOS: WindowGroup z widokami w środku. Rezultatem jest płaski panel unoszący się w przestrzeni. Panel sprawdza się w wielu aplikacjach. Pomieszczenie wokół panelu to to, co dodaje visionOS, a pomieszczenie należy do terytorium RealityKit.

RealityKit to nie SwiftUI w 3D. Architektura różni się kształtem, a nie tylko wymiarem. SwiftUI jest drzewem widoków typu wartościowego z DSL opartym na result builder, zbudowanym na systemie obserwacji; zadaniem frameworka jest obliczenie kolejnego renderowania na podstawie aktualnego stanu. RealityKit to system encja-komponent-system (ECS) z grafem sceny zakorzenionym w kotwicach, które wiążą wirtualne encje z punktami odniesienia w świecie rzeczywistym; zadaniem frameworka jest utrzymywanie sceny 3D, gdy użytkownik i świat poruszają się wokół niej. Ten sam projekt Swift może wykorzystywać oba jednocześnie, a granica między nimi to miejsce, w którym popełnia się większość błędów projektowania przestrzennego.

Niniejszy wpis omawia przestrzenny model myślowy. Pięć konkretnych sposobów, w jakie ten model różni się od okna SwiftUI, oraz kwestię routingu — kiedy każdy z frameworków jest właściwą odpowiedzią.

TL;DR

• RealityKit to system encja-komponent-system (ECS). Encja to węzeł; komponenty to typowane dane dołączone do węzła; systemy uruchamiają logikę na encjach posiadających określone kombinacje komponentów.
• Kotwice wiążą wirtualne encje z punktami odniesienia w świecie rzeczywistym. RealityKit udostępnia cele kotwiczenia poprzez AnchoringComponent.Target (.world, .head, .hand(_:location:), .plane(...), .image(...), .referenceObject(...)). Na visionOS ARKit dostarcza struktury kotwic stanowiące podstawę (WorldAnchor, HandAnchor, ImageAnchor, ObjectAnchor, PlaneAnchor), które ARKit raportuje poprzez strumienie aktualizacji kotwic.
• Scena 3D nie jest drzewem widoków. Pętla renderowania jest ciągła, graf sceny mutuje w czasie, a warstwa renderowania jest sterowana GPU (z Metalem pod spodem), a nie oparta na różnicach.
• RealityView to most SwiftUI. Umieszcza scenę RealityKit wewnątrz drzewa widoków SwiftUI; granica jest jednokierunkowa (SwiftUI hostuje RealityKit, ale nie odwrotnie).
• Reguła routingu: jeśli użytkownik chce okna, należy dostarczyć SwiftUI. Jeśli użytkownik chce pomieszczenia, należy dostarczyć RealityKit. Aplikacje, które potrzebują obu, umieszczają RealityView wewnątrz okna SwiftUI i akceptują, że obie połowy koordynują się jawnie.

Pięć różnic w stosunku do okna SwiftUI

Kształt zmienia się w momencie, gdy umieszczasz cokolwiek poza panelem. Pięć różnic ma znaczenie.

1. Encja-komponent-system, a nie widok-body-stan

Widok SwiftUI to typ wartościowy z obliczaną właściwością body i stanem opartym na property wrappers.¹ Framework ponownie uruchamia body, gdy stan się zmienia; różnica trafia do renderera.

Encja RealityKit to obiekt typu referencyjnego, który znajduje się w grafie sceny. Komponenty to typowane struktury dołączone do encji (ModelComponent, Transform, CollisionComponent, PhysicsBodyComponent, niestandardowe typy Component, które definiujesz).² Systemy to typy zgodne z protokołem System; framework uruchamia każdy zarejestrowany system raz na klatkę, a System.update(context:) (zazwyczaj mutating na strukturze) to miejsce, gdzie system odczytuje i zapisuje komponenty na encjach pasujących do jego zapytania.

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])]))

Sześcian nie ma body. Sześcian ma zestaw komponentów. Dodanie InputTargetComponent i CollisionComponent sprawia, że sześcian reaguje na gesty; po ich usunięciu gesty przechodzą prosto do encji za nim. Dodanie PhysicsBodyComponent sprawia, że sześcian opada pod wpływem grawitacji; po jego usunięciu sześcian unosi się. Kompozycja komponentów określa zachowanie encji.

Zmiana mentalna: w SwiftUI opisujesz to, co powinno być na ekranie, jako funkcję stanu. W RealityKit opisujesz, czym encja jest (jej komponenty), a systemom pozostawiasz decyzję, co się z nią dzieje.

2. Kotwice, a nie współrzędne

Układ współrzędnych widoku SwiftUI to okno. Pozycja 0,0 to lewy górny róg; pozycje są w punktach; ramka widoku to jego przestrzeń. Okno jest wszechświatem.

Układ współrzędnych sceny RealityKit zależy od jej kotwicy. Warstwa kotwiczenia ma dwie strony. AnchorEntity w RealityKit (sterowane przez AnchoringComponent.Target) to to, na czym umieszczasz encję; struktury kotwic ARKit to dane stanowiące podstawę, których system używa do utrzymania synchronizacji celu ze światem rzeczywistym.³

Cele kotwiczenia RealityKit, po które sięgasz wewnątrz AnchorEntity lub AnchoringComponent, to:

• .world(transform:): punkt w przestrzeni świata rzeczywistego zdefiniowany przez transformację
• .head: zablokowany do pozycji głowy użytkownika; encja podąża za wzrokiem użytkownika
• .hand(_:location:): zablokowany do konkretnego stawu dłoni (dłoń, opuszek palca, nadgarstek itp.)
• .plane(...): zablokowany do wykrytej powierzchni poziomej lub pionowej (stół, ściana, podłoga)
• .image(...) / .referenceImage(...): zablokowany do rozpoznanego obrazu 2D w otoczeniu
• .referenceObject(...): zablokowany do rozpoznanego rzeczywistego obiektu 3D

Na visionOS ARKit dostarcza dane kotwic stanowiących podstawę poprzez struktury WorldAnchor, HandAnchor, ImageAnchor, ObjectAnchor i PlaneAnchor dostarczane przez dostawców aktualizacji kotwic ARKitSession. (Śledzenie ciała jest dostępne wyłącznie na iOS/iPadOS w ramach interfejsu śledzenia ciała Apple; visionOS nie udostępnia .body jako celu kotwiczenia RealityKit.)

Kotwica to to, co czyni scenę „rzeczywistą”. Wirtualna szachownica umieszczona na celu .plane dla stołu użytkownika pozostaje na stole, gdy użytkownik wokół niego chodzi; szachownica umieszczona na stałych współrzędnych względem celu .head podąża za głową użytkownika i sprawia wrażenie halucynacji.

Zmiana mentalna: pozycja to nie liczba. Pozycja to czym jest kotwica i gdzie znajduje się encja względem kotwicy. Wirtualny obiekt bez sensownej kotwicy to halucynacja; kotwica to to, co mówi użytkownikowi, że obiekt należy do pomieszczenia.

3. Ciągła pętla renderowania, a nie oparta na różnicach

SwiftUI renderuje, gdy zmienia się stan. Framework decyduje, kiedy potrzebne jest ponowne renderowanie, i oblicza minimalną zmianę drzewa. Pomiędzy renderowaniami ekran jest statyczny.

RealityKit napędza pętlę symulacji i renderowania opartą na klatkach. Graf sceny mutuje w czasie, gdy systemy fizyki, animacji i obsługi wejścia aktualizują transformacje encji i wartości komponentów, a renderer (oparty na Metalu) rysuje aktywną scenę w każdej klatce. Logika dla każdej klatki znajduje się w System.update(context:); ten hook to zaproszenie frameworka do mutowania sceny w każdym tyknięciu.⁴

Zmiana mentalna: czas jest częścią sceny. Body widoku SwiftUI uruchamiane raz jest w porządku; encja RealityKit musi rozważyć, co dzieje się w klatce N+1, N+2, N+3. Metoda update(context:) na niestandardowym System to miejsce, gdzie zapisuje się logikę dla każdej klatki; wartość Component, którą mutujesz wewnątrz update, to to, co renderer odczytuje w następnym przebiegu.

4. RealityView to most, w jednym kierunku

Widoki SwiftUI komponują inne widoki SwiftUI. Encje RealityKit komponują inne encje RealityKit. Granicą między nimi jest RealityView, typ widoku SwiftUI, który hostuje scenę RealityKit.⁵

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
        }
    }
}

Domknięcie make uruchamia się raz, gdy widok pojawia się po raz pierwszy. Domknięcie update uruchamia się za każdym razem, gdy zmienia się stan SwiftUI, od którego zależy widok. Wewnątrz obu domknięć ma się dostęp do sceny RealityKit poprzez parametr content; dodaje się encje, mutuje transformacje, rejestruje systemy.

Granica jest jednokierunkowa. SwiftUI hostuje RealityKit. RealityKit nie hostuje SwiftUI; nie można umieścić widoku SwiftUI „wewnątrz” encji i oczekiwać, że będzie się renderował jako część sceny 3D w taki sam sposób, jak widok podrzędny SwiftUI renderuje się wewnątrz rodzica. Wyjątkiem są załączniki (w parametrze attachments: RealityView): deklaruje się nazwane widoki SwiftUI, pobiera je jako wartości ViewAttachmentEntity, a następnie pozycjonuje i skaluje wewnątrz sceny 3D jak każdą inną encję.⁵ Załączniki to nie osadzone widoki SwiftUI wewnątrz encji; to powierzchnie SwiftUI 2D opakowane jako encje, które renderer może umieścić w 3D. Domyślnie utrzymują stałą orientację; jeśli mają być zwrócone w stronę noszącego, do encji załącznika należy dołączyć BillboardComponent.

5. Gesty w 3D są inne

Gesty SwiftUI (.onTapGesture, DragGesture itp.) działają w przestrzeni ekranu. System wie, gdzie znajduje się palec względem widoku; framework dyspozycjonuje na podstawie hit-testingu w 2D.

Gesty RealityKit działają w przestrzeni sceny.⁶ System wie, gdzie użytkownik patrzy (promień wzroku), gdzie znajdują się dłonie użytkownika (stawy śledzone przez hand tracking) oraz z którą encją przecina się wzrok plus kliknięcie. Model dyspozycji to „użytkownik spojrzał na tę encję i ścisnął palce”; odpowiednik tapnięcia.

Aby encja mogła odbierać gesty, potrzebuje InputTargetComponent i CollisionComponent, który definiuje geometrię hit-testu. Bez InputTargetComponent encja jest niewidoczna dla systemu gestów; bez CollisionComponent system gestów nie ma kształtu, na którym można by wykonać hit-test. Oba muszą być obecne.

Zmiana mentalna: cele gestów to nie obszary ekranu. Cele gestów to encje 3D, które jawnie zdecydowały się na wejście. Reszta sceny to „dekoracja, przez którą użytkownik może patrzeć”.

Kiedy SwiftUI wystarcza

Typowa aplikacja visionOS nie potrzebuje RealityKit. Trzy wzorce, w których sam SwiftUI jest właściwą odpowiedzią:

Aplikacje w kształcie okna bez treści przestrzennych. Timer medytacji, notatnik, panel ustawień, interfejs czatu. Aplikacja to informacje, które się czyta lub z którymi się wchodzi w interakcję poprzez afordancje 2D. Umieszczenie jej w WindowGroup i utrzymanie w formie płaskiej to słuszna decyzja. visionOS traktuje okna SwiftUI jako pływające szklane panele z chromem systemowym; użytkownik otrzymuje komfortowe doświadczenie czytania bez napisania ani jednej linii RealityKit.

Aplikacje wielookienkowe komponujące płaskie panele w przestrzeni. Edytor kodu z osobnymi oknami dla edytora, terminala i dokumentacji. Użytkownik chce, by okna były rozmieszczone w przestrzeni 3D (po lewej, po prawej, z tyłu), ale każde okno samo w sobie jest widokiem SwiftUI. Rozmieszczenie 3D to zadanie systemu operacyjnego; panele są płaskie.

Przeglądarki dokumentacji, galerie zdjęć, odtwarzacze wideo. Treści, które użytkownik konsumuje przez panel. Panel to powierzchnia renderująca; trzeci wymiar to po prostu przestrzenna pozycja panelu w pomieszczeniu.

Reguła: jeśli treść jest 2D (tekst, obrazy, wideo, kontrolki), właściwym frameworkiem jest SwiftUI. Trzeci wymiar to miejsce, w którym pozycjonowany jest panel, a nie to, co jest w nim renderowane.

Kiedy RealityKit jest wymagany

Przypadki, w których SwiftUI nie wystarcza:

Treść 3D, wokół której użytkownik może chodzić. Wirtualny obiekt na stole użytkownika (model samochodu, rzeźba, budynek). Obiekt ma objętość; użytkownik może wokół niego chodzić; obiekt powinien poprawnie zasłaniać się z otoczeniem. Właściwym frameworkiem jest RealityKit, zakotwiczony w celu .plane.

Przestrzenne UI reagujące na pomieszczenie. Przyciski unoszące się nad rzeczywistą klawiaturą, adnotacje dołączone do rzeczywistego obiektu, wirtualna miarka rozłożona wzdłuż prawdziwej ściany. Pozycja UI jest określana przez geometrię świata, a nie przez przestrzeń współrzędnych okna. Kotwice RealityKit dokonują wiązania; załączniki SwiftUI wewnątrz RealityView zapewniają afordancje 2D.

Ciągła symulacja przestrzenna. Stado ptaków, piłka tocząca się po podłodze, symulacja płynów, cokolwiek, gdzie stan sceny ewoluuje w czasie. Ciągła pętla renderowania to właściwe narzędzie; renderer SwiftUI oparty na różnicach albo gubiłby klatki, albo wypalał baterię.

Interakcje śledzenia dłoni. Ściskanie palców, by chwycić, skalowanie dwiema rękami, rysowanie w powietrzu. Model wejścia wymaga HandTrackingProvider z ARKit (z aktualizacjami HandAnchor) plus celu kotwicy .hand(_:location:); SwiftUI nie udostępnia tej powierzchni.

AR ze śledzeniem ciała. Odzwierciedlanie pozy użytkownika na wirtualnej postaci, śledzenie ciała użytkownika w aplikacji fitness, rozpoznawanie obiektów świata rzeczywistego. Przechwytywanie i wnioskowanie odbywają się w ARKit (towarzyszu RealityKit niższego poziomu); RealityKit renderuje wynik.

Reguła: jeśli treść jest 3D i żyje w pomieszczeniu (objętościowa, zakotwiczona, symulowana lub sterowana dłońmi), właściwym frameworkiem jest RealityKit. SwiftUI to chrom wokół niej.

Wzorzec kompozycji

Większość nietrywialnych aplikacji visionOS ostatecznie wykorzystuje oba. Wzorzec, który dobrze się sprawdza w produkcji:

1. Chrom aplikacji (ustawienia, nawigacja, listy, formularze, panele inspektora) żyje w oknach SwiftUI.
2. Scena przestrzenna (treść objętościowa, którą użytkownik manipuluje) żyje w RealityView wewnątrz własnego okna lub objętości.
3. Oba komunikują się poprzez stan SwiftUI. Przycisk w panelu SwiftUI przełącza wartość boolowską @State; domknięcie update: w RealityView odczytuje wartość boolowską i mutuje encję w scenie.
4. Zmiany stanu po stronie RealityKit, które muszą wyjść na powierzchnię SwiftUI, przechodzą przez callbacki, które domknięcie make: w RealityView rejestruje (subscribe(to:) na publisherze zdarzeń sceny).⁷

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)
            }
        }
    }
}

Podział uczciwie określa, który framework jest właścicielem którego zadania. SwiftUI jest właścicielem listy, przycisków, układu, stanu. RealityKit jest właścicielem renderowania 3D, encji, ciągłej symulacji. Stan przekracza granicę jako pojedyncza wartość @State; żaden framework nie sięga do drugiego.

Co zbudowałbym inaczej w moim stosie

Trzy wzorce, które łatwo rozpoznać po wydaniu sceny przestrzennej:

Najpierw kotwica, potem encja. Projektując funkcję, należy zdecydować o kotwicy przed geometrią. Wirtualny instrument zakotwiczony w dłoni użytkownika to inny produkt niż ten sam instrument zakotwiczony w celu .plane na stole. Kotwica decyduje o relacji użytkownika z obiektem; geometria to szczegół implementacji.

Komponenty, a nie podklasy. Kuszące jest dziedziczenie z Entity w celu zbudowania typów domenowych jak ChessPiece: Entity. Wzorzec kompozycji za każdym razem wygrywa z dziedziczeniem: figura szachowa to Entity z ChessPieceComponent (niestandardowe dane: kolor, typ, pozycja), ModelComponent (siatka 3D), InputTargetComponent i CollisionComponent. Nowe zachowania to nowe komponenty, a nie nowe podklasy.

Systemy dla logiki przekrojowej. Gdy dziesięć encji potrzebuje tego samego zachowania (grawitacja, reakcja na kolizje, tłumienie audio, stan gestu), warto napisać System, który operuje na odpowiednich komponentach. System uruchamia się raz na klatkę dla wszystkich pasujących encji. Alternatywa (umieszczenie logiki na każdej encji) produkuje błąd n-razy-n-klatek, którego unikać miał wzorzec ECS.

Kiedy RealityView jest złą odpowiedzią

Kilka przypadków, w których sięgnięcie po RealityView to zła decyzja:

Pojedynczy obraz 3D, bez interakcji. Statyczne logo 3D lub render produktu. Należy zamiast tego użyć widoku SwiftUI Model3D.⁸ Model3D to tania ścieżka dla „załaduj USDZ i wyświetl”; RealityView jest dla scen, które się buduje i mutuje.

Aplikacje iOS z prostymi nakładkami AR. ARView z ARKit (starsza powierzchnia) lub integracja ARView po stronie iOS w RealityKit jest często słuszną decyzją, gdy doświadczenie AR jest funkcją wewnątrz większej aplikacji iOS. RealityView jest natywny dla Swift i SwiftUI i dobrze żyje wewnątrz SwiftUI; starsze przepływy ARView są czasem prostsze, gdy reszta aplikacji to UIKit.

Rysowanie 2D na panelu. Tablica, narzędzie do adnotacji zdjęć, edytor płaskich kształtów. Właściwym narzędziem jest Canvas (powierzchnia rysowania SwiftUI oparta na Metalu) lub MetalView. RealityView to przesada, jeśli nie buduje się w przestrzeni 3D.

Co ten wzorzec oznacza dla aplikacji wydawanych na visionOS 2+

Trzy wnioski.

1. RealityKit i SwiftUI komponują się; nie zlewają się. Należy używać SwiftUI do chromu w kształcie okna i afordancji 2D; RealityKit do treści 3D w kształcie pomieszczenia. Granicą jest RealityView, a granica jest jednokierunkowa.

2. Model myślowy to ECS plus kotwice. Encja jest tym, z czego się składa. Kotwica decyduje, jak encja odnosi się do rzeczywistej przestrzeni użytkownika. Para (komponenty, kotwica) to jednostka projektowa.

3. Pętla renderowania jest ciągła. Czas jest częścią sceny. Logika dla każdej klatki idzie do System.update(context:); logika dla każdej zmiany stanu idzie do RealityView.update:. Mieszanie dwóch warstw (zapisywanie logiki dla każdej klatki w body SwiftUI, zapisywanie logiki sterowanej stanem w System.update) to najczęstszy błąd architektoniczny.

Pełny klaster Apple Ecosystem: typowane App Intents dla Apple Intelligence; serwery MCP dla agentów cross-LLM; kwestia routingu między nimi; Foundation Models dla LLM na urządzeniu i protokołu Tool; Live Activities dla maszyny stanów ekranu blokady iOS; kontrakt runtime watchOS na Apple Watch; wnętrze SwiftUI dla podłoża frameworka; wzorce Liquid Glass dla warstwy wizualnej; wydawanie wieloplatformowe dla zasięgu między urządzeniami. Hub znajduje się w serii Apple Ecosystem. Szerszy kontekst iOS z agentami AI można znaleźć w przewodniku iOS Agent Development.

FAQ

Czy RealityKit zastępuje SwiftUI na visionOS?

Nie. RealityKit i SwiftUI komponują się ze sobą. SwiftUI obsługuje okna 2D, kontrolki i chrom; RealityKit obsługuje sceny 3D zakotwiczone w punktach odniesienia świata rzeczywistego. Większość nietrywialnych aplikacji visionOS używa obu, z RealityView jako mostem, który umieszcza scenę RealityKit wewnątrz drzewa widoków SwiftUI.

Kiedy używać RealityView, a kiedy Model3D?

Należy używać Model3D do wyświetlania pojedynczego statycznego zasobu 3D (plik USDZ, pojedynczy render produktu). Należy używać RealityView do budowania lub mutowania sceny 3D w czasie (wiele encji, fizyka, gesty, śledzenie dłoni, treści zakotwiczone). Model3D to tania ścieżka; RealityView to pełna powierzchnia ECS.

Jaka jest różnica między Entity a Component w RealityKit?

Encja to węzeł w grafie sceny. Komponent to typowane dane dołączone do węzła. ModelComponent daje encji siatkę; InputTargetComponent sprawia, że jest gotowa na gesty; CollisionComponent definiuje geometrię hit-testu; PhysicsBodyComponent sprawia, że reaguje na grawitację. Niestandardowe typy Component, które definiujesz, przechowują dane domenowe. Zachowanie to kompozycja ponad dziedziczenie: zachowanie encji to suma jej komponentów.

Czym są kotwice i dlaczego mają znaczenie?

Kotwice wiążą wirtualną treść z punktami odniesienia w świecie rzeczywistym: głową użytkownika, dłonią, wykrytą powierzchnią, rozpoznanym obrazem, rozpoznanym obiektem lub trwałym punktem świata. Kotwica decyduje o relacji użytkownika z encją. Wirtualny obiekt na celu .plane (stół) pozostaje na miejscu, gdy użytkownik wokół niego chodzi; wirtualny obiekt na celu .head podąża za głową użytkownika. Wybór odpowiedniej kotwicy to pierwsza decyzja projektowa w funkcji przestrzennej.

Czy RealityKit może działać na iOS, a nie tylko na visionOS?

Tak. RealityKit jest dostępny na iOS, iPadOS, macOS i visionOS. Doświadczenia AR sterowane przez ARKit wykorzystują powierzchnię iOS RealityKit. Powierzchnia visionOS dodaje typy kotwic specyficzne dla przestrzeni (głowa, dłoń, świat), których iOS nie udostępnia; podstawowy wzorzec ECS jest współdzielony.

Źródła