插件配置

警告

这些文档是为 SpongeAPI 7 编写的，可能已经过时。如果你觉得你可以帮助更新它们，请提交一个 PR！

在你允许的情况下，配置文件可以让服务器管理员轻松地对插件的部分特性进行控制。 Sponge 通过使用 Configurate 使得对于配置文件的处理变得十分简单。这些页面将会向你解释如何使用 Configurate 激发插件配置文件的最大效能。

小技巧

参见 Configurate 的官方 wiki 以获取更深层次的关于使用其组件的信息。

备注

Sponge 利用一种名为 HOCON 的配置格式。作为 JSON 的一个超集， HOCON 被用作默认的配置文件格式。本文档剩下的部分同样假设你使用HOCON 。参见 HOCON 简介以获取更多关于 HOCON 格式的信息。使用不同的格式的配置系统是相似的，所以如果你使用另一种格式的话，应该不会构成太大的问题。

快速开始

创建一个默认的插件配置

使用 SpongeAPI 的插件都可以使用一个或者多个配置文件。配置文件允许插件去储存一些数据使得服务器管理员可以自定义它们（如果适用）。

获取你的默认插件配置

SpongeAPI 提供的 DefaultConfig 注解可以用于一个字段（Field）或者一个 Setter 上以接收一个 Path 作为你插件文件的默认路径。

你可以通过在某个 ConfigurationLoader<CommentedConfigurationNode> 的字段上加 @DefaultConfig 注解的方式来存取默认配置文件。要注意的是，ConfigurationLoader 不会加载你的 jar 自带的默认配置，除非你明确要求加载。

@DefaultConfig 这一注解需要指定一个名为 sharedRoot 的布尔值。如果你设置其为 true ，那么它返回的路径将对应一个位于共享的文件夹中的名为 your_plugin_id.conf 的文件（这里的“your_plugin_id”被替换成了你的插件 ID）。

小技巧

参见插件的主类以获取设置你的插件 ID 的更多信息。

如果你设置 sharedRoot 为 false ，那么返回的路径将会指向名为 {pluginname}.conf 的文件，该文件位于名称为你的插件 Id 的文件夹内。

如果你不大确定应该把 sharedRoot 设置成什么，考虑以下方面：

如果你计划将来有多个配置文件（复杂的插件），将值设置为 false 。
如果你计划将来只有一个配置文件（不太复杂的插件），设置为 true 。

你了可以获取到一个指向配置文件夹的 Path 而不是单独的文件。只要把它对应的字段和方法使用 ConfigDir 注解，不管 sharedRoot 是真还是假，都将返回一个文件夹，真为插件的特定文件夹，假为共享的文件夹。

备注

尽管获取到一个 File 而不是 Path 是可行的，Configurate （和 Sponge）都十分建议使用 Path 。

示例——在字段中使用 @DefaultConfig

import java.nio.file.Path;
import com.google.inject.Inject;
import org.spongepowered.api.config.ConfigDir;
import org.spongepowered.api.config.DefaultConfig;
import org.spongepowered.configurate.CommentedConfigurationNode;
import org.spongepowered.configurate.loader.ConfigurationLoader;

@Inject
@DefaultConfig(sharedRoot = true)
private Path defaultConfig;

@Inject
@DefaultConfig(sharedRoot = true)
private ConfigurationLoader<CommentedConfigurationNode> configManager;

@Inject
@ConfigDir(sharedRoot = false)
private Path privateConfigDir;

警告

当你的插件第一次支持的时候，返回的配置文件或者目录的路径和名称可能尚未存在。如果你想要把读写配置的托管权交给 Configurate 的话，你其实可以丝毫不用关心这件事，因为 Configurate 库就会帮你做好一切。

备注

YAML 格式（https://yaml.org/spec/1.1/）和 JSON 格式（https://www.json.org/）其实也都是支持的，不过 Sponge 插件的首选还是 HOCON 。可以通过 YAMLConfigurationLoader 或 GsonConfigurationLoader 把 YAML/JSON 加载旧的配置格式，并通过 HoconConfigurationLoader 保存为 HOCON。