CraftAmethyst Docs

Appearance

Tritium Configuration 概览 ​

Tritium Configuration 是一个跨平台（Fabric/Forge/NeoForge/Quilt）的通用配置系统，用于为你的模组提供：

  • 简单声明式的配置类 + 注解（分组/范围/校验/客户端专属）
  • 自动生成可本地化的配置界面（基于 Cloth Config v15）
  • TOML 风格的扁平化配置文件，支持热重载
  • 配置版本化与迁移、运行时校验

支持的数据类型：boolean、int、long、double、String、枚举、List<String>。

快速开始 ​

1) 定义配置类 ​

用注解描述结构与约束（可用 static 或实例字段，以下示例使用 static 字段）：

java
package your.mod;

import me.zcraft.tc.annotation.*;

@ConfigVersion(1)
public class MyConfig {
  @SubCategory("通用")
  public static General general = new General();

  @ClientOnly
  @SubCategory("客户端")
  public static Client client = new Client();

  public static class General {
    public boolean enabled = true;

    @Range(min = 1, max = 256)
    public int maxEntities = 64;

    public Mode mode = Mode.SIMPLE;
    public enum Mode { SIMPLE, VANILLA }
  }

  @ClientOnly
  public static class Client {
    public java.util.List<String> whitelist = java.util.Arrays.asList("minecraft:player", "minecraft:villager");
  }

  // 可选：自定义整体校验
  public void validateConfig() {
    if (!general.enabled && general.maxEntities > 0) {
      throw new IllegalArgumentException("当禁用时，maxEntities 必须为 0");
    }
  }
}

2) 注册配置 ​

在模组初始化时注册（建议在主入口早期）：

java
import me.zcraft.tc.config.TritiumConfig;

public class YourModInit {
  public static final String MOD_ID = "your_mod";

  public static final TritiumConfig CONFIG = TritiumConfig
      .register(MOD_ID, MyConfig.class)
      .filename("my_config"); // 可选：修改文件名（默认 your_mod_config）

  public static void onInitialize() {
    // 其他初始化逻辑
  }
}

3) 在代码中读取配置 ​

由于示例使用了 static 字段，直接引用即可（实例字段则可通过 TritiumConfig.getConfig(MOD_ID).get() 获取实例）：

java
boolean enabled = MyConfig.general.enabled;
int max = MyConfig.general.maxEntities;
java.util.List<String> whitelist = MyConfig.client.whitelist;

4) 打开配置界面（可选） ​

使用自动 UI 构建器生成 Cloth Config 界面：

java
import me.zcraft.tc.config.TritiumAutoConfig;
import net.minecraft.client.gui.screens.Screen;

Screen screen = new TritiumAutoConfig(CONFIG).createConfigScreen(parent);

界面所有标题/条目均支持本地化（见下文“国际化键名约定”）。

5) 配置文件位置与格式 ​

默认路径：config/<modId>/<filename>.toml（例如 config/your_mod/my_config.toml）。

文件为“节 + 键值”形式，字符串需要带引号，列表用 [...]，示例：

toml
# your_mod Configuration
# Generated by TritiumConfig
# Environment: client
# Client-only sections will not be generated on server side

[general]
## Enabled
enabled = true

## Max Entities
maxEntities = 64

## Mode
mode = "SIMPLE"

#-------------------------
# 客户端
#-------------------------

## whitelist
whitelist = ["minecraft:player", "minecraft:villager"]

修改此文件会被自动检测并热重载，无需重启游戏。

注解与国际化 ​

  • @SubCategory("显示名称")：将字段分组为子分类，可多级嵌套；可选 tooltip。
  • @ClientOnly：客户端专属（在服务端不会生成/读取这些项）。
  • @Range(min, max)：用于 int/long/double 的范围约束（超出会记录警告并回退默认值）。
  • @Validation("规则")：字符串校验，支持 minLength:n、maxLength:n、regex:pattern。
  • @ConfigVersion(n)：声明配置版本，用于迁移（见下节）。

国际化键名约定（用于自动 UI 与提示文本）：

  • 标题：config.<modid>.title
  • 分类：config.<modid>.category.<section>（如 general）
  • 条目：config.<modid>.<section>.<path> 与 ... .tooltip
    • 顶层条目一般为 config.<modid>.<section>.<field>
    • 子分类条目为 config.<modid>.<section>.<sub.path>（点分路径）

配置版本迁移与校验 ​

当配置结构变化时，先提高 @ConfigVersion 的值，然后按版本号添加静态迁移方法：

java
// 从 v1 迁移
public static void migrateFromV1(java.util.Map<String, String> values) {
  String oldKey = "general.oldSetting";
  String newKey = "general.newSetting";
  if (values.containsKey(oldKey) && !values.containsKey(newKey)) {
    values.put(newKey, values.remove(oldKey));
  }
}

此外你可以在配置类中声明无参实例方法 public void validateConfig() 来做更复杂的整体校验。

运行时与平台 ​

  • 自动热重载：内部使用 ConfigFileWatcher 轮询文件变化并调用 reload()。
  • UI：TritiumAutoConfig 基于 Cloth Config v15 生成，Fabric/NeoForge 均可使用（平台集成见各自端的工厂类）。
  • 线程安全：保存/重载过程中对内部状态做了同步，请避免在保存瞬间并发写入自定义文件。