CraftAmethyst Docs

Appearance

迁移与校验 ​

当配置结构变化时，你可以通过“版本 + 迁移”保证旧配置平滑升级，并在运行时进行严格校验。

版本声明 ​

在配置类上声明当前版本：

java
@ConfigVersion(3)
public class MyConfig { /* ... */ }
  • 若文件未包含 config_version，会被视为 1
  • 当库检测到文件版本 < 类版本时，将按步迁移（1→2→3...）

自定义迁移 ​

在配置类中为“旧版本号”编写静态方法：

java
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 static void migrateFromV{N}(Map<String,String> values)
  • 该方法应只依赖 values 中的键值对（全部是字符串），自行负责转换与校验
  • 迁移结束后库会写入 config_version = <新版本> 并重写文件（注意：写成扁平键值清单）

默认内置迁移示例（库内）：

  • v1→v2：rendering.enableCulling → rendering.entityCulling.enableCulling 等
  • v2→v3：old.setting → new.setting

校验 ​

装载与重载时会执行：

  1. 注解校验
  • @Range：数值范围越界将回退默认值并记录警告；在 ConfigValidator 中也会抛错
  • @Validation：对字符串进行最小/最大长度与正则校验
  1. 自定义整体校验
  • 若配置类包含 public void validateConfig()，将被调用以执行更复杂的逻辑

实操建议 ​

  • 变更键名/层级时总是提升 @ConfigVersion 并提供对应 migrateFromV{n} 方法
  • 迁移后若希望恢复分节/注释友好的格式，调用一次 save()（例如从 UI 点“保存”）
  • 迁移逻辑尽量“幂等”，多次执行不会造成重复转换