How to Use NMS in Bukkit

Though Minecraft is welcoming to various plugins (which you can use to alter your gameplay experience) some elements of the game are shielded from plugin manipulation. Net.Minecraft.Server (NMS) is one of these protected packages, as it contains vital server code for the game. This code comes directly from Minecraft’s developers, Mojang, and isn’t supposed to be accessible to players.

With Bukkit, players can create an abstraction layer around the NMS code. This allows them to develop plug-ins that interact with the server’s code without making direct changes to the codebase that’s essential for playing the game. Think of it like a window that lets you look at the code you want to use in your plugin but also acts as a barrier that prevents you from changing the code directly.

Let’s explore how to use Bukkit with Minecraft’s NMS.

Before You Start – What You Need to Know About Bukkit

Bukkit is an API that allows you to create and use plugins that alter how you experience the multiplayer aspect of Minecraft. At least, it was. The last version of Bukkit came out in 2016, and it has since been discontinued to make way for a different API, named Spigot. While working similarly to Bukkit, it offers better server performance.

So, using Bukkit for your plugins requires you to both play an outdated version of Minecraft and accept the fact that Bukkit isn’t as good as its replacement API. Assuming you’re happy to accept those sacrifices, here are the only things you need:

• Java Development Kit (JDK) 7 or higher, with most recommending JDK 8.

With that, you’re ready to create some plugins.

How to Create Bukkit Plugins for Minecraft

Before you can start using Bukkit to access Minecraft’s NMS, you need to add the API as a dependency, set a main class that allows Bukkit to interact with the plugin you create, and provide Bukkit with the information it needs to load your plugin into the game. Each step requires coding, with the examples that follow coming from RIP Tutorial.

Step 1 – Add Bukkit as a Dependency

In the past, you could add Bukkit as a dependency in Minecraft by downloading the Bukkit.jar file from Bukkit Repository and adding it to your project’s classpath. That option isn’t available anymore because the Repository is no longer accessible.

Thankfully, there’s an alternative method that makes use of your game’s pom.xml file. Open the file and add the following lines:

<repositories>
    <repository>
        <id>spigot-repo</id>
        <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
    </repository>
</repositories>
<dependencies>
    <!--Bukkit API-->
    <dependency>
        <groupId>org.bukkit</groupId>
        <artifactId>bukkit</artifactId>
        <version>{VERSION}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Step 2 – Create Your Plugin’s Main Class

Your plugin needs to be able to create a single instance of its main class, which is used to extend “JavaPlugin” so that it recognizes and allows you to use the plugin when you’re in-game. Think of this main class as the door through which Bukkit can enter to both load and manipulate the plugin. Most give their plugin’s main class the same name as the plugin itself, making it easier to refer to the main class when coding.

The following example code from RIP Tutorial offers an example of a main class for a plugin named “MyPlugin:”

package com.example.myplugin; //{$TopLevelDomain}.{$Domain}.{$PluginName};
import org.bukkit.plugin.java.JavaPlugin;
public final class MyPlugin extends JavaPlugin {
    @Override
    public void onEnable() {
        //Called when the plugin is enabled
        getLogger().info("onEnable has been invoked!");
    }
    @Override
    public void onDisable() {
        //Called when the plugin is disabled
        getLogger().info("onDisable has been invoked!");
    }
}

Accessing Your Plugin from Another Class

You may wish to access your plugin via a different class than the main class you create for it, which could be helpful for accessing several plugins in a single Minecraft game.

To do that, you need to first store an instance of the main class you created using Bukkit so other classes can access it. Again, the following example code comes from RIP Tutorial and uses the “MyPlugin” class name:

public class MyPlugin extends JavaPlugin {
    private static MyPlugin instance; //Effectively final variable containing your plugin's instance
    public MyPlugin(){
        if(MyPlugin.instance != null) { //Unnecessary check but ensures your plugin is only initialized once.
            throw new Error("Plugin already initialized!");
        }
        MyPlugin.instance = this; //A plugin's constructor should only be called once
    }
    public static MyPlugin getInstance(){ //Get's your plugin's instance
        return instance;
    }
    //your other code...
}

Once you have the instance in place, you can access your main class (created via Bukkit) using the “getInstance()” command. Here’s an example of that using RIP Tutorial’s “MyPlugin” main class:

public class MyOtherClass {
    public void doSomethingWithMainClass(){
        MyPlugin.getInstance().getLogger().info("We just used MyPlugin");
    }
}

Step 3 – Create Your plugin.yml file

A plugin.yml file contains vital information about your plugin, meaning it serves as the plugin’s basic configuration file. Without this file, Bukkit won’t have the information it needs to load your plugin into Minecraft, leading to the plugin failing to load and the game likely crashing.

This file should contain the following details:

• Name – This is the name you’ve given to your plugin (i.e., RIP Tutorial’s “MyPlugin”) and it’ll display in log messages and your plugin list.
• Version – Use this field to denote the plugin’s version history, starting with 1.0.0 and going up as you alter or edit the plugin.
• Main – Contains the name of the plugin’s main class, which extends “JavaPlugin”, allowing Bukkit to enter the plugin. In the RIP Tutorial example, this name would be “package com.example.myplugin,” which you can see in the main class code above.
• Description – A basic description of what your plugin does.
• Author – You can have a single author or multiple authors, with the latter being denoted with square brackets and commas as follows – [Author1, Author2, Author3].
• Contributors – You’ll use this section to note anybody who contributed to your plugin, with the formatting being the same as for the “Authors” section.
• Website – If you have a website to plug, or wish to link people to the plugin’s page or GitHub repository, you can enter the URL here.
• API-Version – Enter the version of the Bukkit API that you use here. If you don’t enter an API version, Minecraft will assume that it’s loading a legacy plugin. The plugin may still work, though you’ll see a warning about it being a legacy version printed in your console upon loading.

The following is an example of a plugin.yml file based on the naming conventions used in the RIP Tutorial code used in this article:

name: MyPlugin
version: 1.0.0
main: package com.example.myplugin
description: A test plugin for Minecraft
author: RIP Tutorial
website: https://riptutorial.com/bukkit
api-version: 1.17

Is Bukkit Right for Accessing and Using NMS?

With that, you’ve created a Bukkit dependency, built a main class to serve as Bukkit’s door into the plugin, and have a plugin.yml file that Bukkit can use to see what the plugin does. However, you may not want to do so, as Bukkit is so out of date that you’ll need to run a very old version of Minecraft to use it effectively. Most have already moved on to Sprigot, which mirrors most of what Bukkit did while offering better performance.

If you still want to use Bukkit to access plugins, why did you choose it ahead of more modern APIs? What sorts of plugins do you use to enhance your Minecraft experience? Tell us all about it in the comments section below.