Metadane Wtyczek

Informacja

The metadata described here is for plugins for SpongeAPI 8 or later. Plugins for version 7 should define their metadata in the @Plugin annotation

Every Sponge plugin must have an entry in a metadata file known as sponge_plugins.json, which is found in the META-INF directory. In most cases, a plugin JAR will contain this file, and the file will refer to one plugin. However, it is possible for there to be multiple plugins in a JAR, and the metadata file can represent multiple plugins.

Jeśli używasz Gradle, SpongeGradle 2 ułatwi Ci zdefiniowanie metadanych dla twojego pluginu. Jeśli tworzysz nowy plugin lub potrzebujesz referencji do tego jak używać SpongeGradle 2, spójrz na nasze repozytorium szablonu pluginu które pokazuje przykładową konfigurację.

Mimo iż większość metadanych jest nieobowiązkowa, dodanie ich pomaga użytkownikom łatwiej zidentyfikować Twój plugin, dając im możliwość sprawdzenia nazwy, wersji, opisu, a nawet autorów pluginu podczas jego działania. Metadane są również używane podczas publikowania pluginów na portalu pluginów takim jak Ore.

Adnotacja Pluginu

Powinieneś oznaczyć swoją główną klasę pluginu przy pomocy adnotacji @Plugin i zawrzeć w niej jego id.

import org.spongepowered.api.plugin.Plugin;

@Plugin(id = "myplugin")

Dodatkowe metadane muszą być zdefiniowane w pliku sponge_plugins.json.

Format sponge_plugins.json

Informacja

Jeśli używasz płyciny SpongeGradle, zalecamy użycie buildera metadanych, który jest tam dostępny.

Plik META-INF/sponge_plugins.json z jednym pluginem wygląda tak:

{
    "loader": {
        "name": "java_plain",
        "version": "1.0"
    },
    "license": "MIT",
    "global": {
        "version": "8.0.0",
        "links": {
            "homepage": "https://www.spongepowered.org",
            "source": "https://www.spongepowered.org/source",
            "issues": "https://www.spongepowered.org/issues"
        },
        "contributors": [
            {
                "name": "SpongePowered",
                "description": "Lead Developer"
            }
        ],
        "dependencies": [
            {
                "id": "spongeapi",
                "version": "8.0.0"
            }
        ]
    },
    "plugins": [
        {
            "id": "test",
            "name": "Test Plugin",
            "entrypoint": "org.spongepowered.test.TestPlugin",
            "description": "Manages the test plugins"
        }
    ]
}

Na ogół, plik json pluginu nie zmieni się zbyt wiele. Każdy element w sekcji „global” może być również umieszczony w metadanych każdego pluginu, co pozwala na nadpisanie wartości w złożonych, wielo-pluginowych plikach JAR.

Poniższa tabela wyjaśnia każdą sekcję pliku:

Sekcja	Wymagane	Wyjaśnienie
Moduł ładujący	tak	Moduł ładujący używany przez plugin. W większości przypadków, plugin będzie używał modułu „java_plain” w wersji „1.0”
Licencja	tak	Licencja pliku JAR z pluginami. Swobodny tekst, ale częstym wyborem są MIT i Apache 2
Mapowanie	nie	Mapowania, w których może być zapisany kod w JAR. Format tego ciągu powinien być w formacie zależności maven-owych (group:artifact:version). Powinieneś skonsultować się z dostawcą mapowań, aby określić prawidłową formę tego pola, jeśli tego potrzebujesz. Standardowe pluginy Sponge nie będą musiały używać mapowania, więc dla nich to pole zostanie pominięte
globalne	nie	Atrybuty, które odnoszą się do wszystkich pluginów, ale mogą być nadpisane na poziomie per-plugin. Zerknij na „atrybuty pluginu” poniżej, aby zobaczyć listę dopuszczalnych wartości. Jeśli ten blok nie został określony, wszystkie wymagane wartości muszą być we wszystkich blokach pluginu.
pluginy	tak, conajmniej jeden plugin jest wymagany	Lista obiektów pluginów z określonymi metadanymi. Zerknij na „atrybuty pluginu” aby zobaczyć listę dopuszczalnych wartości.

Atrybuty Pluginów

Pluginy mogą mieć następujące atrybuty. Każdy atrybut oznaczony jako „globalny” może znaleźć się w sekcji „globalej” i może być nadpisany per-plugin.

Atrybut	Wymagane	Globalne	Wyjaśnienie
id	tak	nie	ID pluginu.
nazwa	nie	nie	Przyjazna nazwa pluginu.
description	nie	nie	Opis pluginu.
entrypoint	tak	nie	Punkt wejściowy pluginu, którym jest w pełni określona nazwa klasy, którą moduł ładujący powinien załadować (często określana jako klasa główna)
wersja	tak	tak	Wersja pluginu. Powinna być w formacie SemVer.
linki	nie	tak	Linki do Twojego projektu na internecie. Zawierają trzy właściwości - gdzie każda jest opcjonalna: homepage: strona główna Twojego pluginu source: gdzie znaleźć kod źródłowy pluginu issues: gdzie użytkownicy mogą zgłaszać problemy związane z pluginem
oznakowanie	nie	tak	Jak Twój plugin jest oznakowany na kliencie. Zawiera dwa pola: logo: ścieżka do logo Twojego pluginu icon: ścieżka do ikony Twojego pluginu
współtwórcy	tak	tak	Lista współtwórców Twojego pluginu. Co najmniej jeden jest wymagany z nazwą i opisem.
zależności	nie	tak	Lista zależności posiadanych przez Twój plugin. Zawiera następujące pola: id: ID pluginu od którego zależy Twój plugin. Wymagane. version: Wersja lub maven-owy zakres wersji, który reprezentuje wersje, od których zależy ten plugin. Wymagane. load-order: „before” or „after”, whether this plugin must load before or after the specified the plugin. Optional - if not defined, the loader will try to load the plugin at an implementation defined point. optional: true or false, whether the dependency must be present for the plugin to function