配置表工具链:从 Excel 到运行时数据,导出、代码生成、校验与加载
一、为什么需要工具链
游戏中的大量数据由策划配置:物品、技能、怪物、关卡、任务、商店、掉落、文本。策划最熟悉的工具是 Excel,而程序需要的是类型明确、加载快、不出错的数据。
配置表工具链连接两者:
策划编辑 Excel │ 导表工具 ├─▶ 数据文件(二进制 / JSON) → 客户端、服务器加载 ├─▶ C# 数据类与加载代码(自动生成) → 程序直接使用,强类型 └─▶ 校验报告 → 配置错误在导表时就被发现目标是:策划改完表、导出,程序不需要改任何代码就能拿到新数据;错误在导表时被拦截,而不是上线后才发现。
二、表头约定
每张表的前几行用来描述字段:
| 行 | 内容 | 例子 |
|---|---|---|
| 字段名 | 程序中使用的名字 | id name quality price skills |
| 类型 | 字段的数据类型 | int string int int int[] |
| 导出目标 | 这个字段给谁用 | cs(双端)c(仅客户端)s(仅服务器) |
| 说明 | 给策划看的中文注释 | 编号、名称、品质、售价、技能列表 |
| 数据行 | 1001 生命药水 2 50 3001,3002 |
复杂类型的表达:
| 类型 | 写法举例 |
|---|---|
| 数组 | 3001,3002,3003 |
| 结构 | (x=1,y=2) 或者拆成多列 |
| 结构数组 | 物品奖励 1001:5;1002:10(ID:数量;ID:数量) |
| 枚举 | 写枚举名而不是数字:Physical、Magic |
| 引用其他表 | 写另一张表的 ID,并在校验中检查存在性 |
约定好统一的语法,并由工具解析和校验,而不是每张表各自约定、程序各自解析。
三、导出格式
| 格式 | 优点 | 缺点 |
|---|---|---|
| JSON | 可读,方便排查 | 体积大、解析慢、解析时产生大量 GC |
| 二进制(自定义或 Protobuf) | 体积小、加载快 | 不可读 |
| FlatBuffers | 不需要反序列化,读取时直接访问字段,可以按需读取 | 构建复杂,体积比 Protobuf 大 |
配置表通常数据量大、只读,加载速度和内存是主要关注点,所以正式包一般使用二进制格式,开发时可以同时导出 JSON 方便查看。格式的对比见 序列化与网络协议。
四、代码生成
根据表头自动生成数据类和加载代码:
// 自动生成,不要手动修改public sealed partial class ItemConfig{ public int Id { get; private set; } public string Name { get; private set; } public int Quality { get; private set; } public int[] Skills { get; private set; }
internal static ItemConfig Read(ByteReader r) => new ItemConfig { Id = r.ReadInt(), Name = r.ReadString(), Quality = r.ReadInt(), Skills = r.ReadIntArray() };}
public sealed class ItemTable{ readonly Dictionary<int, ItemConfig> _map = new(); public IReadOnlyCollection<ItemConfig> All => _map.Values; public ItemConfig Get(int id) => _map.TryGetValue(id, out var v) ? v : null; // 加载代码……}- 程序使用强类型的字段:
Tables.Item.Get(1001).Name,字段改名或删除时编译就会报错,而不是运行时出问题; - 生成的类用
partial,需要附加的计算属性或方法写在另一个文件中,重新生成时不会被覆盖(见 partial); - 配置数据在运行时应该是只读的:属性的 setter 设为私有,集合对外暴露只读接口,防止某处代码修改了配置,影响到所有使用它的地方。
五、校验
导表时的校验是工具链最有价值的部分之一,它把错误挡在打包之前:
| 校验 | 例子 |
|---|---|
| 类型 | int 列中填了文字 |
| 必填 | 物品名称为空 |
| 唯一性 | 两行的 ID 重复 |
| 范围 | 概率不在 0 到 1 之间,品质超出定义的范围 |
| 引用 | 技能表中引用的特效 ID 在特效表中不存在;奖励中的物品 ID 不存在 |
| 资源 | 填写的图标路径、Prefab 路径对应的资源不存在 |
| 业务规则 | 一组掉落的权重之和为 0;关卡的解锁条件引用了还没开放的关卡 |
校验失败时给出明确的位置(哪张表、哪一行、哪一列、什么问题),让策划自己就能修正。
六、运行时的加载与索引
- 按需加载:配置表很多时,不要在启动时把所有表都加载进内存。第一次访问某张表时再加载(懒加载),或者按功能模块分组加载。
- 建立索引:最常用的是按 ID 查找,用字典建立索引;其他常用的查询(按类型、按关卡)也可以预先建立分组。
- 内存:大量重复的字符串(比如很多物品的类型名称)可以在加载时去重;或者使用 FlatBuffers 这类不需要完全反序列化的格式。
- 热更新:配置表的数据文件作为资源一起热更新(见 热更新)。如果生成的代码也有变化(新增了字段),代码也需要热更新。
七、前后端共用
服务器同样需要配置(掉落、商店价格、技能伤害)。同一份 Excel 同时为客户端和服务器导出,保证双方使用的数据一致:
- 通过字段的导出目标,只给客户端导出界面相关的字段(图标、描述),只给服务器导出敏感的字段(掉落概率、怪物刷新规则);
- 敏感数据不应该出现在客户端的包中,否则玩家解包就能看到。
八、多人协作
- Excel 是二进制文件,版本控制中无法合并。两个人同时修改同一张表就会冲突。常见的应对:表按功能拆分得更细;修改前先锁定文件;或者改用基于文本的格式保存源数据。
- 导表纳入 CI 流程:提交后自动导出和校验,失败时通知修改者(见 自动化打包)。
- 国内项目常用的开源导表工具(比如 Luban)已经实现了上面的大部分功能:多种数据格式、代码生成、校验、前后端分离导出,可以直接采用,而不必从零开发。
常见追问
配置表工具链做了什么? 把策划编辑的 Excel 导出成程序使用的数据文件,自动生成强类型的数据类和加载代码,并在导出时做数据校验。
配置表用什么格式导出? 开发时可以用 JSON 方便查看,正式包一般用二进制(自定义、Protobuf)或 FlatBuffers,体积小、加载快、GC 少。
为什么要生成代码,而不是手写读取? 强类型,字段变化时编译期就能发现;减少重复劳动和手写错误;加载代码统一、高效。
导表时应该做哪些校验? 类型、必填、唯一性、数值范围、表之间的引用、资源是否存在、业务规则。
配置表在运行时怎么管理? 按需加载,按 ID 建立字典索引,数据只读,常用的查询预先分组。
服务器的敏感配置怎么处理? 按字段的导出目标分别导出,敏感字段只导给服务器,不打进客户端的包中。
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!