Nukkit Plugin Annotations is now available

Categories: Nukkit | Tags: News

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.

Example: (full)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Plugin(name = "TestPlugin", version = "1.0")
@Description("A test plugin")
@LoadOrder(PluginLoadOrder.STARTUP)
@Author("md_5")
@Website("www.spigotmc.org")
@LogPrefix("Testing")
@Dependency("FastAsyncWorldEdit")
@Dependency("LuckPerms")
@LoadBefore("MobPlugin")
@SoftDependency("PlotSquared")
@Commands(@Command(name = "foo", desc = "Foo command", aliases = {"foobar", "fubar"}, permission = "test.foo", permissionMessage = "You do not have permission!", usage = "/<command> [test|stop]"))
@Permission(name = "test.foo", desc = "Allows foo command", defaultValue = "op")
@Permission(name = "test.*", desc = "Wildcard permission", defaultValue = "op", children = {@ChildPermission(name ="test.foo")})
@ApiVersion("1.0.0")
public class TestPlugin extends PluginBase {

Output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# Auto-generated plugin.yml, generated at 2018/07/12 22:16:27 by cn.wode490390.nukkit.pluginannotation.PluginAnnotationProcessor

main: io.nukkit.exampleplugin.ExamplePlugin
name: TestPlugin
version: '1.0'
description: A test plugin
load: STARTUP
author: md_5
website: www.spigotmc.org
prefix: Testing
depend:
- FastAsyncWorldEdit
- LuckPerms
softdepend:
- PlotSquared
loadbefore:
- MobPlugin
commands:
  foo:
    aliases:
    - foobar
    - fubar
    description: Foo command
    permission: test.foo
    permission-message: You do not have permission!
    usage: /<command> [test|stop]
permissions:
  test.foo:
    description: Allows foo command
  test.*:
    description: Wildcard permission
    children:
      test.foo: {}
api:
- 1.0.0

Getting Started

Prerequisites

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.

1
2
3
4
5
6
<dependency>
  <groupId>com.github.wode490390</groupId>
  <artifactId>PluginAnnotations</artifactId>
  <version>v1.2.2-SNAPSHOT</version>
  <scope>provided</scope>
</dependency>

It uses the JitPack repository.

1
2
3
4
5
6
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

If you are using gradle then simple add this to your dependencies block:

1
2
compileOnly 'com.github.wode490390:PluginAnnotations:v1.2.2-SNAPSHOT'
annotationProcessor 'com.github.wode490390:PluginAnnotations:v1.2.2-SNAPSHOT'
1
maven { url 'https://jitpack.io' }

These annotations are not required to be in any sort of order, any order depicted here is simply for illustrative purposes.

Required Annotations

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, version, and api 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 Javadoc.

1
@Plugin(name="TestPlugin", version="1.0")

Optional Annotations

@Description

Defines the human-friendly description for the plugin.

1
@Description(desc="A simple, human-friendly description")

@LoadOn

Defines the load order of the plugin. (Defaults to PluginLoadOrder.POSTWORLD)

1
@LoadOrder(loadOn=PluginLoadOrder.POSTWORLD)

@Author

Defines the author of this plugin.

This annotation is repeatable.

1
2
@Author(name="md_5")
@Author(name="md_not_5")

@Website

This annotation defines the website for this plugin.

1
@Website(url="www.spigotmc.org")

@LogPrefix

This annotation defines the prefix used for the plugin’s log entries instead of the plugin’s name.

1
@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.

1
2
@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.

1
2
@LoadBefore(plugin = "Essentials")
@LoadBefore(plugin = "Vault")

@SoftDependency

Defines a plugin that is required for this plugin to have full functionality.

This annotation is repeatable.

1
2
@SoftDependency(plugin = "TaskChain")
@SoftDependency(plugin = "Featherboard")

@Command

Defines a new command for this plugin.

This annotation is repeatable.

1
2
@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.

1
2
@Permission(name = "test.foo", desc = "Allows foo command", defaultValue = "op")
@Permission(name = "test.*", desc = "Wildcard foo permission", defaultValue = "op")

@ChildPermission

Defines a new child permission. This annotation is only used in the @Permission annotation.

1
@Permission(name = "test.*", desc = "Wildcard permission", children = {@ChildPermission(name ="test.foo")})

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

Appendix

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.