feat: Add pause and resume to HasTimeScale mixin (#3216)

This PR just adds 2 simple method to easily pause and resume the time
scaled component.

doc/flame/other/util.md

@@ -157,11 +157,17 @@ To make this manipulation easier, Flame provides a `HasTimeScale` mixin. This mi
 to any Flame `Component` and exposes a simple get/set API for `timeScale`. The default value of
 `timeScale` is `1`, implying in-game time of the component is running at the same speed as real life
 time. Setting it to `2` will make the component tick twice as fast and setting it to `0.5` will make
-it tick at half the speed as compared to real life time.
+it tick at half the speed as compared to real life time. This mixin also provides `pause` and `resume`
+methods, which can be used instead of manually setting the timeScale to 0 and 1 respectively.
 
 Since `FlameGame` is a `Component` too, this mixin can be attached to the `FlameGame` as well. Doing
 so will allow controlling time scale for all the component of the game from a single place.
 
+```{note}
+HasTimeScale cannot control the movement of BodyComponent from flame_forge2d individually.
+It is only useful if the whole Game or Forge2DWorld is to be time scaled.
+```
+
 ```{flutter-app}
 :sources: ../flame/examples
 :page: time_scale

packages/flame/lib/src/components/mixins/has_time_scale.dart

@@ -1,7 +1,7 @@
 import 'package:flame/src/components/core/component.dart';
 
 /// This mixin allows components to control their speed as compared to the
-/// normal speed. Only framerate independent logic will benefit [timeScale]
+/// normal speed. Only framerate independent logic will benefit from [timeScale]
 /// changes.
 ///
 /// Note: Modified [timeScale] will be applied to all children as well.
@@ -34,4 +34,17 @@ mixin HasTimeScale on Component {
   void updateTree(double dt) {
     super.updateTree(dt * (parent != null ? _timeScale : 1.0));
   }
+
+  /// Pauses the component by setting the time scale to 0.0.
+  void pause() {
+    timeScale = 0.0;
+  }
+
+  /// Resumes the component by setting the time scale to 1.0 or to the given
+  /// value.
+  void resume({double? newTimeScale}) {
+    if (timeScale == 0.0) {
+      timeScale = newTimeScale ?? 1.0;
+    }
+  }
 }

packages/flame/test/components/mixins/has_time_scale_test.dart

@@ -85,6 +85,63 @@ void main() {
         );
       },
     );
+
+    testWithGame(
+      'pausing and resuming',
+      _GameWithTimeScale.new,
+      (game) async {
+        final component = _MovingComponent();
+        await game.add(component);
+        await game.ready();
+        const stepTime = 10.0;
+        var distance = 0.0;
+        final offset = stepTime * component.speed;
+
+        game.pause();
+        distance = component.x;
+        game.update(stepTime);
+        expect(component.x, distance);
+
+        game.resume();
+        distance = component.x;
+        game.update(stepTime);
+        expect(component.x, distance + offset);
+
+        game.pause();
+        distance = component.x;
+        game.update(stepTime);
+        expect(component.x, distance);
+
+        game.resume(newTimeScale: 0.5);
+        distance = component.x;
+        game.update(stepTime);
+        expect(component.x, distance + 0.5 * offset);
+      },
+    );
+
+    testWithGame(
+      'resume does not modify timeScale if not paused',
+      _GameWithTimeScale.new,
+      (game) async {
+        final component = _MovingComponent();
+        await game.add(component);
+        await game.ready();
+        const stepTime = 10.0;
+        var distance = 0.0;
+        final offset = stepTime * component.speed;
+
+        game.pause();
+        distance = component.x;
+        game.update(stepTime);
+        expect(component.x, distance + game.timeScale * offset);
+
+        game.timeScale = 0.5;
+        game.resume();
+        distance = component.x;
+        game.update(stepTime);
+        expect(component.x, distance + game.timeScale * offset);
+      },
+    );
   });
 }