Unify sprites and sprite sheets

[ManevilleF]

Related PR: #5070 (bevy_ui support for texture sheets)

Objective

Improve ergonomics for sprite sheets and remove:

• SpriteSheetBundle
• TextureAtlasSprite which is almost identic to Sprite

Dev side, this will improve maintenance and avoid duplicate queries and systems for sprite sheets

Solution

I replaced the SpriteBundle::texture field , a Handle<Image>, by a custom SpriteImage enum which can store either:

• a Handle<Image>
• a Handle<TextureAtlas> and texture sheet index

Tasks:

• SpriteImage
• Update extraction system
• Docs
• Update examples
• test examples

---

Changelog

• (BREAKING) SpriteBundle now takes a SpriteImage instead of a Handle<Image>
• (BREAKING) Removed SpriteSheetBundle
• (BREAKING) Removed TextureAtlasSprite component

Migration Guide

Sprites

let handle = asset_server.load("my_icon.png");
commands.spawn_bundle(SpriteBundle {
-   texture: handle,
+   texture: handle.into(),
   ..default()
});

or

let handle = asset_server.load("my_icon.png");
commands.spawn_bundle(SpriteBundle {
-   texture: handle,
+   texture: SpriteImage::Image(handle),
   ..default()
});

Sprite sheets

Before:

let image = asset_server.load("sheet.png");
let atlas_handle = texture_atlases.add(TextureAtlas::from_grid(image, Vec2::splate(100.0), 2, 2);
commands.spawn_bundle(SpriteSheetBundle {
   texture_atlas: atlas_handle,
   sprite: TextureAtlasSprite::new(0),
   ..default()
});

after:

let image = asset_server.load("sheet.png");
let atlas_handle = texture_atlases.add(TextureAtlas::from_grid(image, Vec2::splate(100.0), 2, 2);
commands.spawn_bundle(SpriteBundle {
   texture: SpriteImage::TextureAtlas {
      handle: atlas_handle,
      index: 0,
   },
   ..default()
});

[alice-i-cecile]

These docs are not useful to users who do not know what a sprite is.

[alice-i-cecile]

Perhaps just Sprite? I'm curious about others opinion here.

[ManevilleF]

Well Sprite is already a component

[alice-i-cecile]

We should run some of the 2D stress tests before and after this PR. Ideally we also put together a texture-atlas stress test in some form too.

We are introducing a branch, so I would expect to see some performance regression, but it may be very small in practice.

On the plus side this would make swapping an entity between a single sprite and a sprite sheet much faster because there's no components being added and removed. I can't imagine that happens much though in practice?

[mockersf]

I'm not sure I like having to add those .into() when just using an image

[ManevilleF]

I'm not sure I like having to add those .into() when just using an image

I get that, and the enum approach adds some abstraction that prevents querying directly for Handle<Image> like before.

Note that you already have to call .into() for bevy_ui for example, since its using a UiImage which is a container for the handle.

Either way I think its a choice between:

• Direct handle manipulation
• type wrappers

But I do like the enum wrapper as it removes redundancy, but maybe there is a better way

[alice-i-cecile]

Closing in favor of #5103.