smooth_bevy_cameras/
lib.rs

1//! [![crates.io](https://img.shields.io/crates/v/smooth_bevy_cameras)](https://crates.io/crates/smooth_bevy_cameras)
2//! [![docs.rs](https://docs.rs/smooth-bevy-cameras/badge.svg)](https://docs.rs/smooth-bevy-cameras)
3//!
4//! A collection of exponentially-smoothed camera controllers for the Bevy
5//! Engine.
6//!
7//! # Look Transform
8//!
9//! All controllers are based on a [`LookTransform`] component, which is just an
10//! `eye` point that looks at a `target` point. By modifying this component, the
11//! scene graph `Transform` will automatically be synchronized.
12//!
13//! Any entities with all of `Transform`, LookTransform, and [`Smoother`]
14//! components will automatically have their `Transform` smoothed. Smoothing
15//! will have no effect on the `LookTransform`, only the final `Transform` in
16//! the scene graph.
17//!
18//! ```rust
19//! use bevy::prelude::*;
20//! use smooth_bevy_cameras::{LookTransform, LookTransformBundle, LookTransformPlugin, Smoother};
21//!
22//! fn main() {
23//!     App::new()
24//!         .add_plugins(DefaultPlugins)
25//!         // Enables the system that synchronizes your `Transform`s and `LookTransform`s.
26//!         .add_plugins(LookTransformPlugin)
27//!         .add_systems(Startup, setup)
28//!         .add_systems(Update, move_camera_system);
29//! }
30//!
31//! fn setup(mut commands: Commands) {
32//!     let eye = Vec3::default();
33//!     let target = Vec3::default();
34//!
35//!     commands
36//!         .spawn((Camera3d::default(),
37//                  LookTransform::new(eye, target, Vec3::Y),
38//!                 Smoother::new(0.9), // Value between 0.0 and 1.0, higher is smoother.
39//!         ));
40//!
41//! }
42//!
43//! fn move_camera_system(mut cameras: Query<&mut LookTransform>) {
44//!     // Later, another system will update the `Transform` and apply smoothing automatically.
45//!     for mut c in cameras.iter_mut() { c.target += Vec3::new(1.0, 1.0, 1.0); }
46//! }
47//! ```
48//!
49//! # Look Angles
50//!
51//! When implementing a camera controller, it's often useful to work directly
52//! with the angles (pitch and yaw) of your look direction. You can do this with
53//! the [`LookAngles`] type:
54//!
55//! ```rust
56//! use bevy::prelude::*;
57//! use smooth_bevy_cameras::{
58//!     LookAngles,
59//!     LookTransform
60//! };
61//!
62//! fn look_angles(mut transform: LookTransform, delta: Vec2) {
63//!     let mut angles = LookAngles::from_vector(transform.look_direction().unwrap());
64//!     angles.add_pitch(delta.y);
65//!     angles.add_yaw(delta.x);
66//!     // Third-person.
67//!     transform.eye = transform.target + 1.0 * transform.radius() * angles.unit_vector();
68//!     // First-person.
69//!     // transform.target = transform.eye + 1.0 * transform.radius() * angles.unit_vector();
70//! }
71//! ```
72//!
73//! This is how the built-in controllers implement rotation controls.
74//!
75//! # Built-In Controllers
76//!
77//! These plugins depend on the [`LookTransformPlugin`]:
78//!
79//! - [`FpsCameraPlugin`](crate::controllers::fps::FpsCameraPlugin) +
80//!   [`FpsCameraBundle`](crate::controllers::fps::FpsCameraBundle)
81//!   - WASD: Translate on the XZ plane
82//!   - Shift/Space: Translate along the Y axis
83//!   - Mouse: Rotate camera
84//! - [`OrbitCameraPlugin`](crate::controllers::orbit::OrbitCameraPlugin) +
85//!   [`OrbitCameraBundle`](crate::controllers::orbit::OrbitCameraBundle)
86//!   - CTRL + mouse drag: Rotate camera
87//!   - Right mouse drag: Pan camera
88//!   - Mouse wheel: Zoom
89//! - [`UnrealCameraPlugin`](crate::controllers::unreal::UnrealCameraPlugin) +
90//!   [`UnrealCameraBundle`](crate::controllers::unreal::UnrealCameraBundle)
91//!
92//!   Best use: hold Right mouse button to orbit the view while using WASD to
93//!   navigate in the scene, using scroll wheel to accelerate/decelerate.
94//!   - Left mouse drag: Locomotion
95//!   - Right mouse drag: Rotate camera
96//!   - Left and Right or Middle mouse drag: Pan camera
97//!   - While holding any mouse button, use A/D for panning left/right, Q/E for
98//!     panning up/down
99//!   - While holding any mouse button, use W/S for locomotion forward/backward
100//!   - While holding any mouse button, use scroll wheel to increase/decrease
101//!     locomotion and panning speeds
102//!   - While holding no mouse button, use scroll wheel for locomotion
103//!     forward/backward
104
105pub mod controllers;
106
107mod look_angles;
108mod look_transform;
109
110pub use look_angles::*;
111pub use look_transform::*;
smooth_bevy_cameras/lib.rs

smooth_bevy_cameras/
lib.rs
