Minecraft Bukkit Plugins

Minecraft is a great example technology being used for a practical purpose, having fun!  It has spawned a number of related projects.  One of those is CraftBukkit (often referred to simply as Bukkit), which is an extension of the original Minecraft server.  craftbukkitBukkit leverages everything that Minecraft does, but it provides a number of distinct advantages.  The biggest for me is a clean API and the ability to create custom plugins, which are basically additions of functionality.  This article will provide the details for creating Minecraft Bukkit Plugins.  The information discussed is supported by a working project Bukkit Ouch Plugin on GitHub.

Before you can create any Minecraft Bukkit Plugins, you will first need to install a Bukkit server.  It is pretty simple, and there are plenty of posts related to that, so it will not be covered here.  An excellent place to start would be http://wiki.bukkit.org/Setting_up_a_server.  Once you install the server, you will be ready to create your first plugin.  I chose to use the Eclipse IDE and do the development from inside of the IDE.  This was done for a number of reason.  Mostly convenience and ease of the development effort.  Eclipse does a lot for you and just make everything easier.  Again, there are plenty of posts on Eclipse and that will not be covered in detail here.

After reviewing how most of the existing Minecraft Bukkit Plugins have been created, it becomes clear that the Maven project management tool is being used extensively.  Fortunately, for you Maven is included in Eclipse as an embedded package, and it will not require any special action on your part to use it.  Before we begin developing your first Minecraft Bukkit Plugin, let's take a step back and think about what we need to do.  For this first example, let's keep it simple.  We will create a plugin that says "OUCH! That hurt!", when you break a block.  Sounds pretty simple right, and with the Bukkit API it actually is!  To do this you will need:  

  1. To have the Java JDK installed, if you have the JRE that will not be enough, it will not allow you to compile Java
  2. To have Eclipse installed and configured to be using the JDK as the default
  3. Download the sample GitHub project as a Zip file (see the link at the bottom of the page) and extract it to a temporary location
  4. Create a new Maven project in Eclipse for your plugin
  5. Define the pom.xml in the Maven project
  6. Create a Java package for your classes
  7. Create the Java classes and enter the code

Assuming that you have completed steps 1, 2 and 3, we can think about creating the project.  Eclipse makes this pretty easy.  We will use the shorthand notation of the name of menu selection followed by an arrow to the next menu selection.  To create a new Maven project do the following

  • New -> Other -> Maven -> Maven Project
  • Click on the Next button
  • In the New Maven Project window do the following: 



    1. check the "create a simple project" checkbox
    2. for the values of Group and Artifact use the values from the sample GitHub project, but don't worry too much about because you will replace the file later

Next, you will need to create a Java package for your Java class files.  To create the Java package do the following

  • New -> Package or (New -> Other -> Java -> Package)
  • In the Name field put: com.freitas.minecraft.plugins

Next, you will need to create two Java class files.  To create the classes do the following

  • New -> Class or (New -> Other -> Java -> Class)
  • In the Name field put: OuchPluginListener
  • Repeat again for OuchPlugin

Okay, this is going pretty well and you have everything you need to copy in the files from the sample project.  All you need to do next is to simply copy over the files from the sample project into the Eclipse and then Refresh the project, so that Eclipse will be know about the new files.  You can do the copying either from a file browser, command line copy command, or even directly in Eclipse with a drag and drop.  You will need to copy all three files (pom.xml, OuchPluginListener.java & OuchPlugin.java) into the exact locations in the project.

Finally, you are ready to build your Bukkit Plugin and then deploy it.  To build it, you will need to do

  • Select the ouch-plugin project and right mouse click on it to get a fly-out menu
  • Run As -> Maven build… (Note the build with the three dots is the one to use, very important)
  • A new "Edit Configuration" window will appear, do the following: 



    1. In the "Main" tab, the Name defaults to project, ouch-plugin, you want to add the word package to distinguish this from other build actions
    2. Also in the Main tab, in the "Goal" enter the word package
    3. Click on the "Common" tab, make sure that Debug and Run checkboxes are checked in the "Display in favorites menu"
  • Click on the Apply to save it and then Run button to run the build
  • If it runs successfully, you will find the ouch-plugin-<something>.jar in the target directory of the project
  • You may re-run the build with the Run As -> Maven build or using the Run As (a green circle with a white arrow) in the toolbar

For the deployment, all you need to do is copy the ouch-plugin-<something>.jar into the plugins directory of your CraftBukkit server and restart the server.  You will now be able to go into the server and every time you break a block, that block will tell you it hurt.  I know its a humble begining, but we all have to start some place.  

The Gory Details

Okay, so you have gotten this far in the Minecraft Bukkit Plugin adventure, and it is time to take things to the next level.  Lets go into the gory details of what this all works.  Starting with the pom.xml, this is a standard Maven file that is used to tell the project how to configure itself.  At this point, you really don't need to be a Maven expert.  All you really need is to understand a few important concepts.  What is the repository to get stuff from, and what stuff is needed.  

First, you will need to tell the project about the Bukkit repository.  This is the remote location that provides the required Java JAR files, or dependencies.  In your pom.xml file via the repository element:

            <name>repo.bukkit.org Releases</name>

This will give you access to the Bukkit repository, but this will not allow you to start building Minecraft Bukkit Plugins.  For that you need to include the dependencies.  These are just the things that the plugin needs to be able to build.  In this case that is the bukkit and snakeyaml Jar files.  The bukkit Jar will let you use the Bukkit API and snakeyaml will allow you process YAML files.  In the pom.xml, that is the entry 


Note: the version is expected to change as new versions of Bukkit get released. 

Note: it is not strictly required that you use Maven.  You could use Ant as well.  However, then you would need to manually retrieve the bukkit jar file and put it on the classpath.  This will not be explained here, but there are many tutorials available (http://www.vogella.com/tutorials/ApacheAnt/article.html).

As you could see there were two java classes

  1. a plugin class and
  2. a listener class

Both classes are needed for the Bukkit plugin to work.  The Bukkit framework will take care of most of the work for you, as long as you follow the provided Application Programming Interface (API).  The plugin class will define your plugin, and the listener class will wait in the background for some one to break a block.

The plugin class needs to extend the Bukkit JavaPlugin class.  The JavaPlugin class is a superclass that provide all the functionaltiy that you will need to create a Bukkit plugin.  This is where Bukkit starts doing alot of the work for you.  The class looks something like:

public class OuchPlugin extends JavaPlugin {

       private OuchPluginListener blockListener = new OuchPluginListener();

       public void onEnable() {
              PluginManager pm = getServer().getPluginManager();
              pm.registerEvents(this.blockListener, this);

In this very simple example, we are only defining the onEnable() method, which gets executed when the plugin gets started.  In this case, all we are doing is registering our custom block listener, so that it will listen to Bukkit events and when a specific one occurs to take some action (to be discussed in a little bit).  There are some other methods that are commonly defined in the plugin class:

onLoad() – used to initialize things before the plugin starts, but has loaded

onEnable() – used when the plugin starts up and is active

onCommand() – used when someone executes a command in game

onDisable() – used when the plugin shuts down

The listener class is what listens for some one to break a block and then take an action, which in our case is to say "OUCH! That hurt!".  It implements the Bukkit Listener interface, and catches the BlockBreakEvent.  When the BlockBreakEvent occurs, the listener will get the event, and then get the player and send the message to the player.  Its actually pretty simple.  

There are a large number of events defined by Bukkit.  In fact, too many to mention here.  You can take a look at the Bukkit API documentation (http://jd.bukkit.org/rb/apidocs/) to get the full list.  Look at the events defined under the package org.bukkit.event.  The generally accepted way of using these is to create a method named onDoSomething with the parameter of SomeEvent.  You can defined and register as many listeners as you would like.  

org.bukkit.event – Classes for event triggering and handling
org.bukkit.event.block – Events relating to when a block is changed or interacts with the world.
org.bukkit.event.enchantment – Events triggered from an enchantment table.
org.bukkit.event.entity – Events relating to entities, excluding some directly referencing some more specific entity types.
org.bukkit.event.hanging – Events relating to entities that hang.
org.bukkit.event.inventory – Events relating to inventory manipulation.
org.bukkit.event.painting – Events relating to paintings, but deprecated for more general hanging events.
org.bukkit.event.player – Events relating to players.
org.bukkit.event.server – Events relating to programmatic state changes on the server.
org.bukkit.event.vehicle – Events relating to vehicular entities.
org.bukkit.event.weather – Events relating to weather.
org.bukkit.event.world – Events triggered by various world states or changes.


public class OuchPluginListener implements Listener {


       public void onBlockBreak(BlockBreakEvent event) {
              Player p = event.getPlayer();
              Block bb = event.getBlock();
              p.sendMessage("OUCH! That hurt!");
              p.sendMessage("You broke " + bb.getType().toString());

The plugin.yml file is used to put any configuration information and parameters that allow the behavior of Minecraft Bukkit Plugins to be modified dynamically at runtime.  Although it is not used in this particular plugin, it will be needed for more complex plugins, and in general it is good style to always include it, just in case you need it later.  The YAML file approach is the standard way of providing configuration information that will be read at runtime.  

Source Code

Bukkit Ouch Plugin

Next Steps

Okay so now you have gotten your first Bukkit plugin to work.  You should be very pleased with yourself!  But wait, so what comes next.  The Ouch Plugin was pretty simple plugin, and you want to do something really cool, right!  Okay, well there is something for you.  There is the CustomItemsNG Plugin for you to look at.  This is a plugin based off an actual plugin for the http://dev.bukkit.org/bukkit-plugins site.  This is a very cool plugin that lets you create custom items with special powers.  Give the source code a try.  With what you learned with the Ouch Plugin, you should be able to figure it out. 

Just to shake things up and give a different example, the CustomItemsNG Plugin uses Ant for the build, as opposed to Maven.  It also includes the Bukkit libraries in a libs directory.  This should provide enough of an example to be able to build plugins with Ant.

Have fun!




8 Responses to Minecraft Bukkit Plugins

  1. Heather says:

    I was initially researching for points for my very own site and found your post, “Minecraft Bukkit Plugins |
    Logical Thoughts on TechnologyLogical Thoughts on Technology”,
    do you care in the event I really use several
    of your suggestions? Thx ,Milan

  2. Bob Freitas says:

    Hi Milan,

    Not at all! Its there to share, use as you choose!


  3. An extremely good write-up, i am grateful again and have a brilliant morning!

  4. Pat Bailleu says:

    Fantastic! What a fantastic post, thanks a lot, I’ve learned a whole lot.

  5. Santo Flota says:

    Useful info. Fortunate me I found your web site by chance, and I am shocked why this coincidence didn’t happened in advance! I bookmarked it.

  6. Bob Freitas says:

    Thanks! Glad you liked it!

  7. Bob Freitas says:

    You are very welcome!

  8. Bob Freitas says:

    Stay tuned I will have more articles soon!

Comments are closed.