# RealityKit 开发指南 **用途**：使用 RealityKit 的实体组件系统架构构建 3D 内容、AR 体验和空间计算应用程序 **iOS 版本**：iOS 13+（基础）、iOS 18+（iOS 上的 RealityView）、visionOS 1.0+ **Xcode**：Xcode 15+ ## 何时使用此技能在以下情况下使用此技能： * 构建任何 3D 体验（AR、游戏、可视化、空间计算） * 使用 3D 内容创建 SwiftUI 应用程序（RealityView、Model3D） * 使用锚点实现 AR（世界、图像、面部、身体跟踪） * 使用实体组件系统 (ECS) 架构 * 设置物理、碰撞或空间交互 * 构建多人或共享 AR 体验 * 从 SceneKit 迁移到 RealityKit * 针对visionOS 请勿将此技能用于： * SceneKit 维护（使用 `axiom-scenekit`） * 2D 游戏（使用 `axiom-spritekit`） * 金属着色器编程（使用 `axiom-metal-migration-ref`） * 纯GPU计算（直接使用Metal） ** ** ## 1\.心智模型：ECS 与场景图 ### 场景图 (SceneKit) 在 SceneKit 中，节点拥有自己的属性。节点是一个可渲染、可碰撞、动画的东西。 ### 实体组件系统 (RealityKit) 在 RealityKit 中，实体是**空容器**。组件添加数据。系统处理该数据。实体（身份+层次结构） ├── TransformComponent（位置、旋转、缩放） ├── 模型组件（网格+材质） ├── CollisionComponent（碰撞形状） ├──PhysicsBodyComponent（质量、模式） └── [YourCustomComponent]（游戏特定数据）系统（每帧处理具有特定组件的实体） **为什么 ECS 很重要**： * **组合优于继承**：组合任何实体上的任何组件 * **面向数据**：系统有效地处理组件数组 * **解耦逻辑**：系统彼此不了解 * **可测试** ：组件是纯数据，系统是纯逻辑 ### ECS 心理转变场景图思维|精英思维 ---|--- “玩家节点移动”| “运动系统使用 MovementComponent 处理实体” “向节点子类添加方法”| “添加一个组件，创建一个系统” “覆盖节点中的`update(_:)`”| “注册一个查询组件的系统” “节点知道它的健康状况”| “HealthComponent 保存数据，DamageSystem 处理它” ** ** ## 2\.实体层次结构 ### 创建实体 // 空实体让实体=实体（）实体名称=“玩家” // 具有组件的实体让实体=实体（）实体.组件[ModelComponent.self] = ModelComponent( 网格：.generateBox（大小：0.1），材料：[SimpleMaterial（颜色：.blue，isMetallic：false）] ） // ModelEntity 方便（内置 ModelComponent）让框 = ModelEntity( 网格：.generateBox（大小：0.1），材料：[SimpleMaterial（颜色：.red，isMetallic：true）] ） ### 层级管理 // 父子关系父级.addChild(子级) child.removeFromParent() // 查找实体让找到= root.findEntity（命名：“玩家”） // 枚举对于实体中的子对象.children { // 处理子进程 } // 克隆让克隆=实体.克隆（递归：true） ### 变换 // 局部变换（相对于父级）实体.位置 = SIMD3(0, 1, 0) entity.orientation = simd_quatf(角度: .pi / 4, 轴: SIMD3(0, 1, 0)) entity.scale = SIMD3（重复：2.0） // 世界空间查询让 worldPos = 实体.position(relativeTo: nil) 让 worldTransform =entity.transform(relativeTo: nil) // 设置世界空间变换实体.setPosition(SIMD3(1,0,0),relativeTo: nil) // 看一个点实体.look（位于：targetPosition，来自：entity.position，relativeTo：nil） ** ** ## 3\.组件 ### 内置组件组件|目的 ---|--- `转变` |位置、旋转、缩放 `模型组件` |网格几何形状+材料 `碰撞组件` |物理和交互的碰撞形状 `PhysicsBodyComponent` |质量、物理模式（动态/静态/运动） `PhysicsMotionComponent` |线速度和角速度 `锚定组件` | AR 锚附件 `同步组件` |多人同步 `PerspectiveCameraComponent` |相机设置 `DirectionalLightComponent` |定向光 `点光源组件` |点光源 `SpotLightComponent` |聚光灯 `CharacterControllerComponent` |角色物理控制器 `AudioMixGroupsComponent` |音频混合 `SpatialAudioComponent` | 3D 定位音频 `环境音频组件` |非定位音频 `ChannelAudioComponent` |多声道音频 `不透明度组件` |实体透明度 `GroundingShadowComponent` |接触阴影 `输入目标组件` |手势输入（visionOS） `HoverEffectComponent` |悬停突出显示（visionOS） `辅助功能组件` |旁白支持 ### 自定义组件结构 HealthComponent: 组件 { 无功电流：整数 var 最大值：Int 变量百分比：浮点{ 浮动（当前）/浮动（最大） } } // 使用前注册（通常在app init中） HealthComponent.registerComponent() // 附加到实体实体.组件[HealthComponent.self] = HealthComponent(当前: 100, 最大: 100) // 读取如果让 health =entity.components[HealthComponent.self] { 打印（健康状况.当前） } // 修改实体.组件[HealthComponent.self]?.current -= 10 ### 组件生命周期组件是值类型（结构）。当您读取一个组件、修改它并将其写回时，您将替换整个组件： // 读-修改-写模式 var health =entity.components[HealthComponent.self]! health.current -= 伤害实体.组件[HealthComponent.self] = 健康 **反模式**：持有对组件的引用并期望突变传播。组件在读取时被复制。 ** ** ## 4\.系统 ### 系统协议结构体 DamageSystem: 系统 { // 定义该系统需要哪些组件 static let query = EntityQuery(其中：.has(HealthComponent.self)) 初始化（场景：RealityKit.Scene）{ // 一次性设置 } 函数更新（上下文：SceneUpdateContext）{ 对于 context.entities 中的实体（匹配：Self.query，更新系统时间：.rendering) { var health =entity.components[HealthComponent.self]! 如果 health.current <= 0 { 实体.removeFromParent() } } } } // 注册系统 DamageSystem.registerSystem() ### 系统最佳实践 * **每个系统一个责任**：运动系统、伤害系统、渲染系统 - 不是游戏逻辑系统 * **查询过滤** ：使用精确查询来避免处理不相关的实体 * **顺序很重要**：系统按注册顺序运行。首先注册依赖项。 * **避免存储实体引用**：改为查询每个帧。实体引用可能会变得过时。 ### 事件处理 // 订阅碰撞事件 scene.subscribe(to: CollisionEvents.Began.self) { 事件中让entityA = event.entityA 让entityB = event.entityB // 处理碰撞 } // 订阅场景更新 scene.subscribe(to: SceneEvents.Update.self) { 事件中让 deltaTime = event.deltaTime // 每帧逻辑 } ** ** ## 5\. SwiftUI 集成 ### RealityView（iOS 18+、visionOS 1.0+）结构ContentView：视图{ var body: 一些视图 { RealityView { 内容在 // 关闭——调用一次让框 = ModelEntity( 网格：.generateBox（大小：0.1），材料：[SimpleMaterial（颜色：.blue，isMetallic：false）] ）内容.添加（框） }更新：{内容在 // 更新闭包——当 SwiftUI 状态改变时调用 } } } ### 带摄像头的 RealityView (iOS) 在 iOS 上，“RealityView”提供了用于配置 AR 或虚拟相机的相机内容参数： RealityView { 内容、附件 // 加载3D内容如果让模型=尝试？等待 ModelEntity（命名：“场景”）{ 内容.添加（模型） } } ### 异步加载内容 RealityView { 内容在 // 从包中加载如果让实体=尝试？等待实体（名为：“MyScene”，在：.main）{ 内容.添加（实体） } // 从 URL 加载如果让实体=尝试？等待实体（contentsOf：modelURL）{ 内容.添加（实体） } } ### Model3D（简单显示） // 简单的3D模型展示（无交互） Model3D(named: "toy_robot") { 模型中型号 .resizing() .scaledToFit() } 占位符：{ 进度视图() } ### SwiftUI 附件 (visionOS) RealityView { 内容、附件让实体 = ModelEntity(网格: .generateSphere(半径: 0.1)) 内容.添加（实体） if let label = Attachments.entity(for: "priceTag") { 标签.位置 = SIMD3(0, 0.15, 0) 实体.addChild(标签) } } 附件：{ 附件（id：“priceTag”）{ 文本（“9.99 美元”） .padding() .glassBackgroundEffect() } } ### 状态绑定模式结构 GameView: 视图 { @State private var 分数 = 0 var body: 一些视图 { 虚拟堆栈{ Text("得分：\(得分)") RealityView { 内容在让场景=尝试！等待实体（名为：“GameScene”）内容.添加（场景） }更新：{内容在 // 对状态变化做出反应 // 注意：当 SwiftUI 状态改变时调用 update， // 不是每一帧。使用系统进行每帧逻辑。 } } } } ** ** ## 6\. iOS 上的增强现实 ### 锚实体 // 水平面让锚= AnchorEntity（.plane（.horizontal，分类：.table，最小边界：SIMD2(0.2, 0.2))) // 垂直平面让锚= AnchorEntity（.plane（.vertical，分类：.wall，最小边界：SIMD2(0.5, 0.5))) // 世界位置让锚 = AnchorEntity(世界: SIMD3(0, 0, -1)) // 图像锚点 letanchor = AnchorEntity(.image(group: "AR 资源", name: "海报")) // 人脸锚点（前置摄像头）让锚= AnchorEntity(.face) // 身体锚点让锚= AnchorEntity(.body) ### SpatialTrackingSession（iOS 18+）让会话 = SpatialTrackingSession() 让配置= SpatialTrackingSession.Configuration（跟踪：[.plane，.object]）让结果=等待会话.运行（配置）如果让 notSupported = 结果 { // 处理该设备上不支持的跟踪对于 notSupported.deniedTrackingModes 中的拒绝 { print("不支持：\(拒绝)") } } ### AR 最佳实践 * 将实体锚定到检测到的表面而不是世界位置以保持稳定性 * 使用平面分类（`.table`、`.floor`、`.wall`）来适当放置内容 * 从水平面检测开始——这是最可靠的 * 在真实设备上测试；模拟器AR有限 * 在表面检测期间提供视觉反馈（指导覆盖） ** ** ## 7\.互动 ### ManipulationComponent（iOS、visionOS） // 启用拖动、旋转、缩放手势实体.组件[ManipulationComponent.self] = ManipulationComponent( allowedModes: .all // .translate, .rotate, .scale ） // 还需要 CollisionComponent 进行命中测试实体.generateCollisionShapes（递归：true） ### 输入目标组件 (visionOS) // VisionOS 手势输入所需实体.组件[InputTargetComponent.self] = InputTargetComponent() 实体.组件[CollisionComponent.self] = CollisionComponent( 形状：[.generateBox(大小：SIMD3(0.1, 0.1, 0.1))] ） ### 与 SwiftUI 的手势集成 RealityView { 内容在让实体 = ModelEntity(网格: .generateBox(大小: 0.1)) 实体.generateCollisionShapes（递归：true）实体.组件.设置(InputTargetComponent()) 内容.添加（实体） } .手势( 点击手势() .targetedToAnyEntity() .onEnded { 值在让 tappedEntity = value.entity // 处理点击 } ） .手势( 拖动手势() .targetedToAnyEntity() .onChanged { 值在 value.entity.position = value.convert(value.location3D, 从：.local，到：.scene） } ） ### 命中测试 // 从屏幕点进行光线投射如果让结果 = arView.raycast(来自: screenPoint, 允许：.estimatedPlane，对齐方式：.horizontal).first { 让 worldPosition = result.worldTransform.columns.3 // 将实体放置在 worldPosition 处 } ** ** ## 8\.材质和渲染 ### 材料类型材质 |目的|定制化 ---|---|--- `简单材料` |纯色或纹理 |颜色、金属感、粗糙度 `基于物理的材质` |完整的 PBR |所有 PBR 贴图（基色、法线、金属、粗糙度、AO、发射） `未点亮的材质` |没有灯光反应|颜色或纹理，始终完全照亮 `遮挡材料` |看不见但遮挡| AR内容隐藏在真实物体后面 `视频素材` |表面视频播放| AVPlayer驱动 `ShaderGraphMaterial` |自定义着色器图 |现实作曲家专业版 `自定义材料` |金属着色器功能 |全金属控制 ### 基于物理的材质 var 材质 = PhysicallyBasedMaterial() material.baseColor = .init(色调:.white, 纹理：.init（尝试！.load（名为：“反照率”）））材料.金属 = .init(floatLiteral: 0.0) 材质.粗糙度 = .init(floatLiteral: 0.5) material.normal = .init(texture: .init(try! .load(named: "normal"))) material.ambientOcclusion = .init(texture: .init(try! .load(named: "ao"))) material.emissiveColor = .init(颜色: .blue) 材料.发射强度 = 2.0 让实体=模型实体（网格：.generateSphere（半径：0.1），材料：[材料] ） ### 遮挡材质 (AR) // 隐藏 3D 内容的隐形平面让遮挡器 = ModelEntity( 网格：.generatePlane（宽度：1，深度：1），材质：[OcclusionMaterial()] ）遮挡器.位置 = SIMD3(0, 0, 0) 锚点.addChild(遮挡器) ### 环境照明 // 基于图像的光照如果让资源=尝试？等待环境资源（名为：“studio_lighting”）{ // 通过 RealityView 内容应用 } ** ** ## 9\.物理与碰撞 ### 碰撞形状 // 从网格生成（准确但昂贵）实体.generateCollisionShapes（递归：true） // 手动形状（注重性能）实体.组件[CollisionComponent.self] = CollisionComponent( 形状：[ .generateBox(size: SIMD3(0.1, 0.2, 0.1)), // 盒子 .generateSphere(半径: 0.1), // 球体 .generateCapsule(高度: 0.3, 半径: 0.05) // 胶囊 ] ） ### 物理身体 // Dynamic — 物理模拟控制运动实体.组件[PhysicsBodyComponent.self]=PhysicsBodyComponent( 质量属性：.init（质量：1.0），材质：.generate(staticFriction: 0.5, 动态摩擦：0.3，恢复原状：0.4), 模式：.动态） // Static — 不可移动的碰撞面 ground.components[PhysicsBodyComponent.self] =PhysicsBodyComponent( 模式：.静态） // 运动学——代码控制，参与碰撞 platform.components[PhysicsBodyComponent.self] =PhysicsBodyComponent( 模式：.运动学） ### 碰撞组和过滤器 // 定义组让playerGroup = CollisionGroup(rawValue: 1 << 0) 让敌人组 = 碰撞组（原始值：1 << 1）让bulletGroup = CollisionGroup(rawValue: 1 << 2) // 过滤器：玩家与敌人和子弹发生碰撞实体.组件[CollisionComponent.self] = CollisionComponent( 形状：[.generateSphere（半径：0.1）]，过滤器：碰撞过滤器（组：玩家组，面具：敌人组|子弹组）） ### 碰撞事件 // 在 RealityView 中订阅 make 关闭或 System scene.subscribe(to: CollisionEvents.Began.self, on: playerEntity) { 事件中让 otherEntity = event.entityA == playerEntity ？事件.实体B : 事件.实体A 处理碰撞（与：otherEntity） } ### 施加力量 if varmotion =entity.components[PhysicsMotionComponent.self] { Motion. LinearVelocity = SIMD3(0, 5, 0) // 脉冲向上实体.组件[PhysicsMotionComponent.self] = 运动 } ** ** ## 10\.动画 ### 变换动画 // 在持续时间内动画到位置实体.移动( 到：变换（规模：SIMD3（重复：1.5），旋转：simd_quatf（角度：.pi，轴：SIMD3（0,1,0）），翻译：SIMD3(0, 2, 0) ), 相对于：实体.父级，持续时间：2.0，计时函数：.easeInOut ） ### 播放美元动画如果让实体=尝试？等待实体（名为：“字符”）{ // 播放所有可用的动画对于实体中的动画。availableAnimations { 实体.playAnimation(动画.repeat()) } } ### 动画播放控制让控制器=实体.playAnimation(动画) 控制器.pause() 控制器.resume() controller.speed = 2.0 // 2x 播放速度 controller.blendFactor = 0.5 // 与当前状态混合 ** ** ## 11\.音频 ### 空间音频 // 加载音频资源让资源=尝试！ AudioFileResource.load（命名为：“engine.wav”，配置：.init(shouldLoop: true)) // 创建具有空间音频的实体让音频实体=实体（） audioEntity.components[SpatialAudioComponent.self] = SpatialAudioComponent() 让控制器=audioEntity.playAudio（资源） // 将音频源放置在 3D 空间中 audioEntity.position = SIMD3(2, 0, -1) ### 环境音频实体.组件[AmbientAudioComponent.self] = AmbientAudioComponent() 实体.playAudio（背景音乐） ** ** ## 12\.性能 ### 实体计数 * **实体数量低于 100**：无需担心 * **100-1000 个实体** ：使用 RealityKit 调试器进行监控 * **1000+ 实体**：使用实例化和 LOD 策略 ### 实例化 // 在多个实体之间共享网格和材质让sharedMesh = MeshResource.generateSphere（半径：0.01）让sharedMaterial = SimpleMaterial(颜色: .white, isMetallic: false) 对于我在 0..<1000 { 让实体= ModelEntity（网格：sharedMesh，材料：[sharedMaterial]）实体.position = randomPosition() 父级.addChild(实体) } RealityKit 自动批处理具有相同网格和材质资源的实体。 ### 组件流失 **反模式**：每帧创建和替换组件。 // BAD — 每帧的组件分配函数更新（上下文：SceneUpdateContext）{ 对于 context.entities 中的实体（匹配：查询，更新系统时间：.rendering）{ 实体.组件[ModelComponent.self] = ModelComponent( 网格：.generateBox（大小：0.1）， Materials: [newMaterial] // 每帧新分配） } } // 好——修改现有组件函数更新（上下文：SceneUpdateContext）{ 对于 context.entities 中的实体（匹配：查询，更新系统时间：.rendering）{ // 仅在实际需要时更新如果需要更新{ var model =Entity.Components[ModelComponent.self]! model.materials = [缓存材质] 实体.组件[ModelComponent.self] = 模型 } } } ### 碰撞形状优化 * 使用简单的形状（盒子、球体、胶囊）而不是基于网格的碰撞 * `generateCollisionShapes(recursive: true)` 方便但昂贵 * 对于静态几何体，在设置期间生成一次形状 ### 分析使用 Xcode 的 RealityKit 调试器： * **Entity Inspector** ：查看实体层次结构和组件 * **统计叠加**：实体计数、绘制调用、三角形计数 * **物理可视化**：显示碰撞形状 ** ** ## 13\.多人游戏 ### 同步基础知识 // 如果组件符合 Codable 则自动同步结构 ScoreComponent：组件，可编码 { 变量点：Int } // SynchronizationComponent 控制同步内容实体.组件[SynchronizationComponent.self] = SynchronizationComponent() ### 多点连接服务让服务=尝试MultipeerConnectivityService（会话：mcSession） // 具有 SynchronizationComponent 的实体在对等点之间自动同步 ### 所有权 * 只有实体的**所有者**可以修改它 * 在修改共享实体之前请求所有权 * 不可编码组件数据不同步 ** ** ## 14\.反模式 ### 反模式 1：ECS 中的 UIKit 风格思维 **时间成本**：与架构斗争所带来的挫败感数小时 // BAD — 行为实体的子类化类 PlayerEntity: 实体 { func takeDamage(_ amount: Int) { /* 实体中的逻辑 */ } } // 好——组件保存数据，系统有逻辑 struct HealthComponent: 组件 { var hp: Int } 结构体 DamageSystem: 系统 { static let query = EntityQuery(其中：.has(HealthComponent.self)) 函数更新（上下文：SceneUpdateContext）{ // 此处处理损坏 } } ### 反模式 2：整体实体 **时间成本**：不可测试、不灵活的架构不要将所有游戏逻辑放在一种实体类型中。分成可以混合和匹配的组件。 ### 反模式 3：无系统的基于帧的更新 **时间成本**：错过帧更新，行为不一致 // 不好——基于定时器的更新 Timer.scheduledTimer(withTimeInterval: 1/60, 重复次数: true) { _ in 实体.位置.x += 0.01 } // 好——系统更新结构运动系统：系统{ static let query = EntityQuery(其中：.has(VelocityComponent.self)) 函数更新（上下文：SceneUpdateContext）{ 对于 context.entities 中的实体（匹配：Self.query，更新系统时间：.rendering) { 让速度=实体.组件[VelocityComponent.self]！实体.位置 += 速度.值 * Float(context.deltaTime) } } } ### 反模式 4：不为交互实体生成碰撞形状 **时间成本**：15-30 分钟调试“为什么水龙头不工作” 手势需要 `CollisionComponent`。如果实体具有“InputTargetComponent”(visionOS) 或“ManipulationComponent”但没有“CollisionComponent”，则手势永远不会触发。 ### 反模式 5：在系统中存储实体引用 **时间成本**：由于过时的引用而崩溃 // 不好——实体可能会在帧之间被删除结构 BadSystem: 系统 { varplayerEntity：实体？ // 过时的参考风险函数更新（上下文：SceneUpdateContext）{ playerEntity?.position.x += 0.1 // 可能会崩溃 } } // GOOD — 查询每一帧结构 GoodSystem: 系统 { static let query = EntityQuery(其中：.has(PlayerComponent.self)) 函数更新（上下文：SceneUpdateContext）{ 对于 context.entities 中的实体（匹配：Self.query，更新系统时间：.rendering) { 实体.position.x += Float(context.deltaTime) } } } ** ** ## 15\.代码审查清单 * 自定义组件在使用前通过`registerComponent()`注册 * 在场景加载之前通过 `registerSystem()` 注册系统 * 组件是值类型（结构），而不是类 * 用于组件更新的读-修改-写模式 * 交互实体有 `CollisionComponent` * VisionOS交互实体有`InputTargetComponent` * 碰撞形状尽可能简单（盒子/球体/胶囊） * 系统中没有跨框架存储实体引用 * 相同实体之间共享网格和材质资源 * 组件更新仅在值实际更改时发生 * 用于 3D 资产的 USD/USDZ 格式（非 .scn） * 异步加载用于所有模型/场景加载 * 如果保留视图/控制器，则基于闭包的订阅中的“[weak self]” ** ** ## 16\.压力场景 ### 场景 1：“ECS 对于我们的简单应用来说是大材小用” **压力**：团队不想学习ECS，只需要展示一个3D模型 **错误的方法**：跳过 ECS，将所有逻辑塞入 RealityView 闭包中。 **正确方法**：即使是简单的应用程序也能从 ECS 中受益。 `RealityView` 中的单个 `ModelEntity` 已经在使用 ECS — 您只是还没有添加自定义组件。从简单开始，随着复杂性的增加添加组件。 **推回模板**：“我们已经在使用 ECS — Entity 和 ModelComponent。模式可扩展。当我们需要行为时添加自定义组件是一个结构定义，而不是架构更改。” ### 场景 2：“只需使用 SceneKit，我们知道” **压力**：团队有SceneKit经验，RealityKit不熟悉 **错误的方法**：在 SceneKit 中构建新功能。 **正确方法**：SceneKit 已被软弃用。不会添加新功能。立即投资 RealityKit — 如果需要，ECS 概念可转移到其他游戏引擎（Unity、Unreal、Bevy）。 **推回模板**：“SceneKit 处于维护模式 - 没有新功能，只有安全补丁。我们编写的每一行 SceneKit 都是迁移债。RealityKit 的概念（实体、组件、系统）是行业标准的 ECS。” ### 场景 3：“使其在没有碰撞形状的情况下工作” **压力**：截止日期，碰撞形状设置似乎很复杂 **错误的方法**：跳过碰撞形状，使用基于位置的接近检测。 **正确的方法**：`entity.generateCollisionShapes(recursive: true)`只需要一行。没有它，手势将无法工作，物理也不会发生冲突。 “快捷方式”创建的调试时间多于它节省的时间。 **推回模板**：“手势和物理需要碰撞形状。只有一行：`entity.generateCollisionShapes(recursive: true)`。跳过它意味着手势默默地失败——这是一个更难诊断的错误。” ** ** ## 资源 **全球开发者大会**：2019-603、2019-605、2021-10074、2022-10074、2023-10080、2023-10081、2024-10103、2024-10153 **文档**：/realitykit、/realitykit/entity、/realitykit/realityview、/realitykit/modelentity、/realitykit/anchorentity、/realitykit/component **技能**：axiom-realitykit-ref、axiom-realitykit-diag、axiom-scenekit、axiom-scenekit-ref

Axiom 现实套件

包含技能