1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

//! [![CI](https://github.com/JoJoJet/bevy-mouse-tracking/actions/workflows/ci.yml/badge.svg)](https://github.com/JoJoJet/bevy-mouse-tracking/workflows/ci.yml)
//! [![bevy_mouse_tracking on crates.io](https://img.shields.io/crates/v/bevy_mouse_tracking_plugin.svg)](https://crates.io/crates/bevy_mouse_tracking_plugin)
//! [![bevy_mouse_tracking docs](https://img.shields.io/badge/docs-docs.rs-orange.svg)](https://docs.rs/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)
//!     // ...
//! #    .update();
//!
//!
//! 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::prelude::*;
//! # use bevy_mouse_tracking_plugin::{prelude::*, MousePos};
//! # App::new()
//! #    .add_plugins((DefaultPlugins, MousePosPlugin))
//! #    .add_systems(Startup, setup)
//! #    .add_systems(Update, dbg_mouse)
//! #    .update();
//! 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::prelude::*;
//! # use bevy_mouse_tracking_plugin::{prelude::*, MousePos, MainCamera};
//! # App::new()
//! #    .add_plugins((DefaultPlugins, MousePosPlugin))
//! #    .add_systems(Startup, setup)
//! #    .add_systems(Update, (dbg_world_single, dbg_world_res))
//! #    .update();
//! 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)
//!         // ...
//! #       .insert(MainCamera);
//! }
//!
//! // 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.
//!
//! [`Res`]: bevy::ecs::system::Res

#![allow(clippy::type_complexity)]

pub mod prelude {
    pub use crate::mouse_motion::MouseMotionPlugin;
    pub use crate::mouse_pos::{InitMouseTracking, InitWorldTracking, MousePosPlugin};
}

pub mod mouse_pos;
pub use mouse_pos::{MainCamera, MousePos, MousePosWorld};

pub mod mouse_motion;
pub use mouse_motion::MouseMotion;