feat: Adding tickOnLoad to TimerComponent (#3285)

Adds a `tickOnLoad` method to `TimerComponent`.

---------

Co-authored-by: Lukas Klingsbo <me@lukas.fyi>

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

@@ -1,13 +1,16 @@
+import 'dart:async';
 import 'dart:ui';
 
 import 'package:flame/components.dart';
+import 'package:meta/meta.dart';
 
 /// A component that uses a [Timer] instance which you can react to when it has
 /// finished.
 class TimerComponent extends Component {
   late final Timer timer;
   final bool removeOnFinish;
   final VoidCallback? _onTick;
+  final bool tickWhenLoaded;
 
   /// Creates a [TimerComponent]
   ///
@@ -16,12 +19,15 @@ class TimerComponent extends Component {
   /// [autoStart] When true, will start upon instantiation (default is true)
   /// [onTick] When provided, will be called every time [period] is reached.
   /// This overrides the [onTick] method
+  /// [tickWhenLoaded] When true, will call [onTick] when the component is first
+  /// loaded (default is false).
   TimerComponent({
     required double period,
     bool repeat = false,
     bool autoStart = true,
     this.removeOnFinish = false,
     VoidCallback? onTick,
+    this.tickWhenLoaded = false,
     super.key,
   }) : _onTick = onTick {
     timer = Timer(
@@ -32,6 +38,16 @@ class TimerComponent extends Component {
     );
   }
 
+  @override
+  @mustCallSuper
+  FutureOr<void> onLoad() async {
+    await super.onLoad();
+
+    if (tickWhenLoaded) {
+      onTick();
+    }
+  }
+
   /// Called every time the [timer] reached a tick.
   /// The default implementation calls the closure received on the
   /// constructor and can be overridden to add custom logic.

packages/flame/test/components/timer_component_test.dart

@@ -18,6 +18,23 @@ class _MyTimerComponent extends TimerComponent {
   }
 }
 
+class _MyTickOnLoadTimerComponent extends TimerComponent {
+  int count = 0;
+
+  _MyTickOnLoadTimerComponent()
+      : super(
+          period: 1,
+          repeat: true,
+          removeOnFinish: false,
+          tickWhenLoaded: true,
+        );
+
+  @override
+  void onTick() {
+    count++;
+  }
+}
+
 class _NonRepeatingTimerComponent extends TimerComponent {
   _NonRepeatingTimerComponent()
       : super(
@@ -32,6 +49,7 @@ void main() {
     testWithFlameGame('runs the tick method', (game) async {
       final timer = _MyTimerComponent();
       game.add(timer);
+      await game.ready();
       game.update(0);
 
       game.update(1.2);
@@ -44,6 +62,7 @@ void main() {
         (game) async {
       final world = game.world;
       world.add(_MyTimerComponent());
+      await game.ready();
       game.update(0);
 
       game.update(1.2);
@@ -74,10 +93,28 @@ void main() {
           },
         ),
       );
+      await game.ready();
       game.update(0);
       game.update(1.2);
 
       expect(called, isTrue);
     });
+
+    testWithFlameGame(
+      'runs the tick method on load when tickWhenLoaded is true',
+      (game) async {
+        final timer = _MyTickOnLoadTimerComponent();
+        game.add(timer);
+        await game.ready();
+        expect(timer.count, equals(1));
+
+        game.update(0);
+
+        game.update(1.2);
+
+        game.update(0);
+        expect(timer.count, equals(2));
+      },
+    );
   });
 }