Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Bevy Input Docs : gamepad.rs #9469

Merged
merged 7 commits into from
Aug 19, 2023
Merged

Bevy Input Docs : gamepad.rs #9469

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
acb3dfc
doc(bevy_input): add doc for gamepad items
tguichaoua Aug 17, 2023
be7d060
fix some docs
tguichaoua Aug 17, 2023
bbf6bd6
Update crates/bevy_input/src/gamepad.rs
tguichaoua Aug 17, 2023
2d89908
Update crates/bevy_input/src/gamepad.rs
tguichaoua Aug 17, 2023
82ba30b
Update crates/bevy_input/src/gamepad.rs
tguichaoua Aug 17, 2023
083f43f
Update crates/bevy_input/src/gamepad.rs
tguichaoua Aug 17, 2023
ffa1f6e
GamepadInfo name example
tguichaoua Aug 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 48 additions & 18 deletions crates/bevy_input/src/gamepad.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,17 @@ pub enum AxisSettingsError {
/// Parameter `livezone_lowerbound` was not less than or equal to parameter `deadzone_lowerbound`.
#[error("invalid parameter values livezone_lowerbound {} deadzone_lowerbound {}, expected livezone_lowerbound <= deadzone_lowerbound", .livezone_lowerbound, .deadzone_lowerbound)]
LiveZoneLowerBoundGreaterThanDeadZoneLowerBound {
/// The value of the `livezone_lowerbound` parameter.
livezone_lowerbound: f32,
/// The value of the `deadzone_lowerbound` parameter.
deadzone_lowerbound: f32,
},
/// Parameter `deadzone_upperbound` was not less than or equal to parameter `livezone_upperbound`.
#[error("invalid parameter values livezone_upperbound {} deadzone_upperbound {}, expected deadzone_upperbound <= livezone_upperbound", .livezone_upperbound, .deadzone_upperbound)]
DeadZoneUpperBoundGreaterThanLiveZoneUpperBound {
/// The value of the `livezone_upperbound` parameter.
livezone_upperbound: f32,
/// The value of the `deadzone_upperbound` parameter.
deadzone_upperbound: f32,
},
/// The given parameter was not in range 0.0..=2.0.
Expand All @@ -53,7 +57,9 @@ pub enum ButtonSettingsError {
/// Parameter `release_threshold` was not less than or equal to `press_threshold`.
#[error("invalid parameter values release_threshold {} press_threshold {}, expected release_threshold <= press_threshold", .release_threshold, .press_threshold)]
ReleaseThresholdGreaterThanPressThreshold {
/// The value of the `press_threshold` parameter.
press_threshold: f32,
/// The value of the `release_threshold` parameter.
release_threshold: f32,
},
}
Expand Down Expand Up @@ -100,6 +106,7 @@ impl Gamepad {
reflect(Serialize, Deserialize)
)]
pub struct GamepadInfo {
/// The name of the gamepad.
tguichaoua marked this conversation as resolved.
Show resolved Hide resolved
pub name: String,
}

Expand Down Expand Up @@ -130,6 +137,7 @@ impl Gamepads {
self.gamepads.keys().copied()
}

/// The name of the gamepad if this one is connected.
pub fn name(&self, gamepad: Gamepad) -> Option<&str> {
self.gamepads.get(&gamepad).map(|g| g.name.as_str())
}
Expand Down Expand Up @@ -1025,6 +1033,7 @@ pub fn gamepad_connection_system(
}
}

/// The connection status of a gamepad.
#[derive(Debug, Clone, PartialEq, Reflect)]
#[reflect(Debug, PartialEq)]
#[cfg_attr(
Expand All @@ -1033,7 +1042,9 @@ pub fn gamepad_connection_system(
reflect(Serialize, Deserialize)
)]
pub enum GamepadConnection {
/// The gamepad is connected.
Connected(GamepadInfo),
/// The gamepad is disconnected.
Disconnected,
}

Expand All @@ -1054,22 +1065,27 @@ pub struct GamepadConnectionEvent {
}

impl GamepadConnectionEvent {
/// Creates a [`GamepadConnectionEvent`].
pub fn new(gamepad: Gamepad, connection: GamepadConnection) -> Self {
Self {
gamepad,
connection,
}
}

/// Is the gamepad connected.
tguichaoua marked this conversation as resolved.
Show resolved Hide resolved
pub fn connected(&self) -> bool {
matches!(self.connection, GamepadConnection::Connected(_))
}

/// Is the gamepad disconnected.
tguichaoua marked this conversation as resolved.
Show resolved Hide resolved
pub fn disconnected(&self) -> bool {
!self.connected()
}
}

/// Gamepad event for when the "value" on the axis changes
/// by an amount larger than the threshold defined in [`GamepadSettings`].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be interesting to know when this is usually emitted

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see how to make the docs more clear 🤔
Any suggestion ?

#[derive(Event, Debug, Clone, PartialEq, Reflect)]
#[reflect(Debug, PartialEq)]
#[cfg_attr(
Expand All @@ -1078,12 +1094,16 @@ impl GamepadConnectionEvent {
reflect(Serialize, Deserialize)
)]
pub struct GamepadAxisChangedEvent {
/// The gamepad on which the axis is triggered.
pub gamepad: Gamepad,
/// The type of the triggered axis.
pub axis_type: GamepadAxisType,
/// The value of the axis.
pub value: f32,
}

impl GamepadAxisChangedEvent {
/// Creates a [`GamepadAxisChangedEvent`].
pub fn new(gamepad: Gamepad, axis_type: GamepadAxisType, value: f32) -> Self {
Self {
gamepad,
Expand All @@ -1103,12 +1123,16 @@ impl GamepadAxisChangedEvent {
reflect(Serialize, Deserialize)
)]
pub struct GamepadButtonChangedEvent {
/// The gamepad on which the button is triggered.
pub gamepad: Gamepad,
/// The type of the triggered button.
pub button_type: GamepadButtonType,
/// The value of the button.
pub value: f32,
}

impl GamepadButtonChangedEvent {
/// Creates a [`GamepadButtonChangedEvent`].
pub fn new(gamepad: Gamepad, button_type: GamepadButtonType, value: f32) -> Self {
Self {
gamepad,
Expand Down Expand Up @@ -1163,8 +1187,11 @@ pub fn gamepad_button_event_system(
reflect(Serialize, Deserialize)
)]
pub enum GamepadEvent {
/// A gamepad has been connected or disconnected.
Connection(GamepadConnectionEvent),
/// A button of the gamepad has been triggered.
Button(GamepadButtonChangedEvent),
/// An axis of the gamepad has been triggered.
Axis(GamepadAxisChangedEvent),
}

Expand Down Expand Up @@ -1242,54 +1269,54 @@ const ALL_AXIS_TYPES: [GamepadAxisType; 6] = [
/// 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
/// The rumble intensity of the strong gamepad motor.
///
/// Ranges from 0.0 to 1.0
/// 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_motor: f32,
/// The rumble intensity of the weak gamepad motor
/// The rumble intensity of the weak gamepad motor.
///
/// Ranges from 0.0 to 1.0
/// 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_motor: f32,
}

impl GamepadRumbleIntensity {
/// Rumble both gamepad motors at maximum intensity
/// Rumble both gamepad motors at maximum intensity.
pub const MAX: Self = GamepadRumbleIntensity {
strong_motor: 1.0,
weak_motor: 1.0,
};

/// Rumble the weak motor at maximum intensity
/// Rumble the weak motor at maximum intensity.
pub const WEAK_MAX: Self = GamepadRumbleIntensity {
strong_motor: 0.0,
weak_motor: 1.0,
};

/// Rumble the strong motor at maximum intensity
/// Rumble the strong motor at maximum intensity.
pub const STRONG_MAX: Self = GamepadRumbleIntensity {
strong_motor: 1.0,
weak_motor: 0.0,
};

/// Creates a new rumble intensity with weak motor intensity set to the given value
/// Creates a new rumble intensity with weak motor intensity set to the given value.
///
/// Clamped within the 0 to 1 range
/// Clamped within the 0 to 1 range.
tguichaoua marked this conversation as resolved.
Show resolved Hide resolved
pub const fn weak_motor(intensity: f32) -> Self {
Self {
weak_motor: intensity,
strong_motor: 0.0,
}
}

/// Creates a new rumble intensity with strong motor intensity set to the given value
/// Creates a new rumble intensity with strong motor intensity set to the given value.
///
/// Clamped within the 0 to 1 range
/// Clamped within the 0 to 1 range.
tguichaoua marked this conversation as resolved.
Show resolved Hide resolved
pub const fn strong_motor(intensity: f32) -> Self {
Self {
strong_motor: intensity,
Expand All @@ -1298,7 +1325,7 @@ impl GamepadRumbleIntensity {
}
}

/// An event that controls force-feedback rumbling of a [`Gamepad`]
/// An event that controls force-feedback rumbling of a [`Gamepad`].
///
/// # Notes
///
Expand Down Expand Up @@ -1340,19 +1367,22 @@ pub enum GamepadRumbleRequest {
///
/// To replace an existing rumble, send a [`GamepadRumbleRequest::Stop`] event first.
Add {
/// How long the gamepad should rumble
/// How long the gamepad should rumble.
duration: Duration,
/// How intense the rumble should be
/// How intense the rumble should be.
intensity: GamepadRumbleIntensity,
/// The gamepad to rumble
/// The gamepad to rumble.
gamepad: Gamepad,
},
/// Stop all running rumbles on the given [`Gamepad`].
Stop {
/// The gamepad to stop rumble.
gamepad: Gamepad,
},
/// Stop all running rumbles on the given [`Gamepad`]
Stop { gamepad: Gamepad },
}

impl GamepadRumbleRequest {
/// Get the [`Gamepad`] associated with this request
/// Get the [`Gamepad`] associated with this request.
pub fn gamepad(&self) -> Gamepad {
match self {
Self::Add { gamepad, .. } | Self::Stop { gamepad } => *gamepad,
Expand Down
Loading