配置

配置定义可应用于模组实例的设置和用户偏好。Forge 的配置系统使用 TOML 文件，并通过 NightConfig 读取。

Forge 配置类型比较：CLIENT 仅客户端加载且不同步；COMMON 双端分别加载且不同步；SERVER 仅服务端加载并同步客户端，按世界存放在 serverconfig；配置通过 Builder 定义、构建、注册，Loading 和 Reloading 事件在模组事件总线上处理。

原创说明图，依据 Forge 1.21.x 官方文档绘制。

创建配置

可以使用 IConfigSpec 子类型创建配置。Forge 通过 ForgeConfigSpec 实现，并使用 ForgeConfigSpec$Builder 构建。构建器可通过 Builder#push 创建配置节，并通过 Builder#pop 离开该节。之后可以用两种方法构建配置：

方法	说明
`build`	创建 `ForgeConfigSpec`。
`configure`	创建包含配置值持有类和 `ForgeConfigSpec` 的 pair。

注意：ForgeConfigSpec$Builder#configure 通常与静态代码块及一个构造函数接收 ForgeConfigSpec$Builder 的类一起使用，以附加并持有配置值：

// 在某个配置类中
ExampleConfig(ForgeConfigSpec.Builder builder) {
  // 在 final 字段中定义值
}
// 在可访问构造函数的地方
static {
  Pair<ExampleConfig, ForgeConfigSpec> pair = new ForgeConfigSpec.Builder()
    .configure(ExampleConfig::new);
  // 将 pair 的值存入常量字段
}

每个配置值可提供额外上下文以增加行为，必须在配置值完全构建之前定义：

方法	说明
`comment`	描述配置值的作用；可传入多个字符串形成多行注释。
`translation`	提供配置值名称的翻译键。
`worldRestart`	必须重启世界才能更改配置值。

ConfigValue

可通过任意 #define 方法，使用已定义的上下文构建配置值。所有配置值方法至少接收两项：表示变量名称的路径（以 . 分隔配置节的字符串），以及不存在有效配置时使用的默认值。

ConfigValue 专用方法还接收验证反序列化对象是否有效的验证器，以及表示配置值数据类型的类。

// 对于某个 ForgeConfigSpec$Builder builder
ConfigValue<T> value = builder.comment("Comment")
  .define("config_value_name", defaultValue);

通过 ConfigValue#get 获取值。值还会被缓存，避免多次读取文件。

其他配置值类型

类型	说明与类	方法	额外参数
范围值	必须位于定义的边界内；`Comparable<T>`。	`#defineInRange`	最小值、最大值及数据类型类。
白名单值	必须位于提供的集合中；`T`。	`#defineInList`	允许值的集合。
列表值	条目列表；`List<T>`。	`#defineList`；允许空列表时用 `#defineListAllowEmpty`。	验证反序列化列表元素的验证器。
枚举值	提供集合中的枚举值；`Enum<T>`。	`#defineEnum`	将字符串或整数转换为枚举的 getter，以及允许值的集合。
布尔值	`boolean` 值；`Boolean`。	`#define`	—

注意：FloatValue、DoubleValue、ByteValue、ShortValue、IntValue 和 LongValue 是范围值，分别指定 Float、Double、Byte、Short、Integer 和 Long 类。

注册配置

构建 ForgeConfigSpec 后必须注册，Forge 才能按需加载、跟踪和同步配置。应在模组构造函数中通过 ModLoadingContext#registerConfig 注册，传入表示所属端的类型、ForgeConfigSpec，还可指定文件名。

// 模组构造函数中，假设有 ForgeConfigSpec CONFIG 和 FMLJavaModLoadingContext context
context.registerConfig(Type.COMMON, CONFIG);

类型	加载位置	同步到客户端	客户端位置	服务端位置	默认文件后缀
`CLIENT`	仅客户端	否	`.minecraft/config`	不适用	`-client`
`COMMON`	双端	否	`.minecraft/config`	`<server_folder>/config`	`-common`
`SERVER`	仅服务端	是	`.minecraft/saves/<level_name>/serverconfig`	`<server_folder>/world/serverconfig`	`-server`

提示：Forge 在代码库中记录了配置类型。

配置事件

可通过 ModConfigEvent$Loading 和 ModConfigEvent$Reloading 处理配置加载或重新加载时执行的操作。事件必须注册到模组事件总线。

警告：这些事件会对该模组的所有配置触发，应使用提供的 ModConfig 对象判断正在加载或重新加载的是哪个配置。

原文：Configuration。