文件目录结构

配表系统采用模块化的目录结构设计，确保数据组织清晰、维护方便。

核心设计原则

模块化组织：CSV和Excel文件都应放置在子文件夹中（如equip/目录），尽量避免在顶层目录直接放置数据文件
职责分离：
- Excel、CSV、JSON文件：由策划人员填写数据内容
- CFG文件：由程序人员维护数据结构定义
命名规范：文件和目录命名遵循统一的命名规则

文件类型说明

文件类型	用途	主要维护者
Excel (.xlsx/.xls)	存储游戏配置数据	策划
CSV (.csv)	存储游戏配置数据	策划
JSON (.json)	存储复杂数据结构，用cfgeditor.exe来配置	策划
CFG (.cfg)	定义数据结构规范	程序

示例：数据文件与配置文件的对应关系

数据文件 (levelUp.xlsx)

id	升级经验	等级奖励
id	upgradeExp	levelAward
1	60	1000082
2	70	0
3	80	0
4	90	0

配置文件 (levelUp.cfg)

table levelup[id] {
  id:int;
  upgradeExp:int; // 升级经验
  levelAward:int; // 等级奖励
}

工作流程

新建或修改数据结构

创建数据文件
- 新建或修改CSV/Excel文件
- CSV文件前2-3行作为表头：
  - 第1行：中文描述
  - 第2行：程序用字段名
  - 第3行：可选，可约定填写类型（实际类型以CFG文件为准）
生成配置文件
- 使用cfggen工具自动生成CFG文件
- 如自动生成的CFG不满足需求，手动修改以下配置：
  - 数据类型定义
  - 主键、唯一键、外键约束
  - 枚举类型定义
  - 取值约束条件

修改数据内容

编辑数据：直接修改CSV或Excel文件中的数据内容
数据校验：双击校验数据.bat
处理结果：
- 如校验出错：根据错误提示修改数据
- 如校验成功：可提交到版本控制系统

表间关联支持

系统支持表之间的链接关系，例如：

完成任务配置中的KillMonster参数monsterid，必须在monster表中存在对应记录
此类关联关系需要在CFG文件中进行配置

文件命名规范

通用规则

首字符要求：必须以英文字母（a-z, A-Z）开头

命名解析逻辑：

截取第一个"."之前的内容 → 再截取"_汉字"或汉字之前的部分 → 作为模块名/表名

目录命名

首字母必须是英文字符
遵循模块化命名原则

CFG文件

根目录：必须存在 config.cfg
模块目录：每个模块目录下需有 [模块名].cfg

CSV文件

文件后缀：.csv

命名规则：

截取".csv"之前的内容 → 再截取"_汉字"或汉字之前的部分 → 作为表名

合法格式：
- [表名]_[索引]
- [表名]

Excel文件

文件后缀：.xls 或 .xlsx

Sheet命名：

截取"."之前的内容 → 再截取"_汉字"或汉字之前的部分 → 作为表名

合法格式：
- [表名]_[索引]
- [表名]

JSON文件

目录命名：
```
_[表全名.replace(., _)]/
```
例如：表名为skill.buff → 对应目录为_skill_buff
文件命名：以主键pack的字符串值命名，如1.json

忽略机制

文件忽略规则

CSV文件：文件名不以英文字母开头的文件将被忽略
Excel文件：Sheet名称不以英文字母开头的Sheet将被忽略
通用忽略：
- 以~开头的文件
- 隐藏文件

行列忽略规则

忽略列：如果表头第二行（程序用名）中的单元格为空，则该列将被忽略
忽略行：
- 数据行全部为空的
- 数据行第一个单元格内容以#开头的

示例说明

序号	策划用列	名字	掉落0件物品的概率	掉落1件物品的概率
lootid		name	chance1	chance2
1		测试掉落	100	200
#这行会被忽略
2	XXX用	小宝箱	0	100

4		大宝箱	0	100
5		测试掉落2	20	10

忽略说明：

第2列（策划用列）：程序用名为空，整列被忽略
第4行：以#开头，整行被忽略
第6行：全部为空，整行被忽略

文件组织方式

cfggen 支持两种数据文件组织方式，根据项目规模选择合适的结构：

方式 1: 平铺结构（适合小型项目）

所有数据文件直接放在 config/ 根目录下，适合表数量较少的小型项目。

config/
├── config.cfg           # 结构定义文件
├── item.xlsx            # item表数据
├── task.xlsx            # task表数据
└── reward.xlsx          # reward表数据

特点：

结构简单，适合快速原型开发
文件数量较少时易于管理
随着项目扩大，维护成本会增加

方式 2: 模块化目录结构（推荐，适合中大型项目）

按功能模块组织子目录，每个模块包含相关的表和数据定义文件。

config/
├── config.cfg
├── item/                # item模块
│   ├── item.cfg
│   ├── item.xlsx
│   └── itemtype.xlsx
├── task/                # task模块
│   ├── task.cfg
│   ├── task_任务.xlsx
│   └── completeconditiontype.xlsx
└── equip/               # equip模块
    ├── equip.cfg
    ├── equip.xlsx
    └── rank.xlsx

特点：

职责清晰，模块间低耦合
易于团队协作和分工
支持多语言别名（如 task_任务.xlsx）
便于版本控制和增量更新

详细说明：下面的”目录结构示例”展示了实际项目中的完整目录结构

目录结构示例

config/
│   config.cfg
│
├───ai_行为
│       ai.cfg
│       ai行为.xlsx
│
├───equip
│       ability.csv
│       equip.cfg
│       equipconfig.csv
│       jewelry.csv
│       jewelryrandom.csv
│       jewelrysuit.csv
│       jewelrytype.csv
│       rank.csv
│
├───other
│       drop.csv
│       loot.csv
│       lootitem.csv
│       lootitem_1.csv
│       lootitem_2.csv
│       monster.csv
│       other.cfg
│       signin.csv
│
├───task
│       completeconditiontype任务完成条件类型.csv
│       task.cfg
│       taskextraexp.csv
│       task_任务.csv
│
├───_other_keytest
│       0.json
│       1,2.json
│
└───_task_task2
        1.json
        2.json
        3.json
        4.json
        5.json
        6.json
        7.json
        8.json

高级功能

支持兼容旧的表格结构，也可用于只读取datadir目录下的特定子目录。

配置参数

-asroot

兼容旧版目录结构（ClientTables、PublicTables、ServerTables目录）
配置格式：'ClientTables:noserver,PublicTables,ServerTables:noclient'
配合gen的own参数使用：
- own:-noclient 提取客户端数据
- own:-noserver 提取服务器数据

-exceldirs

指定Excel目录，多个目录以逗号分隔

-jsondirs

指定JSON目录，多个目录以逗号分隔
注意：一旦配置了-asroot、-exceldirs或-jsondirs任一参数，
系统将只使用-datadir下的指定目录，而不是全部目录

-headrow

旧版TSV文件配置（.txt后缀）
表头为4行结构：
第1行：程序用字段名
第2行：数据类型（INT, SHORT, BYTE, INT64, FLOAT, BOOL, STRING）
第3行：其他信息
第4行：中文描述

快速参考

项目	规则	示例
目录命名	英文字母开头	`equip`, `ai_行为`
CSV文件	`.csv`后缀，英文字母开头	`ability.csv`, `task任务.csv`
Excel Sheet	英文字母开头	`levelup`, `monster_1`
CFG文件	模块名.cfg	`equip.cfg`, `task.cfg`
JSON目录	`_[表全名.replace(., _)]`	`_skill_buff/`
忽略文件	非字母开头	`~temp.csv`, `.hidden`
忽略列	程序用名为空
忽略行	全空或以`#`开头	`#注释行`, 空行