跳到正文

配表:CSV 唯一源与配表工具

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

数值只进 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词条定义、各部位各池的权重
家园houses12 座建筑
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 一次报出全部错误,格式是 表:行 列 — 说明。检查顺序:

  1. 列类型、id 唯一、引用存在;
  2. constants 的键集合必须和代码里的 CONSTANT_KEYS 完全一致(不多不少);
  3. 经验曲线严格递增;
  4. 生成炼金动作:每样有炼金价的物品一个 gold_<物品>,等级要求 = 物品等级。在 actions.csv 里手写 gold_* 是错误;
  5. 战斗、工坊、家园、地图各自的检查:副本不能选难度、村中心 0 级人数等于常数、人数不减少……;
  6. 材料档位对齐(checkTierAlignment,见 村民与经济 );
  7. 为了让客户端预测可信:动作的原料不能是它自己的产出;怪物掉落不能是消耗品。

构建结果的版本号是规范化 JSON 的 sha256 前 16 位。服务器把它当 GET /config 的 ETag,客户端没变就拿 304。

3. 生成的表:别手改,改生成器

有几张表是从别的表和公式算出来的,手改会被下一次生成覆盖,有的还有测试盯着「CSV 和生成器对得上」:

表命令依据
skill_xpcli.ts xp [--base 300 --doubling 7 --max 99 --divisor 1]经验公式
monsterscli.ts monsters按基准职业反推(12 秒打死、打掉 54% 血)
consumables 的回血量cli.ts heals背后的村民工时 × 74 × 基准最大血量
house_costscli.ts houses [--report]1.6 × 1.28^(L−1) 个村民工时,村中心 ×1.5
map_sites 的坐标tools/art/map/gen-world.mjs程序化布局
asset_boxesnpm run art:import量图片的不透明区域

4. 命令行

node tools/config/cli.ts <命令>:

命令做什么
checkCI 用的校验(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. 改一张表的流程

  1. 改 CSV(或改生成器参数再重跑生成);
  2. npm run config:check,有平衡相关的改动再看 combat / upkeep 报告;
  3. npm run ci 全绿后提交。服务器重新部署后新配表生效,客户端不用重新打包。

为什么是 CSV 而不是 Luban 这类配表工具:表少而简单,CSV 能 diff、能 review、Excel 直接打开,自带校验就够了。表多到需要继承、多态、本地化时再换(core 的 ConfigBundle 形状不变即可)。