Note: This tutorial equally applies to creating plugins for both the Bukkit and Spigot plugin API’s. For simplicity’s sake, I am going to assume you are running a Spigot server.
Creating a plugin to install on a Spigot server is made easier using a build automation tool such as Gradle. Although you can create your plugin by downloading the required API libraries and any dependencies, this can quickly become very burdensome and error prone. Also, managing the libraries and executing a bunch of build commands distracts from your real purpose – building an interesting and high quality plugin.
This tutorial assumes you have some basic knowledge of Java programming. It also assumes you have a Spigot server already running where you can deploy your newly created plugins.
This tutorial is a companion to the official Bukkit Plugin Tutorial, which can be found by following this link: https://bukkit.gamepedia.com/Plugin_Tutorial.
The official tutorial uses the Maven build automation tool, and the Eclipse Integrated Development Environment to create a plugin. In this tutorial, we will use the Gradle build automation tool to accomplish the same task. Gradle can be easier to deal with, since it uses a simple scripting language to define the plugin build process. Gradle and Maven share many assumptions about how a project should be structured; any previous experience you have with Maven – including completing the official Bukkit Plugin Tutorial – will prove helpful when using Gradle.
The steps required to build a Spigot plugin are:
- Install a Java SDK
- Install Gradle
- Set your development environment using environment variables.
- Start building!
These topics will all be covered in this tutorial. At the end you will have a working plugin that you can install in your Spigot server. Once you have completed this tutorial, you can switch over the official Bukkit Plugin Tutorial to continue learning about adding features to your plugin project.
Install a Java SDK
When creating your plugin, you will be writing Java code. In order to translate the Java code into a program your computer can run, you will need to compile it into bytecode. It is this bytecode that the Java Runtime Environment (JRE) can execute to produce a running program.
You likely already have a JRE installed on your computer. It is required to run Minecraft Java Edition. If you have ever run the “java” command to start a program, then you have used the JRE.
However, in order to create Java programs, you will need to install a Java Software Development Kit (SDK). The SDK provides additional commands, including “javac” – the Java compiler. This is the program that translates your code into something the JRE can run.
There are many different distributions of the JDK available, all of which have their strengths and weaknesses. I primarily use a distribution from Red Hat, called the Red Hat OpenJDK. I have used this JDK distribution to build Spigot plugins, as well as run the Spigot server, and have found it to be reliable and easy to work with. One downside to the Red Hat OpenJDK is the download process. Red Hat requires that you create a Red Hat account, and provide information like your employer and phone number. This is because Red Hat is in the business of selling enterprise software to large customers.
For this tutorial, I am going to use Amazon Corretto 8. This is a distribution of the OpenJDK by Amazon that does not require any registration or logins to download and install.
To download a Windows MSI installer for Amazon Corretto 8, you can use this download link. It will download the latest version that is available: https://corretto.aws/downloads/latest/amazon-corretto-8-x64-windows-jdk.msi.
Run the MSI installer, and accept all the default values. Amazon Corretto 8 is also available for Mac OS and Linux users. To find installers for these platforms, visit this web page: https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html.
The instructions for installing Grade on any operating system can be found at this website: https://gradle.org/install/. This tutorial assumes you are using Windows 10.
To start the installation, create a new directory on your computer called C:\Gradle. This can be accomplished using either File Explorer, or using the “mkdir” command from the Command Prompt.
Now, download the Gradle Binary distribution. This distribution has all that you need to use Gradle. There is a Source distribution as well, but that is meant for developers who will be hacking on the Gradle code itself.
The most current version of the Binary distribution when this tutorial was written was at: https://gradle.org/next-steps/?version=6.3&format=bin. This will download a ZIP file to your computer. Copy this ZIP file to the C:\Gradle directory that you created earlier. You can Unzip this file using File Explorer by right-clicking on the ZIP file, and selecting “Extract All…”. Accept any default values, and you will end up with a new directory called something like “gradle-6.3-bin” in your C:\Gradle directory. At this point, Gradle is installed on your computer.
Set Environment Variables
For the rest of this tutorial, we will be using the Windows Command Prompt to execute the commands needed to create and build our plugin project. In order for the Java and Gradle commands to work properly under the Command Prompt, we need to set some environment variables. These tell the Command Prompt where to look for your installed programs.
Start by opening the Command Prompt, and creating a new directory for your plugin project. In this tutorial, I am using the directory
C:\code-demo. You can make this directory by issuing these three commands:
Your command prompt should now say
C:\code-demo, indicating that you are in the newly created directory.
I find that the easiest way to set environment variables is to create and execute a batch file. Using Notepad (or any other text editor), create a new file called
setenv.cmd and add these lines of text to the file. Don’t forget to save!
This file sets two environment variables. The first,
GRADLE_HOME, should be set to the path where you installed Gradle. If you followed this tutorial exactly, it should be pretty close to the path you need. You may need to adjust the version number to match the distribution you downloaded.
The second line adds the
\bin (or binary) directory of
GRADLE_HOME to your
PATH. This is where the Command Prompt will look for commands when you execute them. Amazon Corretto should automatically add its
\bin directory to the path.
Once you have created and saved this file, you may now run the
setenv.cmd command. The output should look something like this:
In the final line, you can see that the
\bin directories for both Gradle and Amazon Corretto are in your path. You should verify this by typing the two commands shown below. If you get an error message like “gradle is not recognized as an internal or external command”, then double-check the
PATH that you have set in the
Running these two commands tells you a few important things. The first is that the programs were installed correctly, and that your
PATH is set correctly. The second, is that the version of Java which Gradle will use is the one you just installed. You can tell this because the version number displayed for the JVM attribute of the “gradle” command matches the version number produced by the “java” command.
We are now ready to start building our plugin!
Create Your Gradle Project
One of the features of Gradle is the ability to create a shell project using the Gradle command, so that you don’t have to start writing your code from scratch. Besides being a time-saver, this also ensures that the directory structure of your project is set up correctly. Gradle is a class of build tools called “opinionated software”. Another common phrase describing tools like Gradle is “convention over configuration”. This means that Gradle expects your project to be set up a certain way. For example, rather than tell Gradle where your Java source code is located (configuration), you put it where Gradle expects it (convention). This can greatly reduce the size of your build script, reducing the chances of introducing an error. Also, one Gradle project looks like all other Gradle projects, which makes it easier to find your way around someone else’s software projects.
Gradle supports several types of “starter” projects, which it calls “init types”. If you don’t specify an “init type” when starting your Gradle project, you will get a Java application. For creating a Spigot plugin, you need to create a slightly different type of application – a Java library. This is because you will not be running your Java program as a standalone program – you will be installing into another Java program; namely, the Spigot server.
Let’s get started. Enter this command to create your Gradle project. Make the selections shown below when prompted. It is recommended that you provide a unique source package name, so that your Spigot plugin won’t interfere with other plugins (and vice-versa). For this tutorial, you can use the provided package name.
After running the init command, your project directory will look like this:
Gradle created three sets of files and directories for you:
- Some Git configuration files (.gitattributes and .gitignore). These will be useful if you later check your code into the Git version control system. Note that your project directory is not automatically put under Git version control – you still need to use the “git init” command to do that.
- Some Gradle files including the Gradle Wrapper. The Gradle Wrapper allows you to distribute your code to someone who does not already have Gradle installed. The Wrapper will download and install the correct version of Gradle for your project (if needed) whenever someone runs a Gradle command.
- Your project files.
The files that are actually part of your project file are:
build.gradle– this is your actual Gradle build file.
settings.gradle– this contains some project-specific settings, like the project name.
/srcdirectory – this is where your Java code and other project files live.
Open the build.gradle file in your favorite text editor. If you don’t have a favorite text editor, I recommend Microsoft Visual Studio Code (https://code.visualstudio.com/). It is available on all platforms at no cost, and is an excellent code editor.
The first thing we need to do is add a Maven repository where we can download the Bukkit and Spigot API libraries. Libraries that your project uses are generally called “dependencies”. Add a line to the “repositories” section of the build file, such that it looks like this:
The “dependencies” section is where you list your project’s dependencies. Each dependency includes two parts – how you are using the dependency, and the name of the dependency. The name in turn typically has three parts separated by a colon: the groupid, the artifactid, and the version. This allows Gradle to find your dependencies in the various repositories your build file uses.
Gradle provides some example code in the “dependencies” section. We are going to remove this sample code, and replace it with two lines that state that we need both the Bukkit and Spigot API libraries. When finished, your “dependencies” section should look like this:
You can now save and exit this file. At this point, we can actually build our project and product a Java library file. This library contains no actual code we’ve written; however, it’s not a bad test to make sure our build file is correct.
Run the command “gradle build” and make sure your library gets built. You should see output similar to this:
You will notice that a new directory has been added to your project directory called “build”. Within that directory is a new directory (among others) called “libs”. Within that directory is our new Java library called FirstPlugin.jar. This is the file that we would copy to our Spigot server’s “plugins” directory to deploy our new plugin.
Code the Plugin
Let’s write some code!
In your project directory, navigate to this directory (relative to your project’s base directory). If you selected a different package name when creating the project, your directories from “com” on down will reflect your package name.
In this directory, Gradle has generated a sample Java source code file called
Library.java. You can delete this. In its place create a new file called
FirstPlugin.java. This will contain your plugin’s code.
In FirstPlugin.java, we are going to create a new Java class called FirstPlug that extends Bukkit’s JavaPlugin class. To do that, we will also need to import the JavaPlugin class. For now, that is all the code you need:
Gradle also created a unit test for the sample
Library.java class. This file is called
LibraryTest.java and is located under the directory
/src/test/java/com/keithlawless/demo. Delete this file before proceeding; otherwise, the unit test will fail when building your plugin.
Spigot also requires a
plugin.yml file that describes your plugin. This file is required – without it your plugin will not load into the Spigot server. You should create this file in the resources folder located at:
This folder was created for you by Gradle.
The plugin.yml file can contain many lines of code describing your plugin. We are going to create the simplest possible plugin.yml file for now. Enter this text into your plugin.yml file:
The “name” field is simply your plugin name. The “main” field contains the fully qualified name for your plugin. This is the combination of your package name, and the class name of your plugin. This tells Spigot what class to run when it loads your plugin. Finally, the “version” field contains the current version number of your plugin.
At this point, our plugin still does not actually do anything. However, if you were to build this plugin and deploy it to your Spigot server, the server will load your plugin.
At this point you have created a working shell of a Spigot plugin, and have a Gradle project configured to allow you to build your plugin.
You should now go to the official Bukkit Plugin Tutorial, and start at Section 6 – “onEnable() and onDisable()” (https://bukkit.gamepedia.com/Plugin_Tutorial#onEnable.28.29_and_onDisable.28.29). The official tutorial will pick up right where this tutorial stops. The rest of the official tutorial demonstrates adding features to your new plugin. As you add features to your plugin, you can simply run the “gradle build” command from your project directory to create your plugin library.
The code for this tutorial is available on Github at https://github.com/keithlawless/Tutorial-Create-A-Spigot-Plugin.