WIP

Author: merwaaan

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 5.0.0 - 2025-??-??
+
+This release comes with a significant rework of the high-level API that tightens up the relationships between spritesheets, clips and animations.
+
+It also removes the `AnimationLibrary` resource in favor of registering animations in `Assets<Animation>` like other Bevy assets.
+
+As a consequence of the `AnimationLibrary` removal, it's no longer possible to name clips, animations or markers to retrieve them by name across systems.
+An alternative (and safer!) way to retrieve animation data is to save it in custom resources, as demonstrated in the examples (eg. `examples/character.rs`).
+If you still prefer to use names, you may want to define such a custom resource as -- for instance -- a `HashMap<String, Handle<Animation>>`.
+
+Migrating to this new version should be pretty straightforward. Please check out the updated examples and documentation!
+
+### Added
+
+- `Spritesheet` can now create animation-ready sprites, 3D sprites, UI images, cursors and texture atlases to reduce boilerplate when creating animated entities
+- Add an example showcasing animated UI images
+
+### Changed
+
+- Animations are now exclusively created with `Spritesheet::create_animation()` which returns an `AnimationBuilder`
+- Clips are now exclusively created with `AnimationBuilder::start_clip()`/`AnimationBuilder::copy_clip()`
+- Rename `AnimationMarkerId` to `Marker`
+
+### Removed
+
+- Remove the `AnimationLibrary` resource (you can now register animations in `Assets<Animation>`)
+
+### Fixed
+
+- Fix a few panics when selecting out-of-bounds cells in spritesheets
+
 ## 4.0.1 - 2025-10-09
 
 No actual changes. Had to bump the version to republish the crate and fix docs.rs failing to build the documentation.
@@ -9,7 +40,7 @@ No actual changes. Had to bump the version to republish the crate and fix docs.r
 ### Added
 
 - Add support for Bevy 0.17
-- Add an example showing how to setup an animated cursor
+- Add an example showcasing animated cursors
 
 ### Changed
 
@@ -157,7 +188,7 @@ To create a variant of a clip, just clone and reconfigure it before registering
 
 ### Fixed
 
-- Switch `new_clip`/`new_animatio`n closures to FnMut to allow mutations
+- Switch `new_clip`/`new_animation` closures to FnMut to allow mutations
 
 ## 0.1.0 - 2024-04-10
 

README.md

@@ -0,0 +1,14 @@
+# Make events optional
+
+Events are always emitted, even when users never use them.
+This becomes costly when many sprites are spawned.
+Put them behind a feature flag or add a runtime option to toggle them.
+
+# Add the current animation repetition to events
+
+We have it available so might as well use it.
+
+# Optimize playback
+
+There's currently a lot of allocations during playback (esp. for events).
+Use a single storage for all sprites instead of allocating one at each sprite update.

TODO.md

@@ -1,28 +1,22 @@
 // This example shows how to create 3D sprites.
 
-#[path = "./common/mod.rs"]
-pub mod common;
-
 use bevy::{prelude::*, sprite::Anchor};
 use bevy_spritesheet_animation::prelude::*;
 use rand::{Rng, seq::IndexedRandom as _};
 
 fn main() {
     App::new()
-        .add_plugins((
-            DefaultPlugins.set(ImagePlugin::default_nearest()),
-            SpritesheetAnimationPlugin,
-        ))
+        .add_plugins((DefaultPlugins, SpritesheetAnimationPlugin))
         .add_systems(Startup, spawn_sprites)
         .add_systems(Update, (update_on_keypress, orbit, draw_gizmos))
         .run();
 }
 
 fn spawn_sprites(
     mut commands: Commands,
-    mut library: ResMut<AnimationLibrary>,
-    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
     assets: Res<AssetServer>,
+    mut animations: ResMut<Assets<Animation>>,
+    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
 ) {
     // 3D sprites require a 3D camera
 
@@ -33,24 +27,19 @@ fn spawn_sprites(
 
     // Create an animation as usual
 
-    let spritesheet = Spritesheet::new(8, 8);
-
-    let clip = Clip::from_frames(spritesheet.row(3));
-
-    let clip_id = library.register_clip(clip);
+    let image = assets.load("character.png");
 
-    let animation = Animation::from_clip(clip_id);
+    let spritesheet = Spritesheet::new(&image, 8, 8);
 
-    let animation_id = library.register_animation(animation);
+    let animation = spritesheet.create_animation().add_row(3).build();
 
-    // Create an image and a texture atlas like you would for any Bevy sprite
+    let animation_handle = animations.add(animation);
 
-    let image = assets.load("character.png");
+    // Create an image and a texture atlas like you would for 2D sprites
 
-    let atlas = TextureAtlas {
-        layout: atlas_layouts.add(spritesheet.atlas_layout(96, 96)),
-        ..default()
-    };
+    let atlas = spritesheet
+        .with_size_hint(768, 768)
+        .atlas(&mut atlas_layouts);
 
     // Spawn 3D sprites
 
@@ -79,7 +68,7 @@ fn spawn_sprites(
     for (i, sprite) in sprites.into_iter().enumerate() {
         commands.spawn((
             sprite,
-            SpritesheetAnimation::from_id(animation_id),
+            SpritesheetAnimation::new(animation_handle.clone()),
             Orbit {
                 start_angle: i as f32 * std::f32::consts::TAU / sprite_count as f32,
             },
@@ -95,9 +84,8 @@ fn spawn_sprites(
 
     // Help text
 
-    commands.spawn((Text(
-        "C: random colors\nX: flip on X\nY: flip on Y\nA: random anchors\nS: random sizes\nR: reset".to_owned()),
-        TextFont::from_font_size(30.0)
+    commands.spawn(Text::new(
+        "C: random colors\nX: flip on X\nY: flip on Y\nA: random anchors\nS: random sizes\nR: reset"
     ));
 }
 
@@ -166,9 +154,11 @@ struct Orbit {
 }
 
 fn orbit(time: Res<Time>, mut query: Query<(&Orbit, &mut Transform)>) {
+    let secs_elapsed = time.elapsed_secs();
+
     for (orbit, mut transform) in &mut query {
-        transform.translation.x = (orbit.start_angle + time.elapsed_secs()).cos() * 1500.0;
-        transform.translation.z = (orbit.start_angle + time.elapsed_secs()).sin() * 1500.0;
+        transform.translation.x = (orbit.start_angle + secs_elapsed).cos() * 1500.0;
+        transform.translation.z = (orbit.start_angle + secs_elapsed).sin() * 1500.0;
     }
 }
 

assets/cursor.png

@@ -1,76 +1,63 @@
 // This example shows how to create a simple animated sprite.
 
-#[path = "./common/mod.rs"]
-pub mod common;
-
 use bevy::prelude::*;
 use bevy_spritesheet_animation::prelude::*;
 
 fn main() {
     App::new()
-        .add_plugins(DefaultPlugins)
-        // Add the plugin to enable animations.
-        // This makes the AnimationLibrary resource available to your systems.
+        .add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))
+        // Add the plugin to enable animations
+        //
+        // This configures the app to play animations for entities with a SpritesheetAnimation component.
+        // This also makes the Assets<Animation> resource available to your systems.
         .add_plugins(SpritesheetAnimationPlugin)
-        .add_systems(
-            Startup,
-            (create_animation, spawn_sprite.after(create_animation)),
-        )
+        .add_systems(Startup, create_animated_sprite)
         .run();
 }
 
-fn create_animation(mut commands: Commands, mut library: ResMut<AnimationLibrary>) {
+fn create_animated_sprite(
+    mut commands: Commands,
+    assets: Res<AssetServer>,
+    mut animations: ResMut<Assets<Animation>>,
+    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
+) {
     commands.spawn(Camera2d);
 
-    // Create a clip that references some frames from a spritesheet
-
-    let spritesheet = Spritesheet::new(8, 8);
-
-    let clip = Clip::from_frames(spritesheet.row(3));
-
-    let clip_id = library.register_clip(clip);
+    // Create an animation from a row of an 8x8 spritesheet
+    //
+    // This is a simple animation made of a single clip but we can create more sophisticated animations with multiple clips, each one having different parameters.
+    //
+    // See the `composition` example for more details.
 
-    // Create an animation that uses the clip
+    let image = assets.load("character.png");
 
-    let animation = Animation::from_clip(clip_id);
+    let spritesheet = Spritesheet::new(&image, 8, 8);
 
-    let animation_id = library.register_animation(animation);
+    let animation = spritesheet
+        .create_animation()
+        .add_row(3)
+        .set_duration(AnimationDuration::PerFrame(100))
+        .build();
 
-    // Name the animation to retrieve it from other systems
+    // Register the animation as an asset
 
-    library.name_animation(animation_id, "walk").unwrap();
+    let animation_handle = animations.add(animation);
 
-    // This is a simple animation with a single clip but we can create more sophisticated
-    // animations with multiple clips, each one having different parameters.
+    // Create a regular Bevy sprite
     //
-    // See the `composition` example for more details.
-}
-
-// We split the setup in two separate systems to show how to retrieve animations from their name
-
-fn spawn_sprite(
-    mut commands: Commands,
-    library: Res<AnimationLibrary>,
-    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
-    assets: Res<AssetServer>,
-) {
-    // Retrieve our animation from the library
-
-    if let Some(animation_id) = library.animation_with_name("walk") {
-        // Create an image and a texture atlas like you would for any Bevy sprite
-
-        let image = assets.load("character.png");
+    // Here we use the spritesheet to automatically generate the animation-ready Bevy sprite.
+    // This is optional and you may prefer to build the sprite manually.
 
-        let atlas = TextureAtlas {
-            layout: atlas_layouts.add(Spritesheet::new(8, 8).atlas_layout(96, 96)),
-            ..default()
-        };
+    let sprite = spritesheet
+        .with_size_hint(768, 768)
+        .sprite(&mut atlas_layouts);
 
-        // Spawn a sprite with a SpritesheetAnimation component that references our animation
+    // Spawn the sprite with a SpritesheetAnimation component that references our animation
 
-        commands.spawn((
-            Sprite::from_atlas_image(image, atlas),
-            SpritesheetAnimation::from_id(animation_id),
-        ));
-    }
+    commands.spawn((
+        // This is a regular Bevy sprite
+        sprite,
+        // This is the component that animates the sprite
+        SpritesheetAnimation::new(animation_handle),
+    ));
 }