Spigot Plugin.yml Annotations

Jan 1, 2022
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.


    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 (XML):
    It also uses the same repository that the spigot-api repo is housed at.
    Code (XML):
    If you are using gradle then simply add this to your dependencies block:
    Code (Groovy):
    compileOnly 'org.spigotmc:plugin-annotations:1.2.3-SNAPSHOT'
    annotationProcessor 'org.spigotmc:plugin-annotations:1.2.3-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.

    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)

    Defines the human-friendly description for the plugin.
    Code (Java):
    @Description(desc = "A simple, human-friendly description")
    Defines the load order of the plugin. (Defaults to PluginLoadOrder.POSTWORLD)
    Code (Java):
    @LoadOrder(loadOn = PluginLoadOrder.POSTWORLD)
    Defines the author of this plugin.
    This annotation is repeatable.
    Code (Java):
    This annotation defines the website for this plugin.
    Code (Java):
    @Website(url = "www.spigotmc.org")
    This annotation defines the prefix used for the plugin's log entries instead of the plugin's name.
    Code (Java):
    @LogPrefix(prefix = "Test")
    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")
    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")
    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")
    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")
    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)
    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.


    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.


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