用途:在 iOS 上使用 RealityKit 渲染、ARKit 做世界追踪,构建 AR 与 3D 体验。目标为 Swift 6.3 / iOS 26+。
主要能力:RealityView 作为 SwiftUI 入口承载 RealityKit 内容,RealityViewCameraContent 在 iOS 默认显示 AR 相机视图,可用 content.camera = .virtual 切换非 AR 模式;通过 Entity、ModelEntity、AnchorEntity 管理场景对象;支持异步加载 USDZ 模型、ECS 组件(PhysicsBodyComponent、CollisionComponent、InputTargetComponent)、平面与世界锚定、射线检测、手势交互与逐帧更新。
必要用法:在 Info.plist 添加 NSCameraUsageDescription;呈现 AR 前用 ARWorldTrackingConfiguration.isSupported 检查设备支持;AR 为核心功能时添加 arkit required-device 能力。模型应在 RealityView 的 make 闭包中异步加载,实体在 make 中创建、在 update 中修改,避免在 update 中新建实体。交互实体需同时设置 CollisionComponent 与 InputTargetComponent。逐帧逻辑使用 SceneEvents.Update 订阅,而非 SwiftUI 计时器。
限制与注意:RealityKit 场景查询与 ARKit 真实世界射线检测需区分,实体命中测试不能替代 ARKit 表面射线检测;visionOS 的 ARKitSession、WorldTrackingProvider 等类型在 iOS 不可用;相机权限被拒时需提供回退界面;现有 SceneKit 代码应作为独立路径或显式迁移,不应混合场景图。更多物理、动画、光照、ECS、无障碍与性能模式见 references/realitykit-patterns.md。