bevy_input/
mouse.rs

1//! The mouse input functionality.
2
3use crate::{ButtonInput, ButtonState};
4use bevy_ecs::{
5    change_detection::DetectChangesMut,
6    entity::Entity,
7    event::{Event, EventReader},
8    system::{ResMut, Resource},
9};
10use bevy_math::Vec2;
11#[cfg(feature = "bevy_reflect")]
12use {
13    bevy_ecs::reflect::ReflectResource,
14    bevy_reflect::{std_traits::ReflectDefault, Reflect},
15};
16
17#[cfg(all(feature = "serialize", feature = "bevy_reflect"))]
18use bevy_reflect::{ReflectDeserialize, ReflectSerialize};
19
20/// A mouse button input event.
21///
22/// This event is the translated version of the `WindowEvent::MouseInput` from the `winit` crate.
23///
24/// ## Usage
25///
26/// The event is read inside of the [`mouse_button_input_system`]
27/// to update the [`ButtonInput<MouseButton>`] resource.
28#[derive(Event, Debug, Clone, Copy, PartialEq, Eq)]
29#[cfg_attr(feature = "bevy_reflect", derive(Reflect), reflect(Debug, PartialEq))]
30#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
31#[cfg_attr(
32    all(feature = "serialize", feature = "bevy_reflect"),
33    reflect(Serialize, Deserialize)
34)]
35pub struct MouseButtonInput {
36    /// The mouse button assigned to the event.
37    pub button: MouseButton,
38    /// The pressed state of the button.
39    pub state: ButtonState,
40    /// Window that received the input.
41    pub window: Entity,
42}
43
44/// A button on a mouse device.
45///
46/// ## Usage
47///
48/// It is used as the generic `T` value of an [`ButtonInput`] to create a `bevy`
49/// resource.
50///
51/// ## Updating
52///
53/// The resource is updated inside of the [`mouse_button_input_system`].
54#[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
55#[cfg_attr(
56    feature = "bevy_reflect",
57    derive(Reflect),
58    reflect(Debug, Hash, PartialEq)
59)]
60#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
61#[cfg_attr(
62    all(feature = "serialize", feature = "bevy_reflect"),
63    reflect(Serialize, Deserialize)
64)]
65pub enum MouseButton {
66    /// The left mouse button.
67    Left,
68    /// The right mouse button.
69    Right,
70    /// The middle mouse button.
71    Middle,
72    /// The back mouse button.
73    Back,
74    /// The forward mouse button.
75    Forward,
76    /// Another mouse button with the associated number.
77    Other(u16),
78}
79
80/// An event reporting the change in physical position of a pointing device.
81///
82/// This represents raw, unfiltered physical motion.
83/// It is the translated version of [`DeviceEvent::MouseMotion`] from the `winit` crate.
84///
85/// All pointing devices connected to a single machine at the same time can emit the event independently.
86/// However, the event data does not make it possible to distinguish which device it is referring to.
87///
88/// [`DeviceEvent::MouseMotion`]: https://docs.rs/winit/latest/winit/event/enum.DeviceEvent.html#variant.MouseMotion
89#[derive(Event, Debug, Clone, Copy, PartialEq)]
90#[cfg_attr(feature = "bevy_reflect", derive(Reflect), reflect(Debug, PartialEq))]
91#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
92#[cfg_attr(
93    all(feature = "serialize", feature = "bevy_reflect"),
94    reflect(Serialize, Deserialize)
95)]
96pub struct MouseMotion {
97    /// The change in the position of the pointing device since the last event was sent.
98    pub delta: Vec2,
99}
100
101/// The scroll unit.
102///
103/// Describes how a value of a [`MouseWheel`] event has to be interpreted.
104///
105/// The value of the event can either be interpreted as the amount of lines or the amount of pixels
106/// to scroll.
107#[derive(Debug, Hash, Clone, Copy, Eq, PartialEq)]
108#[cfg_attr(feature = "bevy_reflect", derive(Reflect), reflect(Debug, PartialEq))]
109#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
110#[cfg_attr(
111    all(feature = "serialize", feature = "bevy_reflect"),
112    reflect(Serialize, Deserialize)
113)]
114pub enum MouseScrollUnit {
115    /// The line scroll unit.
116    ///
117    /// The delta of the associated [`MouseWheel`] event corresponds
118    /// to the amount of lines or rows to scroll.
119    Line,
120    /// The pixel scroll unit.
121    ///
122    /// The delta of the associated [`MouseWheel`] event corresponds
123    /// to the amount of pixels to scroll.
124    Pixel,
125}
126
127/// A mouse wheel event.
128///
129/// This event is the translated version of the `WindowEvent::MouseWheel` from the `winit` crate.
130#[derive(Event, Debug, Clone, Copy, PartialEq)]
131#[cfg_attr(feature = "bevy_reflect", derive(Reflect), reflect(Debug, PartialEq))]
132#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
133#[cfg_attr(
134    all(feature = "serialize", feature = "bevy_reflect"),
135    reflect(Serialize, Deserialize)
136)]
137pub struct MouseWheel {
138    /// The mouse scroll unit.
139    pub unit: MouseScrollUnit,
140    /// The horizontal scroll value.
141    pub x: f32,
142    /// The vertical scroll value.
143    pub y: f32,
144    /// Window that received the input.
145    pub window: Entity,
146}
147
148/// Updates the [`ButtonInput<MouseButton>`] resource with the latest [`MouseButtonInput`] events.
149///
150/// ## Differences
151///
152/// The main difference between the [`MouseButtonInput`] event and the [`ButtonInput<MouseButton>`] resource is that
153/// the latter has convenient functions like [`ButtonInput::pressed`], [`ButtonInput::just_pressed`] and [`ButtonInput::just_released`].
154pub fn mouse_button_input_system(
155    mut mouse_button_input: ResMut<ButtonInput<MouseButton>>,
156    mut mouse_button_input_events: EventReader<MouseButtonInput>,
157) {
158    mouse_button_input.bypass_change_detection().clear();
159    for event in mouse_button_input_events.read() {
160        match event.state {
161            ButtonState::Pressed => mouse_button_input.press(event.button),
162            ButtonState::Released => mouse_button_input.release(event.button),
163        }
164    }
165}
166
167/// Tracks how much the mouse has moved every frame.
168///
169/// This resource is reset to zero every frame.
170///
171/// This resource sums the total [`MouseMotion`] events received this frame.
172#[derive(Resource, Debug, Clone, Copy, PartialEq, Default)]
173#[cfg_attr(
174    feature = "bevy_reflect",
175    derive(Reflect),
176    reflect(Debug, Default, Resource, PartialEq)
177)]
178#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
179#[cfg_attr(
180    all(feature = "serialize", feature = "bevy_reflect"),
181    reflect(Serialize, Deserialize)
182)]
183pub struct AccumulatedMouseMotion {
184    /// The change in mouse position.
185    pub delta: Vec2,
186}
187
188/// Tracks how much the mouse has scrolled every frame.
189///
190/// This resource is reset to zero every frame.
191///
192/// This resource sums the total [`MouseWheel`] events received this frame.
193#[derive(Resource, Debug, Clone, Copy, PartialEq)]
194#[cfg_attr(
195    feature = "bevy_reflect",
196    derive(Reflect),
197    reflect(Debug, Default, Resource, PartialEq)
198)]
199#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
200#[cfg_attr(
201    all(feature = "serialize", feature = "bevy_reflect"),
202    reflect(Serialize, Deserialize)
203)]
204pub struct AccumulatedMouseScroll {
205    /// The mouse scroll unit.
206    /// If this value changes while scrolling, then the
207    /// result of the accumulation could be incorrect
208    pub unit: MouseScrollUnit,
209    /// The change in scroll position.
210    pub delta: Vec2,
211}
212
213impl Default for AccumulatedMouseScroll {
214    fn default() -> Self {
215        Self {
216            unit: MouseScrollUnit::Line,
217            delta: Vec2::ZERO,
218        }
219    }
220}
221
222/// Updates the [`AccumulatedMouseMotion`] resource using the [`MouseMotion`] event.
223/// The value of [`AccumulatedMouseMotion`] is reset to zero every frame
224pub fn accumulate_mouse_motion_system(
225    mut mouse_motion_event: EventReader<MouseMotion>,
226    mut accumulated_mouse_motion: ResMut<AccumulatedMouseMotion>,
227) {
228    let mut delta = Vec2::ZERO;
229    for event in mouse_motion_event.read() {
230        delta += event.delta;
231    }
232    accumulated_mouse_motion.delta = delta;
233}
234
235/// Updates the [`AccumulatedMouseScroll`] resource using the [`MouseWheel`] event.
236/// The value of [`AccumulatedMouseScroll`] is reset to zero every frame
237pub fn accumulate_mouse_scroll_system(
238    mut mouse_scroll_event: EventReader<MouseWheel>,
239    mut accumulated_mouse_scroll: ResMut<AccumulatedMouseScroll>,
240) {
241    let mut delta = Vec2::ZERO;
242    let mut unit = MouseScrollUnit::Line;
243    for event in mouse_scroll_event.read() {
244        if event.unit != unit {
245            unit = event.unit;
246        }
247        delta += Vec2::new(event.x, event.y);
248    }
249    accumulated_mouse_scroll.delta = delta;
250    accumulated_mouse_scroll.unit = unit;
251}
bevy_input/mouse.rs

bevy_input/
mouse.rs
