# RealityKit VisionOS 开发者 ## 描述和目标该技能为在 VisionOS 上实现基于 RealityKit 的空间体验提供了全面的指导。 RealityKit 使用实体组件系统 (ECS) 架构，其中实体是轻量级容器，行为来自组件，系统驱动每帧更新。 ### 目标 * 使开发人员能够使用 RealityKit 在 VisionOS 上构建沉浸式 3D 体验 * 提供关于何时使用每个组件和系统的明确指导 * 帮助开发者了解ECS模式和最佳实践 * 支持RealityKit场景的调试和优化 * 确保通过 RealityView 与 SwiftUI 正确集成 ## 这个技能应该做什么在 VisionOS 上实现 RealityKit 功能时，此技能应该： 1. **指导组件选择** \-帮助您选择适合渲染、交互、物理、音频和动画需求的组件 2. **提供系统实现模式** \-展示如何创建连续行为的自定义系统 3. **提供代码示例** \- 演示异步资产加载、交互式实体和自定义系统等常见模式 4. **突出最佳实践** \- 强调正确的异步加载、组件注册和性能注意事项 5. **警告陷阱** \- 识别常见错误，例如在visionOS上使用ARView或阻止主要参与者从下表中加载适当的组件或系统参考文件，以了解详细用法、代码示例和最佳实践。 ## 有关技能的信息 ### 核心概念 #### 实体和组件 * 实体是轻量级容器；行为来自组件。 * 优先选择组合而不是继承，并在需要每个实体状态时使用自定义 `Component` \+ `Codable`。 * 使用前使用 Component.registerComponent() 注册一次自定义组件。 * 在主要参与者上保留实体转换和组件更新。 #### RealityView 和附件 * 使用 `RealityView` 来桥接 SwiftUI 和 RealityKit。 * 使用 Entity(named:) 或 Entity(contentsOf:) 异步加载资源并处理错误。 * 始终使用“ViewAttachmentComponent”进行 3D SwiftUI 覆盖，并避免“RealityView”附件关闭。 #### 系统和查询 * 使用自定义“系统”来实现连续的每帧行为。 * 使用 `EntityQuery` \+ `QueryPredicate` 查询实体并在 `update(context:)` 中处理它们。 * 使用 `SystemDependency` 来控制多个系统交互时的更新顺序。 ### 组件参考使用此表来决定在实现 RealityKit 功能时加载哪个组件参考文件： #### 渲染和外观组件|何时使用 ---|--- [`ModelComponent`]() |当使用实体上的网格和材质渲染 3D 几何体时。 [`ModelSortGroupComponent`]() |当遇到重叠几何体的深度战斗（z-fight）问题或需要控制绘制顺序时。 [`OpacityComponent`]() |创建淡入淡出效果、使实体半透明或实现可见性过渡时。 [`AdaptiveResolutionComponent`]() |通过降低远处物体的渲染质量来优化大场景中的性能时。 [`ModelDebugOptionsComponent`]() |在调试渲染问题、可视化模型几何形状或在开发过程中检查边界框时。 [`MeshInstancesComponent`]() |高效渲染同一网格的多个副本时（树木、人群、粒子状物体）。 [`BlendShapeWeightsComponent`]() |当实现面部动画、角色表情或变形网格变形时。 #### 用户交互组件|何时使用 ---|--- [`InputTargetComponent`]() |当使实体交互（可点击、可拖动）或处理用户输入事件时。 [`ManipulationComponent`]() |使用手势或触控板实现内置拖动、旋转和缩放交互时。 [`GestureComponent`]() |当实现超出 ManipulationComponent 提供范围的自定义手势识别时。 [`HoverEffectComponent`]() |当用户查看或悬停在交互式实体上时提供视觉反馈时。 [`AccessibilityComponent`]() |当使实体可供屏幕阅读器、VoiceOver 或其他辅助技术访问时。 [`BillboardComponent`]() |创建 2D 精灵、文本标签或 UI 元素时，应始终面向观看者。 #### 锚定和空间组件|何时使用 ---|--- [`AnchoringComponent`]() |将虚拟内容锚定到检测到的平面、跟踪的图像、手部位置或世界目标时。 [`ARKitAnchorComponent`]() |当访问锚定实体的底层 ARKit 锚定数据时。 [`SceneUnderstandingComponent`]() |当访问场景理解数据（例如检测到的对象或房间重建）时。 [`DockingRegionComponent`]() |定义内容可以自动停靠或卡入到位的区域时。 [`ReferenceComponent`]() |当实现外部实体资产的延迟加载或引用其他文件中的实体时。 [`AttachedTransformComponent`]() |将一个实体的变换附加到另一个实体以进行分层定位时。 #### 相机组件|何时使用 ---|--- [`PerspectiveCameraComponent`]() |为 3D 场景配置具有深度和视野的透视相机时。 [`OrthographicCameraComponent`]() |当为类似 2D 的视图配置没有透视畸变的正交相机时。 [`ProjectiveTransformCameraComponent`]() |当实现自定义相机投影变换以满足特殊渲染需求时。 #### 灯光和阴影组件|何时使用 ---|--- [`PointLightComponent`]() |添加从某个位置向各个方向辐射的全向点光源时。 [`DirectionalLightComponent`]() |添加具有平行光线（如阳光）的定向光以获得一致的场景照明时。 [`SpotLightComponent`]() |添加锥形聚光灯以获得聚焦、定向照明效果时。 [`ImageBasedLightComponent`]() |应用 HDR 纹理的环境照明以实现逼真的反射和环境照明时。 [`ImageBasedLightReceiverComponent`]() |当使实体能够接收和响应场景中基于图像的照明时。 [`GroundingShadowComponent`]() |添加接地阴影以在视觉上将浮动内容锚定到表面时。 [`DynamicLightShadowComponent`]() |当启用光源投射到实体上的实时动态阴影时。 [`EnvironmentLightingConfigurationComponent`]() |配置环境照明行为、强度或混合模式时。 [`VirtualEnvironmentProbeComponent`]() |在虚拟环境中实施反射探针以实现准确反射时。 #### 音频组件|何时使用 ---|--- [`SpatialAudioComponent`]() |播放根据听众位置和方向而变化的 3D 定位音频时。 [`AmbientAudioComponent`]() |播放不随听者位置变化的非定向环境音频时。 [`ChannelAudioComponent`]() |在没有空间化的情况下播放基于声道的音频内容（立体声、环绕声等）时。 [`AudioLibraryComponent`]() |存储和管理多个音频资源以便跨实体重用时。 [`ReverbComponent`]() |将混响效果应用于实体的音频以进行空间声学模拟时。 [`AudioMixGroupsComponent`]() |对音频源进行分组以进行集中混音控制和音量管理时。 #### 动画和角色组件|何时使用 ---|--- [`AnimationLibraryComponent`]() |在单个实体上存储角色动画的多个动画（空闲、行走、奔跑）时。 [`CharacterControllerComponent`]() |通过物理、碰撞和地面检测实现角色移动时。 [`CharacterControllerStateComponent`]() |存储角色控制器的运行时状态（速度、接地状态）时。 [`SkeletalPosesComponent`]() |为骨骼动画和骨骼变换提供骨骼姿势数据时。 [`IKComponent`]() |当实现程序动画的逆运动学时（例如，到达、指向）。 [`BodyTrackingComponent`]() |将 ARKit 身体跟踪数据集成到基于真实世界身体姿势的动画实体时。 #### 物理和碰撞组件|何时使用 ---|--- [`CollisionComponent`]() |为命中测试、光线投射或物理交互定义碰撞形状时。 [`PhysicsBodyComponent`]() |当向实体添加物理行为（质量、重力、力）以进行物理模拟时。 [`PhysicsMotionComponent`]() |以编程方式控制物理体的线速度和角速度时。 [`PhysicsSimulationComponent`]() |配置全局物理模拟参数（例如重力或时间步长）时。 [`ParticleEmitterComponent`]() |从实体位置发射粒子效果（烟雾、火花、碎片）时。 [`ForceEffectComponent`]() |当施加影响多个物理体的力场（重力井、爆炸）时。 [`PhysicsJointsComponent`]() |在物理体之间为铰接结构创建接头（铰链、弹簧）时。 [`GeometricPinsComponent`]() |定义用于连接特定位置处的实体的几何附着点时。 #### 门户和环境组件|何时使用 ---|--- [`PortalComponent`]() |创建通过开口呈现独立世界或场景的门户时。 [`WorldComponent`]() |将实体层次结构指定为门户渲染的单独可渲染世界时。 [`PortalCrossingComponent`]() |当控制实体跨越门户边界时的行为（传送、场景切换）时。 [`EnvironmentBlendingComponent`]() |将虚拟内容与真实环境混合以获得混合现实体验时。 #### 演示和用户界面组件|何时使用 ---|--- [`ViewAttachmentComponent`]() |将 SwiftUI 视图嵌入 3D 空间以获取交互式 UI 元素或标签时。 [`PresentationComponent`]() |通过实体交互呈现 SwiftUI 模式、工作表或系统 UI 时。 [`TextComponent`]() |在不使用 SwiftUI 视图的情况下直接在实体上渲染 3D 文本时。 [`ImagePresentationComponent`]() |在 3D 空间中的实体上显示图像或纹理时。 [`VideoPlayerComponent`]() |使用 AVPlayer 在实体表面上播放视频内容时。 #### 网络和同步组件|何时使用 ---|--- [`SynchronizationComponent`]() |跨网络多人游戏会话同步实体状态、转换和组件时。 [`TransientComponent`]() |将实体标记为临时、非持久且从网络同步中排除时。 ### 系统参考实现自定义 ECS 行为时使用此参考：系统/API |何时使用 ---|--- [`系统和组件创建`]() |当为连续的每帧行为创建自定义系统或为每个实体状态创建自定义组件时。 ### 实现模式 #### RealityView 异步加载 RealityView { 内容在做{ 让实体=尝试等待实体（名为：“场景”）内容.添加（实体） } 抓住 { print("无法加载实体：\(错误)") } } #### 交互式实体设置让实体 = ModelEntity(网格: .generateBox(大小: 0.1)) entity.components.set(CollisionComponent(shapes: [.generateBox(size: [0.1, 0.1, 0.1])])) 实体.组件.设置(InputTargetComponent()) 实体.组件.集(ManipulationComponent()) #### 自定义系统骨架导入RealityKit struct SpinComponent：组件，可编码 { 变量速度：浮动 } 结构 SpinSystem: 系统 { static let query = EntityQuery(其中：.has(SpinComponent.self)) 初始化（场景：场景）{} 函数更新（上下文：SceneUpdateContext）{ 对于 context.entities 中的实体（匹配：Self.query，updatedSystemWhen：.rendering）{ 守卫让旋转=实体.组件[SpinComponent.self]否则{继续} entity.transform.rotation *= simd_quatf(角度: spin.speed * Float(context.deltaTime), 轴: [0, 1, 0]) } } } SpinSystem.registerSystem() ### 陷阱和检查 * 始终异步加载资源；避免遮挡主要演员。 * 在visionOS上避免使用“ARView”；使用“RealityView”。 * 为可拖动或可点击的实体添加 `CollisionComponent` \+ `InputTargetComponent`。 * 切勿使用 `RealityView` 更新闭包；使用自定义“系统”来实现连续行为。 * 网格生成仅限于“box”、“sphere”、“plane”、“cylindrical”和“cone”。

Realitykit Visionos 开发人员

包含技能