From a31486fc300e3875d3ff9eed3c4122c65a46c336 Mon Sep 17 00:00:00 2001
From: Ian Wadham <32025779+IanWadham@users.noreply.github.com>
Date: Sat, 2 Dec 2023 20:19:06 +1100
Subject: [PATCH] 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>
---
 .../app/lib/step5/components/card.dart        | 25 +++++++++++++++----
 .../lib/step5/components/tableau_pile.dart    |  2 +-
 .../app/lib/step5/klondike_world.dart         |  9 +++++++
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/doc/tutorials/klondike/app/lib/step5/components/card.dart b/doc/tutorials/klondike/app/lib/step5/components/card.dart
index 5ffbfeb70..b68049828 100644
--- a/doc/tutorials/klondike/app/lib/step5/components/card.dart
+++ b/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;
+  }
+}
diff --git a/doc/tutorials/klondike/app/lib/step5/components/tableau_pile.dart b/doc/tutorials/klondike/app/lib/step5/components/tableau_pile.dart
index ab7e38a5c..100d91ea6 100644
--- a/doc/tutorials/klondike/app/lib/step5/components/tableau_pile.dart
+++ b/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) {
diff --git a/doc/tutorials/klondike/app/lib/step5/klondike_world.dart b/doc/tutorials/klondike/app/lib/step5/klondike_world.dart
index 51b45a4a3..3f13bf8fd 100644
--- a/doc/tutorials/klondike/app/lib/step5/klondike_world.dart
+++ b/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--;