1. freerush-framework:多游戏、Agent First 的工作区
IdleHD 原本是一个独立仓库,引擎是自己镜像的 cocos-engine,以子模块挂进来。2026-11 起它搬进了 freerush-framework:一个同时装着好几个游戏的开发工作区。仓库都在 cnb 平台的 freerush 组织下,引擎和游戏分别在 engines、games 两个子组织。
框架的思路是 Agent First:确定性的操作(拉仓库、装工具链、打包、生成流水线)写成脚本,判断、编排和排错交给 Agent。能力按插件组织,每个 Skill 用自己的 setup.json 声明用途、依赖、配置字段和验证入口,统一控制台读这些声明来展示「能做什么、需要什么、现在什么状态」。
| 部分 | 在哪 | 管什么 |
|---|---|---|
| 核心 | bootstrap/general/core/ | 命令入口 cli.mjs、统一控制台(cli.mjs web)、模块发现与依赖编排;manifest.json 声明宿主 Agent 和 Node / 引擎 / Creator 等核心资源 |
| 组装清单 | bootstrap/general/workspace.json | 每个游戏、引擎的远端、分支、目录与依赖;不记游戏日常的 HEAD |
| 工具链锁 | bootstrap/general/toolchain.lock.json | Node、Creator 等的版本、下载地址与校验值 |
| Skills | bootstrap/general/skills/ | fr-setup(安装与修复)、fr-repo(本地 Git、评审、推送、引擎分支)、fr-build(打包、流水线、部署)、fr-art(美术与界面)、fr-talk(需求讨论)、fr-acp(调用外部 Agent) |
| 第三方接入 | bootstrap/general/third-party/ | cnb(建仓、流水线、Release 的平台 API)、tapd(工作项) |
| 游戏 | freerush/games/<目录>/ | 各自独立的 Git 仓库,框架不跟踪它们的提交 |
| 引擎 | freerush/engines/cocos/cocos-engine/ | 独立的 cocos-engine 仓,公共基线由组装清单锁定 |
| 本机状态 | .local/、temp/ | 安装选择、服务凭据、临时产物,不进 Git |
组装清单里现在登记了五个游戏,全是 Cocos:cloudbloom(云间生长)、jumpdungeon(地牢)、idlehd、rumble-town(轰隆小镇)、nightstall。IdleHD 的路径是 freerush/games/idle-hd,代号 idlehd。始终从顶层工作区进入开发:协作、提交、推送的通用规则在框架的 bootstrap/general/AGENTS.md,游戏仓库只写自己的约定。
几条通用规矩影响到游戏的日常:
- 每个提交都带 TAPD 工作项的名称和链接,由
fr-repo管提交与推送评审,推送要批准。 - 打包由
fr-build按游戏根目录的build.json规划;.cnb.yml和.cnb/由框架生成,不手改。 - 仓库更新后,Agent 根据实际提交和有上限的 diff 写一份更新说明,用控制台的
--view update页面展示,列出要补装、同步或清理的东西。
2. 引擎:游戏分支 + worktree
Cocos 引擎不随游戏仓库走。框架的 cocos-engine 仓有一条公共基线 freerush/main,每个游戏在上面开自己的分支 game/<代号>/v<版本>。IdleHD 根目录的 engine.json 锁定它用哪条分支、哪个提交:
{ "kind": "cocos", "branch": "game/idlehd/v3.8.8", "commit": "45984bc2…" }
- 要改引擎时,在
freerush/engines/worktrees/idlehd/这个 worktree 里改(worktree 本身不进 Git),用fr-repo engine --game idlehd …走完 commit → review → push(只许快进)→bump。bump把新提交写回engine.json,再走游戏仓库的正常提交。改引擎要明确批准。 - 打包时,框架按
engine.json把引擎检出到temp/build/engines/<提交前 12 位>/(最多留 3 份),用本机的 Creator 编辑器打包。Creator 命令行的退出码 36 才算成功。
以前那套「每晚对齐官方镜像、game-dev 分支推送自动编译发布、子模块指针」的流程随旧仓库退役了。
3. idle-hd 仓库总图
packages/core/ 纯规则:结算、等级、战斗、工坊、家园、市场撮合、时装、GM 指令解析、接口类型
packages/client-logic/ 客户端网络与状态:登录(cookie / 设备码)、预测、同步、推送、A* 寻路、场景元数据校验
server/ 游戏服务器(Node 24 直接跑 TS,零第三方依赖,SQLite)+ 管理后台 / 全服看板网页
client/ Cocos Creator 3.8.8 工程;表现层在 assets/scripts/visual/
config/tables/ 数值配表(CSV,32 张)
tools/config/ 配表命令行:校验、生成经验曲线、怪物反推、平衡 / 消耗 / 家园报告
tools/art/ 美术会话、导入、动作预览、3D 纸娃娃烘焙、大地图生成与烘焙、字体子集
art-source/ 2D 源图与出图清单(LFS)
model-source/ 3D 源模型:建筑、时装部件、武器、角色素体、动作库(LFS)
action-source/ 动作库里没有的动作(Meshy 生成的 BVH / FBX)
scripts/build/ 框架打包调用的脚本:服务器镜像、网页版本信息、图片包
scripts/deploy/ 部署机执行的部署脚本
deploy/ 服务器 Dockerfile 与 compose
plans/ 待办与已经拍板的决定(做完一项删一项)
build.json 打包目标:web、server
engine.json 锁定引擎分支与提交
依赖方向只有一条:core ← client-logic ← visual,core ← server。core 什么都不依赖。
core 里的关键文件
| 文件 | 管什么 |
|---|---|
player.ts | 存档形状、settle 时间线结算、村民派工(setJob)、离线封顶 |
levels.ts | 经验曲线生成、二分查等级 |
combat.ts | 战斗者、职业、整数伤害、小队模拟、副本、消耗品 |
workshop.ts | 装备打造、强化、迁移、精炼、分解 |
home.ts | 家园建筑加成、升级花费、村中心人数 |
market.ts、price.ts | 撮合、手续费、价格档位 |
cosmetics.ts | 时装部位、性别、图层键 |
rng.ts | 确定性随机数 |
gm.ts | GM 指令表与解析(执行在服务器) |
config/build.ts | TABLES 列定义、配表构建与全部校验、炼金动作生成 |
一次请求怎么流
sequenceDiagram
participant C as 客户端 GameStore
participant S as server/app.ts
participant G as server/game.ts
participant D as SQLite
C->>S: POST /idle/api/job {action, workers}
S->>S: need(ctx, true):会话 + Origin + 限流
S->>G: withPlayer
G->>D: BEGIN IMMEDIATE;读存档
G->>G: settle(now, 'full') → touch(now) → setJob
G->>D: 写回存档;COMMIT
G-->>C: 新快照
C->>C: view() = settle(快照, 此刻, 'predict')4. 加东西时改哪里
| 要加 | 改哪 |
|---|---|
| 一个动作(一种树、一种鱼) | actions.csv + drops.csv(加工再加 inputs.csv),assets.csv 加图;不用改代码 |
| 一种物品 | items.csv;炼金动作会自动生成 |
| 一张新表或一列 | 先改 packages/core/src/config/build.ts 的 TABLES,再加 CSV |
| 一个接口 | server/src/app.ts 注册,要身份用 need(ctx),写操作用 need(ctx, true);管理员接口再加 requireFreshRole;在 server/test/server.test.ts 补测试 |
| 结算规则 | packages/core/src,跑完「分多次 = 一次」「predict ⊂ full」两条测试;npm run sync:client 同步进工程并一起提交 |
| 一张图 | 走美术会话(不要自己生图),定稿后 npm run art:import、node client/tools/gen-meta.mjs |
5. 写 TypeScript 的规矩
Node 24 直接跑 .ts(类型剥离),所以导入写 .ts 后缀;不许 enum、namespace、构造函数参数属性(tsconfig.json 开了 erasableSyntaxOnly)。npm run typecheck 只检查不产出。新脚本写成 Windows 与 macOS 都能跑的 .mjs / .ts,不再新增 PowerShell。
6. 提交前
npm run ci # 类型检查(含客户端)+ 配表校验 + 美术清单 + 共享代码没过期 + .meta 一致 + 全部测试
客户端的类型检查不需要 Creator:client/tools/cc-stub.d.ts 只声明表现层用到的那一小块 cc API,拿它当桩来查。.meta、场景和构建配置由 client/tools/gen-meta.mjs 生成,--check 只校验。
玩家看得到的改动,在 client/RELEASE_NOTES.md 最后追加一行,短、笼统,十个字左右(如「大地图加载速度优化」),和改动同一个提交。发版时只收上个版本以来新加的条目,游戏里的「更新公告」和部署后的群通知都从这里来。
7. 说明文档在哪
游戏仓库只维护根目录 README.md 和各目录自己的 README,写「现在是什么样、怎么跑」,不另建 docs/。plans/expansion.md 记还没做的事和已经拍板的决定。本站这几章是对照这些材料和代码整理的。