CG-0MM60OEIA1YX98BY: Rename gem types to generic resource names across Feudalism

Systematic rename of all gem-specific type aliases, constants, and function
names to generic resource equivalents, preparing the codebase for the
medieval Irish crops theme:

  GemColor -> ResourceType, GemOrGold -> ResourceOrWild,
  GemTokens -> ResourceTokens, GemCost -> ResourceCost,
  GEM_COLORS -> RESOURCE_TYPES, ALL_TOKEN_COLORS -> ALL_RESOURCE_TYPES,
  gemAbbrev -> resourceAbbrev, gemDisplayName -> resourceDisplayName,
  GEM_FILL -> RESOURCE_FILL, GEM_TEXT_COLOR -> RESOURCE_TEXT_COLOR,
  SPGemTokens -> SPResourceTokens

Updated 8 source/test files and 2 doc files. All 1616 unit tests pass,
build succeeds, zero remaining references to old names.

Author: rgardler-msft

docs/games/the-build/engine-capabilities-audit.md

@@ -191,7 +191,7 @@ A 2-player card-drafting game with 108 custom-typed cards (8 types). Players sim
 A 2-player engine-building game with 90 development cards across 3 tiers, gem tokens, noble tiles, and a 15-prestige win threshold. **The closest existing example to a "buildy" resource-management game.**
 
 - **Engine APIs used:** `shuffleArray`, `MultiplayerSetupOptions`, `resolveSetupOptions`, `getCurrentPlayer`, `CardGameScene`, `AiPlayer`, `pickRandom`, `TranscriptRecorderBase`, overlay helpers, `createSceneHeader`, `HelpPanel`, `SettingsPanel`
-- **Notable patterns:** Resource economy system (`GemTokens` with add/subtract helpers); market system (3 tier decks with 4 visible each); purchase validation with bonus discounts and gold wildcards; token limit (10) with discard mechanic; noble auto-visit; final-round trigger; `GreedyStrategy` AI with noble-progress scoring. Most relevant precedent for "The Build."
+- **Notable patterns:** Resource economy system (`ResourceTokens` with add/subtract helpers); market system (3 tier decks with 4 visible each); purchase validation with bonus discounts and gold wildcards; token limit (10) with discard mechanic; noble auto-visit; final-round trigger; `GreedyStrategy` AI with noble-progress scoring. Most relevant precedent for "The Build."
 
 ### Lost Cities (`example-games/lost-cities/`)
 A 2-player expedition card game with 60 custom cards (5 colors, investment multipliers + numbered 2-10), played over 3 rounds. Features two-phase turns and ascending-play constraints.
@@ -210,7 +210,7 @@ A 2-player cooperative real-time card game where players simultaneously play num
 ## 3. Minor Extensions (< 1 day each)
 
 ### 3.1 Generic Resource/Token Container
-**What:** Extract Feudalism's `GemTokens` helper (add/subtract/canAfford/total) into a generic `ResourceBank<K extends string>` class in `src/core-engine/` that works with any set of named resource types.
+**What:** Extract Feudalism's `ResourceTokens` helper (add/subtract/canAfford/total) into a generic `ResourceBank<K extends string>` class in `src/core-engine/` that works with any set of named resource types.
 **How it helps "The Build":** A crafty/buildy game needs resource tracking (wood, stone, iron, food, etc.). A generic container avoids every game re-implementing arithmetic and validation for named resources.
 **Effort:** ~4 hours.
 

docs/games/the-build/ideation-concepts.md

@@ -46,7 +46,7 @@ Combines the universally familiar tri-peaks solitaire with spatial grid building
 | Seeded RNG | Existing | `createSeededRng()` |
 | Grid/spatial placement | **NEW** | Need a `Grid<T>` abstraction for the cottage layout |
 | Adjacency evaluation | **NEW** | Need adjacency-based synergy resolver |
-| Resource tracking | Minor extension | Generalize Feudalism's `GemTokens` into `ResourceBank` |
+| Resource tracking | Minor extension | Generalize Feudalism's `ResourceTokens` into `ResourceBank` |
 | Market row | **NEW** | Need reusable `Market<T>` component |
 | Seasonal/round timer | Minor extension | `PhaseManager` can handle this with some extension |
 | Scoring system | Game-specific | Build on existing patterns |

example-games/feudalism/AiStrategy.ts

@@ -8,10 +8,10 @@
  */
 
 import {
-  type GemColor,
-  type GemTokens,
-  GEM_COLORS,
-  ALL_TOKEN_COLORS,
+  type ResourceType,
+  type ResourceTokens,
+  RESOURCE_TYPES,
+  ALL_RESOURCE_TYPES,
   tokenCount,
 } from './FeudalismCards';
 import {
@@ -109,7 +109,7 @@ export const GreedyStrategy: FeudalismAiStrategy = {
 
         const eff = effectiveCost(card.cost, bonuses);
         let totalNeeded = 0;
-        for (const c of GEM_COLORS) {
+        for (const c of RESOURCE_TYPES) {
           totalNeeded += Math.max(0, (eff[c] ?? 0) - tokenCount(player.tokens, c));
         }
         const score = card.points * 10 - totalNeeded;
@@ -139,7 +139,7 @@ export const GreedyStrategy: FeudalismAiStrategy = {
       for (const card of allCards) {
         const eff = effectiveCost(card.cost, bonuses);
         let shortfall = 0;
-        for (const c of GEM_COLORS) {
+        for (const c of RESOURCE_TYPES) {
           shortfall += Math.max(0, (eff[c] ?? 0) - tokenCount(player.tokens, c));
         }
         const value = card.points * 10 - shortfall;
@@ -218,7 +218,7 @@ export class FeudalismAiPlayer extends AiPlayerBase<FeudalismAiStrategy> {
 function scoreNobleProgress(
   session: FeudalismSession,
   player: FeudalismPlayerState,
-  bonusColor: GemColor,
+  bonusColor: ResourceType,
 ): number {
   const bonuses = getBonuses(player);
   let bestScore = 0;
@@ -229,7 +229,7 @@ function scoreNobleProgress(
       // This bonus brings us closer to this noble
       let totalProgress = 0;
       let totalReq = 0;
-      for (const c of GEM_COLORS) {
+      for (const c of RESOURCE_TYPES) {
         const r = noble.requirements[c] ?? 0;
         totalReq += r;
         totalProgress += Math.min(bonuses[c] + (c === bonusColor ? 1 : 0), r);
@@ -247,9 +247,9 @@ function buildRandomDiscard(
   excess: number,
   rng: () => number,
 ): TokenDiscard {
-  const tokens: GemTokens = {};
+  const tokens: ResourceTokens = {};
   let remaining = excess;
-  const colors = [...ALL_TOKEN_COLORS].filter(c => tokenCount(player.tokens, c) > 0);
+  const colors = [...ALL_RESOURCE_TYPES].filter(c => tokenCount(player.tokens, c) > 0);
 
   while (remaining > 0 && colors.length > 0) {
     const idx = Math.floor(rng() * colors.length);
@@ -279,13 +279,13 @@ function buildSmartDiscard(
 
   // Calculate usefulness of each color
   const usefulness: Record<string, number> = {};
-  for (const c of ALL_TOKEN_COLORS) {
+  for (const c of ALL_RESOURCE_TYPES) {
     usefulness[c] = 0;
   }
 
   for (const card of allCards) {
     const eff = effectiveCost(card.cost, bonuses);
-    for (const c of GEM_COLORS) {
+    for (const c of RESOURCE_TYPES) {
       const need = (eff[c] ?? 0) - tokenCount(player.tokens, c);
       if (need < 0) {
         // We have more than needed — this color is less useful per excess token
@@ -299,10 +299,10 @@ function buildSmartDiscard(
   usefulness.gold = 100;
 
   // Discard least useful tokens
-  const tokens: GemTokens = {};
+  const tokens: ResourceTokens = {};
   let remaining = excess;
 
-  const sortedColors = [...ALL_TOKEN_COLORS]
+  const sortedColors = [...ALL_RESOURCE_TYPES]
     .filter(c => tokenCount(player.tokens, c) > 0)
     .sort((a, b) => usefulness[a] - usefulness[b]);
 

example-games/feudalism/FeudalismCards.ts

@@ -2,7 +2,7 @@
  * FeudalismCards.ts
  *
  * Type definitions and data for the Feudalism card game:
- * - Gem colors and token types
+ * - Resource types and token types
  * - Development cards (90 total across 3 tiers)
  * - Noble tiles (10 total)
  * - Supply initialization
@@ -11,64 +11,64 @@
  */
 
 // ---------------------------------------------------------------------------
-// Gem types
+// Resource types
 // ---------------------------------------------------------------------------
 
-/** The five gem colors plus gold (wild). */
-export type GemColor = 'emerald' | 'sapphire' | 'ruby' | 'diamond' | 'onyx';
-export type GemOrGold = GemColor | 'gold';
+/** The five resource types plus gold (wild). */
+export type ResourceType = 'emerald' | 'sapphire' | 'ruby' | 'diamond' | 'onyx';
+export type ResourceOrWild = ResourceType | 'gold';
 
-export const GEM_COLORS: readonly GemColor[] = [
+export const RESOURCE_TYPES: readonly ResourceType[] = [
   'emerald',
   'sapphire',
   'ruby',
   'diamond',
   'onyx',
 ] as const;
 
-export const ALL_TOKEN_COLORS: readonly GemOrGold[] = [
-  ...GEM_COLORS,
+export const ALL_RESOURCE_TYPES: readonly ResourceOrWild[] = [
+  ...RESOURCE_TYPES,
   'gold',
 ] as const;
 
-/** A bag of gem/gold token counts. Missing keys imply 0. */
-export type GemTokens = Partial<Record<GemOrGold, number>>;
+/** A bag of resource/gold token counts. Missing keys imply 0. */
+export type ResourceTokens = Partial<Record<ResourceOrWild, number>>;
 
-/** Shorthand: cost uses only gem colors (no gold in costs). */
-export type GemCost = Partial<Record<GemColor, number>>;
+/** Shorthand: cost uses only resource types (no gold in costs). */
+export type ResourceCost = Partial<Record<ResourceType, number>>;
 
 // ---------------------------------------------------------------------------
 // Helper to read token counts safely
 // ---------------------------------------------------------------------------
 
 /** Return the count for a color, defaulting to 0. */
-export function tokenCount(tokens: GemTokens, color: GemOrGold): number {
+export function tokenCount(tokens: ResourceTokens, color: ResourceOrWild): number {
   return tokens[color] ?? 0;
 }
 
 /** Return the total number of tokens. */
-export function totalTokens(tokens: GemTokens): number {
+export function totalTokens(tokens: ResourceTokens): number {
   let sum = 0;
-  for (const c of ALL_TOKEN_COLORS) {
+  for (const c of ALL_RESOURCE_TYPES) {
     sum += tokenCount(tokens, c);
   }
   return sum;
 }
 
 /** Add two token bags together (returns new object). */
-export function addTokens(a: GemTokens, b: GemTokens): GemTokens {
-  const result: GemTokens = {};
-  for (const c of ALL_TOKEN_COLORS) {
+export function addTokens(a: ResourceTokens, b: ResourceTokens): ResourceTokens {
+  const result: ResourceTokens = {};
+  for (const c of ALL_RESOURCE_TYPES) {
     const val = tokenCount(a, c) + tokenCount(b, c);
     if (val !== 0) result[c] = val;
   }
   return result;
 }
 
 /** Subtract b from a (returns new object). Does NOT check for negatives. */
-export function subtractTokens(a: GemTokens, b: GemTokens): GemTokens {
-  const result: GemTokens = {};
-  for (const c of ALL_TOKEN_COLORS) {
+export function subtractTokens(a: ResourceTokens, b: ResourceTokens): ResourceTokens {
+  const result: ResourceTokens = {};
+  for (const c of ALL_RESOURCE_TYPES) {
     const val = tokenCount(a, c) - tokenCount(b, c);
     if (val !== 0) result[c] = val;
   }
@@ -84,8 +84,8 @@ export type Tier = 1 | 2 | 3;
 export interface DevelopmentCard {
   readonly id: number;
   readonly tier: Tier;
-  readonly cost: GemCost;
-  readonly bonus: GemColor;
+  readonly cost: ResourceCost;
+  readonly bonus: ResourceType;
   readonly points: number;
 }
 
@@ -95,8 +95,8 @@ export interface DevelopmentCard {
 
 export interface NobleTile {
   readonly id: number;
-  /** The gem bonus counts required from purchased cards. */
-  readonly requirements: GemCost;
+  /** The resource bonus counts required from purchased cards. */
+  readonly requirements: ResourceCost;
   readonly points: number; // always 3
 }
 
@@ -115,18 +115,18 @@ export { shuffleArray } from '../../src/card-system/Deck';
 // ---------------------------------------------------------------------------
 
 /**
- * Token counts per gem color based on player count:
- * - 2 players: 4 of each gem, 5 gold
- * - 3 players: 5 of each gem, 5 gold
- * - 4 players: 7 of each gem, 5 gold
+ * Token counts per resource type based on player count:
+ * - 2 players: 4 of each resource, 5 gold
+ * - 3 players: 5 of each resource, 5 gold
+ * - 4 players: 7 of each resource, 5 gold
  */
-export function createTokenSupply(playerCount: number): GemTokens {
+export function createTokenSupply(playerCount: number): ResourceTokens {
   if (playerCount < 2 || playerCount > 4) {
     throw new Error(`Invalid player count: ${playerCount}. Must be 2-4.`);
   }
   const gemCount = playerCount === 2 ? 4 : playerCount === 3 ? 5 : 7;
-  const supply: GemTokens = { gold: 5 };
-  for (const color of GEM_COLORS) {
+  const supply: ResourceTokens = { gold: 5 };
+  for (const color of RESOURCE_TYPES) {
     supply[color] = gemCount;
   }
   return supply;
@@ -150,7 +150,7 @@ export function selectNobles(
 // ---------------------------------------------------------------------------
 
 let nextId = 1;
-function card(tier: Tier, bonus: GemColor, points: number, cost: GemCost): DevelopmentCard {
+function card(tier: Tier, bonus: ResourceType, points: number, cost: ResourceCost): DevelopmentCard {
   return { id: nextId++, tier, cost, bonus, points };
 }
 
@@ -303,7 +303,7 @@ export const TOTAL_CARD_COUNT = 90;
 // ---------------------------------------------------------------------------
 
 let nobleId = 1;
-function noble(requirements: GemCost): NobleTile {
+function noble(requirements: ResourceCost): NobleTile {
   return { id: nobleId++, requirements, points: 3 };
 }
 
@@ -352,11 +352,11 @@ export const MAX_RESERVED = 3;
 export const MAX_TOKENS = 10;
 
 // ---------------------------------------------------------------------------
-// Card label helpers (for UI display)
+// Resource label helpers (for UI display)
 // ---------------------------------------------------------------------------
 
-/** Short abbreviation for a gem color. */
-export function gemAbbrev(color: GemOrGold): string {
+/** Short abbreviation for a resource type. */
+export function resourceAbbrev(color: ResourceOrWild): string {
   switch (color) {
     case 'emerald': return 'G';
     case 'sapphire': return 'U';
@@ -367,33 +367,33 @@ export function gemAbbrev(color: GemOrGold): string {
   }
 }
 
-/** Display name for a gem color. */
-export function gemDisplayName(color: GemOrGold): string {
+/** Display name for a resource type. */
+export function resourceDisplayName(color: ResourceOrWild): string {
   return color.charAt(0).toUpperCase() + color.slice(1);
 }
 
 /** Format a cost object as a short string, e.g. "2W 3R 1K". */
-export function formatCost(cost: GemCost): string {
+export function formatCost(cost: ResourceCost): string {
   const parts: string[] = [];
-  for (const c of GEM_COLORS) {
+  for (const c of RESOURCE_TYPES) {
     const n = cost[c];
-    if (n && n > 0) parts.push(`${n}${gemAbbrev(c)}`);
+    if (n && n > 0) parts.push(`${n}${resourceAbbrev(c)}`);
   }
   return parts.join(' ') || 'Free';
 }
 
 /** Format a card as a display label. */
 export function cardLabel(card: DevelopmentCard): string {
   const pts = card.points > 0 ? ` [${card.points}pt]` : '';
-  return `T${card.tier} ${gemAbbrev(card.bonus)}${pts} (${formatCost(card.cost)})`;
+  return `T${card.tier} ${resourceAbbrev(card.bonus)}${pts} (${formatCost(card.cost)})`;
 }
 
 /** Format a noble tile as a display label. */
 export function nobleLabel(noble: NobleTile): string {
   const reqs: string[] = [];
-  for (const c of GEM_COLORS) {
+  for (const c of RESOURCE_TYPES) {
     const n = noble.requirements[c];
-    if (n && n > 0) reqs.push(`${n}${gemAbbrev(c)}`);
+    if (n && n > 0) reqs.push(`${n}${resourceAbbrev(c)}`);
   }
   return `Noble [3pt] (${reqs.join(' ')})`;
 }