realitykit

用途

RealityKit 用于在 iOS 上构建增强现实体验：使用 RealityKit 负责渲染，使用 ARKit 负责世界追踪。本技能覆盖 RealityView、实体管理、射线检测、场景理解以及基于手势的交互，目标平台为 Swift 6.3 / iOS 26+。

主要能力

• RealityView 基础：RealityView 是 RealityKit 的 SwiftUI 入口。在 iOS 上它提供 RealityViewCameraContent，通过设备摄像头渲染 AR 内容。支持 make 与 update 闭包模式，update 闭包用于响应 SwiftUI 状态变化。
• 加载与创建实体：可从 USDZ 文件异步加载 3D 模型（避免阻塞主线程），也可程序化生成网格（盒体、球体、平面等）。实体采用 ECS（实体组件系统）架构，通过添加组件赋予行为，例如 PhysicsBodyComponent、CollisionComponent、InputTargetComponent。
• 锚定与放置：使用 AnchorEntity 将内容锚定到检测到的表面或世界位置，支持水平面、垂直面、任意平面以及固定世界坐标。
• 射线检测：使用 RealityViewCameraContent 在 SwiftUI 视图坐标与 RealityKit 世界空间之间转换，配合 SpatialTapGesture 在用户点击的检测表面上放置对象。
• 手势与交互：支持对实体进行拖拽手势（DragGesture targetedToAnyEntity）和点击选择（SpatialTapGesture）。
• 场景理解：可订阅 SceneEvents.Update 事件进行逐帧处理。

使用方式

项目配置：在 Info.plist 中添加 NSCameraUsageDescription。iOS 上 RealityKit 默认通过 RealityViewCameraContent（iOS 18+、macOS 15+）使用设备摄像头，基础 AR 无需额外能力。

设备要求：AR 功能需要 A9 芯片或更新设备，展示 AR UI 前应始终验证支持情况，例如使用 ARWorldTrackingConfiguration.isSupported 判断。

关键类型：RealityView（iOS 18+、visionOS 1+，承载 RealityKit 内容的 SwiftUI 视图）、RealityViewCameraContent（iOS 18+、macOS 15+，通过设备摄像头显示的内容）、Entity（所有场景对象的基类）、ModelEntity（带可见 3D 模型的实体）、AnchorEntity（将实体绑定到真实世界锚点）。

加载模型：使用 try? await ModelEntity(named:) 异步加载，避免使用同步的 Entity.load(named:) 阻塞主线程。

交互实体：手势仅对同时具有 CollisionComponent 和 InputTargetComponent 的实体生效，缺少它们时点击和拖拽会穿透。

逐帧逻辑：使用 SceneEvents.Update 订阅而非 SwiftUI 计时器。

适用场景

适用于在 iOS 应用中集成 3D 内容与 AR 体验，例如通过 RealityView 展示 3D 模型、将对象放置到检测到的平面、实现可拖拽或可点击的 AR 实体、以及需要逐帧更新的 AR 场景。

限制与注意事项

• AR 功能需要 A9 芯片或更新设备，必须在使用前检查支持情况，否则在不支持的设备上会静默失败并显示黑屏。
• iOS 上 RealityKit 需要摄像头权限，若用户拒绝授权会显示黑屏且无说明，应请求权限并提供回退 UI。
• 大型 USDZ 文件不应同步加载，否则会导致掉帧和卡顿。
• 不要在 update 闭包中创建新实体，因为 update 会在每次 SwiftUI 状态变化时运行，会导致内容重复；应在 make 中创建、在 update 中修改。
• 碰撞形状应与实体的视觉尺寸匹配。
• visionOS 上 ARKit 提供不同的 API（ARKitSession、WorldTrackingProvider、PlaneDetectionProvider），这些 visionOS 专属类型在 iOS 上不可用；iOS 上 RealityKit 通过 RealityViewCameraContent 自动处理世界追踪。

审查清单

• Info.plist 中已设置 NSCameraUsageDescription
• 展示 AR 视图前已检查 AR 设备能力
• 已请求摄像头权限并处理拒绝情况（提供回退 UI）
• 3D 模型在 make 闭包中异步加载
• 实体在 make 中创建、在 update 中修改（不在 update 中创建）
• 交互实体同时具有 CollisionComponent 和 InputTargetComponent
• 碰撞形状与实体视觉尺寸匹配
• 使用 SceneEvents.Update 订阅处理逐帧逻辑（而非 SwiftUI 计时器）
• 大型场景使用 ModelEntity(named:) 异步加载，而非 Entity.load(named:)
• 锚定实体针对用例选择合适的表面类型
• 为实体设置名称以便在 update 闭包中查找

参考

扩展模式（物理、动画、光照、ECS）见 references/realitykit-patterns.md。相关框架文档包括 RealityKit framework、RealityView、RealityViewCameraContent、Entity、ModelEntity、AnchorEntity、ARKit framework、ARKit in iOS、ARWorldTrackingConfiguration 以及从文件加载实体。