axiom-realitykit-ref

RealityKit API 参考

按类别整理的完整 RealityKit API 参考。

何时使用此参考

在以下情况下使用此参考：

• 查询特定的 RealityKit API 签名或属性
• 查看可用的组件类型
• 为 AR 体验查找合适的锚点类型
• 浏览材质属性和选项
• 设置物理刚体参数
• 查询动画或音频 API 详情
• 查看特定 API 的平台可用性

---

第 1 部分：实体 API

Entity

// Creation
let entity = Entity()
let entity = Entity(components: [TransformComponent(), ModelComponent(...)])

// Async loading
let entity = try await Entity(named: "scene", in: .main)
let entity = try await Entity(contentsOf: url)

// Clone
let clone = entity.clone(recursive: true)

Entity 属性

属性	类型	描述
name	String	用于查找的标识符
id	ObjectIdentifier	唯一标识
isEnabled	Bool	本地启用状态
isEnabledInHierarchy	Bool	实际启用状态（考虑父级）
isActive	Bool	实体是否位于活动场景中
isAnchored	Bool	是否具有锚定祖先或自身已锚定
scene	RealityKit.Scene?	所属场景
parent	Entity?	父实体
children	Entity.ChildCollection	子实体
components	Entity.ComponentSet	所有附加的组件
anchor	HasAnchoring?	最近的锚定祖先

实体层级方法

entity.addChild(child)
entity.addChild(child, preservingWorldTransform: true)
entity.removeChild(child)
entity.removeFromParent()
entity.findEntity(named: "name")  // Recursive search

Entity 子类

类	用途	关键组件
Entity	基础容器	仅 Transform
ModelEntity	可渲染对象	ModelComponent
AnchorEntity	AR 锚点	AnchoringComponent
PerspectiveCamera	虚拟摄像头	PerspectiveCameraComponent
DirectionalLight	太阳光／定向光	DirectionalLightComponent
PointLight	点光源	PointLightComponent
SpotLight	聚光灯	SpotLightComponent
TriggerVolume	不可见碰撞区域	CollisionComponent
ViewAttachmentEntity	3D 中的 SwiftUI 视图	visionOS
BodyTrackedEntity	身体跟踪实体	BodyTrackingComponent

---

第 2 部分：组件目录

Transform

// Properties
entity.position                    // SIMD3<Float>, local
entity.orientation                 // simd_quatf
entity.scale                      // SIMD3<Float>
entity.transform                  // Transform struct

// World-space
entity.position(relativeTo: nil)
entity.orientation(relativeTo: nil)
entity.setPosition(pos, relativeTo: nil)

// Utilities
entity.look(at: target, from: position, relativeTo: nil)

ModelComponent

let component = ModelComponent(
    mesh: MeshResource.generateBox(size: 0.1),
    materials: [SimpleMaterial(color: .red, isMetallic: true)]
)
entity.components[ModelComponent.self] = component

MeshResource 内置生成器

方法	参数
.generateBox(size:)	SIMD3<Float> 或单个 Float
.generateBox(size:cornerRadius:)	圆角方盒
.generateSphere(radius:)	Float
.generatePlane(width:depth:)	Float、Float
.generatePlane(width:height:)	垂直平面
.generateCylinder(height:radius:)	Float、Float
.generateCone(height:radius:)	Float、Float
.generateText(_:)	String，带选项

CollisionComponent

let component = CollisionComponent(
    shapes: [
        .generateBox(size: SIMD3(0.1, 0.2, 0.1)),
        .generateSphere(radius: 0.05),
        .generateCapsule(height: 0.3, radius: 0.05),
        .generateConvex(from: meshResource)
    ],
    mode: .default,                    // .default or .trigger
    filter: CollisionFilter(
        group: CollisionGroup(rawValue: 1),
        mask: .all
    )
)

ShapeResource 类型

方法	描述	性能
.generateBox(size:)	轴对齐方盒	最快
.generateSphere(radius:)	球体	快
.generateCapsule(height:radius:)	胶囊体	快
.generateConvex(from:)	从网格生成凸包	中等
.generateStaticMesh(from:)	精确网格	最慢（仅限静态）

PhysicsBodyComponent

let component = PhysicsBodyComponent(
    massProperties: .init(
        mass: 1.0,
        inertia: SIMD3(repeating: 0.1),
        centerOfMass: .zero
    ),
    material: .generate(
        staticFriction: 0.5,
        dynamicFriction: 0.3,
        restitution: 0.4
    ),
    mode: .dynamic                     // .dynamic, .static, .kinematic
)

模式	行为
.dynamic	物理模拟控制位置
.static	不可移动，参与碰撞
.kinematic	由代码控制，影响动态刚体

PhysicsMotionComponent

var motion = PhysicsMotionComponent()
motion.linearVelocity = SIMD3(0, 5, 0)
motion.angularVelocity = SIMD3(0, .pi, 0)
entity.components[PhysicsMotionComponent.self] = motion

CharacterControllerComponent

entity.components[CharacterControllerComponent.self] = CharacterControllerComponent(
    radius: 0.3,
    height: 1.8,
    slopeLimit: .pi / 4,
    stepLimit: 0.3
)

// Move character with gravity
entity.moveCharacter(
    by: SIMD3(0.1, -0.01, 0),
    deltaTime: Float(context.deltaTime),
    relativeTo: nil
)

AnchoringComponent

// Plane detection
AnchoringComponent(.plane(.horizontal, classification: .table,
                           minimumBounds: SIMD2(0.2, 0.2)))
AnchoringComponent(.plane(.vertical, classification: .wall,
                           minimumBounds: SIMD2(0.5, 0.5)))

// World position
AnchoringComponent(.world(transform: float4x4(...)))

// Image anchor
AnchoringComponent(.image(group: "AR Resources", name: "poster"))

// Face tracking
AnchoringComponent(.face)

// Body tracking
AnchoringComponent(.body)

平面分类

分类	描述
.table	水平桌面
.floor	地面
.ceiling	天花板
.wall	垂直墙面
.door	门
.window	窗户
.seat	椅子／沙发

光源组件

// Directional
let light = DirectionalLightComponent(
    color: .white,
    intensity: 1000,
    isRealWorldProxy: false
)
light.shadow = DirectionalLightComponent.Shadow(
    maximumDistance: 10,
    depthBias: 0.01
)

// Point
PointLightComponent(
    color: .white,
    intensity: 1000,
    attenuationRadius: 5
)

// Spot
SpotLightComponent(
    color: .white,
    intensity: 1000,
    innerAngleInDegrees: 30,
    outerAngleInDegrees: 60,
    attenuationRadius: 10
)

无障碍功能

var accessibility = AccessibilityComponent()
accessibility.label = "Red cube"
accessibility.value = "Interactive 3D object"
accessibility.traits = .button
accessibility.isAccessibilityElement = true
entity.components[AccessibilityComponent.self] = accessibility

其他组件

组件	用途	平台
OpacityComponent	淡入或淡出实体	全部
GroundingShadowComponent	实体下方的接触阴影	全部
InputTargetComponent	启用手势输入	visionOS
HoverEffectComponent	注视或悬停时高亮显示	visionOS
SynchronizationComponent	多人游戏实体同步	全部
ImageBasedLightComponent	自定义环境光照	全部
ImageBasedLightReceiverComponent	接收来自光源的 IBL	全部

---

第 3 部分：系统 API

系统协议

protocol System {
    init(scene: RealityKit.Scene)
    func update(context: SceneUpdateContext)
}

SceneUpdateContext

属性	类型	描述
deltaTime	TimeInterval	距上次更新的时间
scene	RealityKit.Scene	场景

// Query entities
context.entities(matching: query, updatingSystemWhen: .rendering)

EntityQuery

// Has specific component
EntityQuery(where: .has(HealthComponent.self))

// Has multiple components
EntityQuery(where: .has(HealthComponent.self) && .has(ModelComponent.self))

// Does not have component
EntityQuery(where: .has(EnemyComponent.self) && !.has(DeadComponent.self))

场景事件

事件	触发条件
SceneEvents.Update	每一帧
SceneEvents.DidAddEntity	实体添加到场景
SceneEvents.DidRemoveEntity	实体从场景中移除
SceneEvents.AnchoredStateChanged	锚点跟踪发生变化
CollisionEvents.Began	两个实体开始碰撞
CollisionEvents.Updated	碰撞持续
CollisionEvents.Ended	碰撞结束
AnimationEvents.PlaybackCompleted	动画播放完毕

scene.subscribe(to: CollisionEvents.Began.self, on: entity) { event in
    // event.entityA, event.entityB, event.impulse
}

---

第 4 部分：RealityView API

初始化器

// Basic (iOS 18+, visionOS 1.0+)
RealityView { content in
    // make: Add entities to content
}

// With update
RealityView { content in
    // make
} update: { content in
    // update: Called when SwiftUI state changes
}

// With placeholder
RealityView { content in
    // make (async loading)
} placeholder: {
    ProgressView()
}

// With attachments (visionOS)
RealityView { content, attachments in
    // make
} update: { content, attachments in
    // update
} attachments: {
    Attachment(id: "label") { Text("Hello") }
}

RealityViewContent

content.add(entity)
content.remove(entity)
content.entities          // EntityCollection

// iOS/macOS — camera content
content.camera            // RealityViewCameraContent (non-visionOS)

RealityView 上的手势

RealityView { content in ... }
    .gesture(TapGesture().targetedToAnyEntity().onEnded { value in
        let entity = value.entity
    })
    .gesture(DragGesture().targetedToAnyEntity().onChanged { value in
        value.entity.position = value.convert(value.location3D,
            from: .local, to: .scene)
    })
    .gesture(RotateGesture().targetedToAnyEntity().onChanged { value in
        // Handle rotation
    })
    .gesture(MagnifyGesture().targetedToAnyEntity().onChanged { value in
        // Handle scale
    })

---

第 5 部分：Model3D API

// Simple display
Model3D(named: "robot")

// With phases
Model3D(named: "robot") { phase in
    switch phase {
    case .empty:
        ProgressView()
    case .success(let model):
        model.resizable().scaledToFit()
    case .failure(let error):
        Text("Failed: \(error.localizedDescription)")
    @unknown default:
        EmptyView()
    }
}

// From URL
Model3D(url: modelURL)

---

第 6 部分：材质系统

SimpleMaterial

var material = SimpleMaterial()
material.color = .init(tint: .blue)
material.metallic = .init(floatLiteral: 1.0)
material.roughness = .init(floatLiteral: 0.3)

PhysicallyBasedMaterial

var material = PhysicallyBasedMaterial()
material.baseColor = .init(tint: .white,
    texture: .init(try .load(named: "albedo")))
material.metallic = .init(floatLiteral: 0.0)
material.roughness = .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(color: .blue)
material.emissiveIntensity = 2.0
material.clearcoat = .init(floatLiteral: 0.8)
material.clearcoatRoughness = .init(floatLiteral: 0.1)
material.specular = .init(floatLiteral: 0.5)
material.sheen = .init(color: .white)
material.anisotropyLevel = .init(floatLiteral: 0.5)
material.blending = .transparent(opacity: .init(floatLiteral: 0.5))
material.faceCulling = .back            // .none, .front, .back

UnlitMaterial

var material = UnlitMaterial()
material.color = .init(tint: .red,
    texture: .init(try .load(named: "texture")))
material.blending = .transparent(opacity: .init(floatLiteral: 0.8))

特殊材质

// Occlusion — invisible but hides content behind it
let occlusionMaterial = OcclusionMaterial()

// Video
let videoMaterial = VideoMaterial(avPlayer: avPlayer)

TextureResource 加载

// From bundle
let texture = try await TextureResource(named: "texture")

// From URL
let texture = try await TextureResource(contentsOf: url)

// With options
let texture = try await TextureResource(named: "texture",
    options: .init(semantic: .color))  // .color, .raw, .normal, .hdrColor

---

第 7 部分：动画

Transform 动画

entity.move(
    to: Transform(
        scale: .one,
        rotation: targetRotation,
        translation: targetPosition
    ),
    relativeTo: entity.parent,
    duration: 1.5,
    timingFunction: .easeInOut
)

计时函数

函数	曲线
.default	系统默认
.linear	匀速
.easeIn	缓慢开始
.easeOut	缓慢结束
.easeInOut	缓慢开始和结束

播放已加载的动画

// All animations from USD
for animation in entity.availableAnimations {
    let controller = entity.playAnimation(animation)
}

// With options
let controller = entity.playAnimation(
    animation.repeat(count: 3),
    transitionDuration: 0.3,
    startsPaused: false
)

AnimationPlaybackController

let controller = entity.playAnimation(animation)
controller.pause()
controller.resume()
controller.stop()
controller.speed = 0.5            // Half speed
controller.blendFactor = 1.0      // Full blend
controller.isComplete             // Check completion

---

第 8 部分：音频

AudioFileResource

// Load
let resource = try AudioFileResource.load(
    named: "sound.wav",
    configuration: .init(
        shouldLoop: true,
        shouldRandomizeStartTime: false,
        mixGroupName: "effects"
    )
)

音频组件

// Spatial (3D positional)
entity.components[SpatialAudioComponent.self] = SpatialAudioComponent(
    directivity: .beam(focus: 0.5),
    distanceAttenuation: .rolloff(factor: 1.0),
    gain: 0                          // dB
)

// Ambient (non-positional, uniform)
entity.components[AmbientAudioComponent.self] = AmbientAudioComponent(
    gain: -6
)

// Channel (multi-channel output)
entity.components[ChannelAudioComponent.self] = ChannelAudioComponent(
    gain: 0
)

播放

let controller = entity.playAudio(resource)
controller.pause()
controller.stop()
controller.gain = -3               // Adjust volume (dB)
controller.speed = 1.5             // Pitch shift

entity.stopAllAudio()

---

第 9 部分：RealityRenderer（Metal 集成）

// Low-level Metal rendering of RealityKit content
let renderer = try RealityRenderer()
renderer.entities.append(entity)

// Render to Metal texture
let descriptor = RealityRenderer.CameraOutput.Descriptor(
    colorFormat: .bgra8Unorm,
    depthFormat: .depth32Float
)
try renderer.render(
    viewMatrix: viewMatrix,
    projectionMatrix: projectionMatrix,
    size: size,
    colorTexture: colorTexture,
    depthTexture: depthTexture
)

---

资源

WWDC：2019-603、2019-605、2021-10074、2022-10074、2023-10080、2024-10103、2024-10153

文档：/realitykit、/realitykit/entity、/realitykit/component、/realitykit/system、/realitykit/realityview、/realitykit/model3d、/realitykit/modelentity、/realitykit/anchorentity、/realitykit/physicallybasedmaterial

技能：axiom-realitykit、axiom-realitykit-diag、axiom-scenekit-ref