插件配置

配置文件允许用户更改插件的某些行为和功能。本指南将概述如何使用它们。

格式

默认情况下，插件使用 YAML 配置格式（.yml 文件）。其他格式，如 JSON 或 TOML，也可以使用；但是，这些不是 Paper 原生支持的，所以本指南不会涉及这些内容。

YAML 通过树状的 key: value 键值对结构工作，就像你在 plugin.yml 中看到的那样。一个例子看起来像这样：

root:
  one-key: 10
  another-key: David

当访问缩进的值时，你用点（.）分隔各个层级。例如，David 字符串的键是 root.another-key。

创建 `config.yml`

通过在你的插件中放置一个 config.yml 文件，你可以为某些设置指定默认值。这将位于 resources 目录中：

example-plugin
└── src
    └── main
        ├── java
        └── resources
            ├── config.yml
            └── plugin.yml

当你的插件初始化时，你必须将此资源保存到插件的数据目录中，这样用户就可以编辑这些值。下面是你在插件的 onEnable 中如何做到这一点的示例：

TestPlugin.java
public class TestPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        saveResource("config.yml", /* replace */ false);

        // 你也可以使用这个来处理配置文件：
        saveDefaultConfig();
        // 如果默认的 config.yml 不存在，它将被保存

        // getConfig()...
    }
}

信息

布尔参数 replace 指定如果文件已经存在，是否应该替换它。如果设置为 true，配置将在每次调用时被覆盖。

获取和设置数据

一旦配置文件被保存，可以通过 JavaPlugin#getConfig() 获取插件的 FileConfiguration。这将允许通过相应的 #get...(key) 和 #set(key, value) 来获取和设置数据。默认情况下，YAML 支持大多数基本数据类型。这些可以通过 #getString(key) 或 #getBoolean(key) 简单地获取。

然而，一些更复杂的 Bukkit 数据类型也受支持。其中包括 ItemStack、 Location 和 Vector。这里是一个从配置中加载值以传送玩家的示例：

保存配置

每当在配置中设置数据时，你必须调用 FileConfiguration#save(File/String) 才能将更改持久化到磁盘。

TestPlugin.java
public class TestPlugin extends JavaPlugin {

    public void teleportPlayer(Player player) {
        Location to = getConfig().getLocation("target_location");
        player.teleport(to);
    }
}

这是可能的，因为它们实现了 ConfigurationSerializable。你可以通过实现和注册自定义类来自己使用这个。

TeleportOptions.java
public class TeleportOptions implements ConfigurationSerializable {

    private int chunkX;
    private int chunkZ;
    private String name;

    public TeleportOptions(int chunkX, int chunkZ, String name) {
        // 设置值
    }

    public Map<String, Object> serialize() {
        Map<String, Object> data = new HashMap<>();

        data.put("chunk-x", this.chunkX);
        data.put("chunk-z", this.chunkZ);
        data.put("name", this.name);

        return data;
    }

    public static TeleportOptions deserialize(Map<String, Object> args) {
        return new TeleportOptions(
                (int) args.get("chunk-x"),
                (int) args.get("chunk-z"),
                (String) args.get("name")
        );
    }
}

这里我们可以看到，我们有一个基于实例的 serialize 方法，它返回一个映射，然后有一个静态的 deserialize 方法，它接受一个 Map 作为参数并返回一个 TeleportOptions 类的实例。最后，为了让这个工作，我们必须调用： ConfigurationSerialization.registerClass(TeleportOptions.class)

注意

如果你不对 Paper 插件调用 ConfigurationSerialization#registerClass(Class)，你将无法加载或保存你的自定义类。

自定义配置文件

你的插件很可能有许多不同的东西需要配置。如果你选择将这些分散到多个不同的文件中，你仍然可以使用 Bukkit FileConfiguration API 来读取这些数据。这很简单：

File file = new File(plugin.getDataFolder(), "items.yml");
YamlConfiguration config = YamlConfiguration.loadConfiguration(file);
// 在这里处理配置
config.save(file);

这个例子从你的插件的数据目录读取 items.yml 文件。这个文件必须存在，否则会抛出错误。

阻塞 I/O

在主线程上加载和保存文件会降低服务器速度。load 和 save 操作应该异步执行。

Configurate

Configurate 是一个由 Sponge 项目维护的用于处理配置的第三方库。该项目被 Paper 内部用于其配置，并提供了许多 FileConfiguration API 没有的功能。更多信息请参见他们的项目这里。

格式​

创建 config.yml​

获取和设置数据​

自定义配置文件​

Configurate​

格式

创建 `config.yml`

获取和设置数据

自定义配置文件

Configurate