RealityKit visionOS 开发者

描述与目标

本技能提供在 visionOS 上构建基于 RealityKit 的空间体验的完整指导。RealityKit 采用实体-组件-系统（ECS）架构：实体是轻量级容器，行为由组件定义，而系统负责每帧更新逻辑。

目标

• 帮助开发者使用 RealityKit 在 visionOS 上构建沉浸式 3D 体验
• 明确指导在何种场景下应选用特定组件或系统
• 帮助开发者理解 ECS 设计模式及最佳实践
• 支持 RealityKit 场景的调试与性能优化
• 确保通过 RealityView 与 SwiftUI 正确集成

本技能应具备的能力

在 visionOS 上实现 RealityKit 功能时，本技能应做到：

1. 指导组件选型 — 协助您为渲染、交互、物理、音频和动画等需求选择恰当的组件
2. 提供系统实现范式 — 展示如何创建自定义 System 以实现持续性行为
3. 提供代码示例 — 演示常见模式，例如异步资源加载、可交互实体、自定义系统等
4. 强调最佳实践 — 突出说明异步加载、组件注册及性能考量等关键要点
5. 警示常见陷阱 — 指出典型错误，例如在 visionOS 上误用 ARView，或阻塞主 Actor

请根据下方表格，加载对应组件或系统的参考文档，获取详细用法、代码示例与最佳实践。

本技能相关信息

核心概念

实体与组件

• 实体是轻量级容器；其行为由所附加的组件决定。
• 优先采用组合而非继承；当需要为每个实体维护独立状态时，请使用自定义 Component 并遵循 Codable 协议。
• 在使用前，需通过 Component.registerComponent() 全局注册一次自定义组件。
• 仅应从 RealityKit 明确声明的入口点（如 RealityView 闭包、事件处理器及系统）对实体进行修改。

RealityView 与附件

• 使用 RealityView 实现 SwiftUI 与 RealityKit 的桥接。
• 通过 Entity(named:) 或 Entity(contentsOf:) 异步加载资源，并妥善处理错误。
• 若希望在视图定义中同步声明 SwiftUI 附件实体，请使用 RealityView 的 attachments 闭包；若更倾向于以组件方式管理附件，则应使用 ViewAttachmentComponent。

系统与查询

• 对于需持续运行、逐帧更新的行为，请使用自定义 System。
• 使用 EntityQuery 配合 QueryPredicate 查询实体，并在 update(context:) 中进行处理。
• 当多个系统存在依赖关系时，使用 SystemDependency 控制系统更新顺序。

组件参考

请参考下表，在实现 RealityKit 功能时选择需加载的组件参考文档：

渲染与外观

用户交互

锚定与空间定位

摄像机

光照与阴影

音频

动画与角色

物理与碰撞

传送门与环境

呈现与 UI

网络与同步

系统参考

在实现自定义 ECS 行为时，请参考以下内容：

实现范式

RealityView 异步加载

RealityView { content in
    do {
        let entity = try await Entity(named: "Scene")
        content.add(entity)
    } catch {
        print("Failed to load entity: \(error)")
    }
}

可交互实体设置

let entity = ModelEntity(mesh: .generateBox(size: 0.1))
entity.components.set(CollisionComponent(shapes: [.generateBox(size: [0.1, 0.1, 0.1])]))
entity.components.set(InputTargetComponent())
entity.components.set(ManipulationComponent())

自定义系统骨架

import RealityKit

struct SpinComponent: Component, Codable {
    var speed: Float
}

struct SpinSystem: System {
    static let query = EntityQuery(where: .has(SpinComponent.self))

    init(scene: Scene) {}

    func update(context: SceneUpdateContext) {
        for entity in context.entities(matching: Self.query, updatingSystemWhen: .rendering) {
            guard let spin = entity.components[SpinComponent.self] else { continue }
            entity.transform.rotation *= simd_quatf(angle: spin.speed * Float(context.deltaTime), axis: [0, 1, 0])
        }
    }
}

SpinSystem.registerSystem()

常见陷阱与检查项

• 务必异步加载资源；切勿阻塞主 Actor。
• visionOS 上禁止使用 ARView；请改用 RealityView。
• 对于可拖拽或可点击的实体，必须同时添加 CollisionComponent 与 InputTargetComponent。
• 对于由状态驱动的内容更新，请使用 RealityView 的 update 闭包；而对于跨多个实体的持续性逐帧行为，请优先采用自定义 System。
• 内置网格生成支持超出基础图元的更多类型，包括通过 MeshResource API 创建的文本与自定义网格内容。