Welcome to the Minecraft plugin development series! So let’s dive right in!

In this episode, we’re going to cover:

  • The two sides of Minecraft — Difference between the client, server, plugins and mods.
  • Behind Minecraft plugins — What is Bukkit, what is CraftBukkit, what is Spigot and what is Paper. The difference between API vs Server and what is NMS and packets. How Minecraft plugins work.
  • The Heartbeat and TPS — How plugins inject their logic into the server and how many milliseconds your code has before the server starts to lag.
  • Java — How good you need to be in Java in order to code Minecraft plugins.


The two sides of Minecraft

Client side (what you see)

The program you run on your computer. It renders graphics, listens to your keyboard and sends input to the server.

Server side (the hidden part)

The program running in the background, enabling clients to connect to a single place and play together. Runs logic such as mob movement.

Minecraft client is on the left, whereas server files are on the right.

(Minecraft client is on the left, whereas server files are on the right.)


Plugins vs mods


They can use existing game assets and create new behavior for monsters, they can add commands, messages etc. but can’t add new sounds or graphics.

Example: A plugin can create a custom inventory using the Chest inventory that is already found in the client


Mods can add new features into the game but every player trying to connect to a modded server must install the same mod first.

Example: A mod can create a custom inventory with custom shape and textures not found in the original game

Illustration of Minecraft plugins and Minecraft mods.

(Left: Example of Boss plugin, right: Example of Alex’s Mobs mod)


The biggest drawback with mods is that every player needs to download, install and keep updating the same mods as the server uses. All of the most successful Minecraft networks rely on just plugins, and this is what our tutorial will be covering because they are the easiest to make.

And, since Minecraft 1.14, resource packs made it easy to add graphics, textures and even sounds with just plugins alone.


Minecraft server modifications

The native server provided by Mojang does not support plugins.

To fix this, a group of people came together and formed hey0 mod, which was an early server mod (not to be confused with mods described above, as it doesn’t force clients to download anything) with plugin support.

In 2011 it got abandoned and another group of people came together to start Bukkit. It was completely rewritten and brought extensive options for developers (at that time) to create amazing plugins such as WorldEdit, LWC, Portals and others.

A few years later, another group of people formed Spigot, which extended Bukkit and added more performance tweaks and configurability options. After Bukkit developers dissolved in 2014 shortly after Microsoft’s purchase of Mojang, the company behind Minecraft, Spigot got so much more popular because they decided to keep going.

Bukkit is illegal to redistribute

Bukkit received a DCMA letter by one of his contributors, Wesley Wolfe, who opposed the acquisition and it is since then not legal to redistribute the compiled .jar file of the Bukkit server, nor all of its forks. That’s why you need to download BuildTools, a small app made by Spigot’s developer md_5 to compile Spigot on your computer locally.

Finally, there was a third popular group of people who started the Paper project (formerly called PaperSpigot, although they get salty if you mention it), extending Spigot, which further improved on Spigot adding more API methods for developers and further performance optimizations.

Paper “fixed” the complicated steps around downloading and compiling Spigot by providing a single .jar which does all the steps for you. Hence we’re going to be using Paper for or Minecraft server to test our plugins on. I still recommend you use Spigot API against developing your plugin so that even servers using Spigot and not Paper can use it (according to bStats.org, 26% of MC servers still use Spigot).

To conclude, Paper builds on top of Spigot which builds on top of Bukkit which build on top of the original server. We will be using Spigot API to make our plugins against, and use Paper to test them.


API vs server

What is an API?

API are “empty maps” (i.e. Bukkit API, Spigot API, Paper API) that plugin developers can use. They give instruction how the server part (CraftBukkit) should look like.

Here is an example of how the Bukkit API looks like.

The getIP() method in Bukkit.

The example above is from a class “Server”. This class is called an “interface” because it is empty and defines what functions must be placed in the full version of the class. In Java we say that the methods are defined in the class that is implementing the interface.

Bukkit is implemented by CraftBukkit, Spigot API is implemented by Spigot Server etc. Classes in the server part, CraftBukkit, are prefixed with “Craft”, such as a class Zombie in Bukkit API is called CraftZombie.

Please use Bukkit (or Spigot) API whenever you can over CraftBukkit. The reason we have an API is to make your plugin break less on Minecraft updates since the server code tends to change a lot.


What is NMS?

In Java, different program parts are placed in different folders. Such as you have a folder called “mails” on your Desktop, in which you have another folder called “work” in which there is a “presentation” folder. The entire 3 folders for a structure called mails.work.presentation, which is called a “package” in Java.

Each program is defined in its own, unique package, to avoid conflicts and allow developers to use multiple libraries at the same time.

The Mojang’s native server part is placed inside a package called “net.minecraft.server”, shortly NMS, hence the name. NMS is simply an abbreviation for the package where the original server is placed. Bukkit is placed in the “org.bukkit” package and CraftBukkit in the “org.bukkit.craftbukkit” package.

However, there’s something special about NMS. Not everything can be achieved by Bukkit API, some things such as pathfinders and custom AI need to be adjusted by accessing NMS.

The biggest drawback of using NMS is compatibility and usability. Since the native server is obfuscated (Mojang wanted to make it hard for people to understand and steal its property!), a lot of the obfuscated method names change on each Minecraft update. That means you’d likely need to rewrite your code for each Minecraft version. Plus. it’s fairly difficult to guess what most methods do since their original names were changed intentionally to garbage such as “a()”, “b()” etc.

Here is what happens when you call Player.sendMessage() using the Bukkit API. Note that the CraftBukkit actually does handle your call, and passes it further down to the original server where the “magic happens”.

What are packets?

Minecraft server and client communicate with one another using small packages, called packets. Each packet contains several data compressed together in a byte array, such as chat message packet contains the sender of the message and the content itself.

That is an oversimplification, and the actual packets got more and more complicated with more recent Minecraft versions, that is why the API provides such an easy and reliable way to create powerful plugins without having to spend hours tampering and deciphering packets.

How CraftBukkit and NMS works in Minecraft.


The Heartbeat (The Ticking Mechanism)

To synchronize the game, server constantly listens for and sends packets back to players.

This process, “ticking”, happens 20 times per second, called “TPS” (ticks per second). One second has 1,000 milliseconds, divided by 20 equals 50 milliseconds per tick! (0.05s)

When your code takes longer than 0.05s to run, the entire server must wait before the next tick, experiencing lag.

“Async” or parallel programming doesn’t solve the issue of poor code. It will create another “circle” of poor code which can cause serious desync or “out of order” issues.

Here is the entire ticking cycle, illustrated:

The heartbeat of a Minecraft server.


Because poorly coded plugins can crash the entire server and corrupt data.

Plugins are written in Java, and many people skip it….

Many people jump right into plugins, watch Youtube tutorials of poor quality and wonder why their server lags and they lose motivation.

You must understand the code to produce safe and efficient code.

If you have never coded anything before, read this:


Make Minecraft Plugins Fast Without Developers Or Spending Months On Learning Code

Most Minecraft tutorials are outdated, disorganized and teach poor coding standards.

People spend months reading books or taking courses and they are still not self-sufficient and still need to rely on developers or limited plugins.

To fix this, we created a training specifically focused on learning Minecraft plugin development. It’s called Project Orion™

Here’s what’s inside Project Orion™:

  • 7-week training program
  • A full Java + Spigot/Paper plugin development guide
  • No previous coding experience needed
  • Focus on high coding standards and explaining WHY the code works
  • 2x/week live coaching calls
  • 30-day money back guarantee

Click here to learn more about Project Orion™!


I hope you enjoyed this tutorial – let me know if there’s anything which I should have explained in the comments.

We did not start to code just yet, because it’s important you understand the different terms when you are coding and using Google to find articles on SpigotMC using them.

We will be coding our Minecraft plugin using Spigot API in the next episode!