Minecraft Plugin Development Guide

For those new to Minecraft Plugins, there's a lot of new and old documentation to run through on the web.

Additionally plugins compiled on newer versions of Java weren't working on older stable Minecraft server versions.

I've captured my learning in two places:

This guide covers the workflow of editing, compiling and testing plugins.
A plugin starter template: https://github.com/briangershon/minecraft-plugin

The guide and plugin were developed using MacOS, but concepts should work on Windows and Linux as well.

What is a Minecraft plugin?

A plugin in a Java module that runs on a Minecraft server, and can be used to create commands, games, and tools for editing the world.

This is different than Minecraft Mods which actually change and add features to Minecraft itself.

To test your plugin, you need a Minecraft server running locally on your machine, and there are many servers. Spigot and Paper are two popular ones.

Getting Started

I started my journey with Creating a blank Spigot plugin, using Maven.

Then took a slightly different path:

using Visual Studio Code (see setup instructions below)
compiling the plugin directly via the terminal and not rely any specific IDE

Environment Setup and Workflow

I've tested this guide on MacOS with these dependencies:

Java 21 JDK (installed via https://www.oracle.com/java/technologies/downloads)
Installed Maven via Home Brew (brew install maven).

Run a local Minecraft server

Build latest version of spigot via https://www.spigotmc.org/wiki/buildtools into ~/minecraft/spigotmc directory.

Build for same version as your Minecraft client.

cd ~/minecraft/spigotmc
export MAVEN_OPTS="-Xmx2G"
java -Xmx2G -jar BuildTools.jar --rev 1.20.4

You'll now have a spigot-1.20.4.jar file in your current directory.

In one terminal window, I run Spigot via creating a run.sh script for MacOS. The script is:

#/bin/sh
java -Xms2G -Xmx2G -jar spigot-1.20.4.jar nogui

and then run chmod u+x run.sh to make it executable.

If not running MacOS, you'll need to automate this a bit differently, or just run the java command directly in the terminal without a script.

I then restart/reload this server as I iterate on the plugin.

Create Plugin

Visit my plugin starter template which you can clone into your ~/minecraft folder: https://github.com/briangershon/minecraft-plugin

Code Editing

I use Visual Studio Code.

Here are installation instructions:

Visual Studio Code is available at https://code.visualstudio.com/download
Their recommended extension is "Coding Pack for Java". Though if you already have Visual Studio Code and Java JDK installed you may just need the "Extension Pack for Java". More details at https://code.visualstudio.com/docs/languages/java.

Eclipse and IntelliJ are also popular.

If using Eclipse, install Eclipse IDE via https://www.eclipse.org/downloads/packages/installer

Test the plugin

I use a second terminal session for compiling and copying the plugin to the local server.

mvn clean package
cp target/PluginDemo-n.n.n.jar ~/minecraft/spigotmc/plugins/

Flip over to ~/minecraft/spigotmc terminal and type reload. Or if server not running use run.sh script.

You can then run the Minecraft client, choose Multiplayer, choose Direct Connection, type localhost for Server Address. Inside Minecraft, you can type /plugins and you should see yours listed.

briangershon/README.md