Replace axis-like input configuration with new input processors

Cargo.toml

@@ -50,6 +50,10 @@ derive_more = { version = "0.99", default-features = false, features = [
 ] }
 itertools = "0.12"
 serde = { version = "1.0", features = ["derive"] }
+typetag = "0.2"
+dyn-clone = "1.0"
+dyn-eq = "0.1"
+dyn-hash = "0.2"
 
 [dev-dependencies]
 bevy = { version = "0.13", default-features = false, features = [

RELEASES.md

@@ -4,7 +4,39 @@
 
 ### Breaking Changes
 
-- Removed `Direction` type. Use `bevy::math::primitives::Direction2d`.
+- removed `Direction` type in favor of `bevy::math::primitives::Direction2d`.
+- removed `DualAxisShape`.
+- added input processors for `SingleAxis`, `DualAxis`,  `VirtualAxis`, and `VirtualDpad` to refine input values:
+  - Traits:
+    - `AxisProcessor`: Handles single-axis values.
+    - `DualAxisProcessor`: Handles dual-axis values.
+  - Built-in processors:
+    - Composite Processors: Combine multiple processors function as a pipeline.
+      - `AxisProcessingPipeline`: Chain processors for single-axis values.
+      - `define_axis_processing_pipeline` macro: Inlined processor chaining for single-axis values with fixed steps.
+      - `DualAxisProcessingPipeline`: Chain processors for dual-axis values.
+      - `define_dual_axis_processing_pipeline` macro: Inlined processor chaining for dual-axis values with fixed steps.
+    - Inversion: Reverses control (positive becomes negative, etc.)
+      - `AxisInverted`: Single-axis inversion.
+      - `DualAxisInverted`: Dual-axis inversion.
+    - Sensitivity: Adjusts control responsiveness (doubling, halving, etc.).
+      - `AxisSensitivity`: Single-axis scaling.
+      - `DualAxisSensitivity`: Dual-axis scaling.
+    - Value Bounds: Define the boundaries for constraining input values.
+      - `AxisBounds`: Restricts single-axis values to a range.
+      - `DualAxisBounds`: Restricts single-axis values to a range along each axis.
+      - `CircleBounds`: Limits dual-axis values to a maximum magnitude.
+    - Deadzone: Ignores near-zero values, treating them as zero.
+      - Unscaled Deadzone:
+        - `AxisExclusion`: Excludes small single-axis values.
+        - `DualAxisExclusion`: Excludes small dual-axis values along each axis.
+        - `CircleExclusion`: Excludes dual-axis values below a specified magnitude threshold.
+      - Scaled Deadzone:
+        - `AxisDeadzone`: Normalizes single-axis values based on `AxisExclusion` and `AxisBounds::default`.
+        - `DualAxisDeadzone`: Normalizes dual-axis values based on `DualAxisExclusion` and `DualAxisBounds::default`.
+        - `CircleDeadzone`: Normalizes dual-axis values based on `CircleExclusion` and `CircleBounds::default`.
+- removed functions for inverting, adjusting sensitivity, and creating deadzones from `SingleAxis` and `DualAxis`.
+- added `with_processor`, `replace_processor`, and `no_processor` to manage processors for `SingleAxis`, `DualAxis`,  `VirtualAxis`, and `VirtualDpad`.
 
 ### Bugs
 

examples/action_state_resource.rs

@@ -5,7 +5,7 @@
 //! and include it as a resource in a bevy app.
 
 use bevy::prelude::*;
-use leafwing_input_manager::{prelude::*, user_input::InputKind};
+use leafwing_input_manager::prelude::*;
 
 fn main() {
     App::new()

examples/arpg_indirection.rs

@@ -112,19 +112,19 @@ fn spawn_player(mut commands: Commands) {
 
 fn copy_action_state(
     mut query: Query<(
-        &ActionState<Slot>,
+        &mut ActionState<Slot>,
         &mut ActionState<Ability>,
         &AbilitySlotMap,
     )>,
 ) {
-    for (slot_state, mut ability_state, ability_slot_map) in query.iter_mut() {
+    for (mut slot_state, mut ability_state, ability_slot_map) in query.iter_mut() {
         for slot in Slot::variants() {
             if let Some(matching_ability) = ability_slot_map.get(&slot) {
                 // This copies the `ActionData` between the ActionStates,
                 // including information about how long the buttons have been pressed or released
                 ability_state.set_action_data(
                     *matching_ability,
-                    slot_state.action_data(&slot).unwrap().clone(),
+                    slot_state.action_data_mut_or_default(&slot).clone(),
                 );
             }
         }

examples/axis_inputs.rs

@@ -33,9 +33,10 @@ fn spawn_player(mut commands: Commands) {
         .insert(Action::Throttle, GamepadButtonType::RightTrigger2)
         // And we'll use the right stick's x-axis as a rudder control
         .insert(
+            // Add an AxisDeadzone to process horizontal values of the right stick.
             // This will trigger if the axis is moved 10% or more in either direction.
             Action::Rudder,
-            SingleAxis::symmetric(GamepadAxisType::RightStickX, 0.1),
+            SingleAxis::new(GamepadAxisType::RightStickX).with_processor(AxisDeadzone::default()),
         )
         .build();
     commands

examples/clash_handling.rs

@@ -4,7 +4,6 @@
 //! See [`ClashStrategy`] for more details.
 
 use bevy::prelude::*;
-use leafwing_input_manager::clashing_inputs::ClashStrategy;
 use leafwing_input_manager::prelude::*;
 
 fn main() {

examples/consuming_actions.rs

@@ -1,6 +1,5 @@
 //! Demonstrates how to "consume" actions, so they can only be responded to by a single system
 
-use bevy::ecs::system::Resource;
 use bevy::prelude::*;
 use leafwing_input_manager::prelude::*;
 

examples/default_controls.rs

@@ -20,7 +20,7 @@ enum PlayerAction {
 }
 
 impl PlayerAction {
-    /// Define the default binding to the input
+    /// Define the default bindings to the input
     fn default_input_map() -> InputMap<Self> {
         let mut input_map = InputMap::default();
 

examples/input_processing.rs

@@ -0,0 +1,70 @@
+use bevy::prelude::*;
+use leafwing_input_manager::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_plugins(InputManagerPlugin::<Action>::default())
+        .add_systems(Startup, spawn_player)
+        .add_systems(Update, check_data)
+        .run();
+}
+
+#[derive(Actionlike, PartialEq, Eq, Clone, Copy, Hash, Debug, Reflect)]
+enum Action {
+    Move,
+    LookAround,
+}
+
+#[derive(Component)]
+struct Player;
+
+fn spawn_player(mut commands: Commands) {
+    let mut input_map = InputMap::default();
+    input_map
+        .insert(
+            Action::Move,
+            VirtualDPad::wasd()
+                // You can add a processor to handle axis-like user inputs by using the `with_processor`.
+                //
+                // This processor is a circular deadzone that normalizes input values
+                // by clamping their magnitude to a maximum of 1.0,
+                // excluding those with a magnitude less than 0.1,
+                // and scaling other values linearly in between.
+                .with_processor(CircleDeadzone::default())
+                // Followed by appending another processor for the next processing step.
+                .with_processor(AxisSensitivity(2.0).extend_dual()),
+        )
+        .insert(
+            Action::Move,
+            DualAxis::left_stick()
+                // You can replace the currently used processor with another processor.
+                .replace_processor(CircleDeadzone::default())
+                // Or remove the processor directly, leaving no processor applied.
+                .no_processor(),
+        )
+        .insert(
+            Action::LookAround,
+            // You can also add a pipeline to handle axis-like user inputs.
+            DualAxis::mouse_motion().with_processor(
+                DualAxisProcessingPipeline::default()
+                    // The first processor is a circular deadzone.
+                    .with(CircleDeadzone::default())
+                    // The next processor doubles inputs normalized by the deadzone.
+                    .with(AxisSensitivity(2.0).extend_dual()),
+            ),
+        );
+    commands
+        .spawn(InputManagerBundle::with_map(input_map))
+        .insert(Player);
+}
+
+fn check_data(query: Query<&ActionState<Action>, With<Player>>) {
+    let action_state = query.single();
+    for action in action_state.get_pressed() {
+        println!(
+            "Pressed {action:?}! Its data: {:?}",
+            action_state.axis_pair(&action)
+        );
+    }
+}

examples/mouse_position.rs

@@ -60,8 +60,7 @@ fn update_cursor_state_from_window(
 
             if let Some(val) = window.cursor_position() {
                 action_state
-                    .action_data_mut(&driver.action)
-                    .unwrap()
+                    .action_data_mut_or_default(&driver.action)
                     .axis_pair = Some(DualAxisData::from_xy(val));
             }
         }

examples/send_actions_over_network.rs

@@ -6,7 +6,7 @@
 //! Note that [`ActionState`] can also be serialized and sent directly.
 //! This approach will be less bandwidth efficient, but involve less complexity and CPU work.
 
-use bevy::ecs::event::{Events, ManualEventReader};
+use bevy::ecs::event::ManualEventReader;
 use bevy::input::InputPlugin;
 use bevy::prelude::*;
 use leafwing_input_manager::action_diff::ActionDiffEvent;
@@ -23,10 +23,6 @@ enum FpsAction {
     Shoot,
 }
 
-/// This identifier uniquely identifies entities across the network
-#[derive(Component, Clone, PartialEq, Eq, Hash, Debug)]
-struct StableId(u64);
-
 /// Processes an [`Events`] stream of [`ActionDiff`] to update an [`ActionState`]
 ///
 /// In a real scenario, you would have to map the entities between the server and client world.

examples/twin_stick_controller.rs

@@ -39,7 +39,7 @@ pub enum PlayerAction {
 }
 
 impl PlayerAction {
-    /// Define the default binding to the input
+    /// Define the default bindings to the input
     fn default_input_map() -> InputMap<Self> {
         let mut input_map = InputMap::default();
 

examples/virtual_dpad.rs

@@ -32,6 +32,7 @@ fn spawn_player(mut commands: Commands) {
             down: KeyCode::KeyS.into(),
             left: KeyCode::KeyA.into(),
             right: KeyCode::KeyD.into(),
+            processor: None,
         },
     )]);
     commands