WIP

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.0 - 2024-??-??
+
+### Added
+
+- Animation progress can be accessed and mutated directly in the SpritesheetAnimation component
+
 ## 0.3.0 - 2024-08-26
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bevy_spritesheet_animation"
-version = "0.3.0"
+version = "0.4.0"
 description = "A Bevy plugin for animating sprites"
 repository = "https://github.com/merwaaan/bevy_spritesheet_animation"
 readme="README.md"

examples/composition.rs

@@ -4,7 +4,9 @@
 pub mod common;
 
 use bevy::prelude::*;
-use bevy_spritesheet_animation::prelude::*;
+use bevy_spritesheet_animation::{
+    components::spritesheet_animation::AnimationProgress, prelude::*,
+};
 
 fn main() {
     App::new()

examples/control.rs

@@ -0,0 +1,91 @@
+// This example illustrates how to control the state of an animated sprite.
+
+#[path = "./common/mod.rs"]
+pub mod common;
+
+use bevy::prelude::*;
+use bevy_spritesheet_animation::{
+    components::spritesheet_animation::AnimationProgress, prelude::*,
+};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_plugins(SpritesheetAnimationPlugin)
+        .add_systems(Startup, setup)
+        .add_systems(Update, update)
+        .run();
+}
+
+fn setup(
+    mut commands: Commands,
+    mut library: ResMut<SpritesheetLibrary>,
+    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
+    assets: Res<AssetServer>,
+) {
+    commands.spawn(Camera2dBundle::default());
+
+    let texture = assets.load("character.png");
+
+    let layout = atlas_layouts.add(TextureAtlasLayout::from_grid(
+        UVec2::new(96, 96),
+        8,
+        8,
+        None,
+        None,
+    ));
+
+    let clip_id = library.new_clip(|clip| {
+        clip.push_frame_indices(Spritesheet::new(8, 8).positions([(0, 1), (0, 3), (0, 5), (0, 7)]))
+            .set_default_duration(AnimationDuration::PerFrame(3_000));
+    });
+
+    let animation_id = library.new_animation(|animation| {
+        animation
+            .add_stage(clip_id.into())
+            .set_repeat(AnimationRepeat::Cycles(1));
+    });
+
+    commands.spawn((
+        SpriteBundle {
+            texture,
+            ..default()
+        },
+        TextureAtlas {
+            layout,
+            ..default()
+        },
+        SpritesheetAnimation::from_id(animation_id),
+    ));
+}
+
+fn update(keyboard: Res<ButtonInput<KeyCode>>, mut sprites: Query<&mut SpritesheetAnimation>) {
+    for mut sprite in &mut sprites {
+        // Play/Pause
+
+        if keyboard.just_pressed(KeyCode::KeyP) {
+            sprite.playing = !sprite.playing;
+        }
+
+        // Reset
+
+        if keyboard.just_pressed(KeyCode::KeyR) {
+            sprite.reset();
+        }
+
+        // Switch to specific frames
+
+        static KEYS: [KeyCode; 4] = [
+            KeyCode::Numpad0,
+            KeyCode::Numpad1,
+            KeyCode::Numpad2,
+            KeyCode::Numpad3,
+        ];
+
+        for (frame, key) in KEYS.iter().enumerate() {
+            if keyboard.just_pressed(*key) {
+                sprite.progress.frame = frame;
+            }
+        }
+    }
+}

src/animator.rs

@@ -12,8 +12,10 @@ use bevy::{
 use std::{collections::HashMap, sync::Arc};
 
 use crate::{
-    animation::AnimationId, components::spritesheet_animation::SpritesheetAnimation,
-    events::AnimationEvent, library::SpritesheetLibrary,
+    animation::AnimationId,
+    components::spritesheet_animation::{AnimationProgress, SpritesheetAnimation},
+    events::AnimationEvent,
+    library::SpritesheetLibrary,
     systems::spritesheet_animation::ActualTime,
 };
 
@@ -30,6 +32,10 @@ struct AnimationInstance {
     current_stage_index: usize,
     accumulated_time: u32,
 
+    /// The previous animation progress.
+    /// To detect when users manually changed it.
+    last_progress: AnimationProgress,
+
     /// Marks when the animation has ended to emit end events only once
     ended: bool,
 }
@@ -73,23 +79,19 @@ impl SpritesheetAnimator {
             // Create a new animation instance if:
             // - the entity is new OR
             // - it switched animation OR
-            // - a reset has been requested
+            // - progress has been manually controlled
 
             let needs_new_animation_instance = match self.animation_instances.get(&entity) {
-                // The entity has an animation instance already but it switched animation
+                // The entity has an animation instance already but it switched animation/was manually controlled
                 Some(instance) => {
                     instance.animation_id != entity_animation.animation_id
-                        || entity_animation.reset_requested
+                        || instance.last_progress != entity_animation.progress
                 }
                 // The entity has no animation instance yet
                 None => true,
             };
 
             if needs_new_animation_instance {
-                // Clear any reset request
-
-                entity_animation.reset_requested = false;
-
                 // Retrieve the cached animation data (create it if needed)
 
                 let cache = self
@@ -101,8 +103,11 @@ impl SpritesheetAnimator {
 
                 // Create a new iterator for this animation
 
-                let mut iterator =
-                    AnimationIterator::new(entity_animation.animation_id, cache.clone());
+                let mut iterator = AnimationIterator::new(
+                    entity_animation.animation_id,
+                    entity_animation.progress,
+                    cache.clone()
+                );
 
                 // Immediatly assign the first frame to kicktart the animation
 
@@ -111,6 +116,10 @@ impl SpritesheetAnimator {
                 if let Some(first_frame) = &maybe_first_frame {
                     entity_atlas.index = first_frame.atlas_index;
 
+                    // Update the animation progress
+
+                    entity_animation.progress = ;
+
                     // Emit events for the first frame
 
                     let events = SpritesheetAnimator::promote_events(&first_frame.events, &entity);
@@ -132,6 +141,7 @@ impl SpritesheetAnimator {
                         current_frame_duration: first_frame_duration,
                         current_stage_index: first_stage_index,
                         accumulated_time: 0,
+                        last_progress: AnimationProgress::default(),
                         ended: false,
                     },
                 );
@@ -141,7 +151,7 @@ impl SpritesheetAnimator {
 
             // Skip the update if the animation is paused
             //
-            // (skipped AFTER the setup above so that the first frame is assigned, even if paused)
+            // (skipped AFTER the previous steps so that the first/manual frame is assigned, even if paused)
 
             if !entity_animation.playing {
                 continue;
@@ -164,6 +174,10 @@ impl SpritesheetAnimator {
 
                     entity_atlas.index = next_frame.atlas_index;
 
+                    // Update the animation progress
+
+                    entity_animation.progress = ;
+
                     // Store this frame's data
 
                     animation_instance.current_frame_duration = next_frame.duration;