2021 Call for Code Awards: Live from New York, with SNL’s Colin Jost! Learn more

Archived | Building plugins for Minecraft with Docker and Eclipse

Archived content

Archive date: 2019-12-09

This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.

In Part 1 you learned how to set up both an “off-the-shelf,” or unmodified, Minecraft server in Docker and a Spigot server in Docker. This is the first step to building your own Minecraft plugins that can take advantage of the many services, including Watson cognitive services, available on IBM Cloud, IBM’s platform as a service (PaaS) environment. Using these services will make your game experience smarter and more enjoyable.

But you can’t just jump over a mountain in one leap. You need to complete a few more steps before you can build plugins that can use the Watson services. In Part 2 we’ll take you through the next step in setting up your local development environment: setting up Eclipse, then developing, building, and exporting your own server-side Minecraft plugin into a local Docker image.

We’ll do all of the development in the Eclipse integrated development environment (IDE). Eclipse is a free, open-source development environment for Java® and a number of other languages. You can choose almost any Java IDE for Minecraft plugin development, but Eclipse is commonly used in the Minecraft development community among those who use an IDE.

Set up Eclipse in Ubuntu

To use the Eclipse IDE, you need to first install Java in your Ubuntu Linux environment. Eclipse is not only an environment for developing programs in Java, but is itself a Java program. The command to install Java should look familiar because we used it in our Dockerfiles in Part 1. However, this time you need to run the command at the command line of your Ubuntu Linux installation: sudo apt-get install -y default-jdk

Once you’ve successfully installed the JDK version 7, you have a choice:

  • If you’re more comfortable using the Ubuntu GUI, go to the Eclipse downloads page and select the Eclipse Mars release, then download the installation file for Eclipse. The installation file is in the form of a Gzipped tar file. Double-click the tar file in the Ubuntu file manager to open it with the Archive Manager. Then use the file manager to extract the contents of the file to a directory named “eclipse”.
  • If you’re more comfortable using the command line, issue the following commands one at a time:

    -O eclipse-jee-mars-R-linux-gtk-x86_64.tar.gz
    tar -xzf eclipse-jee-mars-R-linux-gtk-x86_64.tar.gz

Regardless of how you downloaded and installed Eclipse, you start it the same way. Assuming that you installed it off of your home directory, type the following command at the command line to start Eclipse: ./eclipse/eclipse

Once Eclipse starts, you’ll be asked whether you want to create a new default workspace or use an existing one. Go ahead and create the default workspace in the directory it specifies.

Workspace launcher

On the Eclipse Welcome screen, click the Workbench icon in the upper right corner to open the workbench.

Workbench icon

You see the Eclipse Workbench:

Eclipse workbench

Import the archive file

We’ll use the Eclipse Project import feature to import a Project Archive file that includes our example. Projects in Eclipse are simply directory structures in your workspace directory. A Project Archive is a special zip file format for Eclipse that allows you to share your completely configured projects with others. Once we bring the project into Eclipse, we’ll walk through the example code. The archive import file is located in the root of the minecraft-project directory that you cloned from GitHub in Part 1, so if you’re trying to jump into this tutorial without following all the examples in Part 1, you’ll need to go back and perform that clone.

  1. Select File > Import from the menu at the top of the Eclipse Workbench.
  2. Select General > Existing Projects into Workspace, then click Next. Import dialog
  3. Select Select Archive File, then click Browse. Import dialog
  4. Navigate to the directory that you cloned to (probably your home directory, although that depends on what you did in Part 1) and open the minecraft-project directory. Select SpigotPlugin.zip and click OK. Import dialog
  5. Click Finish.
  6. In the Workspace, you’ll see a red exclamation point (!) beside SpigotProject. That’s okay — it’s just alerting us that we need to patch up the classpath to point to the spigot-1.8.3.jar file so that the Java code for our plugin will compile (because our code relies on the Spigot APIs, we have to import those APIs). Select SpigotPlugin.zip in the Project pane. Left-click (on other platforms, Alt-Enter or click while holding down the Control key) and select Properties from the pop-up menu, then select Java Build Path. Select the Libraries tab. Import dialog
  7. Select Spigot1.8.3.jar, and click Edit. Import dialog
  8. Double-click on minecraft-project, then select Spigot1.8.3.jar in the next pane. If you’re following closely, you may be worried that this Spigot JAR file doesn’t match the level of the Spigot JAR file that we built in the previous example (which was at level 1.11.2). Actually, because we’re using this JAR file only to allow our code to compile, it’s okay if it’s a bit back-level — the API hasn’t changed in awhile. If, in your own code, this does become a problem later, follow the instructions at the Spigot Build Tools wiki to locally build a new spigot JAR file and replace the one you downloaded from GitHub.
  9. Click Apply, then click OK, then OK again.

At this point, your workspace should show the SpigotPlugin project with no red exclamation points next to it, which means you’ve resolved the problem and we can get on with our example.

Build plugins for Minecraft

The Spigot plugin API is actually pretty simple. If you’ve ever used Java for other types of server-side programming, like building servlets, you’ll find that it’s a straightforward example of the same principles. The reason we’re installing a specific JDK (Java 1.7) is that plugins in Minecraft (or at least those using the Bukkit APIs) must be built on Java 1.7. Otherwise, you get strange class mismatch errors on the server. This may change in the future, but for now, it’s best to stick with Java 1.7 for your development.

The HelloWorld class

Let’s start by looking at a simple plugin for Minecraft that’s the equivalent of the Hello World program in any programming language. We’ll use this file to review some of the simpler features of the Bukkit API.

  1. To start, bring up the plugin source code file from the Eclipse Workbench project pane by clicking and expanding SpigotPlugin.
  2. Click and expand src, then expand the com.ibm.minecraftplugin directory.
  3. Click HelloWorld.java.

Let’s look at the contents of the HelloWorld.java file:

package com.ibm.minecraftplugin;

import org.bukkit.command.Command;
import org.bukkit.command.CommandSender
import org.bukkit.plugin.java.JavaPlugin

public class HelloWorld extends JavaPlugin
  public void onEnable(){
    getLogger().info("Hello World!")
  public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args)
  if (cmd.getName().equalsIgnoreCase("hello")) {
  sender.sendMessage("Hello Everybody!");
  return false;

There are two simple concepts you need to understand. First, building a plugin is as simple as extending the JavaPlugin class, so all of your plugins will be subclasses of JavaPlugin. Second, you’ll need to implement two methods in each plugin class:

  • onEnable() is an event handler that’s called when the server loads the plugin. You perform any necessary setup for the class in this method (for instance, setting up a database connection). We’re applying a standard debugging method, which is to log some status information to the logger so that when the plugin is loaded, you can see results in the log output.
  • onCommand() is called each time a user issues a Minecraft command with /&COMMAND&. Each plugin must determine whether the command can be handled by the plugin (which is as simple as comparing the name of the command to a corresponding name the plugin can handle) and then perform any actions that are necessary.

In our example, once we have validated that the command can be handled by the plugin, we simply send the message “Hello Everybody!” to the sender of the command. It’s trivial, but it’s enough to see how the concept works. If you’d like, you can change either the log message that the onEnable() method writes, or the message that the command sends back to the user to customize your plugin.

Plugin.yml file

The final piece of configuration required for a Bukkit plugin to work involves the Plugin.yml file. This configuration file describes your plugin to the rest of the framework. It’s written in YAML (Yet Another Markup Language) like many other configuration files that you’ll see in this tutorial series. One thing to keep in mind is that you cannot use tabs in YAML plugin files.

To examine your plugin.yml file, double-click the file inside the SpigotPlugin Project. The contents of the file are:

name: HelloWorld
main: com.ibm.minecraftplugin.HelloWorld
version: 1.0
    description: A new command

As you can see, it’s pretty simple: you specify the name of your plugin, the main class, and the version at the top of the file. Any commands that are handled by your class must be listed (indented one space) after the commands: section. In the example here, we’re showing only the description section of the command, but there are other sections that you can use if you examine the Plugin YAML documentation.

Test locally

Now that you’ve written the code of your first plugin, you’re ready to export it and try it out.

You can skip the next section on exporting a JAR file if you just want to use the pre-built HelloWorld.jar file example provided. If you’ve not made any changes to your code, that’s the fastest option. If you’ve made any changes, you’ll need to follow the steps in the next section to try out your new code.

Export your JAR file

To export your JAR file, complete these steps:

  1. In the Workbench, select the SpigotPlugin project, and left-click to bring up the menu, then select Export.
  2. In the Export dialog, select Java > JAR file and click Next. Export window
  3. In the JAR file specification dialog, click Browse.
  4. In the file selection dialog, navigate to the spigot-plugin subdirectory of your minecraft-project directory, and select HelloWorld.jar, then click OK. Jar file selection dialog
  5. Back in the JAR file specification dialog, click Overwrite existing files without warning, then click Finish. JAR file specification dialog

Your new JAR file has now replaced the old one. It’s time to see if your code works!

The new Dockerfile

Just as in the last example, we’ll use a new Dockerfile that will build the example inside a Docker image. First, open a second terminal window in Ubuntu — this is so you can run Docker commands while Eclipse is still running. In the new terminal window (assuming you’re in the home directory and that’s also where you cloned the minecraft-project directory), type the following two commands:

cd minecraft-project/spigot-plugin
cat Dockerfile

You’ll see the new Dockerfile for this example, as shown below. Take a moment to read through it and see if you can spot the differences from our last example Dockerfile.

# Version 0.0.3
# This version builds a spigot server
# using the recommended build strategy for spigot
# This is advantageous in that it’s better for plugin development
# and fits well with the Docker approach
# it also adds a first Minecraft plugin into the bare spigot server
FROM ubuntu:16.04
MAINTAINER Kyle Brown "brownkyl@us.ibm.com"
RUN apt-get update
RUN apt-get install -y git
RUN apt-get install -y default-jdk
RUN apt-get install -y wget
RUN mkdir minecraft
RUN wget "https://hub.spigotmc.org//jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar" -O minecraft/BuildTools.jar
RUN java -jar minecraft/BuildTools.jar –rev 1.12
RUN echo "eula=true" > eula.txt
RUN mkdir plugins
ADD HelloWorld.jar /plugins/HelloWorld.jar
CMD java -XX:MaxPermSize=128M -Xms512m -Xmx1024m -jar spigot-1.12.jar nogui
EXPOSE 25565

As you probably noticed, this is very much like the 0.0.3 example Dockerfile we looked at in Part 1 of this series, but with a couple of differences. First, this one creates a new directory called “plugins”. Second, it then performs a new command in Docker that you’ve not seen: ADD.

The ADD command takes a file from your local (host) directory and copies it into the Docker file — this is cool! That’s exactly what we want in our example — we want the ability to change our plugin file while leaving everything else alone. However, unlike the CMD command, which runs every time you start a new container with Docker run, the ADD command runs only when you do a Docker build. That means that if you make changes to your plugin, you need to rebuild your image. For this example, let’s build our new image for the first time by typing the following command at the command line:

sudo docker build ‑t="(less-thandirectory(greater-than/spigot112‑plugin"

Just as you did in Part 1, replace with your login id. The first time you build the new image, it may take a bit longer than in subsequent builds because Docker constructs some of the new image layers.

Now that you’ve built the new image, it’s time to run it! To do this, type the following command: sudo docker run -i -t -p=25565:25565 <directory>/spigot112-plugin

Because you’re starting the Docker container at the same port as previously, you shouldn’t need to change the configuration of the Minecraft client. You’ll find the first indication that your plugin is working in the on-screen logs of the Minecraft server — look for a line like this: [14:22:50 INFO]: Done (12.942s)! For help, type "help" or "?"

Once you’re sure that the server has started successfully, start up the Minecraft client, connect to your server, and then inside Minecraft type: /hello

Your Minecraft command screen should look something like this:

Minecraft screen

If you see the message “Hello Everybody” (or whatever you changed your message to), it’s working. Congratulations!


In Part 2 of this series, you learned how to build a simple server-side plugin for Minecraft using Eclipse, and how to run it on Docker. In Part 3, you’ll take your plugin to the next level by running it on the web in IBM Cloud.