Bukkit Plugin Development Tutorial - Hello world

In this tutorial we're going to be creating, and running a "hello world" plugin inside the Eclipse IDE

Install Eclipse for Java Development

If you've not already done so you're going to need to install a Java Development Kit (JDK) and the Eclipse Integrated Development Environment (IDE). Basically, installing Eclipse is a case of unzipping it somewhere. Note that my recommendation is NOT to install Eclipse as a "system" program - that means if you are on Windows don't put it in "Program Files", put it somewhere in your files. For example create a directory under "Documents" called "LocalPrograms" and extract it there. The reason for this is that when it comes to updates, Eclipse can get a bit messed up in a multi-user environment, or when some files are owned by users and some by the system. All the download links, and some more info can be found on the Eclipse Wiki
You won't need to install any Eclipse plugins for this tutorial.

Bukkit or CraftBukkit?

A lot of people ask the question, "what is the difference between Bukkit and CraftBukkit?" To which people often respond with the oh-so-helpful statement "Bukkit is the API, CraftBukkit is the implementation". Let's specifically look at the difference between Bukkit.jar and Craftbukkit.jar.

Craftbukkit.jar

Craftbukkit.jar is the file that people install on their servers. It contains everything that's required for running a CraftBukkit server. Bundled in along side the Minecraft stuff are a load of useful libraries that plugins might want to make use of, for example MySql drivers.

Bukkit.jar

The theory goes like this. Everything a plugin developer needs is inside Bukkit.jar. If your code is referencing something minecraft-related and that something isn't in Bukkit.jar, then you're doing something wrong. However, the question of need is subjective:
  • Does the developer need to run their code? If yes, then Bukkit.jar doesn't do the job, because it's not runnable
  • Does the developer need any of the useful libraries that are bundled in Craftbukkit.jar?
Some might say that you should use Bukkit.jar for writing your code and Craftbukkit.jar for running it. However, Eclipse is an Integrated Development Environment - we are going to be writing, running and debugging our code all in the same set up. To do this it turns out that we need both files.
Download Craftbukkit from here and Bukkit from here

Create your hello world project

  1. In Eclipse: File->New->Java Project. Note, sometimes "Java Project" isn't there in the list, if this is the case, click "Project" instead and you will be presented with a full list of project types your Eclipse installation currently supports (and "Java Project" will be in there somewhere)
  2. Enter a name for your project. Call it anything you want within reason (must be a legal name for a directory)
  3. All the other defaults are fine, so click "Next"
  4. Click the "libraries" tab
  5. Click "add external Jar" and browse to the bukkit.jar you downloaded
  6. Do the same again for craftbukkit.jar
  7. Where bukkit.jar now appears in the main window, click the arrow to the left of it to expand the tree (see screenshot)
  8. Click "Javadoc location" then click the edit button
  9. Enter the following URL http://jd.bukkit.org/apidocs/ and click OK
  10. Check what you have against the screen shot below. It is important the bukkit JAR file is first in the build path. As of 1.6, some of the code in this tutorial will not build if craftbukkit comes before bukkit
  11. Click "Finish"


Configure your project runtime

  1. In eclipse, you should see the name of your demo project on the left hand side. Make sure it is highlighted
  2. File->New->Folder and create a new folder called "run" as a subfolder of your project
  3. Select Run->Run Configurations.... a new window will appear
  4. Find "Java application" in the list on the left and click it. Then click the "new" button which will have become active near the top left
  5. Edit the details in the right hand side, main tab
    • Change name from "New_Configuration" to "Craftbukkit Tutorial"
    • Check the project name is correct
    • Set "Main class" to org.bukkit.craftbukkit.Main - you should be able to find this item using the search button (it will appear in the list as Main - org.bukkit.craftbukkit)
  6. Move on to the "arguments tab"
    • In "program arguments" put the following:
    •               -nojline
    • If you can afford the craftbukkit server some more memory, put the following in "VM arguments"
    •               -Xmx1024M -Xms512M 
    • For "working directory" click "other", then click "workspace" and select the "run" directory you created before
  7. Click "Run" in the bottom right
What you should see now is the main Eclipse window and a Minecraft server starting up for the first time in the console tab. When it's done preparing spawn, you will be able to type the usual console commands directly into this tab. Give yourself OP. Then load your minecraft client and check you can connect to 127.0.0.1. If you can't then you're probably going to have to tweak your firewall and/or antivirus settings.
When you are done type "stop" from the console. Now we are ready to put our own code in.

Create the plugin

The hello world Java

In the project tree view on the left, right click the "src" folder. Select New->Class. Another wizard will appear. Now there are 3 important things to fill in at this stage.
  • The source folder. This should already be filled in because of how you launched the wizard
  • The package. For this tutorial, set it to com.minecraftiplist.tutorials
  • The name. Set it to PluginTutorial

New class wizard

Those 3 items will determine the name of the file created, and where it gets put. They must be correct otherwise the code we're going to be pasting in will not work. Note the capitalization. The other items in the wizard are irrelevant, they will determine the initial content of the file, which we are going to discard anyway.
Click "Finish". Eclipse will generate a file called PluginTutorial.java, fill it with some template code and open it in the main window. Select all the code in the file and delete it, then replace it with the code below. Click save when you're done. Don't panic if there is an error, we are expecting that....
package com.minecraftiplist.tutorials;

public class PluginTutorial extends JavaPlugin
{
	private final String HELLO_MESSAGE = "Hello world";
	private final String GOODBYE_MESSAGE = "Goodbye world";
	@Override
	public void onEnable ()
	{
		getLogger().info (HELLO_MESSAGE);
	}
	
	@Override
	public void onDisable ()
	{
		getLogger().info (GOODBYE_MESSAGE);
	}
}

Click on the "problems" tab. You should see that there are 5 errors. Clicking on the arrow to the left will expand the errors section so you can see them individually. You can also see red underscores in the source window, indicating where the errors are. Note that these underscores update dynamically as you type, but the "problems" tab is only updated when you save the file.
Eclipse has a "quick fix" feature and I find it most useful to avoid having to type in long-winded "Import" statements. If you right-click on the top error "JavaPlugin cannot be resolved to a type" and then click "Quick Fix...". One of the options is "Import JavaPlugin..." click that then click finish and save the file. You will notice that the error has gone. You may also have noticed a new line of code was inserted automatically:
import org.bukkit.plugin.java.JavaPlugin;

In fact I never type the word "import" into Eclipse, it's just too easy to get wrong or to forget the full name of the thing you are importing. Quick fixes should be used with caution, namely
  • Don't accept a quick fix option if you don't agree with it
  • Don't accept a quick fix option without first understanding what it is going to do
  • Don't assume that just because the error went away, the fix was correct
Notice how all 5 errors went away. Errors 2,3,4 and 5 were all secondary errors caused by the first one. Missing imports should always be fixed first for this reason.

The puglin.yml file

Click on the "src" folder in the project tree and select "New->File". Call the file plugin.yml.
You will see that the new file is opened in another program, eg Notepad, GEdit or whatever. This is rather annoying. To open it in Eclipse, right click on the file in the project tree, and select "Open With->Text Editor". This will cause the file to be opened in Eclipse's own internal plain-text editor, and it will remember that setting.
Fill plugin.yml with the following content
name: Plugin Tutorial
main: com.minecraftiplist.tutorials.PluginTutorial
version: 0.1


The JAR file

Finally, we need to package the contents up into a JAR file for deployment on the server.
  1. Right click on the project in the tree and click "Export"
  2. Under the "Java" folder, locate "JAR File" and click "Next"
  3. Under your project name select "src" and under that select "com.minecraftiplist.tutorials". Deselect any other items on the left
  4. As a check, click "src" and ensure plugin.yml is ticked on the right
  5. As a check, click "com.minecraftiplist.tutorials" and ensure PluginTutorial.java is ticked on the right
  6. Under "Select the export destination" click "Browse" and browse to the "plugins" folder which you will find as a subfolder underneath your project's "run" folder. (CraftBukkit created this when we ran it earlier). For the filename, tutorial.jar will do
  7. Click "Next"
  8. Tick "Save the description of this JAR in the workspace. Save it somewhere under src. Eclipse will save a ".jardesc" file, it means we don't have to run this wizard again

JAR Export Wizard

Take a look inside the JAR file - it's really a zip file with a different extension. You should find the plugin.yml and PluginTutorial.class. The .class file was taken from the bin directory in your project and derived from the .java file. Every time a .java file is saved, Eclipse will automatically update (recompile) the corresponding class file. It is the class file that ultimately "gets run".

Run the code. Modify it while it runs

Back in the Eclipse main window there is a green arrow in the toolbar at the top. That's the "Run" button. Just to the left of that there is a sort of an insect symbol, that's the "Debug" button. As long as your tutorial project is highlighted on the left, hovering over these buttons should pop up the description "Run Craftbukkit Tutorial" or "Debug Craftbukkit Tutorial". If they don't, then something went wrong in the "Run Configurations" section, most likely the configuration managed to latch on to the wrong project somehow. You'll have to go back in there and fix that if that's the case.
Click the run button, and inspect the output on the console tab. You should see two lines that say something like
2013-04-05 11:15:08 [INFO] [Plugin Tutorial] Enabling Plugin Tutorial v0.1
2013-04-05 11:15:08 [INFO] [Plugin Tutorial] Hello world
Type "stop" at the console, and then edit the contents of the hello and goodbye messages in the source. Change the contents of the text only, not anything else, for example:
	private final String HELLO_MESSAGE = "Hola mundo";
	private final String GOODBYE_MESSAGE = "AdiĆ³s mundo";
Now run the program again. Perhaps you are surprised to see the new messages appearing in the console, given that we haven't updated the JAR file? When the program loads from Eclipse, the .class files are loaded from the project "bin" directory, in preference to the .jar file. This is because the bin location takes precedence on the Java classpath. The nice thing about that is it means you don't have to update the JAR file every time you change a line of code. Furthermore the .class files are automatically updated every time you save the .java files, so you really don't have to think about "recompiling" every time you change something. Just remember to re-do the .jar file before you send it to a remote server, or whenever other resources like plugin.yml change.
Stop the server and run it again in "debug mode" by clicking on that insect. Now change the contents of the hello and goodbye messages once again and type "reload" from the console. You will see your code changes took effect instantly, even before the reload occurs the new goodbye message comes out. This feature is known as "hot code replace". It can be very useful and save time, but it can also lead to unexpected results. Running a "reload" from the console after making changes to your code is generally a good idea.
Hot code replace doesn't always work. Try the following while the server is running in debug mode: delete the onDisable method, ie delete the following lines:
	@Override
	public void onDisable ()
	{
		getLogger().info (GOODBYE_MESSAGE);
	}
On saving you will see an error. The safest thing to do here is click "continue" and then type "stop" at the console for a clean shutdown. However you can just use "Terminate" or "Restart" with impunity if you're not that fussy about preserving the integrity of your maps, or other data within your development installation.

Congratulations! You are now all set up for for doing CraftBukkit plugin development in Eclipse. Java beginners are recommended to do Oracle's Hello World tutorial at this point. If you're perfectly happy with the code you've seen so far, skip to part 3 where we are going to create some explosions! If there's any pieces of code that you're not sure of, part 2 gives a detailed breakdown of it all.

Top