一句话判断

RealityKit 今年迎来了一次能力大爆发：原生 ARKit 数据直通、手势操控组件、环境遮挡、GPU instancing、沉浸式媒体全格式支持，外加 tvOS 新平台。如果你还在用 SceneKit，这是最后的迁移信号。

这场 Session 讲了什么

Laurence 用一个空间解谜游戏串起了今年 RealityKit 的所有新特性。游戏核心玩法：把宝箱锚定在桌面上，玩家抓取周围物体寻找钥匙。

ARKit 数据直通 RealityKit。 以前要同时跑 ARKit session 和 RealityKit 场景，现在通过 SpatialTrackingSession + AnchorStateEvent 就能在 RealityKit 内部直接拿到 ARKit 的锚点数据（transform、extents）。DidAnchor 事件会给你附带 ARKitAnchorComponent 的锚点 entity，直接 cast 到 PlaneAnchor 就能用原始 ARKit 数据。

ManipulationComponent 让 3D 实体的抓取旋转变得极其简单。调用 ManipulationComponent.configureEntity() 一行代码，自动加上 InputTarget、Collision、HoverEffect 和 Manipulation 组件。配合 ManipulationEvents（WillBegin/WillEnd/DidUpdateTransform）可以精确控制物理行为——比如抓取时切 kinematic、释放时切 dynamic 让物体自由落体。

Scene Understanding API 新增了 collision 和 physics flag，房间的真实网格直接参与物理模拟。物体掉到地上会和真实地板碰撞。

EnvironmentBlendingComponent 让虚拟实体被真实静态物体遮挡，效果类似 passthrough 但更精确。注意动态物体（人、宠物）不会触发遮挡。

MeshInstancesComponent 是 GPU instancing 的高层封装。一个 entity + 一组 transform 矩阵就能高效渲染大量重复模型。相比 clone entity 省内存省 draw call。

ImagePresentationComponent 全新组件，支持三种图像：传统 2D 图片、spatial photo（立体照片）、spatial scene（从 2D 照片生成的 3D 立体场景，带 motion parallax）。Spatial scene 的生成动画和系统 Photos app 一致。

VideoPlayerComponent 扩展支持 spatial video 完整空间样式、APMP 180/360/Wide-FOV 视频、Apple Immersive Video，以及自动舒适度调节。

值得深挖的点

AnchorStateEvent 是连接 RealityKit 和 ARKit 的桥梁。 以前你得自己管理两套 session 的同步，现在 RealityKit 内部就能拿到完整的 ARKit 锚点生命周期（DidAnchor/WillUnanchor/DidFailToAnchor）。对自定义渲染引擎来说也是好消息——ARKit 也提供了 AccessoryAnchor 等新类型。

ManipulationComponent 的 releaseBehavior 很关键。 默认行为是松手后物体飞回原位（.snapBack）。如果做解谜或编辑类 app，一定要设成 .stay，否则用户体验会很困惑。

MeshInstancesComponent 有个注意事项： 同一个 MeshInstancesComponent 渲染的所有实例属于同一个 entity。如果覆盖范围很大，应该拆成多个较小 entity 让 frustum culling 生效。

Spatial scene 的生成是异步操作。 你可以选择预生成，也可以等用户点击按钮时再生——设好 desiredViewingMode = .spatial3D 后调用 generate()，组件会自动显示进度动画。

代码片段

用 ManipulationComponent 一行启用交互 + 控制物理行为：

// 一行启用抓取交互
ManipulationComponent.configureEntity(entity)
entity.components[ManipulationComponent.self]?.releaseBehavior = .stay

// 添加物理体，抓取时 kinematic，释放后 dynamic
var physics = PhysicsBodyComponent()
physics.mode = .kinematic
entity.components.set(physics)

// 监听 ManipulationEvents 控制物理模式
entity.subscribe(to: ManipulationEvents.WillBegin.self) { _ in
    entity.components[PhysicsBodyComponent.self]?.mode = .kinematic
}
entity.subscribe(to: ManipulationEvents.WillEnd.self) { _ in
    entity.components[PhysicsBodyComponent.self]?.mode = .dynamic
}

用 MeshInstancesComponent 高效渲染 20 个重复模型：

let meshEntity = try await Entity(named: "Gem", in: realityKitContentBundle)
let instances = MeshInstancesComponent(mesh: meshEntity.model!.mesh)
let instanceData = LowLevelInstanceData(instanceCount: 20)

for i in 0..<20 {
    let transform = Transform(
        scale: .one,
        rotation: simd_quatf(angle: .random(in: 0...(.pi * 2)), axis: .up),
        translation: SIMD3<Float>.random(in: -5...5)
    )
    instanceData[i] = LowLevelInstance(transform: transform.matrix)
}
instances[0] = instanceData
gemEntity.components.set(instances)

最佳实践

用 SpatialTrackingSession 统一管理锚点追踪。 在进入 immersive space 时创建 session，退出时清理。配置时按需开启 plane tracking、accessory tracking 和 scene understanding flags。

ManipulationEvents 比直接 KVO 更可靠。 事件流有明确的生命周期（WillBegin -> DidUpdate -> WillEnd），不会出现竞态条件。

EnvironmentBlendingComponent 的实体会被当作背景层。 它会始终绘制在其他虚拟物体后面。如果你需要某些实体同时参与前景渲染和环境遮挡，需要仔细规划渲染层级。

ImagePresentationComponent 处理 spatial photo 时记得检查 availableViewingModes。 不是所有图片都支持 spatial stereo 模式，不检查就设 desiredViewingMode 会 fallback 到 2D。

还有什么值得关注

• RealityKit 今年新增 tvOS 平台支持，所有 Apple TV 4K 世代都支持。一个代码库跨 iOS/iPadOS/macOS/tvOS/visionOS。
• AVIF 纹理压缩：质量接近 JPEG 且支持 10-bit 色彩，体积显著更小。可以用 Mac 上的 Preview app 或 usdcrush 命令行工具导出。
• HoverEffectComponent 新增 GroupID：共享 GroupID 的 hover effect 会联动激活，不受父子层级限制。
• Post-processing 效果现在可以直接加到 RealityView 上，支持 Metal Performance Shaders、CIFilter 或自定义 shader。iOS/iPadOS/macOS/tvOS 均可用。
• 新增 entity attach to pin API，可以轻松把 mesh 绑定到动画骨骼的关节上，避免手动对齐和昂贵的层级 transform 更新。
• 支持从内存 Data 对象加载 entity（从网络流式加载 USD 场景），以及 spatial accessory 追踪（PS VR2 Sense 控制器和 Logitech Muse）。