Konfiguracja Pluginów

Ostrzeżenie

Ta dokumentacja została napisana dla SpongeAPI 7 i możliwe, że jest już przestarzała. Jeśli masz ochotę wspomóc w jej aktualizacji, prosimy, utwórz PR!

Pliki konfiguracyjne umożliwiają wtyczkom przechowywanie danych oraz pozwalają administratorom serwerów bez problemu przejąć kontrolę nad określonymi elementami wtyczki, jeśli zdecydujesz się na to zezwolić. Sponge używa konfiguracji, aby umożliwić łatwą manipulację plikami konfiguracyjnymi. Strony te wyjaśnią ci jak korzystać z konfiguracji, aby móc w pełni wykorzystać pliki konfiguracyjne.

Wskazówka

Spójrz na oficjalne wiki Configurate aby uzyskać bardziej dogłębne informacje jak pracować z jej komponentami.

Informacja

Sponge używa formatu HOCON, nadzbioru formatu JSON, jako domyślny format zapisywania plików konfiguracyjnych. Pozostała część tego poradnika zakłada że również używasz formatu HOCON. Zobacz Wprowadzenie do HOCON po więcej informacji związanych z formatem HOCON. Praca z innymi formatami jest stosunkowo podobna, więc jeśli używasz innego formatu, nie powinno to sprawiać większych problemów.

• Configuration Loaders
• Configuration Nodes
• Serializacja Obiektów

Szybki Start

Tworzenie domyślnej konfiguracji pluginu

Pluginy używające SpongeAPI mogą używać jednego lub kilku plików konfiguracyjnych. Pliki konfiguracyjne pozwalają pluginom przechowywać dane jak również pozwalają administratorom serwera dostosowywać opcje pluginu (jeśli takowe istnieją).

Otrzymanie domyślnej konfiguracji pluginu

SpongeAPI oferuje adnotację DefaultConfig którą można użyć na polu lub metodzie z typem Path aby uzyskać domyślny plik konfiguracyjny dla swojego pluginu.

Jeśli umieścisz adnotację @DefaultConfig na polu o typie ConfigurationLoader<CommentedConfigurationNode> to będziesz mógł użyć go do wczytywania i zapisywania domyślnego pliku konfiguracyjnego na dysku. Pamiętaj że ConfigurationLoader mający przy sobie adnotację nie używa żadnego domyślnego pliku konfiguracyjnego, którego możesz mieć w swoim jar’rze, chyba że jawnie go załadujesz.

Adnotacja @DefaultConfig wymaga parametru boolean sharedRoot. Jeśli ustawisz sharedRoot na true, zwrócona nazwa ścieżki będzie wskazywać na współdzielony katalog konfiugracyjny. W takim przypadku plik konfiguracyjny dla twojego pluginu będzie nazywał się your_plugin_id.conf (gdzie „your_plugin_id” zastąpiony będzie identyfikatorem Twojego pluginu).

Wskazówka

Zobacz Główna Klasa Pluginu w celu uzyskania informacji dotyczących konfigurowania ID twojego pluginu.

Jeśli ustawisz sharedRoot na false, zwrócona ścieżka będzie odnosić się do pliku o nazwie {pluginname}.conf w odosobnionym katalogu dla twojego pluginu.

Jeśli nie jesteś pewien jaką wartość ustawić dla sharedRoot, weź pod uwagę:

• Jeśli planujesz mieć wiele plików konfiguracyjnych w przyszłości (w przypadku skomplikowanych pluginów), ustaw wartość na false.

• Jeśli planujesz mieć jeden plik konfiguracyjny (w przypadku mniej skomplikowanych pluginów), ustaw wartość na true.

Możesz również uzyskać instancję Path wskazującą na katalog konfiguracyjny zamiast na konkretny plik. Wystarczy że wstrzykniesz ścieżkę używając adnotacji ConfigDir. Parametr sharedRoot ustawiony na false da Ci ścieżkę konkretnego katalogu pluginu a ustawiony na true da Ci współdzielony katalog konfiguracyjny.

Informacja

Mimo że możliwym jest otrzymanie obiektu File zamiast Path, Configurate (i Sponge) rekomenduje używanie Path.

Przykład - Użycie na polu @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;

Ostrzeżenie

Gdy twoja wtyczka jest uruchomiona po raz pierwszy, zwrócone nazwy ścieżek dla plików konfiguracyjnych i katalogów mogą jeszcze nie istnieć. Jeśli postanowisz oddelegować cały proces odczytu / zapisu plików konfiguracyjnych do Configurate, nie będziesz wtedy musiał się martwić o nieistniejące ścieżki, gdyż biblioteka odpowiednio je obsłuży.

Informacja

Format YAML (https://yaml.org/spec/1.1/) i format JSON (https://www.json.org/) jest również wspierany, ale preferowanym formatem konfiguracji dla pluginów Sponge jest HOCON. Konwersja z YAML (lub JSON) na HOCON może być zautomatyzowana za pomocą YAMLConfigurationLoader (lub GsonConfigurationLoader) aby załadować starą konfigurację, a następnie zapisać ją za pomocą HoconConfigurationLoader.