Merge wl-CG-0MLU86JTG1OXPMDW: Extract card texture helpers and shared constants to src/ui/

Author: rgardler-msft

example-games/beleaguered-castle/scenes/BeleagueredCastleScene.ts

@@ -14,7 +14,7 @@
  */
 
 import Phaser from 'phaser';
-import type { Rank, Suit } from '../../../src/card-system/Card';
+import type { Suit } from '../../../src/card-system/Card';
 import type { BeleagueredCastleState, BCMove } from '../BeleagueredCastleState';
 import { FOUNDATION_COUNT, TABLEAU_COUNT, FOUNDATION_SUITS } from '../BeleagueredCastleState';
 import {
@@ -34,19 +34,18 @@ import type { Command } from '../../../src/core-engine/UndoRedoManager';
 import { UndoRedoManager, CompoundCommand } from '../../../src/core-engine/UndoRedoManager';
 import { BCTranscriptRecorder } from '../GameTranscript';
 import type { BCGameTranscript } from '../GameTranscript';
-import { HelpPanel, HelpButton } from '../../../src/ui';
+import {
+  HelpPanel, HelpButton,
+  CARD_W, CARD_H, GAME_W, GAME_H, FONT_FAMILY,
+  cardTextureKey, preloadCardAssets,
+} from '../../../src/ui';
 import type { HelpSection } from '../../../src/ui';
 import helpContent from '../help-content.json';
 
 // ── Constants ───────────────────────────────────────────────
 
-const CARD_W = 48;
-const CARD_H = 65;
 const CARD_GAP = 6;
 
-const GAME_W = 800;
-const GAME_H = 600;
-
 const ANIM_DURATION = 300; // ms per card deal animation
 const DEAL_STAGGER = 40; // ms between successive card deal tweens
 const SNAP_BACK_DURATION = 200; // ms to snap card back on invalid drop
@@ -65,8 +64,6 @@ const TABLEAU_TOP_Y = 135;
 /** Z-depth for a card being dragged. */
 const DRAG_DEPTH = 1000;
 
-const FONT_FAMILY = 'Arial, sans-serif';
-
 // ── Suit symbol mapping for foundation labels ───────────────
 
 const SUIT_SYMBOL: Record<Suit, string> = {
@@ -235,28 +232,7 @@ export class BeleagueredCastleScene extends Phaser.Scene {
   // ── Preload ─────────────────────────────────────────────
 
   preload(): void {
-    // Load card back
-    this.load.svg('card_back', 'assets/cards/card_back.svg', {
-      width: CARD_W,
-      height: CARD_H,
-    });
-
-    // Load all 52 card faces
-    const suits: Suit[] = ['clubs', 'diamonds', 'hearts', 'spades'];
-    const ranks: Rank[] = [
-      'A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K',
-    ];
-
-    for (const suit of suits) {
-      for (const rank of ranks) {
-        const key = this.cardTextureKey(rank, suit);
-        const fileName = this.cardFileName(rank, suit);
-        this.load.svg(key, `assets/cards/${fileName}`, {
-          width: CARD_W,
-          height: CARD_H,
-        });
-      }
-    }
+    preloadCardAssets(this);
   }
 
   // ── Create ──────────────────────────────────────────────
@@ -1282,7 +1258,7 @@ export class BeleagueredCastleScene extends Phaser.Scene {
       const topCard = foundation.peek();
 
       if (topCard) {
-        const texture = this.cardTextureKey(topCard.rank, topCard.suit);
+        const texture = cardTextureKey(topCard.rank, topCard.suit);
         this.foundationSprites[i].setTexture(texture).setVisible(true);
       } else {
         this.foundationSprites[i].setVisible(false);
@@ -1342,7 +1318,7 @@ export class BeleagueredCastleScene extends Phaser.Scene {
         const card = cards[row];
         const targetX = this.tableauColumnX(col);
         const targetY = this.tableauCardY(row);
-        const texture = this.cardTextureKey(card.rank, card.suit);
+        const texture = cardTextureKey(card.rank, card.suit);
 
         // Create the sprite at the deal origin (center), invisible initially
         const sprite = this.add
@@ -1465,7 +1441,7 @@ export class BeleagueredCastleScene extends Phaser.Scene {
         const card = cards[row];
         const x = this.tableauColumnX(col);
         const y = this.tableauCardY(row);
-        const texture = this.cardTextureKey(card.rank, card.suit);
+        const texture = cardTextureKey(card.rank, card.suit);
 
         const sprite = this.add
           .image(x, y, texture)
@@ -1524,27 +1500,6 @@ export class BeleagueredCastleScene extends Phaser.Scene {
     }
   }
 
-  // ── Texture helpers ─────────────────────────────────────
-
-  private cardTextureKey(rank: Rank, suit: Suit): string {
-    const rankName = this.rankFileName(rank);
-    return `${rankName}_of_${suit}`;
-  }
-
-  private cardFileName(rank: Rank, suit: Suit): string {
-    return `${this.rankFileName(rank)}_of_${suit}.svg`;
-  }
-
-  private rankFileName(rank: Rank): string {
-    switch (rank) {
-      case 'A': return 'ace';
-      case 'J': return 'jack';
-      case 'Q': return 'queen';
-      case 'K': return 'king';
-      default: return rank; // 2-10
-    }
-  }
-
   // ── Accessors (for tests and future features) ──────────
 
   /** Get the current game state. */

example-games/golf/scenes/GolfScene.ts

@@ -23,21 +23,20 @@ import type { GameTranscript, BoardSnapshot, CardSnapshot } from '../GameTranscr
 import { TranscriptStore } from '../../../src/core-engine/TranscriptStore';
 import { GameEventEmitter } from '../../../src/core-engine/GameEventEmitter';
 import { PhaserEventBridge } from '../../../src/core-engine/PhaserEventBridge';
-import { HelpPanel, HelpButton } from '../../../src/ui';
+import {
+  HelpPanel, HelpButton,
+  CARD_W, CARD_H, GAME_W, GAME_H, FONT_FAMILY,
+  cardTextureKey, getCardTexture, preloadCardAssets,
+} from '../../../src/ui';
 import type { HelpSection } from '../../../src/ui';
 import helpContent from '../help-content.json';
 
 // ── Constants ───────────────────────────────────────────────
 
-const CARD_W = 48;
-const CARD_H = 65;
 const CARD_GAP = 5;
 const GRID_COLS = 3;
 const GRID_ROWS = 3;
 
-const GAME_W = 800;
-const GAME_H = 600;
-
 const AI_DELAY = 600; // ms before AI chooses
 const AI_SHOW_DRAW_DELAY = 1000; // ms to show drawn card before moving
 const ANIM_DURATION = 300; // ms for animations
@@ -50,8 +49,6 @@ const PILE_Y = 295; // center Y of stock/discard
 const STOCK_X = GAME_W / 2 - 50;
 const DISCARD_X = GAME_W / 2 + 50;
 
-const FONT_FAMILY = 'Arial, sans-serif';
-
 // ── Turn state machine ──────────────────────────────────────
 
 type TurnPhase =
@@ -112,26 +109,7 @@ export class GolfScene extends Phaser.Scene {
   // ── Preload ─────────────────────────────────────────────
 
   preload(): void {
-    // Load card back
-    this.load.svg('card_back', 'assets/cards/card_back.svg', {
-      width: CARD_W,
-      height: CARD_H,
-    });
-
-    // Load all 52 card faces
-    const suits: Suit[] = ['clubs', 'diamonds', 'hearts', 'spades'];
-    const ranks: Rank[] = ['A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K'];
-
-    for (const suit of suits) {
-      for (const rank of ranks) {
-        const key = this.cardTextureKey(rank, suit);
-        const fileName = this.cardFileName(rank, suit);
-        this.load.svg(key, `assets/cards/${fileName}`, {
-          width: CARD_W,
-          height: CARD_H,
-        });
-      }
-    }
+    preloadCardAssets(this);
   }
 
   // ── Create ──────────────────────────────────────────────
@@ -424,32 +402,6 @@ export class GolfScene extends Phaser.Scene {
     };
   }
 
-  // ── Texture helpers ─────────────────────────────────────
-
-  private cardTextureKey(rank: Rank, suit: Suit): string {
-    const rankName = this.rankFileName(rank);
-    return `${rankName}_of_${suit}`;
-  }
-
-  private cardFileName(rank: Rank, suit: Suit): string {
-    return `${this.rankFileName(rank)}_of_${suit}.svg`;
-  }
-
-  private rankFileName(rank: Rank): string {
-    switch (rank) {
-      case 'A': return 'ace';
-      case 'J': return 'jack';
-      case 'Q': return 'queen';
-      case 'K': return 'king';
-      default: return rank; // 2-10
-    }
-  }
-
-  private getCardTexture(card: Card): string {
-    if (!card.faceUp) return 'card_back';
-    return this.cardTextureKey(card.rank, card.suit);
-  }
-
   // ── Refresh display ─────────────────────────────────────
 
   private refreshAll(): void {
@@ -466,7 +418,7 @@ export class GolfScene extends Phaser.Scene {
     const sprites = player === 'human' ? this.humanCardSprites : this.aiCardSprites;
 
     for (let i = 0; i < 9; i++) {
-      sprites[i].setTexture(this.getCardTexture(grid[i]));
+      sprites[i].setTexture(getCardTexture(grid[i]));
     }
   }
 
@@ -483,7 +435,7 @@ export class GolfScene extends Phaser.Scene {
     const top = this.session.shared.discardPile.peek();
     if (top) {
       this.discardSprite.setVisible(true);
-      this.discardSprite.setTexture(this.getCardTexture(top));
+      this.discardSprite.setTexture(getCardTexture(top));
     } else {
       this.discardSprite.setVisible(false);
     }
@@ -755,7 +707,7 @@ export class GolfScene extends Phaser.Scene {
         ease: 'Power2',
         onComplete: () => {
           // Reveal the card's actual face at the midpoint of the flip
-          sprite.setTexture(this.getCardTexture(grid[idx]));
+          sprite.setTexture(getCardTexture(grid[idx]));
           // Second half: scaleX → 1 while completing movement to discard
           this.tweens.add({
             targets: sprite,
@@ -803,7 +755,7 @@ export class GolfScene extends Phaser.Scene {
           duration: SWAP_ANIM_DURATION / 4,
           ease: 'Power2',
           onComplete: () => {
-            sprite.setTexture(this.getCardTexture(grid[idx]));
+            sprite.setTexture(getCardTexture(grid[idx]));
             this.tweens.add({
               targets: sprite,
               scaleX: 1,
@@ -838,7 +790,7 @@ export class GolfScene extends Phaser.Scene {
     // Show drawn card to the right of the discard pile
     const x = DISCARD_X + CARD_W + 20;
     const y = PILE_Y;
-    const texture = this.cardTextureKey(card.rank, card.suit);
+    const texture = cardTextureKey(card.rank, card.suit);
 
     this.drawnCardSprite = this.add.image(x, y, texture);
     this.drawnCardSprite.setAlpha(0);

src/ui/CardTextureHelpers.ts

@@ -0,0 +1,88 @@
+/**
+ * Card Texture Helpers
+ *
+ * Shared functions for mapping Card rank/suit values to Phaser texture keys
+ * and SVG file names. These are used by every game scene that renders
+ * standard playing cards from the `public/assets/cards/` sprite set.
+ *
+ * Also provides a convenience function to preload all 52 card face SVGs
+ * plus the card back into a Phaser scene.
+ */
+
+import type { Card, Rank, Suit } from '@card-system/Card';
+import { RANKS, SUITS } from '@card-system/Card';
+import { CARD_W, CARD_H } from './constants';
+
+/**
+ * Map a rank abbreviation to the full name used in SVG file names.
+ *
+ * - Face cards and ace: `'A'` -> `'ace'`, `'J'` -> `'jack'`, etc.
+ * - Number cards: returned as-is (`'2'` -> `'2'`, `'10'` -> `'10'`).
+ */
+export function rankFileName(rank: Rank): string {
+  switch (rank) {
+    case 'A': return 'ace';
+    case 'J': return 'jack';
+    case 'Q': return 'queen';
+    case 'K': return 'king';
+    default: return rank; // 2-10
+  }
+}
+
+/**
+ * Build the Phaser texture key for a given rank and suit.
+ *
+ * Example: `cardTextureKey('A', 'spades')` -> `'ace_of_spades'`
+ */
+export function cardTextureKey(rank: Rank, suit: Suit): string {
+  return `${rankFileName(rank)}_of_${suit}`;
+}
+
+/**
+ * Build the SVG file name (without directory) for a given rank and suit.
+ *
+ * Example: `cardFileName('A', 'spades')` -> `'ace_of_spades.svg'`
+ */
+export function cardFileName(rank: Rank, suit: Suit): string {
+  return `${rankFileName(rank)}_of_${suit}.svg`;
+}
+
+/**
+ * Return the correct Phaser texture key for a card, taking face-up state
+ * into account. Face-down cards return `'card_back'`.
+ */
+export function getCardTexture(card: Card): string {
+  if (!card.faceUp) return 'card_back';
+  return cardTextureKey(card.rank, card.suit);
+}
+
+/**
+ * Preload all 52 card face SVGs and the card back SVG into a Phaser scene.
+ *
+ * Call this from your scene's `preload()` method instead of manually
+ * iterating over ranks and suits.
+ *
+ * @param scene  The Phaser scene whose loader should be used.
+ * @param width  Card sprite width in pixels (defaults to `CARD_W`).
+ * @param height Card sprite height in pixels (defaults to `CARD_H`).
+ */
+export function preloadCardAssets(
+  scene: Phaser.Scene,
+  width: number = CARD_W,
+  height: number = CARD_H,
+): void {
+  // Card back
+  scene.load.svg('card_back', 'assets/cards/card_back.svg', {
+    width,
+    height,
+  });
+
+  // All 52 card faces
+  for (const suit of SUITS) {
+    for (const rank of RANKS) {
+      const key = cardTextureKey(rank, suit);
+      const file = cardFileName(rank, suit);
+      scene.load.svg(key, `assets/cards/${file}`, { width, height });
+    }
+  }
+}

src/ui/constants.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared UI constants for the Tableau Card Engine.
+ *
+ * These values define the default rendering dimensions and font settings
+ * used across all example-game scenes. Individual games may still define
+ * game-specific constants (e.g. grid gaps, animation timings) locally.
+ */
+
+/** Default card sprite width (pixels). */
+export const CARD_W = 48;
+
+/** Default card sprite height (pixels). */
+export const CARD_H = 65;
+
+/** Default game viewport width (pixels). */
+export const GAME_W = 800;
+
+/** Default game viewport height (pixels). */
+export const GAME_H = 600;
+
+/** Default font family used for in-game text. */
+export const FONT_FAMILY = 'Arial, sans-serif';

src/ui/index.ts

@@ -14,3 +14,15 @@ export type { HelpButtonConfig } from './HelpButton';
 
 export { GameSelectorScene, REGISTRY_KEY_GAMES } from './GameSelectorScene';
 export type { GameEntry } from './GameSelectorScene';
+
+// Shared constants
+export { CARD_W, CARD_H, GAME_W, GAME_H, FONT_FAMILY } from './constants';
+
+// Card texture helpers
+export {
+  rankFileName,
+  cardTextureKey,
+  cardFileName,
+  getCardTexture,
+  preloadCardAssets,
+} from './CardTextureHelpers';