feat: Add isFirstFrame and onStart event to SpriteAnimation

packages/flame/lib/src/sprite_animation.dart

@@ -230,12 +230,21 @@ class SpriteAnimation {
   /// to the first, or keeps returning the last when done.
   bool loop = true;
 
+  /// Registered method to be triggered when the animation starts.
+  void Function()? onStart;
+
+  /// Registered method to be triggered when the animation frame updates.
+  void Function(int currentIndex)? onFrame;
+
   /// Registered method to be triggered when the animation complete.
   void Function()? onComplete;
 
   /// The current frame that should be displayed.
   SpriteAnimationFrame get currentFrame => frames[currentIndex];
 
+  /// Returns whether the animation is on the first frame.
+  bool get isFirstFrame => currentIndex == 0;
+
   /// Returns whether the animation is on the last frame.
   bool get isLastFrame => currentIndex == frames.length - 1;
 
@@ -265,6 +274,7 @@ class SpriteAnimation {
     elapsed = 0.0;
     currentIndex = 0;
     _done = false;
+    _started = false;
   }
 
   /// Sets this animation to be on the last frame.
@@ -291,6 +301,10 @@ class SpriteAnimation {
   bool _done = false;
   bool done() => _done;
 
+  /// Local flag to determine if the animation has started to prevent multiple
+  /// calls to [onStart].
+  bool _started = false;
+
   /// Updates this animation, ticking the lifeTime by an amount [dt]
   /// (in seconds).
   void update(double dt) {
@@ -299,7 +313,12 @@ class SpriteAnimation {
     if (_done) {
       return;
     }
+    if (!_started) {
+      onStart?.call();
+      _started = true;
+    }
     while (clock >= currentFrame.stepTime) {
+      onFrame?.call(currentIndex);
       if (isLastFrame) {
         if (loop) {
           clock -= currentFrame.stepTime;

packages/flame/test/sprite_animation_test.dart

@@ -41,6 +41,40 @@ void main() {
       );
     });
 
+    test('onStart called for single-frame animation', () {
+      var counter = 0;
+      final sprite = MockSprite();
+      final animation =
+          SpriteAnimation.spriteList([sprite], stepTime: 1, loop: false)
+            ..onStart = () => counter++;
+      expect(counter, 0);
+      animation.update(0.5);
+      expect(counter, 1);
+      animation.update(1);
+      expect(counter, 1);
+    });
+
+    test('onFrame called for a multi-frame animation', () {
+      var counter = 0;
+      var i = 0;
+      const animationLength = 3;
+      final sprite = MockSprite();
+      final animation = SpriteAnimation.spriteList(
+        [sprite, sprite, sprite],
+        stepTime: 1,
+        loop: false,
+      );
+      animation.onFrame = (index) {
+        counter++;
+      };
+      for (i = 0; i <= animationLength; i++) {
+        expect(counter, i);
+        animation.update(1);
+      }
+      expect(counter, 3);
+      expect(i, 4);
+    });
+
     test('onComplete called for single-frame animation', () {
       var counter = 0;
       final sprite = MockSprite();
@@ -55,6 +89,42 @@ void main() {
       animation.update(1);
       expect(counter, 1);
     });
+
+    test('test sequence of event lifecycle for an animation', () {
+      var animationStarted = false;
+      var animationRunning = false;
+      var animationComplete = false;
+      final sprite = MockSprite();
+      final animation =
+          SpriteAnimation.spriteList([sprite], stepTime: 1, loop: false);
+      animation.onStart = () {
+        expect(animationStarted, false);
+        expect(animationRunning, false);
+        expect(animationComplete, false);
+        animationStarted = true;
+      };
+      animation.onFrame = (index) {
+        if (index == 0) {
+          expect(animationStarted, true);
+          expect(animationRunning, false);
+          expect(animationComplete, false);
+        }
+        if (index == 1) {
+          expect(animationStarted, true);
+          expect(animationRunning, true);
+          expect(animationComplete, false);
+        }
+        animationRunning = true;
+      };
+      animation.onComplete = () {
+        expect(animationStarted, true);
+        expect(animationRunning, true);
+        expect(animationComplete, false);
+        animationComplete = true;
+      };
+      animation.update(1);
+      expect(animationComplete, true);
+    });
   });
 }