Pan camera mouse pan (#22859)

# Objective

The current PanCamera only supports keyboard panning, when a common use
case is mouse panning.

## Solution

Add optional mouse panning with some settings

## Testing

I ran the Pan Camera example with the new settings

## Additional notes

I added settings for setting the exact mouse button that triggers the
panning, and whether or not to grab the cursor when panning.

I am unsure about the cursor grab part of this design as it may mess
with the app's existing cursor options and the window part may not work
for some setups.

It may be wiser to just omit grabbing for now, or maybe keep grabbing
but don't change visibility idk



As always I am open to any and all feedback.

---------

Co-authored-by: Kevin Chen <chen.kevin.f@gmail.com>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Author: 3 people

crates/bevy_camera_controller/Cargo.toml

@@ -22,6 +22,7 @@ bevy_reflect = { path = "../bevy_reflect", version = "0.19.0-dev", default-featu
 bevy_time = { path = "../bevy_time", version = "0.19.0-dev", default-features = false }
 bevy_transform = { path = "../bevy_transform", version = "0.19.0-dev", default-features = false }
 bevy_window = { path = "../bevy_window", version = "0.19.0-dev", default-features = false }
+bevy_picking = { path = "../bevy_picking", version = "0.19.0-dev", default-features = false }
 
 [features]
 default = ["bevy_reflect"]

crates/bevy_camera_controller/src/pan_camera.rs

@@ -6,15 +6,17 @@
 //! To configure the settings of this controller, modify the fields of the [`PanCamera`] component.
 
 use bevy_app::{App, Plugin, RunFixedMainLoop, RunFixedMainLoopSystems};
-use bevy_camera::Camera;
+use bevy_camera::{Camera, RenderTarget};
 use bevy_ecs::prelude::*;
 use bevy_input::keyboard::KeyCode;
-use bevy_input::mouse::{AccumulatedMouseScroll, MouseScrollUnit};
+use bevy_input::mouse::{AccumulatedMouseScroll, MouseButton, MouseScrollUnit};
 use bevy_input::ButtonInput;
 use bevy_math::{Vec2, Vec3};
+use bevy_picking::events::{Drag, DragEnd, DragStart, Pointer};
 use bevy_time::{Real, Time};
+use bevy_transform::components::GlobalTransform;
 use bevy_transform::prelude::Transform;
-
+use bevy_window::{PrimaryWindow, WindowRef};
 use core::{f32::consts::*, fmt};
 
 /// A plugin that enables 2D camera panning and zooming controls.
@@ -28,7 +30,9 @@ impl Plugin for PanCameraPlugin {
         app.add_systems(
             RunFixedMainLoop,
             run_pancamera_controller.in_set(RunFixedMainLoopSystems::BeforeFixedMainLoop),
-        );
+        )
+        .add_observer(add_window_observer)
+        .add_observer(remove_window_observer);
     }
 }
 
@@ -68,6 +72,16 @@ pub struct PanCamera {
     pub key_rotate_ccw: Option<KeyCode>,
     /// [`KeyCode`] for clockwise rotation.
     pub key_rotate_cw: Option<KeyCode>,
+    /// Mouse pan settings.
+    pub mouse_pan_settings: MousePanSettings,
+}
+
+/// Settings for mouse panning for the [`PanCamera`] controller.
+pub struct MousePanSettings {
+    /// Whether the mouse panning is enabled.
+    pub enabled: bool,
+    /// The mouse button to use for panning.
+    pub button: MouseButton,
 }
 
 /// Provides the default values for the `PanCamera` controller.
@@ -105,6 +119,10 @@ impl Default for PanCamera {
             rotation_speed: PI,
             key_rotate_ccw: Some(KeyCode::KeyQ),
             key_rotate_cw: Some(KeyCode::KeyE),
+            mouse_pan_settings: MousePanSettings {
+                enabled: true,
+                button: MouseButton::Left,
+            },
         }
     }
 }
@@ -235,3 +253,83 @@ fn run_pancamera_controller(
 
     transform.scale = Vec3::splat(controller.zoom_factor);
 }
+
+/// A component attached to window entities that holds the id of an
+/// active `handle_mouse_pan` observer. It is None if there is no
+/// such observer.
+#[derive(Component)]
+struct HandleMousePanObserver(Option<Entity>);
+
+fn add_window_observer(
+    drag_start: On<Pointer<DragStart>>,
+    mut commands: Commands,
+    render_targets: Query<&RenderTarget, With<PanCamera>>,
+    primary_window: Single<Entity, With<PrimaryWindow>>,
+) {
+    for render_target in render_targets.iter() {
+        if let RenderTarget::Window(window) = render_target {
+            let entity = match window {
+                WindowRef::Primary => primary_window.entity(),
+                WindowRef::Entity(entity) => *entity,
+            };
+            if entity == drag_start.entity {
+                let observer_id = commands
+                    .spawn(Observer::new(handle_mouse_pan).with_entity(entity))
+                    .id();
+                commands
+                    .entity(entity)
+                    .insert(HandleMousePanObserver(Some(observer_id)));
+            }
+        }
+    }
+}
+
+fn remove_window_observer(
+    drag_end: On<Pointer<DragEnd>>,
+    mut commands: Commands,
+    render_targets: Query<&RenderTarget, With<PanCamera>>,
+    mut handle_mouse_pan_observer: Query<&mut HandleMousePanObserver>,
+    primary_window: Single<Entity, With<PrimaryWindow>>,
+) {
+    for render_target in render_targets.iter() {
+        if let RenderTarget::Window(window) = render_target {
+            let entity = match window {
+                WindowRef::Primary => primary_window.entity(),
+                WindowRef::Entity(entity) => *entity,
+            };
+            if entity == drag_end.entity
+                && let Ok(mut observer) = handle_mouse_pan_observer.get_mut(entity)
+                && let Some(observer_entity) = observer.0.take()
+            {
+                commands.entity(observer_entity).despawn();
+            }
+        }
+    }
+}
+
+fn handle_mouse_pan(
+    drag: On<Pointer<Drag>>,
+    mut pan_cameras: Query<(&Camera, &GlobalTransform, &mut Transform, &PanCamera)>,
+) {
+    for (camera, global_transform, mut transform, pan_camera_controller) in pan_cameras.iter_mut() {
+        if !pan_camera_controller.enabled || !pan_camera_controller.mouse_pan_settings.enabled {
+            return;
+        }
+
+        let Ok(camera_screen_position) =
+            camera.world_to_viewport(global_transform, transform.translation)
+        else {
+            continue;
+        };
+
+        let offset_camera_screen_position = camera_screen_position + drag.delta * -1.; // inverted feels more natural
+
+        let Ok(new_camera_position) =
+            camera.viewport_to_world_2d(global_transform, offset_camera_screen_position)
+        else {
+            continue;
+        };
+
+        transform.translation = new_camera_position.extend(transform.translation.z);
+    }
+}

release-content/migration-guides/pan_camera_mouse_panning.md

@@ -0,0 +1,8 @@
+---
+title: "Added mouse panning to `PanCamera` component"
+pull_requests: [22859]
+---
+
+By default `PanCamera` now includes mouse panning.
+
+To go back to the keyboard only panning, you need to set the `enabled` field of the `PanCamera`'s mouse_pan_settings field to false.