How To Code a Minecraft Plugin

After many years of waiting, today I can officially announce that Minecraft Plugin Development has come to replit! With this tutorial you will understand all you need to know on how to create the basic boilerplate for a standard Java edition plugin for the Spigot API.

This guide is geared towards creating a plugin on repl.it but will also work for IDEs such as Intelij IDEA and Eclipse (I recommend Intelij out of the two)

For any assistance feel free to leave a reply or join my Discord server discord.gg/zfgVqZv

Background Information

Minecraft Java plugin development can be done for a variety of different APIs such as CraftBukkit, Spigot, PaperMC, Bungeecord, etc.

A Minecraft plugin is essentially a library built on these APIs that will allow you to interact with the API to create custom gamemodes, administration utilities, and much more!

Plugins are typically cross compatible with the main APIs but if you use methods specific to PaperMC it will not run as intended on CraftBukkit or Spigot servers, so be careful if cross-compatibility is a concern for you.

In this tutorial we will be building our plugin on the Spigot API using Maven as our build tool (Gradle is not available on repl.it as far as i’m aware).

Getting Started

Maven

Create a new Java repl and then go to the terminal/console.

Type the following commands in this order:

• rm *
• mvn archetype:generate

After that, you should begin to see Maven (a java build tool) spit messages in console. Leave it for a minute until it asks you to start inputting information for your project.

The first message you see should be along the lines of

Choose a number or apply filter (...):

For this, choose the latest version, for example if I was given this:

1: 1.0-alpha-1
2: 1.0-alpha-2
3: 1.0-alpha-3
4: 1.0-alpha-4
5: 1.0
6: 1.2
7: 1.3
8: 1.4

I would enter 8 into the console.

After this you will see a message asking you to input your groupID. For this, if you have a domain then enter tld.yourdomain, for example I own the domain astolfo.tech so I would enter tech.astolfo. If you don’t have a domain then use me.yourname.

After this it will ask you for your artifactID, this is basically the name of your project. So, just enter what you’d like to call your plugin without any spaces or special characters. Example: tutorialplugin

Once you’ve entered your artifactID it will ask for your plugin version, just put 1.0-SNAPSHOT to start with. It doesn’t really matter what goes here but in the end it will be the prefix of your compiled jarfile.

Once that’s done it will ask for what you’d like the package to be named. In this case enter your groupID+artifactID, for example: tech.astolfo.tutorialplugin or tld.yourdomain.plugin

When that’s over it will ask you to confirm, enter Y, and then you should see this:

Pre-plugin Setup

You should see a folder in your files with the name of your artifactID, click it and open the pom.xml file.

Delete what’s currently in your pom.xml and paste the following:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>REPLACE WITH YOUR GROUPID</groupId>
    <artifactId>REPLACE THIS WITH YOUR ARTIFACT ID</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>REPLACE THIS WITH YOUR PLUGIN NAME</name>

    <description>REPLACE THIS WITH A DESCRIPTION OF YOUR PLUGIN</description>
    <properties>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    <url>https://astolfo.tech</url>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.2</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <createDependencyReducedPom>false</createDependencyReducedPom>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>

    <repositories>
        <repository>
            <id>spigotmc-repo</id>
            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
        </repository>
        <repository>
            <id>sonatype</id>
            <url>https://oss.sonatype.org/content/groups/public/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.8.8-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

Make sure to replace the values i’ve marked with your own values or your plugin will fail to compile!

Once you’ve modified the pom.xml file, navigate to src/main and create a folder called resources and then go inside that folder and create a file called plugin.yml
We will setup this file later!

After that go to src/main/java/groupID/artifactID and delete App.java.

Create a new file called YourPluginName.java and inside of it paste the following:

package YOUR-GROUP-ID.YOUR-ARTIFACT-ID;

import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public class YourPluginName extends JavaPlugin {
    
    @Override
    public void onEnable() {
    }

    @Override
    public void onDisable() {
    }
}

Replace the value for package on line 1 and the name of the class to the appropriate values.

After this, go back to your plugin.yml file and paste the following:

name: NAME_OF_PLUGIN
version: ${project.version}
main: YOUR-GROUP-ID.YOUR-ARTIFACT-ID.YourPluginName

prefix: CONSOLEPREFIX
authors: [YOURNAME]
description: REPLACE THIS WITH A DESCRIPTION THAT WILL BE SHOWN WHEN PLAYERS DO /about <YourPlugin>
website: YOUR WEBSITE

Here’s an example of a working plugin.yml file:

name: TutorialPlugin
version: ${project.version}
main: tech.astolfo.tutorialplugin.TutorialPlugin

prefix: AstolfoTutorial
authors: [AstolfoDev]
description: An example plugin for my replit tutorial!
website: https://astolfo.tech

Setting Up Your Repl

Now that we’ve sorted all that out, create a .replit file in your project root and paste in the following:

language="Java"
run="cd YOURARTIFACTID && mvn clean install"

Remember! Replace the marked value with your own

This will automatically compile your code whenever you click the run button!

Creating a Command

Now that we’ve sorted out all the basics, let’s begin creating our first command!

To start, go to your plugin.yml file and add this to the bottom of the file:

commands:
  COMMANDNAME:
    usage: /<command>

Replace COMMANDNAME with what you want the player to type in game, for example a command called tutorial will be run when you type /tutorial in game. For a full list of command properties read this documentation

After that navigate to src/main/java/groupID/artifactID and create a new folder called classes and inside that folder create a folder called commands.

Inside the commands folder create a new file called YourCommandName.java

Inside that file paste in the following boilerplate:

package YOUR-GROUP-ID.YOUR-ARTIFACT-ID.classes.commands;

import org.bukkit.*;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class YourCommandName implements CommandExecutor {
    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        return true;
    }
}

In this command I will show you how to send a basic message to the player. For more information on various that can be called on the player interface consult this documentation.

Inside our onCommand method (above the return true) we will define the Player as the command executor. To do this we will create a new Player variable called "p" by casting the "sender" variable like this.
Player p = (Player) sender;

Next, to send the message we need to use the Player#sendMessage() method like this: p.sendMessage("OwO");.

Our code should look like this now:

package tech.astolfo.tutorialplugin.classes.commands;

import org.bukkit.*;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class YourCommandName implements CommandExecutor {
    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        Player p = (Player) sender;
        p.sendMessage("OwO");
        return true;
    }
}

If your code looks like mine then that means you’re on the right track!

Now, how do we let the plugin know we want this class to be responsible for the command we created in our plugin.yml?

Simple! Head over to your plugin’s main class (YourPluginName.java) and import the class for your command by writing

import YOUR-GROUP-ID.YOUR-ARTIFACT-ID.classes.commands.YourCommandName;

After that, add the following line inside the onEnable() method

getCommand("COMMANDNAME").setExecutor(new YourCommandName());

And that’s all there is to it! You can run the repl and use your compiled jarfile (located in src/target on your server to test it out!

Creating a Listener

Commands are great and all but what if you want to do an action when an event occurs? (Ex. When a player hits an entity) Well, that’s where listeners come into play!

Go to your classes folder and create a folder called "listeners" and inside it create a new file called YourListenerName.java.

Inside this file paste in the following boilerplate:

package YOUR-GROUP-ID.YOUR-ARTIFACT-ID.classes.listeners;

import org.bukkit.*;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.*;

public class YourListenerName implements Listener {
    }
}

Remember! Replace the marked values with your own

Let’s create a new event handler which will prevent players from dropping items. To do this, create a new method with the player drop event as a parameter like this:

@EventHandler
public void noDropItems(PlayerDropItemEvent e) {
}

WARNING! Ensure you remember to put @EventHandler above the method or it will not work!

Inside our new method let’s get the player who dropped the item using the e#getPlayer() method and send him a message like this

Player p = e.getPlayer();
p.sendMessage("No littering!");

Now, let’s cancel the event so the player can’t drop the item using the e#setCancelled() method.

Our method should look like this now.

@EventHandler
public void noDropItems(PlayerDropItemEvent e) {
    Player p = e.getPlayer();
    p.sendMessage("No littering!");
    e.setCancalled(true);
}

If this is the case, we can move onto actually registering the listener.

Navigate to your main class again, import your listener class and inside your onEnable() method add a new line with the following:

getServer().getPluginManager().registerEvents(new YourListenerName(), this);

That’s all there is to creating a listener. More events can be found on the Spigot API documentation

Compiling your Plugin

Now that we’ve finished, press the run button and it should compile your plugin and put the .jar file for you to download in src/target.

If the build fails and throws an error, either check my working repl project repl.it/@agent9002/Tutorial-Plugin and see what you’ve done differently. Or, if you’re too confused then feel free to contact me.

Need Tech Support?

If you need any assistance feel free to leave a reply or join my Discord server discord.gg/zfgVqZv