[Merged by Bors] - Add z-index support with a predictable UI stack

Cargo.toml

@@ -1442,6 +1442,16 @@ description = "Demonstrates transparency for UI"
 category = "UI (User Interface)"
 wasm = true
 
+[[example]]
+name = "z_index"
+path = "examples/ui/z_index.rs"
+
+[package.metadata.example.z_index]
+name = "UI Z-Index"
+description = "Demonstrates how to control the relative depth (z-position) of UI elements"
+category = "UI (User Interface)"
+wasm = true
+
 [[example]]
 name = "ui"
 path = "examples/ui/ui.rs"

crates/bevy_ui/src/entity.rs

@@ -2,7 +2,7 @@
 
 use crate::{
     widget::{Button, ImageMode},
-    CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage,
+    CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage, ZIndex,
 };
 use bevy_ecs::{
     bundle::Bundle,
@@ -37,6 +37,8 @@ pub struct NodeBundle {
     pub visibility: Visibility,
     /// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
     pub computed_visibility: ComputedVisibility,
+    /// Indicates the depth at which the node should appear in the UI
+    pub z_index: ZIndex,
 }
 
 /// A UI node that is an image
@@ -64,6 +66,8 @@ pub struct ImageBundle {
     pub visibility: Visibility,
     /// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
     pub computed_visibility: ComputedVisibility,
+    /// Indicates the depth at which the node should appear in the UI
+    pub z_index: ZIndex,
 }
 
 /// A UI node that is text
@@ -87,6 +91,8 @@ pub struct TextBundle {
     pub visibility: Visibility,
     /// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
     pub computed_visibility: ComputedVisibility,
+    /// Indicates the depth at which the node should appear in the UI
+    pub z_index: ZIndex,
 }
 
 impl TextBundle {
@@ -135,6 +141,7 @@ impl Default for TextBundle {
             global_transform: Default::default(),
             visibility: Default::default(),
             computed_visibility: Default::default(),
+            z_index: Default::default(),
         }
     }
 }
@@ -164,6 +171,8 @@ pub struct ButtonBundle {
     pub visibility: Visibility,
     /// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
     pub computed_visibility: ComputedVisibility,
+    /// Indicates the depth at which the node should appear in the UI
+    pub z_index: ZIndex,
 }
 
 impl Default for ButtonBundle {
@@ -180,6 +189,7 @@ impl Default for ButtonBundle {
             global_transform: Default::default(),
             visibility: Default::default(),
             computed_visibility: Default::default(),
+            z_index: Default::default(),
         }
     }
 }

crates/bevy_ui/src/focus.rs

@@ -1,7 +1,8 @@
-use crate::{entity::UiCameraConfig, CalculatedClip, Node};
+use crate::{entity::UiCameraConfig, CalculatedClip, Node, UiStack};
 use bevy_ecs::{
     entity::Entity,
     prelude::Component,
+    query::WorldQuery,
     reflect::ReflectComponent,
     system::{Local, Query, Res},
 };
@@ -11,7 +12,6 @@ use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize};
 use bevy_render::camera::{Camera, RenderTarget};
 use bevy_render::view::ComputedVisibility;
 use bevy_transform::components::GlobalTransform;
-use bevy_utils::FloatOrd;
 use bevy_window::Windows;
 use serde::{Deserialize, Serialize};
 use smallvec::SmallVec;
@@ -62,6 +62,19 @@ pub struct State {
     entities_to_reset: SmallVec<[Entity; 1]>,
 }
 
+/// Main query for [`ui_focus_system`]
+#[derive(WorldQuery)]
+#[world_query(mutable)]
+pub struct NodeQuery {
+    entity: Entity,
+    node: &'static Node,
+    global_transform: &'static GlobalTransform,
+    interaction: Option<&'static mut Interaction>,
+    focus_policy: Option<&'static FocusPolicy>,
+    calculated_clip: Option<&'static CalculatedClip>,
+    computed_visibility: Option<&'static ComputedVisibility>,
+}
+
 /// The system that sets Interaction for all UI elements based on the mouse cursor activity
 ///
 /// Entities with a hidden [`ComputedVisibility`] are always treated as released.
@@ -71,15 +84,8 @@ pub fn ui_focus_system(
     windows: Res<Windows>,
     mouse_button_input: Res<Input<MouseButton>>,
     touches_input: Res<Touches>,
-    mut node_query: Query<(
-        Entity,
-        &Node,
-        &GlobalTransform,
-        Option<&mut Interaction>,
-        Option<&FocusPolicy>,
-        Option<&CalculatedClip>,
-        Option<&ComputedVisibility>,
-    )>,
+    ui_stack: Res<UiStack>,
+    mut node_query: Query<NodeQuery>,
 ) {
     // reset entities that were both clicked and released in the last frame
     for entity in state.entities_to_reset.drain(..) {
@@ -91,10 +97,8 @@ pub fn ui_focus_system(
     let mouse_released =
         mouse_button_input.just_released(MouseButton::Left) || touches_input.any_just_released();
     if mouse_released {
-        for (_entity, _node, _global_transform, interaction, _focus_policy, _clip, _visibility) in
-            node_query.iter_mut()
-        {
-            if let Some(mut interaction) = interaction {
+        for node in node_query.iter_mut() {
+            if let Some(mut interaction) = node.interaction {
                 if *interaction == Interaction::Clicked {
                     *interaction = Interaction::None;
                 }
@@ -123,15 +127,21 @@ pub fn ui_focus_system(
         .find_map(|window| window.cursor_position())
         .or_else(|| touches_input.first_pressed_position());
 
-    let mut moused_over_z_sorted_nodes = node_query
-        .iter_mut()
-        .filter_map(
-            |(entity, node, global_transform, interaction, focus_policy, clip, visibility)| {
+    // prepare an iterator that contains all the nodes that have the cursor in their rect,
+    // from the top node to the bottom one. this will also reset the interaction to `None`
+    // for all nodes encountered that are no longer hovered.
+    let mut moused_over_nodes = ui_stack
+        .uinodes
+        .iter()
+        // reverse the iterator to traverse the tree from closest nodes to furthest
+        .rev()
+        .filter_map(|entity| {
+            if let Ok(node) = node_query.get_mut(*entity) {
                 // Nodes that are not rendered should not be interactable
-                if let Some(computed_visibility) = visibility {
+                if let Some(computed_visibility) = node.computed_visibility {
                     if !computed_visibility.is_visible() {
                         // Reset their interaction to None to avoid strange stuck state
-                        if let Some(mut interaction) = interaction {
+                        if let Some(mut interaction) = node.interaction {
                             // We cannot simply set the interaction to None, as that will trigger change detection repeatedly
                             if *interaction != Interaction::None {
                                 *interaction = Interaction::None;
@@ -142,12 +152,12 @@ pub fn ui_focus_system(
                     }
                 }
 
-                let position = global_transform.translation();
+                let position = node.global_transform.translation();
                 let ui_position = position.truncate();
-                let extents = node.size / 2.0;
+                let extents = node.node.size / 2.0;
                 let mut min = ui_position - extents;
                 let mut max = ui_position + extents;
-                if let Some(clip) = clip {
+                if let Some(clip) = node.calculated_clip {
                     min = Vec2::max(min, clip.clip.min);
                     max = Vec2::min(max, clip.clip.max);
                 }
@@ -161,9 +171,9 @@ pub fn ui_focus_system(
                 };
 
                 if contains_cursor {
-                    Some((entity, focus_policy, interaction, FloatOrd(position.z)))
+                    Some(*entity)
                 } else {
-                    if let Some(mut interaction) = interaction {
+                    if let Some(mut interaction) = node.interaction {
                         if *interaction == Interaction::Hovered
                             || (cursor_position.is_none() && *interaction != Interaction::None)
                         {
@@ -172,41 +182,45 @@ pub fn ui_focus_system(
                     }
                     None
                 }
-            },
-        )
-        .collect::<Vec<_>>();
-
-    moused_over_z_sorted_nodes.sort_by_key(|(_, _, _, z)| -*z);
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<Entity>>()
+        .into_iter();
 
-    let mut moused_over_z_sorted_nodes = moused_over_z_sorted_nodes.into_iter();
-    // set Clicked or Hovered on top nodes
-    for (entity, focus_policy, interaction, _) in moused_over_z_sorted_nodes.by_ref() {
-        if let Some(mut interaction) = interaction {
+    // set Clicked or Hovered on top nodes. as soon as a node with a `Block` focus policy is detected,
+    // the iteration will stop on it because it "captures" the interaction.
+    let mut iter = node_query.iter_many_mut(moused_over_nodes.by_ref());
+    while let Some(node) = iter.fetch_next() {
+        if let Some(mut interaction) = node.interaction {
             if mouse_clicked {
                 // only consider nodes with Interaction "clickable"
                 if *interaction != Interaction::Clicked {
                     *interaction = Interaction::Clicked;
                     // if the mouse was simultaneously released, reset this Interaction in the next
                     // frame
                     if mouse_released {
-                        state.entities_to_reset.push(entity);
+                        state.entities_to_reset.push(node.entity);
                     }
                 }
             } else if *interaction == Interaction::None {
                 *interaction = Interaction::Hovered;
             }
         }
 
-        match focus_policy.cloned().unwrap_or(FocusPolicy::Block) {
+        match node.focus_policy.unwrap_or(&FocusPolicy::Block) {
             FocusPolicy::Block => {
                 break;
             }
             FocusPolicy::Pass => { /* allow the next node to be hovered/clicked */ }
         }
     }
-    // reset lower nodes to None
-    for (_entity, _focus_policy, interaction, _) in moused_over_z_sorted_nodes {
-        if let Some(mut interaction) = interaction {
+    // reset `Interaction` for the remaining lower nodes to `None`. those are the nodes that remain in
+    // `moused_over_nodes` after the previous loop is exited.
+    let mut iter = node_query.iter_many_mut(moused_over_nodes);
+    while let Some(node) = iter.fetch_next() {
+        if let Some(mut interaction) = node.interaction {
             // don't reset clicked nodes because they're handled separately
             if *interaction != Interaction::Clicked && *interaction != Interaction::None {
                 *interaction = Interaction::None;

crates/bevy_ui/src/lib.rs

@@ -6,6 +6,7 @@ mod flex;
 mod focus;
 mod geometry;
 mod render;
+mod stack;
 mod ui_node;
 
 pub mod entity;
@@ -33,7 +34,9 @@ use bevy_ecs::{
 use bevy_input::InputSystem;
 use bevy_transform::TransformSystem;
 use bevy_window::ModifiesWindows;
-use update::{ui_z_system, update_clipping_system};
+use stack::ui_stack_system;
+pub use stack::UiStack;
+use update::update_clipping_system;
 
 use crate::prelude::UiCameraConfig;
 
@@ -48,6 +51,8 @@ pub enum UiSystem {
     Flex,
     /// After this label, input interactions with UI entities have been updated for this frame
     Focus,
+    /// After this label, the [`UiStack`] resource has been updated
+    Stack,
 }
 
 /// The current scale of the UI.
@@ -71,6 +76,7 @@ impl Plugin for UiPlugin {
         app.add_plugin(ExtractComponentPlugin::<UiCameraConfig>::default())
             .init_resource::<FlexSurface>()
             .init_resource::<UiScale>()
+            .init_resource::<UiStack>()
             .register_type::<AlignContent>()
             .register_type::<AlignItems>()
             .register_type::<AlignSelf>()
@@ -119,9 +125,7 @@ impl Plugin for UiPlugin {
             )
             .add_system_to_stage(
                 CoreStage::PostUpdate,
-                ui_z_system
-                    .after(UiSystem::Flex)
-                    .before(TransformSystem::TransformPropagate),
+                ui_stack_system.label(UiSystem::Stack),
             )
             .add_system_to_stage(
                 CoreStage::PostUpdate,