Merge branch 'wl-CG-0MM1OOEZH182AHBG-flip-card-animation' into main

Author: rgardler-msft

example-games/golf/scenes/GolfScene.ts

@@ -29,6 +29,7 @@ import {
   dismissOverlay,
   createSceneTitle, createSceneMenuButton,
   PhaseManager,
+  flipCard,
 } from '../../../src/ui';
 import type { HelpSection } from '../../../src/ui';
 import helpContent from '../help-content.json';
@@ -1024,28 +1025,15 @@ export class GolfScene extends CardGameScene {
       sprite.setDepth(10);
 
       // 1. Grid card: flip (reveal face) + translate to discard pile
-      //    First half: scaleX → 0 while moving halfway to discard
-      this.tweens.add({
-        targets: sprite,
-        scaleX: 0,
-        x: (sprite.x + discardPos.x) / 2,
-        y: (sprite.y + discardPos.y) / 2,
-        duration: SWAP_ANIM_DURATION / 2,
-        ease: 'Power2',
-        onComplete: () => {
-          // Reveal the card's actual face at the midpoint of the flip
-          sprite.setTexture(getCardTexture(grid[idx]));
-          // Second half: scaleX → 1 while completing movement to discard
-          this.tweens.add({
-            targets: sprite,
-            scaleX: 1,
-            x: discardPos.x,
-            y: discardPos.y,
-            duration: SWAP_ANIM_DURATION / 2,
-            ease: 'Power2',
-            onComplete: checkDone,
-          });
-        },
+      flipCard({
+        scene: this,
+        target: sprite,
+        newTexture: getCardTexture(grid[idx]),
+        duration: SWAP_ANIM_DURATION,
+        easeClose: 'Power2',
+        destX: discardPos.x,
+        destY: discardPos.y,
+        onComplete: checkDone,
       });
 
       // 2. Drawn card: translate from display position to vacated grid slot
@@ -1076,21 +1064,13 @@ export class GolfScene extends CardGameScene {
         this.hideDrawnCard();
 
         // Phase 2: flip the grid card in place
-        this.tweens.add({
-          targets: sprite,
-          scaleX: 0,
-          duration: SWAP_ANIM_DURATION / 4,
-          ease: 'Power2',
-          onComplete: () => {
-            sprite.setTexture(getCardTexture(grid[idx]));
-            this.tweens.add({
-              targets: sprite,
-              scaleX: 1,
-              duration: SWAP_ANIM_DURATION / 4,
-              ease: 'Power2',
-              onComplete: onComplete, // Skip wrappedOnComplete; drawn card already hidden
-            });
-          },
+        flipCard({
+          scene: this,
+          target: sprite,
+          newTexture: getCardTexture(grid[idx]),
+          duration: SWAP_ANIM_DURATION / 2,
+          easeClose: 'Power2',
+          onComplete: onComplete, // Skip wrappedOnComplete; drawn card already hidden
         });
       };
 
@@ -1128,30 +1108,16 @@ export class GolfScene extends CardGameScene {
       this.drawnCardSprite = this.add.image(startX, startY, 'card_back');
       this.drawnCardSprite.setDepth(15);
 
-      // First half: move halfway + flip (scaleX → 0)
-      this.tweens.add({
-        targets: this.drawnCardSprite,
-        x: (startX + destX) / 2,
-        y: (startY + destY) / 2,
-        scaleX: 0,
-        duration: ANIM_DURATION / 2,
-        ease: 'Power2',
+      flipCard({
+        scene: this,
+        target: this.drawnCardSprite,
+        newTexture: faceTexture,
+        duration: ANIM_DURATION,
+        easeClose: 'Power2',
+        destX,
+        destY,
         onComplete: () => {
-          if (!this.drawnCardSprite) return;
-          // Reveal face at midpoint
-          this.drawnCardSprite.setTexture(faceTexture);
-          // Second half: complete move + flip back (scaleX → 1)
-          this.tweens.add({
-            targets: this.drawnCardSprite,
-            x: destX,
-            y: destY,
-            scaleX: 1,
-            duration: ANIM_DURATION / 2,
-            ease: 'Power2',
-            onComplete: () => {
-              if (this.drawnCardSprite) this.drawnCardSprite.setDepth(0);
-            },
-          });
+          if (this.drawnCardSprite) this.drawnCardSprite.setDepth(0);
         },
       });
     } else {

example-games/the-mind/scenes/TheMindScene.ts

@@ -43,6 +43,7 @@ import {
   dismissOverlay,
   createSceneHeader,
   layoutCardPositions,
+  flipCard,
 } from '../../../src/ui';
 import type { HelpSection } from '../../../src/ui';
 import helpContent from '../help-content.json';
@@ -960,9 +961,8 @@ export class TheMindScene extends CardGameScene {
         .setDepth(DEPTH_PLAYED_CARD);
 
       const faceUpTex = getMindCardTexture({ value: cardValue, faceUp: true });
-      const halfDuration = ANIM_DURATION / 2;
 
-      // Tween to pile position; flip to face-up at the midpoint
+      // Tween to pile position (translation runs in parallel with flip)
       this.tweens.add({
         targets: tempSprite,
         x: PILE_X,
@@ -972,20 +972,15 @@ export class TheMindScene extends CardGameScene {
       });
 
       // Midpoint flip: scale X to 0 then back to 1 with the face-up texture
-      this.tweens.add({
-        targets: tempSprite,
-        scaleX: 0,
-        duration: halfDuration,
-        ease: 'Cubic.easeIn',
-        onComplete: () => {
-          tempSprite.setTexture(faceUpTex);
+      flipCard({
+        scene: this,
+        target: tempSprite,
+        newTexture: faceUpTex,
+        duration: ANIM_DURATION,
+        easeClose: 'Cubic.easeIn',
+        easeOpen: 'Cubic.easeOut',
+        onMidpoint: () => {
           tempSprite.setDisplaySize(CARD_W, CARD_H);
-          this.tweens.add({
-            targets: tempSprite,
-            scaleX: 1,
-            duration: halfDuration,
-            ease: 'Cubic.easeOut',
-          });
         },
       });
 

src/ui/flipCard.ts

@@ -0,0 +1,134 @@
+/**
+ * flipCard – reusable two-phase card-flip animation helper.
+ *
+ * Performs the classic "scaleX → 0 → change texture → scaleX → 1" card flip.
+ * Optionally translates the sprite to a destination during the flip.
+ *
+ * @module ui/flipCard
+ */
+
+/** Options for the {@link flipCard} animation. */
+export interface FlipCardOptions {
+  /** The Phaser scene that owns the tween timeline. */
+  scene: Phaser.Scene;
+
+  /**
+   * The sprite (or Image) to flip.
+   * Must support `setTexture()` and be a valid Phaser tween target.
+   */
+  target: Phaser.GameObjects.Image | Phaser.GameObjects.Sprite;
+
+  /** The texture key to apply at the midpoint of the flip. */
+  newTexture: string;
+
+  /**
+   * Total duration of the flip in milliseconds.
+   * Each half (close + open) takes `duration / 2`.
+   * @default 300
+   */
+  duration?: number;
+
+  /**
+   * Easing for the first half (scaleX → 0).
+   * @default 'Power2'
+   */
+  easeClose?: string;
+
+  /**
+   * Easing for the second half (scaleX → 1).
+   * Defaults to the value of `easeClose` for symmetric easing.
+   */
+  easeOpen?: string;
+
+  /**
+   * Optional destination to translate to during the flip.
+   * When set, the sprite moves to `(destX, destY)` over both halves:
+   * halfway during close, the rest during open.
+   */
+  destX?: number;
+
+  /**
+   * Optional destination Y.  Required if `destX` is provided.
+   */
+  destY?: number;
+
+  /**
+   * Called at the midpoint of the flip, immediately after the new texture
+   * is applied.  Use this for side effects such as `setDisplaySize()`.
+   */
+  onMidpoint?: () => void;
+
+  /**
+   * Called after the full flip animation completes (end of the open phase).
+   */
+  onComplete?: () => void;
+}
+
+/**
+ * Play a two-phase card-flip animation on a sprite.
+ *
+ * Phase 1 (close): scaleX tweens from current value to 0.
+ * At the midpoint the texture is swapped and `onMidpoint` fires.
+ * Phase 2 (open): scaleX tweens from 0 back to 1.
+ *
+ * If `destX`/`destY` are provided the sprite also translates — halfway
+ * during phase 1 and the rest during phase 2 — so the flip and slide
+ * are combined into a single smooth motion.
+ *
+ * @returns The phase-1 tween so the caller can cancel/chain if needed.
+ */
+export function flipCard(opts: FlipCardOptions): Phaser.Tweens.Tween {
+  const {
+    scene,
+    target,
+    newTexture,
+    duration = 300,
+    easeClose = 'Power2',
+    easeOpen = easeClose,
+    destX,
+    destY,
+    onMidpoint,
+    onComplete,
+  } = opts;
+
+  const half = duration / 2;
+
+  // Build the close-phase tween config
+  const closeConfig: Phaser.Types.Tweens.TweenBuilderConfig = {
+    targets: target,
+    scaleX: 0,
+    duration: half,
+    ease: easeClose,
+    onComplete: () => {
+      target.setTexture(newTexture);
+      onMidpoint?.();
+
+      // Build the open-phase tween config
+      const openConfig: Phaser.Types.Tweens.TweenBuilderConfig = {
+        targets: target,
+        scaleX: 1,
+        duration: half,
+        ease: easeOpen,
+        onComplete: onComplete ? () => onComplete() : undefined,
+      };
+
+      // Add translation for the second half if destination was provided
+      if (destX !== undefined && destY !== undefined) {
+        openConfig.x = destX;
+        openConfig.y = destY;
+      }
+
+      scene.tweens.add(openConfig);
+    },
+  };
+
+  // Add translation for the first half (to the midpoint position)
+  if (destX !== undefined && destY !== undefined) {
+    const startX = (target as Phaser.GameObjects.Image).x;
+    const startY = (target as Phaser.GameObjects.Image).y;
+    closeConfig.x = (startX + destX) / 2;
+    closeConfig.y = (startY + destY) / 2;
+  }
+
+  return scene.tweens.add(closeConfig);
+}

src/ui/index.ts

@@ -13,6 +13,10 @@ export { CardGameScene } from './CardGameScene';
 export { PhaseManager } from './PhaseManager';
 export type { PhaseManagerConfig } from './PhaseManager';
 
+// Card flip animation
+export { flipCard } from './flipCard';
+export type { FlipCardOptions } from './flipCard';
+
 // Card layout helpers
 export { layoutCardPositions } from './layoutCardPositions';
 export type {