Game Config Edit

A Rust and Dioxus desktop editor for game CSV configuration files.

Game Config Edit（游戏配置编辑器）用于浏览、检查和编辑游戏项目中的 CSV 配置。它提供大表虚拟滚动、整列类型分析、JSON 聚焦查看、工作区搜索、安全保存和外部修改检测，并用明确的颜色区分错误、兼容性警告与多行文本。

安装与使用

支持 Windows x64 和 macOS Apple Silicon：

npm install --global game-config-edit
gconf [workspace]

workspace 是包含 CSV 配置的工作目录。省略参数时，程序会恢复最近的工作目录或显示目录选择器；双击程序启动与无参数启动行为一致。

支持的配置类型

程序支持两种配置结构：普通表和杂项表。文件名不参与类型识别。

普通表

除杂项表以外的 CSV 都按普通表处理。

• 支持 1–5 行表头，默认 2 行。
• 最后一行表头是字段名，之前的表头行是说明或注释。
• 数据从表头之后的第一条记录开始。
• 程序扫描整列数据并显示推断类型；类型行只用于展示和诊断，不会写入 CSV。
• 空单元格不参与整列类型推断，也不会单独产生类型错误。

一个使用两行表头的普通表示例：

说明,角色编号,角色名称,角色属性,掉落配置
字段,id,name,stats,rewards
示例,1001,哈哈哈,"{""hp"":100,""enabled"":true}","[{""mid"":1,""num"":2}]"
示例,1002,Arthur,"{""hp"":120,""enabled"":false}","[{""mid"":2,""num"":1}]"

该示例会显示类似以下类型：

| 字段 | 类型 | |---|---| | 字段 | string | | id | number | | name | string | | stats | {enabled:bool;hp:number} | | rewards | {mid:number;num:number}[] |

普通表支持的类型

| 类型 | 示例 | 规则 | |---|---|---| | string | hello、100级开放 | 普通文本；数字与普通文本混合时整列也归为 string | | number | 123、-3.14、1e3 | 必须是有限且符合 JSON number 语法的数值；纯 0/1 列属于 number | | bool | true、false | 大小写敏感；出现文本布尔值时可以与 0/1 混用 | | JSON 对象 | {"mid":1,"name":"哈哈哈"} | 必须是完整 JSON 对象，类型行显示递归的具体字段类型 | | JSON 数组 | [1,2,3]、[[1,2],[3,4]] | 支持嵌套数组、对象数组和异构元素，按实际内容显示具体类型 | | 分隔符数组 | "a","b"、"a","b";"c","d" | 这是解析后的单元格值；元素必须由双引号包围，逗号分隔元素，分号分隔二维分组。写入逗号 CSV 时还要按 CSV 规则整体引用并双写内部引号 |

结构化类型使用类似 TypeScript 的表达式：string[]、number[][]、{id:number}[]、{mid:number;name:string}、{id:number;name?:string} 和 (number|string)[]。空数组显示为 unknown[]。

程序会合并整列中的合法结构值。只要一列出现合法 JSON 对象，该列其他非空值也必须是 JSON 对象；数组列遵循相同规则，不匹配的单元格会标红。

mixed 是黄色诊断结果，不是建议使用的配置类型。它表示整列包含无法归入同一基础类型的值，例如 true 与 2。标量文本 null 在普通表中按 string 处理；null 只会作为 JSON 对象字段或数组元素出现在具体类型表达式中。

杂项表

同时满足以下条件时自动识别为杂项表：

• 所有 CSV 记录都恰好有 4 列。
• 第二条记录的前三个字段严格依次为 valueType、key、value。
• 第四个字段名不限，固定作为说明文本。

杂项表固定使用两行表头，不显示普通表的自动类型推断行。第二列的非空 key 必须区分大小写且不能重复；第三列的值按同一行第一列的类型声明校验。

杂项表示例：

类型,键,值,说明
valueType,key,value,note
number,MAX_LEVEL,100,等级上限
bool,FEATURE_OPEN,true,功能开关
string,WELCOME_TEXT,欢迎回来,登录提示
number[],REWARD_IDS,"1001,1002,1003",奖励 ID
"{mid:number,num:number}[]",SHOP_ITEMS,"[{""mid"":1001,""num"":2}]",商店物品

杂项表支持的声明类型

| 声明 | 接受的值 | |---|---| | string | 任意文本，包括空值和看起来像数字的文本 | | number | 有限且符合 JSON number 语法的数值 | | bool | true、false、0 或 1 | | null | 只能是字面量 null | | number[]、string[] | JSON 数组、逗号分隔值或单个元素；空数组使用 [] | | string[][] 等嵌套数组 | 必须使用符合声明层级的 JSON 数组 | | {mid:number,num:number} | 必须使用 JSON 对象，字段集合和每个字段的类型都要完全一致 | | {mid:number,num:number}[] | 必须使用符合对象声明的 JSON 对象数组 |

数组可以嵌套任意层，对象字段名可以是合法标识符或 JSON 双引号字符串。杂项表声明不支持联合类型和可选字段；对象多字段、少字段或字段类型不正确都会标红。

什么是合规配置

本项目将“能够正确解析且没有红色错误”的配置定义为合规配置。黄色警告表示兼容性风险，但不阻止保存，也不影响基本合规结论。

文件与 CSV 结构

• 可编辑配置使用 UTF-8 或 UTF-8 BOM。GB18030 文件可以预览，但确认转换并保存为 UTF-8 后才属于可编辑的合规配置。
• 分隔符必须是逗号、制表符、分号或竖线之一；无法可靠识别时需要手动选择正确分隔符。
• 所有记录的字段数必须一致。
• 标准引用字段必须正确闭合，字段关闭引号后不能出现非法字符。
• JSON 写入 CSV 引用字段时，JSON 内部的 " 要按 CSV 规则写成 ""，如上面的示例所示。
• 普通表必须包含所配置数量的表头记录；杂项表必须满足固定四列和第二行字段名规则。

红色错误

存在以下任一情况时，配置不合规：

• CSV 无法解析或记录列数不一致。
• 普通表的结构化列存在对象、数组类型不匹配。
• 单元格包含 Tab、全角空格、零宽字符或 BOM 等危险不可见字符。
• 杂项表的 valueType 声明无效。
• 杂项表存在重复的非空 key。
• 杂项表的 value 不符合同行声明，或对象字段集合不完全一致。

红色错误会计入状态栏、进入 F8 导航，并在保存前要求再次确认。

黄色警告与多行文本

• 黄色 mixed 表示普通表整列包含不兼容的基础类型。
• 普通字符串中的未转义 ASCII 双引号或非法反斜杠转义会标黄。这些内容可能被部分直接拼接字符串的转换工具错误处理。
• 合法转义包括 \"、\\、\/、\b、\f、\n、\r、\t 和 \uXXXX。
• 黄色警告可以通过 F8 导航，但不会触发保存确认。
• 包含真实 CR/LF 的单元格使用青绿色表示多行文本。这不是错误或警告，原始换行会完整保留。

合规检查清单

1. 文件是 UTF-8 或 UTF-8 BOM，分隔符选择正确。
2. CSV 能完整解析，所有记录列数一致，引用字段正确闭合。
3. 普通表的表头行数正确；或者文件严格符合杂项表的四列结构。
4. 普通表的 JSON 对象和数组在整列中结构分类一致。
5. 杂项表没有重复 key，所有类型声明和值匹配。
6. 状态栏没有红色单元格或 CSV 解析错误。
7. 如需兼容直接拼接字符串的下游工具，再处理所有黄色警告。

完整产品行为和验收标准见 GitHub 仓库。npm 页面上的说明随包版本发布。