Getting started with Bukkit plugin development

This post pertains specifically to Bukkit, which is no longer available due to a DMCA takedown request, and the future of Bukkit is somewhat in question now unfortunately.

Getting started developing in any platform always has a learning curve as you find your way around the language(s), tools and conventions involved. Developing plugins for Bukkit is no different. There are a number of good tutorial resources on this topic, so rather than do a full write-up we’ll link to a couple of tutorials and then add some additional comments to outline the process and identify some of the things to watch for — the ‘gotchas’ of plugin development.

The general process for getting started can be enumerated in these steps:

Install the following tools to set up your development environment.

  • Download Oracle’s Java SE JDK (the JRE alone is not sufficient). Go ahead and install that first since you will need this to run Eclipse.
  • Download and install Eclipse (if you are already set up to do Java development with another IDE, such as NetBeans, that’s great. In this post we’ll focus on Eclipse though.)
  • Get the Bukkit jar file. (craftbukkit-1.7.10-R0.1-20140804.183445-7.jar) [Which you can’t get anymore]

You will find several tutorials (both documents and videos) with a bit of searching online. But two pretty reasonable tutorials to get your started are here:

Bukkit Coding for Dummies — a 10 page Google Doc covering pluggin development using Eclipse. This has some useful screen shots and code examples.

How to make a Bukkit plugin — This site has several similar examples, also with screen shots and code examples. To pick one tutorial, take a look at Part 10 on invisibility and custom books.

These tutorials will give you the details. For the sake of having a more general overview though, the steps for creating a plugin is basically this:

1. Launch into Eclipse and select your workspace — some directory somewhere on your computer that you can let Eclipse more or less have free reign in. Eclipse will use that directory

2. Create a new Java Project.

3. Add a new Package. This is basically your java source file. The convention in the world of Java is to name packages using a reverse-url, so you might use com.myfullname.bukkitone. (And no, you don’t need to really have the name registered or anything like that… although it is a nice touch if you do.)

4. Write up your plugin (see the tutorials above for more details there.) Be sure to import the appropriate libraries as needed.

5. Create your YML file for your Pluggin. This is where you will list the commands your plugin recognizes.

6. Compile your code into a JAR file. Select your project in the Package Explorer and then Select Export -> JAR File. Uncheck .classpath and .project from the resources to export, and select the location for Eclipse to save your jar file. You can click through to the next couple of screens but the defaults after this should be fine. You can also just hit ‘Finish’.

7. Copy your jar file to your Minecraft server’s plugin directory and start up Minecraft. Minecraft should recognize the plugin and load it. You should see this if you tail the logs/latest.log file.

Things that may trip you up….

Q1) I can’t compile my plugin but my code looks right? Except that Eclipse doesn’t recognize JavaPlugin and a bunch of other names?
A1) You probably don’t have the craftbukkit jar file loaded, or it is somewhere that Eclipse can’t find it (this may be the case if you cloned a plugin from a Git repo and the Eclipse project is referencing a jar file in a path that doesn’t exist on your computer.) You can correct that by simply adding the jar file (which you should have downloaded by now.)
  1. Go to your projects properties and go to the Java Build Path section.
  2. Click on the Libraries tab.
  3. Click on the Add External Jars button and find the craftbukkit jar file on your computer.
Q2) Why is my plugin not running on my server? It runs okay on my laptop?
A2) This is generally due to a mismatch between the version of Java that your plugin was compiled for and the version you are running on your server. Particularly if you see a message in your error log that looks something like:
Could not load ‘plugins/MyPluggin.jar’ in folder ‘plugins’
org.bukkit.plugin.InvalidPluginException java.lang.UnsupportedClassVersionError de/nofear13/craftbukkituptodate/CraftBukkitUpToDate : Unsupported major.minor version 51.0
You can’t load a plugin compiled with Java8 on a server where you are running Bukkit with java7. So what are you supposed to do if you can’t control which version of java is running on the server?
The short answer is that you have to compile your pluggin to target Java 6 or higher. In Eclipse you should do the following:
  1. Go to your projects properties and go to the Java Compiler section.
  2. Uncheck ‘Use compliance from execution environment…’
  3. Set Compiler Compliance Level to 1.6
After that try re-building your jar file and try that.
Q3) In my java code I added a command, but I can’t invoke the command?
A3) Besides the Java source you need to list commands in the plugin’s yml file (a lot of examples don’t note this at all)