🎲 RealityKit

⭐ Difficulty: ⭐⭐⭐⭐ ⏱️ Est. Time: 3-4h 📂 Graphics & Media

사실적인 3D 렌더링과 AR 경험

iOS 13+visionOS 최적화

✨ RealityKit is?

RealityKit is Apple's high-performance 3D rendering engine, integrated with ARKit to deliver realistic AR experiences. It supports physics, animation, spatial audio, photorealistic rendering, and integrates seamlessly with SwiftUI.

💡 Key Features: PBR Rendering · Physics Simulation · Animation · Spatial Audio · Entity Component System · USD Support · Reality Composer · visionOS Support

🎯 1. Basic Scene Setup

RealityKit으로 3D 씬을 생성.

RealityKitView.swift — Basic Setup

import SwiftUI
import RealityKit

struct RealityKitView: View {
    var body: some View {
        RealityView { content in
            // 3D 박스 생성
            let mesh = MeshResource.generateBox(size: 0.3)

            // PBR 머티리얼 (Physically Based Rendering)
            var material = PhysicallyBasedMaterial()
            material.baseColor = .init(tint: .blue)
            material.roughness = .init(floatLiteral: 0.3)
            material.metallic = .init(floatLiteral: 0.8)

            // 엔티티 생성
            let entity = ModelEntity(mesh: mesh, materials: [material])

            // 위치 설정
            entity.position = [0, 0, -0.5]

            // 씬에 추가
            content.add(entity)
        }
    }
}

🎨 2. 머티리얼과 텍스처

다양한 머티리얼로 사실적인 표면을 만듭.

Materials.swift — 머티리얼 설정

import RealityKit

class MaterialsManager {
    // 1. 물리 기반 머티리얼 (PBR)
    func createMetalMaterial() -> PhysicallyBasedMaterial {
        var material = PhysicallyBasedMaterial()

        // 기본 색상
        material.baseColor = .init(tint: .gray)

        // 금속성 (0.0 = 비금속, 1.0 = 완전 금속)
        material.metallic = .init(floatLiteral: 1.0)

        // 거칠기 (0.0 = 매끄러움, 1.0 = 거침)
        material.roughness = .init(floatLiteral: 0.2)

        return material
    }

    // 2. 단순 머티리얼
    func createSimpleMaterial() -> SimpleMaterial {
        var material = SimpleMaterial()
        material.color = .init(tint: .red, texture: nil)
        return material
    }

    // 3. 텍스처 적용
    func createTexturedMaterial() async throws -> PhysicallyBasedMaterial {
        var material = PhysicallyBasedMaterial()

        // 이미지에서 텍스처 로드
        if let texture = try? await TextureResource(named: "wood.jpg") {
            material.baseColor = .init(texture: .init(texture))
        }

        return material
    }

    // 4. 발광 머티리얼
    func createEmissiveMaterial() -> PhysicallyBasedMaterial {
        var material = PhysicallyBasedMaterial()

        // 발광 색상 및 강도
        material.emissiveColor = .init(color: .yellow)
        material.emissiveIntensity = 2.0

        return material
    }

    // 5. 투명 머티리얼
    func createTransparentMaterial() -> PhysicallyBasedMaterial {
        var material = PhysicallyBasedMaterial()
        material.baseColor = .init(tint: .blue.withAlphaComponent(0.5))
        material.blending = .transparent
        return material
    }
}

🎬 3. 애니메이션

엔티티에 움직임 is added.

Animations.swift — 애니메이션

import RealityKit

extension Entity {
    // 1. 회전 애니메이션
    func addRotationAnimation() {
        // 360도 회전
        let rotation = Transform(
            pitch: 0,
            yaw: .Float.pi * 2,
            roll: 0
        )

        // 애니메이션 생성
        let rotationAnimation = FromToByAnimation(
            to: rotation,
            duration: 3.0,
            timing: .linear,
            isAdditive: true
        )

        // 무한 반복
        let animation = try? AnimationResource.generate(with: rotationAnimation)
        if let animation {
            playAnimation(animation.repeat())
        }
    }

    // 2. 이동 애니메이션
    func moveAnimation(to position: SIMD3<Float>, duration: TimeInterval) {
        var transform = self.transform
        transform.translation = position

        move(
            to: transform,
            relativeTo: parent,
            duration: duration,
            timingFunction: .easeInOut
        )
    }

    // 3. 스케일 애니메이션
    func pulseAnimation() {
        let originalScale = scale
        let targetScale = originalScale * 1.2

        let scaleUp = FromToByAnimation(
            to: Transform(scale: targetScale),
            duration: 0.5,
            timing: .easeInOut
        )

        let scaleDown = FromToByAnimation(
            to: Transform(scale: originalScale),
            duration: 0.5,
            timing: .easeInOut
        )

        // 시퀀스 애니메이션
        if let animation = try? AnimationResource.sequence([
            .generate(with: scaleUp),
            .generate(with: scaleDown)
        ].compactMap { $0 }) {
            playAnimation(animation.repeat())
        }
    }

    // 4. 바운스 애니메이션
    func bounceAnimation() {
        let originalY = position.y
        let jumpHeight: Float = 0.3

        var upTransform = transform
        upTransform.translation.y += jumpHeight

        // 위로
        move(to: upTransform, relativeTo: parent, duration: 0.5, timingFunction: .easeOut)

        // 잠시 후 아래로
        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
            guard let self else { return }
            var downTransform = self.transform
            downTransform.translation.y = originalY
            self.move(to: downTransform, relativeTo: parent, duration: 0.5, timingFunction: .easeIn)
        }
    }
}

⚙️ 4. 물리 엔진

현실적인 물리 시뮬레이션 is added.

Physics.swift — Physics Simulation

import RealityKit

class PhysicsManager {
    // 1. 동적 물리 (중력 적용)
    func addDynamicPhysics(to entity: Entity) {
        // 충돌 형태 생성
        entity.generateCollisionShapes(recursive: true)

        // 동적 물리 바디 (중력 적용)
        entity.components[PhysicsBodyComponent.self] = PhysicsBodyComponent(
            massProperties: .default,
            mode: .dynamic
        )
    }

    // 2. 정적 물리 (고정된 객체)
    func addStaticPhysics(to entity: Entity) {
        entity.generateCollisionShapes(recursive: true)

        // 정적 물리 바디 (움직이지 않음)
        entity.components[PhysicsBodyComponent.self] = PhysicsBodyComponent(
            mode: .static
        )
    }

    // 3. 커스텀 질량과 마찰력
    func createCustomPhysicsBody() -> PhysicsBodyComponent {
        // 질량 속성
        let mass: Float = 2.0
        let massProperties = PhysicsMassProperties(mass: mass)

        // 물리 머티리얼 (마찰, 탄성)
        let physicsMaterial = PhysicsMaterialResource.generate(
            friction: .init(staticFriction: 0.5, dynamicFriction: 0.3),
            restitution: 0.8 // 탄성 (0 = 흡수, 1 = 완전 반발)
        )

        return PhysicsBodyComponent(
            massProperties: massProperties,
            material: physicsMaterial,
            mode: .dynamic
        )
    }

    // 4. 힘 적용
    func applyForce(to entity: Entity, force: SIMD3<Float>) {
        guard var physicsBody = entity.components[PhysicsBodyComponent.self] else { return }

        // 힘 적용
        physicsBody.applyImpulse(force, relativeTo: nil)
        entity.components[PhysicsBodyComponent.self] = physicsBody
    }

    // 5. 충돌 감지
    func setupCollisionDetection(for entity: Entity) {
        // 충돌 그룹 설정
        entity.components[CollisionComponent.self] = CollisionComponent(
            shapes: [.generateBox(size: [0.1, 0.1, 0.1])],
            mode: .trigger,
            filter: .init(group: .all, mask: .all)
        )
    }
}

🔊 5. 공간 오디오

3D 공간에서 사실적인 오디오를 재생.

SpatialAudio.swift — 공간 오디오

import RealityKit

class SpatialAudioManager {
    // 공간 오디오 추가
    func addSpatialAudio(to entity: Entity, audioFile: String) async {
        // 오디오 리소스 로드
        guard let audioResource = try? await AudioFileResource(named: audioFile) else {
            print("오디오 로드 실패")
            return
        }

        // 공간 오디오 컨트롤러
        let audioController = entity.prepareAudio(audioResource)

        // 재생 옵션
        audioController.gain = 1.0
        audioController.fade(to: .max, duration: 1.0)

        // 재생
        audioController.play()
    }

    // 반복 재생
    func playLoopingAudio(entity: Entity, audioFile: String) async {
        guard let resource = try? await AudioFileResource(named: audioFile) else { return }

        let controller = entity.playAudio(resource)
        controller.isLooping = true
    }
}

📱 SwiftUI Integration Example

RealityKitDemoView.swift — Complete Demo

import SwiftUI
import RealityKit

struct RealityKitDemoView: View {
    @State private var selectedShape: Shape = .box

    enum Shape: String, CaseIterable {
        case box = "박스"
        case sphere = "구"
        case cylinder = "원기둥"
    }

    var body: some View {
        VStack {
            // 3D 뷰
            RealityView { content in
                // 초기 씬 설정
                setupScene(content)
            } update: { content in
                // 선택된 도형으로 업데이트
                updateShape(content, shape: selectedShape)
            }

            // 컨트롤
            Picker("도형 선택", selection: $selectedShape) {
                ForEach(Shape.allCases, id: \.self) { shape in
                    Text(shape.rawValue).tag(shape)
                }
            }
            .pickerStyle(.segmented)
            .padding()
        }
    }

    func setupScene(_ content: RealityViewContent) {
        // 조명 추가
        let light = PointLight()
        light.position = [0, 0.5, 0]
        light.light.intensity = 1000
        content.add(light)

        // 초기 도형
        let entity = createShape(.box)
        content.add(entity)
    }

    func updateShape(_ content: RealityViewContent, shape: Shape) {
        // 기존 엔티티 제거
        content.entities.forEach { entity in
            if entity is ModelEntity {
                content.remove(entity)
            }
        }

        // 새 도형 추가
        let entity = createShape(shape)
        content.add(entity)
    }

    func createShape(_ shape: Shape) -> ModelEntity {
        let mesh: MeshResource

        switch shape {
        case .box:
            mesh = .generateBox(size: 0.2)
        case .sphere:
            mesh = .generateSphere(radius: 0.1)
        case .cylinder:
            mesh = .generateCylinder(height: 0.2, radius: 0.1)
        }

        var material = PhysicallyBasedMaterial()
        material.baseColor = .init(tint: .blue)
        material.metallic = 0.8
        material.roughness = 0.2

        let entity = ModelEntity(mesh: mesh, materials: [material])
        entity.position = [0, 0, -0.5]

        // 회전 애니메이션
        entity.addRotationAnimation()

        return entity
    }
}

💡 HIG Guidelines

성능: Optimize complex models with LOD (Level of Detail)
조명: 현실적인 조명으로 깊이감 제공
스케일: 실제 크기에 맞는 스케일 사용
물리: 과도한 물리 시뮬레이션은 성능 저하
텍스처: 압축된 텍스처 사용으로 메모리 절약

🎯 Practical Usage

제품 시각화: 3D 제품 뷰어
AR Games: 물리 기반 게임 메커닉
건축 시각화: 건물 내부 탐색
교육: 3D 모델로 학습
visionOS 앱: 공간 컴퓨팅 경험

📚 Learn More

⚡️ Reality Composer: Apple's tool for designing AR scenes without code. Load .rcproject files created in Reality Composer directly into RealityKit.

📎 Apple Official Resources

📘 Documentation 🎬 WWDC Sessions