feat: add analog trigger precision scaling

NSEvent · NSEvent · commit da2533809ac4 · 2026-07-02T17:24:59.000-07:00
diff --git a/XboxControllerMapper/XboxControllerMapper/Models/JoystickSettings.swift b/XboxControllerMapper/XboxControllerMapper/Models/JoystickSettings.swift
@@ -42,6 +42,36 @@ enum StickMode: String, Codable, CaseIterable {
     }
 }
 
+/// Which analog trigger, if any, scales cursor speed as a continuous precision control.
+enum AnalogPrecisionTriggerMode: String, Codable, CaseIterable {
+    case off = "off"
+    case left = "left"
+    case right = "right"
+    case either = "either"
+
+    var displayName: String {
+		switch self {
+		case .off: return "Off"
+		case .left: return "L2 / LT"
+		case .right: return "R2 / RT"
+		case .either: return "Either"
+		}
+    }
+
+    func rawValue(leftTrigger: Double, rightTrigger: Double) -> Double {
+		switch self {
+		case .off:
+			return 0
+		case .left:
+			return leftTrigger
+		case .right:
+			return rightTrigger
+		case .either:
+			return max(leftTrigger, rightTrigger)
+		}
+    }
+}
+
 /// Settings for joystick behavior.
 ///
 /// Per-stick response (mode, sensitivity, acceleration, deadzone, invert, custom
@@ -114,6 +144,18 @@ struct JoystickSettings: Codable, Equatable {
     /// Modifier that triggers focus mode (slower mouse speed)
     var focusModeModifier: ModifierFlags = .command
 
+    /// Analog trigger that proportionally slows mouse/touchpad cursor movement.
+    var analogPrecisionTriggerMode: AnalogPrecisionTriggerMode = .off
+
+    /// Cursor-speed floor at a full trigger pull (0.05 - 1.0).
+    var analogPrecisionMinimumSpeed: Double = 0.15
+
+    /// Trigger value ignored before precision scaling begins (0.0 - 0.95).
+    var analogPrecisionDeadzone: Double = 0.05
+
+    /// Response curve from trigger depth to speed reduction (0 = linear, 1 = cubic).
+    var analogPrecisionCurve: Double = 0.35
+
     /// Whether gyroscope aiming is enabled during focus mode.
     var gyroAimingEnabled: Bool = false
 
@@ -198,6 +240,9 @@ struct JoystickSettings: Codable, Equatable {
                (0.5...5.0).contains(touchpadZoomToPanRatio) &&
                (1.0...4.0).contains(scrollBoostMultiplier) &&
                range.contains(focusModeSensitivity) &&
+			   (0.05...1.0).contains(analogPrecisionMinimumSpeed) &&
+			   (0.0...0.95).contains(analogPrecisionDeadzone) &&
+			   range.contains(analogPrecisionCurve) &&
                range.contains(gyroAimingSensitivity) &&
                range.contains(gyroAimingDeadzone) &&
                range.contains(gestureSensitivity) &&
@@ -209,6 +254,25 @@ struct JoystickSettings: Codable, Equatable {
         return JoystickCurves.mouseMultiplier(sensitivity: focusModeSensitivity)
     }
 
+    /// Multiplier applied to cursor motion based on analog trigger depth.
+    /// Returns 1.0 when disabled or below deadzone, and approaches
+    /// `analogPrecisionMinimumSpeed` at full trigger pull.
+    func analogPrecisionMultiplier(leftTrigger: Double, rightTrigger: Double) -> Double {
+		guard analogPrecisionTriggerMode != .off else { return 1.0 }
+		let rawTrigger = max(0.0, min(1.0, analogPrecisionTriggerMode.rawValue(
+			leftTrigger: leftTrigger,
+			rightTrigger: rightTrigger
+		)))
+		let deadzone = max(0.0, min(0.95, analogPrecisionDeadzone))
+		guard rawTrigger > deadzone else { return 1.0 }
+
+		let minimumSpeed = max(0.05, min(1.0, analogPrecisionMinimumSpeed))
+		let normalized = (rawTrigger - deadzone) / (1.0 - deadzone)
+		let exponent = 1.0 + max(0.0, min(1.0, analogPrecisionCurve)) * 2.0
+		let shaped = pow(normalized, exponent)
+		return 1.0 - shaped * (1.0 - minimumSpeed)
+    }
+
     func calibratedTouchpadValue(_ raw: Double, boost: Double) -> Double {
         // Calibration curve: keeps 0 and 1 stable, but maps 0.5 -> 0.5 + boost * 0.25.
         return min(1.0, max(0.0, raw + boost * raw * (1.0 - raw)))
@@ -260,6 +324,10 @@ extension JoystickSettings {
         case scrollBoostMultiplier
         case focusModeSensitivity
         case focusModeModifier
+		case analogPrecisionTriggerMode
+		case analogPrecisionMinimumSpeed
+		case analogPrecisionDeadzone
+		case analogPrecisionCurve
         case gyroAimingEnabled
         case gyroAimingSensitivity
         case gyroAimingDeadzone
@@ -320,6 +388,17 @@ extension JoystickSettings {
         scrollBoostMultiplier = try container.decode(.scrollBoostMultiplier, default: 2.0, clampedTo: 1.0...4.0)
         focusModeSensitivity = try container.decode(.focusModeSensitivity, default: 0.2, clampedTo: unit)
         focusModeModifier = try container.decode(.focusModeModifier, default: .command)
+		analogPrecisionTriggerMode = try container.decodeLenient(
+			.analogPrecisionTriggerMode,
+			default: AnalogPrecisionTriggerMode.off
+		)
+		analogPrecisionMinimumSpeed = try container.decode(
+			.analogPrecisionMinimumSpeed,
+			default: 0.15,
+			clampedTo: 0.05...1.0
+		)
+		analogPrecisionDeadzone = try container.decode(.analogPrecisionDeadzone, default: 0.05, clampedTo: 0.0...0.95)
+		analogPrecisionCurve = try container.decode(.analogPrecisionCurve, default: 0.35, clampedTo: unit)
         gyroAimingEnabled = try container.decode(.gyroAimingEnabled, default: false)
         gyroAimingSensitivity = try container.decode(.gyroAimingSensitivity, default: 0.3, clampedTo: unit)
         gyroAimingDeadzone = try container.decode(.gyroAimingDeadzone, default: 0.3, clampedTo: unit)
@@ -361,6 +440,10 @@ extension JoystickSettings {
         try container.encode(scrollBoostMultiplier, forKey: .scrollBoostMultiplier)
         try container.encode(focusModeSensitivity, forKey: .focusModeSensitivity)
         try container.encode(focusModeModifier, forKey: .focusModeModifier)
+		try container.encode(analogPrecisionTriggerMode, forKey: .analogPrecisionTriggerMode)
+		try container.encode(analogPrecisionMinimumSpeed, forKey: .analogPrecisionMinimumSpeed)
+		try container.encode(analogPrecisionDeadzone, forKey: .analogPrecisionDeadzone)
+		try container.encode(analogPrecisionCurve, forKey: .analogPrecisionCurve)
         try container.encode(gyroAimingEnabled, forKey: .gyroAimingEnabled)
         try container.encode(gyroAimingSensitivity, forKey: .gyroAimingSensitivity)
         try container.encode(gyroAimingDeadzone, forKey: .gyroAimingDeadzone)
diff --git a/XboxControllerMapper/XboxControllerMapper/Services/Mapping/JoystickHandler.swift b/XboxControllerMapper/XboxControllerMapper/Services/Mapping/JoystickHandler.swift
@@ -66,6 +66,10 @@ extension MappingEngine {
         // Single lock acquisition for all controller input state (cache-friendly snapshot)
         let controllerSnapshot = controllerService.snapshot()
         let leftStick = controllerSnapshot.leftStick
+		let analogPrecisionMultiplier = settings.analogPrecisionMultiplier(
+			leftTrigger: Double(controllerSnapshot.leftTrigger),
+			rightTrigger: Double(controllerSnapshot.rightTrigger)
+		)
 		processGyroAiming(
 			settings: settings,
 			now: now,
@@ -233,6 +237,7 @@ extension MappingEngine {
             side: .left,
             settings: settings,
             tuning: leftTuning,
+			analogPrecisionMultiplier: analogPrecisionMultiplier,
             dt: dt,
             now: now
         )
@@ -251,6 +256,7 @@ extension MappingEngine {
                 side: .right,
                 settings: settings,
                 tuning: rightTuning,
+				analogPrecisionMultiplier: analogPrecisionMultiplier,
                 dt: dt,
                 now: now
             )
@@ -500,7 +506,13 @@ extension MappingEngine {
         }
     }
 
-    nonisolated func processMouseMovement(_ stick: CGPoint, tuning: StickTuning, settings: JoystickSettings, now: CFAbsoluteTime) {
+    nonisolated func processMouseMovement(
+		_ stick: CGPoint,
+		tuning: StickTuning,
+		settings: JoystickSettings,
+		analogPrecisionMultiplier: Double,
+		now: CFAbsoluteTime
+    ) {
         let focusFlags = settings.focusModeModifier.cgEventFlags
         let isFocusActive = focusFlags.rawValue != 0 && inputSimulator.isHoldingModifiers(focusFlags)
 
@@ -515,7 +527,8 @@ extension MappingEngine {
         let normalizedMagnitude = JoystickMath.normalizedMagnitude(magnitude, deadzone: tuning.mouseDeadzone)
         let acceleratedMagnitude = pow(normalizedMagnitude, tuning.mouseAccelerationExponent)
 
-        let targetMultiplier = isFocusActive ? settings.focusMultiplier : tuning.mouseMultiplier
+		let baseTargetMultiplier = isFocusActive ? settings.focusMultiplier : tuning.mouseMultiplier
+		let targetMultiplier = baseTargetMultiplier * analogPrecisionMultiplier
 
         if state.currentMultiplier == 0 {
             state.currentMultiplier = targetMultiplier
diff --git a/XboxControllerMapper/XboxControllerMapper/Services/Mapping/JoystickStickStrategies.swift b/XboxControllerMapper/XboxControllerMapper/Services/Mapping/JoystickStickStrategies.swift
@@ -21,6 +21,7 @@ struct MouseStickStrategy: JoystickStickStrategy {
             input.stick,
             tuning: input.tuning,
             settings: input.settings,
+			analogPrecisionMultiplier: input.analogPrecisionMultiplier,
             now: input.now
         )
     }
diff --git a/XboxControllerMapper/XboxControllerMapper/Services/Mapping/JoystickStickStrategy.swift b/XboxControllerMapper/XboxControllerMapper/Services/Mapping/JoystickStickStrategy.swift
@@ -20,6 +20,8 @@ struct JoystickStickInput {
     /// mode from here; `settings` is for genuinely global knobs (focus mode,
     /// scroll boost).
     let tuning: StickTuning
+    /// Continuous precision multiplier from analog trigger depth (1.0 = normal).
+    let analogPrecisionMultiplier: Double
     let dt: TimeInterval
     let now: CFAbsoluteTime
 }
diff --git a/XboxControllerMapper/XboxControllerMapper/Services/Mapping/TouchpadInputHandler.swift b/XboxControllerMapper/XboxControllerMapper/Services/Mapping/TouchpadInputHandler.swift
@@ -84,9 +84,19 @@ extension MappingEngine {
         guard magnitude > deadzone else { return }
 
         let sensitivity = Config.touchpadNativeScale * settings.touchpadSensitivityMultiplier
+		let analogPrecisionMultiplier: Double
+		if settings.analogPrecisionTriggerMode == .off {
+			analogPrecisionMultiplier = 1.0
+		} else {
+			let controllerSnapshot = controllerService.snapshot()
+			analogPrecisionMultiplier = settings.analogPrecisionMultiplier(
+				leftTrigger: Double(controllerSnapshot.leftTrigger),
+				rightTrigger: Double(controllerSnapshot.rightTrigger)
+			)
+		}
 
-        let dx = Double(smoothedDelta.x) * sensitivity
-        var dy = -Double(smoothedDelta.y) * sensitivity
+		let dx = Double(smoothedDelta.x) * sensitivity * analogPrecisionMultiplier
+		var dy = -Double(smoothedDelta.y) * sensitivity * analogPrecisionMultiplier
 
         if settings.leftStick.invertMouseY {
             dy = -dy
diff --git a/XboxControllerMapper/XboxControllerMapper/Views/MainWindow/SettingsViews.swift b/XboxControllerMapper/XboxControllerMapper/Views/MainWindow/SettingsViews.swift
@@ -184,6 +184,48 @@ struct JoystickSettingsView: View {
                     }
                 }
 
+				Picker("Analog Trigger", selection: Binding(
+					get: { settings.analogPrecisionTriggerMode },
+					set: { updateSettings(\.analogPrecisionTriggerMode, $0) }
+				)) {
+					ForEach(AnalogPrecisionTriggerMode.allCases, id: \.self) { mode in
+						Text(LocalizedStringKey(mode.displayName)).tag(mode)
+					}
+				}
+				.pickerStyle(.segmented)
+
+				if settings.analogPrecisionTriggerMode != .off {
+					SliderRow(
+						label: "Minimum Speed",
+						value: Binding(
+							get: { settings.analogPrecisionMinimumSpeed },
+							set: { updateSettings(\.analogPrecisionMinimumSpeed, $0) }
+						),
+						range: 0.05...1.0,
+						description: "Cursor speed at full trigger pull"
+					)
+
+					SliderRow(
+						label: "Trigger Deadzone",
+						value: Binding(
+							get: { settings.analogPrecisionDeadzone },
+							set: { updateSettings(\.analogPrecisionDeadzone, $0) }
+						),
+						range: 0...0.5,
+						description: "How far the trigger moves before slowing starts"
+					)
+
+					SliderRow(
+						label: "Trigger Curve",
+						value: Binding(
+							get: { settings.analogPrecisionCurve },
+							set: { updateSettings(\.analogPrecisionCurve, $0) }
+						),
+						range: 0...1,
+						description: "0 = linear, 1 = more slowdown near full pull"
+					)
+				}
+
                 Toggle("Highlight Focused Cursor", isOn: $focusCursorHighlightEnabled)
                     .onChange(of: focusCursorHighlightEnabled) { _, newValue in
                         FocusModeIndicator.isEnabled = newValue
diff --git a/XboxControllerMapper/XboxControllerMapperTests/JoystickSettingsPointerLockCodableTests.swift b/XboxControllerMapper/XboxControllerMapperTests/JoystickSettingsPointerLockCodableTests.swift
@@ -37,3 +37,87 @@ final class JoystickSettingsPointerLockCodableTests: XCTestCase {
         XCTAssertTrue(settings.isValid())
     }
 }
+
+final class JoystickSettingsAnalogPrecisionCodableTests: XCTestCase {
+
+    func testDefaultIsOffAndLegacyDecodeKeepsNormalSpeed() throws {
+		let settings = try JSONDecoder().decode(JoystickSettings.self, from: Data("{}".utf8))
+
+		XCTAssertEqual(settings.analogPrecisionTriggerMode, .off)
+		XCTAssertEqual(settings.analogPrecisionMultiplier(leftTrigger: 1.0, rightTrigger: 1.0), 1.0)
+    }
+
+    func testEncodeDecodeRoundTripAllTriggerModes() throws {
+		for mode in AnalogPrecisionTriggerMode.allCases {
+			var settings = JoystickSettings()
+			settings.analogPrecisionTriggerMode = mode
+			settings.analogPrecisionMinimumSpeed = 0.25
+			settings.analogPrecisionDeadzone = 0.1
+			settings.analogPrecisionCurve = 0.75
+
+			let data = try JSONEncoder().encode(settings)
+			let decoded = try JSONDecoder().decode(JoystickSettings.self, from: data)
+
+			XCTAssertEqual(decoded.analogPrecisionTriggerMode, mode)
+			XCTAssertEqual(decoded.analogPrecisionMinimumSpeed, 0.25)
+			XCTAssertEqual(decoded.analogPrecisionDeadzone, 0.1)
+			XCTAssertEqual(decoded.analogPrecisionCurve, 0.75)
+		}
+    }
+
+    func testUnknownTriggerModeDegradesToOff() throws {
+		let json = #"{"analogPrecisionTriggerMode": "pressurePlate"}"#
+		let settings = try JSONDecoder().decode(JoystickSettings.self, from: Data(json.utf8))
+
+		XCTAssertEqual(settings.analogPrecisionTriggerMode, .off)
+    }
+
+    func testAnalogPrecisionMultiplierUsesSelectedTrigger() {
+		var settings = JoystickSettings()
+		settings.analogPrecisionTriggerMode = .left
+		settings.analogPrecisionMinimumSpeed = 0.2
+		settings.analogPrecisionDeadzone = 0.1
+		settings.analogPrecisionCurve = 0.0
+
+		XCTAssertEqual(settings.analogPrecisionMultiplier(leftTrigger: 0.1, rightTrigger: 1.0), 1.0)
+		XCTAssertEqual(settings.analogPrecisionMultiplier(leftTrigger: 1.0, rightTrigger: 0.0), 0.2, accuracy: 1e-10)
+
+		settings.analogPrecisionTriggerMode = .right
+		XCTAssertEqual(settings.analogPrecisionMultiplier(leftTrigger: 1.0, rightTrigger: 0.1), 1.0)
+		XCTAssertEqual(settings.analogPrecisionMultiplier(leftTrigger: 0.0, rightTrigger: 1.0), 0.2, accuracy: 1e-10)
+    }
+
+    func testEitherTriggerUsesDeeperPullAndIsMonotonic() {
+		var settings = JoystickSettings()
+		settings.analogPrecisionTriggerMode = .either
+		settings.analogPrecisionMinimumSpeed = 0.15
+		settings.analogPrecisionDeadzone = 0.0
+		settings.analogPrecisionCurve = 0.35
+
+		let shallow = settings.analogPrecisionMultiplier(leftTrigger: 0.2, rightTrigger: 0.1)
+		let medium = settings.analogPrecisionMultiplier(leftTrigger: 0.2, rightTrigger: 0.5)
+		let full = settings.analogPrecisionMultiplier(leftTrigger: 0.0, rightTrigger: 1.0)
+
+		XCTAssertGreaterThan(shallow, medium)
+		XCTAssertGreaterThan(medium, full)
+		XCTAssertEqual(full, 0.15, accuracy: 1e-10)
+    }
+
+    func testDecodingClampsAnalogPrecisionRanges() throws {
+		let json = """
+		{
+		  "analogPrecisionTriggerMode": "either",
+		  "analogPrecisionMinimumSpeed": 0.01,
+		  "analogPrecisionDeadzone": 2.0,
+		  "analogPrecisionCurve": -1.0
+		}
+		"""
+
+		let settings = try JSONDecoder().decode(JoystickSettings.self, from: Data(json.utf8))
+
+		XCTAssertEqual(settings.analogPrecisionMinimumSpeed, 0.05)
+		XCTAssertEqual(settings.analogPrecisionDeadzone, 0.95)
+		XCTAssertEqual(settings.analogPrecisionCurve, 0.0)
+		XCTAssertTrue(settings.isValid())
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,7 @@ struct MouseStickStrategy: JoystickStickStrategy {`
`21`	`21`	`input.stick,`
`22`	`22`	`tuning: input.tuning,`
`23`	`23`	`settings: input.settings,`
	`24`	`+ analogPrecisionMultiplier: input.analogPrecisionMultiplier,`
`24`	`25`	`now: input.now`
`25`	`26`	`)`
`26`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,8 @@ struct JoystickStickInput {`
`20`	`20`	/// mode from here; `settings` is for genuinely global knobs (focus mode,
`21`	`21`	`/// scroll boost).`
`22`	`22`	`let tuning: StickTuning`
	`23`	`+ /// Continuous precision multiplier from analog trigger depth (1.0 = normal).`
	`24`	`+ let analogPrecisionMultiplier: Double`
`23`	`25`	`let dt: TimeInterval`
`24`	`26`	`let now: CFAbsoluteTime`
`25`	`27`	`}`