(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.

Summary

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:

• Coding with Minecraft [Article]
• Instant Minecraft Designs – Building a Tudor-style house [Article]
• CryENGINE 3: Breaking Ground with Sandbox [Article]