feat: add TextBoxComponent::resetAnimation

Enables resetting of the typewriter animation of the TextBoxComponent.
Useful for changing lines without having to re-insert the component into
the scene node, which causes undesired flashing.

Author: Wilhansen

packages/flame/lib/src/components/text_box_component.dart

@@ -408,4 +408,15 @@ class TextBoxComponent<T extends TextRenderer> extends TextComponent {
   void skip() {
     boxConfig = boxConfig.copyWith(timePerChar: 0);
   }
+
+  /// Rewind the typewriter effect to start from the first character again.
+  ///
+  /// Useful for reusing this component when changing lines so that the next
+  /// line does not show immediately.
+  /// Also resets the [onComplete] call state which will be called again
+  /// when the line is finished.
+  void resetAnimation() {
+    _lifeTime = 0;
+    _isOnCompleteExecuted = false;
+  }
 }

packages/flame/test/components/text_box_component_test.dart

@@ -219,6 +219,35 @@ lines.''',
       expect(textBoxComponent2.finished, true);
     });
 
+    testWithFlameGame(
+      'TextBoxComponent resets animation to the start of text',
+      (
+        game,
+      ) async {
+        final textBoxComponent1 = TextBoxComponent(
+          text: 'aaa',
+          boxConfig: const TextBoxConfig(timePerChar: 1.0),
+        );
+        await game.ensureAdd(textBoxComponent1);
+        // forward time by 2.5 seconds
+        game.update(2.5);
+        expect(textBoxComponent1.finished, false);
+        // flush
+        game.update(0.6);
+        expect(textBoxComponent1.finished, true);
+        // reset animation
+        textBoxComponent1.resetAnimation();
+        // 'finished' state should reset immediately
+        expect(textBoxComponent1.finished, false);
+        expect(textBoxComponent1.currentChar, 0);
+        expect(textBoxComponent1.currentLine, 0);
+        game.update(2.5);
+        expect(textBoxComponent1.finished, false);
+        game.update(0.6);
+        expect(textBoxComponent1.finished, true);
+      },
+    );
+
     testGolden(
       'Alignment options',
       (game, tester) async {