Add threshold value for GamepadControlDirection, `MouseMoveDirect…

…ion`, and `MouseScrollDirection` (#624)

* threshold

* minor

* address

* fix CI

* mention panic

RELEASES.md

@@ -1,5 +1,11 @@
 # Release Notes
 
+## Version 0.16.0 (Unreleased)
+
+### Usability (0.16.0)
+
+- added `threshold` value for `GamepadControlDirection`, `MouseMoveDirection`, and `MouseScrollDirection` to be considered pressed.
+
 ## Version 0.15.1
 
 ### Enhancements (0.15.1)

src/axislike.rs

@@ -25,13 +25,23 @@ impl AxisDirection {
         }
     }
 
-    /// Checks if the given `value` represents an active input in this direction.
+    /// Checks if the given `value` represents an active input in this direction,
+    /// considering the specified `threshold`.
+    ///
+    /// # Requirements
+    ///
+    /// - `threshold` >= `0.0`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the requirement isn't met.
     #[must_use]
     #[inline]
-    pub fn is_active(&self, value: f32) -> bool {
+    pub fn is_active(&self, value: f32, threshold: f32) -> bool {
+        assert!(threshold >= 0.0);
         match self {
-            Self::Negative => value < 0.0,
-            Self::Positive => value > 0.0,
+            Self::Negative => value < -threshold,
+            Self::Positive => value > threshold,
         }
     }
 }
@@ -151,11 +161,20 @@ impl DualAxisDirection {
         }
     }
 
-    /// Checks if the given `value` represents an active input in this direction.
+    /// Checks if the given `value` represents an active input in this direction,
+    /// considering the specified `threshold`.
+    ///
+    /// # Requirements
+    ///
+    /// - `threshold` >= `0.0`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the requirement isn't met.
     #[must_use]
     #[inline]
-    pub fn is_active(&self, value: Vec2) -> bool {
-        let component_along_axis = self.axis().get_value(value);
-        self.axis_direction().is_active(component_along_axis)
+    pub fn is_active(&self, value: Vec2, threshold: f32) -> bool {
+        let axis_value = self.axis().get_value(value);
+        self.axis_direction().is_active(axis_value, threshold)
     }
 }

src/user_input/gamepad.rs

@@ -1,7 +1,10 @@
 //! Gamepad inputs
 
+use std::hash::{Hash, Hasher};
+
 use bevy::input::gamepad::{GamepadAxisChangedEvent, GamepadButtonChangedEvent, GamepadEvent};
 use bevy::input::{Axis, ButtonInput};
+use bevy::math::FloatOrd;
 use bevy::prelude::{
     Events, Gamepad, GamepadAxis, GamepadAxisType, GamepadButton, GamepadButtonType, Gamepads,
     Reflect, Res, ResMut, Vec2, World,
@@ -69,29 +72,55 @@ fn read_axis_value(
 /// app.update();
 /// assert!(app.read_pressed(input));
 /// ```
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Reflect, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Reflect, Serialize, Deserialize)]
 #[must_use]
 pub struct GamepadControlDirection {
     /// The axis that this input tracks.
     pub axis: GamepadAxisType,
 
     /// The direction of the axis to monitor (positive or negative).
-    pub side: AxisDirection,
+    pub direction: AxisDirection,
+
+    /// The threshold value for the direction to be considered pressed.
+    /// Must be non-negative.
+    pub threshold: f32,
 }
 
 impl GamepadControlDirection {
     /// Creates a [`GamepadControlDirection`] triggered by a negative value on the specified `axis`.
     #[inline]
     pub const fn negative(axis: GamepadAxisType) -> Self {
-        let side = AxisDirection::Negative;
-        Self { axis, side }
+        Self {
+            axis,
+            direction: AxisDirection::Negative,
+            threshold: 0.0,
+        }
     }
 
     /// Creates a [`GamepadControlDirection`] triggered by a positive value on the specified `axis`.
     #[inline]
     pub const fn positive(axis: GamepadAxisType) -> Self {
-        let side = AxisDirection::Positive;
-        Self { axis, side }
+        Self {
+            axis,
+            direction: AxisDirection::Positive,
+            threshold: 0.0,
+        }
+    }
+
+    /// Sets the `threshold` value.
+    ///
+    /// # Requirements
+    ///
+    /// - `threshold` >= `0.0`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the requirement isn't met.
+    #[inline]
+    pub fn threshold(mut self, threshold: f32) -> Self {
+        assert!(threshold >= 0.0);
+        self.threshold = threshold;
+        self
     }
 
     /// "Up" on the left analog stick (positive Y-axis movement).
@@ -129,7 +158,7 @@ impl UserInput for GamepadControlDirection {
     /// [`GamepadControlDirection`] represents a simple virtual button.
     #[inline]
     fn decompose(&self) -> BasicInputs {
-        BasicInputs::Simple(Box::new(*self))
+        BasicInputs::Simple(Box::new((*self).threshold(0.0)))
     }
 }
 
@@ -140,7 +169,7 @@ impl Buttonlike for GamepadControlDirection {
     #[inline]
     fn pressed(&self, input_store: &CentralInputStore, gamepad: Gamepad) -> bool {
         let value = read_axis_value(input_store, gamepad, self.axis);
-        self.side.is_active(value)
+        self.direction.is_active(value, self.threshold)
     }
 
     /// Sends a [`GamepadEvent::Axis`] event with a magnitude of 1.0 for the specified direction on the provided [`Gamepad`].
@@ -150,7 +179,7 @@ impl Buttonlike for GamepadControlDirection {
         let event = GamepadEvent::Axis(GamepadAxisChangedEvent {
             gamepad,
             axis_type: self.axis,
-            value: self.side.full_active_value(),
+            value: self.direction.full_active_value(),
         });
         world.resource_mut::<Events<GamepadEvent>>().send(event);
     }
@@ -168,6 +197,16 @@ impl Buttonlike for GamepadControlDirection {
     }
 }
 
+impl Eq for GamepadControlDirection {}
+
+impl Hash for GamepadControlDirection {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.axis.hash(state);
+        self.direction.hash(state);
+        FloatOrd(self.threshold).hash(state);
+    }
+}
+
 impl UpdatableInput for GamepadAxis {
     type SourceData = Axis<GamepadAxis>;