Deprecate SpriteSheetBundle and AtlasImageBundle (#12218)

# Objective

After the `TextureAtlas` changes that landed in 0.13,
`SpriteSheetBundle` is equivalent to `TextureAtlas` + `SpriteBundle` and
`AtlasImageBundle` is equivalent to `TextureAtlas` + `ImageBundle`. As
such, the atlas bundles aren't particularly useful / necessary additions
to the API anymore.

In addition, atlas bundles are inconsistent with `ImageScaleMode` (also
introduced in 0.13) which doesn't have its own version of each image
bundle.

## Solution

Deprecate `SpriteSheetBundle` and `AtlasImageBundle` in favor of
including `TextureAtlas` as a separate component alongside
`SpriteBundle` and `ImageBundle`, respectively.

---

## Changelog

- Deprecated `SpriteSheetBundle` and `AtlasImageBundle`.

## Migration Guide

- `SpriteSheetBundle` has been deprecated. Use `TextureAtlas` alongside
a `SpriteBundle` instead.
- `AtlasImageBundle` has been deprecated. Use `TextureAtlas` alongside
an `ImageBundle` instead.

crates/bevy_sprite/src/bundle.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use crate::{Sprite, TextureAtlas};
 use bevy_asset::Handle;
 use bevy_ecs::bundle::Bundle;
@@ -11,9 +13,11 @@ use bevy_transform::components::{GlobalTransform, Transform};
 ///
 /// # Extra behaviours
 ///
-/// You may add the following components to enable additional behaviours
+/// You may add the following components to enable additional behaviours:
 /// - [`ImageScaleMode`](crate::ImageScaleMode) to enable either slicing or tiling of the texture
-/// - [`TextureAtlas`] to draw specific sections of a sprite sheet, (See [`SpriteSheetBundle`])
+/// - [`TextureAtlas`] to draw specific sections of the texture
+///
+/// Note that `ImageScaleMode` is currently not compatible with `TextureAtlas`.
 #[derive(Bundle, Clone, Debug, Default)]
 pub struct SpriteBundle {
     /// Specifies the rendering properties of the sprite, such as color tint and flip.
@@ -41,6 +45,10 @@ pub struct SpriteBundle {
 /// Check the following examples for usage:
 /// - [`animated sprite sheet example`](https://github.com/bevyengine/bevy/blob/latest/examples/2d/sprite_sheet.rs)
 /// - [`texture atlas example`](https://github.com/bevyengine/bevy/blob/latest/examples/2d/texture_atlas.rs)
+#[deprecated(
+    since = "0.14.0",
+    note = "Use `TextureAtlas` alongside a `SpriteBundle` instead"
+)]
 #[derive(Bundle, Clone, Debug, Default)]
 pub struct SpriteSheetBundle {
     /// Specifies the rendering properties of the sprite, such as color tint and flip.

crates/bevy_sprite/src/lib.rs

@@ -12,9 +12,13 @@ mod texture_atlas_builder;
 mod texture_slice;
 
 pub mod prelude {
+    #[allow(deprecated)]
+    #[doc(hidden)]
+    pub use crate::bundle::SpriteSheetBundle;
+
     #[doc(hidden)]
     pub use crate::{
-        bundle::{SpriteBundle, SpriteSheetBundle},
+        bundle::SpriteBundle,
         sprite::{ImageScaleMode, Sprite},
         texture_atlas::{TextureAtlas, TextureAtlasLayout},
         texture_slice::{BorderRect, SliceScaleMode, TextureSlice, TextureSlicer},

crates/bevy_sprite/src/texture_atlas_builder.rs

@@ -173,14 +173,10 @@ impl<'a> TextureAtlasBuilder<'a> {
     ///     let texture = textures.add(texture);
     ///     let layout = layouts.add(atlas_layout);
     ///     // Spawn your sprite
-    ///     commands.spawn(SpriteSheetBundle {
+    ///     commands.spawn((
-    ///        texture,
+    ///         SpriteBundle { texture, ..Default::default() },
-    ///        atlas: TextureAtlas {
+    ///         TextureAtlas::from(layout),
-    ///             layout,
+    ///     ));
-    ///             index: 0
-    ///         },
-    ///       ..Default::default()
-    ///     });
     /// }
     /// ```
     ///

crates/bevy_ui/src/node_bundles.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 //! This module contains basic node bundles used to build UIs
 
 #[cfg(feature = "bevy_text")]
@@ -77,8 +79,11 @@ impl Default for NodeBundle {
 ///
 /// # Extra behaviours
 ///
-/// You may add the following components to enable additional behaviours
+/// You may add the following components to enable additional behaviours:
 /// - [`ImageScaleMode`](bevy_sprite::ImageScaleMode) to enable either slicing or tiling of the texture
+/// - [`TextureAtlas`] to draw specific sections of the texture
+///
+/// Note that `ImageScaleMode` is currently not compatible with `TextureAtlas`.
 #[derive(Bundle, Debug, Default)]
 pub struct ImageBundle {
     /// Describes the logical size of the node
@@ -122,6 +127,10 @@ pub struct ImageBundle {
 /// A UI node that is a texture atlas sprite
 ///
 /// This bundle is identical to [`ImageBundle`] with an additional [`TextureAtlas`] component.
+#[deprecated(
+    since = "0.14.0",
+    note = "Use `TextureAtlas` alongside `ImageBundle` instead"
+)]
 #[derive(Bundle, Debug, Default)]
 pub struct AtlasImageBundle {
     /// Describes the logical size of the node
@@ -292,8 +301,11 @@ where
 ///
 /// # Extra behaviours
 ///
-/// You may add the following components to enable additional behaviours
+/// You may add the following components to enable additional behaviours:
 /// - [`ImageScaleMode`](bevy_sprite::ImageScaleMode) to enable either slicing or tiling of the texture
+/// - [`TextureAtlas`] to draw specific sections of the texture
+///
+/// Note that `ImageScaleMode` is currently not compatible with `TextureAtlas`.
 #[derive(Bundle, Clone, Debug)]
 pub struct ButtonBundle {
     /// Describes the logical size of the node

examples/2d/sprite_sheet.rs

@@ -48,15 +48,15 @@ fn setup(
     let animation_indices = AnimationIndices { first: 1, last: 6 };
     commands.spawn(Camera2dBundle::default());
     commands.spawn((
-        SpriteSheetBundle {
+        SpriteBundle {
-            texture,
-            atlas: TextureAtlas {
-                layout: texture_atlas_layout,
-                index: animation_indices.first,
-            },
             transform: Transform::from_scale(Vec3::splat(6.0)),
+            texture,
             ..default()
         },
+        TextureAtlas {
+            layout: texture_atlas_layout,
+            index: animation_indices.first,
+        },
         animation_indices,
         AnimationTimer(Timer::from_seconds(0.1, TimerMode::Repeating)),
     ));

examples/2d/texture_atlas.rs

@@ -240,19 +240,21 @@ fn create_sprite_from_atlas(
     atlas_handle: Handle<TextureAtlasLayout>,
     texture: Handle<Image>,
 ) {
-    commands.spawn(SpriteSheetBundle {
+    commands.spawn((
-        transform: Transform {
+        SpriteBundle {
-            translation: Vec3::new(translation.0, translation.1, translation.2),
+            transform: Transform {
-            scale: Vec3::splat(3.0),
+                translation: Vec3::new(translation.0, translation.1, translation.2),
+                scale: Vec3::splat(3.0),
+                ..default()
+            },
+            texture,
             ..default()
         },
-        texture,
+        TextureAtlas {
-        atlas: TextureAtlas {
-            index: sprite_index,
             layout: atlas_handle,
+            index: sprite_index,
         },
-        ..default()
+    ));
-    });
 }
 
 /// Create and spawn a label (text)

examples/stress_tests/many_animated_sprites.rs

@@ -84,12 +84,8 @@ fn setup(
             timer.set_elapsed(Duration::from_secs_f32(rng.gen::<f32>()));
 
             commands.spawn((
-                SpriteSheetBundle {
+                SpriteBundle {
                     texture: texture_handle.clone(),
-                    atlas: TextureAtlas {
-                        layout: texture_atlas_handle.clone(),
-                        ..Default::default()
-                    },
                     transform: Transform {
                         translation,
                         rotation,
@@ -101,6 +97,7 @@ fn setup(
                     },
                     ..default()
                 },
+                TextureAtlas::from(texture_atlas_handle.clone()),
                 AnimationTimer(timer),
             ));
         }

examples/ui/ui_texture_atlas.rs

@@ -49,16 +49,18 @@ fn setup(
             ..default()
         })
         .with_children(|parent| {
-            parent.spawn(AtlasImageBundle {
+            parent.spawn((
-                style: Style {
+                ImageBundle {
-                    width: Val::Px(256.),
+                    style: Style {
-                    height: Val::Px(256.),
+                        width: Val::Px(256.),
+                        height: Val::Px(256.),
+                        ..default()
+                    },
+                    image: UiImage::new(texture_handle),
                     ..default()
                 },
-                texture_atlas: texture_atlas_handle.into(),
+                TextureAtlas::from(texture_atlas_handle),
-                image: UiImage::new(texture_handle),
+            ));
-                ..default()
-            });
             parent.spawn(TextBundle::from_sections([
                 TextSection::new("press ".to_string(), text_style.clone()),
                 TextSection::new(