Skip to content

A plugin for effortless mouse tracking in the bevy game engine.

Notifications You must be signed in to change notification settings

JoJoJet/bevy-mouse-tracking

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

53 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

bevy_mouse_tracking_plugin

CI bevy_mouse_tracking on crates.io bevy_mouse_tracking docs

Versions

Bevy Version Crate Version
0.12 0.7
0.11 0.6
0.9 0.5
0.8 0.4
0.7 0.2.1
0.6 0.2.0
main branch main branch

This crate aims to make mouse tracking both effortless and explicit. Tracking is opt-in and handled opaquely by this plugin.

The mouse can be tracked on a per-camera basis by querying for tracking components. Additionally, a global resource is maintained that tracks the main camera, if applicable.

Basics

use bevy::prelude::*;
use bevy_mouse_tracking_plugin::prelude::*;

// First, add the plugin to your `App`.

App::new()
    .add_plugins((DefaultPlugins, MousePosPlugin))
    .add_systems(Startup, setup)
    .add_systems(Update, dbg_mouse)
    // ...


fn setup(mut commands: Commands) {
    commands
        // Spawn a camera bundle
        .spawn(Camera2dBundle::default())
        // Opt in to mouse tracking.
        // `InitMouseTracking` is a command that adds the mouse tracking
        // component to the camera with a correct initial value.
        .add(InitMouseTracking);
}

// Now, we can track the mouse position by querying for it.

use bevy_mouse_tracking_plugin::MousePos;

fn dbg_mouse(mouse: Query<&MousePos>) {
    // This will print the screen-space location of the mouse on every frame.
    eprintln!("{}", *mouse.single());
    // If we did `mouse.iter()` instead, this will naturally work for multiple cameras.
}

Having to call Query::single is a bit annoying, and potentially error-prone. Instead, we can specify a main camera, which the plugin will treat specially.

use bevy_mouse_tracking_plugin::MainCamera;

fn setup(mut commands: Commands) {
    commands
        // Spawn a camera with tracking.
        .spawn(Camera2dBundle::default())
        .add(InitMouseTracking)
        // Add a component to mark it as the main camera.
        .insert(MainCamera);
}

// Now that we've specified the main camera, we can get the mouse position using a global resource.

fn dbg_mouse(mouse: Res<MousePos>) {
    // This will print the screen-space location of the mouse on every frame.
    eprintln!("{}", *mouse);
}

World-space

We can do better than just screen-space: this crate supports automatic transformation to world-space coordinates via [MousePosWorld] -- this is can be accessed as either a component or a resource.

use bevy_mouse_tracking_plugin::MousePosWorld;

fn setup(mut commands: Commands) {
    commands
        .spawn(Camera2dBundle::default())
        // Opt in to world-space mouse tracking.
        // This will automatically opt into screen-space tracking.
        .add(InitWorldTracking)
        // ...
}

// Getting the world-space position using a query.
fn dbg_world_single(mouse: Query<&MousePosWorld>) {
    // This will print the world-space position of the mouse on every frame.
    eprintln!("{}", *mouse.single());
}

// Getting it using the resource.
fn dbg_world_res(mouse: Res<MousePosWorld>) {
    eprintln!("{}", *mouse);
}

Note that this is only supported for two-dimensional, orthographic cameras, but pull requests for 3D support are welcome!

If you do not specify a [MainCamera], the [MousePos] and [MousePosWorld] resources will still exist, but they will always be zero.

Mouse motion

This crate supports a resource that tracks mouse motion, via [MouseMotionPlugin]. The motion can be accessed from any system in a [MouseMotion] resource.

Crate name

As a final aside: the name of this crate is intentionally verbose, since it is very likely that this crate will eventually be made redundant by future updates to Bevy.
I recommend renaming the crate in your Cargo.toml:

[dependencies]
mouse_tracking = { package = "bevy_mouse_tracking_plugin", version = "..." }

License: MIT

About

A plugin for effortless mouse tracking in the bevy game engine.

Topics

Resources

Stars

Watchers

Forks

Languages