balatro-cli 0.1.0

package/src/index.js

@@ -0,0 +1,217 @@
+/**
+ * Main loop: Ante -> Blind (small/big/boss) -> Round -> Shop. Log-style output throughout.
+ */
+
+import log from './logStyle.js';
+import * as deck from './deck.js';
+import { formatCard, formatCardPadded, sortHand } from './deck.js';
+import { getBlindConfig, getBlindLabel, BLIND_ORDER, ANTES_COUNT } from './blinds.js';
+import { createRoundState, playHand, doDiscard } from './round.js';
+import * as shop from './shop.js';
+import * as cli from './cli.js';
+
+const STARTING_MONEY = 4;
+
+const ERROR_MSG = {
+  no_hands_left: '出牌次数已用完',
+  no_discards_left: '弃牌次数已用完',
+  must_play_5: '本盲注必须出满 5 张牌',
+  invalid_indices: '无效的牌序号',
+  need_5_cards: '请选择 5 张牌',
+  hand_type_already_played: '本轮已出过该牌型',
+  choose_cards: '请指定要弃的牌',
+};
+
+const HAND_ZH = {
+  HighCard: '高牌',
+  Pair: '对子',
+  TwoPair: '两对',
+  ThreeOfAKind: '三条',
+  Straight: '顺子',
+  Flush: '同花',
+  FullHouse: '葫芦',
+  FourOfAKind: '四条',
+  StraightFlush: '同花顺',
+  RoyalFlush: '皇家同花顺',
+};
+
+const BLIND_ZH = { small: '小盲', big: '大盲', boss: '首领' };
+
+function formatHand(hand) {
+  return hand.map((c, i) => `${i + 1}:${formatCard(c)}`).join(' ');
+}
+
+export async function runGame() {
+  const rl = cli.createInterface();
+  log.info('引导', '服务就绪');
+  log.debug('引导', '选项: 新对局 / 继续 / 退出');
+  const menu = await cli.askMainMenu(rl);
+  if (menu === 'exit') {
+    rl.close();
+    return;
+  }
+
+  let runState = {
+    money: STARTING_MONEY,
+    jokers: [],
+    handLevels: {},
+    deckState: deck.createGameDeck(),
+    anteIndex: 0,
+    blindIndex: 0,
+    voucherBoughtThisAnte: false,
+    showHints: process.env.POKER_HIDE_HINTS !== '1',
+  };
+
+  log.info('Gateway', '对局开始', { 底注: 1, 盲注: BLIND_ZH[BLIND_ORDER[0]] || BLIND_ORDER[0] });
+
+  while (runState.anteIndex < ANTES_COUNT) {
+    const blindType = BLIND_ORDER[runState.blindIndex];
+    const blindConfig = getBlindConfig(runState.anteIndex, blindType);
+    runState.bossDebuff = blindConfig.debuff === 'one_hand_type' ? 'one_hand_type' : null;
+
+    log.warn('调度', `盲注=${BLIND_ZH[blindType] || blindType} 底注=${runState.anteIndex + 1} 目标分=${blindConfig.target}`, {
+      出牌次数: blindConfig.hands,
+      弃牌次数: blindConfig.discards,
+    });
+
+    if (blindType !== 'boss') {
+      const skipOrFight = await cli.askSkipOrFight(rl);
+      if (skipOrFight === 'skip') {
+        log.info('Gateway', '已跳过盲注，获得标签');
+        runState.blindIndex++;
+        if (runState.blindIndex >= BLIND_ORDER.length) {
+          runState.blindIndex = 0;
+          runState.anteIndex++;
+          runState.voucherBoughtThisAnte = false;
+        }
+        continue;
+      }
+    }
+
+    const roundState = createRoundState(runState.deckState, blindConfig);
+    let cleared = false;
+    await log.animateDots('发牌中', 900, 180);
+
+    while (roundState.handsLeft > 0 && !cleared) {
+      sortHand(roundState.hand);
+      const slotWidth = 5;
+      const posLine = [1, 2, 3, 4, 5, 6, 7, 8].map((n) => String(n).padEnd(slotWidth)).join('');
+      const cardLine = roundState.hand.map((c) => formatCardPadded(c, slotWidth)).join('');
+      log.info('牌务', '序号 ' + posLine);
+      log.info('牌务', '手牌 ' + cardLine, { 出牌次数: roundState.handsLeft, 弃牌次数: roundState.discardsLeft });
+      log.info('计分', '目标分', { 目标: roundState.target });
+      if (runState.showHints) log.info('提示', '出牌: 5个序号 如 13568 或 1 3 5 6 8 | 弃牌: q+序号 如 q25 或 q 2 5 | /hint 关提示');
+
+      const choice = await cli.askPlayOrDiscard(rl, log);
+      if (choice.action === 'toggleHint') {
+        runState.showHints = !runState.showHints;
+        log.info('提示', runState.showHints ? '已开启提示' : '已关闭提示');
+        continue;
+      }
+      if (choice.action === 'discard') {
+        if (roundState.discardsLeft <= 0) {
+          log.warn('计分', '弃牌次数已用完');
+          continue;
+        }
+        if (choice.indices.length === 0) {
+          if (runState.showHints) log.warn('提示', '请输入要弃的牌序号，例如 q 2 5 或 弃牌 1 3');
+          else log.warn('计分', '弃牌需带序号，如 q 2 5');
+          continue;
+        }
+        const result = doDiscard(roundState, choice.indices);
+        if (result.error) {
+          log.warn('计分', ERROR_MSG[result.error] || result.error);
+          continue;
+        }
+        log.info('牌务', '已弃牌', { 剩余弃牌: roundState.discardsLeft });
+        continue;
+      }
+
+      if (choice.action === 'play') {
+        if (choice.indices.length !== 5) {
+          log.warn('计分', '请输入 5 张牌序号(1-8)', { 示例: '1 3 5 6 8' });
+          continue;
+        }
+        const result = playHand(roundState, runState, choice.indices);
+        if (result.error) {
+          log.warn('计分', ERROR_MSG[result.error] || result.error);
+          continue;
+        }
+        const handName = HAND_ZH[result.handId] || result.handId;
+        const chips = result.result?.chips ?? 0;
+        const mult = result.result?.mult ?? 0;
+        await log.animateScoreResult(handName, chips, mult, result.score, result.target);
+        if (result.cleared) {
+          await log.sleep(180);
+          cleared = true;
+          const moneyEarned = blindType === 'boss' ? 8 : blindType === 'big' ? 5 : 3;
+          runState.money = (runState.money || 0) + moneyEarned;
+          log.info('结算', '结算完成', { 状态: '成功', 获得: moneyEarned, 余额: runState.money });
+          break;
+        }
+      }
+    }
+
+    if (!cleared) {
+      log.error('Gateway', '盲注未通过', { 底注: runState.anteIndex + 1, 盲注: BLIND_ZH[blindType] || blindType });
+      rl.close();
+      return;
+    }
+
+    if (runState.anteIndex === ANTES_COUNT - 1 && blindType === 'boss') {
+      log.info('引导', '对局完成，胜利。');
+      rl.close();
+      return;
+    }
+
+    runState.blindIndex++;
+    if (runState.blindIndex >= BLIND_ORDER.length) {
+      runState.blindIndex = 0;
+      runState.anteIndex++;
+      runState.voucherBoughtThisAnte = false;
+    }
+
+    log.info('Gateway', '盲注通过，进入商店', { 底注: runState.anteIndex + 1 });
+    await log.sleep(200);
+    const shopState = shop.createShopState(runState);
+    let leave = false;
+    while (!leave) {
+      if (runState.showHints) log.info('提示', '可选: 1/2 买小丑 p 星球牌 v 优惠券 r 刷新 s1/s2… 出售小丑 q 离开');
+      log.info('商店', '当前', {
+        金钱: runState.money,
+        已装备小丑: runState.jokers.map((j) => j.nameZh || j.name),
+        可购: shopState.jokers.map((j) => `${j.nameZh || j.name} ¥${j.price}`),
+      });
+      const sel = await cli.askShopChoice(rl, shopState, runState);
+      if (sel.action === 'leave') leave = true;
+      else if (sel.action === 'joker') {
+        const j = shopState.jokers[sel.index];
+        if (shop.buyJoker(runState, j)) {
+          shopState.jokers = shopState.jokers.filter((_, i) => i !== sel.index);
+          log.info('库存', '已购买小丑牌', { 槽位: runState.jokers.length });
+        } else log.warn('商店', '无法购买', { 原因: '金钱不足或槽位已满' });
+      } else if (sel.action === 'planet' && shopState.planet && shopState.planet[0]) {
+        const p = shopState.planet[0];
+        if (shop.buyPlanet(runState, p)) {
+          shopState.planet = [];
+          log.info('库存', '已使用星球牌', { 牌型: HAND_ZH[p.handId] || p.handId });
+        } else log.warn('商店', '无法购买', { 原因: '金钱不足' });
+      } else if (sel.action === 'voucher' && shopState.voucher) {
+        const v = shopState.voucher;
+        if (shop.buyVoucher(runState, v)) {
+          shopState.voucher = null;
+          log.info('库存', '已使用优惠券', { 类型: v?.nameZh || v?.name || '空白' });
+        } else log.warn('商店', '无法购买', { 原因: '金钱不足或本底注已买过' });
+      } else if (sel.action === 'refresh') {
+        if (shop.refreshShop(shopState, runState)) log.info('商店', '已刷新');
+        else log.warn('商店', '金钱不足');
+      } else if (sel.action === 'sellJoker') {
+        const sold = shop.sellJoker(runState, sel.index);
+        if (sold.ok) log.info('库存', '已出售小丑牌', { 获得: sold.money, 余额: runState.money });
+        else log.warn('商店', '无法出售');
+      }
+    }
+  }
+
+  rl.close();
+}

package/src/jokers.js

@@ -0,0 +1,98 @@
+/**
+ * Joker definitions: id, name, price, effect (addChips, addMult, multMult, or conditional).
+ * Effects applied left-to-right; order matters (chips left, mult middle, xMult right).
+ */
+
+/** Base chips and mult per hand at level 1 (Balatro). */
+export const HAND_BASE = {
+  HighCard: { chips: 5, mult: 1 },
+  Pair: { chips: 10, mult: 2 },
+  TwoPair: { chips: 20, mult: 2 },
+  ThreeOfAKind: { chips: 30, mult: 3 },
+  Straight: { chips: 30, mult: 4 },
+  Flush: { chips: 35, mult: 4 },
+  FullHouse: { chips: 40, mult: 4 },
+  FourOfAKind: { chips: 60, mult: 7 },
+  StraightFlush: { chips: 100, mult: 8 },
+  RoyalFlush: { chips: 100, mult: 8 },
+};
+
+/** Planet per-level bonus: +chips, +mult (e.g. Pluto: +10 chips, +1 mult per level). */
+export const PLANET_PER_LEVEL = {
+  HighCard: { chips: 10, mult: 1 },
+  Pair: { chips: 15, mult: 1 },
+  TwoPair: { chips: 20, mult: 1 },
+  ThreeOfAKind: { chips: 20, mult: 2 },
+  Straight: { chips: 30, mult: 3 },
+  Flush: { chips: 15, mult: 2 },
+  FullHouse: { chips: 25, mult: 2 },
+  FourOfAKind: { chips: 30, mult: 3 },
+  StraightFlush: { chips: 40, mult: 4 },
+  RoyalFlush: { chips: 40, mult: 4 },
+};
+
+const JOKERS = [
+  { id: 'Joker_Base', name: 'Base Joker', nameZh: '基础小丑', price: 2, effect: 'addMult', value: 4 },
+  { id: 'Joker_PlusChips', name: 'Plus Chips', nameZh: '加筹码', price: 3, effect: 'addChips', value: 20 },
+  { id: 'Joker_PlusMult', name: 'Plus Mult', nameZh: '加倍率', price: 4, effect: 'addMult', value: 3 },
+  { id: 'Joker_TimesMult', name: 'Times Mult', nameZh: '乘倍率', price: 5, effect: 'multMult', value: 2 },
+  { id: 'Joker_Pair', name: 'Pair Bonus', nameZh: '对子加成', price: 4, effect: 'conditionalMult', condition: 'handId', handId: 'Pair', value: 5 },
+  { id: 'Joker_Three', name: 'Three Bonus', nameZh: '三条加成', price: 5, effect: 'conditionalMult', condition: 'handId', handId: 'ThreeOfAKind', value: 8 },
+  { id: 'Joker_Flush', name: 'Flush Bonus', nameZh: '同花加成', price: 5, effect: 'conditionalMult', condition: 'handId', handId: 'Flush', value: 10 },
+  { id: 'Joker_Straight', name: 'Straight Chips', nameZh: '顺子筹码', price: 4, effect: 'conditionalChips', condition: 'handId', handId: 'Straight', value: 80 },
+  { id: 'Joker_NoDiscard', name: 'No Discard', nameZh: '未弃牌', price: 6, effect: 'conditionalMult', condition: 'discardsLeft', value: 15 },
+  { id: 'Joker_EveryJoker', name: 'Per Joker', nameZh: '每张小丑', price: 5, effect: 'perJokerMult', value: 2 },
+];
+
+export function getJokerPool() {
+  return [...JOKERS];
+}
+
+export function getJokerById(id) {
+  return JOKERS.find((j) => j.id === id) || null;
+}
+
+export function getRandomJokers(pool, count, excludeIds = []) {
+  const available = pool.filter((j) => !excludeIds.includes(j.id));
+  const shuffled = [...available].sort(() => Math.random() - 0.5);
+  return shuffled.slice(0, count);
+}
+
+/**
+ * Apply a single joker to current chips and mult. Modifies state in place; returns same object.
+ */
+export function applyJoker(joker, state) {
+  const { chips, mult, handId, discardsLeft, totalJokers } = state;
+  let addC = 0;
+  let addM = 0;
+  let mulM = 1;
+
+  switch (joker.effect) {
+    case 'addChips':
+      addC = joker.value ?? 0;
+      break;
+    case 'addMult':
+      addM = joker.value ?? 0;
+      break;
+    case 'multMult':
+      mulM = joker.value ?? 1;
+      break;
+    case 'conditionalMult':
+      if (joker.condition === 'handId' && handId === joker.handId) addM = joker.value ?? 0;
+      if (joker.condition === 'discardsLeft' && discardsLeft > 0) addM = joker.value ?? 0;
+      break;
+    case 'conditionalChips':
+      if (joker.condition === 'handId' && handId === joker.handId) addC = joker.value ?? 0;
+      break;
+    case 'perJokerMult':
+      addM = (totalJokers ?? 0) * (joker.value ?? 0);
+      break;
+    default:
+      break;
+  }
+
+  state.chips = chips + addC;
+  state.mult = mult + addM;
+  state.mult = Math.floor(state.mult * mulM);
+  return state;
+}

package/src/logStyle.js

@@ -0,0 +1,92 @@
+/**
+ * Server-log style formatter: [ISO time] LEVEL [Component] message
+ * All game output goes through this to look like monitoring logs.
+ */
+
+function log(level, component, message, data) {
+  const time = new Date().toISOString();
+  const line = `[${time}] ${level} [${component}] ${message}` + (data != null && typeof data === 'object' && Object.keys(data).length > 0 ? ' ' + JSON.stringify(data) : '');
+  console.log(line);
+}
+
+export default {
+  debug(component, message, data) {
+    log('DEBUG', component, message, data);
+  },
+  info(component, message, data) {
+    log('INFO', component, message, data);
+  },
+  warn(component, message, data) {
+    log('WARN', component, message, data);
+  },
+  error(component, message, data) {
+    log('ERROR', component, message, data);
+  },
+  /** Optional: log with short delay for "streaming" feel (ms) */
+  async infoDelayed(component, message, data, delayMs = 50) {
+    await new Promise((r) => setTimeout(r, delayMs));
+    this.info(component, message, data);
+  },
+  /** Sleep for transition / animation (ms) */
+  async sleep(ms) {
+    await new Promise((r) => setTimeout(r, ms));
+  },
+  /**
+   * 终端点动画：同一行循环显示 prefix + . / .. / ...
+   * @param {string} prefix 如 "发牌中" "结算中"
+   * @param {number} durationMs 总时长
+   * @param {number} stepMs 每步间隔
+   */
+  async animateDots(prefix, durationMs = 800, stepMs = 160) {
+    process.stdout.write('\n');
+    const steps = Math.max(1, Math.floor(durationMs / stepMs));
+    for (let i = 0; i < steps; i++) {
+      const dots = '.'.repeat((i % 3) + 1);
+      const time = new Date().toISOString();
+      const line = `[${time}] INFO [牌务] ${prefix}${dots}`;
+      process.stdout.write(line.padEnd(78));
+      await new Promise((r) => setTimeout(r, stepMs));
+      if (i < steps - 1) process.stdout.write('\r');
+    }
+    process.stdout.write('\r' + ' '.repeat(78) + '\r');
+  },
+  async animateSettling(durationMs = 500, stepMs = 140) {
+    process.stdout.write('\n');
+    const prefix = '结算中';
+    const steps = Math.max(1, Math.floor(durationMs / stepMs));
+    for (let i = 0; i < steps; i++) {
+      const dots = '.'.repeat((i % 3) + 1);
+      const time = new Date().toISOString();
+      const line = `[${time}] INFO [计分] ${prefix}${dots}`;
+      process.stdout.write(line.padEnd(78));
+      await new Promise((r) => setTimeout(r, stepMs));
+      if (i < steps - 1) process.stdout.write('\r');
+    }
+    process.stdout.write('\r' + ' '.repeat(78) + '\r');
+  },
+  /**
+   * 计分动画：先出牌型与筹码倍率，再小丑结算中，最后得分从 0 跳到目标值
+   */
+  async animateScoreResult(handName, chips, mult, finalScore, target) {
+    const time = () => new Date().toISOString();
+    process.stdout.write('\n');
+    process.stdout.write(`[${time()}] INFO [计分] 牌型=${handName} 筹码=${chips} 倍率=${mult}\n`);
+    await new Promise((r) => setTimeout(r, 180));
+    process.stdout.write(`[${time()}] INFO [计分] 小丑牌结算中`);
+    for (let i = 0; i < 4; i++) {
+      await new Promise((r) => setTimeout(r, 120));
+      process.stdout.write('.');
+    }
+    process.stdout.write('\r' + ' '.repeat(60) + '\r');
+    const steps = 14;
+    const stepMs = 45;
+    const prefix = `[${time()}] INFO [计分] 牌型=${handName} 得分=`;
+    for (let i = 0; i <= steps; i++) {
+      const current = i === steps ? finalScore : Math.floor((finalScore * (i + 1)) / (steps + 1));
+      process.stdout.write(prefix + String(current).padStart(6) + ` 目标=${target}`);
+      await new Promise((r) => setTimeout(r, stepMs));
+      if (i < steps) process.stdout.write('\r');
+    }
+    process.stdout.write('\n');
+  },
+};

package/src/round.js

@@ -0,0 +1,70 @@
+/**
+ * Single blind round: 8 cards in hand, limited hands/discards, play or discard until target met or out of attempts.
+ */
+
+import * as deck from './deck.js';
+import { computeScore } from './scoring.js';
+import { getBlindConfig } from './blinds.js';
+
+/**
+ * Run one round. Returns { cleared: boolean, score?: number, handId?, target }.
+ * state: { deckState, handLevels, jokers }
+ * onPlay(cards, result), onDiscard(handAfter) for logging; ask() for user input (handled by cli).
+ */
+export function createRoundState(deckState, blindConfig) {
+  const hand = deck.dealHand(deckState);
+  return {
+    deckState,
+    hand,
+    handsLeft: blindConfig.hands,
+    discardsLeft: blindConfig.discards,
+    target: blindConfig.target,
+    debuff: blindConfig.debuff,
+    playedHandTypes: new Set(),
+    mustPlay5: blindConfig.debuff === 'must_play_5',
+  };
+}
+
+/**
+ * Play 5 cards (or fewer for high card/pair if not mustPlay5). Returns { cleared, score, handId } or error.
+ */
+export function playHand(roundState, state, indices) {
+  const { deckState, hand, handsLeft, discardsLeft, target, playedHandTypes, mustPlay5 } = roundState;
+  if (handsLeft <= 0) return { error: 'no_hands_left' };
+  if (indices.length !== 5 && mustPlay5) return { error: 'must_play_5' };
+  if (indices.some((i) => i < 0 || i >= hand.length)) return { error: 'invalid_indices' };
+  const cards = indices.map((i) => hand[i]).filter(Boolean);
+  if (cards.length !== 5) return { error: 'need_5_cards' };
+
+  const result = computeScore(cards, state.handLevels || {}, state.jokers || [], { discardsLeft });
+  const alreadyPlayed = playedHandTypes.has(result.handId);
+  if (state.bossDebuff === 'one_hand_type' && alreadyPlayed) return { error: 'hand_type_already_played' };
+
+  roundState.handsLeft--;
+  roundState.playedHandTypes.add(result.handId);
+  const newHand = deck.playCards(deckState, hand, indices);
+  roundState.hand = newHand;
+
+  const cleared = result.score >= target;
+  return { cleared, score: result.score, handId: result.handId, target, result };
+}
+
+/**
+ * Discard by indices, refill hand. Returns { success } or error.
+ */
+export function doDiscard(roundState, indices) {
+  const { deckState, hand, discardsLeft } = roundState;
+  if (discardsLeft <= 0) return { error: 'no_discards_left' };
+  if (indices.length === 0) return { error: 'choose_cards' };
+  if (indices.some((i) => i < 0 || i >= hand.length)) return { error: 'invalid_indices' };
+
+  roundState.discardsLeft--;
+  roundState.hand = deck.discardCards(deckState, hand, indices);
+  return { success: true };
+}
+
+export function isRoundOver(roundState, state) {
+  const { handsLeft, target } = roundState;
+  if (handsLeft <= 0) return { lost: true };
+  return { lost: false };
+}

package/src/scoring.js

@@ -0,0 +1,64 @@
+/**
+ * Score = chips * mult. Base from hand type + level, then card chip values, then jokers left-to-right.
+ */
+
+import { cardChipValue } from './deck.js';
+import { evaluateHand } from './handRank.js';
+import { HAND_BASE, PLANET_PER_LEVEL, applyJoker } from './jokers.js';
+
+export function getHandBaseChipsMult(handId, level = 1) {
+  const base = HAND_BASE[handId] || { chips: 5, mult: 1 };
+  const perLevel = PLANET_PER_LEVEL[handId] || { chips: 0, mult: 0 };
+  const chips = base.chips + (level - 1) * (perLevel.chips || 0);
+  const mult = base.mult + (level - 1) * (perLevel.mult || 0);
+  return { chips, mult };
+}
+
+/**
+ * Compute chips from scoring cards only (hand-dependent: high card 1 card, pair 2+3 kickers, etc.).
+ */
+export function chipsFromCards(scoringCards) {
+  if (!scoringCards || scoringCards.length === 0) return 0;
+  return scoringCards.reduce((sum, c) => sum + cardChipValue(c.rank), 0);
+}
+
+/**
+ * Full score for a played hand.
+ * @param {Object[]} cards - 5 cards played
+ * @param {Object} handLevels - { HandId: level } e.g. { Pair: 2, HighCard: 1 }
+ * @param {Object[]} jokers - equipped jokers in order
+ * @param {Object} context - { discardsLeft }
+ */
+export function computeScore(cards, handLevels = {}, jokers = [], context = {}) {
+  if (!cards || cards.length !== 5) return { score: 0, handId: 'HighCard', chips: 0, mult: 0 };
+  const evaluated = evaluateHand(cards);
+  const handId = evaluated.handId;
+  const level = handLevels[handId] ?? 1;
+  const base = getHandBaseChipsMult(handId, level);
+  let chips = base.chips + chipsFromCards(evaluated.scoringCards);
+  let mult = base.mult;
+
+  const state = {
+    chips,
+    mult,
+    handId,
+    discardsLeft: context.discardsLeft ?? 0,
+    totalJokers: jokers.length,
+  };
+
+  for (const j of jokers) {
+    applyJoker(j, state);
+    chips = state.chips;
+    mult = state.mult;
+  }
+
+  const score = Math.floor(chips * mult);
+  return {
+    score,
+    handId,
+    level,
+    chips: state.chips,
+    mult: state.mult,
+    scoringCards: evaluated.scoringCards,
+  };
+}

package/src/shop.js

@@ -0,0 +1,105 @@
+/**
+ * Shop after clearing a blind: buy jokers, planet cards, tarot/spectral, vouchers; refresh.
+ */
+
+import { getJokerPool, getRandomJokers } from './jokers.js';
+import { PLANET_PER_LEVEL } from './jokers.js';
+
+const JOKER_SLOT_MAX = 5;
+const PLANET_IDS = [
+  'Pluto', 'Mercury', 'Uranus', 'Venus', 'Saturn', 'Jupiter', 'Earth', 'Mars', 'Neptune'
+];
+const HAND_IDS_FOR_PLANET = [
+  'HighCard', 'Pair', 'TwoPair', 'ThreeOfAKind', 'Straight', 'Flush', 'FullHouse', 'FourOfAKind', 'StraightFlush'
+];
+
+export function createShopState(runState) {
+  const pool = getJokerPool();
+  const jokers = getRandomJokers(pool, 3, (runState.jokers || []).map((j) => j.id));
+  const planetList = PLANET_IDS.map((id, i) => ({
+    id,
+    handId: HAND_IDS_FOR_PLANET[i],
+    price: 4,
+  }));
+  const planet = planetList[Math.floor(Math.random() * planetList.length)];
+  return {
+    jokers: jokers.slice(0, 2),
+    planet: planet ? [planet] : [],
+    voucher: runState.voucherBoughtThisAnte ? null : { id: 'Blank', name: '+1 小丑槽位', nameZh: '+1 小丑槽位', price: 10 },
+    refreshCost: 5, // 与 Balatro 一致：刷新起价 5，每次 +1，进新商店重置
+  };
+}
+
+export function canBuyJoker(runState, joker) {
+  if (!joker) return false;
+  const current = runState.jokers || [];
+  const maxSlots = runState.jokerSlots ?? JOKER_SLOT_MAX;
+  if (current.length >= maxSlots) return false;
+  return (runState.money || 0) >= joker.price;
+}
+
+export function buyJoker(runState, joker) {
+  if (!canBuyJoker(runState, joker)) return { ok: false };
+  runState.money = (runState.money || 0) - joker.price;
+  runState.jokers = [...(runState.jokers || []), joker];
+  return { ok: true };
+}
+
+/** 出售小丑：售价 = floor(购买价/2)，最低 1（与 Balatro 一致） */
+export function sellJoker(runState, index) {
+  const list = runState.jokers || [];
+  if (index < 0 || index >= list.length) return { ok: false, money: 0 };
+  const sold = list[index];
+  const buyCost = sold.price || 2;
+  const money = Math.max(1, Math.floor(buyCost / 2));
+  runState.money = (runState.money || 0) + money;
+  runState.jokers = list.filter((_, i) => i !== index);
+  return { ok: true, money };
+}
+
+export function canBuyPlanet(runState, planet) {
+  if (!planet) return false;
+  return (runState.money || 0) >= (planet.price || 4);
+}
+
+export function buyPlanet(runState, planet) {
+  if (!canBuyPlanet(runState, planet)) return { ok: false };
+  runState.money = (runState.money || 0) - (planet.price || 4);
+  const handId = planet.handId || planet.id;
+  runState.handLevels = runState.handLevels || {};
+  runState.handLevels[handId] = (runState.handLevels[handId] || 1) + 1;
+  return { ok: true };
+}
+
+export function canBuyVoucher(runState, voucher) {
+  if (!voucher) return false;
+  if (runState.voucherBoughtThisAnte) return false;
+  return (runState.money || 0) >= (voucher.price || 10);
+}
+
+export function buyVoucher(runState, voucher) {
+  if (!canBuyVoucher(runState, voucher)) return { ok: false };
+  runState.money = (runState.money || 0) - (voucher.price || 10);
+  runState.voucherBoughtThisAnte = true;
+  if (voucher.id === 'Blank') runState.jokerSlots = (runState.jokerSlots || JOKER_SLOT_MAX) + 1;
+  return { ok: true };
+}
+
+export function refreshShop(shopState, runState) {
+  const cost = shopState.refreshCost ?? 5;
+  if ((runState.money || 0) < cost) return { ok: false };
+  runState.money = runState.money - cost;
+  shopState.refreshCost = (shopState.refreshCost ?? 5) + 1;
+  const pool = getJokerPool();
+  shopState.jokers = getRandomJokers(pool, 2, (runState.jokers || []).map((j) => j.id));
+  const planets = PLANET_IDS.map((id, i) => ({
+    id: HAND_IDS_FOR_PLANET[i],
+    handId: HAND_IDS_FOR_PLANET[i],
+    price: 4,
+  }));
+  const planet = planets[Math.floor(Math.random() * planets.length)];
+  shopState.planet = planet ? [planet] : [];
+  return { ok: true };
+}
+
+export const JOKER_SLOT_MAX_EXPORT = JOKER_SLOT_MAX;