Migrate bevy_sprite to required components (#15489)

# Objective

Continue migration of bevy APIs to required components, following
guidance of https://hackmd.io/@bevy/required_components/

## Solution

- Make `Sprite` require `Transform` and `Visibility` and
`SyncToRenderWorld`
- move image and texture atlas handles into `Sprite`
- deprecate `SpriteBundle`
- remove engine uses of `SpriteBundle`

## Testing

ran cargo tests on bevy_sprite and tested several sprite examples.

---

## Migration Guide

Replace all uses of `SpriteBundle` with `Sprite`. There are several new
convenience constructors: `Sprite::from_image`,
`Sprite::from_atlas_image`, `Sprite::from_color`.

WARNING: use of `Handle<Image>` and `TextureAtlas` as components on
sprite entities will NO LONGER WORK. Use the fields on `Sprite` instead.
I would have removed the `Component` impls from `TextureAtlas` and
`Handle<Image>` except it is still used within ui. We should fix this
moving forward with the migration.

crates/bevy_ecs/src/bundle.rs

@@ -77,8 +77,6 @@ use core::{any::TypeId, ptr::NonNull};
 /// Additionally, [Tuples](`tuple`) of bundles are also [`Bundle`] (with up to 15 bundles).
 /// These bundles contain the items of the 'inner' bundles.
 /// This is a convenient shorthand which is primarily used when spawning entities.
-/// For example, spawning an entity using the bundle `(SpriteBundle {...}, PlayerMarker)`
-/// will spawn an entity with components required for a 2d sprite, and the `PlayerMarker` component.
 ///
 /// [`unit`], otherwise known as [`()`](`unit`), is a [`Bundle`] containing no components (since it
 /// can also be considered as the empty tuple).

crates/bevy_sprite/src/bundle.rs

@@ -1,3 +1,4 @@
+#![expect(deprecated)]
 use crate::Sprite;
 use bevy_asset::Handle;
 use bevy_ecs::bundle::Bundle;
@@ -16,6 +17,10 @@ use bevy_transform::components::{GlobalTransform, Transform};
 /// - [`ImageScaleMode`](crate::ImageScaleMode) to enable either slicing or tiling of the texture
 /// - [`TextureAtlas`](crate::TextureAtlas) to draw a specific section of the texture
 #[derive(Bundle, Clone, Debug, Default)]
+#[deprecated(
+ since = "0.15.0",
+ note = "Use the `Sprite` component instead. Inserting it will now also insert `Transform` and `Visibility` automatically."
+)]
 pub struct SpriteBundle {
  /// Specifies the rendering properties of the sprite, such as color tint and flip.
  pub sprite: Sprite,

crates/bevy_sprite/src/lib.rs

@@ -185,9 +185,9 @@ pub fn calculate_bounds_2d(
  atlases: Res<Assets<TextureAtlasLayout>>,
  meshes_without_aabb: Query<(Entity, &Mesh2d), (Without<Aabb>, Without<NoFrustumCulling>)>,
  sprites_to_recalculate_aabb: Query<
- (Entity, &Sprite, &Handle<Image>, Option<&TextureAtlas>),
+ (Entity, &Sprite),
  (
- Or<(Without<Aabb>, Changed<Sprite>, Changed<TextureAtlas>)>,
+ Or<(Without<Aabb>, Changed<Sprite>)>,
  Without<NoFrustumCulling>,
  ),
  >,
@@ -199,13 +199,13 @@ pub fn calculate_bounds_2d(
  }
  }
  }
- for (entity, sprite, texture_handle, atlas) in &sprites_to_recalculate_aabb {
+ for (entity, sprite) in &sprites_to_recalculate_aabb {
  if let Some(size) = sprite
  .custom_size
  .or_else(|| sprite.rect.map(|rect| rect.size()))
- .or_else(|| match atlas {
+ .or_else(|| match &sprite.texture_atlas {
  // We default to the texture size for regular sprites
- None => images.get(texture_handle).map(Image::size_f32),
+ None => images.get(&sprite.image).map(Image::size_f32),
  // We default to the drawn rect for atlas sprites
  Some(atlas) => atlas
  .texture_rect(&atlases)
@@ -259,10 +259,7 @@ mod test {
  app.add_systems(Update, calculate_bounds_2d);
 
  // Add entities
- let entity = app
- .world_mut()
- .spawn((Sprite::default(), image_handle))
- .id();
+ let entity = app.world_mut().spawn(Sprite::from_image(image_handle)).id();
 
  // Verify that the entity does not have an AABB
  assert!(!app

crates/bevy_sprite/src/picking_backend.rs

@@ -4,7 +4,7 @@
 
 use core::cmp::Reverse;
 
-use crate::{Sprite, TextureAtlas, TextureAtlasLayout};
+use crate::{Sprite, TextureAtlasLayout};
 use bevy_app::prelude::*;
 use bevy_asset::prelude::*;
 use bevy_ecs::prelude::*;
@@ -32,8 +32,6 @@ pub fn sprite_picking(
  sprite_query: Query<(
  Entity,
  &Sprite,
- Option<&TextureAtlas>,
- &Handle<Image>,
  &GlobalTransform,
  Option<&PickingBehavior>,
  &ViewVisibility,
@@ -42,9 +40,9 @@ pub fn sprite_picking(
 ) {
  let mut sorted_sprites: Vec<_> = sprite_query
  .iter()
- .filter(|x| !x.4.affine().is_nan())
+ .filter(|x| !x.2.affine().is_nan())
  .collect();
- sorted_sprites.sort_by_key(|x| Reverse(FloatOrd(x.4.translation().z)));
+ sorted_sprites.sort_by_key(|x| Reverse(FloatOrd(x.2.translation().z)));
 
  let primary_window = primary_window.get_single().ok();
 
@@ -77,82 +75,79 @@ pub fn sprite_picking(
  .iter()
  .copied()
  .filter(|(.., visibility)| visibility.get())
- .filter_map(
- |(entity, sprite, atlas, image, sprite_transform, picking_behavior, ..)| {
- if blocked {
- return None;
- }
-
- // Hit box in sprite coordinate system
- let extents = match (sprite.custom_size, atlas) {
- (Some(custom_size), _) => custom_size,
- (None, None) => images.get(image)?.size().as_vec2(),
- (None, Some(atlas)) => texture_atlas_layout
- .get(&atlas.layout)
- .and_then(|layout| layout.textures.get(atlas.index))
- // Dropped atlas layouts and indexes out of bounds are rendered as a sprite
- .map_or(images.get(image)?.size().as_vec2(), |rect| {
- rect.size().as_vec2()
- }),
- };
- let anchor = sprite.anchor.as_vec();
- let center = -anchor * extents;
- let rect = Rect::from_center_half_size(center, extents / 2.0);
-
- // Transform cursor line segment to sprite coordinate system
- let world_to_sprite = sprite_transform.affine().inverse();
- let cursor_start_sprite =
- world_to_sprite.transform_point3(cursor_ray_world.origin);
- let cursor_end_sprite = world_to_sprite.transform_point3(cursor_ray_end);
-
- // Find where the cursor segment intersects the plane Z=0 (which is the sprite's
- // plane in sprite-local space). It may not intersect if, for example, we're
- // viewing the sprite side-on
- if cursor_start_sprite.z == cursor_end_sprite.z {
- // Cursor ray is parallel to the sprite and misses it
- return None;
- }
- let lerp_factor =
- f32::inverse_lerp(cursor_start_sprite.z, cursor_end_sprite.z, 0.0);
- if !(0.0..=1.0).contains(&lerp_factor) {
- // Lerp factor is out of range, meaning that while an infinite line cast by
- // the cursor would intersect the sprite, the sprite is not between the
- // camera's near and far planes
- return None;
- }
- // Otherwise we can interpolate the xy of the start and end positions by the
- // lerp factor to get the cursor position in sprite space!
- let cursor_pos_sprite = cursor_start_sprite
- .lerp(cursor_end_sprite, lerp_factor)
- .xy();
-
- let is_cursor_in_sprite = rect.contains(cursor_pos_sprite);
-
- blocked = is_cursor_in_sprite
- && picking_behavior.map(|p| p.should_block_lower) != Some(false);
-
- is_cursor_in_sprite.then(|| {
- let hit_pos_world =
- sprite_transform.transform_point(cursor_pos_sprite.extend(0.0));
- // Transform point from world to camera space to get the Z distance
- let hit_pos_cam = cam_transform
- .affine()
- .inverse()
- .transform_point3(hit_pos_world);
- // HitData requires a depth as calculated from the camera's near clipping plane
- let depth = -cam_ortho.near - hit_pos_cam.z;
- (
- entity,
- HitData::new(
- cam_entity,
- depth,
- Some(hit_pos_world),
- Some(*sprite_transform.back()),
- ),
- )
- })
- },
- )
+ .filter_map(|(entity, sprite, sprite_transform, picking_behavior, ..)| {
+ if blocked {
+ return None;
+ }
+
+ // Hit box in sprite coordinate system
+ let extents = match (sprite.custom_size, &sprite.texture_atlas) {
+ (Some(custom_size), _) => custom_size,
+ (None, None) => images.get(&sprite.image)?.size().as_vec2(),
+ (None, Some(atlas)) => texture_atlas_layout
+ .get(&atlas.layout)
+ .and_then(|layout| layout.textures.get(atlas.index))
+ // Dropped atlas layouts and indexes out of bounds are rendered as a sprite
+ .map_or(images.get(&sprite.image)?.size().as_vec2(), |rect| {
+ rect.size().as_vec2()
+ }),
+ };
+ let anchor = sprite.anchor.as_vec();
+ let center = -anchor * extents;
+ let rect = Rect::from_center_half_size(center, extents / 2.0);
+
+ // Transform cursor line segment to sprite coordinate system
+ let world_to_sprite = sprite_transform.affine().inverse();
+ let cursor_start_sprite = world_to_sprite.transform_point3(cursor_ray_world.origin);
+ let cursor_end_sprite = world_to_sprite.transform_point3(cursor_ray_end);
+
+ // Find where the cursor segment intersects the plane Z=0 (which is the sprite's
+ // plane in sprite-local space). It may not intersect if, for example, we're
+ // viewing the sprite side-on
+ if cursor_start_sprite.z == cursor_end_sprite.z {
+ // Cursor ray is parallel to the sprite and misses it
+ return None;
+ }
+ let lerp_factor =
+ f32::inverse_lerp(cursor_start_sprite.z, cursor_end_sprite.z, 0.0);
+ if !(0.0..=1.0).contains(&lerp_factor) {
+ // Lerp factor is out of range, meaning that while an infinite line cast by
+ // the cursor would intersect the sprite, the sprite is not between the
+ // camera's near and far planes
+ return None;
+ }
+ // Otherwise we can interpolate the xy of the start and end positions by the
+ // lerp factor to get the cursor position in sprite space!
+ let cursor_pos_sprite = cursor_start_sprite
+ .lerp(cursor_end_sprite, lerp_factor)
+ .xy();
+
+ let is_cursor_in_sprite = rect.contains(cursor_pos_sprite);
+
+ blocked = is_cursor_in_sprite
+ && picking_behavior.map(|p| p.should_block_lower) != Some(false);
+
+ is_cursor_in_sprite.then(|| {
+ let hit_pos_world =
+ sprite_transform.transform_point(cursor_pos_sprite.extend(0.0));
+ // Transform point from world to camera space to get the Z distance
+ let hit_pos_cam = cam_transform
+ .affine()
+ .inverse()
+ .transform_point3(hit_pos_world);
+ // HitData requires a depth as calculated from the camera's near clipping plane
+ let depth = -cam_ortho.near - hit_pos_cam.z;
+ (
+ entity,
+ HitData::new(
+ cam_entity,
+ depth,
+ Some(hit_pos_world),
+ Some(*sprite_transform.back()),
+ ),
+ )
+ })
+ })
  .collect();
 
  let order = camera.order as f32;

crates/bevy_sprite/src/render/mod.rs

@@ -1,10 +1,10 @@
 use core::ops::Range;
 
 use crate::{
- texture_atlas::{TextureAtlas, TextureAtlasLayout},
- ComputedTextureSlices, Sprite, WithSprite, SPRITE_SHADER_HANDLE,
+ texture_atlas::TextureAtlasLayout, ComputedTextureSlices, Sprite, WithSprite,
+ SPRITE_SHADER_HANDLE,
 };
-use bevy_asset::{AssetEvent, AssetId, Assets, Handle};
+use bevy_asset::{AssetEvent, AssetId, Assets};
 use bevy_color::{ColorToComponents, LinearRgba};
 use bevy_core_pipeline::{
  core_2d::{Transparent2d, CORE_2D_DEPTH_FORMAT},
@@ -377,15 +377,12 @@ pub fn extract_sprites(
  &ViewVisibility,
  &Sprite,
  &GlobalTransform,
- &Handle<Image>,
- Option<&TextureAtlas>,
  Option<&ComputedTextureSlices>,
  )>,
  >,
 ) {
  extracted_sprites.sprites.clear();
- for (original_entity, entity, view_visibility, sprite, transform, handle, sheet, slices) in
- sprite_query.iter()
+ for (original_entity, entity, view_visibility, sprite, transform, slices) in sprite_query.iter()
  {
  if !view_visibility.get() {
  continue;
@@ -394,12 +391,14 @@ pub fn extract_sprites(
  if let Some(slices) = slices {
  extracted_sprites.sprites.extend(
  slices
- .extract_sprites(transform, original_entity, sprite, handle)
+ .extract_sprites(transform, original_entity, sprite)
  .map(|e| (commands.spawn(TemporaryRenderEntity).id(), e)),
  );
  } else {
- let atlas_rect =
- sheet.and_then(|s| s.texture_rect(&texture_atlases).map(|r| r.as_rect()));
+ let atlas_rect = sprite
+ .texture_atlas
+ .as_ref()
+ .and_then(|s| s.texture_rect(&texture_atlases).map(|r| r.as_rect()));
  let rect = match (atlas_rect, sprite.rect) {
  (None, None) => None,
  (None, Some(sprite_rect)) => Some(sprite_rect),
@@ -423,7 +422,7 @@ pub fn extract_sprites(
  custom_size: sprite.custom_size,
  flip_x: sprite.flip_x,
  flip_y: sprite.flip_y,
- image_handle_id: handle.id(),
+ image_handle_id: sprite.image.id(),
  anchor: sprite.anchor.as_vec(),
  original_entity: Some(original_entity),
  },

crates/bevy_sprite/src/sprite.rs

@@ -1,16 +1,22 @@
+use bevy_asset::Handle;
 use bevy_color::Color;
 use bevy_ecs::{component::Component, reflect::ReflectComponent};
 use bevy_math::{Rect, Vec2};
 use bevy_reflect::{std_traits::ReflectDefault, Reflect};
+use bevy_render::{sync_world::SyncToRenderWorld, texture::Image, view::Visibility};
+use bevy_transform::components::Transform;
 
-use crate::TextureSlicer;
+use crate::{TextureAtlas, TextureSlicer};
 
-/// Specifies the rendering properties of a sprite.
-///
-/// This is commonly used as a component within [`SpriteBundle`](crate::bundle::SpriteBundle).
+/// Describes a sprite to be rendered to a 2D camera
 #[derive(Component, Debug, Default, Clone, Reflect)]
+#[require(Transform, Visibility, SyncToRenderWorld)]
 #[reflect(Component, Default, Debug)]
 pub struct Sprite {
+ /// The image used to render the sprite
+ pub image: Handle<Image>,
+ /// The (optional) texture atlas used to render the sprite
+ pub texture_atlas: Option<TextureAtlas>,
  /// The sprite's color tint
  pub color: Color,
  /// Flip the sprite along the `X` axis
@@ -21,9 +27,9 @@ pub struct Sprite {
  /// of the sprite's image
  pub custom_size: Option<Vec2>,
  /// An optional rectangle representing the region of the sprite's image to render, instead of rendering
- /// the full image. This is an easy one-off alternative to using a [`TextureAtlas`](crate::TextureAtlas).
+ /// the full image. This is an easy one-off alternative to using a [`TextureAtlas`].
  ///
- /// When used with a [`TextureAtlas`](crate::TextureAtlas), the rect
+ /// When used with a [`TextureAtlas`], the rect
  /// is offset by the atlas's minimal (top-left) corner position.
  pub rect: Option<Rect>,
  /// [`Anchor`] point of the sprite in the world
@@ -38,6 +44,38 @@ impl Sprite {
  ..Default::default()
  }
  }
+
+ /// Create a sprite from an image
+ pub fn from_image(image: Handle<Image>) -> Self {
+ Self {
+ image,
+ ..Default::default()
+ }
+ }
+
+ /// Create a sprite from an image, with an associated texture atlas
+ pub fn from_atlas_image(image: Handle<Image>, atlas: TextureAtlas) -> Self {
+ Self {
+ image,
+ texture_atlas: Some(atlas),
+ ..Default::default()
+ }
+ }
+
+ /// Create a sprite from a solid color
+ pub fn from_color(color: impl Into<Color>, size: Vec2) -> Self {
+ Self {
+ color: color.into(),
+ custom_size: Some(size),
+ ..Default::default()
+ }
+ }
+}
+
+impl From<Handle<Image>> for Sprite {
+ fn from(image: Handle<Image>) -> Self {
+ Self::from_image(image)
+ }
 }
 
 /// Controls how the image is altered when scaled.
@@ -58,7 +96,7 @@ pub enum ImageScaleMode {
  },
 }
 
-/// How a sprite is positioned relative to its [`Transform`](bevy_transform::components::Transform).
+/// How a sprite is positioned relative to its [`Transform`].
 /// It defaults to `Anchor::Center`.
 #[derive(Component, Debug, Clone, Copy, PartialEq, Default, Reflect)]
 #[reflect(Component, Default, Debug, PartialEq)]