数值只进 config/tables/*.csv,不写死在代码里。每张表的列定义(名字、标题、说明、列类型)写在 packages/core/src/config/build.ts 的 TABLES 里,命令行、网页配表编辑器、服务器加载三方共用同一份定义。加列加表先改 TABLES。
1. 32 张表
| 组 | 表 | 管什么 |
|---|---|---|
| 物品与技能 | items | 背包里的一切;vendorPrice 是炼金价 |
categories | 背包分组 | |
skills | 技能列表 | |
actions | 一种树、一种矿 = 一个动作:等级要求、时长、经验 | |
drops | 每轮产出:数量范围 + 概率 | |
inputs | 每轮原料 | |
skill_xp | 经验曲线(生成) | |
constants | 全局整数:离线封顶、村民数、市场规则、战斗常数、地图尺寸…… | |
| 战斗 | classes | 七个职业 |
regions | 六个战斗区域 | |
monsters | 怪物数值(生成) | |
loot | 怪物掉落 | |
dungeons、dungeon_waves | 单人副本与它的波次 | |
consumables | 料理、生命药水、增益药剂(回血量生成) | |
| 工坊 | gear | 装备外形与打造配方 |
gear_tiers | 六个档位 | |
qualities | 六个品质 | |
enhance | 强化各级成功率与加成 | |
refine_materials | 能喂进精炼的东西各值多少 | |
affixes、affix_pools | 词条定义、各部位各池的权重 | |
| 家园 | houses | 12 座建筑 |
house_levels | 各级通用的加成和材料档位 | |
house_costs | 各建筑各级材料(生成) | |
village_levels | 村中心各级的村民与战斗者人数 | |
house_stages | 家园页卡片在各级用哪张图 | |
| 外观与地图 | cosmetics | 时装部件 |
map_sites | 大地图上的地点:坐标、种类、打开哪一页(坐标由地图生成器写) | |
map_scenes | 烘焙好的 HD-2D 场景 → 对齐到哪个地点 | |
| 资源 | assets | 资源键 → bundle、路径、类型、逻辑尺寸、发多少分辨率、格式 |
asset_boxes | 图片的包围盒(导入时生成) |
列类型有 id、string、int、chance、bool、color、ref:<表>。# 开头的行是注释,很多表的头几行写着「为什么是这个数」和拍板日期。
2. 构建时查什么
buildBundle 一次报出全部错误,格式是 表:行 列 — 说明。检查顺序:
- 列类型、id 唯一、引用存在;
constants的键集合必须和代码里的CONSTANT_KEYS完全一致(不多不少);- 经验曲线严格递增;
- 生成炼金动作:每样有炼金价的物品一个
gold_<物品>,等级要求 = 物品等级。在actions.csv里手写gold_*是错误; - 战斗、工坊、家园、地图各自的检查:副本不能选难度、村中心 0 级人数等于常数、人数不减少……;
- 材料档位对齐(
checkTierAlignment,见 村民与经济 ); - 为了让客户端预测可信:动作的原料不能是它自己的产出;怪物掉落不能是消耗品。
构建结果的版本号是规范化 JSON 的 sha256 前 16 位。服务器把它当 GET /config 的 ETag,客户端没变就拿 304。
3. 生成的表:别手改,改生成器
有几张表是从别的表和公式算出来的,手改会被下一次生成覆盖,有的还有测试盯着「CSV 和生成器对得上」:
| 表 | 命令 | 依据 |
|---|---|---|
skill_xp | cli.ts xp [--base 300 --doubling 7 --max 99 --divisor 1] | 经验公式 |
monsters | cli.ts monsters | 按基准职业反推(12 秒打死、打掉 54% 血) |
consumables 的回血量 | cli.ts heals | 背后的村民工时 × 74 × 基准最大血量 |
house_costs | cli.ts houses [--report] | 1.6 × 1.28^(L−1) 个村民工时,村中心 ×1.5 |
map_sites 的坐标 | tools/art/map/gen-world.mjs | 程序化布局 |
asset_boxes | npm run art:import | 量图片的不透明区域 |
4. 命令行
node tools/config/cli.ts <命令>:
| 命令 | 做什么 |
|---|---|
check | CI 用的校验(npm run config:check) |
build [out] | 写出 config/dist/config.json |
xp / monsters / heals / houses | 生成上表那几张 |
curve | 只砍白桦时每级要多久 |
combat | 平衡报告:同职能差距、副本通关率与时长 |
upkeep | 战斗消耗折合几个村民(目标 1–1.5) |
art [--check] | 生成出图清单 art-source/MANIFEST.md |
5. 网页配表编辑器
管理后台 /idle/admin/ 的「配表」页,只有超级管理员能用:
- 在网页上改表格,「校验」走同一个
buildBundle,一次列出全部错误; - 「应用到线上」把改过的表写进数据卷的
config-override/,热更、广播config_changed,在线的客户端自动重拉配表; - 「恢复仓库配表」删掉覆盖;
- 「导出 CSV」拿回去提交。线上覆盖只是试数值用的,要长期生效必须导出、提交进仓库。
「经验曲线」页画出正在编辑的 skill_xp,可以切对数纵轴。
6. 改一张表的流程
- 改 CSV(或改生成器参数再重跑生成);
npm run config:check,有平衡相关的改动再看combat/upkeep报告;npm run ci全绿后提交。服务器重新部署后新配表生效,客户端不用重新打包。
为什么是 CSV 而不是 Luban 这类配表工具:表少而简单,CSV 能 diff、能 review、Excel 直接打开,自带校验就够了。表多到需要继承、多态、本地化时再换(core 的 ConfigBundle 形状不变即可)。