Merge branch 'main' into feat/extend-settings-group

Author: mpowell90

_release-content/migration-guides/input_focus_setting_getting.md

@@ -0,0 +1,27 @@
+---
+title: "`InputFocus` fields are no longer public"
+pull_requests: [23723]
+---
+
+The `.0` field on `InputFocus` is no longer public.
+Use the getter and setters methods instead.
+
+Before:
+
+```rust
+let focused_entity = input_focus.0;
+input_focus.0 = Some(entity);
+input_focus.0 = None;
+```
+
+After:
+
+```rust
+let focused_entity = input_focus.get();
+input_focus.set(entity);
+input_focus.clear();
+```
+
+Additionally, the core setup of `InputFocus` and related resources now occurs in `InputFocusPlugin`,
+rather than `InputDispatchPlugin`.
+This is part of `DefaultPlugins`, so most users will not need to make any changes.

_release-content/migration-guides/skybox_image.md

@@ -0,0 +1,42 @@
+---
+title: "`Skybox` `image` is now optional"
+pull_requests: [23691]
+---
+
+The `image` field of the `Skybox` component now has the type `Option<Handle<Image>>` instead of `Handle<Image>`.
+A `Skybox` component without an image will not draw anything, just like it was not present.
+
+If you were creating a skybox with an image, wrap the image handle in `Some`:
+
+```rust
+// 0.18
+Skybox {
+    image: my_skybox,
+    brightness: 1000.0,
+    ..default()
+}
+
+// 0.19
+Skybox {
+    image: Some(my_skybox),
+    brightness: 1000.0,
+    ..default()
+}
+```
+
+If you were previously creating a `Skybox` component with a placeholder image to be changed later, you can now remove the placeholder:
+
+```rust
+// 0.18
+Skybox {
+    image: cubemap_image_that_will_not_actually_be_seen,
+    brightness: 1000.0,
+    ..default()
+}
+
+// 0.19
+Skybox {
+    brightness: 1000.0,
+    ..default()
+}
+```

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);
+    }
+}

crates/bevy_core_pipeline/src/skybox/mod.rs

@@ -227,17 +227,18 @@ fn prepare_skybox_bind_groups(
     views: Query<(Entity, &Skybox, &DynamicUniformIndex<SkyboxUniforms>)>,
 ) {
     for (entity, skybox, skybox_uniform_index) in &views {
-        if let (Some(skybox), Some(view_uniforms), Some(skybox_uniforms)) = (
-            images.get(&skybox.image),
+        if let (Some(image_handle), Some(view_uniforms), Some(skybox_uniforms)) = (
+            &skybox.image,
             view_uniforms.uniforms.binding(),
             skybox_uniforms.binding(),
-        ) {
+        ) && let Some(image) = images.get(image_handle)
+        {
             let bind_group = render_device.create_bind_group(
                 "skybox_bind_group",
                 &pipeline_cache.get_bind_group_layout(&pipeline.bind_group_layout),
                 &BindGroupEntries::sequential((
-                    &skybox.texture_view,
-                    &skybox.sampler,
+                    &image.texture_view,
+                    &image.sampler,
                     view_uniforms,
                     skybox_uniforms,
                 )),
@@ -246,6 +247,8 @@ fn prepare_skybox_bind_groups(
             commands
                 .entity(entity)
                 .insert(SkyboxBindGroup((bind_group, skybox_uniform_index.index())));
+        } else {
+            commands.entity(entity).remove::<SkyboxBindGroup>();
         }
     }
 }

crates/bevy_ecs/src/event/mod.rs

@@ -272,6 +272,22 @@ pub trait Event: Send + Sync + Sized + 'static {
 /// });
 /// ```
 ///
+/// ## Best practices for event propagation
+///
+/// Propagation is useful for events that should be handled by multiple entities in a hierarchy, such as UI events.
+/// In these cases, it is common for the event to be triggered on a "leaf" entity, and then propagate up to "root" entities.
+/// In this pattern, it is generally recommended to trigger the event on the most specific entity possible (the leaf), and then use propagation to have it handled by more general entities (the roots).
+///
+/// Once an event is handled by a given entity, you should stop propagation.
+/// This ensures that only a single "behavior" resolves per event sent,
+/// avoiding unexpected behavior from entities higher up the hierarchy.
+///
+/// This advice has one notable wrinkle:
+/// if an entity is "disabled" (e.g. if a UI node is grayed out),
+/// the event should still be considered "handled" by that entity,
+/// even though the observer logic should not be run.
+/// This ensures consistent behavior regardless of the enabled/disabled state of entities.
+///
 /// ## Naming and Usage Conventions
 ///
 /// In most cases, it is recommended to use a named struct field for the "event target" entity, and to use