Migrate UI bundles to required components

crates/bevy_ui/src/lib.rs

@@ -59,7 +59,7 @@ pub mod prelude {
             ui_material::*,
             ui_node::*,
             widget::{Button, Label},
-            Interaction, UiMaterialHandle, UiMaterialPlugin, UiScale,
+            Interaction, MaterialNode, UiMaterialPlugin, UiScale,
         },
         // `bevy_sprite` re-exports for texture slicing
         bevy_sprite::{BorderRect, ImageScaleMode, SliceScaleMode, TextureSlicer},

crates/bevy_ui/src/node_bundles.rs

@@ -3,8 +3,8 @@
 
 use crate::{
     widget::{Button, UiImageSize},
-    BackgroundColor, BorderColor, BorderRadius, ContentSize, FocusPolicy, Interaction, Node,
-    ScrollPosition, Style, UiImage, UiMaterial, UiMaterialHandle, ZIndex,
+    BackgroundColor, BorderColor, BorderRadius, ContentSize, FocusPolicy, Interaction,
+    MaterialNode, Node, ScrollPosition, Style, UiImage, UiMaterial, ZIndex,
 };
 use bevy_ecs::bundle::Bundle;
 use bevy_render::view::{InheritedVisibility, ViewVisibility, Visibility};
@@ -187,14 +187,18 @@ impl Default for ButtonBundle {
 /// Adding a `BackgroundColor` component to an entity with this bundle will ignore the custom
 /// material and use the background color instead.
 #[derive(Bundle, Clone, Debug)]
+#[deprecated(
+    since = "0.15.0",
+    note = "Use the `MaterialNode` component instead. Inserting `MaterialNode` will also insert the other components required automatically."
+)]
 pub struct MaterialNodeBundle<M: UiMaterial> {
     /// Describes the logical size of the node
     pub node: Node,
     /// Styles which control the layout (size and position) of the node and its children
     /// In some cases these styles also affect how the node drawn/painted.
     pub style: Style,
     /// The [`UiMaterial`] used to render the node.
-    pub material: UiMaterialHandle<M>,
+    pub material: MaterialNode<M>,
     /// Whether this node should block interaction with lower nodes
     pub focus_policy: FocusPolicy,
     /// The transform of the node

crates/bevy_ui/src/render/mod.rs

@@ -65,6 +65,25 @@ pub mod graph {
     }
 }
 
+/// Z offsets of "extracted nodes" for a given entity. These exist to allow rendering multiple "extracted nodes"
+/// for a given source entity (ex: render both a background color _and_ a custom material for a given node).
+///
+/// When possible these offsets should be defined in _this_ module to ensure z-index coordination across contexts.
+/// When this is _not_ possible, pick a suitably unique index unlikely to clash with other things (ex: `0.1826823` not `0.1`).
+///
+/// Offsets should be unique for a given node entity to avoid z fighting.
+/// These should pretty much _always_ be larger than -1.0 and smaller than 1.0 to avoid clipping into nodes
+/// above / below the current node in the stack.
+///
+/// A z-index of 0.0 is the baseline, which is used as the primary "background color" of the node.
+///
+/// Note that nodes "stack" on each other, so a negative offset on the node above could clip _into_
+/// a positive offset on a node below.
+pub mod stack_z_offsets {
+    pub const BACKGROUND_COLOR: f32 = 0.0;
+    pub const MATERIAL: f32 = 0.18267;
+}
+
 pub const UI_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(13012847047162779583);
 
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
@@ -823,7 +842,7 @@ pub fn queue_uinodes(
             pipeline,
             entity: (*entity, extracted_uinode.main_entity),
             sort_key: (
-                FloatOrd(extracted_uinode.stack_index as f32),
+                FloatOrd(extracted_uinode.stack_index as f32 + stack_z_offsets::BACKGROUND_COLOR),
                 entity.index(),
             ),
             // batch_range will be calculated in prepare_uinodes

crates/bevy_ui/src/render/ui_material_pipeline.rs

@@ -60,9 +60,9 @@ where
             Shader::from_wgsl
         );
         app.init_asset::<M>()
-            .register_type::<UiMaterialHandle<M>>()
+            .register_type::<MaterialNode<M>>()
             .add_plugins((
-                ExtractComponentPlugin::<UiMaterialHandle<M>>::extract_visible(),
+                ExtractComponentPlugin::<MaterialNode<M>>::extract_visible(),
                 RenderAssetPlugin::<PreparedUiMaterial<M>>::default(),
             ));
 
@@ -363,18 +363,15 @@ pub fn extract_ui_material_nodes<M: UiMaterial>(
     materials: Extract<Res<Assets<M>>>,
     default_ui_camera: Extract<DefaultUiCamera>,
     uinode_query: Extract<
-        Query<
-            (
-                Entity,
-                &Node,
-                &GlobalTransform,
-                &UiMaterialHandle<M>,
-                &ViewVisibility,
-                Option<&CalculatedClip>,
-                Option<&TargetCamera>,
-            ),
-            Without<BackgroundColor>,
-        >,
+        Query<(
+            Entity,
+            &Node,
+            &GlobalTransform,
+            &MaterialNode<M>,
+            &ViewVisibility,
+            Option<&CalculatedClip>,
+            Option<&TargetCamera>,
+        )>,
     >,
     render_entity_lookup: Extract<Query<RenderEntity>>,
 ) {
@@ -652,7 +649,7 @@ pub fn queue_ui_material_nodes<M: UiMaterial>(
             pipeline,
             entity: (*entity, extracted_uinode.main_entity),
             sort_key: (
-                FloatOrd(extracted_uinode.stack_index as f32),
+                FloatOrd(extracted_uinode.stack_index as f32 + stack_z_offsets::MATERIAL),
                 entity.index(),
             ),
             batch_range: 0..0,

crates/bevy_ui/src/ui_material.rs

@@ -1,5 +1,6 @@
 use core::hash::Hash;
 
+use crate::Node;
 use bevy_asset::{Asset, AssetId, Handle};
 use bevy_derive::{Deref, DerefMut};
 use bevy_ecs::{component::Component, reflect::ReflectComponent};
@@ -10,7 +11,7 @@ use bevy_render::{
 };
 use derive_more::derive::From;
 
-/// Materials are used alongside [`UiMaterialPlugin`](crate::UiMaterialPlugin) and [`MaterialNodeBundle`](crate::prelude::MaterialNodeBundle)
+/// Materials are used alongside [`UiMaterialPlugin`](crate::UiMaterialPlugin) and [`MaterialNode`](crate::prelude::MaterialNode)
 /// to spawn entities that are rendered with a specific [`UiMaterial`] type. They serve as an easy to use high level
 /// way to render `Node` entities with custom shader logic.
 ///
@@ -58,17 +59,16 @@ use derive_more::derive::From;
 ///
 /// // Spawn an entity using `CustomMaterial`.
 /// fn setup(mut commands: Commands, mut materials: ResMut<Assets<CustomMaterial>>, asset_server: Res<AssetServer>) {
-///     commands.spawn(MaterialNodeBundle {
-///         style: Style {
-///             width: Val::Percent(100.0),
-///             ..Default::default()
-///         },
-///         material: UiMaterialHandle(materials.add(CustomMaterial {
+///     commands.spawn((
+///         MaterialNode(materials.add(CustomMaterial {
 ///             color: LinearRgba::RED,
 ///             color_texture: asset_server.load("some_image.png"),
 ///         })),
-///         ..Default::default()
-///     });
+///         Style {
+///             width: Val::Percent(100.0),
+///             ..Default::default()
+///         },
+///     ));
 /// }
 /// ```
 /// In WGSL shaders, the material's binding would look like this:
@@ -157,22 +157,23 @@ where
     Component, Clone, Debug, Deref, DerefMut, Reflect, PartialEq, Eq, ExtractComponent, From,
 )]
 #[reflect(Component, Default)]
-pub struct UiMaterialHandle<M: UiMaterial>(pub Handle<M>);
+#[require(Node)]
+pub struct MaterialNode<M: UiMaterial>(pub Handle<M>);
 
-impl<M: UiMaterial> Default for UiMaterialHandle<M> {
+impl<M: UiMaterial> Default for MaterialNode<M> {
     fn default() -> Self {
         Self(Handle::default())
     }
 }
 
-impl<M: UiMaterial> From<UiMaterialHandle<M>> for AssetId<M> {
-    fn from(material: UiMaterialHandle<M>) -> Self {
+impl<M: UiMaterial> From<MaterialNode<M>> for AssetId<M> {
+    fn from(material: MaterialNode<M>) -> Self {
         material.id()
     }
 }
 
-impl<M: UiMaterial> From<&UiMaterialHandle<M>> for AssetId<M> {
-    fn from(material: &UiMaterialHandle<M>) -> Self {
+impl<M: UiMaterial> From<&MaterialNode<M>> for AssetId<M> {
+    fn from(material: &MaterialNode<M>) -> Self {
         material.id()
     }
 }

examples/ui/ui_material.rs

@@ -1,6 +1,6 @@
 //! Demonstrates the use of [`UiMaterials`](UiMaterial) and how to change material values
 
-use bevy::{prelude::*, reflect::TypePath, render::render_resource::*};
+use bevy::{color::palettes::css::RED, prelude::*, reflect::TypePath, render::render_resource::*};
 
 /// This example uses a shader source file from the assets subdirectory
 const SHADER_ASSET_PATH: &str = "shaders/custom_ui_material.wgsl";
@@ -35,22 +35,22 @@ fn setup(
         ))
         .with_children(|parent| {
             let banner_scale_factor = 0.5;
-            parent.spawn(MaterialNodeBundle {
-                style: Style {
+            parent.spawn((
+                MaterialNode(ui_materials.add(CustomUiMaterial {
+                    color: LinearRgba::WHITE.to_f32_array().into(),
+                    slider: 0.5,
+                    color_texture: asset_server.load("branding/banner.png"),
+                    border_color: LinearRgba::WHITE.to_f32_array().into(),
+                })),
+                Style {
                     position_type: PositionType::Absolute,
                     width: Val::Px(905.0 * banner_scale_factor),
                     height: Val::Px(363.0 * banner_scale_factor),
                     border: UiRect::all(Val::Px(10.)),
                     ..default()
                 },
-                material: UiMaterialHandle(ui_materials.add(CustomUiMaterial {
-                    color: LinearRgba::WHITE.to_f32_array().into(),
-                    slider: 0.5,
-                    color_texture: asset_server.load("branding/banner.png"),
-                    border_color: LinearRgba::WHITE.to_f32_array().into(),
-                })),
-                ..default()
-            });
+                BackgroundColor(RED.into()),
+            ));
         });
 }
 
@@ -82,7 +82,7 @@ impl UiMaterial for CustomUiMaterial {
 // Also updates the color of the image to a rainbow color
 fn animate(
     mut materials: ResMut<Assets<CustomUiMaterial>>,
-    q: Query<&UiMaterialHandle<CustomUiMaterial>>,
+    q: Query<&MaterialNode<CustomUiMaterial>>,
     time: Res<Time>,
 ) {
     let duration = 2.0;