@arcanahq/cardgames 1.0.0

package/assembly/poker/showdown.ts

@@ -0,0 +1,106 @@
+// @ts-nocheck
+/**
+ * Poker Showdown Utilities
+ * 
+ * Utilities for comparing multiple poker hands and determining winners
+ * Supports both 5-card and 7-card (Hold'em) hands
+ * 
+ * Provides both a concrete StandardShowdownEvaluator and convenience functions
+ * that use the standard evaluator by default.
+ */
+
+import { Card, HandRank } from "../cards";
+import { evaluateHand, compareHands, getBestFiveCards } from "../poker";
+import { ShowdownEvaluator, ShowdownResult } from "./showdown_evaluator";
+
+/**
+ * Standard showdown evaluator for traditional poker games
+ * Uses standard 52-card deck evaluation
+ */
+export class StandardShowdownEvaluator extends ShowdownEvaluator {
+  evaluateHand(holeCards: Card[], communityCards: Card[]): HandRank {
+    return evaluateHand(holeCards, communityCards);
+  }
+  
+  getBestFiveCards(holeCards: Card[], communityCards: Card[]): Card[] {
+    return getBestFiveCards(holeCards, communityCards);
+  }
+  
+  compareHands(hand1: HandRank, hand2: HandRank): i32 {
+    return compareHands(hand1, hand2);
+  }
+}
+
+// Default evaluator instance for convenience functions
+const defaultEvaluator = new StandardShowdownEvaluator();
+
+/**
+ * Compare multiple poker hands and determine winners
+ * Uses the default StandardShowdownEvaluator
+ * 
+ * @param holeCardsMap Map of seat ID to their hole cards (2 cards for Hold'em)
+ * @param communityCards Community cards (5 cards for Hold'em: flop + turn + river)
+ * @returns ShowdownResult with winners, hand ranks, and best 5-card hands
+ */
+export function compareHandsShowdown(
+  holeCardsMap: Map<i32, Card[]>,
+  communityCards: Card[]
+): ShowdownResult {
+  return defaultEvaluator.compareHandsShowdown(holeCardsMap, communityCards);
+}
+
+/**
+ * Compare exactly 5 cards and determine winner
+ * Useful for games like 5-card draw
+ * Uses the default StandardShowdownEvaluator
+ * 
+ * @param handsMap Map of seat ID to their 5-card hand
+ * @returns ShowdownResult with winners
+ */
+export function compareFiveCardHands(handsMap: Map<i32, Card[]>): ShowdownResult {
+  return defaultEvaluator.compareFiveCardHands(handsMap);
+}
+
+/**
+ * Get hand rank for a single player
+ * Convenience function for evaluating one player's hand
+ * Uses the default StandardShowdownEvaluator
+ * 
+ * @param holeCards Player's hole cards (2 cards for Hold'em)
+ * @param communityCards Community cards (5 cards for Hold'em)
+ * @returns HandRank for the player's best hand
+ */
+export function getPlayerHandRank(holeCards: Card[], communityCards: Card[]): HandRank {
+  return defaultEvaluator.getPlayerHandRank(holeCards, communityCards);
+}
+
+/**
+ * Get best 5-card hand for a single player
+ * Convenience function for getting a player's best 5-card hand
+ * Uses the default StandardShowdownEvaluator
+ * 
+ * @param holeCards Player's hole cards (2 cards for Hold'em)
+ * @param communityCards Community cards (5 cards for Hold'em)
+ * @returns Best 5-card hand
+ */
+export function getPlayerBestHand(holeCards: Card[], communityCards: Card[]): Card[] {
+  return defaultEvaluator.getPlayerBestHand(holeCards, communityCards);
+}
+
+/**
+ * Compare two specific hands and return winner
+ * Uses the default StandardShowdownEvaluator
+ * 
+ * @param holeCards1 First player's hole cards
+ * @param holeCards2 Second player's hole cards
+ * @param communityCards Community cards
+ * @returns 1 if player 1 wins, -1 if player 2 wins, 0 if tie
+ */
+export function compareTwoHands(
+  holeCards1: Card[],
+  holeCards2: Card[],
+  communityCards: Card[]
+): i32 {
+  return defaultEvaluator.compareTwoHands(holeCards1, holeCards2, communityCards);
+}
+

package/assembly/poker/showdown_evaluator.ts

@@ -0,0 +1,225 @@
+// @ts-nocheck
+/**
+ * Showdown Evaluator Interface
+ * 
+ * Abstract interface for evaluating poker showdowns.
+ * Allows different implementations for different poker variants
+ * (e.g., standard Hold'em, Six-plus Hold'em, etc.)
+ */
+
+import { Card, HandRank } from "../cards";
+
+/**
+ * Result of a showdown comparison
+ */
+export class ShowdownResult {
+  winners: i32[]; // Array of seat IDs that tied for the win
+  handRanks: Map<i32, HandRank>; // Map of seat ID to their hand rank
+  bestFiveCards: Map<i32, Card[]>; // Map of seat ID to their best 5-card hand
+  
+  constructor(
+    winners: i32[],
+    handRanks: Map<i32, HandRank>,
+    bestFiveCards: Map<i32, Card[]>
+  ) {
+    this.winners = winners;
+    this.handRanks = handRanks;
+    this.bestFiveCards = bestFiveCards;
+  }
+}
+
+/**
+ * Abstract interface for showdown evaluation
+ * Implement this for different poker variants
+ * 
+ * This interface is flexible enough to support:
+ * - Hold'em variants (Texas Hold'em, Six-Plus, etc.) - uses community cards
+ * - Stud variants (5-card, 7-card) - no community cards, all cards in holeCards
+ * - Omaha variants - must use specific number of hole cards
+ * - Lowball variants - lowest hand wins
+ */
+export abstract class ShowdownEvaluator {
+  /**
+   * Evaluate a single player's hand from hole cards and community cards
+   * 
+   * For Hold'em: holeCards = 2 cards, communityCards = 5 cards
+   * For Stud: holeCards = 5 or 7 cards, communityCards = [] (empty)
+   * For Omaha: holeCards = 4 cards, communityCards = 5 cards (must use exactly 2 hole cards)
+   * 
+   * @param holeCards Player's hole cards (or all cards for stud variants)
+   * @param communityCards Community cards (empty for stud variants)
+   * @returns HandRank for the player's best hand
+   */
+  abstract evaluateHand(holeCards: Card[], communityCards: Card[]): HandRank;
+  
+  /**
+   * Get the best 5-card hand from hole cards and community cards
+   * @param holeCards Player's hole cards
+   * @param communityCards Community cards
+   * @returns Best 5-card hand
+   */
+  abstract getBestFiveCards(holeCards: Card[], communityCards: Card[]): Card[];
+  
+  /**
+   * Compare two hand ranks
+   * @param hand1 First hand rank
+   * @param hand2 Second hand rank
+   * @returns -1 if hand1 < hand2, 0 if equal, 1 if hand1 > hand2
+   */
+  abstract compareHands(hand1: HandRank, hand2: HandRank): i32;
+  
+  /**
+   * Compare multiple poker hands and determine winners
+   * @param holeCardsMap Map of seat ID to their hole cards
+   * @param communityCards Community cards
+   * @returns ShowdownResult with winners, hand ranks, and best 5-card hands
+   */
+  compareHandsShowdown(
+    holeCardsMap: Map<i32, Card[]>,
+    communityCards: Card[]
+  ): ShowdownResult {
+    const handRanks = new Map<i32, HandRank>();
+    const bestFiveCards = new Map<i32, Card[]>();
+    const winners = new Array<i32>(0);
+    
+    // Evaluate each player's hand
+    const seatIds = holeCardsMap.keys();
+    for (let i = 0; i < seatIds.length; i++) {
+      const seatId = seatIds[i];
+      const holeCards = holeCardsMap.get(seatId);
+      
+      if (holeCards.length === 0) {
+        continue; // Skip empty hands
+      }
+      
+      // Evaluate hand using the abstract method
+      const handRank = this.evaluateHand(holeCards, communityCards);
+      handRanks.set(seatId, handRank);
+      
+      // Get best 5-card hand using the abstract method
+      const bestFive = this.getBestFiveCards(holeCards, communityCards);
+      bestFiveCards.set(seatId, bestFive);
+    }
+    
+    if (handRanks.size === 0) {
+      return new ShowdownResult(winners, handRanks, bestFiveCards);
+    }
+    
+    // Find the best hand(s)
+    let bestRank: HandRank | null = null;
+    const seatIdsForComparison = handRanks.keys();
+    
+    for (let i = 0; i < seatIdsForComparison.length; i++) {
+      const seatId = seatIdsForComparison[i];
+      const rank = handRanks.get(seatId);
+      
+      if (bestRank === null) {
+        bestRank = rank;
+        winners.push(seatId);
+      } else {
+        const comparison = this.compareHands(rank, bestRank);
+        if (comparison > 0) {
+          // New best hand
+          bestRank = rank;
+          winners.length = 0;
+          winners.push(seatId);
+        } else if (comparison === 0) {
+          // Tie
+          winners.push(seatId);
+        }
+      }
+    }
+    
+    return new ShowdownResult(winners, handRanks, bestFiveCards);
+  }
+  
+  /**
+   * Compare exactly 5 cards and determine winner
+   * Useful for games like 5-card draw
+   * @param handsMap Map of seat ID to their 5-card hand
+   * @returns ShowdownResult with winners
+   */
+  compareFiveCardHands(handsMap: Map<i32, Card[]>): ShowdownResult {
+    const handRanks = new Map<i32, HandRank>();
+    const bestFiveCards = new Map<i32, Card[]>();
+    const winners = new Array<i32>(0);
+    
+    // Evaluate each player's 5-card hand
+    const seatIds = handsMap.keys();
+    for (let i = 0; i < seatIds.length; i++) {
+      const seatId = seatIds[i];
+      const hand = handsMap.get(seatId);
+      
+      if (hand.length !== 5) {
+        continue; // Skip invalid hands
+      }
+      
+      // Evaluate 5-card hand directly (no community cards)
+      const handRank = this.evaluateHand(hand, new Array<Card>(0));
+      handRanks.set(seatId, handRank);
+      bestFiveCards.set(seatId, hand);
+    }
+    
+    if (handRanks.size === 0) {
+      return new ShowdownResult(winners, handRanks, bestFiveCards);
+    }
+    
+    // Find the best hand(s)
+    let bestRank: HandRank | null = null;
+    const seatIdsForComparison = handRanks.keys();
+    
+    for (let i = 0; i < seatIdsForComparison.length; i++) {
+      const seatId = seatIdsForComparison[i];
+      const rank = handRanks.get(seatId);
+      
+      if (bestRank === null) {
+        bestRank = rank;
+        winners.push(seatId);
+      } else {
+        const comparison = this.compareHands(rank, bestRank);
+        if (comparison > 0) {
+          // New best hand
+          bestRank = rank;
+          winners.length = 0;
+          winners.push(seatId);
+        } else if (comparison === 0) {
+          // Tie
+          winners.push(seatId);
+        }
+      }
+    }
+    
+    return new ShowdownResult(winners, handRanks, bestFiveCards);
+  }
+  
+  /**
+   * Get hand rank for a single player
+   * Convenience method
+   */
+  getPlayerHandRank(holeCards: Card[], communityCards: Card[]): HandRank {
+    return this.evaluateHand(holeCards, communityCards);
+  }
+  
+  /**
+   * Get best 5-card hand for a single player
+   * Convenience method
+   */
+  getPlayerBestHand(holeCards: Card[], communityCards: Card[]): Card[] {
+    return this.getBestFiveCards(holeCards, communityCards);
+  }
+  
+  /**
+   * Compare two specific hands and return winner
+   * @returns 1 if hand1 wins, -1 if hand2 wins, 0 if tie
+   */
+  compareTwoHands(
+    holeCards1: Card[],
+    holeCards2: Card[],
+    communityCards: Card[]
+  ): i32 {
+    const rank1 = this.evaluateHand(holeCards1, communityCards);
+    const rank2 = this.evaluateHand(holeCards2, communityCards);
+    return this.compareHands(rank1, rank2);
+  }
+}
+

package/assembly/poker/six_plus_showdown.ts

@@ -0,0 +1,96 @@
+// @ts-nocheck
+/**
+ * Six-Plus Hold'em Showdown Evaluator
+ * 
+ * Six-Plus Hold'em (also known as Short Deck Hold'em) uses a 36-card deck
+ * (removes 2-5 cards) and has different hand rankings:
+ * - Flush beats Full House
+ * - Three of a Kind beats Straight
+ * 
+ * This evaluator implements the Six-Plus Hold'em hand ranking rules.
+ */
+
+import { Card, HandRank, HandType, Rank } from "../cards";
+import { ShowdownEvaluator, ShowdownResult } from "./showdown_evaluator";
+import { evaluateHand, getBestFiveCards } from "../poker";
+
+/**
+ * Six-Plus Hold'em showdown evaluator
+ * Uses modified hand rankings for 36-card deck
+ */
+export class SixPlusShowdownEvaluator extends ShowdownEvaluator {
+  /**
+   * Evaluate a hand using Six-Plus Hold'em rules
+   * Hand rankings are different: Flush > Full House, Three of a Kind > Straight
+   */
+  evaluateHand(holeCards: Card[], communityCards: Card[]): HandRank {
+    // First evaluate using standard rules
+    const standardRank = evaluateHand(holeCards, communityCards);
+    
+    // Then adjust for Six-Plus Hold'em rankings
+    return this.adjustForSixPlusRanking(standardRank);
+  }
+  
+  /**
+   * Get best 5-card hand (same as standard)
+   */
+  getBestFiveCards(holeCards: Card[], communityCards: Card[]): Card[] {
+    return getBestFiveCards(holeCards, communityCards);
+  }
+  
+  /**
+   * Compare hands using Six-Plus Hold'em rules
+   * Override to handle Six-Plus ranking swaps
+   */
+  compareHands(hand1: HandRank, hand2: HandRank): i32 {
+    // Get adjusted types for comparison
+    const type1 = this.getSixPlusType(hand1.handType);
+    const type2 = this.getSixPlusType(hand2.handType);
+    
+    // Compare types first
+    if (type1 < type2) return -1;
+    if (type1 > type2) return 1;
+    
+    // Same type, compare kickers
+    const maxLen = hand1.kickers.length > hand2.kickers.length ? hand1.kickers.length : hand2.kickers.length;
+    for (let i = 0; i < maxLen; i++) {
+      const kicker1 = i < hand1.kickers.length ? hand1.kickers[i] : 0;
+      const kicker2 = i < hand2.kickers.length ? hand2.kickers[i] : 0;
+      if (kicker1 < kicker2) return -1;
+      if (kicker1 > kicker2) return 1;
+    }
+    
+    return 0;
+  }
+  
+  /**
+   * Get Six-Plus Hold'em type value for comparison
+   * Returns a value where higher = better hand
+   * Hand rankings: Royal Flush > Straight Flush > Four of a Kind > Flush > Full House > Three of a Kind > Straight > Two Pair > Pair > High Card
+   */
+  private getSixPlusType(handType: i32): i32 {
+    // Map standard types to Six-Plus ranking values
+    // Higher number = better hand
+    if (handType === HandType.ROYAL_FLUSH) return 10;
+    if (handType === HandType.STRAIGHT_FLUSH) return 9;
+    if (handType === HandType.FOUR_OF_A_KIND) return 8;
+    if (handType === HandType.FLUSH) return 7; // Flush beats Full House in Six-Plus
+    if (handType === HandType.FULL_HOUSE) return 6; // Full House loses to Flush in Six-Plus
+    if (handType === HandType.THREE_OF_A_KIND) return 5; // Three of a Kind beats Straight in Six-Plus
+    if (handType === HandType.STRAIGHT) return 4; // Straight loses to Three of a Kind in Six-Plus
+    if (handType === HandType.TWO_PAIR) return 3;
+    if (handType === HandType.PAIR) return 2;
+    return 1; // HIGH_CARD
+  }
+  
+  /**
+   * Adjust hand rank for Six-Plus Hold'em rules
+   * This is used for display/logging purposes
+   */
+  private adjustForSixPlusRanking(rank: HandRank): HandRank {
+    // This method is kept for potential future use
+    // The actual comparison is handled in compareHands via getSixPlusType
+    return rank;
+  }
+}
+

package/assembly/poker/stud_evaluator.ts

@@ -0,0 +1,60 @@
+// @ts-nocheck
+/**
+ * Stud Poker Showdown Evaluator
+ * 
+ * Evaluator for 5-card and 7-card stud poker variants.
+ * In stud poker, there are no community cards - each player has their own complete hand.
+ * 
+ * For 7-card stud: Players receive 7 cards and choose the best 5
+ * For 5-card stud: Players receive 5 cards (use all 5)
+ */
+
+import { Card, HandRank } from "../cards";
+import { ShowdownEvaluator } from "./showdown_evaluator";
+import { evaluateHand, getBestFiveCards } from "../poker";
+
+/**
+ * Standard stud poker evaluator
+ * Works for both 5-card and 7-card stud
+ */
+export class StudShowdownEvaluator extends ShowdownEvaluator {
+  /**
+   * Evaluate a stud hand
+   * In stud, all cards are in holeCards, communityCards is empty
+   * 
+   * @param holeCards All player's cards (5 for 5-card stud, 7 for 7-card stud)
+   * @param communityCards Empty array for stud variants
+   */
+  evaluateHand(holeCards: Card[], communityCards: Card[]): HandRank {
+    // For stud, all cards are in holeCards, communityCards should be empty
+    // We can use the standard evaluator with empty community cards
+    return evaluateHand(holeCards, communityCards);
+  }
+  
+  /**
+   * Get best 5-card hand from stud cards
+   * For 5-card stud, returns all cards
+   * For 7-card stud, returns best 5 cards
+   */
+  getBestFiveCards(holeCards: Card[], communityCards: Card[]): Card[] {
+    // For stud, all cards are in holeCards
+    if (holeCards.length === 5) {
+      // 5-card stud: use all cards
+      return holeCards;
+    } else if (holeCards.length === 7) {
+      // 7-card stud: choose best 5
+      return getBestFiveCards(holeCards, new Array<Card>(0));
+    }
+    
+    // Fallback: use standard logic
+    return getBestFiveCards(holeCards, communityCards);
+  }
+  
+  /**
+   * Compare hands (same as standard)
+   */
+  compareHands(hand1: HandRank, hand2: HandRank): i32 {
+    return hand1.compare(hand2);
+  }
+}
+

package/assembly/poker/variant_utils.ts

@@ -0,0 +1,51 @@
+// @ts-nocheck
+/**
+ * Poker Variant Utilities
+ * 
+ * Helper functions for working with different poker variants
+ */
+
+import { ShowdownEvaluator } from "./showdown_evaluator";
+import { StandardShowdownEvaluator } from "./showdown";
+import { SixPlusShowdownEvaluator } from "./six_plus_showdown";
+import { StudShowdownEvaluator } from "./stud_evaluator";
+import { OmahaShowdownEvaluator } from "./omaha_evaluator";
+import { PokerVariant, PokerVariantConfig } from "./variants";
+
+/**
+ * Get the appropriate showdown evaluator for a poker variant
+ * 
+ * @param variant Variant name (e.g., PokerVariant.TEXAS_HOLDEM)
+ * @param config Optional variant configuration
+ * @returns ShowdownEvaluator instance for the variant
+ */
+export function getEvaluatorForVariant(
+  variant: string,
+  config: PokerVariantConfig | null = null
+): ShowdownEvaluator {
+  if (variant === PokerVariant.SIX_PLUS_HOLDEM || variant === PokerVariant.SHORT_DECK_HOLDEM) {
+    return new SixPlusShowdownEvaluator();
+  }
+  
+  if (variant === PokerVariant.SEVEN_CARD_STUD || variant === PokerVariant.FIVE_CARD_STUD || variant === PokerVariant.RAZZ) {
+    return new StudShowdownEvaluator();
+  }
+  
+  if (variant === PokerVariant.OMAHA || variant === PokerVariant.OMAHA_HI_LO) {
+    return new OmahaShowdownEvaluator();
+  }
+  
+  // Default to standard Hold'em
+  return new StandardShowdownEvaluator();
+}
+
+/**
+ * Create evaluator from variant configuration
+ * 
+ * @param config Poker variant configuration
+ * @returns ShowdownEvaluator instance
+ */
+export function createEvaluator(config: PokerVariantConfig): ShowdownEvaluator {
+  return getEvaluatorForVariant(config.variant, config);
+}
+