設定插件

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

小訣竅

請參閱 Configurate 官方 wiki 以獲取更深入關於使用其組件的資訊。

備註

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

快速入門

建立一個預設的插件設定

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

取得你的預設插件設定

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

@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 ninja.leaping.configurate.commented.CommentedConfigurationNode;
import ninja.leaping.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/)也是被支援的,但 Sponge 插件設定檔格式的首選是 HOCON。可以透過使用 YAMLConfigurationLoader 讀取舊設定檔,並使用 HoconConfigurationLoader 將它們儲存,來將 YAML 自動轉換為 HOCON。