Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2025-02-16 22:18:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

Document gamepad.rs (#5548)

Browse source 
# Objective

- Fixes #5544
- Part of the splitting process of #3692.

## Solution

- Document everything in the `gamepad.rs` file.
- Add a doc example for mocking gamepad input.

---

## Changelog

- Added and updated the documentation inside of the `gamepad.rs` file.
This commit is contained in:
KDecay 2022-08-05 02:28:07 +00:00
parent 704d8e251b
commit 54750deddd
1 changed files with 385 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

400
crates/bevy_input/src/gamepad.rs
View file

@ -3,65 +3,115 @@ use bevy_ecs::event::{EventReader, EventWriter};
use bevy_ecs::system::{Res, ResMut};
use bevy_utils::{tracing::info, HashMap, HashSet};
/// A gamepad with an associated `ID`.
///
/// ## Usage
///
/// The primary way to access the individual connected gamepads is done through the [`Gamepads`]
/// `bevy` resource. It is also used inside of [`GamepadEvent`]s and [`GamepadEventRaw`]s to distinguish
/// which gamepad an event corresponds to.
///
/// ## Note
///
/// The `ID` of a gamepad is fixed until the gamepad disconnects or the app is restarted.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub struct Gamepad {
/// The `ID` of the gamepad.
pub id: usize,
}
impl Gamepad {
/// Creates a new [`Gamepad`].
pub fn new(id: usize) -> Self {
Self { id }
}
}
#[derive(Default, Debug)]
/// Container of unique connected [`Gamepad`]s
/// A collection of connected [`Gamepad`]s.
///
/// [`Gamepad`]s are registered and deregistered in [`gamepad_connection_system`]
/// ## Usage
///
/// It is stored in a `bevy` resource which tracks all of the currently connected [`Gamepad`]s.
///
/// ## Updating
///
/// The [`Gamepad`]s are registered and deregistered in the [`gamepad_connection_system`]
/// whenever a [`GamepadEventType::Connected`] or [`GamepadEventType::Disconnected`]
/// event is received.
#[derive(Default, Debug)]
pub struct Gamepads {
/// The collection of the connected [`Gamepad`]s.
gamepads: HashSet<Gamepad>,
}
impl Gamepads {
/// Returns true if the [Gamepads] contains a [Gamepad].
/// Returns `true` if the `gamepad` is connected.
pub fn contains(&self, gamepad: &Gamepad) -> bool {
self.gamepads.contains(gamepad)
}
/// Iterates over registered [Gamepad]s
/// An iterator visiting all connected [`Gamepad`]s in arbitrary order.
pub fn iter(&self) -> impl Iterator<Item = &Gamepad> + '_ {
self.gamepads.iter()
}
/// Registers [Gamepad].
/// Registers the `gamepad` marking it as connected.
fn register(&mut self, gamepad: Gamepad) {
self.gamepads.insert(gamepad);
}
/// Deregisters [Gamepad.
/// Deregisters the `gamepad` marking it as disconnected.
fn deregister(&mut self, gamepad: &Gamepad) {
self.gamepads.remove(gamepad);
}
}
/// The data contained in a [`GamepadEvent`] or [`GamepadEventRaw`].
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub enum GamepadEventType {
/// A [`Gamepad`] has been connected.
Connected,
/// A [`Gamepad`] has been disconnected.
Disconnected,
/// The value of a [`Gamepad`] button has changed.
ButtonChanged(GamepadButtonType, f32),
/// The value of a [`Gamepad`] axis has changed.
AxisChanged(GamepadAxisType, f32),
}
/// An event of a [`Gamepad`].
///
/// This event is the translated version of the [`GamepadEventRaw`]. It is available to
/// the end user and can be used for game logic.
///
/// ## Differences
///
/// The difference between the [`GamepadEventRaw`] and the [`GamepadEvent`] is that the
/// former respects user defined [`GamepadSettings`] for the gamepad inputs when translating it
/// to the latter. The former also updates the [`Input<GamepadButton>`], [`Axis<GamepadAxis>`],
/// and [`Axis<GamepadButton>`] resources accordingly.
///
/// ## Gamepad input mocking
///
/// When mocking gamepad input, use [`GamepadEventRaw`]s instead of [`GamepadEvent`]s.
/// Otherwise [`GamepadSettings`] won't be respected and the [`Input<GamepadButton>`],
/// [`Axis<GamepadAxis>`], and [`Axis<GamepadButton>`] resources won't be updated correctly.
///
/// An example for gamepad input mocking can be seen in the documentation of the [`GamepadEventRaw`].
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub struct GamepadEvent {
/// The gamepad this event corresponds to.
pub gamepad: Gamepad,
/// The type of the event.
pub event_type: GamepadEventType,
}
impl GamepadEvent {
/// Creates a new [`GamepadEvent`].
pub fn new(gamepad: Gamepad, event_type: GamepadEventType) -> Self {
Self {
gamepad,
@ -70,14 +120,100 @@ impl GamepadEvent {
}
}
/// A raw event of a [`Gamepad`].
///
/// This event is the translated version of the `EventType` from the `GilRs` crate.
/// It is available to the end user and can be used for game logic.
///
/// ## Differences
///
/// The difference between the `EventType` from the `GilRs` crate and the [`GamepadEventRaw`]
/// is that the latter has less events, because the button pressing logic is handled through the generic
/// [`Input<T>`] instead of through events.
///
/// The difference between the [`GamepadEventRaw`] and the [`GamepadEvent`] can be seen in the documentation
/// of the [`GamepadEvent`].
///
/// ## Gamepad input mocking
///
/// The following example showcases how to mock gamepad input by manually sending [`GamepadEventRaw`]s.
///
/// ```
/// # use bevy_input::prelude::*;
/// # use bevy_input::InputPlugin;
/// # use bevy_input::gamepad::GamepadEventRaw;
/// # use bevy_app::prelude::*;
/// # use bevy_ecs::prelude::*;
/// #
/// // This system sets the `bool` resource to `true` if the `South` button
/// // of the first gamepad is pressed.
/// fn change_resource_on_gamepad_button_press(
/// mut my_resource: ResMut<bool>,
/// gamepads: Res<Gamepads>,
/// button_inputs: ResMut<Input<GamepadButton>>,
/// ) {
/// let gamepad = gamepads.iter().next().unwrap();
/// let gamepad_button= GamepadButton::new(*gamepad, GamepadButtonType::South);
///
/// *my_resource = button_inputs.pressed(gamepad_button);
/// }
///
/// // Create our app.
/// let mut app = App::new();
///
/// // Add the input plugin and the system/resource we want to test.
/// app.add_plugin(InputPlugin)
/// .insert_resource(false)
/// .add_system(change_resource_on_gamepad_button_press);
///
/// // Define our dummy gamepad input data.
/// let gamepad = Gamepad::new(0);
/// let button_type = GamepadButtonType::South;
///
/// // Send the gamepad connected event to mark our gamepad as connected.
/// // This updates the `Gamepads` resource accordingly.
/// app.world.send_event(GamepadEventRaw::new(gamepad, GamepadEventType::Connected));
///
/// // Send the gamepad input event to mark the `South` gamepad button as pressed.
/// // This updates the `Input<GamepadButton>` resource accordingly.
/// app.world.send_event(GamepadEventRaw::new(
/// gamepad,
/// GamepadEventType::ButtonChanged(button_type, 1.0)
/// ));
///
/// // Advance the execution of the schedule by a single cycle.
/// app.update();
///
/// // At this point you can check if your game logic corresponded correctly to the gamepad input.
/// // In this example we are checking if the `bool` resource was updated from `false` to `true`.
/// assert!(app.world.resource::<bool>());
///
/// // Send the gamepad input event to mark the `South` gamepad button as released.
/// // This updates the `Input<GamepadButton>` resource accordingly.
/// app.world.send_event(GamepadEventRaw::new(
/// gamepad,
/// GamepadEventType::ButtonChanged(button_type, 0.0)
/// ));
///
/// // Advance the execution of the schedule by another cycle.
/// app.update();
///
/// // Check if the `bool` resource was updated from `true` to `false`.
/// assert!(!app.world.resource::<bool>());
/// #
/// # bevy_ecs::system::assert_is_system(change_resource_on_gamepad_button_press);
/// ```
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub struct GamepadEventRaw {
/// The gamepad this event corresponds to.
pub gamepad: Gamepad,
/// The type of the event.
pub event_type: GamepadEventType,
}
impl GamepadEventRaw {
/// Creates a new [`GamepadEventRaw`].
pub fn new(gamepad: Gamepad, event_type: GamepadEventType) -> Self {
Self {
gamepad,
@ -86,38 +222,93 @@ impl GamepadEventRaw {
}
}
/// A type of a [`GamepadButton`].
///
/// ## Usage
///
/// This is used to determine which button has changed its value when receiving a
/// [`GamepadEventType::ButtonChanged`]. It is also used in the [`GamepadButton`]
/// which in turn is used to create the [`Input<GamepadButton>`] or
/// [`Axis<GamepadButton>`] `bevy` resources.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub enum GamepadButtonType {
/// The bottom action button of the action pad (i.e. PS: Cross, Xbox: A).
South,
/// The right action button of the action pad (i.e. PS: Circle, Xbox: B).
East,
/// The upper action button of the action pad (i.e. PS: Triangle, Xbox: Y).
North,
/// The left action button of the action pad (i.e. PS: Square, Xbox: X).
West,
/// The C button.
C,
/// The Z button.
Z,
/// The first left trigger.
LeftTrigger,
/// The second left trigger.
LeftTrigger2,
/// The first right trigger.
RightTrigger,
/// The second right trigger.
RightTrigger2,
/// The select button.
Select,
/// The start button.
Start,
/// The mode button.
Mode,
/// The left thumb stick button.
LeftThumb,
/// The right thumb stick button.
RightThumb,
/// The up button of the D-Pad.
DPadUp,
/// The down button of the D-Pad.
DPadDown,
/// The left button of the D-Pad.
DPadLeft,
/// The right button of the D-Pad.
DPadRight,
}
/// A button of a [`Gamepad`].
///
/// ## Usage
///
/// It is used as the generic `T` value of an [`Input`] and [`Axis`] to create `bevy` resources. These
/// resources store the data of the buttons and axes of a gamepad and can be accessed inside of a system.
///
/// ## Updating
///
/// The resources are updated inside of the [`gamepad_event_system`].
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub struct GamepadButton {
/// The gamepad on which the button is located on.
pub gamepad: Gamepad,
/// The type of the button.
pub button_type: GamepadButtonType,
}
impl GamepadButton {
/// Creates a new [`GamepadButton`].
///
/// # Examples
///
/// ```
/// # use bevy_input::gamepad::{GamepadButton, GamepadButtonType, Gamepad};
/// #
/// let gamepad_button = GamepadButton::new(
/// Gamepad::new(1),
/// GamepadButtonType::South,
/// );
/// ```
pub fn new(gamepad: Gamepad, button_type: GamepadButtonType) -> Self {
Self {
gamepad,
@ -126,53 +317,148 @@ impl GamepadButton {
}
}
/// A type of a [`GamepadAxis`].
///
/// ## Usage
///
/// This is used to determine which axis has changed its value when receiving a
/// [`GamepadEventType::AxisChanged`]. It is also used in the [`GamepadAxis`]
/// which in turn is used to create the [`Axis<GamepadAxis>`] `bevy` resource.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub enum GamepadAxisType {
/// The horizontal value of the left stick.
LeftStickX,
/// The vertical value of the left stick.
LeftStickY,
/// The value of the left `Z` button.
LeftZ,
/// The horizontal value of the right stick.
RightStickX,
/// The vertical value of the right stick.
RightStickY,
/// The value of the right `Z` button.
RightZ,
}
/// An axis of a [`Gamepad`].
///
/// ## Usage
///
/// It is used as the generic `T` value of an [`Axis`] to create a `bevy` resource. This resource
/// stores the data of the axes of a gamepad and can be accessed inside of a system.
///
/// ## Updating
///
/// The resource is updated inside of the [`gamepad_event_system`].
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
pub struct GamepadAxis {
/// The gamepad on which the axis is located on.
pub gamepad: Gamepad,
/// The type of the axis.
pub axis_type: GamepadAxisType,
}
impl GamepadAxis {
/// Creates a new [`GamepadAxis`].
///
/// # Examples
///
/// ```
/// # use bevy_input::gamepad::{GamepadAxis, GamepadAxisType, Gamepad};
/// #
/// let gamepad_axis = GamepadAxis::new(
/// Gamepad::new(1),
/// GamepadAxisType::LeftStickX,
/// );
/// ```
pub fn new(gamepad: Gamepad, axis_type: GamepadAxisType) -> Self {
Self { gamepad, axis_type }
}
}
/// Settings for all [`Gamepad`]s.
///
/// ## Usage
///
/// It is used to create a `bevy` resource that stores the settings of every [`GamepadButton`] and
/// [`GamepadAxis`]. If no user defined [`ButtonSettings`], [`AxisSettings`], or [`ButtonAxisSettings`]
/// are defined, the default settings of each are used as a fallback accordingly.
///
/// ## Note
///
/// The [`GamepadSettings`] are used inside of the [`gamepad_event_system`], but are never written to
/// inside of `bevy`. To modify these settings, mutate the corresponding resource.
#[derive(Default, Debug)]
pub struct GamepadSettings {
/// The default button settings.
pub default_button_settings: ButtonSettings,
/// The default axis settings.
pub default_axis_settings: AxisSettings,
/// The default button axis settings.
pub default_button_axis_settings: ButtonAxisSettings,
/// The user defined button settings.
pub button_settings: HashMap<GamepadButton, ButtonSettings>,
/// The user defined axis settings.
pub axis_settings: HashMap<GamepadAxis, AxisSettings>,
/// The user defined button axis settings.
pub button_axis_settings: HashMap<GamepadButton, ButtonAxisSettings>,
}
impl GamepadSettings {
/// Returns the [`ButtonSettings`] of the `button`.
///
/// If no user defined [`ButtonSettings`] are specified the default [`ButtonSettings`] get returned.
///
/// # Examples
///
/// ```
/// # use bevy_input::gamepad::{GamepadSettings, GamepadButton, Gamepad, GamepadButtonType};
/// #
/// # let settings = GamepadSettings::default();
/// let button = GamepadButton::new(Gamepad::new(1), GamepadButtonType::South);
/// let button_settings = settings.get_button_settings(button);
/// ```
pub fn get_button_settings(&self, button: GamepadButton) -> &ButtonSettings {
self.button_settings
.get(&button)
.unwrap_or(&self.default_button_settings)
}
/// Returns the [`AxisSettings`] of the `axis`.
///
/// If no user defined [`AxisSettings`] are specified the default [`AxisSettings`] get returned.
///
/// # Examples
///
/// ```
/// # use bevy_input::gamepad::{GamepadSettings, GamepadAxis, Gamepad, GamepadAxisType};
/// #
/// # let settings = GamepadSettings::default();
/// let axis = GamepadAxis::new(Gamepad::new(1), GamepadAxisType::LeftStickX);
/// let axis_settings = settings.get_axis_settings(axis);
/// ```
pub fn get_axis_settings(&self, axis: GamepadAxis) -> &AxisSettings {
self.axis_settings
.get(&axis)
.unwrap_or(&self.default_axis_settings)
}
/// Returns the [`ButtonAxisSettings`] of the `button`.
///
/// If no user defined [`ButtonAxisSettings`] are specified the default [`ButtonAxisSettings`] get returned.
///
/// # Examples
///
/// ```
/// # use bevy_input::gamepad::{GamepadSettings, GamepadButton, Gamepad, GamepadButtonType};
/// #
/// # let settings = GamepadSettings::default();
/// let button = GamepadButton::new(Gamepad::new(1), GamepadButtonType::South);
/// let button_axis_settings = settings.get_button_axis_settings(button);
/// ```
pub fn get_button_axis_settings(&self, button: GamepadButton) -> &ButtonAxisSettings {
self.button_axis_settings
.get(&button)
@ -180,9 +466,22 @@ impl GamepadSettings {
}
}
/// Settings for a [`GamepadButton`].
///
/// ## Usage
///
/// It is used inside of the [`GamepadSettings`] to define the threshold for a gamepad button
/// to be considered pressed or released. A button is considered pressed if the `press`
/// value is surpassed and released if the `release` value is undercut.
///
/// ## Updating
///
/// The current value of a button is received through the [`GamepadEvent`]s or [`GamepadEventRaw`]s.
#[derive(Debug, Clone)]
pub struct ButtonSettings {
/// The threshold for the button to be considered as pressed.
pub press: f32,
/// The threshold for the button to be considered as released.
pub release: f32,
}
@ -196,30 +495,49 @@ impl Default for ButtonSettings {
}
impl ButtonSettings {
/// Returns `true` if the button is pressed.
///
/// A button is considered pressed if the `value` passed is greater than or equal to the `press` threshold.
fn is_pressed(&self, value: f32) -> bool {
value >= self.press
}
/// Returns `true` if the button is released.
///
/// A button is considered released if the `value` passed is lower than or equal to the `release` threshold.
fn is_released(&self, value: f32) -> bool {
value <= self.release
}
}
/// Defines the sensitivity range and threshold for an axis.
/// Settings for a [`GamepadAxis`].
///
/// Values that are lower than `negative_high` will be rounded to -1.0.
/// Values that are higher than `positive_high` will be rounded to 1.0.
/// Values that are in-between `negative_low` and `positive_low` will be rounded to 0.0.
/// Otherwise, values will not be rounded.
/// It is used inside of the [`GamepadSettings`] to define the sensitivity range and
/// threshold for an axis.
///
/// ## Logic
///
/// - Values that are in-between `negative_low` and `positive_low` will be rounded to 0.0.
/// - Values that are higher than or equal to `positive_high` will be rounded to 1.0.
/// - Values that are lower than or equal to `negative_high` will be rounded to -1.0.
/// - Otherwise, values will not be rounded.
///
/// The valid range is from -1.0 to 1.0, inclusive.
///
/// ## Updating
///
/// The current value of an axis is received through the [`GamepadEvent`]s or [`GamepadEventRaw`]s.
#[derive(Debug, Clone)]
pub struct AxisSettings {
/// The positive high value at which to apply rounding.
pub positive_high: f32,
/// The positive low value at which to apply rounding.
pub positive_low: f32,
/// The negative high value at which to apply rounding.
pub negative_high: f32,
/// The negative low value at which to apply rounding.
pub negative_low: f32,
///`threshold` defines the minimum difference between old and new values to apply the changes.
/// The threshold defining the minimum difference between the old and new values to apply the changes.
pub threshold: f32,
}
@ -236,6 +554,16 @@ impl Default for AxisSettings {
}
impl AxisSettings {
/// Filters the `new_value` according to the specified settings.
///
/// If the `new_value` is:
/// - in-between `negative_low` and `positive_low` it will be rounded to 0.0.
/// - higher than or equal to `positive_high` it will be rounded to 1.0.
/// - lower than or equal to `negative_high` it will be rounded to -1.0.
/// - Otherwise it will not be rounded.
///
/// If the difference between the calculated value and the `old_value` is lower or
/// equal to the `threshold`, [`None`] will be returned.
fn filter(&self, new_value: f32, old_value: Option<f32>) -> Option<f32> {
let new_value = if new_value <= self.positive_low && new_value >= self.negative_low {
0.0
@ -257,10 +585,29 @@ impl AxisSettings {
}
}
/// Settings for a [`GamepadButton`].
///
/// It is used inside of the [`GamepadSettings`] to define the sensitivity range and
/// threshold for a button axis.
///
/// ## Logic
///
/// - Values that are higher than or equal to `high` will be rounded to 1.0.
/// - Values that are lower than or equal to `low` will be rounded to 0.0.
/// - Otherwise, values will not be rounded.
///
/// The valid range is from 0.0 to 1.0, inclusive.
///
/// ## Updating
///
/// The current value of a button is received through the [`GamepadEvent`]s or [`GamepadEventRaw`]s.
#[derive(Debug, Clone)]
pub struct ButtonAxisSettings {
/// The high value at which to apply rounding.
pub high: f32,
/// The low value at which to apply rounding.
pub low: f32,
/// The threshold to apply rounding.
pub threshold: f32,
}
@ -275,6 +622,15 @@ impl Default for ButtonAxisSettings {
}
impl ButtonAxisSettings {
/// Filters the `new_value` according to the specified settings.
///
/// If the `new_value` is:
/// - lower than or equal to `low` it will be rounded to 0.0.
/// - higher than or equal to `high` it will be rounded to 1.0.
/// - Otherwise it will not be rounded.
///
/// If the difference between the calculated value and the `old_value` is lower or
/// equal to the `threshold`, [`None`] will be returned.
fn filter(&self, new_value: f32, old_value: Option<f32>) -> Option<f32> {
let new_value = if new_value <= self.low {
0.0
@ -294,9 +650,11 @@ impl ButtonAxisSettings {
}
}
/// Monitors gamepad connection and disconnection events, updating the [`Gamepads`] resource accordingly
/// Monitors gamepad connection and disconnection events and updates the [`Gamepads`] resource accordingly.
///
/// By default, runs during `CoreStage::PreUpdate` when added via [`InputPlugin`](crate::InputPlugin).
/// ## Note
///
/// Whenever a [`Gamepad`] connects or disconnects, an information gets printed to the console using the [`info!`] macro.
pub fn gamepad_connection_system(
mut gamepads: ResMut<Gamepads>,
mut gamepad_event: EventReader<GamepadEvent>,
@ -316,6 +674,16 @@ pub fn gamepad_connection_system(
}
}
/// Modifies the gamepad resources and sends out gamepad events.
///
/// The resources [`Input<GamepadButton>`], [`Axis<GamepadAxis>`], and [`Axis<GamepadButton>`] are updated
/// and the [`GamepadEvent`]s are sent according to the received [`GamepadEventRaw`]s respecting the [`GamepadSettings`].
///
/// ## Differences
///
/// The main difference between the events and the resources is that the latter allows you to check specific
/// buttons or axes, rather than reading the events one at a time. This is done through convenient functions
/// like [`Input::pressed`], [`Input::just_pressed`], [`Input::just_released`], and [`Axis::get`].
pub fn gamepad_event_system(
mut button_input: ResMut<Input<GamepadButton>>,
mut axis: ResMut<Axis<GamepadAxis>>,
@ -388,6 +756,7 @@ pub fn gamepad_event_system(
}
}
/// An array of every [`GamepadButtonType`] variant.
const ALL_BUTTON_TYPES: [GamepadButtonType; 19] = [
GamepadButtonType::South,
GamepadButtonType::East,
@ -410,6 +779,7 @@ const ALL_BUTTON_TYPES: [GamepadButtonType; 19] = [
GamepadButtonType::DPadRight,
];
/// An array of every [`GamepadAxisType`] variant.
const ALL_AXIS_TYPES: [GamepadAxisType; 6] = [
GamepadAxisType::LeftStickX,
GamepadAxisType::LeftStickY,