中文 | English
本指南分两部分:第一部分给只想下棋的玩家,第二部分给想改代码、做二次开发的开发者。 开头的公共部分两边都建议读一下。
ChessCheers 是一个跑在浏览器里的国际象棋应用,有两种玩法:
- 人 vs 机:你和 Stockfish 引擎对弈,难度可调
- 人 vs 人:同一台设备上黑白轮流走,适合摆棋和练习
它首先是一个同人游戏。 棋子立绘与语音来自手机游戏《明日方舟》,作者出于对该游戏与国际象棋的喜爱而制作,与官方无任何关联。项目底层基于国际象棋引擎 Stockfish 完成算棋,用 Chess.js 管理行棋规则。
其次它是一个通用框架。 棋子和棋盘全部来自 data/ 目录下的素材文件——理论上只要按规范替换图片、动画与音频,就能让任何自定义角色与棋盘出现在游戏里,换成你自己的 IP、原创角色或纯几何棋子都可以。
素材的版权归属与使用限制见 许可与声明,使用或分发前请务必阅读。
推荐本地运行。网页版的素材与 AI 引擎全靠网络下载,网速不稳时体验会明显打折,详见方式二。
方式一:本地启动(推荐)
git clone https://github.com/Schlampig/ChessCheers.git
cd ChessCheers
node tools/serve.js浏览器会自动打开 http://127.0.0.1:8766/。
当前稳定版本为 v1.0.1(Releases 页始终为最新版)。 想固定版本可
git checkout v1.0.1;不用 git 时,从该页下载源码包解压即可运行。
⚠️ 不要直接双击code/html/index.html。file://协议下浏览器会拦截 Web Worker,AI 引擎起不来,你将只能看到棋盘而不能和机器对弈。 必须通过上面的 HTTP 方式访问。
方式二:在线访问
打开项目部署地址(形如 https://<用户名>.github.io/ChessCheers/)即可,无需安装任何东西。
⚠️ 网页版需要网速流畅才能畅玩:首次打开要下载棋盘、棋子预览图与 AI 引擎, 网络较差时可能要等十几秒,棋子动画会滞后,甚至听得到语音却看不到动画。 想稳定对弈请用方式一。
| 概念 | 是什么 | 在哪里 |
|---|---|---|
| 阵营 | 一套棋子皮肤:6 种棋子 × 3 种状态的动画与语音,外加胜负结算插画 | data/chesspiece/<阵营名>/ |
| 棋盘 | 一张正方形(严格 1:1)的图片 | data/chessboard/<名字>.webp |
| 棋谱 | 按国际象棋标准记谱法记录的走法,如 1. e4 e5 2. Nf3 |
对弈页右侧边栏 |
┌──────────────┐
│ 首页 index │ 选阵营 / 棋盘 / 模式 / 难度
└──────┬───────┘
│ 开始对局
▼
┌──────────────┐ ┌──────────────┐
│ 对弈页 game │──结束──▶│ 结算页 result │
└──────┬───────┘ └──────┬───────┘
│ 退出 │ 确认
└──────────┬─────────────┘
▼
回到首页
┌──────────────┐
│ 了解更多 about │ ◀── 首页「了解更多」
└──────────────┘
从上到下四张卡片,全部用下拉菜单选择。
- 左边是白方的阵营,右边是黑方的阵营,各有一个「随机」选项
- 选好之后,下方会展开该阵营的文字介绍(如果素材作者写了
阵营介绍.md) - 阵营数不足 2 个时,这里会显示
Error:阵营人不齐!,无法开局
- 列出
data/chessboard/下所有合格(严格 1:1)的棋盘,默认选中「标准」 - 下方显示预览图与像素尺寸
- 如果有图片因为比例不对被跳过,会用黄字告诉你哪张、为什么
- 人 vs 机:与算法较量,会多出「执棋颜色」选项
- 执白:你先走
- 执黑:AI 先走,且棋盘会自动翻转,让你执的一方永远在屏幕下方
- 随机:开局时决定
- 人 vs 人:你自己操控黑白双方,此时没有难度可选
只在「人 vs 机」时出现,按 ELO 积分分七档,默认「600-1000:灵机一动」。
| 档位 | 名称 | 大致水平 |
|---|---|---|
| 500 以下 | 初生牛犊 | 随机性较强,适合第一次玩 |
| 600–1000 | 灵机一动 | 会看几步棋 |
| 1100–1500 | 激流勇进 | 有基本战术意识 |
| 1600–2000 | 福至心灵 | 接近业余好手 |
| 2100–2500 | 行云流水 | 接近专业水平 |
| 2600–3000 | 随心所欲 | 很强 |
| 3000 以上 | 返璞归真 | 最强档 |
配置下方的强度条会随选择变化。
点最下方的「开始对局」。也可以在顶部菜单点「来一局」,效果相同。
如果配置有问题(比如素材不够),顶部会弹出提示,不会跳转。
两种方式都支持:
- 点击:先点自己的棋子(会高亮所有合法落点),再点目标格
- 拖拽:按住棋子拖到目标格松开
规则完全遵循国际象棋标准。非法走法会让棋子「走一半再加速退回」,并提示「不能移动到那里!」。
任何棋子都能被选中观察(会播放选中动画),哪怕当前不能移动——方便你欣赏素材。
王车易位、吃过路兵、兵升变都已实现。升变时会弹出选择框,选皇后/城堡/骑士/主教。
棋盘右侧有个 › 箭头,点开是棋谱记录:
- 实时显示标准记谱法,最新一步高亮
- 下方三个按钮:打印(导出 TXT)/ 认输(直接结束本局)/ 退出(回首页,不保存)
- 再点右上角
‹收起
棋盘右上角第一行的喇叭图标可以开关全部音效(默认开启)。
- 选棋子、落子、被吃都有对应语音
- 吃子时,被吃方与吃子方的动画和语音同时播放
- 结算时会自动播放对应结局的语音
浏览器有自动播放限制,如果结算语音没响,在页面上随便点一下就会补播。
- 顶部徽标显示双方阵营,轮到谁谁高亮
- 人机模式下 AI 思考时右下会出现「引擎思考中…」
- 人机执黑时,你的棋子永远在下方(棋盘上下翻转,坐标也随之变化)
对局结束会自动跳转。
- 人 vs 机:你赢显示「恭喜获胜」,输显示「遗憾失败」,和棋显示「达成共识」
- 人 vs 人:客观语气,如「恭喜,白方获胜」
画面会用当前阵营对应结局的插画(胜负和三种)铺满,并配上专属语音。
三个按钮:
| 按钮 | 作用 |
|---|---|
| 再来一盘 | 沿用本局所有配置(阵营/棋盘/难度/执色)立刻重开 |
| 打印 | 导出 TXT,含打印时间、对局配置、完整棋谱、结算文案 |
| 确认 | 回到首页 |
顶部菜单的「了解更多」是一个 Markdown 文档页,右上角 CN | EN 可切换中英文。
左侧目录可折叠,点击目录项跳转到对应段落。
Q:双击 html 文件打开,AI 不动?
file:// 下浏览器禁止 Web Worker。请用 node tools/serve.js 或任意 HTTP 服务器。
Q:没有声音? 先点一下页面(解锁音频),再检查右上角喇叭是否被关掉。
Q:为什么我放的棋盘没出现在下拉里? 棋盘必须是严格 1:1 的正方形。启动服务时终端会打印被跳过的原因,首页也有黄字提示。
Q:为什么我放的阵营没出现在下拉里?
需要 King、Queen、Bishop、Knight、Rook、Pawn 六个文件夹齐全,且每个里至少有一张视觉素材(webm/gif/png/jpg)。
Q:AI 走得太慢/太快? 难度越高,搜索越深、思考越久。低难度约 0.7 秒,最高难度约 2 秒。
| 层 | 选型 | 约束 |
|---|---|---|
| 规则 | Chess.js 0.10 | 该版本没有 board() 方法,用 get(square) 代替 |
| AI | Stockfish WASM | 跑在 Web Worker,UCI 协议通信 |
| 前端 | HTML5 / CSS3 / 原生 JS | ES5 语法:不用箭头函数、let/const、模板字符串、async/await |
| 构建 | 无 | 改完直接刷新,没有打包步骤 |
| 部署 | GitHub Pages | 纯静态 |
代码风格约定:单函数 ≤ 30 行;IIFE 封装避免全局污染;核心逻辑写简短注释。
ChessCheers/
├── index.html # 部署入口,meta refresh 跳到 code/html/index.html
├── .nojekyll # 关闭 GitHub Pages 的 Jekyll 处理
├── AGENTS.md # 给 AI 编码助手的项目约定
├── README.md # 项目介绍(英文版在 doc/README_en.md)
│
├── code/
│ ├── html/ # index / game / result / about
│ ├── css/ # 与页面一一对应,无共用样式文件
│ ├── js/
│ │ ├── assets.js # 【生成物】素材清单,勿手改
│ │ ├── asset-loader.js # 素材查询、棋子 DOM 构建、音效、logo
│ │ ├── stockfish-engine.js # Worker 封装、UCI 解析、难度映射
│ │ ├── index.js # 首页:配置校验与跳转
│ │ ├── game.js # 对弈页:渲染 / 动画 / 交互 / AI
│ │ ├── result.js # 结算页:文案、素材、导出
│ │ ├── about.js # 了解更多:Markdown 解析 + 目录
│ │ ├── chess.min.js # 第三方:Chess.js
│ │ └── stockfish.wasm(.js) # 第三方:Stockfish
│ └── test/ # CDP 自动化测试
│
├── data/
│ ├── chessboard/ # 棋盘图片
│ ├── chesspiece/ # 阵营素材
│ ├── chesslogo/ # 项目 logo
│ └── others/ # 文档用示意图
│
├── doc/
│ ├── PRD.md # 项目设计方案
│ ├── UserGuide.md # 本文(英文版 UserGuide_en.md)
│ ├── README_en.md # README 英文版
│ └── intro/ # 「了解更多」页面读取的中英文文档
│
└── tools/
├── serve.js # 本地服务器(启动时自动扫描素材)
├── serve.command # macOS 双击启动
├── scan-assets.js # 素材扫描与规范检查,生成 assets.js
├── optimize-assets.py # 图片转 webp、语音转 m4a(可选)
├── make-posters.js # 生成棋子静止态预览图(可选)
└── bump-version.js # 批量更新静态资源版本号
纯静态站点无法在运行时列举目录(没有 readdir,也拿不到服务器目录索引)。
所以素材列表必须在启动/部署前扫描生成,写进 code/js/assets.js,页面再从这个 JS 变量读取。
data/ 目录
│ node tools/scan-assets.js
▼
code/js/assets.js (window.CHESS_ASSETS = { camps, boards, logo, ... })
│
├── index.js → 填下拉框、显示阵营介绍、校验配置
├── game.js → 决定加载哪套棋子/棋盘素材
└── result.js → 决定结算插画与语音用哪个阵营
assets.js 是生成物,不要手动编辑;改素材后重新扫描即可。
| 文件 | 职责 | 关键函数 |
|---|---|---|
index.js |
读清单渲染配置项、校验、拼 URL 跳转 | renderCamps / renderBoards / buildGameUrl |
game.js |
棋盘渲染、拖拽/点击、动画编排、AI 调度、棋谱 | renderPieces / runMove / maybeTriggerAI / finishGame |
result.js |
胜负文案、结算素材与语音、TXT 导出、再来一盘 | buildText / loadAsset / printRecord |
about.js |
Markdown 逐行解析、目录生成、中英切换 | parseMarkdown / generateToc / loadDocument |
game.js 内部按职责分层,读代码时建议按这个顺序:
几何 colOf / rowOf / viewCol / viewRow / placeAt / squareFromPoint
渲染 renderBoardBg / renderCoords / renderPieces / renderContextMarks
动画 runMove → slideThenCommit → commitMove → playImpactFx
交互 onPointerDown / onPointerMove / onPointerUp / requestMove
AI initEngine / maybeTriggerAI / uciToMove
UI 控制 updateMoveList / updateTurnBadge / toggleSound / printRecord
结算 evaluateNext / finishGame / playKingCapture / goResult
视角翻转:isFlipped() 只在「人机 + 玩家执黑」时为真。翻转只影响呈现层(placeAt、squareFromPoint、坐标标签、棋盘背景旋转),规则层始终使用标准格号。新增任何涉及坐标的代码,都必须经过 viewCol / viewRow。
首页 → 对弈页(URL 参数):
game.html?wf=<白方阵营>&bf=<黑方阵营>&board=<棋盘名>&mode=pve|pvp[&elo=<分数>][&side=white|black|random]&v=<版本号>
对弈页 → 结算页:完整对局数据写入 sessionStorage(键名 chesscheers_last_game),
URL 只带 outcome 等少量参数作为兜底。改任何一方都要同步另一边。
stockfish-engine.js 用一层 Worker 直连 stockfish.wasm.js,走 UCI 协议:
uci→ 等uciok→setoption→isready→ 等readyok→ 就绪- 每步:
position fen <fen>+go depth <n> - 收到
bestmove后按档位补足最短思考时长,再回调
难度表在 ELO_LEVELS,同时控制搜索深度、Skill Level 与最短思考时间。
- 格式:
png/jpg/jpeg/webp - 长宽比:严格 1:1(容差 1%),否则会被判定不合格并跳过
- 命名:无限制,文件名(去扩展名)即下拉选项名
- 建议长边 ≤ 1024。若同时提供
<名字>-mini.webp,首页预览会用它(几十 KB), 下拉框旁边不会再拉原图
data/chesspiece/<阵营名>/
├── King/ Queen/ Bishop/ Knight/ Rook/ Pawn/ # 六个都必须存在
│ ├── 选中.webm # 或 .gif / .png / .jpg / .jpeg / .webp
│ ├── 选中.wav # 可选:.wav / .m4a / .mp3 / .ogg
│ ├── 落子.webm
│ ├── 落子.wav
│ ├── 被吃.webm
│ ├── 被吃.wav
│ └── 预览.webp # 可选:静止态首帧,由 tools/make-posters.js 生成
├── 结算动画/ # 可选
│ ├── win/ 赢棋.png + 赢棋.wav
│ ├── lose/ 输棋.png + 输棋.wav
│ └── draw/ 和棋.png + 和棋.wav
└── 阵营介绍.md # 可选,选该阵营时展示
合格判定:六个棋子目录齐全,且每个至少有一张视觉素材。 不满足的阵营不会进入下拉,终端与首页会给缺失清单。
状态映射(scan-assets.js 的 mapStates):
- 优先按文件名前缀匹配
选中/落子/被吃 - 匹配不上按文件名排序依次分配
- 数量不足时循环复用
写代码时如果新增状态,要同时改 STATES 与 asset-loader 里的 STATE_LABELS。
棋子静止时,如果直接用 <video preload="auto"> 展示首帧,棋盘上 32 个棋子会同时
下载几十 MB 视频——弱网下根本进不了对局。tools/make-posters.js 把每个棋子的
选中.webm 首帧截成 192px 的 预览.webp(含透明通道,单个 4~7KB),
页面静止态只加载它,视频只在真正播动画时才按需下载。
没有预览图也能正常运行,只是会退回视频首帧方案。新增阵营后建议补跑一次:
node tools/make-posters.js三个结局各自独立,缺失时不会报错,只是结算页退回灰色简洁弹窗(无插画、无语音)。
图片建议 16:9 横图:结算页按此比例铺开,object-fit: cover 只裁掉极窄的边。
data/chesslogo/ 下放一张名字含 logo 的图片即可用于首页展示与网页图标。
若同时提供带尺寸后缀的版本(如 -128),会优先用它作 favicon,避免每页加载大图。
node tools/serve.js # 起服务,自动扫描素材,带规范检查报告改完代码直接刷新浏览器。但注意:页面里的 css/js 引用带版本号 ?v=...,
改了前端资源后要执行一次:
node tools/bump-version.js它会把 5 个 HTML 的 ?v= 与 3 个 JS 里的 BUILD 常量刷成同一个新值。
忘了这一步,浏览器可能继续用旧缓存,表现为「改了没生效」。
素材变了:
node tools/scan-assets.js # 手动扫描(用 serve.js 时启动会自动跑)网页版的瓶颈几乎总是素材体积而不是代码:原始素材动辄几十 MB,弱网下首屏根本打不开。 新增或替换素材后,按顺序跑:
python3 tools/optimize-assets.py # 棋盘/结算图转 webp、语音转 m4a(需 Pillow)
node tools/make-posters.js # 从「选中.webm」截首帧生成 预览.webp(需 Chrome)
node tools/scan-assets.js # 重新生成清单
node tools/bump-version.js # 刷新资源版本号- 棋盘建议长边 ≤ 1024、结算图 ≤ 1600;
optimize-assets.py会顺带生成首页用的-mini缩略图 预览.webp是棋子静止态用的首帧图(每个几 KB)。没有它,棋盘上 32 个棋子会各自 拉一段完整视频,首屏从几百 KB 变成几十 MB——这是网页版卡顿最常见的原因- 原始文件建议先备份(仓库里默认放在
.assets-original/,已被 gitignore)
需要本机装有 Google Chrome,先起服务,再跑:
node code/test/cdp-check.js # 对弈页:走子/AI/吃子/易位/过路兵/升变/非法退回/拖拽/翻转/结局
node code/test/cdp-index.js # 首页:下拉填充/介绍/模式联动/跳转参数
node code/test/cdp-result.js # 结算页:胜负判定/素材/按钮/打印/再来一盘三个脚本都会启动 headless Chrome,通过 CDP 真实操作页面并断言结果。
端口默认 8766,可用 CC_BASE=http://127.0.0.1:8080 覆盖。
把项目发布成可在浏览器直接访问的网址是可选步骤:只在自己电脑上玩,本地启动就够了。 如果希望分享给朋友,或者自己换台设备也能玩,可以按照下面的步骤部署到你自己的 GitHub Pages。
- 把仓库推送到你自己的 GitHub 账号
- 进入仓库 → Settings → Pages → Source 选
main分支、根目录 - 等待约 1 分钟,访问
https://<你的用户名>.github.io/<仓库名>/
注意事项:
- 部署前执行一次
node tools/scan-assets.js,确保素材清单与素材一致 - 根目录
index.html负责跳转,.nojekyll关闭 Jekyll(否则下划线开头的文件会被忽略) - 页面与素材全部使用相对路径,部署到子目录(
/仓库名/)也能正常工作
code/css/—— 样式随你code/js/index.js、result.js、about.js—— 页面逻辑code/js/game.js—— 对弈核心(改动前建议先跑测试)code/html/—— 结构与文案tools/—— 工具脚本
code/js/asset-loader.js—— 改素材解析规则会影响全部页面code/js/stockfish-engine.js—— 改通信协议要考虑 Worker 的异步特性code/js/assets.js—— 不要手改,它是scan-assets.js生成的
data/—— 素材本身。要加素材请新增目录,不要改动已有文件doc/intro/—— 「了解更多」页面运行时读取,删改会导致该页空白code/js/chess.min.js、stockfish.wasm*—— 第三方库,替换需自行验证兼容性
| 现象 | 原因 |
|---|---|
| AI 不走棋 | 用 file:// 打开了页面,Worker 被拦截 |
| 改了 JS 没生效 | 忘了 node tools/bump-version.js,浏览器用了旧缓存 |
| 新素材不出现在下拉 | 忘了重新扫描;或素材不合格(看终端报告) |
| 棋盘格子颜色错位 | 只翻转了棋子没翻转棋盘背景,检查 renderBoardBg 与 isFlipped |
| 结算页标题不对 | outcome 与 winner 不一致,检查 result.js 的 loadState |
| 手机端布局溢出 | 用 --window-size 截图会误判,需用 CDP 的设备模拟验证 |
- 代码:本项目仅供学习与交流,严禁商业用途。转载请注明出处。
- 第三方库:
- Chess.js — BSD-2-Clause
- Stockfish — GPL-3.0
- stockfish.wasm — GPL-3.0
- 素材(
data/目录):棋子立绘、配音等来自《明日方舟》同人创作与 PRTS 中文维基,版权归原权利方所有,仅用于个人学习与非商业展示。如有侵权,请通过 issue 联系,作者将立即下架相关素材。 - 本项目与上海鹰角网络科技有限公司无关。
欢迎引用该项目,或基于该项目进行其他创作,引用格式如下:
- 项目名称:ChessCheers
- 项目地址:https://github.com/Schlampig/ChessCheers
- 项目作者:猪猪熊(PigPigBear/Kuyiking)
- 作者链接:https://github.com/Schlampig