Configuration des plugins
Avertissement
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!
Les fichiers de configuration permettent aux plugins de stocker des données, ainsi que de permettre aux administrateurs de serveur de prendre facilement le contrôle sur des parties spécifiques d’un plugin, si vous choisissez de les laisser faire. Sponge utilise Configure pour vous permettre de manipuler facilement les fichiers de configuration. Ces pages vous expliqueront comment utiliser la configuration pour pouvoir utiliser les fichiers de configuration à votre plein avantage.
Astuce
Voir le wiki de Configurate pour obtenir des informations plus détaillées sur l’utilisation de ses composants.
Note
Sponge se sert du format de configuration HOCON, un sur-ensemble de JSON, comme format par défaut pour des fichiers de configuration sauvegardés. Le reste de ce guide suppose que vous savez déjà utiliser HOCON. Voir la page Introduction à HOCON pour plus d’informations concernant le format HOCON. La manière de travailler avec différents formats ressemble à la manière de travailler avec un système de configuration, vous ne devriez donc pas faire face à beaucoup de problèmes si vous utilisez un autre format à la place.
Démarrage rapide
Créer une Configuration de Base pour votre Plugin
Les plugins utilisant SpongeAPI ont la possibilité d’utiliser un ou plusieurs fichiers de configuration. Les fichiers de configuration permettent aux plugins stocker des données, et permettent aux administrateurs du serveur de personnaliser les options du plugin (si possible).
Votre Première Configuration par Défaut
SpongeAPI offre l’utilisation de l’annotation DefaultConfig sur une méthode ou un champ avec le type Path pour obtenir le fichier de configuration par défaut de votre plugin.
Si vous placez l’annotation @DefaultConfig sur un champ avec le type ConfigurationLoader<CommentedConfigurationNode>, alors vous pouvez l’utiliser pour charger et sauvegarder le fichier de configuration par défaut dans le système de fichiers. Merci de garder à l’esprit que le ConfigurationLoader annoté n’utilise pas un quelconque fichier de configuration par défaut que vous auriez pu mettre dans votre jar, à moins que vous ne le chargiez explicitement.
L’annotation @DefaultConfig exige un booléen sharedRoot. Si vous définissez sharedRoot sur true, le chemin d’accès retourné sera dans un répertoire de configuration partagé. Dans ce cas, le fichier de configuration pour votre plugin sera your_plugin_id.conf, où « your_plugin_id » est remplacé par l’ID de votre plugin.
Astuce
Voir Classe Principale du Plugin pour les informations sur la configuration de votre ID de plugin.
Si vous définissez sharedRoot sur false, le chemin d’accès retourné fera référence à un fichier nommé {pluginname}.conf dans un répertoire spécifique à votre plugin.
Si vous n’êtes pas sûr de ce qu’il faut définir pour la valeur de sharedRoot, jetez un œil à cela:
Si vous prévoyez d’avoir plusieurs fichiers de configuration (plugin complexe), vous devrez mettre la valeur sur
false.Si vous envisagez d’avoir un seul fichier de configuration (plugin moins complexe), vous devrez mettre la valeur sur
true.
Vous pouvez également obtenir une instance de Path pointant sur le répertoire de config au lieu d’un fichier particulier. Juste l’avoir injecté à l’aide de l’annotation ConfigDir, soit avec sharedRoot définit sur false pour un répertoire spécifique de plugin, ou sur true pour obtenir le répertoire de configuration partagé.
Note
Bien qu’il soit possible de récupérer un File au lieu d’un Path, Configurate (et Sponge) recommandent d’utiliser Path.
Exemple - Field utilisant @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;
Avertissement
Lorsque votre plugin s’exécute pour la première fois, les chemins d’accès aux fichiers de configuration et aux répertoires peuvent ne pas encore exister. Si vous déléguez toute lecture / écriture de fichiers à Configurate, vous n’aurez pas besoin de vous soucier des chemins non-existants car la bibliothèque les gérera correctement.
Note
L’utilisation du format YAML (https://yaml.org/spec/1.1/) et du format JSON (https://www.json.org/) est également supporté, mais le format de configuration préféré pour les plugins Sponge est HOCON. La conversion du YAML (ou JSON) vers l’HOCON peut être automatisé en utilisant un YAMLConfigurationLoader (ou GsonConfigurationLoader) pour charger l’ancienne configuration, puis la sauvegarder en utilisant un HoconConfigurationLoader.
