Learning the Bukkit API

Exclusive offer: get 50% off this eBook here
Building Minecraft Server Modifications

Building Minecraft Server Modifications — Save 50%

Discover how to program your own server plugins and augment your Minecraft server with Bukkit with this book and ebook

$17.99    $9.00
by Cody M. Sommer | September 2013 | Games Open Source

In this article, by Cody M. Sommer, the author of Building Minecraft Server
, we will learn Bukkit by learning how to read its API documentation.

You may be wondering what the difference is between Bukkit and CraftBukkit. Many people use the two words interchangeably. However, they are in fact different files. In this article you will be introduced to the Bukkit API and learn what it allows you to accomplish through programming plugins for a CraftBukkit server. By the end of this article you will most likely have numerous ideas for plugins that you will eventually be able to create yourself. This article will cover the following in more detail:

  • Understanding the purpose of an API
  • Finding documentation of the Bukkit API
  • Navigating through JavaDocs to find specific information

(For more resources related to this topic, see here.)

Introduction to APIs

API is an acronym for Application Programming Interface. An API helps to control how various software components are used. CraftBukkit includes the Minecraft code in a form that is easier for developers to utilize in creating plugins. CraftBukkit has a lot of code that we do not need to access for creating plugins. It also includes code that we should not use as it could cause the server to become unstable. Bukkit provides us with the classes that we can use to properly modify the game. Basically, Bukkit acts as a bridge between our plugin and the CraftBukkit server. The Bukkit team adds new classes, methods, and so on, to the API as new features develop in Minecraft, but the preexisting code rarely changes. This ensures that our Bukkit plugins will still function correctly months or even years from now. Even though new versions of Minecraft/CraftBukkit are being released. For example, if Minecraft were to change how an entity's health is handled, we would notice no difference.

The CraftBukkit jar would account for this change and when our plugin calls the getHealth() method it would function exactly as it had before the update. Another example of how great the Bukkit API is would be the addition of new Minecraft features, such as new items. Let's say that we've created a plugin that gives food an expiration date. To see if an item is food we'd use the isEdible() method. Minecraft continues to create new items. If one of these new items was Pumpkin Bread, CraftBukkit would flag that type of item as edible and would therefore be given an expiration date by our plugin. A year from now, any new food items would still be given expiration dates without us needing to change any of our code.

The Bukkit API documentation

Documentation of the Bukkit API can be found at jd.bukkit.org. You will see several links regarding the status of the build (Recommended, Beta, or Development) and the form of the documentation (JavaDocs or Doxygen). If you are new to reading documentation of Java code, you may prefer Doxygen. It includes useful features, such as a search bar and collapsible lists and diagrams. If you are already familiar with reading documentation then you may be more comfortable using the JavaDocs. In the following screenshot, both API docs are side by side for comparison. The traditional JavaDocs are on the left and the Doxygen documentation is on the right.

The following figure is the inheritance diagram for LivingEntity from the Doxygen site. Take note that on the site you are able to zoom in and click a box to go to that class.

I encourage you to browse through each documentation to decide which one you prefer. They are simply displayed differently. When using the Doxygen API docs, you will have to navigate to the bukkit package to see a list of classes and packages. It can be found navigating to the following links within the left column: Bukkit | Classes | Class List | org | bukkit, as shown in the following screenshot:

Navigating the Bukkit API Documentation

We can look through this documentation to get a general idea of what we are able to modify on a CraftBukkit server. Server-side plugins are different from client-side mods. We are limited with what we are able to modify in the game using server-side plugins. For example, we cannot create a new type of block but we can make lava blocks rain from the sky. We cannot make zombies look and sound like dinosaurs but we can put a zombie on a leash, change its name to Fido and have it not burn in the daylight. For the most part you cannot change the visual aspect of the game, but you can change how it functions. This ensures that everyone who connects to the server with a standard Minecraft client will have the same experience.

For some more examples on what we can do, we will view various pages of the API docs. You will notice that the classes are organized into several packages. These packages help group similar classes together. For example, a Cow , a Player, and a Zombie are all types of entities and thus can be found in the org.bukkit.entity package. So if I were to say that the World interface can be found at org.bukkit. World then you will know that the World class can be found within the bukkit package, which is inside the org package. Knowing this will help you find the classes that you are looking for. The search bar near the top right corner of the Doxygen site is another way to quickly find a class.

Let's look at the World class and see what it has to offer. The classes are listed in alphabetical order so we will find World near the end of the list within the bukkit package. Once you click on the World class link, all of its methods will be displayed in the main column of the site under the header Public Member Functions as shown in the following screenshot:

A World object is an entire world on your server. By default, a Minecraft server has multiple worlds including the main world, nether, and end. CraftBukkit even allows you to add additional worlds. The methods that are listed in the World class apply to the specific world object. For example, the Bukkit.getWorlds() method will give you a list of all the worlds that are on the server; each one is unique. Therefore if you were to call the getName() method on the first world it may return world while calling the same method on the second world may return world_nether.


In this article we learnt about what the reader can do by programming plugins. We also learnt the difference between Bukkit and CraftBukkit and how they relate to Minecraft. The term acronym API was also explained.

Resources for Article :

Further resources on this subject:

Building Minecraft Server Modifications Discover how to program your own server plugins and augment your Minecraft server with Bukkit with this book and ebook
Published: September 2013
eBook Price: $17.99
Book Price: $29.99
See more
Select your format and quantity:

About the Author :

Cody M. Sommer

Cody M. Sommer has always been interested in computers. In his free time he would take them apart just to learn more about how they worked. He eventually began building computers for himself and others. Cody would spend many hours a day on his computer whether he was playing games, browsing the internet, or learning more about how they work. It wasn't until his college career that he was introduced to software development. During his senior year of high school, Cody began taking courses in Computer Science at The College at Brockport: State University of New York. The college primarily taught the Java language due to its vast presence in modern software.

After a year or so, Cody had a solid understanding of Java and various programming techniques. He was anxious to put these to use. His first out-of-school project consisted of programming a solitaire type card game to play itself and print out statistics on the results. This is when he discovered that the game he had been trying to win for the past few months only dealt a "winning" deck about once in every 1000 games. Being able to control a computer to complete a task fascinated Cody. Programming the card game took less than one week so he had to find another project; preferably one that would be challenging, keep him busy, and not be completed for a long time. This is when he discovered the Bukkit project.

Both Minecraft and the Bukkit API are programmed in Java which Cody knew very well. On the Bukkit forums were countless server administrators just waiting for a developer to come along to create their idea. All that was required of him to begin creating Bukkit plugins was to learn the Bukkit API. Cody first dissected a few public projects to study their structure and get an idea of how these server plugins were programmed. Through self-teaching and with the aid of more experienced developers, he eventually managed to create his first project, called Turnstile. This plugin required that players on a Minecraft server pay in-game money to enter specific areas, such as subway stations. He developed several plugins his first few months. Most of these were requested by other people. However, two of his favorite projects, PhatLoots and TextPlayer, were his original ideas.

Cody enjoyed pushing the game to its limits. The creation of TextPlayer is one example of this. The plugin allowed Minecraft players or server admins to always be connected to the servers that they play on. This was all done through e-mail and text messages. People could be alerted on their phone of events that occurred on the server. These events included a friend logging on, a player vandalizing the game world, or a player entering their house or property. The plugin grew to allow people to communicate back to the server which also allowed admins and moderators to run server commands from their cell phone.

These various projects aided Cody in learning Java. Most of his programming knowledge came from school but some things are not fully understood until they are put to use in a real-life scenario. Depending on their complexity, Bukkit plugins can even help developers practice advance programming techniques, such as recursion, algorithms, and data structures. Through timing reports, a developer can improve their code by finding slowly executing blocks of code. Some of the most important steps of the software development life cycle are emphasized in Cody's Bukkit plugins. These steps include bug fixes, addition of new features, and writing code that is prepared for future changes in the project.

Two years later, Cody graduated with a Bachelor's degree and is still active within the Bukkit community. He has over 10 public plugins, works as a private developer for some of the top Minecraft Servers in the world, and creates private plugins upon request. His projects are still pushing Minecraft servers to their limits of what they are able to accomplish.

Cody occasionally tutors developers to write efficient code and help them tackle challenging tasks. One of his goals is to help grow the Bukkit community with new developers as he feels that writing code for something that interests you is a great way to practice programming and encourage you to learn more.

Books From Packt

Instant Minecraft: Pi Edition Coding How-to [Instant]
Instant Minecraft: Pi Edition Coding How-to [Instant]

Instant Minecraft Designs How-to [Instant]
Instant Minecraft Designs How-to [Instant]

Instant Raspberry Pi Gaming [Instant]
Instant Raspberry Pi Gaming [Instant]

 CryENGINE 3 Game Development: Beginner's Guide
CryENGINE 3 Game Development: Beginner's Guide

GameSalad Beginner’s Guide
GameSalad Beginner’s Guide

Instant Raspberry Pi Gaming [Instant]
Instant Raspberry Pi Gaming [Instant]

Game Maker 8 Cookbook
Game Maker 8 Cookbook

Learning ROS for Robotics Programming
Learning ROS for Robotics Programming

Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software