13 unstable releases (6 breaking)
0.7.0 | Nov 24, 2023 |
---|---|
0.6.0 | Jul 14, 2023 |
0.5.3 | Jan 27, 2023 |
0.5.0 | Nov 24, 2022 |
0.1.1 | Feb 23, 2021 |
#1481 in Game dev
195KB
224 lines
bevy_mouse_tracking_plugin
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
Dependencies
~38–73MB
~1.5M SLoC