axiom-realitykit-ref

RealityKit API リファレンス

カテゴリ別にまとめた RealityKit の完全な API リファレンスです。

このリファレンスを使用する場面

次のような場合に、このリファレンスを使用してください。

• 特定の RealityKit API のシグネチャやプロパティを調べる
• 利用可能なコンポーネントの種類を確認する
• AR エクスペリエンスに適したアンカーの種類を見つける
• マテリアルのプロパティやオプションを確認する
• 物理ボディのパラメーターを設定する
• アニメーションやオーディオ API の詳細を調べる
• 特定の API が利用可能なプラットフォームを確認する

---

パート 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 のプロパティ

プロパティ	型	説明
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 の階層メソッド

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	2 つのエンティティが衝突し始めたとき
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：アニメーション

トランスフォームアニメーション

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