wip

Author: merwaaan

CHANGELOG.md

@@ -2,9 +2,30 @@
 
 ## 5.0.0 - 2025-??-??
 
+This release comes with a significant rework of the high-level API that tightens 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, 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 Bevy Sprites and TextureAtlases to reduce boilerplate
+
 ### 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`
+- Optimize playback TODO (x? speedup)
+
+### Removed
+
+- Remove the `AnimationLibrary` resource (you can now register new animations in `Assets<Animation>`)
 
 ## 4.0.0 - 2025-10-09
 
@@ -159,7 +180,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,8 +1,5 @@
 // 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 _};
@@ -20,9 +17,9 @@ fn main() {
 
 fn spawn_sprites(
     mut commands: Commands,
-    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
-    mut animations: ResMut<Assets<Animation>>,
     assets: Res<AssetServer>,
+    mut animations: ResMut<Assets<Animation>>,
+    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
 ) {
     // 3D sprites require a 3D camera
 
@@ -33,22 +30,19 @@ fn spawn_sprites(
 
     // Create an animation as usual
 
-    let spritesheet = Spritesheet::new(8, 8);
+    let image = assets.load("character.png");
 
-    let clip = Clip::from_frames(spritesheet.row(3));
+    let spritesheet = Spritesheet::new(&image, 8, 8);
 
-    let animation = Animation::from_clip(clip);
+    let animation = spritesheet.create_animation().add_row(3).build();
 
     let animation_handle = animations.add(animation);
 
     // Create an image and a texture atlas like you would for 2D sprites
 
-    let image = assets.load("character.png");
-
-    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
 

examples/3d.rs

@@ -1,84 +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 Assets<Animation> resource available to your systems.
+        // 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)
-        // For that example's sake, we split the setup in two separate systems to show how to retrieve animations with animation sets
-        .add_systems(
-            Startup,
-            (create_animation, spawn_sprite.after(create_animation)),
-        )
+        .add_systems(Startup, create_animated_sprite)
         .run();
 }
 
-// Define an animation set to refer to our animation across systems.
-//
-// This is not mandatory at all.
-// However it is convenient for accessing
-animation_set!(MyAnimation [
-  anim run
-]);
-
-fn create_animation(mut commands: Commands, mut animations: ResMut<Assets<Animation>>) {
+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));
-
-    // Create an animation that uses the clip
+    // Create an animation from a row of an 8x8 spritesheet
     //
-    // This is a simple animation with a single clip but we can create more sophisticated
-    // animations with multiple clips, each one having different parameters.
+    // 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.
 
-    let animation = Animation::from_clip(clip);
-
-    let animation_handle = animations.add(animation);
+    let image = assets.load("character.png");
 
-    // Store the animation to retrieve it from other systems
+    let spritesheet = Spritesheet::new(&image, 8, 8);
 
-    commands.insert_resource(MyAnimation {
-        run: animation_handle,
-    });
-}
+    let animation = spritesheet
+        .create_animation()
+        .add_row(3)
+        .set_duration(AnimationDuration::PerFrame(100))
+        .build();
 
-fn spawn_sprite(
-    mut commands: Commands,
-    assets: Res<AssetServer>,
-    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
-    my_animation: Res<MyAnimation>,
-) {
-    // Create an image and a texture atlas like you would for any Bevy sprite
-    //
-    // Here we use the Spritesheet helper to easily generate the atlas.
-    // This is optional and you may prefer to build the atlas manually.
+    // Register the animation as an asset
 
-    let image = assets.load("character.png");
+    let animation_handle = animations.add(animation);
 
-    let spritesheet = Spritesheet::new(8, 8); // TODO weird to have to recreate it
+    // Create a regular Bevy sprite
+    //
+    // 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.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::new(my_animation.run.clone()),
+        // This is a regular Bevy sprite
+        sprite,
+        // This is the component that animates the sprite
+        SpritesheetAnimation::new(animation_handle),
     ));
 }

examples/basic.rs

@@ -3,9 +3,6 @@
 // - We create a few animations for our character (idle, run, shoot) in a Startup system
 // - We move the character with the keyboard and switch between animations in an Update system
 
-#[path = "./common/mod.rs"]
-pub mod common;
-
 use bevy::prelude::*;
 use bevy_spritesheet_animation::prelude::*;
 
@@ -20,45 +17,46 @@ fn main() {
         .run();
 }
 
-animation_set!(MyAnimations [
-    anim idle,
-    anim run,
-    anim shoot
-]);
+#[derive(Resource)]
+struct MyAnimations {
+    idle: Handle<Animation>,
+    run: Handle<Animation>,
+    shoot: Handle<Animation>,
+}
 
 fn spawn_character(
     mut commands: Commands,
     assets: Res<AssetServer>,
-    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
     mut animations: ResMut<Assets<Animation>>,
+    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
 ) {
-    commands.spawn(Camera2d);
-
     // Create the animations
 
-    let spritesheet = Spritesheet::new(8, 8);
+    let image = assets.load("character.png");
 
-    // Idle
+    let spritesheet = Spritesheet::new(&image, 8, 8);
 
-    let idle_clip = Clip::from_frames(spritesheet.horizontal_strip(0, 0, 5));
+    // Idle
 
-    let idle_animation = Animation::from_clip(idle_clip);
+    let idle_animation = spritesheet
+        .create_animation()
+        .add_horizontal_strip(0, 0, 5)
+        .build();
 
     let idle_animation_handle = animations.add(idle_animation);
 
     // Run
 
-    let run_clip = Clip::from_frames(spritesheet.row(3));
-
-    let run_animation = Animation::from_clip(run_clip);
+    let run_animation = spritesheet.create_animation().add_row(3).build();
 
     let run_animation_handle = animations.add(run_animation);
 
     // Shoot
 
-    let shoot_clip = Clip::from_frames(spritesheet.horizontal_strip(0, 5, 5));
-
-    let shoot_animation = Animation::from_clip(shoot_clip);
+    let shoot_animation = spritesheet
+        .create_animation()
+        .add_horizontal_strip(0, 5, 5)
+        .build();
 
     let shoot_animation_handle = animations.add(shoot_animation);
 
@@ -72,17 +70,13 @@ fn spawn_character(
 
     // Spawn the character
 
-    let image = assets.load("character.png");
+    let sprite = spritesheet
+        .with_size_hint(768, 768)
+        .sprite(&mut atlas_layouts);
 
-    let atlas = TextureAtlas {
-        layout: atlas_layouts.add(spritesheet.atlas_layout(96, 96)),
-        ..default()
-    };
+    commands.spawn((sprite, SpritesheetAnimation::new(idle_animation_handle)));
 
-    commands.spawn((
-        Sprite::from_atlas_image(image, atlas),
-        SpritesheetAnimation::new(idle_animation_handle),
-    ));
+    commands.spawn(Camera2d);
 }
 
 // Component to mark that a character is currently shooting