huajishe-tts/docs/dev-log/13-holdem-game.md

13 · 德州扑克（Holdem）游戏

做什么

用户要求在 tts-like 里扩充一个德州扑克对局游戏，最多 9 人入座，按德州扑克规则（盲注 / 翻牌 / 转牌 / 河牌 / 摊牌）走完整一手牌。

这是 dev-log 12 末尾记的"加新游戏不是调 Lua 文件"那条路径的首次落地：纯 TypeScript 写 reducer + 自定义 React 牌桌 + 隐藏信息（每人只看自己底牌）。

范围

• 引擎：packages/engine/src/games/holdem.ts + holdem-eval.ts
• UI：apps/web/src/HoldemBoard.tsx（自定义牌桌，不复用通用 <Board>）
• 大厅：packages/ui/src/LobbyRoomList.tsx 支持 2..9 可变人数 + setupData 表单
• App：apps/web/src/App.tsx 注册 holdem + 本地 9 座切换 / 联机可变人数
• 测试：holdem.test.ts（25 用例）+ holdem-eval.test.ts（16 用例）+ holdem-multiplayer.spec.ts（E2E）

设计要点

1. 牌型评估器（holdem-eval.ts，纯函数）

• evaluate5/evaluate7：7 张牌取最大 5 张组合，返回 Evaluation { category, kickers }
• compareHands：类别 → kicker 逐位比
• makeDeck：52 张 ♠♥♦♣ × 13 点
• cardLabel：中文牌面（"红桃 A"、"方块 10"）
• 10 个类别常量（CATEGORY_HIGH_CARD .. CATEGORY_ROYAL_FLUSH）

2. 引擎（holdem.ts）

State（HoldemState）：房间配置（startingStack / smallBlind / bigBlind）+ players: Record<string, HoldemPlayer> + 牌局进行（deck/hands 为 SECRET）+ results: HoldemResults | null。

Phase 机（5 阶段）：

waiting → (startHand move) → preflop → flop → turn → river → showdown → waiting
                                                              ↑ fold-win 也走这里

Move（8 个）：sitDown / startHand / fold / check / call / raise / allIn（raise 别名）/ sitDown。全部 client: false（不在 turn.activePlayers 内的玩家调会被拒）。

隐藏信息：playerView 剥掉 deck / hands，只注入当前玩家自己的 myHand。摊牌时 results.revealedHands 才把所有人的底牌公开。

盲注 / 按钮轮转：dealerButton 每手 +1（mod seatedWithChips），SB = nextSeat(button)，BB = nextSeat(SB)。heads-up 时 SB 先行动（标准规则）。

边池结算：buildPots 按 totalBetThisHand 分层，resolveHand 对每层跑 evaluate7，并列赢家平分。

局终 endIf：只在 showdown/waiting 且 handNumber > 0 时判定 seatedWithChips.length === 1。开局没人入座不算局终。

validateSetupData：校验 startingStack/smallBlind/bigBlind 为正整数且 bigBlind >= smallBlind，非法返回 400。

3. UI（HoldemBoard.tsx）

• 椭圆桌 + N 座位按角度环形分布（seatPos(idx, N)）
• 每座显示名字 / 筹码 / 本街下注 / 状态徽章（D/SB/BB/弃牌/ALL-IN/行动中）/ 底牌
• 中央公共牌 + 底池；底部行动条（弃牌 / 过牌 / 跟注 / 加注 slider / 全下）
• waiting 阶段：就座 + 开始按钮（房主可见，eligibleCount >= 2 才 enable）
• showdown：结果面板（每个 pot 的赢家 / 牌型名）+ 日志面板
• 自动入座：mount 时若未入座自动 sitDown

4. 大厅可变人数（LobbyRoomList.tsx）

新增 props：

• maxSeats：座位上限（holdem=9，其余=2）
• setupOptions：创建表单选项（holdem 的筹码 / 小盲 / 大盲）
• onSelect 回调加 numPlayers 参数，供上层 Client({ numPlayers }) 用

创建表单：maxSeats > 2 时显示座位选择器（2..9）+ setupData 输入框。加入按钮从硬编码 P0/P1 改为遍历 m.players 动态渲染 P0..P(n-1)。

5. App.tsx

GAMES record 扩展为 GameMeta：{ game, name, engineName, maxSeats, setupOptions }。

• HoldemLocalView：9 座切换调试（下拉选 P0..P8，key={seat} 重建 Client 触发 playerView 重算）
• HoldemOnlineView：config.numPlayers 驱动 Client({ numPlayers })，切房间若 numPlayers 变化则重建 Client

OnlineConfig 加 numPlayers 字段，创建/加入时由 LobbyRoomList 写入。

遇到什么问题

问题 1：机器重启导致 HoldemBoard.tsx 末尾 128 字节 NULL

上一轮会话最后正在写 HoldemBoard.tsx 时机器重启，文件末尾被填充了 128 字节 0x00（wc -c = 16161，最后 128 字节全是 NULL）。TypeScript 报 TS1127: Invalid character 在第 427 行的 128 个字符上。

修法：data.rstrip(b'\x00') 清掉尾部 NULL，文件实际内容到第 426 行 }; 完整结束。教训：跨会话恢复时先 xxd 检查文件末尾是否有 NULL，TypeScript 的"Invalid character"往往是 NULL 字节而非编码问题。

问题 2：ViewG 不能赋给 HoldemState（playerView 剥了 deck/hands）

HoldemBoard 拿到的 G 是 playerView 剥过 secret 的 ViewG = Omit<HoldemState,'deck'|'hands'> & { myHand }，但 HOLDEM_HELPERS.host(G) / seatedWithChips(G) / nextSeat(G,...) 的签名是 G: HoldemState → TS 报 ViewG is missing properties: deck, hands。

修法：引擎新增 export type HoldemView = Omit<HoldemState, 'deck' | 'hands'>，把只读 helper（pids / nameOf / canAct / unfoldedPids / handOver / host / seatedWithChips / nextSeat / nextActor / eligibleCount）的签名从 HoldemState 放宽到 HoldemView。这些函数只读 G.players（+ G.acted/G.currentBet，都在 HoldemView 里），结构类型让 HoldemState 和 ViewG 都自动满足。buildPots / resolveHand 读 hands，保持 HoldemState 不变。

好处：UI 无需 as HoldemState 强转，类型安全 + playerView 保密约束在编译期可见。

问题 3：pnpm dev / pnpm start 在新 shell 找不到 pnpm

重启后新 shell 没有加载 nvm，which pnpm 报 NOT FOUND。

修法：export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"; corepack enable。corepack enable 在 node bin 目录创建 pnpm shim，之后 pnpm / pnpm -r ts 正常。见 lessons-learned §1.1。

问题 4：heads-up 先行动者判定

2 人房时按钮位 = P0，nextSeat(P0) = P1（SB），nextSeat(P1) = P0（BB）。firstToAct = nextSeat(BB) = nextSeat(P0) = P1。所以 heads-up preflop P1（SB）先行动——符合标准规则（SB 先动 preflop，BB 先动 flop+）。E2E 据此让 P1 弃牌结束一手。

怎么解决（具体做法）

引擎层

packages/engine/src/games/holdem.ts：

• HoldemView 类型 + 5 个 phase + 8 个 move + validateSetupData + playerView + 边池结算
• HOLDEM_HELPERS 导出纯查询函数给 UI / 测试复用

packages/engine/src/games/holdem-eval.ts：

• 纯函数评估器，无状态，可独立单测

UI 层

apps/web/src/HoldemBoard.tsx：426 行，椭圆桌 SVG + 行动条 + 结果面板 + 日志。WaitingControls 子组件管就座 / 开始。

packages/ui/src/LobbyRoomList.tsx：可变人数 + setupData 表单 + 动态加入按钮。

apps/web/src/App.tsx：HoldemLocalView / HoldemOnlineView + GameMeta 元数据 + OnlineConfig.numPlayers。

测试

• holdem-eval.test.ts：16 用例（类别排序 / wheel / 踢脚 / 平局 / 中文名）
• holdem.test.ts：25 用例（盲注 / fold-win / 全下 / 边池 / 按钮轮转 / 局终 / validateSetupData）
• holdem-multiplayer.spec.ts：E2E 走完一手 heads-up（创建 → 加入 → 就座 → 开始 → 弃牌胜 → 回 waiting）

成果

• 全量验证：
  • pnpm -r ts 5/5 包通过
  • pnpm -r test engine 75 + server 9 = 84 通过
  • pnpm test:e2e 5/5 通过（含新 holdem + 既有 war/mill/drag-test 未回归）
• 文件清单：
  • 新增 packages/engine/src/games/holdem.ts（~840 行）
  • 新增 packages/engine/src/games/holdem-eval.ts（~200 行）
  • 新增 packages/engine/src/games/holdem.test.ts + holdem-eval.test.ts
  • 新增 apps/web/src/HoldemBoard.tsx（426 行）
  • 新增 apps/web/e2e/holdem-multiplayer.spec.ts
  • 改 packages/ui/src/LobbyRoomList.tsx（可变人数 + setupData）
  • 改 apps/web/src/App.tsx（注册 holdem + HoldemLocalView/OnlineView）
  • 改 packages/server/src/index.ts（games 数组加 Holdem，已在上轮完成）

关联

• 12-unified-port-and-player-names.md — 命名系统为本游戏打基础
• lessons-learned §12.1-12.3 — 本轮的坑（NULL 损坏 / HoldemView / pnpm）
• decisions D30-D32 — HoldemView 类型、可变人数大厅、9 座本地切换