NEOLearn

Mouse

Read mouse buttons, motion and the wheel, find the cursor in the window and the world, and hide, lock or change the cursor.

Updated October 20, 2026

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).

Rust
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:

ResourceFieldWhat it is
AccumulatedMouseMotiondelta: Vec2How 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.
AccumulatedMouseScrolldelta: Vec2, unitHow far the wheel or trackpad scrolled this frame. unit is MouseScrollUnit::Line (wheel notches) or MouseScrollUnit::Pixel (trackpads).
src/main.rs
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:

MessageWhat it is
MouseButtonInputA button pressed or released, with its window.
MouseMotionOne raw motion, delta.
MouseWheelOne scroll: unit, x, y, window.
CursorMovedThe cursor moved inside a window: position in logical pixels, delta (if known), window.
PinchGesture, RotationGesture, DoubleTapGesture, PanGestureTrackpad 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:

Rust
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:

FieldWhat it does
visibleShows or hides the cursor over the window.
grab_modeCursorGrabMode::None (free), Confined (kept inside the window) or Locked (held in place; use mouse motion).
Rust
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;
    }
}
PlatformWhat changes
macOSNo Confined: it falls back to None.
Linux (X11)No Locked: it falls back to Confined.
WebThe 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, AndroidThere'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.

Next steps#