RealityKit API Reference

Complete API reference for RealityKit organized by category.

When to Use This Reference

Use this reference when:

• Looking up specific RealityKit API signatures or properties

• Checking which component types are available

• Finding the right anchor type for an AR experience

• Browsing material properties and options

• Setting up physics body parameters

• Looking up animation or audio API details

• Checking platform availability for specific APIs

Part 1: Entity 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 Properties

Property Type Description

name

String

Identifier for lookup

id

ObjectIdentifier

Unique identity

isEnabled

Bool

Local enabled state

isEnabledInHierarchy

Bool

Effective enabled (considers parents)

isActive

Bool

Entity is in an active scene

isAnchored

Bool

Has anchoring or anchored ancestor

scene

RealityKit.Scene?

Owning scene

parent

Entity?

Parent entity

children

Entity.ChildCollection

Child entities

components

Entity.ComponentSet

All attached components

anchor

HasAnchoring?

Nearest anchoring ancestor

Entity Hierarchy Methods

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

Entity Subclasses

Class Purpose Key Component

Entity

Base container Transform only

ModelEntity

Renderable object ModelComponent

AnchorEntity

AR anchor point AnchoringComponent

PerspectiveCamera

Virtual camera PerspectiveCameraComponent

DirectionalLight

Sun/directional DirectionalLightComponent

PointLight

Point light PointLightComponent

SpotLight

Spot light SpotLightComponent

TriggerVolume

Invisible collision zone CollisionComponent

ViewAttachmentEntity

SwiftUI view in 3D visionOS

BodyTrackedEntity

Body-tracked entity BodyTrackingComponent

Part 2: Component Catalog

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 Built-in Generators

Method Parameters

.generateBox(size:)

SIMD3<Float> or single Float

.generateBox(size:cornerRadius:)

Rounded box

.generateSphere(radius:)

Float

.generatePlane(width:depth:)

Float , Float

.generatePlane(width:height:)

Vertical plane

.generateCylinder(height:radius:)

Float , Float

.generateCone(height:radius:)

Float , Float

.generateText(_:)

String , with options

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 Types

Method Description Performance

.generateBox(size:)

Axis-aligned box Fastest

.generateSphere(radius:)

Sphere Fast

.generateCapsule(height:radius:)

Capsule Fast

.generateConvex(from:)

Convex hull from mesh Moderate

.generateStaticMesh(from:)

Exact mesh Slowest (static only)

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 )

Mode Behavior

.dynamic

Physics simulation controls position

.static

Immovable, participates in collisions

.kinematic

Code-controlled, affects dynamic bodies

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)

Plane Classification

Classification Description

.table

Horizontal table surface

.floor

Floor surface

.ceiling

Ceiling surface

.wall

Vertical wall

.door

Door

.window

Window

.seat

Chair/couch

Light Components

// 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 )

Accessibility

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

Additional Components

Component Purpose Platform

OpacityComponent

Fade entity in/out All

GroundingShadowComponent

Contact shadow beneath entity All

InputTargetComponent

Enable gesture input visionOS

HoverEffectComponent

Highlight on gaze/hover visionOS

SynchronizationComponent

Multiplayer entity sync All

ImageBasedLightComponent

Custom environment lighting All

ImageBasedLightReceiverComponent

Receive IBL from source All

Part 3: System API

System Protocol

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

SceneUpdateContext

Property Type Description

deltaTime

TimeInterval

Time since last update

scene

RealityKit.Scene

The 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))

Scene Events

Event Trigger

SceneEvents.Update

Every frame

SceneEvents.DidAddEntity

Entity added to scene

SceneEvents.DidRemoveEntity

Entity removed from scene

SceneEvents.AnchoredStateChanged

Anchor tracking changes

CollisionEvents.Began

Two entities start colliding

CollisionEvents.Updated

Collision continues

CollisionEvents.Ended

Collision ends

AnimationEvents.PlaybackCompleted

Animation finishes

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

Part 4: RealityView API

Initializers

// 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)

Gestures on 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 })

Part 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)

Part 6: Material System

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))

Special Materials

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

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

TextureResource Loading

// 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

Part 7: Animation

Transform Animation

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

Timing Functions

Function Curve

.default

System default

.linear

Constant speed

.easeIn

Slow start

.easeOut

Slow end

.easeInOut

Slow start and end

Playing Loaded Animations

// 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

Part 8: Audio

AudioFileResource

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

Audio Components

// 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 )

Playback

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

entity.stopAllAudio()

Part 9: RealityRenderer (Metal Integration)

// 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 )

Resources

WWDC: 2019-603, 2019-605, 2021-10074, 2022-10074, 2023-10080, 2024-10103, 2024-10153

Docs: /realitykit, /realitykit/entity, /realitykit/component, /realitykit/system, /realitykit/realityview, /realitykit/model3d, /realitykit/modelentity, /realitykit/anchorentity, /realitykit/physicallybasedmaterial

Skills: axiom-realitykit, axiom-realitykit-diag, axiom-scenekit-ref