RealityKit API reference — Entity, Component, System, RealityView, Model3D, anchor types, material system, physics, collision, animation, audio, accessibility

SKILL.md•axiom-realitykit-ref

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

> axiom-realitykit-ref