Plugin Metadata

Ajouter des métadonnées de plugin aide les autres utilisateurs à identifier votre plugin plus facilement en leur donnant la possibilité de vérifier le nom, la version, la description, ou mêmes les auteurs d’un plugin lors de l’exécution. Ça sera également utilisé lors de la publication de plugins sur un portail de plugins comme Ore.

Actuellement, Sponge supporte les types de métadonnées de plugins suivants :

• Plugin ID, Plugin Name, Version

• Description

• URL (par exemple un Site Web)

• Auteurs

• Dépendances de Plugins

Annotation Plugin

Vous pouvez définir des métadonnées supplémentaires dans votre annotation @Plugin. Vous pouvez fournir toutes les informations dans cette annotation, même si seulement l’id est requise. Une annotation @Plugin utilisant tous les fields disponibles ressemble à ceci:

import org.spongepowered.api.plugin.Plugin;

@Plugin(id = "myplugin", name = "My Plugin", version = "1.0",
    description = "This is a very cool plugin I made for me",
    url = "http://example.com",
    authors = {"Spongie", "FLARD"},
    dependencies = {@Dependency(id = "otherplugin", optional = true)})

Pour chaque @Dependency que vous donnez, vous voudrez peut être aussi fournir une version spécifiant un rayon de versions, en accord avec Dependency#version(). L’attribut optional indique que le plugin peut être chargé sans cette dépendance. À moins que ce ne soit spécifié explicitement, l’absence d’une dépendance empêchera le chargement de votre plugin.

Note

Pour authors et dependencies, les accolades peuvent ne pas être écrites si seulement un élément est spécifié, par exemple: dependencies = @Dependency(id = "otherplugin", optional = true) dans l’exemple ci-dessus.

Métadonnées de Fichiers

En plus des métadonnées de plugin définies dans l’annotation du plugin, nous recommandons aussi aux plugins d’inclure ces métadonnées dans un fichier supplémentaire dans le JAR, qui présente plusieurs avantages :

• Intégration plus simple pour les systèmes de build (par exemple mettre la version depuis le système de build dans les métadonnées du plugin)

• Plus facile pour les portails de plugins d’obtenir les métadonnées de plugin (aucune analyse des fichiers class nécessaire)

Note

Nous recommandons fortement aux plugins publics d’inclure des métadonnes de fichier. Les portails de plugins comme Ore peuvent exiger des métadonnées de fichier. Voir Utiliser le Processeur d’Annotations pour une façon simple de le générer. L’implémentation peut afficher un avertissement si un plugin ne possède pas de métadonnées de fichier.

Le format du mcmod.info

Pour les plugins Sponge, nous utilisons un fichier appelé mcmod.info, qui fait partie de la racine du JAR de votre plugin. Le format est originaire de Forge, et a été utilisé par plusieurs projets dans la communauté Minecraft, donc nous avons choisi d’utiliser le même.

mcmod.info est en fait un simple fichier JSON qui définit les métadonnées de plugin comme de simples champs. Voici un fichier exemple qui pourrait être utilisé pour un plugin Sponge :

[{
    "modid": "myplugin",
    "name": "My Plugin",
    "version": "1.0",
    "description": "This is a very cool plugin I made for me",
    "authorList": [
        "Spongie",
        "FLARD"
    ],
    "dependencies": [
        "otherplugin"
    ]
}]

Utiliser le Processeur d’Annotations

L’écriture d’un fichier supplémentaire est un peu annuyant. Heureusement, vous n’avez habituellement rien d’autre à faire. Lorsque vous compilez votre plugin, SpongeAPI est capable de générer ce fichier automatiquement en fonction des informations fournies dans votre annotation @Plugin.

Activation

Si vous utilisez un système de build comme Gradle ou Maven et n’avez pas explicitement désactivé le traitement d’annotations, vous n’avez rien d’autre à faire. Par défaut, le processeur d’annotations va automatiquement s’exécuter et générer un fichier mcmod.info basé sur le contenu de votre annotation @Plugin.

Si vous n’utilisez pas de système de build, vous avez besoin d’activer manuellement le processeur d’annotations.

Intégration de Système de Build

Si vous utilisez Gradle, SpongeGradle va fournir une intégration supplémentaire pour Gradle et les métadonnées de plugin. Par exemple, il va inclure automatiquement la version du projet définie dans le script de build de Gradle dans les métadonnées de plugin. Voir Configurer Gradle pour plus de détails.

Note

Si vous utilisez l’IDE NetBeans, assurez-vous d’avoir décoché l’option Compile On Save dans Project Properties > Build > Compile pour être sûr que le fichier mcmod.info soit généré correctement.