Repository Public License
1// ORIX Alarm2// File: App/Wake/HapticEngine.swift3// Description: Core Haptics engine with one distinct pattern per feedback event, restart handling and a UIKit fallback.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import CoreHaptics8import UIKit910/// Plays the app's haptic vocabulary. Use through `Haptics.play`.11final class HapticEngine {12 static let shared = HapticEngine()1314 /// False on devices without a Taptic Engine and in the simulator: the UIKit generators are used instead.15 let supportsCoreHaptics = CHHapticEngine.capabilitiesForHardware().supportsHaptics16 private var engine: CHHapticEngine?17 private var isRunning = false18 /// Players are cached per event; they die with the engine and are rebuilt after a reset.19 private var players: [Haptics.Event: any CHHapticPatternPlayer] = [:]20 private var lastTick: TimeInterval = 021 private let selectionGenerator = UISelectionFeedbackGenerator()22 private let notificationGenerator = UINotificationFeedbackGenerator()2324 private init() {}2526 func prepare() {27 if supportsCoreHaptics { _ = startedEngine() } else { selectionGenerator.prepare() }28 }2930 func play(_ event: Haptics.Event) {31 if event == .tick {32 // A fast wheel can ask for hundreds of ticks per second: keep at most one every 28 ms.33 let now = ProcessInfo.processInfo.systemUptime34 guard now - lastTick >= 0.028 else { return }35 lastTick = now36 }37 guard supportsCoreHaptics, let engine = startedEngine() else { return playFallback(event) }38 do {39 let player: any CHHapticPatternPlayer40 if let cached = players[event] { player = cached }41 else {42 player = try engine.makePlayer(with: Self.pattern(for: event))43 players[event] = player44 }45 try player.start(atTime: CHHapticTimeImmediate)46 } catch {47 // The engine may have been stopped under us (audio interruption, app in background): rebuild next time.48 invalidate()49 playFallback(event)50 }51 }5253 // MARK: Engine lifecycle5455 private func startedEngine() -> CHHapticEngine? {56 if engine == nil {57 guard let created = try? CHHapticEngine() else { return nil }58 created.playsHapticsOnly = true // never touches the audio session used by the soundscape59 created.isAutoShutdownEnabled = true // the system idles the engine; `start()` below wakes it60 Self.installHandlers(on: created)61 engine = created62 }63 if !isRunning {64 do { try engine?.start(); isRunning = true } catch { invalidate(); return nil }65 }66 return engine67 }6869 /// The handlers are called on a Core Haptics queue, so they are built outside the main actor and hop back to it.70 private nonisolated static func installHandlers(on engine: CHHapticEngine) {71 engine.stoppedHandler = { _ in72 Task { @MainActor in HapticEngine.shared.engineStopped() }73 }74 engine.resetHandler = {75 Task { @MainActor in HapticEngine.shared.invalidate() }76 }77 }7879 /// Stopped by the system (interruption, backgrounding, idle shutdown): the players stay valid, the engine restarts on the next event.80 private func engineStopped() { isRunning = false }8182 /// The haptic server was reset: everything created from the old engine is unusable.83 private func invalidate() {84 players.removeAll()85 engine = nil86 isRunning = false87 }8889 // MARK: Patterns9091 private static func tap(_ time: TimeInterval, _ intensity: Float, _ sharpness: Float) -> CHHapticEvent {92 CHHapticEvent(eventType: .hapticTransient, parameters: [93 .init(parameterID: .hapticIntensity, value: intensity), .init(parameterID: .hapticSharpness, value: sharpness),94 ], relativeTime: time)95 }9697 private static func hum(_ time: TimeInterval, _ duration: TimeInterval, _ intensity: Float, _ sharpness: Float) -> CHHapticEvent {98 CHHapticEvent(eventType: .hapticContinuous, parameters: [99 .init(parameterID: .hapticIntensity, value: intensity), .init(parameterID: .hapticSharpness, value: sharpness),100 ], relativeTime: time, duration: duration)101 }102103 private static func curve(_ points: [(TimeInterval, Float)]) -> CHHapticParameterCurve {104 CHHapticParameterCurve(parameterID: .hapticIntensityControl, controlPoints: points.map { .init(relativeTime: $0.0, value: $0.1) }, relativeTime: 0)105 }106107 static func pattern(for event: Haptics.Event) throws -> CHHapticPattern {108 switch event {109 case .selection: // one crisp, medium click110 return try CHHapticPattern(events: [tap(0, 0.5, 0.55)], parameters: [])111 case .tick: // barely there, sharp: a detent112 return try CHHapticPattern(events: [tap(0, 0.22, 0.9)], parameters: [])113 case .alarmSet: // "locked in": soft press, then a firm, crisp latch114 return try CHHapticPattern(events: [tap(0, 0.45, 0.25), hum(0.02, 0.09, 0.3, 0.2), tap(0.14, 0.95, 0.75)], parameters: [])115 case .success: // light then bright: a small upward step116 return try CHHapticPattern(events: [tap(0, 0.5, 0.35), tap(0.1, 0.85, 0.7)], parameters: [])117 case .failure: // three dull, heavy thuds118 return try CHHapticPattern(events: [tap(0, 0.9, 0.1), tap(0.1, 0.65, 0.08), tap(0.2, 0.9, 0.1), hum(0.2, 0.12, 0.4, 0.05)], parameters: [])119 case .warning: // two identical sharp knocks, spaced out120 return try CHHapticPattern(events: [tap(0, 0.8, 0.95), tap(0.24, 0.8, 0.95)], parameters: [])121 case .missionComplete: // rising triple, then a short bright tail122 return try CHHapticPattern(events: [tap(0, 0.5, 0.3), tap(0.13, 0.75, 0.55), tap(0.26, 1.0, 0.85), hum(0.27, 0.22, 0.55, 0.6)],123 parameterCurves: [curve([(0, 1), (0.27, 1), (0.49, 0)])])124 case .wakeConfirmed: // long warm swell that blooms and settles, closed by a soft round tap125 return try CHHapticPattern(events: [hum(0, 1.3, 1.0, 0.15), tap(1.32, 0.6, 0.3)],126 parameterCurves: [curve([(0, 0.05), (0.75, 1.0), (1.0, 0.7), (1.3, 0.0), (1.31, 1.0)])])127 }128 }129130 // MARK: Fallback131132 private func playFallback(_ event: Haptics.Event) {133 switch event {134 case .selection, .tick: selectionGenerator.selectionChanged()135 case .success, .alarmSet: notificationGenerator.notificationOccurred(.success)136 case .failure: notificationGenerator.notificationOccurred(.error)137 case .warning: notificationGenerator.notificationOccurred(.warning)138 case .missionComplete: UIImpactFeedbackGenerator(style: .heavy).impactOccurred()139 case .wakeConfirmed: UIImpactFeedbackGenerator(style: .soft).impactOccurred(intensity: 1)140 }141 }142}143