📳 Core Haptics

정교한 촉각 피드백 디자인 프레임워크

iOS 13+Taptic Engine

✨ Core Haptics란?

Core Haptics는 iPhone의 Taptic Engine을 활용하여 정교하고 커스터마이즈 가능한 촉각 피드백을 만드는 프레임워크입니다. 단순한 진동을 넘어 강도, 선명도, 지속 시간을 조절하여 게임, 앱, 사용자 인터랙션에 몰입감 있는 촉각 경험을 제공합니다. AHAP 파일을 통해 복잡한 햅틱 패턴을 저장하고 재생할 수 있습니다.

💡 핵심 기능: 커스텀 햅틱 패턴 · 연속/순간 이벤트 · 강도 조절 · 선명도 조절 · AHAP 파일 지원 · 오디오-햅틱 동기화 · 동적 매개변수

🎮 1. CHHapticEngine 초기화

CHHapticEngine을 생성하고 시작합니다.

HapticManager.swift — 엔진 초기화

import CoreHaptics
import SwiftUI

@Observable
class HapticManager {
    private var engine: CHHapticEngine?
    var supportsHaptics = false

    init() {
        prepareHaptics()
    }

    // 햅틱 엔진 준비
    func prepareHaptics() {
        // 디바이스가 햅틱을 지원하는지 확인
        guard CHHapticEngine.capabilitiesForHardware().supportsHaptics else {
            print("⚠️ 햅틱 미지원 디바이스")
            return
        }

        do {
            // 엔진 생성
            engine = try CHHapticEngine()
            supportsHaptics = true

            // 엔진 시작
            try engine?.start()

            // 엔진 정지 핸들러
            engine?.stoppedHandler = { reason in
                print("⚠️ 엔진 정지: \(reason)")
            }

            // 엔진 리셋 핸들러
            engine?.resetHandler = { [weak self] in
                print("🔄 엔진 리셋")
                do {
                    try self?.engine?.start()
                } catch {
                    print("❌ 엔진 재시작 실패: \(error)")
                }
            }

            print("✅ 햅틱 엔진 준비 완료")
        } catch {
            print("❌ 햅틱 엔진 생성 실패: \(error)")
        }
    }

    // 엔진 시작
    func startEngine() {
        guard supportsHaptics else { return }

        do {
            try engine?.start()
        } catch {
            print("❌ 엔진 시작 실패: \(error)")
        }
    }

    // 엔진 정지
    func stopEngine() {
        engine?.stop()
    }
}

💥 2. 순간 햅틱 이벤트

순간적인 탭이나 충격을 표현하는 Transient 이벤트를 만듭니다.

TransientHaptics.swift — 순간 햅틱

import CoreHaptics

extension HapticManager {
    // 기본 탭 햅틱
    func playSimpleTap() {
        guard supportsHaptics, let engine = engine else { return }

        do {
            // 순간 이벤트 생성
            let event = CHHapticEvent(
                eventType: .hapticTransient,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 1.0)
                ],
                relativeTime: 0
            )

            // 패턴 생성 및 재생
            let pattern = try CHHapticPattern(events: [event], parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)

            print("✅ 탭 햅틱 재생")
        } catch {
            print("❌ 햅틱 재생 실패: \(error)")
        }
    }

    // 커스텀 강도의 탭
    func playTap(intensity: Float, sharpness: Float) {
        guard supportsHaptics, let engine = engine else { return }

        do {
            let event = CHHapticEvent(
                eventType: .hapticTransient,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: intensity),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: sharpness)
                ],
                relativeTime: 0
            )

            let pattern = try CHHapticPattern(events: [event], parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)
        } catch {
            print("❌ 햅틱 재생 실패: \(error)")
        }
    }

    // 연속 탭 패턴
    func playDoubleTap() {
        guard supportsHaptics, let engine = engine else { return }

        do {
            let events = [
                CHHapticEvent(
                    eventType: .hapticTransient,
                    parameters: [
                        CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
                        CHHapticEventParameter(parameterID: .hapticSharpness, value: 1.0)
                    ],
                    relativeTime: 0
                ),
                CHHapticEvent(
                    eventType: .hapticTransient,
                    parameters: [
                        CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
                        CHHapticEventParameter(parameterID: .hapticSharpness, value: 1.0)
                    ],
                    relativeTime: 0.2 // 0.2초 후 두 번째 탭
                )
            ]

            let pattern = try CHHapticPattern(events: events, parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)

            print("✅ 더블 탭 햅틱 재생")
        } catch {
            print("❌ 햅틱 재생 실패: \(error)")
        }
    }
}

🌊 3. 연속 햅틱 이벤트

지속적인 진동을 표현하는 Continuous 이벤트를 만듭니다.

ContinuousHaptics.swift — 연속 햅틱

import CoreHaptics

extension HapticManager {
    // 연속 진동 (1초)
    func playContinuousHaptic(duration: TimeInterval = 1.0) {
        guard supportsHaptics, let engine = engine else { return }

        do {
            // 연속 이벤트 생성
            let event = CHHapticEvent(
                eventType: .hapticContinuous,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.7),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.5)
                ],
                relativeTime: 0,
                duration: duration
            )

            let pattern = try CHHapticPattern(events: [event], parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)

            print("✅ 연속 햅틱 재생")
        } catch {
            print("❌ 햅틱 재생 실패: \(error)")
        }
    }

    // 강도가 변하는 연속 햅틱
    func playFadingHaptic() {
        guard supportsHaptics, let engine = engine else { return }

        do {
            // 강도가 점차 감소하는 연속 이벤트
            let event = CHHapticEvent(
                eventType: .hapticContinuous,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.5)
                ],
                relativeTime: 0,
                duration: 2.0
            )

            // 강도 감소 매개변수 커브
            let parameterCurve = CHHapticParameterCurve(
                parameterID: .hapticIntensityControl,
                controlPoints: [
                    CHHapticParameterCurve.ControlPoint(relativeTime: 0, value: 1.0),
                    CHHapticParameterCurve.ControlPoint(relativeTime: 2.0, value: 0.0)
                ],
                relativeTime: 0
            )

            let pattern = try CHHapticPattern(
                events: [event],
                parameterCurves: [parameterCurve]
            )

            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)

            print("✅ 페이드 아웃 햅틱 재생")
        } catch {
            print("❌ 햅틱 재생 실패: \(error)")
        }
    }

    // 펄스 패턴 (박동)
    func playPulsePattern() {
        guard supportsHaptics, let engine = engine else { return }

        do {
            var events: [CHHapticEvent] = []

            // 5번의 펄스 생성
            for i in 0..<5 {
                let event = CHHapticEvent(
                    eventType: .hapticTransient,
                    parameters: [
                        CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.8),
                        CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.5)
                    ],
                    relativeTime: TimeInterval(i) * 0.3
                )
                events.append(event)
            }

            let pattern = try CHHapticPattern(events: events, parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)

            print("✅ 펄스 패턴 재생")
        } catch {
            print("❌ 햅틱 재생 실패: \(error)")
        }
    }
}

📄 4. AHAP 파일

복잡한 햅틱 패턴을 AHAP 파일로 저장하고 로드합니다.

AHAPLoader.swift — AHAP 파일 로드

import CoreHaptics

extension HapticManager {
    // AHAP 파일에서 패턴 로드
    func playAHAPFile(named fileName: String) {
        guard supportsHaptics, let engine = engine else { return }

        do {
            // AHAP 파일 경로 가져오기
            guard let url = Bundle.main.url(
                forResource: fileName,
                withExtension: "ahap"
            ) else {
                print("❌ AHAP 파일을 찾을 수 없음")
                return
            }

            // 패턴 생성
            let pattern = try CHHapticPattern(contentsOf: url)

            // 플레이어 생성 및 재생
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)

            print("✅ AHAP 파일 재생: \(fileName)")
        } catch {
            print("❌ AHAP 파일 재생 실패: \(error)")
        }
    }

    // AHAP 패턴을 파일로 저장
    func savePattern(_ pattern: CHHapticPattern, to fileName: String) {
        do {
            // 패턴을 딕셔너리로 변환
            let dictionary = pattern.exportDictionary()

            // JSON 데이터 생성
            let jsonData = try JSONSerialization.data(
                withJSONObject: dictionary,
                options: .prettyPrinted
            )

            // 파일로 저장
            let url = FileManager.default
                .urls(for: .documentDirectory, in: .userDomainMask)[0]
                .appendingPathComponent("\(fileName).ahap")

            try jsonData.write(to: url)

            print("✅ AHAP 파일 저장: \(url)")
        } catch {
            print("❌ AHAP 파일 저장 실패: \(error)")
        }
    }
}

// AHAP 파일 예제 구조 (JSON)
/*
{
  "Pattern": [
    {
      "Event": {
        "Time": 0.0,
        "EventType": "HapticTransient",
        "EventParameters": [
          { "ParameterID": "HapticIntensity", "ParameterValue": 1.0 },
          { "ParameterID": "HapticSharpness", "ParameterValue": 1.0 }
        ]
      }
    }
  ]
}
*/

🎨 5. 게임용 햅틱 패턴

게임에서 사용할 수 있는 다양한 햅틱 패턴을 구현합니다.

GameHaptics.swift — 게임용 햅틱

import CoreHaptics

extension HapticManager {
    // 충돌 효과
    func playCollisionHaptic(intensity: Float) {
        guard supportsHaptics, let engine = engine else { return }

        do {
            let event = CHHapticEvent(
                eventType: .hapticTransient,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: intensity),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 1.0)
                ],
                relativeTime: 0
            )

            let pattern = try CHHapticPattern(events: [event], parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)
        } catch {
            print("❌ 충돌 햅틱 실패: \(error)")
        }
    }

    // 폭발 효과
    func playExplosionHaptic() {
        guard supportsHaptics, let engine = engine else { return }

        do {
            // 강한 초기 충격
            let impact = CHHapticEvent(
                eventType: .hapticTransient,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 1.0)
                ],
                relativeTime: 0
            )

            // 여진
            let rumble = CHHapticEvent(
                eventType: .hapticContinuous,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.5),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.3)
                ],
                relativeTime: 0.1,
                duration: 0.5
            )

            let pattern = try CHHapticPattern(events: [impact, rumble], parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)
        } catch {
            print("❌ 폭발 햅틱 실패: \(error)")
        }
    }

    // 엔진 소리 (지속적인 진동)
    func playEngineHaptic() {
        guard supportsHaptics, let engine = engine else { return }

        do {
            let event = CHHapticEvent(
                eventType: .hapticContinuous,
                parameters: [
                    CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.6),
                    CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.2)
                ],
                relativeTime: 0,
                duration: 3.0
            )

            let pattern = try CHHapticPattern(events: [event], parameters: [])
            let player = try engine.makePlayer(with: pattern)
            try player.start(atTime: 0)
        } catch {
            print("❌ 엔진 햅틱 실패: \(error)")
        }
    }
}

📱 종합 예제

HapticDemoView.swift — 햅틱 데모 앱

import SwiftUI

struct HapticDemoView: View {
    @State private var hapticManager = HapticManager()
    @State private var intensity: Float = 0.5
    @State private var sharpness: Float = 0.5

    var body: some View {
        NavigationStack {
            Form {
                Section("기본 햅틱") {
                    Button("단순 탭") {
                        hapticManager.playSimpleTap()
                    }

                    Button("더블 탭") {
                        hapticManager.playDoubleTap()
                    }

                    Button("연속 진동") {
                        hapticManager.playContinuousHaptic()
                    }
                }

                Section("커스텀 햅틱") {
                    VStack(alignment: .leading, spacing: 12) {
                        Text("강도: \(String(format: "%.2f", intensity))")
                        Slider(value: $intensity, in: 0...1)

                        Text("선명도: \(String(format: "%.2f", sharpness))")
                        Slider(value: $sharpness, in: 0...1)

                        Button("테스트") {
                            hapticManager.playTap(intensity: intensity, sharpness: sharpness)
                        }
                        .frame(maxWidth: .infinity)
                        .buttonStyle(.borderedProminent)
                    }
                }

                Section("패턴") {
                    Button("페이드 아웃") {
                        hapticManager.playFadingHaptic()
                    }

                    Button("펄스 패턴") {
                        hapticManager.playPulsePattern()
                    }
                }

                Section("게임 효과") {
                    Button("충돌") {
                        hapticManager.playCollisionHaptic(intensity: 0.8)
                    }

                    Button("폭발") {
                        hapticManager.playExplosionHaptic()
                    }

                    Button("엔진 소리") {
                        hapticManager.playEngineHaptic()
                    }
                }

                Section {
                    Text("햅틱 지원: \(hapticManager.supportsHaptics ? "✅" : "❌")")
                        .foregroundStyle(.secondary)
                }
            }
            .navigationTitle("햅틱 데모")
        }
    }
}

💡 HIG 가이드라인

적절한 사용: 의미 있는 인터랙션에만 햅틱 사용
과도한 사용 금지: 너무 빈번한 햅틱은 사용자를 피로하게 함
디바이스 확인: 햅틱 지원 여부 확인 필수
설정 존중: 시스템 햅틱 설정 존중
오디오와 조화: 사운드와 햅틱을 함께 사용하면 더 강력한 효과

🎯 실전 활용

게임: 충돌, 폭발, 발사 등의 물리적 피드백
UI 인터랙션: 버튼 탭, 스위치 토글, 슬라이더 조작
알림: 중요한 이벤트에 대한 촉각 알림
미디어 앱: 음악 비트에 맞춘 햅틱
접근성: 시각 장애인을 위한 촉각 피드백

📚 더 알아보기

⚡️ 성능 팁: 햅틱 엔진은 앱이 백그라운드로 가면 자동으로 중지됩니다. 포그라운드로 돌아올 때 resetHandler를 사용하여 자동으로 재시작하도록 설정하세요. AHAP 파일을 사용하면 복잡한 패턴을 효율적으로 관리할 수 있습니다.