这款自研 3D 弹珠跳棋已经跑在 https://chinesecheckers.iouxi.com 上:六芒星棋盘 121 个孔位、每位 10 颗玻璃弹珠、2–6 人在线对战,线上产物 gzip 后合计约 174 KB,联机协议版本 v3 —— 下面是把一个想法推到上线的完整记录,每个数字都取自线上产物与源码本身。
一、起手:先把规则砍到「一个动作、两种走法」
中国跳棋(Chinese Checkers)的物理规则本身很古老,但搬进浏览器要先回答三个问题:棋盘怎么编码、一次回合允许什么、联机时谁是权威。我们选择先定规则再写渲染,最后连规则本身也保持成一份纯函数文件。
最终定下的回合模型只有一句话:一个回合 = 一步走(step)或一串跳(hop chain),二者选一,跳到哪里都可以停。 关键在最后四个字——「可以停」:传统跳棋要求连跳到底,而本作把连跳路径上任何可达落点都算合法终点,玩家在链中途选中哪一格就在哪一格收手。这让一子多跳从「一条强制路径」变成「一组可选路径」,正是它最上瘾的地方。
配套约束三条:跳过的路径不能重复踩自己走过的格(在 BFS 枚举跳点时就禁止,不是靠事后回溯);有合法走法必须走,无子可动才跳过回合;每位玩家 10 颗弹珠,全部抵达对角营地即结束。
二、棋盘:121 个孔位是算出来的,不是摆出来的
六芒星棋盘看着复杂,落到代码里是一个纯几何判定。棋盘 = 两个边长 5 的等边三角形叠加:
- 中心六边形半径 4,按六边形数公式
1 + 3n(n+1)得出 61 个孔; - 六个星角各是一个边长 5 的三角形臂,每臂 10 个孔,合计 60 个;
- 61 + 60 = 121 个孔位,与标准中国跳棋完全一致。
坐标用轴向六边形坐标 (q, r),六个方向固定为 (0,-1)、(1,-1)、(1,0)、(0,1)、(-1,1)、(-1,0)。在盘判定只有两行不等式:q,r,s(其中 s = -q-r)全部 ≥ -4,或全部 ≤ 4,取并集即得星形轮廓,遍历 q,r ∈ [-8,8] 共得 121 个有效点。
六个营地按星角编号 0..5(0=东北、1=东、2=东南、3=西南、4=西、5=西北),目标营地 = (本方营地 + 3) % 6,也就是正对面那个角。座位顺序按人数定死:2 人 [0,3]、3 人 [0,2,5]、4 人 [0,2,3,5]、6 人 [0,1,2,3,4,5]。
三、规则引擎:零依赖的纯逻辑,一份代码三处用
规则层写成完全不碰 DOM 和 Three.js 的纯类 CheckersGame,接口只有:列出当前所有合法走法、施加一步走法、查询某方进度。这样同一份代码能同时跑在客户端、服务端和 AI 里——服务端拿它做权威裁决,客户端拿它做本地预演,AI 拿它做搜索。所谓的「规则引擎拒绝落子,舞台已回滚」这类保护,逻辑上就是「客户端算一遍、服务端再算一遍、结果不一致就拒收」。
跳点的枚举用 BFS:种子是起点本身(天然满足不可重复踩格),队列里走的是完整路径,每个可达落点都带着它自己的路径数组返回,因此动画可以直接按路径逐格播放。
连跳还有一套表现分(不影响胜负,只用于结算):总分 = 总跳数 × 10 + Σ(连跳 ≥ 2 时的 连跳数² × 5)。二次项专门奖励长链规划——一次跳 6 格的收益是 36×5 = 180 分,远高于连跳 2 格的 20 分。
四、联机:协议版本 3,一堆写死在常量表里的数字
联机层按 PROTOCOL_VERSION = 3 走 WebSocket JSON 帧,单帧上限 8 KiB,每帧四字段(type / seq / payload / timestamp)逐一做结构校验,非法帧直接拒收。所有阈值集中在一份常量文件里,客户端与服务端共用同一份:
| 项目 | 数值 |
|---|---|
| 线上可匹配人数 | 2 / 3 / 6(4 人局仅本地) |
| 队列容量 | 2 人 256、3 人 256、6 人 128 |
| 单回合超时 | 30 000 ms(剩 10 000 ms 开始催) |
| 连续托管上限 | 3 次后自动认输 |
| 掉线宽限 | 60 000 ms |
| 心跳 | 30 000 ms ping,60 000 ms 判死 |
| 消息限流 | 10 条/秒;走子 2 次/秒 |
| 组队邀请码 | 3 位,排除 0/O/1/I/L 等易混字符 |
| 重连退避 | 1 000 ms 起,上限 15 000 ms |
身份是服务端签发的:playerId 形如 p_ + 8 位十六进制,resumeToken 16 位十六进制,matchId 形如 m_ + 10 位。客户端把这两个值存在 localStorage(键名 mc.net.v1),重连时凭以恢复席位与对局;昵称最长 12 字,落地前会先压缩空白、再剥掉控制字符。
匹配队列的等待策略写得很细:排队 20 秒给软提示,60 秒未成局给出「换个模式试试」,90 秒才提示;等超过 45 秒,匹配器允许用 AI 座位补位开局,AI 落子前有 800 毫秒的拟人停顿。对局开始有 3 秒倒计时,结束后 30 秒的「再来一局」投票窗口,房间空置 5 秒才销毁。
五、AI:难度和策略是两条正交的轴
这里最容易被做错的做法,是把「难度」和「打法」混成一个下拉菜单。我们拆成了两个维度:
- 难度 = 搜索力度:easy 是随机合法走(20% 概率退回贪心),medium 是 1 层贪心,hard 是 minimax + alpha-beta + 迭代加深,硬预算 700 毫秒、节点上限 20 万、最大深度 8,时钟每 1024 个节点采样一次。
- 策略 = 评估意图:四档人格共用一套收益函数,差异只在权重。
| 策略 | 对手权重 | 连跳欲望 | 堵桥惩罚 | 送桥奖励 |
|---|---|---|---|---|
| 均衡 | 0.6 | 0 | 0 | 0 |
| 进攻 | 0.15 | 2.5 | 0 | 0 |
| 防守 | 1.2 | -0.5 | 6 | 0 |
| 协作 | 0.6 | 0 | 0 | 4 |
「堵桥」惩罚 6 是这套设计里最锋利的数字:它意味着牺牲自己的位置分去卡住对手的桥头是划算的,这正是双人跳棋真正的战术核心,而不是简单地把弹珠往家赶。迭代加深的另一个好处是残局天然占便宜——分支因子变小,同样预算能搜得更深,此前那套按进度百分比硬切深度的启发式因此被整个删掉。
六、画面与包体:174 KB gzip 里塞进 3D 玻璃质感
渲染用 three.js 0.169.0,色调映射走 ACES Filmic(曝光 1.12),阴影用 PCF Soft,主光是一盏 4800K 暖色平行光(#FFD9AE,强度 2.6),配一盏冷白补光(#AFC8FF,强度 0.5)制造冷暖对撞,玻璃边缘的菲涅尔冷白全反射正是靠这束补光打出来的。
弹珠是程序化生成的旧玻璃珠:球体 48×32 段,材质 roughness 0.07、clearcoat 1.0、虹彩折射率 1.45、薄膜厚度 140–480 纳米;每颗珠子的缩放随机在 0.98–1.02 之间(刻意的不完美),再叠一层冷边光与背光透射近似次表面散射。音效全部由 Web Audio API 实时合成(振荡器 + 噪声缓冲),没有任何音频文件——这是包体能压下来的关键一环。
画质分三档,按设备能力自动降级:low 关阴影关环境光贴图、像素比锁 1;medium 像素比上限 1.5、阴影贴图 2048、140 颗尘埃粒子;high 像素比上限 2、阴影贴图 2048、320 颗尘埃粒子。
线上产物实测(2026-11-09 抓取):
| 文件 | 原始 | gzip |
|---|---|---|
| main-*.js | 643 639 B | 172 808 B |
| main-*.css | 21 855 B | 5 312 B |
| 合计 | 665 494 B | 178 120 B |
按 1024 进制算,gzip 后约 174 KiB,稳稳落在「首屏 ≤ 300 KB」这条线以内。有意思的是 source map 反而有 2 487 510 字节(约 2.37 MiB),比它描述的代码还大——它包含 40 个源文件条目(其中 34 个是项目自身的 23 个 client + 11 个 shared 模块,6 个是 three.js 等依赖),且没有做公网访问限制。对生产环境来说这是个该收紧的点:压缩后的体积优势会被这份明文源码抵消。
七、上线:一次构建、一次部署
工程上用的是 Vite 打包 + nanostores 做状态管理 + nanoid 生成随机 ID(这三个版本分别是 three 0.169.0、nanostores 0.10.3、nanoid 5.1.16;截至 2026-11-09,npm 上它们的最新版本已经分别是 0.187.0、1.5.5、6.0.2),规则与网络协议写在 src/shared/ 下,客户端与服务端 import 同一份源码。
PWA 配置走 manifest:名字 Marble Checkers、display: standalone、主题色 #1B4D3E、start_url 为根路径。设置项(主题、画质、音量、动画速度)存 localStorage,键名 mc.settings.v1;教程完成标记单独一个键 mc_tutorial_done。
游戏分四种模式:同屏热座、人机对弈、在线匹配、组队对战(2v2 / 3v3,人与 AI 自由混搭)。组队时队伍由座次自动派生——4 人局按回合序号的奇偶分成 A/B 两队(A 队 = 序号 0、2),6 人局同理分 3v3,玩家不能手挑队友;2 人和 3 人局是个人混战,没有队伍。
服务端部署在 https://chinesecheckers.iouxi.com,IOUXI 站内也在 IOUXI 是什么 里说明了这款自研作品的来历,3D 展厅见 3D 展厅。