掼蛋大师 (Guandan Master)

Language / 语言

• 简体中文（当前）：README.md
• English: README.en.md
• Русский: README.ru.md
• 日本語: README.ja.md
• 한국어: README.ko.md

一个以本地对战为核心、支持局域网联机的掼蛋项目。
目标是把“规则正确、节奏顺畅、AI可对抗、可持续演进”这四件事同时做好。

项目亮点

• 完整对局流程：发牌、出牌、过牌、接风、结算、升级、进贡/还贡。
• A关卡规则：支持打A过关、失败降级、三次不过回2等机制。
• 四档AI难度：easy / medium / hard / master，策略逐层增强。
• 终局体验：胜利结算页、动画表现、关键结果文案强化。
• 桌面发布能力：支持 Electron 打包为 Windows 可执行版本。

游戏玩法说明

1. 基本目标

• 四人两队，队友相对而坐。
• 通过出牌竞争名次，按名次组合决定本局升级与下一局节奏。
• 以“先过关到A并完成A关卡”作为核心胜负目标。

2. 出牌与回合

• 支持常见掼蛋牌型（单张、对子、三张、顺子、连对、钢板、炸弹等）。
• 每轮按顺时针行动，需跟同类型且更大的牌；无法跟牌可选择 Pass。
• 当其他三家都 Pass 时，最后出牌者获得新一轮首发权（接风）。

3. 升级与A关卡

• 普通级别按当局名次组合升级。
• 到达 A 后进入冲关局，只有满足“头游+二游（双下）”或“头游+三游（单下）”才算过A并终局获胜。
• 若冲A失败，触发降级逻辑；支持连续失败递进降级与“三次不过回2”。

4. 进贡与还贡

• 根据上局名次触发进贡/还贡流程。
• 还贡后，首发权由规则决定（包含抗贡分支）。
• AI已接入该阶段上下文，在“还贡开局”与“抗贡开局”采用不同策略倾向。

AI 策略设计

难度分层

• easy：规则正确 + 基础跟牌，保留明显失误，适合新手。
• medium：加入协同意识与基础收益判断，减少无意义压队友和无收益炸弹。
• hard：加入 1-2 轮前瞻，优化接风后首发型与中后盘控节奏。
• master：强化残局搜索与对手建模，重点处理临门拦截、骗炸反制、尾盘收官。

当前核心策略点

• 记牌与概率估计：动态统计关键牌暴露信息，评估抢控与放权。
• 协同信号：队友领先时降侵略，队友临门时优先喂节奏。
• 控制链优先：首发优先可连续控权的复合牌型。
• 炸弹经济学：仅在“保队友、断对手、炸后可续控”三类高收益场景主动炸。
• 终局特化：小手牌阶段切换尾盘策略，减少死尾与失误。
• A关卡特化：将冲A成功率纳入策略目标，必要时接受短期让利换整体胜率。

技术栈

• 前端：React 18 + TypeScript + Vite
• 状态管理：Zustand
• 动画与UI：Framer Motion + Tailwind CSS
• 联机通信：Socket.IO（客户端 + Node服务端）
• 桌面打包：Electron + electron-builder

目录结构

src/
  components/   对局与通用组件
  pages/        场景页面（主菜单、对局、结算、联机等）
  store/        全局状态与游戏流程
  lib/          规则引擎、AI分层策略、音频与工具
  workers/      AI Worker 计算线程
  types/        领域模型类型定义
server/         联机服务端
main.js         Electron 主进程入口

快速开始

1) 安装依赖

npm install

2) 启动前端开发环境

npm run dev

• 默认访问地址通常为 http://localhost:5173/。

3) 启动联机服务（可选）

node server/index.js

• 默认端口 3001。

4) 质量检查

npm run check
npm run lint

5) 构建与打包

npm run build
npm run electron:build:win

开源协议

本项目采用 Apache-2.0 协议开源。

欢迎讨论与共建

如果你也是掼蛋爱好者，欢迎提出你最关心的问题或建议：

• 哪些规则细节还可以更贴近你本地牌桌习惯？
• 你希望AI在哪些场景更“像人”、更有压迫感？
• 是否需要加入更多赛事模式、数据复盘、对局回放功能？

欢迎提交 Issue / PR，也欢迎在讨论区分享你的实战牌例，一起把这个项目打磨成更强的掼蛋开源作品。