設定插件

警告

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

在你允許的情況下,設定檔使插件能夠儲存資料,也使伺服器管理員能夠輕易控制插件的特定部分。Sponge 使用 Configurate 來讓你能夠輕易操作設定檔。這些頁面將解釋如何利用 Configurate 來充分利用設定檔。

小訣竅

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

備註

Sponge 利用一種名為 HOCON 的設定格式,一個 JSON 的超集,作為儲存設定檔的預設格式。本指南的剩餘部分將假設你也使用 HOCON 。參閱 HOCON 介紹 以獲取更多關於 HOCON 格式的資訊。透過設定系統使用不同格式的設定檔是相似的。因此若你使用另一種格式來代替,應該不會構成太多問題。

快速入門

建立一個預設的插件設定

使用 SpongeAPI 的插件可以選擇使用一個或多個設定檔。設定檔讓插件能夠儲存資料,也讓伺服器管理員能夠自定義插件選項(如果適用)。

取得你的預設插件設定

SpongeAPI 提供的 DefaultConfig Annotation 可用於一個欄位(Field)或 Setter 方法,搭配 Path 類別來取得你插件的預設設定檔。

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

@DefaultConfig 這個 Annotation 需要一個布林值 sharedRoot。若你將 sharedRoot 設為 true,那麼它回傳的路徑將位於一個共享的設定資料夾,在這情況下,你的插件的設定檔名稱將為 your_plugin_id.conf(其中「your_plugin_id」將被取代為你的插件所指定的 ID)。

小訣竅

參閱 主要插件類別 以獲取設定你的插件 ID 的更多資訊。

若你將 sharedRoot 設為 false,那麼回傳的路徑將會是在你插件的資料夾中名為 {pluginname}.conf 的檔案。

如果你不確定該將 sharedRoot 設為什麼,請考慮以下幾項:

  • 如果你打算擁有多個設定檔(複雜的插件),將其值設定為 false

  • 如果你打算只擁有一個設定檔(不太複雜的插件),將其值設定為 true

你也可以取得一個指向設定資料夾而非特定檔案的 Path 實例,只要使用 ConfigDir Annotation 注入即可。將 sharedRoot 設為 false 時,會是插件資料夾;設為 true 時,會是共享的設定資料夾。

備註

儘管可能取得一個 File 而非 Path,Configurate(與 Sponge)建議使用 Path

範例——在欄位(Field)使用 @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,那你不必擔心不存在的路徑,函式庫會適當的處理這些情況。

備註

YAML 格式(http://yaml.org/spec/1.1/)與 JSON 格式(https://www.json.org/)也被支援,但 Sponge 插件設定檔格式的首選是 HOCON。可以透過使用 YAMLConfigurationLoader(或 GsonConfigurationLoader) 讀取舊設定檔,並使用 HoconConfigurationLoader 將它們儲存,來將 YAML(或 JSON)自動轉換為 HOCON。