localconfig 条目语法

基本信息

属性	值
解析器	`localconfig/LocalConfigEntry.fromString(line, withValue)`
语法说明来源	jar 内 `/assets/defaultkeys/default-localconfig.txt` 的注释头
预设示例	jar 内 `/assets/defaultkeys/example-localconfig.txt`（首次启动自动生成到 `config/localconfig-example.txt`）

基本形式

FILE/CATEGORY/TYPE:NAME

TYPE: 可省略，省略时 type 置为 "*"
CATEGORY 省略时置为 "*"
分类层级用 . 分隔，如 general.subcategory
注释行（# 开头）与空行返回 null，被调用方跳过

转义与特殊字符

语法	含义
`[...]`	转义，用于文件名中含 `/`（子目录）时，如 `[eirairc/shared.cfg]`
`"..."`	引号区内的 `/` `:` `$` `` `#` 均不作为语法字符*处理
`!` 前缀	否定条目（`not = true`），用于在通配条目下排除特定项
`*`	通配符，可出现在 `CATEGORY` / `NAME` / `TYPE` 中；文件名中不允许
`$key`	无值参数，如 `$format=simple` 的 `format`
`NAME<>`	后缀 `<>` 表示该项是列表，等价于在 TYPE 后追加 `<>`（如 `I<>`）

解析器中 * 出现在文件名位置会报错并丢弃整行（LocalConfigEntry.java:113-118）。

TYPE 的含义

TYPE 是 Forge 配置的单字符类型前缀：B（布尔）、I（整数）、S（字符串）、D（双精度）。

在 forge 格式中，解析器从属性名首字符取 type、再跳过后续 2 个字符（name = name.substring(0, 1); name = name.substring(2);），即匹配 B:foo 这样的写法。

simple 与 ini 处理器调用时把 type 固定传 "*"。

通配匹配算法

passesWithWildcard(pattern, value)（:169-199）是一个标准的贪心 * 通配实现（类 glob）：

pattern 或 value 为 "*" → 直接 true；
用 starIndex / starMatchIndex 回溯，无正则依赖。

passesProperty(category, name, type) 对三个维度同时做该匹配（:160-163）。

containsWildcard() 只检查 category / name / type 三者是否含 *。

否定条目的作用范围

! 条目只在被否定对象自身含通配符时才生效。三个 handler 里的判断都是同一形状：

if (entry.containsWildcard()) {
    for (LocalConfigEntry notEntry : notEntries) {
        if (notEntry.passesProperty(category, name, type)) {
            continue lineLoop;   // backup 中跳过该行
        }
    }
}

即 ! 只能用来细化一条通配条目，不能用来"删除"一条精确条目。

定义行 vs 值行

fromString 有 withValue 参数：

文件	`withValue`	允许 `=`
`config/localconfig.txt`	`false`	不允许，出现即报错丢行
`localconfig.cfg`	`true`	允许，`=` 后为旧值

值行中还支持 $ 段：withValue && value == null 时 $ 之后的内容取为 value。

识别符

getIdentifier(file, category, type, name) 产出 file/category/type:name 形式（文件名含 / 时自动加 []），是写入 localconfig.cfg 的键，也是 warn 日志里显示的标识。

限制

解析器是手写字符扫描器，不是分词器；语法错误只记 logger.error 并丢弃整行，无行号、无行上下文恢复。
同一个 file//format 分组内条目首个匹配即 break，重叠写法只有第一条生效，顺序敏感。
恢复时必须先在 config/localconfig.txt 找到匹配定义才会采用旧值（restoreLocalConfig 的双重循环），否则该旧值被静默丢弃。
example-localconfig.txt 只在 config/localconfig-example.txt 不存在时复制一次；玩家删掉后会重新生成，修改它无意义（它只是只读参考）。