这一章讲「为什么这样做」。每块代码在哪,见 工作区与源码 。
1. 一张图
flowchart LR
subgraph repo[idle-hd 仓库]
core[packages/core<br/>纯规则:结算·战斗·工坊·市场·GM 解析]
cl[packages/client-logic<br/>网络·预测·推送·寻路]
srv[server<br/>Node 24 · SQLite]
vis[client/assets/scripts/visual<br/>Cocos 表现层]
cfg[config/tables/*.csv]
end
core --> srv
core -->|sync-client-shared 拷贝| vis
cl -->|拷贝| vis
cfg --> srv
srv -->|GET /config 下发| vis线上的样子:
浏览器(网页版)
│ /idle/… 入口页、引擎脚本、接口
▼
站点的 Caddy ── /idle/* ──► idlehd-server:8020(容器,不对外开端口)
├─ SQLite(卷 idlehd-data)
├─ 网页版发布目录(releases/<版本>,CURRENT 指当前版)
└─ OIDC ──► 身份服务
│
└─ 资源 bundle、图片包 ──► CDN(Cloudflare R2,桶里只留当前版本)
2. 分层:core / client-logic / visual / server
| 层 | 在哪 | 能用什么 | 不许用什么 |
|---|---|---|---|
| core | packages/core/src | 纯 TypeScript | node:*、DOM、cc、Math.random、Date.now()、浮点累加 |
| client-logic | packages/client-logic/src | core、XMLHttpRequest | cc(平台差异走 Platform 接口) |
| visual | client/assets/scripts/visual | cc、client-logic | 直接调接口(只调 GameStore) |
| server | server/src | core、Node 标准库 | 任何第三方包 |
关键约束:同一份结算代码在两端跑。服务器用它算真账,客户端用它在两次同步之间推进度条、显示必出的产出。所以 core 只能用两端逐位一致的东西:
- 时间由调用方传进来,core 自己不看钟。
- 数值全是整数:时间是毫秒,倍率是万分比(bps,10000 = ×1),每一步向下取整。唯一的浮点数是掉落概率,只拿来比大小。
- 随机数是自己写的:
rng.ts用 splitmix32 打散,roll(seed, 循环号, 槽位)是一个纯函数。同一颗种子、同一个循环,在哪台机器上掷都一样。
测试里钉着两条,改了结算相关的东西必须还绿(packages/core/test/core.test.ts):
- 分多次结算 = 一次结算。 挖三小时煤,一次算完和每 9973 毫秒算一次,结果逐位相同(deepEqual)。这是懒结算成立的根本。
- predict ⊂ full。 客户端的预测模式只是服务器完整结算的子集:经验完全一致,必出产出一致,概率掉落(鸟窝之类)预测里没有。
Cocos Creator 只编译 client/assets/ 里的脚本,所以 core 与 client-logic 由 scripts/sync-client-shared.ts 拷进 client/assets/scripts/shared/。那是生成物,CI 跑 --check 防过期。
3. 懒结算:从存档和时间算出来
放置游戏的通行做法是按时间戳结算,不按帧模拟(Kongregate 的 The Math of Idle Games 系列 [1]、Melvor Idle 的离线进度都是这个思路)。存档里只记「几个岗位在做什么、每个岗位下一次事件在哪一刻、结算到了哪一刻」,任何读写之前先 settle(state, cfg, now),把这段时间里发生的事一次性推完。
- 服务器没有逐秒循环:离线玩家的 CPU 成本是零,直到有人来问。
- 离线封顶 12 小时:从最后一次在线(
lastActiveAt)算起(constants.offlineCapMinutes = 720)。到点所有岗位和战斗自动停,做到一半的那一轮原料退回。这样鼓励玩家回来看看,也防止「挂一个月」把数值打穿。 - 几个岗位按全局时间顺序合并:村民模式下,砍树、烧炭、烹饪可以同时跑,上游的产出就是下游的原料。结算是一个事件循环:每个岗位只有「下一次完成」或「下一次开工」一个事件,每次取全局最早的那个;同一时刻先完成后开工,再按岗位顺序,战斗排最后。这个顺序是固定的,所以分几次结算都得到同一个结果。细节见 村民与经济 。
- 单次最多 40 万个事件(
MAX_EVENTS_PER_SETTLE):配表写错时也拖不死请求。 - 战斗也是懒结算:一场战斗在开打那一刻就整场模拟完,料理当场扣掉,奖励在结束时刻入账。打到一半停下,这一场吃掉的料理退回。见 战斗 。
种子只在服务器
掉落种子只存在服务器上,发给客户端的存档里种子清零(redactForClient)。所以客户端预测不了概率掉落,只能等同步。否则作弊者可以先算出下一轮掉不掉宝石,再决定要不要挂。
战斗是例外的一半:伤害浮动和暴击用的 fightSeed 是公开的,客户端拿它逐位重放整场战斗来播动画;决定掉落的 seed 仍然只在服务器。
4. 客户端怎么跟上
- 启动时并发拿三样:配表(
GET /config,ETag 是配表版本)、自己是谁、事件游标。记下服务器与本机的时差。 GameStore.view()把快照拷一份,用 core 的同一个settle(…, 'predict')推到校正后的此刻。结果缓存 8 毫秒,下一帧一定重算。- 每 15 秒同步一次;每次操作后、收到成交 / 撤单 / 状态变了的推送时也同步。
- 推送用长轮询:
GET events?since=N,没有新事件就挂 25 秒。不用 WebSocket 或 SSE,是因为 Cocos 原生端没有 EventSource,反代和心跳也麻烦;长轮询在所有平台上都只是普通 HTTP 请求。
5. 市场
限价单加订单簿撮合,价格优先、时间优先(交易所的标准规则 [2]),成交价取挂单方(maker)的价格。
- 托管:挂卖单时物品先扣走,挂买单时「价格 × 数量」的金币先扣走;成交、撤单、过期时结算或退回。同一份东西不可能被卖两次,撮合时也不必回头查背包。
- 买单以更高的限价吃到更便宜的卖单,差价退回。卖方付 5% 手续费,这是全游戏唯一的金币回收口。
- 自己的单不和自己成交(防对敲刷量)。物品挂单 72 小时过期自动退回;每人最多 20 张挂单,装备寄售也算在里面。
- 一个 SQLite 事务做完全部:托管、撮合、双方入账(对方离线也直接改他的存档,先替他结算到此刻)、写成交、推送。单进程加同步 SQLite 让每个请求天然串行,不需要行锁。
- 装备是实例,不进订单簿:一口价寄售,不绑定,不过期(占着挂单数就够了),强化等级和词条跟着装备走。
6. 金币从哪来、到哪去
升级不花金币(2026-11-04 拍板)。家园、强化、强化迁移、精炼全用材料,金币只用于玩家之间交易:
| 方向 | 途径 |
|---|---|
| 产出 | 炼金(村民把物品按炼金价一个一个炼成金币)、打怪掉金币 |
| 回收 | 市场手续费 5% |
NPC 商人(卖店)删掉了,物品表里的 vendorPrice 现在就是炼金价。时装商城的价格列留着,目前全部免费。长期会不会越攒越多,要等真实数据。
7. 服务器:Node 24 + SQLite + 零依赖
选它的理由是「规则只写一份」:客户端是 Cocos 的 TypeScript,服务器也用 TypeScript,core 两端共用。Node 24 直接执行 .ts(类型剥离 [3]),不需要编译;SQLite 单进程同步写 [4],让市场撮合不需要锁。所有改状态的操作放进 db.tx(() => …),里面不许 await:一让出事件循环,「天然串行」的前提就没了,所以代码里检测到返回 Promise 就直接抛错。接口、登录和安全见 服务器与安全
。
8. 配表
CSV 是唯一源(config/tables/*.csv),能 diff、能 code review、Excel / WPS 能直接打开。列定义写在 core 的 TABLES 里,命令行、网页配表编辑器、服务器加载三方共用,一次报全部错误(表:行 列 — 原因)。服务器启动时加载并算内容哈希,客户端从 GET /config 拿,所以改数值不用发客户端。管理后台还能在线改表、热更。见 配表
。
9. 资源
代码与配表只写资源键(assets.csv 里的 item_log_oak、map_scene_world),不写路径。键 → bundle + 路径 + 类型 + 逻辑尺寸 + 实际发多少分辨率 + 格式。源图在 art-source/(全分辨率,走 LFS),npm run art:import 按表缩放、量化后放进 client/assets/bundles/。
网页版的图片在打包后合成图片包(每个 bundle 几个、大地图按区域、时装按部件),全部从 CDN 下;进了包的原图从产物里删掉。见 客户端 与 打包与部署 。
10. 表现:从陪伴小窗到大地图
最早照「TaskbarHero」那种感觉做:主体是数据页面,当前动作的小动画在一个可以拖动的陪伴小窗里。2026-11-09 起主角换成了大地图:
- 场景在 3D 里搭(Tripo 生成的建筑模型、Quaternius 的 CC0 套件、手绘贴片),从固定相机按角色烘焙器的同一套像素化离线烘成图块与贴片,游戏里仍是 2D(按脚底排前后)。
- 不走引擎里的实时 3D:客户端没有 3D 管线,开发机上没装 Creator,网页性能也没把握。
- 「HD-2D」那层感觉在后处理里补:整张世界渲到一张 RenderTexture,再斜着透视看(近大远小),加景深、调色、雾气。
陪伴小窗的代码还在,只是隐藏了(SHOW_COMPANION = false)。小窗口时(或点「小窗」)整页变成地图加一个可折叠的快捷面板,还能弹出浏览器的画中画窗口,适合挂在屏幕角落「摸鱼」。见 大地图
。
参考
- Anthony Pecorella(Kongregate),The Math of Idle Games 三篇:https://www.gamedeveloper.com/design/the-math-of-idle-games-part-i
- Order matching system(价格优先、时间优先):https://en.wikipedia.org/wiki/Order_matching_system
- Node.js, Modules: TypeScript(类型剥离):https://nodejs.org/api/typescript.html
- SQLite, Write-Ahead Logging:https://www.sqlite.org/wal.html ;Node.js
node:sqlite:https://nodejs.org/api/sqlite.html