跳到正文

工作区与源码:freerush 框架里的一个游戏

联机放置游戏第 02 节 / 共 11 节 ·2026-11-16·~6 min

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.jsonNode、Creator 等的版本、下载地址与校验值
Skillsbootstrap/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.tsGM 指令表与解析(执行在服务器)
config/build.tsTABLES 列定义、配表构建与全部校验、炼金动作生成

一次请求怎么流

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 记还没做的事和已经拍板的决定。本站这几章是对照这些材料和代码整理的。