Add gamepad rumble support to bevy_input

Cargo.toml

@@ -1247,6 +1247,16 @@ description = "Iterates and prints gamepad input and connection events"
 category = "Input"
 wasm = false
 
+[[example]]
+name = "gamepad_rumble"
+path = "examples/input/gamepad_rumble.rs"
+
+[package.metadata.example.gamepad_rumble]
+name = "Gamepad Rumble"
+description = "Shows how to rumble a gamepad using force feedback"
+category = "Input"
+wasm = false
+
 [[example]]
 name = "keyboard_input"
 path = "examples/input/keyboard_input.rs"

crates/bevy_gilrs/Cargo.toml

@@ -11,9 +11,12 @@ keywords = ["bevy"]
 [dependencies]
 # bevy
 bevy_app = { path = "../bevy_app", version = "0.11.0-dev" }
+bevy_core = { path = "../bevy_core", version = "0.11.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.11.0-dev" }
 bevy_input = { path = "../bevy_input", version = "0.11.0-dev" }
+bevy_log = { path = "../bevy_log", version = "0.11.0-dev" }
 bevy_utils = { path = "../bevy_utils", version = "0.11.0-dev" }
+bevy_time = { path = "../bevy_time", version = "0.11.0-dev" }
 
 # other
 gilrs = "0.10.1"

crates/bevy_gilrs/src/lib.rs

@@ -2,13 +2,15 @@
 
 mod converter;
 mod gilrs_system;
+mod rumble;
 
-use bevy_app::{App, Plugin, PreStartup, PreUpdate};
+use bevy_app::{App, Plugin, PostUpdate, PreStartup, PreUpdate};
 use bevy_ecs::prelude::*;
 use bevy_input::InputSystem;
 use bevy_utils::tracing::error;
 use gilrs::GilrsBuilder;
 use gilrs_system::{gilrs_event_startup_system, gilrs_event_system};
+use rumble::{play_gilrs_rumble, RumblesManager};
 
 #[derive(Default)]
 pub struct GilrsPlugin;
@@ -22,8 +24,10 @@ impl Plugin for GilrsPlugin {
         {
             Ok(gilrs) => {
                 app.insert_non_send_resource(gilrs)
+                    .init_non_send_resource::<RumblesManager>()
                     .add_systems(PreStartup, gilrs_event_startup_system)
-                    .add_systems(PreUpdate, gilrs_event_system.before(InputSystem));
+                    .add_systems(PreUpdate, gilrs_event_system.before(InputSystem))
+                    .add_systems(PostUpdate, play_gilrs_rumble);
             }
             Err(err) => error!("Failed to start Gilrs. {}", err),
         }

crates/bevy_gilrs/src/rumble.rs

@@ -0,0 +1,133 @@
+//! Handle user specified rumble request events.
+use bevy_ecs::{
+    prelude::{EventReader, Res},
+    system::NonSendMut,
+};
+use bevy_input::gamepad::{GamepadRumbleIntensity, GamepadRumbleRequest};
+use bevy_log::{debug, warn};
+use bevy_time::Time;
+use bevy_utils::HashMap;
+use gilrs::{
+    ff::{self, BaseEffect, BaseEffectType},
+    GamepadId, Gilrs,
+};
+
+use crate::converter::convert_gamepad_id;
+
+struct RunningRumble {
+    deadline: f32,
+    // We use `effect.drop()` to interact with this, but rustc can't know
+    // gilrs uses Drop as an API feature.
+    #[allow(dead_code)]
+    effect: ff::Effect,
+}
+
+enum RumbleError {
+    GamepadNotFound,
+    GilrsError(ff::Error),
+}
+impl From<ff::Error> for RumbleError {
+    fn from(err: ff::Error) -> Self {
+        RumbleError::GilrsError(err)
+    }
+}
+
+#[derive(Default)]
+pub(crate) struct RumblesManager {
+    rumbles: HashMap<GamepadId, Vec<RunningRumble>>,
+}
+
+fn is_stop_request(request: &GamepadRumbleRequest) -> bool {
+    !request.additive && request.intensity == GamepadRumbleIntensity::ZERO
+}
+
+fn to_gilrs_magnitude(ratio: f32) -> u16 {
+    (ratio * u16::MAX as f32) as u16
+}
+
+fn get_base_effects(
+    GamepadRumbleIntensity { weak, strong }: GamepadRumbleIntensity,
+) -> Vec<ff::BaseEffect> {
+    let mut effects = Vec::new();
+    if strong > 0. {
+        effects.push(BaseEffect {
+            kind: BaseEffectType::Strong {
+                magnitude: to_gilrs_magnitude(strong),
+            },
+            ..Default::default()
+        });
+    }
+    if weak > 0. {
+        effects.push(BaseEffect {
+            kind: BaseEffectType::Strong {
+                magnitude: to_gilrs_magnitude(weak),
+            },
+            ..Default::default()
+        });
+    }
+    effects
+}
+
+fn add_rumble(
+    manager: &mut RumblesManager,
+    gilrs: &mut Gilrs,
+    rumble: GamepadRumbleRequest,
+    current_time: f32,
+) -> Result<(), RumbleError> {
+    let (gamepad_id, _) = gilrs
+        .gamepads()
+        .find(|(pad_id, _)| convert_gamepad_id(*pad_id) == rumble.gamepad)
+        .ok_or(RumbleError::GamepadNotFound)?;
+
+    if !rumble.additive {
+        // `ff::Effect` uses RAII, dropping = deactivating
+        manager.rumbles.remove(&gamepad_id);
+    }
+
+    if !is_stop_request(&rumble) {
+        let deadline = current_time + rumble.duration_seconds;
+
+        let mut effect_builder = ff::EffectBuilder::new();
+
+        for effect in get_base_effects(rumble.intensity) {
+            effect_builder.add_effect(effect);
+        }
+
+        let effect = effect_builder.gamepads(&[gamepad_id]).finish(gilrs)?;
+        effect.play()?;
+
+        let gamepad_rumbles = manager.rumbles.entry(gamepad_id).or_default();
+        gamepad_rumbles.push(RunningRumble { deadline, effect });
+    }
+    Ok(())
+}
+pub(crate) fn play_gilrs_rumble(
+    time: Res<Time>,
+    mut gilrs: NonSendMut<Gilrs>,
+    mut requests: EventReader<GamepadRumbleRequest>,
+    mut manager: NonSendMut<RumblesManager>,
+) {
+    let current_time = time.elapsed_seconds();
+    // Remove outdated rumble effects.
+    for (_gamepad, rumbles) in manager.rumbles.iter_mut() {
+        // `ff::Effect` uses RAII, dropping = deactivating
+        rumbles.retain(|RunningRumble { deadline, .. }| *deadline >= current_time);
+    }
+    manager
+        .rumbles
+        .retain(|_gamepad, rumbles| !rumbles.is_empty());
+
+    // Add new effects.
+    for rumble in requests.iter().cloned() {
+        let pad = rumble.gamepad;
+        match add_rumble(&mut manager, &mut gilrs, rumble, current_time) {
+            Ok(()) => {}
+            Err(RumbleError::GilrsError(err)) => {
+                debug!("Tried to rumble {pad:?} but an error occurred: {err}");
+            }
+            Err(RumbleError::GamepadNotFound) => {
+                warn!("Tried to rumble {pad:?} but it doesn't exist!");
+            }
+        };
+    }
+}

crates/bevy_input/src/gamepad.rs

@@ -1240,6 +1240,83 @@ const ALL_AXIS_TYPES: [GamepadAxisType; 6] = [
     GamepadAxisType::RightZ,
 ];
 
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct GamepadRumbleIntensity {
+    /// The rumble intensity of the strong gamepad motor
+    ///
+    /// Ranges from 0.0 to 1.0
+    pub strong: f32,
+    /// The rumble intensity of the weak gamepad motor
+    ///
+    /// Ranges from 0.0 to 1.0
+    pub weak: f32,
+}
+
+impl GamepadRumbleIntensity {
+    /// Rumble both gamepad motors at maximum intensity
+    pub const MAX: Self = GamepadRumbleIntensity {
+        strong: 1.0,
+        weak: 1.0,
+    };
+
+    /// Don't rumble at all, only makes sense when `additive` is `false`
+    pub const ZERO: Self = GamepadRumbleIntensity {
+        strong: 0.0,
+        weak: 0.0,
+    };
+}
+
+/// Request that `gamepad` should rumble with `intensity` for `duration_seconds`
+///
+/// # Notes
+///
+/// * Does nothing if the `gamepad` does not support rumble
+/// * If a new `GamepadRumbleRequest` is sent while another one is still executing, it
+///   replaces the old one.
+///
+/// # Example
+///
+/// ```
+/// # use bevy_gilrs::{GamepadRumbleRequest, GamepadRumbleIntensity};
+/// # use bevy_input::gamepad::Gamepad;
+/// # use bevy_app::EventWriter;
+/// fn rumble_pad_system(mut rumble_requests: EventWriter<GamepadRumbleRequest>) {
+///     let request = GamepadRumbleRequest {
+///         intensity: GamepadRumbleIntensity::Strong,
+///         duration_seconds: 10.0,
+///         gamepad: Gamepad(0),
+///         additive: true,
+///     };
+///     rumble_requests.send(request);
+/// }
+/// ```
+#[derive(Clone)]
+pub struct GamepadRumbleRequest {
+    /// The duration in seconds of the rumble
+    pub duration_seconds: f32,
+    /// How intense the rumble should be
+    pub intensity: GamepadRumbleIntensity,
+    /// The gamepad to rumble
+    pub gamepad: Gamepad,
+    /// Whether the rumble effects should add up, or replace any existing effects
+    pub additive: bool,
+}
+
+impl GamepadRumbleRequest {
+    /// Stop all running rumbles on the given `Gamepad`
+    pub fn stop(gamepad: Gamepad) -> Self {
+        Self {
+            duration_seconds: 0.0,
+            intensity: GamepadRumbleIntensity {
+                strong: 0.0,
+                weak: 0.0,
+            },
+            gamepad,
+            additive: false,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::gamepad::{AxisSettingsError, ButtonSettingsError};

crates/bevy_input/src/lib.rs

@@ -39,8 +39,8 @@ use gamepad::{
     gamepad_axis_event_system, gamepad_button_event_system, gamepad_connection_system,
     gamepad_event_system, AxisSettings, ButtonAxisSettings, ButtonSettings, Gamepad, GamepadAxis,
     GamepadAxisChangedEvent, GamepadAxisType, GamepadButton, GamepadButtonChangedEvent,
-    GamepadButtonType, GamepadConnection, GamepadConnectionEvent, GamepadEvent, GamepadSettings,
-    Gamepads,
+    GamepadButtonType, GamepadConnection, GamepadConnectionEvent, GamepadEvent,
+    GamepadRumbleRequest, GamepadSettings, Gamepads,
 };
 
 #[cfg(feature = "serialize")]
@@ -72,6 +72,7 @@ impl Plugin for InputPlugin {
             .add_event::<GamepadButtonChangedEvent>()
             .add_event::<GamepadAxisChangedEvent>()
             .add_event::<GamepadEvent>()
+            .add_event::<GamepadRumbleRequest>()
             .init_resource::<GamepadSettings>()
             .init_resource::<Gamepads>()
             .init_resource::<Input<GamepadButton>>()

examples/README.md

@@ -236,6 +236,7 @@ Example | Description
 [Char Input Events](../examples/input/char_input_events.rs) | Prints out all chars as they are inputted
 [Gamepad Input](../examples/input/gamepad_input.rs) | Shows handling of gamepad input, connections, and disconnections
 [Gamepad Input Events](../examples/input/gamepad_input_events.rs) | Iterates and prints gamepad input and connection events
+[Gamepad Rumble](../examples/input/gamepad_rumble.rs) | Shows how to rumble a gamepad using force feedback
 [Keyboard Input](../examples/input/keyboard_input.rs) | Demonstrates handling a key press/release
 [Keyboard Input Events](../examples/input/keyboard_input_events.rs) | Prints out all keyboard events
 [Keyboard Modifiers](../examples/input/keyboard_modifiers.rs) | Demonstrates using key modifiers (ctrl, shift)

examples/input/gamepad_rumble.rs

@@ -0,0 +1,56 @@
+//! Shows how to trigger force-feedback, making gamepads rumble when buttons are
+//! pressed.
+
+use bevy::{
+    input::gamepad::{GamepadRumbleIntensity, GamepadRumbleRequest},
+    prelude::*,
+};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Update, gamepad_system)
+        .run();
+}
+
+fn gamepad_system(
+    gamepads: Res<Gamepads>,
+    button_inputs: Res<Input<GamepadButton>>,
+    mut rumble_requests: EventWriter<GamepadRumbleRequest>,
+) {
+    for gamepad in gamepads.iter() {
+        let button_pressed = |button| {
+            button_inputs.just_pressed(GamepadButton {
+                gamepad,
+                button_type: button,
+            })
+        };
+        if button_pressed(GamepadButtonType::South) {
+            info!("(S) South face button: weak rumble for 1 second");
+            // Use the simplified API provided by Bevy
+            rumble_requests.send(GamepadRumbleRequest {
+                gamepad,
+                duration_seconds: 1.0,
+                intensity: GamepadRumbleIntensity {
+                    strong: 0.0,
+                    weak: 0.25,
+                },
+                additive: true,
+            });
+        } else if button_pressed(GamepadButtonType::West) {
+            info!("(W) West face button: maximum rumble for 5 second");
+            rumble_requests.send(GamepadRumbleRequest {
+                gamepad,
+                intensity: GamepadRumbleIntensity {
+                    strong: 1.0,
+                    weak: 1.0,
+                },
+                duration_seconds: 5.0,
+                additive: true,
+            });
+        } else if button_pressed(GamepadButtonType::North) {
+            info!("(N) North face button: Interrupt the current rumble");
+            rumble_requests.send(GamepadRumbleRequest::stop(gamepad));
+        }
+    }
+}