Метаданные плагина

Добавление метаданных в плагин помогает пользователям легче идентифицировать ваш плагин, предоставляя им возможность получить имя, версию, описание или список авторов плагина во время исполнения. Эта информация так же используется при публикации плагинов на различных ресурсах, таких как Ore.

На данный момент Sponge поддерживает следующие типы метаданных:

• ID плагина, название, версия

• Описание

• URL-адрес (например, веб-сайт)

• Авторы

• Зависимости плагина

Аннотация Plugin

Вы можете определить дополнительные (необязательные) метаданные плагина в аннотации @Plugin. Вы можете предоставить всю мета-информацию в аннотации, несмотря на то, что требуется только идентификатор. Аннотация @Plugin, которая использует все доступные поля, выглядит так:

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)})

Для каждой @Dependency, которую вы запрашиваете, вы также можете указать параметр version, определяющий диапазон версий в соответствии с Dependency#version(). Параметр optional указывает, что ваш плагин может работать, даже если данной зависимости нет. Если зависимость не указана как необязательна, то отсутствие какой-либо зависимости предотвратит загрузку вашего плагина.

Примечание

Для параметра authors и dependencies фигурные скобки могут быть пропущены, если указан только один элемент, например, dependencies = @Dependency(id = "otherplugin", optional = true) в приведенном выше примере.

Метаданные в файле

Дополнительно к аннотации с метаданными, определенной в плагине, мы так же рекомендуем включать в плагины файл с метаданными. Такой подход имеет ряд достоинств:

• Более простая интеграция с системами сборки (к примеру, автоматическая вставка версии сборки в метаданные плагина)

• Ресурсам посвященным плагинам проще анализировать метаданные плагина (нет необходимости разбирать class файлы)

Примечание

Мы настоятельно рекомендуем публичным плагинам включать файл с метаданными. Ресурсам посвященным плагинам, таким как Ore, могут потребоваться метаданные из файла. См. Using the Annotation Processor для простого способа генерации файла. Ресурс может вывести предупреждение, если в плагине отсутствует файл с метаданными.

Формат mcmod.info

Для Sponge плагинов мы используем файл mcmod.info, включенный в корень вашего JAR плагина. Формат файла был унаследован у Forge, так как данный формат успешно использовался несколькими проектами Minecraft сообществ.

mcmod.info это обычный JSON файл, который определяет метаданные плагина как простые поля. Ниже приведен пример файла, который может быть включен в 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"
    ]
}]

Использование процессора аннотаций

Написание дополнительного файла весьма раздражает. К счастью, для этого не требуется особых усилий. При компиляции вашего плагина, SpongeAPI способен генерировать этот файл автоматически на основе информации, представленной в аннотации @Plugin.

Включение

If you’re using a build system such as Gradle or Maven and have not explicitly disabled annotation processing there is nothing extra you need to do. By default, the annotation processor will automatically run and generate a mcmod.info file based on the contents of your @Plugin annotation.

Если вы не используете систем сборки, то вам необходимо вручную включать процессор аннотаций.

Интеграция с системами сборки

Если вы используете Gradle, то SpongeGradle обеспечит вам дополнительную интеграцию метаданных Gradle и метаданных плагина. Например он автоматически включит версию сборки, описанную в скрипте сборки Gradle, в ваши метаданные плагина. См. Настройка Gradle для деталей.

Примечание

If you’re using the NetBeans IDE make sure you’ve unchecked the Compile On Save option under Project Properties > Build > Compile to make sure the mcmod.info file will be generated correctly.