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,146 @@
+//! 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 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 handle_rumble_request(
+    manager: &mut RumblesManager,
+    gilrs: &mut Gilrs,
+    rumble: GamepadRumbleRequest,
+    current_time: f32,
+) -> Result<(), RumbleError> {
+    let gamepad = match rumble {
+        GamepadRumbleRequest::Add { gamepad, .. } | GamepadRumbleRequest::Stop { gamepad } => {
+            gamepad
+        }
+    };
+    let (gamepad_id, _) = gilrs
+        .gamepads()
+        .find(|(pad_id, _)| convert_gamepad_id(*pad_id) == gamepad)
+        .ok_or(RumbleError::GamepadNotFound)?;
+
+    match rumble {
+        GamepadRumbleRequest::Stop { .. } => {
+            // `ff::Effect` uses RAII, dropping = deactivating
+            manager.rumbles.remove(&gamepad_id);
+        }
+        GamepadRumbleRequest::Add {
+            duration,
+            intensity,
+            ..
+        } => {
+            let deadline = current_time + duration.as_secs_f32();
+
+            let mut effect_builder = ff::EffectBuilder::new();
+
+            for effect in get_base_effects(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 gamepad = match rumble {
+            GamepadRumbleRequest::Add { gamepad, .. } | GamepadRumbleRequest::Stop { gamepad } => {
+                gamepad
+            }
+        };
+        match handle_rumble_request(&mut manager, &mut gilrs, rumble, current_time) {
+            Ok(()) => {}
+            Err(RumbleError::GilrsError(err)) => {
+                debug!(
+                    "Tried to handle rumble request for {gamepad:?} but an error occurred: {err}"
+                );
+            }
+            Err(RumbleError::GamepadNotFound) => {
+                warn!("Tried to handle rumble request {gamepad:?} but it doesn't exist!");
+            }
+        };
+    }
+}

crates/bevy_input/src/gamepad.rs

@@ -5,6 +5,7 @@ use bevy_ecs::{
     system::{Res, ResMut, Resource},
 };
 use bevy_reflect::{std_traits::ReflectDefault, FromReflect, Reflect};
+use bevy_utils::Duration;
 use bevy_utils::{tracing::info, HashMap};
 use thiserror::Error;
 
@@ -1240,6 +1241,104 @@ const ALL_AXIS_TYPES: [GamepadAxisType; 6] = [
     GamepadAxisType::RightZ,
 ];
 
+/// The intensity at which a gamepad's force-feedback motors may rumble.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct GamepadRumbleIntensity {
+    /// The rumble intensity of the strong gamepad motor
+    ///
+    /// Ranges from 0.0 to 1.0
+    ///
+    /// By convention, this is usually a low-frequency motor on the left-hand
+    /// side of the gamepad, though it may vary across platforms and hardware.
+    pub strong: f32,
+    /// The rumble intensity of the weak gamepad motor
+    ///
+    /// Ranges from 0.0 to 1.0
+    ///
+    /// By convention, this is usually a high-frequency motor on the right-hand
+    /// side of the gamepad, though it may vary across platforms and hardware.
+    pub weak: f32,
+}
+
+impl GamepadRumbleIntensity {
+    /// Rumble both gamepad motors at maximum intensity
+    pub const MAX: Self = GamepadRumbleIntensity {
+        strong: 1.0,
+        weak: 1.0,
+    };
+
+    /// Rumble the weak motor at maximum intensity
+    pub const WEAK_MAX: Self = GamepadRumbleIntensity {
+        strong: 0.0,
+        weak: 1.0,
+    };
+
+    /// Rumble the strong motor at maximum intensity
+    pub const STRONG_MAX: Self = GamepadRumbleIntensity {
+        strong: 1.0,
+        weak: 0.0,
+    };
+
+    /// Creates a new rumble intensity with weak motor intensity set to the given value
+    pub fn weak(weak: f32) -> Self {
+        Self { weak, strong: 0.0 }
+    }
+
+    /// Creates a new rumble intensity with strong motor intensity set to the given value
+    pub fn strong(strong: f32) -> Self {
+        Self { strong, weak: 0.0 }
+    }
+}
+
+/// An event that controls force-feedback rumbling of a [`Gamepad`]
+///
+/// # Notes
+///
+/// Does nothing if the gamepad or platform does not support rumble.
+///
+/// # Example
+///
+/// ```
+/// # use bevy_input::gamepad::{Gamepad, Gamepads, GamepadRumbleRequest, GamepadRumbleIntensity};
+/// # use bevy_ecs::prelude::{EventWriter, Res};
+/// # use bevy_utils::Duration;
+/// fn rumble_gamepad_system(
+///     mut rumble_requests: EventWriter<GamepadRumbleRequest>,
+///     gamepads: Res<Gamepads>
+/// ) {
+///     for gamepad in gamepads.iter() {
+///         rumble_requests.send(GamepadRumbleRequest::Add {
+///             gamepad,
+///             intensity: GamepadRumbleIntensity::MAX,
+///             duration: Duration::from_secs_f32(0.5),
+///         });
+///     }
+/// }
+/// ```
+#[derive(Clone)]
+pub enum GamepadRumbleRequest {
+    /// Add a rumble to the given gamepad.
+    ///
+    /// Simultaneous rumble effects add up to the sum of their strengths.
+    ///
+    /// Consequently, if two rumbles at half intensity are added at the same
+    /// time, their intensities will be added up, and the controller will rumble
+    /// at full intensity until one of the rumbles finishes, then the rumble
+    /// will continue at the intensity of the remaining event.
+    ///
+    /// To replace an existing rumble, send a [`GamepadRumbleRequest::Stop`] event first.
+    Add {
+        /// How long the gamepad should rumble
+        duration: Duration,
+        /// How intense the rumble should be
+        intensity: GamepadRumbleIntensity,
+        /// The gamepad to rumble
+        gamepad: Gamepad,
+    },
+    /// Stop all running rumbles on the given `Gamepad`
+    Stop { gamepad: Gamepad },
+}
+
 #[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)