bevymousetracking_plugin

Versions

| Bevy Version | Crate Version | |--------------|---------------| | 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

```rust use bevy::prelude::; use bevy_mouse_tracking_plugin::prelude::;

// First, add the plugin to your App.

App::new() .addplugins(DefaultPlugins) .addplugin(MousePosPlugin) .addstartupsystem(setup) .addsystem(dbgmouse) // ...

fn setup(mut commands: Commands) { commands // Spawn a camera bundle .spawn(Camera2dBundle::default()) // Opt in to mouse tracking .addmousetracking(); }

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

use bevymousetracking_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.

```rust use bevymousetracking_plugin::MainCamera;

fn setup(mut commands: Commands) { commands // Spawn a camera with tracking. .spawn(Camera2dBundle::default()) .addmousetracking() // 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) { // 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.

```rust use bevymousetracking_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. .addworldtracking() // ... }

// Getting the world-space position using a query. fn dbgworldsingle(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 dbgworldres(mouse: Res) { 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: toml [dependencies] mouse_tracking = { package = "bevy_mouse_tracking_plugin", version = "..." }

License: MIT