Configuring Plugins
Configuration files allow plugins to store data, as well as allow server administrators to easily take control over specific portions of a plugin, if you so choose to let them. Sponge uses Configurate to allow you to easily manipulate configuration files. These pages will explain how to utilize Configurate in order to use configuration files to full advantage.
Tip
See the official Configurate wiki to gain more in-depth information about working with its components.
Notitie
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 Introductie voor 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.
Snelle Start
Creating a Default Plugin Configuration
Plugins using SpongeAPI have the option to use one or more configuration files. Configuration files allow plugins to store data, and they allow server administrators to customize plugin options (if applicable).
Je Standaard Plugin Configuratie Verkrijgen
SpongeAPI offers the use of the DefaultConfig annotation on a field or setter method with the type
Path
to get the default configuration file for your plugin.
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.
De @DefaultConfig
annotatie vereist een sharedRoot
boolean. Als de sharedRoot
op true
gezet wordt, zal het teruggeven pad in een gedeelde configuratie map zijn. In dit geval zal het configuratiebestand van jouw plugin jouw_plugin_id.conf
zijn.
Tip
See Hoofdklasse uw plugin for information on configuring your plugin ID.
If you set sharedRoot
to false
, the returned pathname will refer to a file named {pluginname}.conf
in a
directory specific to your plugin.
Als je onzeker bent over de waarde van sharedRoot
, overweeg dan het volgende:
Als je van plan bent om meerdere configuratiebestanden (complexere plugins) te hebben in de toekomst, zet de waarde dan op
false
.Als je van plan bent om een enkel configuratiebestand (minder complexe plugins) te hebben, zet de waarde dan op
true
.
You can also obtain a Path
instance pointing to the config directory instead of a particular file. Just
have it injected using the ConfigDir annotation, either with sharedRoot
set to false
for a plugin
specific directory or to true
to get the shared configuration directory.
Notitie
While it may be possible to get a File
instead of a Path
, Configurate (and Sponge) recommend using Path
.
Voorbeeld - Veld gebruikt @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;
Waarschuwing
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.
Notitie
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.