@arcanahq/cardgames 1.0.0

package/assembly/cardgames.ts

@@ -0,0 +1,314 @@
+// @ts-nocheck
+/**
+ * Card Game Utilities Library
+ * 
+ * Provides common card game operations that can be shared across different card games:
+ * - Standard deck creation (52 cards)
+ * - Deterministic shuffling using Fisher-Yates algorithm
+ * - Card dealing utilities
+ * 
+ * All operations are deterministic when using seeded randomness from the random module.
+ */
+
+import { Card, Suit, Rank } from "./cards";
+import { RandomSeed, getRandomIntInRange } from "@arcanahq/core/assembly/primitives/random";
+
+/**
+ * Creates a standard 52-card deck in unshuffled order
+ * Cards are ordered: suits in order (Spades, Hearts, Diamonds, Clubs),
+ * ranks in order (2, 3, 4, 5, 6, 7, 8, 9, 10, J, Q, K, A)
+ * 
+ * @returns A new array containing all 52 cards in standard order
+ */
+export function createStandardDeck(): Card[] {
+  const deck = new Array<Card>(52);
+  let index = 0;
+  
+  for (let s = 0; s < Suit.ALL.length; s++) {
+    for (let r = 0; r < Rank.ALL.length; r++) {
+      deck[index] = new Card(Suit.ALL[s], Rank.ALL[r]);
+      index++;
+    }
+  }
+  
+  return deck;
+}
+
+/**
+ * Shuffles a deck using the Fisher-Yates algorithm with deterministic randomness
+ * The shuffle is reproducible given the same seed
+ * 
+ * @param deck The deck to shuffle (will be modified in place)
+ * @param seed The random seed to use for shuffling
+ * @returns The updated random seed after shuffling
+ */
+export function shuffleDeck(deck: Card[], seed: RandomSeed): RandomSeed {
+  const n = deck.length;
+  let currentSeed = seed;
+  
+  // Fisher-Yates shuffle: iterate from last element to first
+  for (let i = n - 1; i > 0; i--) {
+    // Get random index from 0 to i (inclusive)
+    const result = getRandomIntInRange(currentSeed, 0, i + 1);
+    const j = <i32>result.value;
+    currentSeed = result.seed;
+    
+    // Swap cards[i] and cards[j]
+    const temp = deck[i];
+    deck[i] = deck[j];
+    deck[j] = temp;
+  }
+  
+  return currentSeed;
+}
+
+/**
+ * Result class for createShuffledDeck
+ */
+export class ShuffledDeckResult {
+  deck: Card[];
+  newSeed: RandomSeed;
+  
+  constructor(deck: Card[], newSeed: RandomSeed) {
+    this.deck = deck;
+    this.newSeed = newSeed;
+  }
+}
+
+/**
+ * Creates a shuffled deck from a standard deck using deterministic randomness
+ * 
+ * @param seed The random seed to use for shuffling
+ * @returns A ShuffledDeckResult containing the shuffled deck and the updated random seed
+ */
+export function createShuffledDeck(seed: RandomSeed): ShuffledDeckResult {
+  const deck = createStandardDeck();
+  const newSeed = shuffleDeck(deck, seed);
+  return new ShuffledDeckResult(deck, newSeed);
+}
+
+/**
+ * Deals a single card from the top of the deck
+ * 
+ * @param deck The deck to deal from (will be modified)
+ * @returns The dealt card, or null if the deck is empty
+ */
+export function dealCard(deck: Card[]): Card | null {
+  if (deck.length === 0) {
+    return null;
+  }
+  const card = deck.pop();
+  return card !== null ? card : null;
+}
+
+/**
+ * Deals multiple cards from the top of the deck
+ * 
+ * @param deck The deck to deal from (will be modified)
+ * @param count The number of cards to deal
+ * @returns An array of dealt cards (may be shorter than count if deck runs out)
+ */
+export function dealCards(deck: Card[], count: i32): Card[] {
+  const dealt = new Array<Card>(0);
+  for (let i = 0; i < count; i++) {
+    if (deck.length === 0) {
+      break; // Deck is empty
+    }
+    const card = dealCard(deck);
+    if (card !== null) {
+      dealt.push(card);
+    } else {
+      break; // Deck is empty
+    }
+  }
+  return dealt;
+}
+
+/**
+ * Result class for dealCardFromDeck
+ */
+export class DealCardResult {
+  card: Card | null;
+  newDeck: Card[];
+  newSeed: RandomSeed;
+  
+  constructor(card: Card | null, newDeck: Card[], newSeed: RandomSeed) {
+    this.card = card;
+    this.newDeck = newDeck;
+    this.newSeed = newSeed;
+  }
+}
+
+/**
+ * Deals a card from a specific position in the deck using deterministic randomness
+ * This is useful for games that need to deal cards in a specific order based on a seed
+ * 
+ * @param deck The deck to deal from
+ * @param seed The random seed to use for selecting the card
+ * @returns A DealCardResult containing the dealt card, the updated deck, and the updated seed
+ */
+export function dealCardFromDeck(
+  deck: Card[],
+  seed: RandomSeed
+): DealCardResult {
+  if (deck.length === 0) {
+    return new DealCardResult(null, deck, seed);
+  }
+  
+  // Use deterministic randomness to select a card index
+  const result = getRandomIntInRange(seed, 0, deck.length);
+  const cardIndex = <i32>result.value;
+  const newSeed = result.seed;
+  
+  // Remove the selected card from the deck
+  const card = deck[cardIndex];
+  const newDeck = new Array<Card>(deck.length - 1);
+  
+  let newDeckIndex = 0;
+  for (let i = 0; i < deck.length; i++) {
+    if (i !== cardIndex) {
+      newDeck[newDeckIndex] = deck[i];
+      newDeckIndex++;
+    }
+  }
+  
+  return new DealCardResult(card, newDeck, newSeed);
+}
+
+/**
+ * Gets the number of cards remaining in the deck
+ * 
+ * @param deck The deck to check
+ * @returns The number of cards in the deck
+ */
+export function getDeckSize(deck: Card[]): i32 {
+  return deck.length;
+}
+
+/**
+ * Checks if the deck is empty
+ * 
+ * @param deck The deck to check
+ * @returns True if the deck is empty, false otherwise
+ */
+export function isDeckEmpty(deck: Card[]): bool {
+  return deck.length === 0;
+}
+
+/**
+ * Creates a copy of a deck without modifying the original
+ * 
+ * @param deck The deck to clone
+ * @returns A new array containing copies of all cards in the deck
+ */
+export function cloneDeck(deck: Card[]): Card[] {
+  const cloned = new Array<Card>(deck.length);
+  for (let i = 0; i < deck.length; i++) {
+    cloned[i] = deck[i];
+  }
+  return cloned;
+}
+
+/**
+ * Converts a Card to an integer representation (0-51)
+ * Mapping: cardIndex = suitIndex * 13 + rankIndex
+ * - Suit order: Spades=0, Hearts=1, Diamonds=2, Clubs=3
+ * - Rank order: 2=0, 3=1, 4=2, 5=3, 6=4, 7=5, 8=6, 9=7, 10=8, J=9, Q=10, K=11, A=12
+ * 
+ * @param card The card to convert
+ * @returns An integer from 0-51 representing the card
+ */
+export function cardToInt(card: Card): i32 {
+  // Find suit index
+  let suitIndex: i32 = -1;
+  for (let i = 0; i < Suit.ALL.length; i++) {
+    if (Suit.ALL[i] === card.suit) {
+      suitIndex = i;
+      break;
+    }
+  }
+  
+  // Find rank index
+  let rankIndex: i32 = -1;
+  for (let i = 0; i < Rank.ALL.length; i++) {
+    if (Rank.ALL[i] === card.rank) {
+      rankIndex = i;
+      break;
+    }
+  }
+  
+  // If card is invalid, return -1
+  if (suitIndex < 0 || rankIndex < 0) {
+    return -1;
+  }
+  
+  // Calculate card index: suitIndex * 13 + rankIndex
+  return suitIndex * 13 + rankIndex;
+}
+
+/**
+ * Converts an integer (0-51) back to a Card
+ * Mapping: cardIndex = suitIndex * 13 + rankIndex
+ * - Suit order: Spades=0, Hearts=1, Diamonds=2, Clubs=3
+ * - Rank order: 2=0, 3=1, 4=2, 5=3, 6=4, 7=5, 8=6, 9=7, 10=8, J=9, Q=10, K=11, A=12
+ * 
+ * @param value The integer value (0-51) representing the card
+ * @returns A Card object, or null if the value is invalid
+ */
+export function intToCard(value: i32): Card | null {
+  // Validate range
+  if (value < 0 || value >= 52) {
+    return null;
+  }
+  
+  // Calculate suit and rank indices
+  const suitIndex = value / 13;  // Integer division
+  const rankIndex = value % 13;  // Modulo
+  
+  // Get suit and rank from arrays
+  if (suitIndex >= Suit.ALL.length || rankIndex >= Rank.ALL.length) {
+    return null;
+  }
+  
+  const suit = Suit.ALL[suitIndex];
+  const rank = Rank.ALL[rankIndex];
+  
+  return new Card(suit, rank);
+}
+
+/**
+ * Converts a deck of cards to an array of integers
+ * Useful for serialization and storage
+ * 
+ * @param deck The deck to serialize
+ * @returns An array of integers (0-51) representing each card
+ */
+export function deckToIntArray(deck: Card[]): i32[] {
+  const result = new Array<i32>(deck.length);
+  for (let i = 0; i < deck.length; i++) {
+    result[i] = cardToInt(deck[i]);
+  }
+  return result;
+}
+
+/**
+ * Converts an array of integers back to a deck of cards
+ * Useful for deserialization
+ * 
+ * @param ints An array of integers (0-51) representing cards
+ * @returns An array of Card objects
+ */
+export function intArrayToDeck(ints: i32[]): Card[] {
+  const deck = new Array<Card>(ints.length);
+  for (let i = 0; i < ints.length; i++) {
+    const card = intToCard(ints[i]);
+    if (card !== null) {
+      deck[i] = card;
+    } else {
+      // Invalid card value - skip or use a default?
+      // For now, we'll create a placeholder card
+      deck[i] = new Card(Suit.SPADES, Rank.TWO);
+    }
+  }
+  return deck;
+}

package/assembly/cards.ts

@@ -0,0 +1,314 @@
+// @ts-nocheck
+/**
+ * Deck of Cards Library
+ * 
+ * Provides Card, Suit, and Rank classes for card games.
+ * All operations are deterministic when using seeded randomness.
+ */
+
+import { getRandomIntInRange, RandomSeed, RandomResult } from "@arcanahq/core/assembly/primitives/random";
+
+// Card suit constants
+export class Suit {
+  static readonly SPADES: string = "♠";
+  static readonly HEARTS: string = "♥";
+  static readonly DIAMONDS: string = "♦";
+  static readonly CLUBS: string = "♣";
+  
+  static readonly ALL: string[] = [Suit.SPADES, Suit.HEARTS, Suit.DIAMONDS, Suit.CLUBS];
+  
+  static isValid(suit: string): bool {
+    return suit === Suit.SPADES || suit === Suit.HEARTS || suit === Suit.DIAMONDS || suit === Suit.CLUBS;
+  }
+}
+
+// Card rank constants
+export class Rank {
+  static readonly TWO: string = "2";
+  static readonly THREE: string = "3";
+  static readonly FOUR: string = "4";
+  static readonly FIVE: string = "5";
+  static readonly SIX: string = "6";
+  static readonly SEVEN: string = "7";
+  static readonly EIGHT: string = "8";
+  static readonly NINE: string = "9";
+  static readonly TEN: string = "10";
+  static readonly JACK: string = "J";
+  static readonly QUEEN: string = "Q";
+  static readonly KING: string = "K";
+  static readonly ACE: string = "A";
+  
+  static readonly ALL: string[] = [
+    Rank.TWO, Rank.THREE, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN,
+    Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE
+  ];
+  
+  static isValid(rank: string): bool {
+    for (let i = 0; i < Rank.ALL.length; i++) {
+      if (Rank.ALL[i] === rank) {
+        return true;
+      }
+    }
+    return false;
+  }
+  
+  /**
+   * Get numeric value for comparison (2=2, A=14)
+   */
+  static getValue(rank: string): i32 {
+    if (rank === Rank.TWO) return 2;
+    if (rank === Rank.THREE) return 3;
+    if (rank === Rank.FOUR) return 4;
+    if (rank === Rank.FIVE) return 5;
+    if (rank === Rank.SIX) return 6;
+    if (rank === Rank.SEVEN) return 7;
+    if (rank === Rank.EIGHT) return 8;
+    if (rank === Rank.NINE) return 9;
+    if (rank === Rank.TEN) return 10;
+    if (rank === Rank.JACK) return 11;
+    if (rank === Rank.QUEEN) return 12;
+    if (rank === Rank.KING) return 13;
+    if (rank === Rank.ACE) return 14;
+    return 0;
+  }
+}
+
+/**
+ * Card class representing a single playing card
+ */
+export class Card {
+  suit: string;
+  rank: string;
+  
+  constructor(suit: string, rank: string) {
+    this.suit = suit;
+    this.rank = rank;
+  }
+  
+  static fromString(str: string): Card | null {
+    // Format: "As" (Ace of spades), "Kh" (King of hearts), "2d" (2 of diamonds), "Tc" (10 of clubs)
+    if (str.length < 2) return null;
+    
+    const rankStr = str.substring(0, str.length - 1);
+    const suitStr = str.substring(str.length - 1);
+    
+    // Map suit characters
+    let suit: string = "";
+    if (suitStr === "s" || suitStr === "S") suit = Suit.SPADES;
+    else if (suitStr === "h" || suitStr === "H") suit = Suit.HEARTS;
+    else if (suitStr === "d" || suitStr === "D") suit = Suit.DIAMONDS;
+    else if (suitStr === "c" || suitStr === "C") suit = Suit.CLUBS;
+    else return null;
+    
+    // Map rank characters
+    let rank: string = "";
+    if (rankStr === "2") rank = Rank.TWO;
+    else if (rankStr === "3") rank = Rank.THREE;
+    else if (rankStr === "4") rank = Rank.FOUR;
+    else if (rankStr === "5") rank = Rank.FIVE;
+    else if (rankStr === "6") rank = Rank.SIX;
+    else if (rankStr === "7") rank = Rank.SEVEN;
+    else if (rankStr === "8") rank = Rank.EIGHT;
+    else if (rankStr === "9") rank = Rank.NINE;
+    else if (rankStr === "T" || rankStr === "t" || rankStr === "10") rank = Rank.TEN;
+    else if (rankStr === "J" || rankStr === "j") rank = Rank.JACK;
+    else if (rankStr === "Q" || rankStr === "q") rank = Rank.QUEEN;
+    else if (rankStr === "K" || rankStr === "k") rank = Rank.KING;
+    else if (rankStr === "A" || rankStr === "a") rank = Rank.ACE;
+    else return null;
+    
+    return new Card(suit, rank);
+  }
+  
+  toString(): string {
+    let rankStr: string = "";
+    if (this.rank === Rank.TWO) rankStr = "2";
+    else if (this.rank === Rank.THREE) rankStr = "3";
+    else if (this.rank === Rank.FOUR) rankStr = "4";
+    else if (this.rank === Rank.FIVE) rankStr = "5";
+    else if (this.rank === Rank.SIX) rankStr = "6";
+    else if (this.rank === Rank.SEVEN) rankStr = "7";
+    else if (this.rank === Rank.EIGHT) rankStr = "8";
+    else if (this.rank === Rank.NINE) rankStr = "9";
+    else if (this.rank === Rank.TEN) rankStr = "T";
+    else if (this.rank === Rank.JACK) rankStr = "J";
+    else if (this.rank === Rank.QUEEN) rankStr = "Q";
+    else if (this.rank === Rank.KING) rankStr = "K";
+    else if (this.rank === Rank.ACE) rankStr = "A";
+    else rankStr = "?";
+    
+    let suitStr: string = "";
+    if (this.suit === Suit.SPADES) suitStr = "s";
+    else if (this.suit === Suit.HEARTS) suitStr = "h";
+    else if (this.suit === Suit.DIAMONDS) suitStr = "d";
+    else if (this.suit === Suit.CLUBS) suitStr = "c";
+    else suitStr = "?";
+    
+    return rankStr + suitStr;
+  }
+  
+  equals(other: Card | null): bool {
+    if (other === null) return false;
+    return this.suit === other.suit && this.rank === other.rank;
+  }
+  
+  getValue(): i32 {
+    return Rank.getValue(this.rank);
+  }
+}
+
+/**
+ * Hand rank types for poker evaluation
+ */
+export class HandType {
+  static readonly HIGH_CARD: i32 = 1;
+  static readonly PAIR: i32 = 2;
+  static readonly TWO_PAIR: i32 = 3;
+  static readonly THREE_OF_A_KIND: i32 = 4;
+  static readonly STRAIGHT: i32 = 5;
+  static readonly FLUSH: i32 = 6;
+  static readonly FULL_HOUSE: i32 = 7;
+  static readonly FOUR_OF_A_KIND: i32 = 8;
+  static readonly STRAIGHT_FLUSH: i32 = 9;
+  static readonly ROYAL_FLUSH: i32 = 10;
+}
+
+/**
+ * HandRank represents the strength of a poker hand
+ */
+export class HandRank {
+  handType: i32;
+  kickers: i32[]; // Sorted descending, used for tie-breaking
+  
+  constructor(handType: i32, kickers: i32[] = []) {
+    this.handType = handType;
+    this.kickers = kickers;
+  }
+  
+  /**
+   * Compare two hand ranks
+   * Returns: -1 if this < other, 0 if equal, 1 if this > other
+   */
+  compare(other: HandRank): i32 {
+    if (this.handType < other.handType) return -1;
+    if (this.handType > other.handType) return 1;
+    
+    // Same hand type, compare kickers
+    const maxLen = this.kickers.length > other.kickers.length ? this.kickers.length : other.kickers.length;
+    for (let i = 0; i < maxLen; i++) {
+      const thisKicker = i < this.kickers.length ? this.kickers[i] : 0;
+      const otherKicker = i < other.kickers.length ? other.kickers[i] : 0;
+      if (thisKicker < otherKicker) return -1;
+      if (thisKicker > otherKicker) return 1;
+    }
+    
+    return 0;
+  }
+}
+
+/**
+ * Deck class representing a standard 52-card deck
+ */
+export class Deck {
+  cards: Card[];
+  
+  constructor() {
+    this.cards = new Array<Card>(52);
+    let idx = 0;
+    for (let s = 0; s < Suit.ALL.length; s++) {
+      for (let r = 0; r < Rank.ALL.length; r++) {
+        this.cards[idx] = new Card(Suit.ALL[s], Rank.ALL[r]);
+        idx++;
+      }
+    }
+  }
+  
+  /**
+   * Create a new deck from existing cards (for deserialization)
+   */
+  static fromCards(cards: Card[]): Deck {
+    const deck = new Deck();
+    deck.cards = cards;
+    return deck;
+  }
+  
+  /**
+   * Shuffle the deck using Fisher-Yates algorithm with deterministic randomness
+   */
+  shuffle(seed: RandomSeed): RandomSeed {
+    const n = this.cards.length;
+    let currentSeed = seed;
+    
+    for (let i = n - 1; i > 0; i--) {
+      // Get random index from 0 to i (inclusive)
+      const result = getRandomIntInRange(currentSeed, 0, i + 1);
+      const j = <i32>result.value;
+      currentSeed = result.seed;
+      
+      // Swap cards[i] and cards[j]
+      const temp = this.cards[i];
+      this.cards[i] = this.cards[j];
+      this.cards[j] = temp;
+    }
+    
+    return currentSeed;
+  }
+  
+  /**
+   * Deal one card from the top of the deck
+   */
+  dealCard(): Card | null {
+    if (this.cards.length === 0) return null;
+    return this.cards.pop();
+  }
+  
+  /**
+   * Deal multiple cards
+   */
+  dealCards(count: i32): Card[] {
+    const dealt = new Array<Card>(0);
+    for (let i = 0; i < count; i++) {
+      const card = this.dealCard();
+      if (card !== null) {
+        dealt.push(card);
+      } else {
+        break;
+      }
+    }
+    return dealt;
+  }
+  
+  /**
+   * Burn a card (remove without returning)
+   */
+  burnCard(): bool {
+    return this.dealCard() !== null;
+  }
+  
+  /**
+   * Get number of cards remaining
+   */
+  size(): i32 {
+    return this.cards.length;
+  }
+  
+  /**
+   * Check if deck is empty
+   */
+  isEmpty(): bool {
+    return this.cards.length === 0;
+  }
+  
+  /**
+   * Get a copy of the deck
+   */
+  clone(): Deck {
+    const newDeck = new Deck();
+    newDeck.cards = new Array<Card>(this.cards.length);
+    for (let i = 0; i < this.cards.length; i++) {
+      newDeck.cards[i] = this.cards[i];
+    }
+    return newDeck;
+  }
+}
+