Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-10 07:04:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

Deprecate SpriteSheetBundle and AtlasImageBundle (#12218)

Browse source 
# 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.
This commit is contained in:
Ben Frankel 2024-03-03 12:11:15 -08:00 committed by GitHub
parent de0ed293fa
commit 6e83439a06
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 62 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
crates/bevy_sprite/src/bundle.rs
View file

@ -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.

6
crates/bevy_sprite/src/lib.rs
View file

@ -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},

12
crates/bevy_sprite/src/texture_atlas_builder.rs
View file

@ -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 {
/// texture,
/// atlas: TextureAtlas {
/// layout,
/// index: 0
/// },
/// ..Default::default()
/// });
/// commands.spawn((
/// SpriteBundle { texture, ..Default::default() },
/// TextureAtlas::from(layout),
/// ));
/// }
/// ```
///

16
crates/bevy_ui/src/node_bundles.rs
View file

@ -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

12
examples/2d/sprite_sheet.rs
View file

@ -48,15 +48,15 @@ fn setup(
let animation_indices = AnimationIndices { first: 1, last: 6 };
commands.spawn(Camera2dBundle::default());
commands.spawn((
SpriteSheetBundle {
texture,
atlas: TextureAtlas {
layout: texture_atlas_layout,
index: animation_indices.first,
},
SpriteBundle {
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)),
));

20
examples/2d/texture_atlas.rs
View file

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

7
examples/stress_tests/many_animated_sprites.rs
View file

@ -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),
));
}

18
examples/ui/ui_texture_atlas.rs
View file

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