Plugins konfigurieren

Warnung

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!

Konfigurationsdateien ermöglichen es den Plugins Daten zu speichern und erlauben es den Administratoren einzelne Teile eines Plugins zu verändern (in sofern es das zulässt). Sponge benutzt Configurate, um einen schnellen Zugriff auf die Konfigurationsdateien anbieten zu können. Die folgenden Artikel werden erklären, wie Configurate benutzt werden muss, um Konfigurationsdateien in ihrem gesamten Umfang nutzen zu können.

Tipp

See the official Configurate wiki to gain more in-depth information about working with its components.

Bemerkung

Sponge makes use of the HOCON configuration format, a superset of JSON, as the default format for saving configuration files. The rest of this guide will assume you are using HOCON as well. See Einführung in HOCON more for information regarding the HOCON format. Working with different formats is made relatively similar by the Configurate system, so it should not pose too much of an issue if you use an alternate format instead.

• ConfigurationLoader
• Nodes konfigurieren
• Serialisieren von Objekten

Schnellstart

Erstellen der Standard-Plugin-Konfiguration

Für Plugins, die Gebrauch von der SpongeAPI machen, besteht die Möglichkeit mehrere Konfigurationsdateien zu nutzen. Diese Dateien erlauben es Plugins Daten zu speichern und Serveradministratoren ihre Plugins entsprechend zu konfigurieren (falls zutreffend).

Erstellen der Standard-Plugin-Konfiguration

Die SpongeAPI erlaubt das Verwenden der DefaultConfig Anmerkung vor einer Variable oder einer Methode mit dem Typ File, um die Standardkonfigurationsdatei für dein Plugin zu finden.

If you place the @DefaultConfig annotation on a field with the type ConfigurationLoader<CommentedConfigurationNode> 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.

Die @DefaultConfig Anmerkung benötigt eine boolsche sharedRoot Variable. Wenn sharedRoot auf true gesetzt wird, so liegt der ausgegebene Pfad in einem speziellen Ordner für (Plugin-) Konfigurationen. In diesem Fall wird deine Konfigurationsdatei Deine_Plugin_ID.conf heissen (mit „Deine_Plugin_ID“ für die von dir vergebene, einmalige ID deines Plugins).

Tipp

Unter Hauptklasse des Plugins sind Informationen verfügbar, wie die Plugin-ID geändert werden kann.

Wenn sharedRoot auf false gesetzt wird, so wird der zurückgegebene Pfad auf eine Datei {pluginname}.conf im Ordner deines Plugins verweisen.

Wenn du nicht sicher bist auf welchen Wert sharedRoot gesetzt werden sollte, überlege dir folgendes:

• Wenn in Zukunft mehrere Konfigurationsdateien genutzt werden sollen (komplexe Plugins), so setze den Wert auf false.

• Wenn nur eine Konfigurationsdatei zum Einsatz kommen soll (bei nicht so komplexen Plugins), setze den Wert auf true.

Du kannst außerdem eine Path Instanz verwenden, die auf dein Konfigurationsverzeichnis zeigt, statt einer speziellen Datei. Du kannst dies durch die ConfigDir Annotation automatisch einfügen lassen. Entweder mit sharedRoot auf false gesetzt, wenn du ein Plugin spezifischen Ordner verwenden möchtest, oder auf true, wenn du das geteilte Konfigurationsverzeichnis verwenden möchtest.

Bemerkung

Während es möglich ist, eine File statt einem Pfad zu verwenden, empfiehlt Configurate (und Sponge) die Verwendung von Path.

Ein Beispiel, welches @DefaultConfig ** nutzt:**

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;

Warnung

When your plugin is running for the first time, returned pathnames for configuration files and directories may not yet exist. If you delegate all reading / writing of files to Configurate, you do not need to worry about non-existent paths as the library will handle them appropriately.

Bemerkung

The use of YAML format (https://yaml.org/spec/1.1/) and JSON format (https://www.json.org/) is also supported, but the preferred config format for Sponge plugins is HOCON. Conversion from YAML (or JSON) to HOCON can be automated by using a YAMLConfigurationLoader (or GsonConfigurationLoader) to load the old config and then saving it using a HoconConfigurationLoader.