路径追踪控制文件
2025/7/17
路径追踪控制文件
概述
本说明用于指导编写控制文件(control.json5
),该文件用于定义JSON合并规则。当程序加载追踪文件(*.json
)时,会根据控制文件中的规则对追踪文件内容进行合并处理。虽然文件名使用.json5
后缀(方便编辑器支持语法高亮),但实际只支持标准JSON格式(不支持注释、尾随逗号等JSON5特性)。
应用场景
场景一:批量统一标注与配置
需求:为整个系列的追踪文件统一添加标签、作者和版本信息
问题:手动修改几十上百个文件耗时且易出错
解决方案:使用全局覆盖规则统一添加
{
"global_cover": {
"info": {
"_arr_add": ["tags"],
"tags": ["纳塔地区", "材料收集"],
"author": "项目组",
"version": "2.0",
"enable_monster_loot_split": true
}
}
}
效果:
- 所有追踪文件自动添加
["纳塔地区", "材料收集"]
标签(保留原有标签) - 统一设置作者为"项目组"
- 统一版本升级为"2.0"
- 所有文件启用怪物标记区分功能
场景二:批量修改与导出
需求:批量修改蒙德地区所有追踪文件的描述信息
解决方案:使用特定覆盖规则+导出功能
{
"json_list": [
{
"name": "107蒙德风龙废墟南",
"cover": {
"info": {
"description": "风龙废墟南侧-风神瞳收集点(2024更新)"
}
}
},
{
"name": "108蒙德风龙废墟北",
"cover": {
"info": {
"description": "风龙废墟北侧-宝箱收集点(2024更新)"
}
}
}
]
}
操作流程:
- 在调度器中点击"更多功能"
- 选择"导出根据控制文件修改内容"
- 系统批量生成更新后的追踪文件,需自行拷贝覆盖
场景三:支持脚本特殊需求
需求:为特定追踪文件添加脚本所需的特殊参数
问题:不同脚本需要不同的参数配置
解决方案:使用特定覆盖规则添加自定义属性
{
"json_list": [
{
"name": "330【水免】【高危】稻妻渊下宫大日御舆西",
"cover": {
"script_params": {
"difficulty": "extreme",
"element_immunity": ["hydro"],
"recommended_level": 90
}
}
},
{
"name": "416须弥沙漠五绿洲的子遗地下",
"cover": {
"script_params": {
"environment": "sandstorm",
"visibility": 0.4
}
}
}
]
}
文件位置
请将控制文件命名为 control.json5
,并放置在相应的路径追踪目录下,作用于该目录下或指定部分的文件,如果想控制子目录里的,则子目录可以通过ref参数,引用父目录文件(也支持多层级)。
引用方式
{
"ref":".."
}
基本结构
{
"global_cover": {
// 全局覆盖规则(应用于所有追踪文件)
},
"json_list": [
{
"name": "追踪文件名称", // 必须与追踪文件名(没有.json后缀)需要和info.name完全匹配
"cover": {
// 针对该追踪文件的覆盖规则
}
}
// 可添加多个规则
]
}
全局覆盖规则(global_cover)
- 应用于所有追踪文件
- 在特定覆盖规则之前应用
- 支持普通属性覆盖、数组合并和对象覆盖指令
示例:
{
"global_cover": {
"info": {
"_arr_add": ["tags"],
"enable_monster_loot_split": true,
"tags": ["材料一", "材料二"],
"other_params": {
"custom": "global_value"
}
}
}
}
特定覆盖规则(json_list)
- 根据追踪文件名和控制里面
info.name
进行匹配 - 在全局覆盖之后应用
- 支持所有全局覆盖的功能
结构:
{
"name": "追踪文件名称",
"cover": {
// 覆盖规则(同global_cover)
}
}
示例:
{
"name": "6101--纳塔_镜璧山_西海岸1_(8-13)",
"cover": {
"_obj_over": ["info"],
"info": {
"type": "collect3",
"tags": ["材料", "怪物"]
},
"positions": [
{
"id": 1,
"x": 10000.0
}
]
}
}
特殊指令
1. 数组合并指令 _arr_add
- 作用:将指定数组与原数组合并(去重)
- 值类型:字符串数组(指定要合并的属性名)
- 位置:在要合并的数组的同级对象中
"_arr_add": ["tags", "authors"]
2. 对象覆盖指令 _obj_over
- 作用:完全覆盖指定对象(而不是合并)
- 值类型:字符串数组(指定要覆盖的属性名)
- 位置:在要覆盖的对象的同级对象中
"_obj_over": ["info", "other_params"]
合并规则详解
1. 默认合并行为
- 普通属性(字符串、数字、布尔值):直接覆盖
- 对象:递归合并属性
- 数组:直接覆盖(除非使用
_arr_add
指令)
2. 指令优先级
_obj_over
(对象完全覆盖)_arr_add
(数组合并)- 默认合并行为
3. 合并顺序
- 应用全局覆盖规则(
global_cover
) - 查找匹配的特定覆盖规则(
json_list
) - 应用匹配的特定覆盖规则
完整示例
{
"global_cover": {
"info": {
"_arr_add": ["tags"],
"enable_monster_loot_split": true,
"tags": ["材料1", "材料2"],
"version": "1.6"
}
},
"json_list": [
{
"name": "6101--纳塔_镜璧山_西海岸1_(8-13)",
"cover": {
"_obj_over": ["info"],
"info": {
"type": "collect3",
"tags": ["材料", "怪物"]
},
"positions": [
{
"id": 1,
"x": 10000.0
}
]
}
},
{
"name": "107蒙德风龙废墟南",
"cover": {
"info": {
"description": "风龙废墟南侧收集点"
}
}
}
]
}
注意事项
- 文件格式限制:虽然可以使用
.json5
后缀名(方便编辑器高亮),但文件内容必须是标准JSON格式(不支持注释、尾随逗号等JSON5特性) - 名称匹配:
name
匹配是大小写敏感的,必须与追踪文件名(不包含扩展)一致 - 数组去重:基于元素的JSON字符串表示进行去重
- 对象覆盖:
_obj_over
会完全替换整个对象(包括所有子属性) - 未匹配处理:未匹配到特定规则时,只应用全局规则
- 属性路径:规则支持任意层级的嵌套属性
最佳实践
- 使用支持JSON高亮的编辑器(如VSCode)
- 名称匹配建议复制追踪文件中的实际名称
- 先测试全局规则,再添加特定规则
- 复杂规则先在小范围测试
- 保持控制文件简洁,避免过度复杂嵌套
常见问题
Q: 为什么我的规则没有生效?
A: 请检查:
- 控制文件位置是否正确
name
是否完全匹配(包括大小写)- JSON格式是否正确(可使用JSON验证工具)
- 特殊指令的拼写是否正确(
_arr_add
,_obj_over
)
Q: 如何为多个文件应用相同规则?
A: 在json_list
中为每个文件创建单独的规则项
Q: 如何完全替换数组而不是合并?
A: 不使用_arr_add
指令,直接提供新数组值
Q: 如何删除已有属性?
A: 目前不支持属性删除,可设置为空值(如"property": null
)