RealityKit Et Le Modèle Mental Spatial

SwiftUI sur visionOS vous offre une fenêtre dans l’espace 3D. RealityKit vous offre le reste de la pièce. La différence, c’est le modèle mental, et le modèle mental, c’est l’architecture.

Un développeur SwiftUI qui aborde visionOS pour la première fois a tendance à construire les mêmes formes qu’il construirait sur iOS : un WindowGroup contenant des vues. Le résultat est un panneau plat flottant dans l’espace. Le panneau convient à beaucoup d’applications. La pièce autour du panneau, c’est ce que visionOS ajoute, et la pièce, c’est le territoire de RealityKit.

RealityKit n’est pas SwiftUI en 3D. L’architecture est différente dans sa forme, pas seulement dans sa dimension. SwiftUI est un arbre de vues à types-valeur avec un DSL à result-builder posé sur un système d’observation ; le travail du framework consiste à calculer le prochain rendu à partir de l’état actuel. RealityKit est un système entité-composant-système (ECS) avec un graphe de scène enraciné dans des ancres qui lient des entités virtuelles à des points de référence du monde réel ; le travail du framework consiste à maintenir une scène 3D pendant que l’utilisateur et le monde se déplacent autour d’elle. Le même projet Swift peut utiliser les deux en même temps, et la frontière entre les deux est l’endroit où se produisent la plupart des erreurs de design spatial.

Ce billet parcourt le modèle mental spatial. Cinq façons concrètes dont le modèle diffère d’une fenêtre SwiftUI, et la question de routage : quand chaque framework est-il la bonne réponse.

TL;DR

• RealityKit est un système entité-composant-système (ECS). Une entité est un nœud ; les composants sont des données typées attachées au nœud ; les systèmes exécutent une logique sur les entités qui possèdent des combinaisons de composants spécifiques.
• Les ancres lient des entités virtuelles à des points de référence du monde réel. RealityKit expose les cibles d’ancrage via AnchoringComponent.Target (.world, .head, .hand(_:location:), .plane(...), .image(...), .referenceObject(...)). Sur visionOS, ARKit fournit les structures d’ancres sous-jacentes (WorldAnchor, HandAnchor, ImageAnchor, ObjectAnchor, PlaneAnchor) qu’ARKit signale à travers des flux de mises à jour d’ancres.
• Une scène 3D n’est pas un arbre de vues. La boucle de rendu est continue, le graphe de scène mute au fil du temps, et la couche de rendu est pilotée par GPU (Metal en dessous) plutôt que basée sur la diffusion (diff).
• RealityView est le pont SwiftUI. Il place une scène RealityKit à l’intérieur d’un arbre de vues SwiftUI ; la frontière est unidirectionnelle (SwiftUI héberge RealityKit, et non l’inverse).
• La règle de routage : si l’utilisateur veut une fenêtre, livrez du SwiftUI. Si l’utilisateur veut la pièce, livrez du RealityKit. Les applications qui ont besoin des deux placent un RealityView à l’intérieur d’une fenêtre SwiftUI et acceptent que les deux moitiés se coordonnent explicitement.

Cinq Différences Avec Une Fenêtre SwiftUI

La forme change dès que vous placez quoi que ce soit en dehors du panneau. Cinq différences comptent.

1. Entité-Composant-Système, Pas Vue-Body-État

Une vue SwiftUI est un type à valeur avec une propriété calculée body et un état soutenu par des property wrappers.¹ Le framework réexécute le body lorsque l’état change ; le diff alimente le moteur de rendu.

Une entité RealityKit est un objet à type-référence qui se trouve dans un graphe de scène. Les composants sont des structures typées attachées aux entités (ModelComponent, Transform, CollisionComponent, PhysicsBodyComponent, ainsi que des types Component personnalisés que vous définissez).² Les systèmes sont des types qui se conforment au protocole System ; le framework exécute chaque système enregistré une fois par frame, et System.update(context:) (typiquement mutating sur une struct) est l’endroit où le système lit et écrit les composants des entités qui correspondent à sa requête.

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

Le cube ne possède pas de body. Le cube possède un ensemble de composants. Ajouter InputTargetComponent et CollisionComponent, c’est ce qui fait que le cube répond aux gestes ; retirez-les et les gestes traversent directement vers l’entité située derrière. Ajouter PhysicsBodyComponent, c’est ce qui fait que le cube tombe sous l’effet de la gravité ; retirez-le et le cube flotte. La composition des composants détermine le comportement de l’entité.

Le changement mental : en SwiftUI, vous décrivez ce qui doit se trouver à l’écran en fonction de l’état. En RealityKit, vous décrivez ce qu’une entité est (ses composants) et vous laissez les systèmes décider de ce qui lui arrive.

2. Des Ancres, Pas Des Coordonnées

Le système de coordonnées d’une vue SwiftUI, c’est la fenêtre. La position 0,0 est le coin supérieur gauche ; les positions sont en points ; le frame de la vue est son espace. La fenêtre est l’univers.

Le système de coordonnées d’une scène RealityKit dépend de son ancre. La couche d’ancrage a deux faces. L’AnchorEntity de RealityKit (pilotée par un AnchoringComponent.Target) est ce sur quoi vous placez une entité ; les structures d’ancres d’ARKit sont les données sous-jacentes que le système utilise pour maintenir la cible synchronisée avec le monde réel.³

Les cibles d’ancrage RealityKit que vous utilisez à l’intérieur d’une AnchorEntity ou d’un AnchoringComponent sont :

• .world(transform:) : un point dans l’espace du monde réel défini par une transformation
• .head : verrouillé sur la pose de la tête de l’utilisateur ; l’entité suit le regard de l’utilisateur
• .hand(_:location:) : verrouillé sur une articulation de main spécifique (paume, bout du doigt, poignet, etc.)
• .plane(...) : verrouillé sur une surface horizontale ou verticale détectée (table, mur, sol)
• .image(...) / .referenceImage(...) : verrouillé sur une image 2D reconnue dans l’environnement
• .referenceObject(...) : verrouillé sur un objet 3D du monde réel reconnu

Sur visionOS, ARKit fournit les données d’ancres sous-jacentes via les structures WorldAnchor, HandAnchor, ImageAnchor, ObjectAnchor et PlaneAnchor, livrées par les fournisseurs de mises à jour d’ancres ARKitSession. (Le suivi du corps est exclusif à iOS/iPadOS sur la surface de body-tracking d’Apple ; visionOS n’expose pas .body comme cible d’ancrage RealityKit.)

L’ancre, c’est ce qui rend la scène « réelle ». Un échiquier virtuel placé sur une cible .plane correspondant à la table de l’utilisateur reste sur la table lorsque l’utilisateur en fait le tour ; un échiquier placé à des coordonnées fixes par rapport à une cible .head suit la tête de l’utilisateur et donne l’impression d’une hallucination.

Le changement mental : la position n’est pas un nombre. La position, c’est quelle est l’ancre, et où se trouve l’entité par rapport à l’ancre. Un objet virtuel sans ancre sensée est une hallucination ; l’ancre, c’est ce qui dit à l’utilisateur que l’objet appartient à la pièce.

3. Boucle De Rendu Continue, Pas Basée Sur Le Diff

SwiftUI effectue le rendu lorsque l’état change. Le framework décide quand un nouveau rendu est nécessaire et calcule le changement minimal de l’arbre. Entre les rendus, l’écran est statique.

RealityKit pilote une boucle de simulation et de rendu basée sur les frames. Le graphe de scène mute au fil du temps à mesure que la physique, les systèmes d’animation et les gestionnaires d’entrée mettent à jour les transformations des entités et les valeurs des composants, et le moteur de rendu (basé sur Metal) dessine la scène active à chaque frame. La logique par frame se trouve dans System.update(context:) ; ce hook est l’invitation du framework à muter la scène à chaque tick.⁴

Le changement mental : le temps fait partie de la scène. Un body de vue SwiftUI qui s’exécute une fois suffit ; une entité RealityKit doit considérer ce qui se passe à la frame N+1, N+2, N+3. La méthode update(context:) sur un System personnalisé est l’endroit où vous écrivez la logique par frame ; la valeur Component que vous mutez à l’intérieur de update est ce que le moteur de rendu lit lors de la passe suivante.

4. RealityView Est Le Pont, Dans Une Seule Direction

Les vues SwiftUI composent d’autres vues SwiftUI. Les entités RealityKit composent d’autres entités RealityKit. La frontière entre les deux est RealityView, un type de vue SwiftUI qui héberge une scène 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
        }
    }
}

La closure make s’exécute une seule fois lors de la première apparition de la vue. La closure update s’exécute chaque fois que l’état SwiftUI dont la vue dépend change. À l’intérieur des deux closures, vous avez accès à la scène RealityKit via le paramètre content ; vous ajoutez des entités, mutez des transformations, enregistrez des systèmes.

La frontière est unidirectionnelle. SwiftUI héberge RealityKit. RealityKit n’héberge pas SwiftUI ; vous ne pouvez pas placer une vue SwiftUI « à l’intérieur » d’une entité et vous attendre à ce qu’elle soit rendue dans la scène 3D comme une sous-vue SwiftUI est rendue à l’intérieur d’un parent. L’exception, ce sont les attachments (dans le paramètre attachments: de RealityView) : vous déclarez des vues SwiftUI nommées, vous les récupérez sous forme de valeurs ViewAttachmentEntity, puis vous les positionnez et les redimensionnez à l’intérieur de la scène 3D comme n’importe quelle autre entité.⁵ Les attachments ne sont pas des vues SwiftUI intégrées à l’intérieur d’une entité ; ce sont des surfaces SwiftUI 2D enveloppées sous forme d’entités que le moteur de rendu peut placer en 3D. Par défaut, ils conservent une orientation fixe ; si vous voulez qu’ils fassent face au porteur, attachez un BillboardComponent à l’entité d’attachment.

5. Les Gestes En 3D Sont Différents

Les gestes SwiftUI (.onTapGesture, DragGesture, etc.) opèrent dans l’espace écran. Le système sait où se trouve le doigt par rapport à la vue ; le framework dispatche selon un test de hit en 2D.

Les gestes RealityKit opèrent dans l’espace de la scène.⁶ Le système sait où l’utilisateur regarde (le rayon du regard), où se trouvent les mains de l’utilisateur (articulations du suivi des mains), et avec quelle entité l’intersection regard + tap se produit. Le modèle de dispatch est : « l’utilisateur a regardé cette entité et a pincé » ; l’équivalent d’un tap.

Pour qu’une entité reçoive des gestes, elle a besoin d’un InputTargetComponent et d’un CollisionComponent qui définit la géométrie de hit-test. Sans InputTargetComponent, l’entité est invisible pour le système de gestes ; sans CollisionComponent, le système de gestes n’a aucune forme contre laquelle effectuer le hit-test. Les deux doivent être présents.

Le changement mental : les cibles de gestes ne sont pas des régions de l’écran. Les cibles de gestes sont des entités 3D qui ont explicitement choisi de recevoir des entrées. Le reste de la scène, c’est « de la décoration que l’utilisateur peut traverser du regard ».

Quand SwiftUI Suffit

Une application visionOS courante n’a pas besoin de RealityKit. Trois patterns où SwiftUI seul est la bonne réponse :

Applications en forme de fenêtre sans contenu spatial. Un minuteur de méditation, un carnet, un panneau de paramètres, une interface de chat. L’application, c’est de l’information que vous lisez ou avec laquelle vous interagissez via des affordances 2D. La placer dans un WindowGroup et la garder plate, c’est le bon choix. visionOS traite les fenêtres SwiftUI comme des panneaux de verre flottants avec le chrome système ; l’utilisateur obtient une expérience de lecture confortable sans que vous écriviez une seule ligne de RealityKit.

Applications multi-fenêtres qui composent des panneaux plats dans l’espace. Un éditeur de code avec des fenêtres séparées pour l’éditeur, le terminal et la documentation. L’utilisateur veut que les fenêtres soient disposées dans l’espace 3D (à gauche, à droite, derrière), mais chaque fenêtre est elle-même une vue SwiftUI. La disposition 3D, c’est le travail de l’OS ; les panneaux sont plats.

Visionneuses de documentation, galeries de photos, lecteurs vidéo. Du contenu que l’utilisateur consomme à travers le panneau. Le panneau est la surface de rendu ; la troisième dimension n’est que la position spatiale du panneau dans la pièce.

La règle : si le contenu est 2D (texte, images, vidéo, contrôles), le bon framework est SwiftUI. La troisième dimension, c’est l’endroit où le panneau est positionné, pas ce qui est rendu à l’intérieur.

Quand RealityKit Est Requis

Les cas où SwiftUI ne suffit pas :

Du contenu 3D autour duquel l’utilisateur peut marcher. Un objet virtuel sur la table de l’utilisateur (un modèle de voiture, une sculpture, un bâtiment). L’objet a du volume ; l’utilisateur peut se déplacer autour de lui ; l’objet doit s’occlure correctement avec la pièce. Le bon framework, c’est RealityKit, ancré sur une cible .plane.

Une UI spatiale qui répond à la pièce. Des boutons qui flottent au-dessus d’un clavier réel, des annotations attachées à un objet réel, un mètre ruban virtuel posé le long d’un mur réel. La position de l’UI est déterminée par la géométrie du monde, pas par l’espace de coordonnées d’une fenêtre. Les ancres RealityKit effectuent la liaison ; les attachments SwiftUI à l’intérieur d’un RealityView fournissent les affordances 2D.

Simulation spatiale continue. Une volée d’oiseaux, une balle qui roule sur le sol, une simulation de fluide, tout ce où l’état de la scène évolue au fil du temps. La boucle de rendu continue est le bon outil ; le moteur de rendu basé sur le diff de SwiftUI manquerait des frames ou consommerait la batterie.

Interactions de hand-tracking. Pincer pour saisir, mise à l’échelle à deux mains, dessin en l’air. Le modèle d’entrée nécessite le HandTrackingProvider d’ARKit (avec les mises à jour HandAnchor) plus une cible d’ancrage .hand(_:location:) ; SwiftUI n’expose pas cette surface.

AR avec suivi du corps. Refléter la pose de l’utilisateur sur un personnage virtuel, suivre le corps de l’utilisateur pour une application de fitness, reconnaître des objets réels. La capture et l’inférence se produisent dans ARKit (le compagnon de plus bas niveau de RealityKit) ; RealityKit effectue le rendu du résultat.

La règle : si le contenu est en 3D et vit dans la pièce (volumétrique, ancré, simulé ou piloté à la main), le bon framework est RealityKit. SwiftUI est le chrome qui l’entoure.

Le Pattern De Composition

La plupart des applications visionOS non triviales finissent par utiliser les deux. Le pattern qui se livre bien :

1. Le chrome de l’application (paramètres, navigation, listes, formulaires, panneaux d’inspecteur) vit dans des fenêtres SwiftUI.
2. La scène spatiale (le contenu volumétrique que l’utilisateur manipule) vit dans un RealityView à l’intérieur de sa propre fenêtre ou volume.
3. Les deux communiquent à travers l’état SwiftUI. Un bouton dans un panneau SwiftUI bascule un booléen @State ; la closure update: du RealityView lit le booléen et mute l’entité dans la scène.
4. Les changements d’état du côté RealityKit qui ont besoin de remonter à SwiftUI passent par des callbacks que la closure make: du RealityView enregistre (subscribe(to:) sur le publisher d’événements de la scène).⁷

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

La séparation est honnête sur le framework qui possède quel travail. SwiftUI possède la liste, les boutons, la mise en page, l’état. RealityKit possède le rendu 3D, les entités, la simulation continue. L’état traverse la frontière sous forme d’une seule valeur @State ; aucun des deux frameworks n’atteint dans l’autre.

Ce Que Je Construirais Différemment Dans Ma Stack

Trois patterns qui deviennent faciles à reconnaître une fois que vous avez livré une scène spatiale :

L’ancre d’abord, l’entité ensuite. Lors de la conception d’une fonctionnalité, décidez de l’ancre avant la géométrie. Un instrument virtuel ancré sur la main de l’utilisateur est un produit différent du même instrument ancré sur une cible .plane sur la table. L’ancre décide de la relation de l’utilisateur avec l’objet ; la géométrie est un détail d’implémentation.

Des composants, pas des sous-classes. Il est tentant de sous-classer Entity pour construire des types de domaine comme ChessPiece: Entity. Le pattern de composition bat l’héritage à chaque fois : une pièce d’échecs est une Entity avec un ChessPieceComponent (données personnalisées : couleur, type, position), un ModelComponent (le maillage 3D), un InputTargetComponent et un CollisionComponent. Les nouveaux comportements sont de nouveaux composants, pas de nouvelles sous-classes.

Des systèmes pour la logique transversale. Lorsque dix entités ont besoin du même comportement (gravité, réponse aux collisions, atténuation audio, état de geste), écrivez un System qui opère sur les composants pertinents. Le système s’exécute une fois par frame sur toutes les entités correspondantes. L’alternative (placer la logique sur chaque entité) produit le bug n-fois-n-frames que le pattern ECS a été inventé pour éviter.

Quand RealityView Est La Mauvaise Réponse

Quelques cas où recourir à RealityView est le mauvais choix :

Une seule image 3D, sans interaction. Un logo 3D statique ou un rendu de produit. Utilisez plutôt une vue SwiftUI Model3D.⁸ Model3D est le chemin économique pour « charger un USDZ et l’afficher » ; RealityView est pour les scènes que vous construisez et mutez.

Applications iOS avec de simples superpositions AR. L’ARView d’ARKit (la surface plus ancienne) ou l’intégration ARView côté iOS de RealityKit est souvent le bon choix lorsque l’expérience AR est une fonctionnalité au sein d’une application iOS plus large. RealityView est natif Swift-et-SwiftUI et vit bien à l’intérieur de SwiftUI ; les anciens flux de travail ARView sont parfois plus simples lorsque le reste de l’application est en UIKit.

Dessin 2D sur un panneau. Un tableau blanc, un outil d’annotation de photos, un éditeur de formes plates. Le bon outil, c’est Canvas (la surface de dessin SwiftUI basée sur Metal) ou MetalView. RealityView, c’est de la sur-ingénierie si vous ne construisez pas dans l’espace 3D.

Ce Que Le Pattern Signifie Pour Les Applications Livrées Sur visionOS 2+

Trois enseignements.

1. RealityKit et SwiftUI se composent ; ils ne s’effondrent pas. Utilisez SwiftUI pour le chrome en forme de fenêtre et les affordances 2D ; utilisez RealityKit pour le contenu 3D en forme de pièce. La frontière, c’est RealityView, et la frontière est unidirectionnelle.

2. Le modèle mental, c’est ECS plus ancres. Une entité est ce dont elle est composée. Une ancre décide comment l’entité se rapporte à l’espace réel de l’utilisateur. Le couple (composants, ancre) est l’unité de design.

3. La boucle de rendu est continue. Le temps fait partie de la scène. La logique par frame va dans System.update(context:) ; la logique pilotée par changement d’état va dans RealityView.update:. Mélanger les deux couches (écrire la logique par frame dans le body SwiftUI, écrire la logique pilotée par l’état dans System.update) est l’erreur d’architecture la plus courante.

Le cluster Apple Ecosystem complet : les App Intents typés pour Apple Intelligence ; les serveurs MCP pour les agents inter-LLM ; la question de routage entre eux ; Foundation Models pour LLM sur appareil et le protocole Tool ; Live Activities pour la machine à états du Lock Screen iOS ; le contrat du runtime watchOS sur l’Apple Watch ; les internes de SwiftUI pour le substrat du framework ; les patterns Liquid Glass pour la couche visuelle ; la livraison multi-plateforme pour la portée inter-appareils. Le hub se trouve dans la série Apple Ecosystem. Pour un contexte iOS-avec-agents-IA plus large, consultez le guide iOS Agent Development.

FAQ

RealityKit remplace-t-il SwiftUI sur visionOS ?

Non. RealityKit et SwiftUI se composent. SwiftUI gère les fenêtres 2D, les contrôles et le chrome ; RealityKit gère les scènes 3D ancrées sur des points de référence du monde réel. La plupart des applications visionOS non triviales utilisent les deux, avec RealityView comme pont qui place une scène RealityKit à l’intérieur d’un arbre de vues SwiftUI.

Quand devrais-je utiliser RealityView vs Model3D ?

Utilisez Model3D pour afficher un seul actif 3D statique (un fichier USDZ, un seul rendu de produit). Utilisez RealityView pour construire ou muter une scène 3D au fil du temps (entités multiples, physique, gestes, suivi des mains, contenu ancré). Model3D est le chemin économique ; RealityView est la surface ECS complète.

Quelle est la différence entre une Entity et un Component dans RealityKit ?

Une entité est un nœud dans le graphe de scène. Un composant est une donnée typée attachée au nœud. ModelComponent donne à l’entité un maillage ; InputTargetComponent la rend éligible aux gestes ; CollisionComponent définit la géométrie de hit-test ; PhysicsBodyComponent la fait répondre à la gravité. Les types Component personnalisés que vous définissez contiennent les données de domaine. Le comportement, c’est de la composition plutôt que de l’héritage : le comportement d’une entité, c’est la somme de ses composants.

Que sont les ancres et pourquoi sont-elles importantes ?

Les ancres lient le contenu virtuel à des points de référence du monde réel : la tête de l’utilisateur, sa main, une surface détectée, une image reconnue, un objet reconnu, ou un point persistant du monde. L’ancre décide de la relation de l’utilisateur avec l’entité. Un objet virtuel sur une cible .plane (la table) reste en place lorsque l’utilisateur en fait le tour ; un objet virtuel sur une cible .head suit la tête de l’utilisateur. Choisir la bonne ancre est la première décision de design dans une fonctionnalité spatiale.

RealityKit peut-il fonctionner sur iOS, et pas seulement sur visionOS ?

Oui. RealityKit est livré sur iOS, iPadOS, macOS et visionOS. Les expériences AR pilotées par ARKit utilisent la surface iOS de RealityKit. La surface visionOS ajoute des types d’ancres spécifiques au spatial (tête, main, monde) qu’iOS n’expose pas ; le pattern ECS de base est partagé.

Références