SpigotPlugin.md

Developing your first Spigot plugin

This is a small guide on developing a Spigot plugin. There are other guides online, however some of these guides are outdated and do not clearly direct you on how to setup your environment properly (for example, how you add the API to your project has now changed).

This guide is updated as of 19/06/2024.

Contents

• Install Java
• Install and Compile Build Tools
• Setup Server
• Integrated Development Environment
  • Create and Prepare Project
• Develop a Plugin
  • Build Artifact
    • Setup
    • Build

Install Java

You need the Java Development Kit (JDK) which includes the Java Runtime Environment (JRE) to develop Spigot plugins using Java.

The version that Spigot supports as of 18/06/2024 is Java version 21/22 which can be downloaded from https://adoptium.net/temurin/releases/. Select the options that apply to you and select JDK as the Package Type and it will give you a download to install.

Install and Compile Build Tools

SpigotMC has developed a tool to make it easy to compile your Spigot builds called BuildTools. This tool will download the required source files, patch it and compile it for you. You can download the Spigot Build Tools from https://hub.spigotmc.org/jenkins/job/BuildTools/.

Note: You may need to install the Git tool to use the Build Tools, you can download it from https://www.git-scm.com/downloads.

When you open the tool you must select the version of the server you want to target and a location to store all of the build artifacts (jar files) before selecting Compile. This process may take a while so be patient.

Setup Server

We are going to need a server to test the plugins on.

1. Create a folder for your Minecraft server.
2. Copy the spigot.jar from the build tools directory into your server folder.
3. Create a batch file called start.bat which will be used for starting the server with the following content:

@echo off
java -Xms2G -Xmx4G -XX:+UseG1GC -jar spigot.jar nogui
pause

Replace -Xms2G (minimum heap size) and Xmx4G (maximum heap size) with the memory size (RAM) that you would prefer. 4. Run the start.bat file to setup the initial server files. 5. Agree to the eula.txt file which has been generated by opening it and replacing the value false with true. 6. Start the server again by running start.bat. 7. You should now have a running Spigot server.

Integrated Development Environment

You need an Integrated Development Environment (IDE) to develop the plugins in, you can use powerful editors like Visual Studio Code (VSCode), however using an IDE build specifically for Java will give you a much better experience.

My recommendation is to use IntelliJ IDEA which is created by JetBrains who have tons of experience developing language specific IDE's like PyCharm (Python IDE) and Rider (C#/.NET IDE).

You can download IntelliJ IDEA from https://www.jetbrains.com/idea/download/. Make sure you download the Community Edition of IntelliJ and not the Ultimate edition as it is the commercial version of the software which runs under a trial period. The community edition is the free and open source version of IntelliJ IDEA.

Create and Prepare Project

After you have installed the IDE you need to create a new project.

1. Create a project by clicking the New Project button.
2. Give the project a name (this is your plugin name).
3. Select the JDK you want to target (in this case, the JDK you downloaded and installed earlier).
4. Leave the rest of the settings as default and click the Create button
5. Right click your project and select Open Module Settings.
6. Select the Libraries tab.
7. Click the + icon to open the file browser.
8. Navigate to your server directory you setup earlier.
9. Select the ./bundler/libraries/spigot-api-version.jar file and click Ok.
10. You are now ready to develop a Spigot plugin.

Develop a Plugin

1. Right click the src directory and create a package matching the naming scheme tld.domain.subdomain. This name should be unique, an example of following this scheme is com.anchydev.testplugin. This is where all your code for your plugin will live.
2. Move the Main class file that was automatically generated into this directory.
3. Click the Main class file to edit it and implement the following code:

package com.anchydev.TestPlugin;  
  
import org.bukkit.Bukkit;  
import org.bukkit.ChatColor;  
import org.bukkit.plugin.java.JavaPlugin;  
  
public class Main extends JavaPlugin {  
    @Override  
    public void onEnable() {  
        Bukkit.getLogger().info("Hello from " + this.getName() + "!");  
    }  
}

4. Create a plugin.yml in the src directory with the following contents:

name: NameOfYourPlugin  
version: 1.0  
author: YourName  
main: com.anchydev.TestPlugin.Main
api-version: 1.20.4

Build Artifact

Setup

Before you build an artifact you must setup your artifact profile first:

1. Right click your project and select Open Module Settings.
2. Select the Artifacts tab.
3. Click the + icon to add a new artifact type.
4. Select JAR > From modules with dependencies.
5. Leave everything blank and press OK.
6. In the right panel click the + icon for adding a copy of a file.
7. Select File and add the plugin.yml file you created in the src directory earlier.
8. Set a build output path where your jar file will be compiled to.
9. Close the project settings.

Build

You are now ready to build an artifact (jar) of your plugin.

1. Open the Build menu at the top of the screen (it may be in the hamburger menu) and click Build Artifacts.
2. Copy the jar file from the output you chose earlier into your servers plugins directory.

Test

Now that you have compiled and built an artifact of your plugin, you need to test it.

1. Restart the Spigot server.
2. Wait for the server to start-up.
3. Observe the "Hello from PluginName!" message in the server console.

You have successfully created your first plugin! To develop it further you only need follow the 2nd Part of the Build Artifact section of this guide.