配置系统 API

基本信息

属性 值
根注解 com.gtnewhorizon.gtnhlib.config.Config
管理器 com.gtnewhorizon.gtnhlib.config.ConfigurationManager
字段解析 com.gtnewhorizon.gtnhlib.config.ConfigFieldParser
包路径 src/main/java/com/gtnewhorizon/gtnhlib/config/（10 个类）
沿革 源自 FalsePattern，LGPL-3.0（README.md Credits 节）

这是 GTNHLib 被引用最多的 API：ae2stuff 等下游 mod 直接在自己的 mod 根包放一个带 @Config 的类即可获得配置读写、校验与 Forge 配置 GUI，无需手写任何 Configuration 调用。

功能

在类上标注 @Config，其每个字段即成为一个配置项。README 的描述（README.md Config 节）：

Define configs with the @Config annotation on a class. Each field becomes a config option. Set defaults, ranges, comments, and lang keys with field annotations like @DefaultInt, @RangeInt, and @Comment. The library reads, writes, and validates the .cfg file for you. No manual Configuration calls. Mark fields @Sync to push server values to clients on connect. Generates a Forge config GUI straight from the annotations.

类级注解 @Config

config/Config.java:14 起，@Retention(RUNTIME)、@Target(TYPE)。成员：

成员 默认值 说明
modid() 必填 关联的 mod id
category() "general" 根分类名
configSubDirectory() "" 配置文件子目录，相对 config/；如 "myMod"
filename() "" 文件名；留空则回退为 modid
categoryCulling() true 自动清除处理中未观察到的陈旧分类

文件名解析在 config/ConfigurationManager.java:71：

final var filename = Optional.of(cfg.filename().trim()).filter(s -> !s.isEmpty()).orElse(modid);

扩展名由 ConfigurationManager.java:82 的 filename + ".cfg" 自动补上。

categoryCulling 的注解（config/Config.java:41-49）明确要求：若 mod 使用动态创建或外部管理的分类，应关闭它，否则会被清掉。

字段注解

config/Config.java 共定义 28 个嵌套注解（grep -c '@interface ' config/Config.java = 29，含根注解自身），绝大多数为 @Target(FIELD)，少数允许 TYPE（用于 GUI 分组/排序，如 @Config.Order、@Config.Entry）。常用的有：

注解 作用
@Config.Comment 说明文字，支持字符串数组
@Config.DefaultBoolean / DefaultInt / DefaultFloat / DefaultString / DefaultDouble / DefaultEnum 声明默认值
@Config.DefaultStringList / DefaultIntList / DefaultDoubleList 声明列表型默认值
@Config.RangeInt / RangeFloat / RangeDouble 取值范围，越界被拒绝
@Config.RequiresMcRestart / RequiresWorldRestart 标注需重启生效（生成 GUI 提示）
@Config.Sync 玩家加入时由服务端推送至客户端
@Config.Ignore 跳过该字段（Config.java:95，无成员）
@Config.LangKey / LangKeyPattern 指定语言键与键内格式化模式
@Config.Order / Config.Entry 控制配置 GUI 的排序与自定义条目
@Config.Name 覆盖 GUI 中的显示名
@Config.Pattern 正则校验
@Config.Reloadable 支持运行时重载
@Config.RequiresMod 仅在指定 mod 加载时生效
@Config.ModDetectedDefault / ModDetectedDefaultList 按已加载 mod 集合决定默认值
@Config.ExcludeFromAutoGui 不进自动生成的 GUI，需自行提供条目

ConfigurationManager 入口

config/ConfigurationManager.java:38 起，全部为静态方法：

方法 用途
registerConfig(Class<?>) 注册配置类，抛 ConfigException（:66）
save(Class<?>...) 落盘（:101）
reloadConfig(Class<?>, String) 重载（:121）
getConfigElements(Class<?>) 生成 Forge IConfigElement 列表（:315）
getConfigElements(Class<?>, boolean) 同上，可指定是否分类分组（:327）
getConfigElementsMulti(Class<?>...) 跨多个配置类生成（:361）
getConfigElementsMulti(boolean, Class<?>...) 同上（:366）
getConfig(Class<?>) 取底层 Configuration（:511）
isModRegistered(String modid) 判定 mod 是否已注册配置（:524）
onInit() FML init 阶段调用（:532）
applyConfigEntries() 应用 @Config.Entry 自定义条目（:540）

顶层公开静态方法共 11 个；第 12 个 public static 成员是内部类 ConfigNode（:629），不是方法。

ConfigNode 内部类（:629）承载 GUI 树，每个节点含 order、requiredModsOr、requiredModsAnd 与 children，即按 mod 是否加载条件显示配置分组。

数值

数值名 值
config 包类数 10
@Config 类级成员数 5
@Config 嵌套注解数 28
ConfigurationManager 顶层公开静态方法 11
GTNHLib 自身注册的 @Config 类 3（GTNHLibConfig、NumberFormatConfig、ExampleConfig）

交互

典型用法三步：

  1. 在 mod 根包写一个类，标注 @Config(modid = "yourmod")
  2. 每个字段加 @Config.Comment + @Config.DefaultXxx（+ 可选 @Config.RangeXxx）
  3. 在 preInit 调 ConfigurationManager.registerConfig(YourConfig.class)

注册时机很关键：想在 mixin 构造期就读到配置值，必须在 coremod 构造器里注册。GTNHLib 自身就是这么做的 —— GTNHLibCore() 构造器直接 registerConfig(GTNHLibConfig.class)（core/GTNHLibCore.java:57）。

registerConfig 抛出的 ConfigException 在 GTNHLibCore 与 CommonProxy 中都被包成 RuntimeException 抛出（CommonProxy.java:100-102），即配置错误会导致启动失败而非静默降级。

相关条目