feat(effects)!: Added SequenceEffect (#1218)

Added SequenceEffect, which performs a series of other effects.

The biggest challenge in implementing this feature came from the need to run the sequence in reverse, due to the alternate flag. This required that every effect and every controller supported running "back in time", which is not as simple as it sounds.

The following breaking changes were introduced:

    The Effect class no longer supports .reverse() method and .isReversed flag.

    This flag was added only 2 weeks ago (

Effect controllers restructuring #1134), with the idea that it will be necessary for the SequenceEffect. However, as it turned out, this flag is not as helpful as I thought it would be. In fact, given the user's ability to change it any point, it makes the implementation very error-prone.

To be clear, the ability for each effect to run in reverse remains -- only now it can no longer be triggered by the user manually. Instead, SequenceEffect triggers that ability itself at the alternation point. If there is demand in the future to manually force any effect to run backwards, we could restore this flag, but this would require thorough testing to make it work correctly.

Infinite effects now return duration = double.infinity instead of null, which seems more appropriate.

examples/lib/stories/effects/sequence_effect_example.dart

@@ -0,0 +1,63 @@
+import 'dart:ui';
+
+import 'package:flame/components.dart';
+import 'package:flame/effects.dart';
+import 'package:flame/game.dart';
+
+class SequenceEffectExample extends FlameGame {
+  static const String description = '''
+    Sequence of effects, consisting of a move effect, a rotate effect, another
+    move effect, a scale effect, and then one more move effect. The sequence
+    then runs in the opposite order (alternate = true) and loops infinitely
+    (infinite = true).
+  ''';
+
+  @override
+  Future<void> onLoad() async {
+    super.onLoad();
+    const tau = Transform2D.tau;
+    EffectController duration(double x) => EffectController(duration: x);
+    add(
+      Player()
+        ..position = Vector2(200, 300)
+        ..add(
+          SequenceEffect(
+            [
+              MoveEffect.to(Vector2(400, 300), duration(0.7)),
+              RotateEffect.by(tau / 4, duration(0.5)),
+              MoveEffect.to(Vector2(400, 400), duration(0.7)),
+              ScaleEffect.by(Vector2.all(1.5), duration(0.7)),
+              MoveEffect.to(Vector2(400, 500), duration(0.7)),
+            ],
+            alternate: true,
+            infinite: true,
+          ),
+        ),
+    );
+  }
+}
+
+class Player extends PositionComponent {
+  Player()
+      : path = Path()
+          ..lineTo(40, 20)
+          ..lineTo(0, 40)
+          ..quadraticBezierTo(8, 20, 0, 0)
+          ..close(),
+        bodyPaint = Paint()..color = const Color(0x887F99B3),
+        borderPaint = Paint()
+          ..style = PaintingStyle.stroke
+          ..strokeWidth = 3
+          ..color = const Color(0xFFFFFD9A),
+        super(anchor: Anchor.center, size: Vector2(40, 40));
+
+  final Path path;
+  final Paint borderPaint;
+  final Paint bodyPaint;
+
+  @override
+  void render(Canvas canvas) {
+    canvas.drawPath(path, bodyPaint);
+    canvas.drawPath(path, borderPaint);
+  }
+}