Mouse
Read mouse buttons, motion and the wheel, find the cursor in the window and the world, and hide, lock or change the cursor.
On this page
The mouse gives you three things: buttons (a ButtonInput<MouseButton>), movement (raw motion, independent of the cursor) and the cursor's position in each window. Use motion for camera look, and the cursor for pointing at things.
Buttons#
ButtonInput<MouseButton> works like the keyboard's; see Keyboard. The buttons are Left, Right, Middle, Back, Forward and Other(n).
fn shoot(buttons: Res<ButtonInput<MouseButton>>) {
if buttons.just_pressed(MouseButton::Left) {
info!("fire");
}
}Motion and the wheel#
Two resources sum up each frame and reset to zero the next:
| Resource | Field | What it is |
|---|---|---|
AccumulatedMouseMotion | delta: Vec2 | How far the mouse moved this frame, in raw device units. It keeps reporting when the cursor is locked or at the edge of the screen. |
AccumulatedMouseScroll | delta: Vec2, unit | How far the wheel or trackpad scrolled this frame. unit is MouseScrollUnit::Line (wheel notches) or MouseScrollUnit::Pixel (trackpads). |
use neo::{
input::mouse::{AccumulatedMouseMotion, AccumulatedMouseScroll},
prelude::*,
};
fn look(motion: Res<AccumulatedMouseMotion>, scroll: Res<AccumulatedMouseScroll>) {
if motion.delta != Vec2::ZERO {
info!("turn by {}, {}", motion.delta.x, motion.delta.y);
}
if scroll.delta.y != 0.0 {
info!("zoom by {}", scroll.delta.y);
}
}For every change in order, read the messages instead:
| Message | What it is |
|---|---|
MouseButtonInput | A button pressed or released, with its window. |
MouseMotion | One raw motion, delta. |
MouseWheel | One scroll: unit, x, y, window. |
CursorMoved | The cursor moved inside a window: position in logical pixels, delta (if known), window. |
PinchGesture, RotationGesture, DoubleTapGesture, PanGesture | Trackpad and touch gestures. Pinch, rotation and double-tap come only from macOS and iOS. |
The cursor's position#
Window::cursor_position() is the cursor in logical pixels from the window's top-left corner, or None when it's outside. Turn it into a ray in the world with the camera:
fn point(
window: Single<&Window>,
camera: Single<(&Camera, &GlobalTransform)>,
mut gizmos: Gizmos,
) {
let (camera, camera_transform) = *camera;
if let Some(cursor) = window.cursor_position()
&& let Ok(ray) = camera.viewport_to_world(camera_transform, cursor)
&& let Some(point) = ray.plane_intersection_point(Vec3::ZERO, InfinitePlane3d::new(Vec3::Y))
{
gizmos.circle(Isometry3d::new(point + Vec3::Y * 0.01, Quat::from_rotation_arc(Vec3::Z, Vec3::Y)), 0.2, Color::WHITE);
}
}In 2D, camera.viewport_to_world_2d(camera_transform, cursor) gives the point in world space. To find which entity is under the cursor, use Picking rather than casting rays yourself.
Hiding and locking the cursor#
Each window entity has a CursorOptions component:
| Field | What it does |
|---|---|
visible | Shows or hides the cursor over the window. |
grab_mode | CursorGrabMode::None (free), Confined (kept inside the window) or Locked (held in place; use mouse motion). |
use neo::window::{CursorGrabMode, CursorOptions};
fn capture(
mut cursor: Single<&mut CursorOptions>,
mouse: Res<ButtonInput<MouseButton>>,
keys: Res<ButtonInput<KeyCode>>,
) {
if mouse.just_pressed(MouseButton::Left) {
cursor.visible = false;
cursor.grab_mode = CursorGrabMode::Locked;
}
if keys.just_pressed(KeyCode::Escape) {
cursor.visible = true;
cursor.grab_mode = CursorGrabMode::None;
}
}| Platform | What changes |
|---|---|
| macOS | No Confined: it falls back to None. |
| Linux (X11) | No Locked: it falls back to Confined. |
| Web | The browser only locks the pointer after a click or key press, and Esc always releases it. NEO's web builds start from a click for this reason. |
| iOS, Android | There's no cursor. |
The gameplay kit captures the mouse on a click and releases it on Esc for you.
The cursor's icon#
Insert a CursorIcon on the window entity to change the pointer, for example CursorIcon::System(SystemCursorIcon::Grabbing) while dragging. Both types are in neo::window. NEO's builds include custom cursor images (CursorIcon::Custom); see Windows.
Examples: cargo run --example mouse_input, mouse_input_events and mouse_grab.