IOUXI 首页 › 博客 › 自研纪实:弹珠跳棋从想法到上线的完整记录

自研纪实:弹珠跳棋从想法到上线的完整记录

发布于 2026-11-09 · 更新于 2026-11-10 · 11 分钟阅读 · IOUXI 编辑部

这款自研 3D 弹珠跳棋已经跑在 https://chinesecheckers.iouxi.com 上:六芒星棋盘 121 个孔位、每位 10 颗玻璃弹珠、2–6 人在线对战,线上产物 gzip 后合计约 174 KB,联机协议版本 v3 —— 下面是把一个想法推到上线的完整记录,每个数字都取自线上产物与源码本身。

一、起手:先把规则砍到「一个动作、两种走法」

中国跳棋(Chinese Checkers)的物理规则本身很古老,但搬进浏览器要先回答三个问题:棋盘怎么编码、一次回合允许什么、联机时谁是权威。我们选择先定规则再写渲染,最后连规则本身也保持成一份纯函数文件。

最终定下的回合模型只有一句话:一个回合 = 一步走(step)或一串跳(hop chain),二者选一,跳到哪里都可以停。 关键在最后四个字——「可以停」:传统跳棋要求连跳到底,而本作把连跳路径上任何可达落点都算合法终点,玩家在链中途选中哪一格就在哪一格收手。这让一子多跳从「一条强制路径」变成「一组可选路径」,正是它最上瘾的地方。

配套约束三条:跳过的路径不能重复踩自己走过的格(在 BFS 枚举跳点时就禁止,不是靠事后回溯);有合法走法必须走,无子可动才跳过回合;每位玩家 10 颗弹珠,全部抵达对角营地即结束。

二、棋盘:121 个孔位是算出来的,不是摆出来的

六芒星棋盘看着复杂,落到代码里是一个纯几何判定。棋盘 = 两个边长 5 的等边三角形叠加:

坐标用轴向六边形坐标 (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:难度和策略是两条正交的轴

这里最容易被做错的做法,是把「难度」和「打法」混成一个下拉菜单。我们拆成了两个维度:

策略对手权重连跳欲望堵桥惩罚送桥奖励
均衡0.6000
进攻0.152.500
防守1.2-0.560
协作0.6004

「堵桥」惩罚 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-*.js643 639 B172 808 B
main-*.css21 855 B5 312 B
合计665 494 B178 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 展厅。

常见问题

为什么把「连跳必须走到底」改成「可以中途停」?
因为可选落点集合比强制路径好玩得多。源码里跳点用 BFS 枚举,每个可达落点都自带完整路径,中途停就等于选了这条路径的某个前缀终点。这一个改动把棋局分支数显著拉开,也让「最优解」不再唯一——顺带催生了表现分里的连跳二次项:一次跳 6 格按 36×5 = 180 分结算,远高于连跳 2 格的 20 分。
联机怎么防止有人改客户端多走一步?
规则引擎写成零 DOM、零 Three.js 依赖的纯逻辑类,客户端和服务端 import 的是同一份源码。服务端按同一套规则重算并裁决,客户端提交的走法若不被接受,舞台直接回滚。传输层再加两道闸:单帧 8 KiB 上限、四字段结构校验,走子限流 2 次/秒、消息限流 10 条/秒。
AI 为什么单独拆出「策略」这一层?
因为难度和打法不是一回事。难度只决定搜索力度(easy 随机、medium 1 层贪心、hard 为 700 毫秒 / 20 万节点预算的 minimax + alpha-beta + 迭代加深),策略决定评估函数里的权重。四档人格共用同一套收益函数,防守型的堵桥惩罚权重是 6,协作型的送桥奖励是 4——同一个难度下,四种人格打出来的棋路完全不同。
整套东西到底有多大,会不会拖垮手机?
线上主包 gzip 后 178 120 字节,约 174 KiB;CSS 单独 gzip 后 5 312 字节。音效不占体积,因为全部由 Web Audio API 实时合成。画质三档自动降级:low 档关阴影、关环境光贴图、像素比锁 1,medium 像素比上限 1.5、high 上限 2。中低端机走 low 或 medium 档即可。

相关阅读

事实来源

返回栏目首页 · 博客