Configuration des plugins

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 fichier de configuration sauvegardés. Le reste de ce guide suppose que vous savez déjà utiliser HOCON. Regarder 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.

• Loaders de Configuration
• Configuration des Nodes
• Sérialisation d’objets

Démarrage rapide

Créer une Configuration de Base pour votre Plugin

Les plugins utilisant l’API Sponge 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

L’API Sponge 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.

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 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;

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

Le format YAML (http://yaml.org/spec/1.1/) est également supporté, mais le format préféré pour les configurations de plugins Sponge est HOCON. La conversion de YAML à HOCON peut être automatiséeen utilisant un YAMLConfigurationLoader pour charger l’ancienne configuration puis la sauvegarder en utilisant un HoconConfigurationLoader.