CraftAmethyst Docs

Appearance

API 索引（中文） ​

本文列出 Tritium Configuration 主要 API 与注解，便于查阅。

核心类 ​

TritiumConfig ​

  • static TritiumConfig register(String modId, Class<?> configClass)
    • 注册配置并完成默认校验、文件创建、文件监视。
  • static TritiumConfig getConfig(String modId)
    • 获取已注册的配置句柄。
  • static Map<String, TritiumConfig> getAllConfigs()
    • 获取所有已注册配置的快照。
  • <T> T get()
    • 返回当前配置对象实例（若字段为实例字段，可通过它读取）。
  • void reload()
    • 从磁盘重新加载并应用到内存（会重新校验）。
  • void save()
    • 将当前内存配置写回磁盘（生成注释与分组）。
  • TritiumConfig filename(String name)
    • 自定义文件名（不带扩展名），默认 modId + "_config"。
  • boolean isClientEnvironment() | String getModId() | Class<?> getConfigClass()

说明与限制：

  • 支持类型：boolean/int/long/double/String/enum/List<String>。
  • 非支持类型会记录警告并回退默认值。
  • 客户端专属字段/分组在服务端环境会被忽略。

TritiumAutoConfig（自动 UI） ​

  • 构造：new TritiumAutoConfig(TritiumConfig config)
  • Screen createConfigScreen(Screen parent)
    • 构建 Cloth Config v15 配置界面。
    • 文本键：
      • 标题：config.&lt;modid&gt;.title
      • 分类：config.&lt;modid&gt;.category.&lt;section&gt;
      • 条目：config.&lt;modid&gt;.&lt;section&gt;.&lt;path&gt; 与 ... .tooltip

字段到控件的映射：

  • boolean → 开关
  • int/long/double → 数值输入（支持 @Range）
  • String → 文本输入
  • enum → 枚举下拉
  • List<String> → 字符串列表编辑

辅助类（通常无需直接使用） ​

ConfigParser ​

  • 负责解析 toml 风格文件到键值映射，提供：
    • Supplier<Boolean> getBoolean(String key, boolean def)
    • Supplier<Integer> getInt(String key, int def)
    • Supplier<Long> getLong(String key, long def)
    • Supplier<Double> getDouble(String key, double def)
    • Supplier<String> getString(String key, String def)
    • Supplier<Enum> getEnum(String key, Enum def)
    • Supplier<List<String>> getStringList(String key, List<String> def)

ConfigValue<T> ​

  • 包装 Supplier<T> 的带缓存值对象：
    • 构造：new ConfigValue<>(supplier)（默认 3000ms 缓存）
    • T get()：返回缓存值（过期自动刷新）
    • void refresh()：强制刷新缓存
    • T getRaw()：直接读取底层 Supplier
    • long getCacheAge()：距上次刷新毫秒数

ConfigFileWatcher ​

  • 定时检查配置文件的 lastModified，若变化则触发回调（默认每 2s）。

ConfigValidator ​

  • 遍历配置对象进行：
    • @Range 数值范围校验
    • @Validation 字符串规则校验（minLength:n、maxLength:n、regex:pattern）
    • 递归校验嵌套分组
    • 调用配置类的 public void validateConfig()（若存在）

ConfigMigration ​

  • 依据 @ConfigVersion(n) 与文件中的 config_version 执行多步迁移。
  • 自定义迁移：在配置类中声明静态方法 public static void migrateFromV{n}(Map<String,String> values)。
    • 方法中可按键名移动/改名/转换值。
  • 默认示例迁移（库内置）：
    • v1→v2：rendering.enableCulling → rendering.entityCulling.enableCulling 等
    • v2→v3：old.setting → new.setting

注解参考 ​

@SubCategory ​

  • 目标：FIELD，保留策略：RUNTIME
  • 属性：
    • String value()：显示名称
    • String tooltip() default ""：可选提示
  • 作用：将对象字段视为子分类，递归展开其内部字段。

@ClientOnly ​

  • 目标：FIELD/TYPE，保留策略：RUNTIME
  • 作用：仅在客户端读取/生成，服务端忽略。

@Range ​

  • 目标：FIELD，保留策略：RUNTIME
  • 属性：double min(), double max(), String message()
  • 作用：限制数值型字段取值范围。

@Validation ​

  • 目标：FIELD，保留策略：RUNTIME
  • 属性：String value()（规则：minLength:n、maxLength:n、regex:pattern）
  • 作用：字符串字段的额外格式校验。

@ConfigVersion ​

  • 目标：TYPE，保留策略：RUNTIME
  • 属性：int value()、String migration() default ""
  • 作用：声明当前配置版本，用于迁移流程。

约定与最佳实践 ​

  • 建议将“功能模块”作为顶层 Section，将细分设置放在子分类；避免过深层级。
  • 对外使用 static 字段最直观；若需多个配置实例，可改为实例字段并通过 get() 获取实例。
  • 变更键名时请提供迁移方法并提升 @ConfigVersion，以保证旧配置平滑升级。
  • 为 UI 提供完善的本地化与 tooltip，提升可用性。