Add a few missing helpers to SpriteAnimation (#1147)

packages/flame/CHANGELOG.md

@@ -5,6 +5,7 @@
  - Fixed margin calculation in `HudMarginComponent` when using a viewport
  - Fixed position calculation in `HudMarginComponent` when using a viewport
  - Add noClip option to `FixedResolutionViewport`
+ - Add a few missing helpers to SpriteAnimation
 
 ## [1.0.0-releasecandidate.17]
  - Added `StandardEffectController` class

packages/flame/lib/src/sprite_animation.dart

@@ -256,6 +256,14 @@ class SpriteAnimation {
     _done = false;
   }
 
+  /// Sets this animation to be on the last frame.
+  void setToLast() {
+    currentIndex = frames.length - 1;
+    clock = frames[currentIndex].stepTime;
+    elapsed = totalDuration();
+    update(0);
+  }
+
   /// Gets the current [Sprite] that should be shown.
   ///
   /// In case it reaches the end:
@@ -294,6 +302,11 @@ class SpriteAnimation {
     }
   }
 
+  /// Returns a new Animation equal to this one in definition, but each copy can be run independently.
+  SpriteAnimation clone() {
+    return SpriteAnimation(frames.toList(), loop: loop);
+  }
+
   /// Returns a new Animation based on this animation, but with its frames in reversed order
   SpriteAnimation reversed() {
     return SpriteAnimation(frames.reversed.toList(), loop: loop);

packages/flame/test/components/sprite_animation_component_test.dart

@@ -6,6 +6,48 @@ void main() async {
   // Generate an image
   final image = await generateImage();
 
+  group('SpriteAnimationComponent clone and reversed', () {
+    test(
+      'clone creates independent copy',
+      () {
+        final animation = SpriteAnimation.spriteList(
+          List.filled(5, Sprite(image)),
+          stepTime: 0.1,
+          loop: false,
+        );
+        final copy = animation.clone();
+        expect(copy.loop, animation.loop);
+
+        animation.update(0.1);
+        expect(animation.currentIndex, 1);
+        expect(copy.currentIndex, 0);
+
+        copy.update(0.2);
+        expect(animation.currentIndex, 1);
+        expect(copy.currentIndex, 2);
+      },
+    );
+    test(
+      'reversed creates independent copy',
+      () {
+        final animation = SpriteAnimation.spriteList(
+          List.filled(5, Sprite(image)),
+          stepTime: 0.1,
+          loop: false,
+        );
+        final copy = animation.reversed();
+        expect(copy.loop, animation.loop);
+
+        animation.update(0.1);
+        expect(animation.currentIndex, 1);
+        expect(copy.currentIndex, 0);
+
+        copy.update(0.2);
+        expect(animation.currentIndex, 1);
+        expect(copy.currentIndex, 2);
+      },
+    );
+  });
   group('SpriteAnimationComponent shouldRemove', () {
     flameGame.test(
       'removeOnFinish is true and animation#loop is false',
@@ -164,6 +206,23 @@ void main() async {
   });
 
   group('SpriteAnimation timing of animation frames', () {
+    test('Can move to last frame programatically', () {
+      // Non-looping animation, with the expected total duration of 0.500 s
+      final animation = SpriteAnimation.spriteList(
+        List.filled(5, Sprite(image)),
+        stepTime: 0.1,
+        loop: false,
+      );
+      var callbackInvoked = 0;
+      animation.onComplete = () {
+        callbackInvoked++;
+      };
+      animation.setToLast();
+      expect(animation.currentIndex, 4);
+      expect(animation.elapsed, 0.5);
+      expect(animation.done(), true);
+      expect(callbackInvoked, 1);
+    });
     // See https://github.com/flame-engine/flame/issues/895
     flameGame.test('Last animation frame is not skipped', (game) async {
       // Non-looping animation, with the expected total duration of 0.500 s