├── .github
    └── workflows
    │   └── main.yml
├── .gitignore
├── CHANGELOG.md
├── Cargo.toml
├── LICENSE-APACHE
├── LICENSE-MIT
├── README.md
├── assets
    └── demo.gif
├── examples
    ├── advanced.rs
    └── basic.rs
└── src
    ├── controller.rs
    └── lib.rs


/.github/workflows/main.yml:
--------------------------------------------------------------------------------
 1 | on:
 2 |   push:
 3 |     branches:
 4 |       - main
 5 |   pull_request:
 6 |     branches:
 7 |       - main
 8 | 
 9 | name: Continuous integration
10 | 
11 | jobs:
12 |   build:
13 |     name: Build
14 |     runs-on: ubuntu-latest
15 |     steps:
16 |       - uses: actions/checkout@v4
17 |       - uses: dtolnay/rust-toolchain@stable
18 |       - run: cargo build
19 | 
20 |   test:
21 |     name: Test
22 |     runs-on: ubuntu-latest
23 |     steps:
24 |       - uses: actions/checkout@v4
25 |       - uses: dtolnay/rust-toolchain@stable
26 |       - name: Install alsa and udev
27 |         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev
28 |         if: runner.os == 'linux'
29 |       - run: cargo test
30 | 
31 |   build-examples:
32 |     name: Build Examples
33 |     runs-on: ubuntu-latest
34 |     steps:
35 |       - uses: actions/checkout@v4
36 |       - uses: dtolnay/rust-toolchain@stable
37 |       - name: Install alsa and udev
38 |         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev
39 |         if: runner.os == 'linux'
40 |       - run: cargo build --examples
41 | 
42 |   fmt:
43 |     name: Rustfmt
44 |     runs-on: ubuntu-latest
45 |     steps:
46 |       - uses: actions/checkout@v4
47 |       - uses: dtolnay/rust-toolchain@stable
48 |       - run: rustup component add rustfmt
49 |       - run: cargo fmt --all -- --check
50 | 
51 |   clippy:
52 |     name: Clippy
53 |     runs-on: ubuntu-latest
54 |     steps:
55 |       - uses: actions/checkout@v4
56 |       - uses: dtolnay/rust-toolchain@stable
57 |       - run: rustup component add clippy
58 |       - run: cargo clippy -- -D warnings
59 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /target
2 | /Cargo.lock
3 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | ## 0.10
 2 | 
 3 | - Update to Bevy 0.16
 4 | 
 5 | ## 0.9.2
 6 | 
 7 | - Fixes bug with bounds calculation, causing incorrect behaviour when bounds are asymmetrical (#30)
 8 | 
 9 | ## 0.9.1
10 | 
11 | - Add `Camera3d` as a required component (new feature of Bevy 0.15) of `RtsCamera`, so you don't have to add it manually
12 | 
13 | ## 0.9
14 | 
15 | - Update to Bevy 0.15
16 | 
17 | ## 0.8.1
18 | 
19 | - Adds a `reset_smoothing` method to `RtsCamera`
20 | 
21 | ## 0.8
22 | 
23 | - Update to Bevy 0.14
24 | - Fix issue that caused the camera to move after initialization
25 | 
26 | ## 0.7 and older
27 | 
28 | I dunno, stuff. I only just created this file now, sorry.
29 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "bevy_rts_camera"
 3 | version = "0.10.0"
 4 | authors = ["Plonq"]
 5 | edition = "2021"
 6 | description = "An RTS-style camera for Bevy"
 7 | keywords = ["gamedev", "bevy", "rts", "camera"]
 8 | categories = ["game-development"]
 9 | license = "MIT OR Apache-2.0"
10 | repository = "https://github.com/Plonq/bevy_rts_camera"
11 | homepage = "https://github.com/Plonq/bevy_rts_camera"
12 | readme = "README.md"
13 | exclude = ["assets/"]
14 | 
15 | [dependencies]
16 | bevy = { version = "0.16", default-features = false, features = [
17 |     "bevy_core_pipeline",
18 |     "bevy_render",
19 |     "bevy_window",
20 |     "bevy_picking",
21 |     "bevy_mesh_picking_backend",
22 | ] }
23 | 
24 | [dev-dependencies]
25 | bevy = { version = "0.16" }
26 | 


--------------------------------------------------------------------------------
/LICENSE-APACHE:
--------------------------------------------------------------------------------
  1 |                                  Apache License
  2 |                            Version 2.0, January 2004
  3 |                         http://www.apache.org/licenses/
  4 | 
  5 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  6 | 
  7 |    1. Definitions.
  8 | 
  9 |       "License" shall mean the terms and conditions for use, reproduction,
 10 |       and distribution as defined by Sections 1 through 9 of this document.
 11 | 
 12 |       "Licensor" shall mean the copyright owner or entity authorized by
 13 |       the copyright owner that is granting the License.
 14 | 
 15 |       "Legal Entity" shall mean the union of the acting entity and all
 16 |       other entities that control, are controlled by, or are under common
 17 |       control with that entity. For the purposes of this definition,
 18 |       "control" means (i) the power, direct or indirect, to cause the
 19 |       direction or management of such entity, whether by contract or
 20 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 21 |       outstanding shares, or (iii) beneficial ownership of such entity.
 22 | 
 23 |       "You" (or "Your") shall mean an individual or Legal Entity
 24 |       exercising permissions granted by this License.
 25 | 
 26 |       "Source" form shall mean the preferred form for making modifications,
 27 |       including but not limited to software source code, documentation
 28 |       source, and configuration files.
 29 | 
 30 |       "Object" form shall mean any form resulting from mechanical
 31 |       transformation or translation of a Source form, including but
 32 |       not limited to compiled object code, generated documentation,
 33 |       and conversions to other media types.
 34 | 
 35 |       "Work" shall mean the work of authorship, whether in Source or
 36 |       Object form, made available under the License, as indicated by a
 37 |       copyright notice that is included in or attached to the work
 38 |       (an example is provided in the Appendix below).
 39 | 
 40 |       "Derivative Works" shall mean any work, whether in Source or Object
 41 |       form, that is based on (or derived from) the Work and for which the
 42 |       editorial revisions, annotations, elaborations, or other modifications
 43 |       represent, as a whole, an original work of authorship. For the purposes
 44 |       of this License, Derivative Works shall not include works that remain
 45 |       separable from, or merely link (or bind by name) to the interfaces of,
 46 |       the Work and Derivative Works thereof.
 47 | 
 48 |       "Contribution" shall mean any work of authorship, including
 49 |       the original version of the Work and any modifications or additions
 50 |       to that Work or Derivative Works thereof, that is intentionally
 51 |       submitted to Licensor for inclusion in the Work by the copyright owner
 52 |       or by an individual or Legal Entity authorized to submit on behalf of
 53 |       the copyright owner. For the purposes of this definition, "submitted"
 54 |       means any form of electronic, verbal, or written communication sent
 55 |       to the Licensor or its representatives, including but not limited to
 56 |       communication on electronic mailing lists, source code control systems,
 57 |       and issue tracking systems that are managed by, or on behalf of, the
 58 |       Licensor for the purpose of discussing and improving the Work, but
 59 |       excluding communication that is conspicuously marked or otherwise
 60 |       designated in writing by the copyright owner as "Not a Contribution."
 61 | 
 62 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 63 |       on behalf of whom a Contribution has been received by Licensor and
 64 |       subsequently incorporated within the Work.
 65 | 
 66 |    2. Grant of Copyright License. Subject to the terms and conditions of
 67 |       this License, each Contributor hereby grants to You a perpetual,
 68 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 69 |       copyright license to reproduce, prepare Derivative Works of,
 70 |       publicly display, publicly perform, sublicense, and distribute the
 71 |       Work and such Derivative Works in Source or Object form.
 72 | 
 73 |    3. Grant of Patent License. Subject to the terms and conditions of
 74 |       this License, each Contributor hereby grants to You a perpetual,
 75 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 76 |       (except as stated in this section) patent license to make, have made,
 77 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 78 |       where such license applies only to those patent claims licensable
 79 |       by such Contributor that are necessarily infringed by their
 80 |       Contribution(s) alone or by combination of their Contribution(s)
 81 |       with the Work to which such Contribution(s) was submitted. If You
 82 |       institute patent litigation against any entity (including a
 83 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 84 |       or a Contribution incorporated within the Work constitutes direct
 85 |       or contributory patent infringement, then any patent licenses
 86 |       granted to You under this License for that Work shall terminate
 87 |       as of the date such litigation is filed.
 88 | 
 89 |    4. Redistribution. You may reproduce and distribute copies of the
 90 |       Work or Derivative Works thereof in any medium, with or without
 91 |       modifications, and in Source or Object form, provided that You
 92 |       meet the following conditions:
 93 | 
 94 |       (a) You must give any other recipients of the Work or
 95 |           Derivative Works a copy of this License; and
 96 | 
 97 |       (b) You must cause any modified files to carry prominent notices
 98 |           stating that You changed the files; and
 99 | 
100 |       (c) You must retain, in the Source form of any Derivative Works
101 |           that You distribute, all copyright, patent, trademark, and
102 |           attribution notices from the Source form of the Work,
103 |           excluding those notices that do not pertain to any part of
104 |           the Derivative Works; and
105 | 
106 |       (d) If the Work includes a "NOTICE" text file as part of its
107 |           distribution, then any Derivative Works that You distribute must
108 |           include a readable copy of the attribution notices contained
109 |           within such NOTICE file, excluding those notices that do not
110 |           pertain to any part of the Derivative Works, in at least one
111 |           of the following places: within a NOTICE text file distributed
112 |           as part of the Derivative Works; within the Source form or
113 |           documentation, if provided along with the Derivative Works; or,
114 |           within a display generated by the Derivative Works, if and
115 |           wherever such third-party notices normally appear. The contents
116 |           of the NOTICE file are for informational purposes only and
117 |           do not modify the License. You may add Your own attribution
118 |           notices within Derivative Works that You distribute, alongside
119 |           or as an addendum to the NOTICE text from the Work, provided
120 |           that such additional attribution notices cannot be construed
121 |           as modifying the License.
122 | 
123 |       You may add Your own copyright statement to Your modifications and
124 |       may provide additional or different license terms and conditions
125 |       for use, reproduction, or distribution of Your modifications, or
126 |       for any such Derivative Works as a whole, provided Your use,
127 |       reproduction, and distribution of the Work otherwise complies with
128 |       the conditions stated in this License.
129 | 
130 |    5. Submission of Contributions. Unless You explicitly state otherwise,
131 |       any Contribution intentionally submitted for inclusion in the Work
132 |       by You to the Licensor shall be under the terms and conditions of
133 |       this License, without any additional terms or conditions.
134 |       Notwithstanding the above, nothing herein shall supersede or modify
135 |       the terms of any separate license agreement you may have executed
136 |       with Licensor regarding such Contributions.
137 | 
138 |    6. Trademarks. This License does not grant permission to use the trade
139 |       names, trademarks, service marks, or product names of the Licensor,
140 |       except as required for reasonable and customary use in describing the
141 |       origin of the Work and reproducing the content of the NOTICE file.
142 | 
143 |    7. Disclaimer of Warranty. Unless required by applicable law or
144 |       agreed to in writing, Licensor provides the Work (and each
145 |       Contributor provides its Contributions) on an "AS IS" BASIS,
146 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 |       implied, including, without limitation, any warranties or conditions
148 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 |       PARTICULAR PURPOSE. You are solely responsible for determining the
150 |       appropriateness of using or redistributing the Work and assume any
151 |       risks associated with Your exercise of permissions under this License.
152 | 
153 |    8. Limitation of Liability. In no event and under no legal theory,
154 |       whether in tort (including negligence), contract, or otherwise,
155 |       unless required by applicable law (such as deliberate and grossly
156 |       negligent acts) or agreed to in writing, shall any Contributor be
157 |       liable to You for damages, including any direct, indirect, special,
158 |       incidental, or consequential damages of any character arising as a
159 |       result of this License or out of the use or inability to use the
160 |       Work (including but not limited to damages for loss of goodwill,
161 |       work stoppage, computer failure or malfunction, or any and all
162 |       other commercial damages or losses), even if such Contributor
163 |       has been advised of the possibility of such damages.
164 | 
165 |    9. Accepting Warranty or Additional Liability. While redistributing
166 |       the Work or Derivative Works thereof, You may choose to offer,
167 |       and charge a fee for, acceptance of support, warranty, indemnity,
168 |       or other liability obligations and/or rights consistent with this
169 |       License. However, in accepting such obligations, You may act only
170 |       on Your own behalf and on Your sole responsibility, not on behalf
171 |       of any other Contributor, and only if You agree to indemnify,
172 |       defend, and hold each Contributor harmless for any liability
173 |       incurred by, or claims asserted against, such Contributor by reason
174 |       of your accepting any such warranty or additional liability.
175 | 
176 |    END OF TERMS AND CONDITIONS
177 | 


--------------------------------------------------------------------------------
/LICENSE-MIT:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy
 4 | of this software and associated documentation files (the "Software"), to deal
 5 | in the Software without restriction, including without limitation the rights
 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 7 | copies of the Software, and to permit persons to whom the Software is
 8 | furnished to do so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in all
11 | copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19 | SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | [![Crates.io](https://img.shields.io/crates/v/bevy_rts_camera)](https://crates.io/crates/bevy_rts_camera)
 2 | [![docs.rs](https://docs.rs/bevy_rts_camera/badge.svg)](https://docs.rs/bevy_rts_camera)
 3 | [![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)
 4 | 
 5 | <div style="text-align: center">
 6 |   <h1>Bevy RTS Camera</h1>
 7 | </div>
 8 | 
 9 | ![A screen recording showing camera movement](assets/demo.gif "Demo of bevy_rts_camera")
10 | 
11 | ## Summary
12 | 
13 | Bevy RTS Camera provides an RTS-style camera for Bevy Engine, to get your game up and running quickly. Designed for
14 | simple use cases, and does not try to cover advanced requirements.
15 | 
16 | ## Features:
17 | 
18 | - Pan, zoom, and rotation
19 | - Automatically follows whatever you mark as 'ground'
20 | - Smoothed movement
21 | - Customisable controls and other settings
22 | - Comes with optional controller, or you can control it yourself
23 | 
24 | ## Default Controller
25 | 
26 | A default controller is included with these default controls:
27 | 
28 | - Arrow Keys: pan
29 | - Mouse Wheel: zoom
30 | - Middle Mouse: rotate
31 | 
32 | You can also 'edge pan' by moving the mouse to the edge of the screen.
33 | 
34 | ## Quick Start
35 | 
36 | Add the plugin:
37 | 
38 | ```rust ignore
39 | .add_plugins(RtsCameraPlugin)
40 | ```
41 | 
42 | Add `RtsCamera` (this will automatically add a `Camera3d` but you can add it manually if necessary):
43 | 
44 | ```rust ignore
45 | commands.spawn((
46 |     RtsCamera::default(),
47 |     RtsCameraControls::default(),  // Optional
48 | ));
49 | ```
50 | 
51 | Add `Ground` to your ground/terrain entities:
52 | 
53 | ```rust ignore
54 | commands.spawn((
55 |     PbrBundle {
56 |         mesh: meshes.add(Plane3d::default().mesh().size(80.0, 80.0)),
57 |         ..default()
58 |     },
59 |     Ground,
60 | ));
61 | ```
62 | 
63 | This will set up a camera at world origin with good defaults based on a roughly realistic scale (where an average human
64 | is 1.75 units tall).
65 | 
66 | Check out the [advanced example](https://github.com/Plonq/bevy_rts_camera/blob/main/examples/advanced.rs) to see
67 | the possible configuration options.
68 | 
69 | ## Version Compatibility
70 | 
71 | | bevy | bevy_rts_camera |
72 | |------|-----------------|
73 | | 0.16 | 0.10            |
74 | | 0.15 | 0.9             |
75 | | 0.14 | 0.8             |
76 | | 0.13 | 0.1-0.7         |
77 | 
78 | ## License
79 | 
80 | All code in this repository is dual-licensed under either:
81 | 
82 | * MIT License ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
83 | * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)
84 |   or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
85 | 
86 | at your option.
87 | This means you can select the license you prefer!
88 | This dual-licensing approach is the de-facto standard in the Rust ecosystem and there
89 | are [very good reasons](https://github.com/bevyengine/bevy/issues/2373) to include both.
90 | 


--------------------------------------------------------------------------------
/assets/demo.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Plonq/bevy_rts_camera/073909b9d6e464bb3d3f25372b2a1fe4ebfca559/assets/demo.gif


--------------------------------------------------------------------------------
/examples/advanced.rs:
--------------------------------------------------------------------------------
  1 | //! A more complex scene with a moving "unit" that demonstrates how to jump to a location or lock
  2 | //! onto a particular entity.
  3 | 
  4 | use std::f32::consts::TAU;
  5 | 
  6 | use bevy::prelude::*;
  7 | 
  8 | use bevy_rts_camera::{Ground, RtsCamera, RtsCameraControls, RtsCameraPlugin, RtsCameraSystemSet};
  9 | 
 10 | fn main() {
 11 |     App::new()
 12 |         .add_plugins(DefaultPlugins)
 13 |         .add_plugins(RtsCameraPlugin)
 14 |         .add_systems(Startup, setup)
 15 |         .add_systems(
 16 |             Update,
 17 |             (move_unit, (lock_or_jump, toggle_controls))
 18 |                 .chain()
 19 |                 .before(RtsCameraSystemSet),
 20 |         )
 21 |         .run();
 22 | }
 23 | 
 24 | #[derive(Component)]
 25 | struct Move;
 26 | 
 27 | fn setup(
 28 |     mut commands: Commands,
 29 |     mut meshes: ResMut<Assets<Mesh>>,
 30 |     mut materials: ResMut<Assets<StandardMaterial>>,
 31 | ) {
 32 |     // Ground
 33 |     commands.spawn((
 34 |         Mesh3d(meshes.add(Plane3d::default().mesh().size(80.0, 80.0))),
 35 |         MeshMaterial3d(materials.add(Color::srgb(0.3, 0.5, 0.3))),
 36 |         // Add `Ground` component to any entity you want the camera to treat as ground.
 37 |         Ground,
 38 |     ));
 39 |     // Some "terrain"
 40 |     let terrain_material = materials.add(Color::srgb(0.8, 0.7, 0.6));
 41 |     commands.spawn((
 42 |         Mesh3d(meshes.add(Cuboid::new(15.0, 1.0, 5.0))),
 43 |         MeshMaterial3d(terrain_material.clone()),
 44 |         Transform::from_xyz(15.0, 0.5, -5.0),
 45 |         Ground,
 46 |     ));
 47 |     commands.spawn((
 48 |         Mesh3d(meshes.add(Cuboid::new(10.0, 5.0, 15.0))),
 49 |         MeshMaterial3d(terrain_material.clone()),
 50 |         Transform::from_xyz(-15.0, 2.5, 0.0),
 51 |         Ground,
 52 |     ));
 53 |     commands.spawn((
 54 |         Mesh3d(meshes.add(Sphere::new(12.5))),
 55 |         MeshMaterial3d(terrain_material.clone()),
 56 |         Transform::from_xyz(0.0, 0.0, -23.0),
 57 |         Ground,
 58 |     ));
 59 |     // Some generic units that are not part of the 'Ground' (ignored for height calculation)
 60 |     for x in -5..5 {
 61 |         for z in -5..5 {
 62 |             commands.spawn((
 63 |                 Mesh3d(meshes.add(Capsule3d::new(0.25, 1.25))),
 64 |                 MeshMaterial3d(terrain_material.clone()),
 65 |                 Transform::from_xyz(x as f32 * 0.7, 0.75, z as f32 * 0.7),
 66 |             ));
 67 |         }
 68 |     }
 69 |     // A moving unit that can be locked onto
 70 |     commands
 71 |         .spawn((
 72 |             Mesh3d(meshes.add(Capsule3d::new(0.25, 1.25))),
 73 |             MeshMaterial3d(terrain_material.clone()),
 74 |             Transform::from_xyz(0.0, 0.75, 0.0),
 75 |         ))
 76 |         .insert(Move);
 77 |     // Light
 78 |     commands.spawn((
 79 |         DirectionalLight {
 80 |             illuminance: 1000.0,
 81 |             shadows_enabled: true,
 82 |             ..default()
 83 |         },
 84 |         Transform::from_rotation(Quat::from_euler(
 85 |             EulerRot::YXZ,
 86 |             150.0f32.to_radians(),
 87 |             -40.0f32.to_radians(),
 88 |             0.0,
 89 |         )),
 90 |     ));
 91 |     // Help text
 92 |     commands.spawn(Text::new(
 93 |         "\
 94 | Press K to jump to the moving unit
 95 | Hold L to lock onto the moving unit
 96 | Press T to toggle controls (K and L will still work)",
 97 |     ));
 98 |     // Camera
 99 |     commands.spawn((
100 |         RtsCamera {
101 |             // Increase min height (decrease max zoom)
102 |             // height_min: 10.0,
103 |             // Increase max height (decrease min zoom)
104 |             height_max: 50.0,
105 |             // Change the angle of the camera to 35 degrees
106 |             min_angle: 35.0f32.to_radians(),
107 |             // Decrease smoothing
108 |             smoothness: 0.1,
109 |             // Change starting position
110 |             target_focus: Transform::from_xyz(3.0, 0.0, -3.0),
111 |             // Change starting zoom level
112 |             target_zoom: 0.2,
113 |             // Disable dynamic angle (angle of camera will stay at `min_angle`)
114 |             // dynamic_angle: false,
115 |             ..default()
116 |         },
117 |         RtsCameraControls {
118 |             // Change pan controls to WASD
119 |             key_up: KeyCode::KeyW,
120 |             key_down: KeyCode::KeyS,
121 |             key_left: KeyCode::KeyA,
122 |             key_right: KeyCode::KeyD,
123 |             // Rotate the camera with right click
124 |             button_rotate: MouseButton::Right,
125 |             // Keep the mouse cursor in place when rotating
126 |             lock_on_rotate: true,
127 |             // Drag pan with middle click
128 |             button_drag: Some(MouseButton::Middle),
129 |             // Keep the mouse cursor in place when dragging
130 |             lock_on_drag: true,
131 |             // Change the width of the area that triggers edge pan. 0.1 is 10% of the window height.
132 |             edge_pan_width: 0.1,
133 |             // Increase pan speed
134 |             pan_speed: 25.0,
135 |             ..default()
136 |         },
137 |     ));
138 | }
139 | 
140 | // Move a unit in a circle
141 | fn move_unit(
142 |     time: Res<Time>,
143 |     mut cube_q: Query<&mut Transform, With<Move>>,
144 |     mut angle: Local<f32>,
145 | ) {
146 |     if let Ok(mut cube_tfm) = cube_q.single_mut() {
147 |         // Rotate 20 degrees a second, wrapping around to 0 after a full rotation
148 |         *angle += 20f32.to_radians() * time.delta_secs() % TAU;
149 |         // Convert angle to position
150 |         let pos = Vec3::new(angle.sin() * 7.5, 0.75, angle.cos() * 7.5);
151 |         cube_tfm.translation = pos;
152 |     }
153 | }
154 | 
155 | // Either jump to the moving unit (press K) or lock onto it (hold L)
156 | fn lock_or_jump(
157 |     key_input: Res<ButtonInput<KeyCode>>,
158 |     cube_q: Query<&Transform, With<Move>>,
159 |     mut cam_q: Query<&mut RtsCamera>,
160 | ) {
161 |     for cube in cube_q.iter() {
162 |         for mut cam in cam_q.iter_mut() {
163 |             if key_input.pressed(KeyCode::KeyL) {
164 |                 cam.target_focus.translation = cube.translation;
165 |                 cam.snap = true;
166 |             }
167 |             if key_input.just_pressed(KeyCode::KeyK) {
168 |                 cam.target_focus.translation = cube.translation;
169 |                 cam.target_zoom = 0.4;
170 |             }
171 |         }
172 |     }
173 | }
174 | 
175 | fn toggle_controls(
176 |     mut controls_q: Query<&mut RtsCameraControls>,
177 |     key_input: Res<ButtonInput<KeyCode>>,
178 | ) {
179 |     for mut controls in controls_q.iter_mut() {
180 |         if key_input.just_pressed(KeyCode::KeyT) {
181 |             controls.enabled = !controls.enabled;
182 |         }
183 |     }
184 | }
185 | 


--------------------------------------------------------------------------------
/examples/basic.rs:
--------------------------------------------------------------------------------
 1 | //! A basic scene with some "terrain" and "units" to demonstrate how to set up a basic
 2 | //! RTS camera.
 3 | 
 4 | use bevy::prelude::*;
 5 | 
 6 | use bevy_rts_camera::{Ground, RtsCamera, RtsCameraControls, RtsCameraPlugin};
 7 | 
 8 | fn main() {
 9 |     App::new()
10 |         .add_plugins(DefaultPlugins)
11 |         .add_plugins(RtsCameraPlugin)
12 |         .add_systems(Startup, setup)
13 |         .run();
14 | }
15 | 
16 | fn setup(
17 |     mut commands: Commands,
18 |     mut meshes: ResMut<Assets<Mesh>>,
19 |     mut materials: ResMut<Assets<StandardMaterial>>,
20 | ) {
21 |     // Ground
22 |     commands.spawn((
23 |         Mesh3d(meshes.add(Plane3d::default().mesh().size(80.0, 80.0))),
24 |         MeshMaterial3d(materials.add(Color::srgb(0.3, 0.5, 0.3))),
25 |         // Add `Ground` component to any entity you want the camera to treat as ground.
26 |         Ground,
27 |     ));
28 |     // Some "terrain"
29 |     let terrain_material = materials.add(Color::srgb(0.8, 0.7, 0.6));
30 |     commands.spawn((
31 |         Mesh3d(meshes.add(Cuboid::new(15.0, 1.0, 5.0))),
32 |         MeshMaterial3d(terrain_material.clone()),
33 |         Transform::from_xyz(15.0, 0.5, -5.0),
34 |         Ground,
35 |     ));
36 |     commands.spawn((
37 |         Mesh3d(meshes.add(Cuboid::new(10.0, 5.0, 15.0))),
38 |         MeshMaterial3d(terrain_material.clone()),
39 |         Transform::from_xyz(-15.0, 2.5, 0.0),
40 |         Ground,
41 |     ));
42 |     commands.spawn((
43 |         Mesh3d(meshes.add(Sphere::new(12.5))),
44 |         MeshMaterial3d(terrain_material.clone()),
45 |         Transform::from_xyz(0.0, 0.0, -23.0),
46 |         Ground,
47 |     ));
48 |     // Some generic units that are not part of the 'Ground' (ignored for height calculation)
49 |     for x in -5..5 {
50 |         for z in -5..5 {
51 |             commands.spawn((
52 |                 Mesh3d(meshes.add(Capsule3d::new(0.25, 1.25))),
53 |                 MeshMaterial3d(terrain_material.clone()),
54 |                 Transform::from_xyz(x as f32 * 0.7, 0.75, z as f32 * 0.7),
55 |             ));
56 |         }
57 |     }
58 |     // Light
59 |     commands.spawn((
60 |         DirectionalLight {
61 |             illuminance: 1000.0,
62 |             shadows_enabled: true,
63 |             ..default()
64 |         },
65 |         Transform::from_rotation(Quat::from_euler(
66 |             EulerRot::YXZ,
67 |             150.0f32.to_radians(),
68 |             -40.0f32.to_radians(),
69 |             0.0,
70 |         )),
71 |     ));
72 |     // Camera
73 |     commands.spawn((RtsCamera::default(), RtsCameraControls::default()));
74 | }
75 | 


--------------------------------------------------------------------------------
/src/controller.rs:
--------------------------------------------------------------------------------
  1 | #![allow(clippy::too_many_arguments)]
  2 | 
  3 | use crate::{Ground, RtsCamera, RtsCameraSystemSet};
  4 | use bevy::input::mouse::{MouseMotion, MouseScrollUnit, MouseWheel};
  5 | use bevy::input::ButtonInput;
  6 | use bevy::prelude::*;
  7 | use bevy::window::{CursorGrabMode, PrimaryWindow};
  8 | use std::f32::consts::PI;
  9 | 
 10 | pub struct RtsCameraControlsPlugin;
 11 | 
 12 | impl Plugin for RtsCameraControlsPlugin {
 13 |     fn build(&self, app: &mut App) {
 14 |         app.add_systems(
 15 |             Update,
 16 |             (zoom, pan, grab_pan, rotate).before(RtsCameraSystemSet),
 17 |         );
 18 |     }
 19 | }
 20 | 
 21 | /// Optional camera controller. If you want to use an input manager, don't use this and instead
 22 | /// control the camera yourself by updating `RtsCamera.target_focus` and `RtsCamera.target_zoom`.
 23 | /// # Example
 24 | /// ```no_run
 25 | /// # use bevy::prelude::*;
 26 | /// # use bevy_rts_camera::{RtsCameraPlugin, RtsCamera, RtsCameraControls};
 27 | /// # fn main() {
 28 | /// #     App::new()
 29 | /// #         .add_plugins(DefaultPlugins)
 30 | /// #         .add_plugins(RtsCameraPlugin)
 31 | /// #         .add_systems(Startup, setup)
 32 | /// #         .run();
 33 | /// # }
 34 | /// fn setup(mut commands: Commands) {
 35 | ///     commands
 36 | ///         .spawn((
 37 | ///             RtsCamera::default(),
 38 | ///             RtsCameraControls::default(),
 39 | ///         ));
 40 | ///  }
 41 | /// ```
 42 | #[derive(Component, Debug, PartialEq, Clone)]
 43 | pub struct RtsCameraControls {
 44 |     /// The key that will pan the camera up (or forward).
 45 |     /// Defaults to `KeyCode::ArrowUp`.
 46 |     pub key_up: KeyCode,
 47 |     /// The key that will pan the camera down (or backward).
 48 |     /// Defaults to `KeyCode::ArrowDown`.
 49 |     pub key_down: KeyCode,
 50 |     /// The key that will pan the camera left.
 51 |     /// Defaults to `KeyCode::ArrowLeft`.
 52 |     pub key_left: KeyCode,
 53 |     /// The key that will pan the camera right.
 54 |     /// Defaults to `KeyCode::ArrowRight`.
 55 |     pub key_right: KeyCode,
 56 |     /// The mouse button used to rotate the camera.
 57 |     /// Defaults to `MouseButton::Middle`.
 58 |     pub button_rotate: MouseButton,
 59 |     /// The key that will rotate the camera left.
 60 |     /// Defaults to `KeyCode::KeyQ`.
 61 |     pub key_rotate_left: KeyCode,
 62 |     /// The key that will rotate the camera right.
 63 |     /// Defaults to `KeyCode::KeyE`.
 64 |     pub key_rotate_right: KeyCode,
 65 |     /// How fast the keys will rotate the camera.
 66 |     /// Defaults to `16.0`.
 67 |     pub key_rotate_speed: f32,
 68 |     /// Whether to lock the mouse cursor in place while rotating.
 69 |     /// Defaults to `false`.
 70 |     pub lock_on_rotate: bool,
 71 |     /// The mouse button used to 'drag pan' the camera.
 72 |     /// Defaults to `None`.
 73 |     pub button_drag: Option<MouseButton>,
 74 |     /// Whether to lock the mouse cursor in place while dragging.
 75 |     /// Defaults to `false`.
 76 |     pub lock_on_drag: bool,
 77 |     /// How far away from the side of the screen edge pan will kick in, defined as a percentage
 78 |     /// of the window's height. Set to `0.0` to disable edge panning.
 79 |     /// Defaults to `0.05` (5%).
 80 |     pub edge_pan_width: f32,
 81 |     /// Speed of camera pan (either via keyboard controls or edge panning).
 82 |     /// Defaults to `15.0`.
 83 |     pub pan_speed: f32,
 84 |     /// How much the camera will zoom.
 85 |     /// Defaults to `1.0`.
 86 |     pub zoom_sensitivity: f32,
 87 |     /// Whether these controls are enabled.
 88 |     /// Defaults to `true`.
 89 |     pub enabled: bool,
 90 | }
 91 | 
 92 | impl Default for RtsCameraControls {
 93 |     fn default() -> Self {
 94 |         RtsCameraControls {
 95 |             key_up: KeyCode::ArrowUp,
 96 |             key_down: KeyCode::ArrowDown,
 97 |             key_left: KeyCode::ArrowLeft,
 98 |             key_right: KeyCode::ArrowRight,
 99 |             button_rotate: MouseButton::Middle,
100 |             key_rotate_left: KeyCode::KeyQ,
101 |             key_rotate_right: KeyCode::KeyE,
102 |             key_rotate_speed: 16.0,
103 |             lock_on_rotate: false,
104 |             button_drag: None,
105 |             lock_on_drag: false,
106 |             edge_pan_width: 0.05,
107 |             pan_speed: 15.0,
108 |             zoom_sensitivity: 1.0,
109 |             enabled: true,
110 |         }
111 |     }
112 | }
113 | 
114 | pub fn zoom(
115 |     mut mouse_wheel: EventReader<MouseWheel>,
116 |     mut cam_q: Query<(&mut RtsCamera, &RtsCameraControls)>,
117 | ) {
118 |     for (mut cam, cam_controls) in cam_q.iter_mut().filter(|(_, ctrl)| ctrl.enabled) {
119 |         let zoom_amount = mouse_wheel
120 |             .read()
121 |             .map(|event| match event.unit {
122 |                 MouseScrollUnit::Line => event.y,
123 |                 MouseScrollUnit::Pixel => event.y * 0.001,
124 |             })
125 |             .fold(0.0, |acc, val| acc + val);
126 |         let new_zoom =
127 |             (cam.target_zoom + zoom_amount * 0.5 * cam_controls.zoom_sensitivity).clamp(0.0, 1.0);
128 |         cam.target_zoom = new_zoom;
129 |     }
130 | }
131 | 
132 | pub fn pan(
133 |     mut cam_q: Query<(&mut RtsCamera, &RtsCameraControls)>,
134 |     button_input: Res<ButtonInput<KeyCode>>,
135 |     mouse_input: Res<ButtonInput<MouseButton>>,
136 |     primary_window_q: Query<&Window, With<PrimaryWindow>>,
137 |     time: Res<Time<Real>>,
138 | ) {
139 |     for (mut cam, controller) in cam_q.iter_mut().filter(|(_, ctrl)| ctrl.enabled) {
140 |         if controller
141 |             .button_drag
142 |             .is_some_and(|btn| mouse_input.pressed(btn))
143 |         {
144 |             continue;
145 |         }
146 | 
147 |         let mut delta = Vec3::ZERO;
148 | 
149 |         // Keyboard pan
150 |         if button_input.pressed(controller.key_up) {
151 |             delta += Vec3::from(cam.target_focus.forward())
152 |         }
153 |         if button_input.pressed(controller.key_down) {
154 |             delta += Vec3::from(cam.target_focus.back())
155 |         }
156 |         if button_input.pressed(controller.key_left) {
157 |             delta += Vec3::from(cam.target_focus.left())
158 |         }
159 |         if button_input.pressed(controller.key_right) {
160 |             delta += Vec3::from(cam.target_focus.right())
161 |         }
162 | 
163 |         // Edge pan
164 |         if delta.length_squared() == 0.0 && !mouse_input.pressed(controller.button_rotate) {
165 |             if let Ok(primary_window) = primary_window_q.single() {
166 |                 if let Some(cursor_position) = primary_window.cursor_position() {
167 |                     let win_w = primary_window.width();
168 |                     let win_h = primary_window.height();
169 |                     let pan_width = win_h * controller.edge_pan_width;
170 |                     // Pan left
171 |                     if cursor_position.x < pan_width {
172 |                         delta += Vec3::from(cam.target_focus.left())
173 |                     }
174 |                     // Pan right
175 |                     if cursor_position.x > win_w - pan_width {
176 |                         delta += Vec3::from(cam.target_focus.right())
177 |                     }
178 |                     // Pan up
179 |                     if cursor_position.y < pan_width {
180 |                         delta += Vec3::from(cam.target_focus.forward())
181 |                     }
182 |                     // Pan down
183 |                     if cursor_position.y > win_h - pan_width {
184 |                         delta += Vec3::from(cam.target_focus.back())
185 |                     }
186 |                 }
187 |             }
188 |         }
189 | 
190 |         let new_target = cam.target_focus.translation
191 |             + delta.normalize_or_zero()
192 |             * time.delta_secs()
193 |             * controller.pan_speed
194 |             // Scale based on zoom so it (roughly) feels the same speed at different zoom levels
195 |             * cam.target_zoom.remap(0.0, 1.0, 1.0, 0.5);
196 |         cam.target_focus.translation = new_target;
197 |     }
198 | }
199 | 
200 | pub fn grab_pan(
201 |     mut cam_q: Query<(
202 |         &Transform,
203 |         &GlobalTransform,
204 |         &mut RtsCamera,
205 |         &RtsCameraControls,
206 |         &Camera,
207 |         &Projection,
208 |     )>,
209 |     mut mouse_motion: EventReader<MouseMotion>,
210 |     mouse_button: Res<ButtonInput<MouseButton>>,
211 |     mut ray_cast: MeshRayCast,
212 |     mut ray_hit: Local<Option<Vec3>>,
213 |     ground_q: Query<Entity, With<Ground>>,
214 |     mut primary_window_q: Query<&mut Window, With<PrimaryWindow>>,
215 |     mut previous_mouse_grab_mode: Local<CursorGrabMode>,
216 | ) {
217 |     for (cam_tfm, cam_gtfm, mut cam, controller, camera, projection) in cam_q
218 |         .iter_mut()
219 |         .filter(|(_, _, _, ctrl, _, _)| ctrl.enabled)
220 |     {
221 |         let Some(drag_button) = controller.button_drag else {
222 |             continue;
223 |         };
224 |         let Ok(mut primary_window) = primary_window_q.single_mut() else {
225 |             return;
226 |         };
227 | 
228 |         if mouse_button.just_pressed(drag_button) && controller.lock_on_drag {
229 |             let Some(cursor_position) = primary_window.cursor_position() else {
230 |                 return;
231 |             };
232 | 
233 |             *previous_mouse_grab_mode = primary_window.cursor_options.grab_mode;
234 |             primary_window.cursor_options.grab_mode = CursorGrabMode::Locked;
235 |             primary_window.cursor_options.visible = false;
236 | 
237 |             if let Ok(cursor_ray) = camera.viewport_to_world(cam_gtfm, cursor_position) {
238 |                 *ray_hit = ray_cast
239 |                     .cast_ray(
240 |                         cursor_ray,
241 |                         &MeshRayCastSettings {
242 |                             filter: &|entity| ground_q.get(entity).is_ok(),
243 |                             ..default()
244 |                         },
245 |                     )
246 |                     .first()
247 |                     .map(|(_, hit)| hit.point);
248 |             }
249 |         }
250 | 
251 |         if mouse_button.just_released(drag_button) {
252 |             *ray_hit = None;
253 | 
254 |             primary_window.cursor_options.grab_mode = *previous_mouse_grab_mode;
255 |             primary_window.cursor_options.visible = true;
256 |         }
257 | 
258 |         if mouse_button.pressed(drag_button) {
259 |             let mut mouse_delta = mouse_motion.read().map(|e| e.delta).sum::<Vec2>();
260 | 
261 |             let mut multiplier = 1.0;
262 |             let vp_size = camera.logical_viewport_size().unwrap();
263 |             match *projection {
264 |                 Projection::Perspective(ref p) => {
265 |                     mouse_delta *= Vec2::new(p.fov * p.aspect_ratio, p.fov) / vp_size;
266 |                     multiplier = (*ray_hit).map_or_else(
267 |                         || cam_tfm.translation.distance(cam.focus.translation),
268 |                         |hit| hit.distance(cam_tfm.translation),
269 |                     );
270 |                 }
271 |                 Projection::Orthographic(ref p) => {
272 |                     mouse_delta *= Vec2::new(p.area.width(), p.area.height()) / vp_size;
273 |                 }
274 |                 Projection::Custom(ref _p) => todo!(),
275 |             }
276 | 
277 |             let mut delta = Vec3::ZERO;
278 |             delta += cam.target_focus.forward() * mouse_delta.y;
279 |             delta += cam.target_focus.right() * -mouse_delta.x;
280 |             cam.target_focus.translation += delta * multiplier;
281 |         }
282 |     }
283 | }
284 | 
285 | pub fn rotate(
286 |     mut cam_q: Query<(&mut RtsCamera, &RtsCameraControls)>,
287 |     mouse_input: Res<ButtonInput<MouseButton>>,
288 |     keys: Res<ButtonInput<KeyCode>>,
289 |     mut mouse_motion: EventReader<MouseMotion>,
290 |     mut primary_window_q: Query<&mut Window, With<PrimaryWindow>>,
291 |     mut previous_mouse_grab_mode: Local<CursorGrabMode>,
292 | ) {
293 |     if let Ok(mut primary_window) = primary_window_q.single_mut() {
294 |         for (mut cam, controller) in cam_q.iter_mut().filter(|(_, ctrl)| ctrl.enabled) {
295 |             if mouse_input.just_pressed(controller.button_rotate) && controller.lock_on_rotate {
296 |                 *previous_mouse_grab_mode = primary_window.cursor_options.grab_mode;
297 |                 primary_window.cursor_options.grab_mode = CursorGrabMode::Locked;
298 |                 primary_window.cursor_options.visible = false;
299 |             }
300 | 
301 |             if mouse_input.pressed(controller.button_rotate) {
302 |                 let mouse_delta = mouse_motion.read().map(|e| e.delta).sum::<Vec2>();
303 |                 // Adjust based on window size, so that moving mouse entire width of window
304 |                 // will be one half rotation (180 degrees)
305 |                 let delta_x = mouse_delta.x / primary_window.width() * PI;
306 |                 cam.target_focus.rotate_local_y(-delta_x);
307 |             } else {
308 |                 let left = if keys.pressed(controller.key_rotate_left) {
309 |                     1.0
310 |                 } else {
311 |                     0.0
312 |                 };
313 |                 let right = if keys.pressed(controller.key_rotate_right) {
314 |                     1.0
315 |                 } else {
316 |                     0.0
317 |                 };
318 | 
319 |                 let delta = right - left;
320 |                 if delta != 0.0 {
321 |                     cam.target_focus.rotate_local_y(
322 |                         delta / primary_window.width() * PI * controller.key_rotate_speed,
323 |                     );
324 |                 }
325 |             }
326 | 
327 |             if mouse_input.just_released(controller.button_rotate) {
328 |                 primary_window.cursor_options.grab_mode = *previous_mouse_grab_mode;
329 |                 primary_window.cursor_options.visible = true;
330 |             }
331 |         }
332 |     }
333 | }
334 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
  1 | #![warn(missing_docs)]
  2 | #![doc = include_str!("../README.md")]
  3 | 
  4 | use std::f32::consts::TAU;
  5 | 
  6 | use bevy::math::bounding::Aabb2d;
  7 | use bevy::picking::mesh_picking::ray_cast::RayMeshHit;
  8 | use bevy::prelude::*;
  9 | 
 10 | pub use controller::RtsCameraControls;
 11 | 
 12 | use crate::controller::RtsCameraControlsPlugin;
 13 | 
 14 | mod controller;
 15 | 
 16 | const MAX_ANGLE: f32 = TAU / 5.0;
 17 | 
 18 | /// Bevy plugin that provides RTS camera controls.
 19 | /// # Example
 20 | /// ```no_run
 21 | /// # use bevy::prelude::*;
 22 | /// # use bevy_rts_camera::{RtsCameraPlugin};
 23 | /// fn main() {
 24 | ///     App::new()
 25 | ///         .add_plugins(DefaultPlugins)
 26 | ///         .add_plugins(RtsCameraPlugin)
 27 | ///         .run();
 28 | /// }
 29 | /// ```
 30 | pub struct RtsCameraPlugin;
 31 | 
 32 | impl Plugin for RtsCameraPlugin {
 33 |     fn build(&self, app: &mut App) {
 34 |         app.add_plugins(RtsCameraControlsPlugin)
 35 |             .add_systems(PreUpdate, initialize)
 36 |             .add_systems(
 37 |                 Update,
 38 |                 (
 39 |                     follow_ground,
 40 |                     snap_to_target,
 41 |                     dynamic_angle,
 42 |                     move_towards_target,
 43 |                     apply_camera_bounds,
 44 |                     update_camera_transform,
 45 |                 )
 46 |                     .chain()
 47 |                     .in_set(RtsCameraSystemSet),
 48 |             );
 49 |     }
 50 | }
 51 | 
 52 | /// System set containing all the systems that control the RTS camera.
 53 | /// If you want to control the camera manually in any way (e.g. snapping to a specific location),
 54 | /// you should run that before this system set.
 55 | #[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
 56 | pub struct RtsCameraSystemSet;
 57 | 
 58 | /// Marks a camera to be used as an RTS camera.
 59 | /// Only one instance of this component should exist at any given moment.
 60 | /// This does not include a controller. Add `RtsCameraControls` as well if you want.
 61 | /// # Example
 62 | /// ```no_run
 63 | /// # use bevy::prelude::*;
 64 | /// # use bevy_rts_camera::{RtsCameraPlugin, RtsCamera};
 65 | /// # fn main() {
 66 | /// #     App::new()
 67 | /// #         .add_plugins(DefaultPlugins)
 68 | /// #         .add_plugins(RtsCameraPlugin)
 69 | /// #         .add_systems(Startup, setup)
 70 | /// #         .run();
 71 | /// # }
 72 | /// fn setup(mut commands: Commands) {
 73 | ///     commands
 74 | ///         .spawn((
 75 | ///             RtsCamera::default(),
 76 | ///         ));
 77 | ///  }
 78 | /// ```
 79 | #[derive(Component, Copy, Clone, Debug)]
 80 | #[require(Camera3d)]
 81 | pub struct RtsCamera {
 82 |     /// The minimum height the camera can zoom in to, or the height of the camera at `1.0` zoom.
 83 |     /// Should be set to a value that avoids clipping.
 84 |     /// Defaults to `0.5`.
 85 |     pub height_min: f32,
 86 |     /// The maximum height the camera can zoom out to, or the height of the camera at `0.0` zoom.
 87 |     /// Defaults to `10.0`.
 88 |     pub height_max: f32,
 89 |     /// The bounds in which the camera is constrained, along the XZ plane of `target_focus`. This
 90 |     /// prevents panning past these limits. Imagine looking directly down relative to `target_focus`
 91 |     /// and the XZ plane corresponds XY of the Vec2s, except +Y is up/forward (-Z).
 92 |     /// Defaults to `Aabb2d::new(Vec2::ZERO, Vec2::new(20.0, 20.0))` (i.e. can move 20.0 in any
 93 |     /// direction starting at world center).
 94 |     pub bounds: Aabb2d,
 95 |     /// The current angle in radians of the camera, where a value of `0.0` is looking directly down
 96 |     /// (-Y), and a value of `TAU / 4.0` (90 degrees) is looking directly forward.
 97 |     /// If you want to customise the angle, set `min_angle` instead.
 98 |     /// Defaults to 25 degrees.
 99 |     pub angle: f32,
100 |     /// The target angle in radians of the camera, where a value of `0.0` is looking directly down
101 |     /// (-Y), and a value of `TAU / 4.0` (90 degrees) is looking directly forward.
102 |     /// The camera will smoothly transition from `angle` to `target_angle`.
103 |     /// If you want to customise the angle, set `min_angle` instead.
104 |     /// Defaults to 25 degrees.
105 |     pub target_angle: f32,
106 |     /// The angle of the camera at no zoom (max height). By default, angle increases as you zoom in.
107 |     /// If `dynamic_angle` is disabled, then that does not happen and the camera will stay fixed at
108 |     /// `min_zoom`.
109 |     /// If you want to customise the angle, this is what you want to change.
110 |     /// Defaults to 25 degrees.
111 |     pub min_angle: f32,
112 |     /// Whether the camera should increase its angle the more you zoom in, so you can see
113 |     /// characters up close from a sideways view instead of top down.
114 |     /// If this is
115 |     /// Defaults to `true`.
116 |     pub dynamic_angle: bool,
117 |     /// The amount of smoothing applied to the camera movement. Should be a value between `0.0` and
118 |     /// `1.0`. Set to `0.0` to disable smoothing. `1.0` is infinite smoothing (the camera won't
119 |     /// move).
120 |     /// Defaults to `0.3`.
121 |     pub smoothness: f32,
122 |     /// The current focus of the camera, including the orientation (which way is forward). The
123 |     /// camera's actual transform is calculated based on this transform.
124 |     /// Updated automatically.
125 |     /// Typically you won't need to set this manually, even if you implement your own controls.
126 |     /// Set `target_focus` instead.
127 |     /// Defaults to `Transform::IDENTITY`.
128 |     pub focus: Transform,
129 |     /// The target focus of the camera, including the target orientation (which way is forward).
130 |     /// This is where the camera should move to, and is how smoothing is implemented
131 |     /// Updated automatically when using `RtsCameraControls`, but should be updated manually
132 |     /// if you implement your own controls. You can also change this when adding this component to
133 |     /// set the starting position.
134 |     /// Defaults to `Transform::IDENTITY`.
135 |     pub target_focus: Transform,
136 |     /// The current zoom level, between `0.0` and `1.0`, where 0 is no zoom (`height_max`), and 1 is
137 |     /// max zoom (`height_min`).
138 |     /// Typically you won't need to set this manually, even if you implement your own controls.
139 |     /// Set `target_zoom` instead.
140 |     /// Defaults to `0.0`.
141 |     pub zoom: f32,
142 |     /// The target zoom level. Used to implement zoom smoothing.
143 |     /// Updated automatically when using `RtsCameraControls`, but should be updated manually
144 |     /// if you implement your own controls. You can also change this when adding this component to
145 |     /// set the starting zoom.
146 |     /// Defaults to `0.0`.
147 |     pub target_zoom: f32,
148 |     /// Whether the camera should snap to `target_focus` and `target_zoom`. Will be set to
149 |     /// `false` after one frame. Useful if you want to lock the camera to a specific target (e.g.
150 |     /// to follow a unit), by setting `target_focus` and setting this to `true` on every frame.
151 |     /// Defaults to `false`.
152 |     pub snap: bool,
153 | }
154 | 
155 | impl Default for RtsCamera {
156 |     fn default() -> Self {
157 |         RtsCamera {
158 |             bounds: Aabb2d::new(Vec2::ZERO, Vec2::new(20.0, 20.0)),
159 |             height_min: 2.0,
160 |             height_max: 30.0,
161 |             angle: 20.0f32.to_radians(),
162 |             target_angle: 20.0f32.to_radians(),
163 |             min_angle: 20.0f32.to_radians(),
164 |             dynamic_angle: true,
165 |             smoothness: 0.3,
166 |             focus: Transform::IDENTITY,
167 |             target_focus: Transform::IDENTITY,
168 |             zoom: 0.0,
169 |             target_zoom: 0.0,
170 |             snap: false,
171 |         }
172 |     }
173 | }
174 | 
175 | impl RtsCamera {
176 |     /// Sets the camera's position, angle and focus immediately to their current smoothing destination.
177 |     pub fn reset_smoothing(&mut self) {
178 |         self.focus.translation = self.target_focus.translation;
179 |         self.focus.rotation = self.target_focus.rotation;
180 |         self.zoom = self.target_zoom;
181 |         self.angle = self.target_angle;
182 |     }
183 | }
184 | 
185 | /// Marks an entity that should be treated as 'ground'. The RTS camera will stay a certain distance
186 | /// (based on min/max height and zoom) above any meshes marked with this component (using a ray
187 | /// cast).
188 | /// You'll likely want to mark all terrain entities, but not things like buildings, trees, or units.
189 | #[derive(Component, Copy, Clone, Debug, PartialEq, Reflect)]
190 | #[reflect(Component)]
191 | pub struct Ground;
192 | 
193 | fn initialize(mut cam_q: Query<&mut RtsCamera, Added<RtsCamera>>) {
194 |     for mut cam in cam_q.iter_mut() {
195 |         // Snap to targets when RtsCamera is added. Note that we snap whole transform, not just XZ
196 |         // translation like snap_to system.
197 |         cam.zoom = cam.target_zoom;
198 |         cam.focus = cam.target_focus;
199 |         cam.angle = cam.min_angle;
200 |         cam.target_angle = cam.min_angle;
201 |     }
202 | }
203 | 
204 | fn follow_ground(
205 |     mut cam_q: Query<&mut RtsCamera>,
206 |     ground_q: Query<Entity, With<Ground>>,
207 |     mut ray_cast: MeshRayCast,
208 | ) {
209 |     for mut cam in cam_q.iter_mut() {
210 |         let ray_start = Vec3::new(
211 |             cam.target_focus.translation.x,
212 |             cam.target_focus.translation.y + cam.height_max,
213 |             cam.target_focus.translation.z,
214 |         );
215 |         if let Some(hit1) = cast_ray(ray_start, Dir3::NEG_Y, &mut ray_cast, &|entity| {
216 |             ground_q.get(entity).is_ok()
217 |         }) {
218 |             cam.target_focus.translation.y = hit1.point.y;
219 |         }
220 |     }
221 | }
222 | 
223 | fn snap_to_target(mut cam_q: Query<&mut RtsCamera>) {
224 |     // When snapping in a top down camera, only the XZ should be snapped. The Y coord is controlled
225 |     // by zoom and that should remain smoothed, as should rotation.
226 |     for mut cam in cam_q.iter_mut() {
227 |         if cam.snap {
228 |             cam.focus.translation.x = cam.target_focus.translation.x;
229 |             cam.focus.translation.z = cam.target_focus.translation.z;
230 |             cam.snap = false;
231 |         }
232 |     }
233 | }
234 | 
235 | fn dynamic_angle(mut query: Query<&mut RtsCamera>) {
236 |     for mut cam in query.iter_mut().filter(|cam| cam.dynamic_angle) {
237 |         cam.target_angle = cam
238 |             .min_angle
239 |             .lerp(MAX_ANGLE, ease_in_circular(cam.target_zoom));
240 |     }
241 | }
242 | 
243 | fn move_towards_target(mut cam_q: Query<&mut RtsCamera>, time: Res<Time<Real>>) {
244 |     for mut cam in cam_q.iter_mut() {
245 |         cam.focus.translation = cam.focus.translation.lerp(
246 |             cam.target_focus.translation,
247 |             1.0 - cam.smoothness.powi(7).powf(time.delta_secs()),
248 |         );
249 |         cam.focus.rotation = cam.focus.rotation.lerp(
250 |             cam.target_focus.rotation,
251 |             1.0 - cam.smoothness.powi(7).powf(time.delta_secs()),
252 |         );
253 |         cam.zoom = cam.zoom.lerp(
254 |             cam.target_zoom,
255 |             1.0 - cam.smoothness.powi(7).powf(time.delta_secs()),
256 |         );
257 |         cam.angle = cam.angle.lerp(
258 |             cam.target_angle,
259 |             1.0 - cam.smoothness.powi(7).powf(time.delta_secs()),
260 |         );
261 |     }
262 | }
263 | 
264 | /// Constrains a 3D position to lie within the specified 2D axis-aligned
265 | /// bounding box (AABB).
266 | ///
267 | /// This function ensures that the X and Z coordinates of the given 3D position
268 | /// are clamped to the bounds of the provided [`Aabb2d`]. The Y coordinate
269 | /// remains unchanged, as the bounds only apply to the XZ plane.
270 | #[inline(always)]
271 | fn apply_bounds(bounds: &Aabb2d, position: Vec3) -> Vec3 {
272 |     let closest_point = bounds.closest_point(Vec2::new(position.x, position.z));
273 | 
274 |     Vec3::new(closest_point.x, position.y, closest_point.y)
275 | }
276 | 
277 | fn apply_camera_bounds(mut cam_q: Query<&mut RtsCamera>) {
278 |     for mut cam in cam_q.iter_mut() {
279 |         cam.target_focus.translation = apply_bounds(&cam.bounds, cam.target_focus.translation);
280 |     }
281 | }
282 | 
283 | fn update_camera_transform(mut cam_q: Query<(&mut Transform, &RtsCamera)>) {
284 |     for (mut tfm, cam) in cam_q.iter_mut() {
285 |         let rotation = Quat::from_rotation_x(cam.angle - 90f32.to_radians());
286 |         let camera_height = cam.height_max.lerp(cam.height_min, cam.zoom);
287 |         let camera_offset = camera_height * cam.angle.tan();
288 | 
289 |         tfm.rotation = cam.focus.rotation * rotation;
290 |         tfm.translation =
291 |             cam.focus.translation + (Vec3::Y * camera_height) + (cam.focus.back() * camera_offset);
292 |     }
293 | }
294 | 
295 | fn cast_ray<'a>(
296 |     origin: Vec3,
297 |     dir: Dir3,
298 |     ray_cast: &'a mut MeshRayCast<'_, '_>,
299 |     filter: &'a dyn Fn(Entity) -> bool,
300 | ) -> Option<&'a RayMeshHit> {
301 |     let ray1 = Ray3d::new(origin, dir);
302 |     let hits1 = ray_cast.cast_ray(
303 |         ray1,
304 |         &MeshRayCastSettings {
305 |             filter,
306 |             ..default()
307 |         },
308 |     );
309 |     hits1.first().map(|(_, hit)| hit)
310 | }
311 | 
312 | fn ease_in_circular(x: f32) -> f32 {
313 |     1.0 - (1.0 - x.powi(2)).sqrt()
314 | }
315 | 
316 | #[cfg(test)]
317 | mod tests {
318 |     use bevy::math::bounding::Aabb2d;
319 | 
320 |     use super::*;
321 | 
322 |     #[test]
323 |     fn test_symmetric_bounds() {
324 |         // Default bounds with zero center, i.e., symmetric around origin.
325 |         let bounds = Aabb2d::new(Vec2::ZERO, Vec2::new(20.0, 20.0));
326 | 
327 |         // Position at center should remain unchanged.
328 |         let center_pos = Vec3::new(0.0, 0.0, 0.0);
329 |         assert_eq!(apply_bounds(&bounds, center_pos), center_pos);
330 | 
331 |         // Position at edge should remain unchanged.
332 |         let edge_pos = Vec3::new(20.0, 0.0, 20.0);
333 |         assert_eq!(apply_bounds(&bounds, edge_pos), edge_pos);
334 | 
335 |         // Position inside bounds should remain unchanged.
336 |         let in_bounds_pos = Vec3::new(15.0, 0.0, 15.0);
337 |         assert_eq!(apply_bounds(&bounds, in_bounds_pos), in_bounds_pos);
338 | 
339 |         // Position outside bounds should be clamped.
340 |         let out_of_bounds_pos = Vec3::new(25.0, 0.0, 25.0);
341 |         assert_eq!(
342 |             apply_bounds(&bounds, out_of_bounds_pos),
343 |             Vec3::new(20.0, 0.0, 20.0)
344 |         );
345 |     }
346 | 
347 |     #[test]
348 |     fn test_asymmetric_bounds() {
349 |         // Bounds with non-zero center, i.e., asymmetric relative to origin.
350 |         //
351 |         // Effective bounds: x: [10, 190], z: [-10, 190].
352 |         let bounds = Aabb2d::new(Vec2::new(100.0, 90.0), Vec2::new(90.0, 100.0));
353 | 
354 |         // Position at center should remain unchanged.
355 |         let center_pos = Vec3::new(100.0, 0.0, 90.0);
356 |         assert_eq!(apply_bounds(&bounds, center_pos), center_pos);
357 | 
358 |         // Position at edge should remain unchanged.
359 |         let edge_pos = Vec3::new(190.0, 0.0, 190.0);
360 |         assert_eq!(apply_bounds(&bounds, edge_pos), edge_pos);
361 | 
362 |         // Position inside bounds should remain unchanged.
363 |         let in_bounds_pos = Vec3::new(150.0, 0.0, 100.0);
364 |         assert_eq!(apply_bounds(&bounds, in_bounds_pos), in_bounds_pos);
365 | 
366 |         // Position outside bounds should be clamped
367 |         let out_of_bounds_pos = Vec3::new(200.0, 0.0, 200.0); // beyond edge
368 |         assert_eq!(
369 |             apply_bounds(&bounds, out_of_bounds_pos),
370 |             Vec3::new(190.0, 0.0, 190.0)
371 |         );
372 |     }
373 | }
374 | 


--------------------------------------------------------------------------------