注解详解

Tritium Configuration 通过注解来声明配置结构、范围与平台属性。本节逐一说明。

@SubCategory

• 目标：FIELD，保留策略：RUNTIME
• 作用：将一个对象字段视为“子分类”（可递归嵌套）
• 属性：
  • String value()：显示名称（用于文档/示例；实际 UI 文本来自本地化）
  • String tooltip() default ""：可选提示（UI 可本地化覆盖）

示例：

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

  public static class General {
    public boolean enabled = true;
  }
}

注意：

• 顶层的每个字段通常对应一个“分类”（category）
• 子分类可多层嵌套，最终展开为具体条目

@ClientOnly

• 目标：FIELD/TYPE，保留策略：RUNTIME
• 作用：标记客户端专属配置（在服务端环境不会生成/读取这些项）

示例：

@ClientOnly
public static class ClientOnlySection {
  public boolean showHud = true;
}

@Range

• 目标：FIELD，保留策略：RUNTIME
• 作用：用于数值型字段（int/long/double）的范围约束
• 属性：
  • double min() default Double.MIN_VALUE
  • double max() default Double.MAX_VALUE
  • String message() default "Value must be between {min} and {max}"

行为：

• 运行时装载时若发现超出范围，会记录警告并回退到默认值
• UI 数值输入会自动应用 min/max 限制

示例：

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

@Validation

• 目标：FIELD，保留策略：RUNTIME
• 作用：字符串字段的额外格式校验
• 规则：
  • minLength:n 最小长度
  • maxLength:n 最大长度
  • regex:pattern 正则匹配

示例：

@Validation("regex:^[a-z0-9_]+$")
public String profile = "default";

@ConfigVersion

• 目标：TYPE，保留策略：RUNTIME
• 作用：声明当前配置版本，驱动迁移逻辑
• 属性：
  • int value() 当前版本号（从 1 起）
  • String migration() default ""（保留备用）

示例：

@ConfigVersion(3)
public class MyConfig { /* ... */ }

配套的迁移写法见“迁移与校验”。