---
name: ios-arkit-builder
description: "Augmented reality apps — RealityKit, scene reconstruction, hand tracking, USDZ, visionOS bridge. Modern ARKit + RealityKit: World tracking, plane detection, scene reconstruction (LiDAR), people occlusion, hand tracking, RealityComposer Pro, USDZ assets, and a bridge for porting to visionOS / Apple Vision Pro."
license: MIT
---

# iOS ARKit Builder

A focused assistant for building augmented reality features on iPhone and iPad with ARKit and RealityKit, and carrying that work forward to Apple Vision Pro. It targets the modern Swift stack — `ARKitSession`, `RealityView`, RealityComposer Pro packages, and USDZ — rather than legacy SceneKit-based AR. Aimed at iOS developers who already know Swift/SwiftUI but want correct, current AR plumbing instead of stitching together stale Stack Overflow snippets.

## When to use it

- Standing up a world-tracking session with horizontal/vertical plane detection and tap-to-place content.
- Wiring LiDAR scene reconstruction so virtual objects collide with and occlude behind real geometry.
- Adding people occlusion or hand tracking, then mapping gestures to entity behaviors.
- Importing a USDZ or RealityComposer Pro scene and driving its animations/materials from code.
- Porting an existing iOS AR app toward visionOS without rewriting the entity model from scratch.

## How it works

The skill scaffolds against `ARWorldTrackingConfiguration` with `.planeDetection`, `.sceneReconstruction = .meshWithClassification`, and `.frameSemantics = .personSegmentationWithDepth` for occlusion. On the RealityKit side it generates `ARView` (UIKit) or `RealityView` (SwiftUI) setups, `AnchorEntity` placement via raycasting (`session.raycast`), and `ModelEntity` loading from `.usdz` / `.reality` bundles. Collision and physics use `generateCollisionShapes` and `PhysicsBodyComponent`. For hand tracking and spatial input it uses the visionOS `HandTrackingProvider` / `WorldTrackingProvider` running under `ARKitSession`, and flags which APIs are iOS-only versus visionOS-only so the port doesn't silently break.

## Example

```swift
// Tap to place a USDZ model on a detected plane
let config = ARWorldTrackingConfiguration()
config.planeDetection = [.horizontal, .vertical]
config.sceneReconstruction = .meshWithClassification
arView.session.run(config)

@objc func handleTap(_ g: UITapGestureRecognizer) {
    let p = g.location(in: arView)
    guard let r = arView.raycast(from: p,
        allowing: .estimatedPlane, alignment: .horizontal).first else { return }
    let anchor = AnchorEntity(world: r.worldTransform)
    let model = try! ModelEntity.loadModel(named: "lamp.usdz")
    model.generateCollisionShapes(recursive: true)
    anchor.addChild(model)
    arView.scene.addAnchor(anchor)
}
```

## Tips & gotchas

- `sceneReconstruction` and people occlusion require a LiDAR device; gate them with `ARWorldTrackingConfiguration.supportsSceneReconstruction(.mesh)` or you'll crash on a non-Pro iPhone.
- USDZ scale is in meters. A model authored in centimeters lands 100x too big — fix it in RealityComposer Pro or scale the `ModelEntity`, don't eyeball it.
- Hand tracking is a visionOS capability, not iOS. The skill keeps that code behind availability checks so the shared codebase still compiles for iPhone.
- Add `NSCameraUsageDescription` to Info.plist; ARKit fails silently-ish without it.

## FAQ

**ARKit or RealityKit — which does this use?** Both. ARKit provides tracking/sensing; RealityKit renders and simulates. The skill defaults to RealityKit and treats SceneKit AR as legacy.

**Does the visionOS bridge auto-convert my app?** No. It reshapes your entity/anchor code toward `RealityView` and `ARKitSession`, and marks iOS-only APIs, but spatial UI and input still need manual review.

**Minimum versions?** iOS 13+ for RealityKit; scene reconstruction needs a LiDAR device and iOS 13.4+. Hand tracking needs visionOS 1.0+.