設定插件

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

小訣竅

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

備註

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

快速入門

建立一個預設的插件設定

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

取得你的預設插件設定

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

If you place the @DefaultConfig annotation on a field with the type ConfigurationLoader then you can use it to load and save the default config file in the file system. Please keep in mind that the annotated ConfigurationLoader does not use any default config file that you might ship with your jar, unless you explicitly load it.

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

小訣竅

參閱 主要的插件 Class 以獲取設定你的插件 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/)與 JSON 格式(https://www.json.org/)也是被支援的,但 Sponge 插件設定檔格式的首選是 HOCON。可以透過使用 YAMLConfigurationLoader(或 GsonConfigurationLoader) 讀取舊設定檔,並使用 HoconConfigurationLoader 將它們儲存,來將 YAML(或 JSON)自動轉換為 HOCON。