What is a plugin?

Before you write a plugin, it helps to know exactly what one is. On this page you will learn what a server does, where Paper comes from, how plugins differ from mods and datapacks, and what happens inside the server when it loads your plugin. You will also take a first look at a real plugin's code, so you can see its parts before you learn to write them.

The client and the server

When you play Minecraft with friends, two kinds of programs are involved.

• The client is the game you start from the Minecraft launcher. It draws the world, plays sounds, and reads your keyboard and mouse.
• The server is the program that actually runs the world. It decides where every mob walks, which blocks break, what drops, who has which items, and what everyone sees in chat.

The client asks; the server decides. When you click to break a block, your client tells the server "Steve wants to break this stone". The server checks that it is allowed, removes the block, drops the cobblestone, and then tells every nearby client "that stone is gone now". Your client just draws the result.

This is the most important idea on the page: plugins run on the server. Because the server makes every decision, a plugin that runs inside the server can change any decision. It can stop a block from breaking, give a player an item, or send a message, and every client simply shows the result.

What a plugin is

A plugin is a file, ending in .jar, that contains code written in Java. You drop it into the server's plugins folder, start the server, and the server runs your code alongside its own.

Once loaded, a plugin can do three main kinds of things:

• React to things that happen. A player joins, breaks a block, takes damage, opens a chest, chats. Each of these is an event, and your plugin can run code when it happens.
• Add commands. Players type /rules or /home, and your code runs.
• Change the game. Give items, teleport players, spawn mobs, show titles, edit blocks, save data, and much more.

That is all a plugin really is: code that the server runs when something happens or when someone types a command. Everything else (shops, minigames, anti-cheat) is built from those pieces.

A first look inside a plugin

Here is a small but complete plugin. It greets every player who joins and adds a /rules command. You do not need to understand the code yet; the next chapters teach every word. For now, just spot its three parts.

Two words will come up in the notes. A class is one Java file that holds a piece of your plugin, like a toolbox for one job. A method is one named action inside a class, like onEnable, that the server can run. The next chapters teach both properly.

Part 1: plugin.yml, a small text file that introduces the plugin to the server:

11name: TourPlugin22version: '1.0.0'33main: com.example.whatisaplugintour.TourPlugin44api-version: '26.3'55description: Greets players and adds a /rules command.

Part 2: the main class, the code the server starts. It sets everything up:

1package com.example.whatisaplugintour;2 3import org.bukkit.plugin.java.JavaPlugin;4 15public final class TourPlugin extends JavaPlugin {6 7    @Override28    public void onEnable() {39        getServer().getPluginManager().registerEvents(new GreetingListener(), this);410        registerCommand("rules", "Shows the server rules", new RulesCommand());511        getLogger().info("TourPlugin is enabled!");12    }13 14    @Override615    public void onDisable() {16        getLogger().info("TourPlugin is disabled. Bye!");17    }18}

Part 3: the features. A listener that reacts to players joining, and a command:

1package com.example.whatisaplugintour;2 3import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7 18public final class GreetingListener implements Listener {9 210    @EventHandler311    public void onJoin(PlayerJoinEvent event) {12        Player player = event.getPlayer();413        player.sendRichMessage("<green>Welcome! <gray>Type <yellow>/rules</yellow> to read the server rules.");14    }15}

1package com.example.whatisaplugintour;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import org.bukkit.command.CommandSender;6 17public final class RulesCommand implements BasicCommand {8 9    @Override210    public void execute(CommandSourceStack source, String[] args) {311        CommandSender sender = source.getSender();412        sender.sendRichMessage("<gold><bold>Server rules");13        sender.sendRichMessage("<gray>1. Be kind to other players.");14        sender.sendRichMessage("<gray>2. No griefing or stealing.");15        sender.sendRichMessage("<gray>3. Have fun!");16    }17}

This is what a player sees on a server running that plugin, first when joining and then after typing /rules:

Notice what is not there: no world, no mobs, no blocks, no networking code. The server already does all of that. Your plugin only adds the parts that make your server different, which is why a useful plugin can be this small.

Paper, Spigot, Bukkit and friends

Mojang, the company that makes Minecraft, gives away an official server program. People call it the vanilla server, because it is the plain flavor. The vanilla server cannot load plugins at all.

So the community built their own servers that can. Each new one was made by taking the previous one and improving it. Making a copy of a project and continuing it separately is called a fork.

Why Paper?

Paper is the most popular plugin server, it is fast, it is updated quickly after each Minecraft release, and its API is the biggest and most modern. Almost every plugin written for Bukkit or Spigot also runs on Paper, so you lose nothing by choosing it.

For a long time Paper copied every change Spigot made and added its own on top. Then Paper made a hard fork: it stopped copying from Spigot and now develops completely on its own. In plain words, Paper is no longer "Spigot plus extras"; it is its own project. For you, that means one thing: code that uses Paper's newer API does not run on Spigot. Since this guide uses that newer API (because it is much easier and safer), your plugins will need Paper or a fork of Paper, like Purpur.

Plugins, mods, datapacks and resource packs

Plugins are not the only way to change Minecraft. Here is how the four common ways compare:

The biggest advantage of plugins is the second row: players join with the normal game. Nobody has to download anything, install a mod loader or match your mod list. That is why almost every public server with custom features uses plugins.

Plugins and the others also work together. A plugin can send players a resource pack, so a "Magic Wand" item can have its own texture, and a server can use datapacks and plugins at the same time.

What plugins can do

Nearly everything you have seen on a big server is a plugin, or several plugins working together. A few examples, with what players see and the chapter that teaches it:

Welcome messages and titles (Events and listeners, Titles and boss bars):

Commands (Commands):

Custom items with names, descriptions and abilities (Items and ItemStacks):

Menus that players click (Building GUI menus):

Minigames with timers and boss bars (The scheduler, Scoreboards):

Economies, protection and anti-cheat. A coins system is a plugin that stores a number for every player (Saving player data). Spawn protection is a plugin that cancels block breaking near spawn (Canceling events). An anti-cheat is a plugin that watches movement events and flags impossible ones.

How a server loads plugins

Every time the server starts, it goes through the same steps. Knowing them helps you read the console and understand why your plugin did (or did not) start.

1. The server looks in the plugins folder

   It finds every .jar file in plugins. Files in subfolders are ignored.

2. It reads each plugin.yml

   Every plugin jar must contain a plugin.yml. The server reads the name, version, main class and api-version, and any other plugins this one needs. If the file is missing or broken, that plugin is skipped with an error.

3. It creates each main class

   Using the main: line, the server finds your main class inside the jar and creates it. Then it calls the plugin's onLoad method (most plugins leave it empty). The console shows "Loading server plugin".

4. It prepares the worlds

   The server loads the overworld, the nether and the end.

5. It enables the plugins

   For each plugin, the server calls onEnable. This is where your plugin registers its listeners and commands. The console shows "Enabling". Plugins that depend on other plugins are enabled after them.

6. Players can join

   The console prints "Done". From now on, your listeners and commands run whenever their events happen.

Here is what that looks like in the console of a Paper 26.3 server with our tour plugin installed (some lines left out):

[14:02:05 INFO]: [PluginInitializerManager] Initializing plugins...[14:02:05 INFO]: [PluginInitializerManager] Initialized 1 plugin[14:02:05 INFO]: [PluginInitializerManager] Bukkit plugins (1): - TourPlugin (1.0.0)[14:02:08 INFO]: Starting minecraft server version 26.3[14:02:08 INFO]: [TourPlugin] Loading server plugin TourPlugin v1.0.0[14:02:08 INFO]: Preparing level "world"[14:02:09 INFO]: Done preparing level "world" (0.912s)[14:02:09 INFO]: [TourPlugin] Enabling TourPlugin v1.0.0[14:02:09 INFO]: [TourPlugin] TourPlugin is enabled![14:02:10 INFO]: Done (4.871s)! For help, type "help"

The line TourPlugin is enabled! is the one our onEnable printed. When the server stops, the steps run backward: every plugin's onDisable runs ("Disabling TourPlugin v1.0.0", then our "Bye!" line), and then the worlds are saved.

What a jar is, and what compiling means

You write plugins as text: files ending in .java, full of words like public and sendRichMessage. This text is called source code. It is written for humans to read.

The server cannot run that text directly. First, a program called the Java compiler reads your source code, checks it for mistakes, and translates it into .class files. These contain bytecode: compact instructions for the JVM (the Java Virtual Machine, the engine that runs Java programs, including the Minecraft server itself). That translation step is called compiling.

A jar file ("Java archive") is just a zip file with a different ending. It holds the compiled classes and any other files the plugin needs. The tour plugin's jar looks like this inside:

You will never build a jar by hand. A build tool called Gradle does it with one click: it downloads the Paper API, runs the compiler, and zips the result. Your toolbox introduces Gradle, and Your first plugin builds a real jar.

Compiling has a big bonus: the compiler catches many mistakes before your plugin ever reaches a server. If you misspell sendRichMessage, the compiler refuses to build the jar and tells you the exact line. That is much better than a plugin that crashes while players are online.

Java the language and Minecraft: Java Edition

The word "Java" means two different things, and beginners mix them up all the time:

• Java, the programming language, made by Sun Microsystems in the 1990s and now run by Oracle and a big open community. Banks, phones and websites use it. You install it as a "JDK" (you will do that in Your toolbox).
• Minecraft: Java Edition, the PC version of Minecraft. It is called that because it is written in the Java language, to tell it apart from Bedrock Edition (consoles, phones and the Windows store version), which is written in C++.

Paper is a Java Edition server, and Paper plugins are written in the Java language. Bedrock players cannot join a Java server on their own (a separate tool called Geyser can let them in, but that is outside this guide). And no, JavaScript is not Java either: it is a different language with a confusingly similar name.

9@Override10public void execute(CommandSourceStack source, String[] args) {11    CommandSender sender = source.getSender();12    sender.sendRichMessage("<gold><bold>Server rules");13    sender.sendRichMessage("<gray>1. Be kind to other players.");14    sender.sendRichMessage("<gray>2. No griefing or stealing.");115    sender.sendRichMessage("<gray>3. No hacked clients or x-ray.");216    sender.sendRichMessage("<gray>4. Have fun!");17}

Recap

• The client draws the game; the server runs the world and makes every decision. Plugins run on the server, so players install nothing.
• A plugin is a jar of compiled Java code. It reacts to events, adds commands and changes the game.
• Every plugin has a plugin.yml and a main class that extends JavaPlugin; its onEnable runs when the server starts.
• Bukkit came first, Spigot forked it, Paper forked Spigot and is now a hard fork with a much bigger API. Paper-API plugins run on Paper and its forks, not on Spigot.
• Mods add truly new content but need installs; datapacks and resource packs change data and looks; plugins change server behavior.
• Compiling turns .java source code into .class bytecode, and the build packs it with plugin.yml into a jar.
• Java the language is not Minecraft: Java Edition, and neither is JavaScript.

Quick quiz

Next steps

• Your toolbox: install Java 25 and IntelliJ IDEA, and meet Gradle.
• Your first plugin: write, run and see a plugin like the tour plugin in your own game.