Build iOS augmented reality and 3D experiences with RealityKit and ARKit. Use when adding RealityView content, loading entities or USDZ models, anchoring objects to planes or world positions, distinguishing entity hit tests from ARKit real-world raycasts, handling AR camera availability, world track

RealityKit Build AR experiences on iOS using RealityKit for rendering and ARKit for world tracking. Covers RealityView , entity management, raycasting, scene understanding, and gesture based interactions. Targets Swift 6.3 / iOS 26+. Contents [Setup]( setup) [RealityView Basics]( realityview basics) [Loading and Creating Entities]( loading and creating entities) [Anchoring and Placement]( anchoring and placement) [Raycasting]( raycasting) [Gestures and Interaction]( gestures and interaction) [Scene Understanding]( scene understanding) [Common Mistakes]( common mistakes) [Review Checklist]( review checklist) [References]( references) Setup Project Configuration 1. Add NSCameraUsageDescription to Info.plist 2. On iOS, RealityViewCameraContent displays an AR camera view by default (iOS 18+, macOS 15+); use .virtual camera mode for explicit non AR fallback 3. No entitlement is required for basic AR. If AR is core to the app, add the arkit required device capability; otherwise gate AR UI with isSupported . Device Requirements Check the exact AR configuration's isSupported value before presenting AR UI. Key Types Type Platform Role RealityView iOS 18+, visionOS 1+ SwiftUI view that hosts RealityKit content RealityViewCameraContent iOS 18+, macOS 15+ Content displayed through an AR camera view on iOS, non AR on macOS Entity All Base class for all scene objects ModelEntity All Entity with a visible 3D model AnchorEntity All Tethers entities to a real world anchor RealityView Basics RealityView is the SwiftUI entry point for RealityKit. RealityViewCameraContent is the iOS/macOS content type. On iOS, it uses an AR camera view by default and can use content.camera = .virtual for non AR mode when requested or when AR/camera access is unavailable. Make and Update Pattern Use the update closure to respond to SwiftUI state changes: Loading and Creating Entities Loading from USDZ Files Load 3D models asynchronously to avoid blocking the main thread: Adding Components Entities use an ECS (Entity Component System) architecture. Add components to give entities behavior: Anchoring and Placement AnchorEntity Use AnchorEntity to anchor content to detected surfaces or world positions: Anchor Targets Target Description .plane(.horizontal, ...) Horizontal surfaces (floors, tables) .plane(.vertical, ...) Vertical surfaces (walls) .plane(.any, ...) Any detected plane .world(transform:) Fixed world space position Raycasting Keep RealityKit scene queries separate from ARKit real world raycasts: RealityViewCameraContent.ray(through:in:to:) returns a camera ray in RealityKit coordinate spaces. It projects a screen point into the virtual scene; it is not proof of a detected physical surface. RealityViewCameraContent.hitTest(point:in:query:mask:) hits virtual entities made hittable by CollisionComponent shapes. Use those shapes for entity picking and targeted gestures, not ARKit plane detection. Use AnchorEntity(.plane(...)) for simple placement on detected planes. Use ARKit ARRaycastQuery plus ARSession.raycast( :) when the task needs a one shot intersection with real world surfaces, then anchor with AnchorEntity(raycastResult:) . Do not treat entity hit tests as substitutes for ARKit surface raycasts. Gestures and Interaction For gesture based entity interaction, add CollisionComponent for the hittable shape and InputTargetComponent for input targeting. Drag Gesture on Entities Scene Understanding Per Frame Updates Subscribe to SceneEvents.Update for continuous scene work rather than driving RealityKit with a SwiftUI timer. Keep the subscription alive and use event.deltaTime ; see [Entity Animations](references/realitykit patterns.md entity animations). Platform Boundaries On visionOS, ARKit provides a different API surface with ARKitSession , WorldTrackingProvider , and PlaneDetectionProvider . These visionOS specific types are not available on iOS. On iOS, RealityKit handles world tracking automatically through RealityViewCameraContent . For iOS architecture or migration notes, gate AR with ARWorldTrackingConfiguration.isSupported , host content with RealityViewCameraContent , and build scenes from Entity / ModelEntity placed with AnchorEntity . Handoffs: CollisionComponent + InputTargetComponent handle RealityKit interaction; AccessibilityComponent handles entity accessibility metadata; detailed SwiftUI gestures and VoiceOver/Switch Control policy belong to siblings. Treat existing SCNView / SCNNode work as either a separate SceneKit path or an explicit migration to RealityKit, not a mixed scene graph. Common Mistakes DON'T: Skip AR capability checks Use the configuration specific support check from Setup before presenting AR. Show non AR content or an explicit unavailable state when it fails. DON'T: Load heavy models synchronously Loading large USDZ files on the main thread causes frame drops and hangs. The make closure of RealityView is async use it. DON'T: Forget collision and input target components for interactive entities Interactive entities need both components shown in [Gestures and Interaction]( gestures and interaction); without them, taps and drags pass through. DON'T: Create new entities in the update closure The update closure runs on every SwiftUI state change. Creating entities there duplicates content on each render pass. DON'T: Ignore camera permission RealityKit on iOS needs camera access. If the user denies permission, the view shows a black screen with no explanation. Review Checklist [ ] NSCameraUsageDescription set in Info.plist [ ] AR device capability checked before presenting AR views [ ] Camera permission requested and denial handled with a fallback UI [ ] arkit required device capability added when AR is the app's core purpose [ ] 3D models loaded asynchronously in the make closure [ ] Entities created in make , modified in update (not created in update ) [ ] Interaction prerequisites and sibling handoffs follow the Gestures section [ ] Entity hit tests, camera rays, and ARKit surface raycasts follow the Raycasting distinctions [ ] SceneEvents.Update subscriptions used for per frame logic (not SwiftUI timers) [ ] Large scenes use ModelEntity(named:) async loading, not Entity.load(named:) [ ] Anchor entities target appropriate surface types for the use case [ ] Entity names set for lookup in the update closure References Read [references/realitykit patterns.md](references/realitykit patterns.md) for physics, animations, lighting, ECS, accessibility, and performance patterns. [RealityKit framework](https://sosumi.ai/documentation/realitykit) [RealityView](https://sosumi.ai/documentation/realitykit/realityview) [RealityViewCameraContent](https://sosumi.ai/documentation/realitykit/realityviewcameracontent) [RealityViewCamera](https://sosumi.ai/documentation/realitykit/realityviewcamera) [Entity](https://sosumi.ai/documentation/realitykit/entity) [ModelEntity](https://sosumi.ai/documentation/realitykit/modelentity) [AnchorEntity](https://sosumi.ai/documentation/realitykit/anchorentity) [ARKit framework](https://sosumi.ai/documentation/arkit) [ARKit in iOS](https://sosumi.ai/documentation/arkit/arkit in ios) [Verifying Device Support and User Permission](https://sosumi.ai/documentation/arkit/verifying device support and user permission) [ARWorldTrackingConfiguration](https://sosumi.ai/documentation/arkit/arworldtrackingconfiguration) [ARRaycastQuery](https://sosumi.ai/documentation/arkit/arraycastquery) [ARSession.raycast( :)](https://sosumi.ai/documentation/arkit/arsession/raycast( :)) [Loading entities from a file](https://sosumi.ai/documentation/realitykit/loading entities from a file)