fix: Issue #2889, Klondike Step5, incorrect animation of the deal. (#2893)

When the cards are dealt at the start of a Klondike Step 5 game there
are multiple occurrences of unrealistic behaviors:

- Several cards being dealt may come from the middle of the Stock Pile,
- Cards that are dealt early can be seen moving in front of cards that
are dealt later.

Each card dealt should be rendered on the top of the Stock Pile and
should be seen to come from there. During the deal, later cards dealt
are placed on top of earlier ones, so later cards should be seen to move
in front of earlier ones when they are travelling from the Stock Pile to
their positions in the layout.

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

doc/tutorials/klondike/app/lib/step5/components/card.dart

@@ -359,20 +359,18 @@ class Card extends PositionComponent
     Vector2 to, {
     double speed = 10.0,
     double start = 0.0,
+    int startPriority = 100,
     Curve curve = Curves.easeOutQuad,
     VoidCallback? onComplete,
-    bool bumpPriority = true,
   }) {
     assert(speed > 0.0, 'Speed must be > 0 widths per second');
     final dt = (to - position).length / (speed * size.x);
     assert(dt > 0, 'Distance to move must be > 0');
-    if (bumpPriority) {
-      priority = 100;
-    }
     add(
-      MoveToEffect(
+      CardMoveEffect(
         to,
         EffectController(duration: dt, startDelay: start, curve: curve),
+        transitPriority: startPriority,
         onComplete: () {
           onComplete?.call();
         },
@@ -443,3 +441,20 @@ class Card extends PositionComponent
 
   //#endregion
 }
+
+class CardMoveEffect extends MoveToEffect {
+  CardMoveEffect(
+    super.destination,
+    super.controller, {
+    super.onComplete,
+    this.transitPriority = 100,
+  });
+
+  final int transitPriority;
+
+  @override
+  void onStart() {
+    super.onStart(); // Flame connects MoveToEffect to EffectController.
+    parent?.priority = transitPriority;
+  }
+}

doc/tutorials/klondike/app/lib/step5/components/tableau_pile.dart

@@ -75,7 +75,7 @@ class TableauPile extends PositionComponent implements Pile {
       _cards.add(card);
       card.doMove(
         nextPosition,
-        bumpPriority: false, // Priorities have been set: don't change them.
+        startPriority: card.priority,
         onComplete: () {
           nCardsToMove--;
           if (nCardsToMove == 0) {

doc/tutorials/klondike/app/lib/step5/klondike_world.dart

@@ -114,6 +114,13 @@ class KlondikeWorld extends World with HasGameReference<KlondikeGame> {
     // For the "Same deal" option, re-use the previous seed, else use a new one.
     cards.shuffle(Random(game.seed));
 
+    // Each card dealt must be seen to come from the top of the deck!
+    var dealPriority = 1;
+    for (final card in cards) {
+      card.priority = dealPriority++;
+    }
+
+    // Change priority as cards take off: so later cards fly above earlier ones.
     var cardToDeal = cards.length - 1;
     var nMovingCards = 0;
     for (var i = 0; i < 7; i++) {
@@ -121,7 +128,9 @@ class KlondikeWorld extends World with HasGameReference<KlondikeGame> {
         final card = cards[cardToDeal--];
         card.doMove(
           tableauPiles[j].position,
+          speed: 15.0,
           start: nMovingCards * 0.15,
+          startPriority: 100 + nMovingCards,
           onComplete: () {
             tableauPiles[j].acquireCard(card);
             nMovingCards--;