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 (XML):
<dependency>
<groupId>org.spigotmc</groupId>
<artifactId>plugin-annotations</artifactId>
<version>1.2.3-SNAPSHOT</version>
</dependency>
<groupId>org.spigotmc</groupId>
<artifactId>plugin-annotations</artifactId>
<version>1.2.3-SNAPSHOT</version>
</dependency>
Code (XML):
<repositories>
<repository>
<id>spigot-repo</id>
<url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
</repository>
</repositories>
<repository>
<id>spigot-repo</id>
<url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
</repository>
</repositories>
Code (Groovy):
compileOnly 'org.spigotmc:plugin-annotations:1.2.3-SNAPSHOT'
annotationProcessor 'org.spigotmc:plugin-annotations:1.2.3-SNAPSHOT'
annotationProcessor 'org.spigotmc:plugin-annotations:1.2.3-SNAPSHOT'
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.
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.
@LoadOnCode (Java):
@Description(desc = "A simple, human-friendly description")
Defines the load order of the plugin. (Defaults to PluginLoadOrder.POSTWORLD)
@AuthorCode (Java):
@LoadOrder(loadOn = PluginLoadOrder.POSTWORLD)
Defines the author of this plugin.
This annotation is repeatable.
@WebsiteThis annotation is repeatable.
Code (Java):
@Author("md_5")
@Author("md_not_5")
@Author("md_not_5")
This annotation defines the website for this plugin.
@LogPrefixCode (Java):
@Website(url = "www.spigotmc.org")
This annotation defines the prefix used for the plugin's log entries instead of the plugin's name.
@DependencyCode (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.
@LoadBeforeUse the required plugin's name attribute to specify a dependency.
This annotation is repeatable.
Code (Java):
@Dependency(plugin = "WorldEdit")
@Dependency(plugin = "Towny")
@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.
@SoftDependencyThis is equivalent to the other plugin soft-depending on this plugin.
This annotation is repeatable.
Code (Java):
@LoadBefore(plugin = "Essentials")
@LoadBefore(plugin = "Vault")
@LoadBefore(plugin = "Vault")
Defines a plugin that is required for this plugin to have full functionality.
This annotation is repeatable.
@CommandThis annotation is repeatable.
Code (Java):
@SoftDependency(plugin = "TaskChain")
@SoftDependency(plugin = "Featherboard")
@SoftDependency(plugin = "Featherboard")
Defines a new command for this plugin.
This annotation is repeatable.
@PermissionThis 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")
@Command(name="bar", desc="Bar command")
Defines a new permission for this plugin.
This annotation is repeatable.
@ChildPermissionThis 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)
@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.
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 SourcePlugin.yml Wiki
Repeating Annotations Documentation