Spigot Plugin.yml Annotations

May 2, 2018
Spigot Plugin.yml Annotations
  • Spigot Plugin.yml Annotations

    Annotation-based automatic plugin.yml generation




    Plugin Annotations is a tool created to help developers who find it tedious to make and fill out a plugin.yml file every time they create a new project.


    Prerequisites(top)

    The only prerequisite to using plugin-annotations is to have it as a dependency. If you are using maven this is the same process as adding any other dependency.
    Code (HTML5):
    <dependency>
      <groupId>org.spigotmc</groupId>
      <artifactId>plugin-annotations</artifactId>
      <version>1.1.0-SNAPSHOT</version>
      <scope>provided</scope>
    </dependency>
    It also uses the same repository that the spigot-api repo is housed at.
    Code (HTML5):
    <repositories>
      <repository>
        <id>spigot-repo</id>
        <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
      </repository>
    </repositories>
    If you are using gradle then simple add this to your dependencies block:
    Code (Groovy):
    compileOnly 'org.spigotmc:plugin-annotations:1.1.0-SNAPSHOT'
    These annotations are not required to be in any sort of order, any order depicted here is simply for illustrative purposes.

    Required Annotations(top)

    Plugin-annotations only has one required annotation! The @Plugin annotation.
    If you are familiar with how plugin.yml files work then you probably know that the only required attributes are the main, name, and version attributes. All other attributes are, while helpful, optional. The @Plugin annotation satisfies all three of those requirements in a single annotation.

    @Plugin
    There are two values that are required within the @Plugin annotation. They are name, and version.
    The name attributes defines the name of the plugin and the version attribute defines the version of the plugin.
    For more information on these attributes see the Plugin.yml wiki.
    Code (Java):
    @Plugin(name="TestPlugin", version="1.0")

    Optional Annotations(top)


    @Description
    Defines the human-friendly description for the plugin.
    Code (Java):
    @Description(desc="A simple, human-friendly description")
    @LoadOn
    Defines the load order of the plugin. (Defaults to PluginLoadOrder.POSTWORLD)
    Code (Java):
    @LoadOrder(loadOn=PluginLoadOrder.POSTWORLD)
    @Author
    Defines the author of this plugin.
    This annotation is repeatable.
    Code (Java):
    @Author(name="md_5")
    @Author(name="md_not_5")
    @Website
    This annotation defines the website for this plugin.
    Code (Java):
    @Website(url="www.spigotmc.org")
    @LogPrefix
    This annotation defines the prefix used for the plugin's log entries instead of the plugin's name.
    Code (Java):
    @LogPrefix(prefix="Test")
    @Dependency
    This annotation defines another plugin that is required for this plugin to load.
    Use the required plugin's name attribute to specify a dependency.
    This annotation is repeatable.
    Code (Java):
    @Dependency(plugin = "WorldEdit")
    @Dependency(plugin = "Towny")
    @LoadBefore
    Defines a plugin that this plugin should load before.
    This is equivalent to the other plugin soft-depending on this plugin.
    This annotation is repeatable.
    Code (Java):
    @LoadBefore(plugin = "Essentials")
    @LoadBefore(plugin = "Vault")
    @SoftDependency
    Defines a plugin that is required for this plugin to have full functionality.
    This annotation is repeatable.
    Code (Java):
    @SoftDependency(plugin = "TaskChain")
    @SoftDependency(plugin = "Featherboard")
    @Command
    Defines a new command for this plugin.
    This annotation is repeatable.
    Code (Java):
    @Command(name = "foo", desc = "Foo command", aliases = {"foobar", "fubar"}, permission = "test.foo", permissionMessage = "You do not have permission!", usage = "/<command> [test|stop]"
    @Command(name="bar", desc="Bar command")
    @Permission
    Defines a new permission for this plugin.
    This annotation is repeatable.
    Code (Java):
    @Permission(name = "test.foo", desc = "Allows foo command", defaultValue = PermissionDefault.OP)
    @Permission(name = "test.*", desc = "Wildcard foo permission", defaultValue = PermissionDefault.OP)
    @ChildPermission
    Defines a new child permission. This annotation is only used in the @Permission annotation.
    Code (Java):
    @Permission(name = "test.*", desc = "Wildcard permission", children = {@ChildPermission(name ="test.foo")})

    All these annotations have the same options as their plugin.yml counterparts.

    Appendix(top)

    Plugin-Annotations uses java 8's repeatable annotation. The follow annotations are repeatable, and their parents follow.
    @Author -> @Authors
    @Dependency -> @DependsOn
    @LoadBefore -> @LoadBeforePlugins
    @SoftDependency -> @SoftDependsOn
    @Command -> @Commands
    @Permission -> @Permissions

    It is highly recommended to simply repeat the usage of a repeatable annotation instead of using it's parent to register multiple of the same annotation.

    This wiki does not go into the specific attributes of each annotation for the sake of brevity. The source is easily accessible and most IDEs will give you prompts about the required attributes, as well as optional attributes.

    Links(top)

    Plugin-Annotations Source
    Plugin.yml Wiki
    Repeating Annotations Documentation
  • Loading...
  • Loading...