Plume Config / 基于 TOML

Plume Config是一个为Minecraft模组制作中的配置文件处理而准备的轻量化Api库，使用了Tom's Obvious Minimal Language（TOML）格式作为文件规范。

部署

可能的版本

build.gradle

repositories {
    maven {
        url = "https://api.modrinth.com/maven"
    }
}
dependencies {
    modApi include("maven.modrinth:plumeconfig:4uCYxiEc")
    modLocalRuntime("org.tomlj:tomlj:1.1.0")
}

具体内容

Plume Config使用了Modrinth Maven代理仓库，要在你的项目中部署Plume Config，请在build.gradle文件中添加以下内容：

一、添加Modrinth Maven仓库

repositories {
    maven {
        url = "https://api.modrinth.com/maven"
    }
}

Modrinth推荐的方式

repositories {
    exclusiveContent {
        forRepository {
            maven {
                name = "Modrinth"
                url = "https://api.modrinth.com/maven"
            }
        }
        filter {
            includeGroup "maven.modrinth"
        }
    }
}

二、部署Plume Config的最新版本

dependencies {
    modApi include("maven.modrinth:plumeconfig:4uCYxiEc")
}

在重新构建你的项目之前，请注意以下几点：

1. 请使用modApi指令部署，且不要将Plume Config作为你的前置模组。

2. 低于v3.2.0的版本已经不再受支持，请尽量使用最新的版本。

3. 请使用版本代码（如4uCYxiEc）而不是版本号（如v3.2.1）从Maven仓库中拉取文件，你可以在Modrinth版本列表中查看版本代码。

4. 因为Gradle的某些问题，仅仅导入Plume Config会让你的模组在开发调试环境崩溃，而可执行文件却可以运行。如要避免类似情况的发生，请在调试环境中单独引入Tomlj依赖：在dependencies中加入语句“modLocalRuntime("org.tomlj:tomlj:1.1.0")”。你可以在可能的版本章节中查看可运行的Gradle代码。

演示

example.toml

# This is a comment
# at the top of the file
# An integer
integer = 1 # Int
# A boolean
bool = false
[abc]
# Multi-line
# comment
s = "string" # String | A String Comment
d = 1.0
[def]
# A color
# Which is under supported
color = 0xff000000

使用

这里有一个示范类：Example.java

当你部署完毕后， 多亏了简明灵活的注解和极少量需要调用的方法，随时上手使用也不是什么难事。

类

首先，定义一个ConfigFile类：

public class MyModInitializer {
    public static final ConfigFile CONFIG = new ConfigFile("my_modid", "my_config.toml"); // 还有其它的构造器可以使用，详见Javadoc
}

然后，设计属于你的配置文件：

public class MyConfig {
    // 继续读...
}

@Option注解

在这个特殊的类里，每当你想定义一个选项，只需使用@Option注解：

@Option // 你可以在字段前注解，或者...
public String s = "string";
private static @Option int integer = 1; // ...把注解写在修饰词后
// 被@Option注解的类无论被public还是private修饰都可以，但不能被protected修饰
// 这个选项同样可以被final修饰，但是不推荐，因为无法从文件读取这类选项的值

s = "string"
integer = 1

每个选项的默认键即是字段的名称，但在文档的剩下内容中，你会知道如何单独更改选项的键。

@Option注解同样可以用来为选项添加额外信息，比如更改选项的键：

@Option(key = "different_key")
public String s = "string";

different_key = "string"

你不可以在同一个文件中使用重复的键。Plume Config不会检查这类行为，但不代表这不会造成混乱。

你可以用同样的方式为选项添加名称和注释：

@Option(name = "字符串", comment = "这是一串字符")
public String s = "string";
@Option(key = "integer", name = "整型")
private static int i = 1;

s = "string" # 字符串 | 这是一串字符
integer = 1 # 整型

对于较特殊的情况，Plume Config也支持多行字符串：

@Option
public String s = "多-\n行\\\n字符串！"

s = """
多-
行\
字符串！"""

@Comment注解

除了@Option注解以外，还有一个注解@Comment可以为字段添加单独成行的注释。

@Comment("一条")
@Comment("两行的注释")
public @Option String s = "字符串";

@Comment(value = "另一条注释", newLine = LineBreak.BEFORE)
private @Option static int i = 12345;

s = "字符串"
# 一条
# 两行的注释
i = 12345

# 另一条注释

@Comment注解仅可用于已被@Option注解的字段。

@Comment注解可以在同一处多次使用，每一条会独占一行。

在@Comment注解中，你可以用LineBreak枚举常量来指定换行行为。

@Comment注解不仅可以用于字段前，还可以用于类的定义：

@Comment("这是一条")
@Comment(value = "在文件顶端的注释", newLine = LineBreak.AFTER)
public class MyConfig {
//...
}

# 这是一条
# 在文件顶端的注释

@Category注解

TOML的特性之一是可分类的点键，你可以在代码中使用@Category注解实现：

public @Option String uncat="未分类";

@Comment("分类注释")
@Category("abc")
public @Option String cat="分类";

uncat = "未分类"

[abc]
cat = "分类"
# 分类注释

字段的顺序并不重要，Plume Config会帮助分类。

这就是注解系统的工作原理。让我们实际操作一下：

import java.awt.*;

@Comment("这个配置文件控制玩家在游戏中的各项行为", newLine = LineBreak.AFTER)
public class MyConfig {
@Option(key = "player_name", name = "玩家名", comment = "在游戏内显示")
public String playerName = "西格玛";

@Option(comment = "生命条长度")
public double health = 1.0;

@Comment("非调试环境请不要更改此选项")
@Category("misc")
@Option(comment = "唯一身份标识")
public int identity = Color.BLACK;

@Option(key = "streaming_switch", comment = "开关串流模式")
public boolean streamingSwitch = false;
}

记得在模组启动时加载这个配置实例：

public class MyModInitializer implements ModInitializer {
    public static final ConfigFile CONFIG = new ConfigFile("my_modid", "my_config.toml");
    public static final MyConfig CONFIG_INSTANCE = new MyConfig();
    
    @Override
    public void onInitialize() {
        // 不要担心文件不存在，Plume Config会创建这些文件
        CONFIG_INSTANCE = CONFIG.load(MyConfig.class); // 填入你的配置类，告诉Plume Config要加载什么
    }
}

现在启动模组，你的配置文件（run/config/my_modid/my_config.toml）看上去应该是这个样子的：

# 这个配置文件控制玩家在游戏中的各项行为

player_name = "西格玛" # 玩家名 | 在游戏内显示
health = 1.0 # 生命条长度
streaming_switch = false # 开关串流模式

[misc]
identity = 0xff000000 # 唯一身份标识
# 非调试环境请不要更改此选项

在你的代码中，记得保证每次启动时都会加载一遍配置文件。

现在，你已经可以正常访问其中的字段了：

public class MyModInitializer implements ModInitializer {
    public static final ConfigFile CONFIG = new ConfigFile("my_modid", "my_config.toml");
    public static final MyConfig CONFIG_INSTANCE = new MyConfig();
    @Override
    public void onInitialize() {
        CONFIG_INSTANCE = CONFIG.load(MyConfig.class);
        
        // 你可以正常使用它们
        System.out.println(CONFIG_INSTANCE.playerName);
        System.out.println(CONFIG_INSTANCE.health);
        System.out.println(CONFIG_INSTANCE.identity);
        System.out.println(CONFIG_INSTANCE.streaming_switch);
        
        CONFIG_INSTANCE.playerName = "兰布达";
        CONFIG_INSTANCE.color = Color.RED;
        
        // 别忘了保存你更改过的字段！
        CONFIG.save(CONFIG_INSTANCE); // 填入你更改过的配置实例。
    }
}

挺酷的吧！Plume Config还不支持TOML的全部特性，但我们一直在努力开发。如果你关心开发进度，可以关注Plume Config的GitHub开源仓库。

协议

Plume Config在GPL协议下授权可用。