Welcome

This guide takes you from "I have never written code" to building your own Minecraft server plugins for Paper 26.3. This first page shows you how the guide works, what you will build, and how to get help when you are stuck, so you can spend the rest of your time actually making plugins.

Who this guide is for

You are in the right place if you play Minecraft, you are curious how servers do the things they do (custom commands, shops, minigames, welcome titles), and you want to make those things yourself.

You do not need any of these:

• Coding experience. Every word like "method", "class" or "compile" is explained the first time it appears, on every page. You never have to remember where you read it first.
• Math. Plugins use the kind of math you already do in Minecraft: adding coins, counting down seconds, checking if a number is bigger than another.
• A paid program or server. Everything you install is free, and you test your plugins on a server that runs on your own PC.

What you do need is a Windows PC, about an hour at a time, and the patience to read error messages instead of panicking at them. The guide teaches that last part too.

The guide teaches two things at once: the Java programming language, and the Paper server software that runs your plugins. It never teaches Java just for its own sake. Every Java idea comes with the place you will meet it in real plugin code, because the goal is plugins, not school exercises.

What you will build

By the end of the guide you will have built eight complete plugins in the Projects part, plus many smaller ones along the way. Here is a taste of what players will see on your server.

A welcome kit that greets new players with a big title and a sound (Project: Welcome kit):

Commands with cooldowns, so /heal cannot be spammed (Project: /heal and /feed):

A magic wand: a custom item with its own name, description and right-click spell (Project: Magic wand):

A chest menu shop that players click instead of typing commands (Project: Shop menu):

And a live scoreboard on the side of the screen that updates every second (Project: Live sidebar scoreboard):

None of this needs players to install anything. They join your server with the normal Minecraft game, and your plugin does the rest. What is a plugin? explains why.

The learning path

The guide is split into parts. You can see all of them in the menu on the left side of every page.

The suggested order

Read Start here from top to bottom, then Java basics, then Paper essentials. After each chapter, do its challenge in the Practice Arena. Start the projects once you have read the Paper chapters they need. This is the slowest path, and the one that sticks best.

The fast path

If you cannot wait to see something happen in the game, that is fine too. Read Start here up to Your first plugin, get your plugin running, and then jump straight to Events and listeners and Commands. Whenever a piece of Java confuses you, open the Java basics chapter about it (the glossary and hover text, below, tell you which one). Many people learn best this way: build first, understand second.

How the pages work

Every page has the same building blocks. Here they are, so nothing surprises you later.

Code blocks with notes

This is a complete, real plugin. It says hello to every player who joins. You are not expected to understand it yet; just look at how the block works.

11package com.example.welcomehello;2 3import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7import org.bukkit.plugin.java.JavaPlugin;8 29public final class HelloPlugin extends JavaPlugin implements Listener {10 11    @Override312    public void onEnable() {413        getServer().getPluginManager().registerEvents(this, this);514        getLogger().info("HelloPlugin is ready to greet players!");15    }16 17    @EventHandler618    public void onJoin(PlayerJoinEvent event) {19        Player player = event.getPlayer();720        player.sendRichMessage("<gold>Hello there! <gray>This server runs my first plugin.");21    }22}

Things to try on that block:

• Hover any word in the code. A tooltip explains what it is, for example what a Player is or what sendRichMessage does. This works on every code block in the guide, for every word, including Java keywords like public and void.
• Read the notes under the code. Each note number matches a marked line.
• Copy the code with the Copy button in the block's header.
• Open in Compile Lab loads the whole plugin into the Compile Lab, where you can change it and compile it against the real Paper 26.3 code, right in your browser.

When Steve joins a server running that plugin, this is what he sees in chat. Previews like this show you what players will see, drawn the way Minecraft draws it:

Runnable examples

Plain Java examples (programs that are not plugins) have a green run arrow. Press it and the program runs; its output appears in a terminal under the code.

11void main() {22    IO.println("[WelcomeKit] Enabling WelcomeKit v1.0.0");3    IO.println("[WelcomeKit] Loaded 3 starter items.");4    IO.println("[WelcomeKit] Ready to greet new players!");5}

You will use these runnable examples a lot in the Java basics part, where you learn the language one small program at a time. In live mode (below) you can also press Edit, change the code, and run your own version.

Terms, exercises, quizzes and progress

• Dotted words are glossary terms. Hover one for a one-line explanation. The full list is in the Glossary.
• Callout boxes add tips, warnings and Minecraft comparisons. "Under the hood" boxes are optional; skip them on a first read.
• Exercises give you a small task. Try it first, then open a hint if you are stuck, and only then the solution.
• Quizzes at the end of each chapter check that the important ideas landed. Click an answer to see why it is right or wrong.
• Mark this page as done at the bottom of each chapter tracks your progress. The bar at the top of the screen fills up as you go. Your progress is saved in your browser.
• Search with Ctrl+K finds any page, heading or term.

Live mode and file mode

The guide is a website that lives in a folder on your PC. You can open it in two ways, and the badge in the top bar tells you which one you are using.

File mode is perfect for reading. Switch to live mode once Java 25 is installed. Start Guide.cmd starts a small helper program that runs only on your own PC (nobody on the internet can reach it), opens the guide in your browser, and runs code when you press Run. Close its black window to stop it.

The tools

The Tools part of the guide has helpers that explain, classify and check things for you. You do not need them on day one, but remember they exist. Each one is useful at a particular moment:

The Practice Arena

The Practice Arena is where you turn reading into skill. It is built around the Plugin Path: a row of small, guided challenges that teach you to code plugins, starting with "say hello when a player joins" and growing step by step. Each challenge tells you the goal, shows what players should see, gives you a mini-lesson and exact steps, and then checks your code with real tests. A few Java warm-ups are there too, but even those are pieces of real plugins, like the math inside a cooldown.

Chapters that have matching challenges show a "Practice this" link at the bottom, right above the "Mark this page as done" button.

How to get unstuck

Everyone gets stuck. Professional developers get stuck every day; the difference is that they have a routine for it. Here is yours:

1. Read the error, all of it

   The first red line usually says exactly what is wrong and on which line. Error messages look scary, but they are trying to help. The guide teaches you to read them in How code reads and Null, exceptions and stack traces.

2. Ask the Error Doctor

   Paste the error into the Error Doctor. It recognizes the common build, startup and runtime errors and tells you what to change. The Error encyclopedia lists them all.

3. Check the FAQ and the glossary

   The FAQ answers the questions every beginner asks ("why does my listener not fire?"), and the Glossary explains every term.

4. Change one thing at a time

   If you change five things and it still fails, you learn nothing. Change one, run again, and compare. Debugging like a pro turns this into a calm routine.

5. Ask a person, with a good question

   The PaperMC community (linked from docs.papermc.io) is friendly to people who show their work. A good question gets a fast answer.

A good question includes what you wanted, what happened instead, the full error, the code, and your versions. Something like this:

1I want: players get a welcome message when they join.2What happens: nothing in chat, no error in the console.3What I tried: I added getLogger().info in onJoin, and that line never prints.4Versions: Paper 26.3, Java 25.5My code: (paste the listener class and the main class here)

Notice the third line: it shows you already tried something. In this case it also nearly answers itself: if a line inside your join code never prints, Paper was probably never told to run that code. You will learn how to tell Paper on the events page.

1void main() {2    IO.println("[ParkourPro] Enabling ParkourPro v0.1.0");13    IO.println("[ParkourPro] Built by Jace.");4    IO.println("[ParkourPro] Loaded 1 course.");5    IO.println("[ParkourPro] Ready for the first run!");6}

17@EventHandler18public void onJoin(PlayerJoinEvent event) {19    Player player = event.getPlayer();120    player.sendRichMessage("<aqua>Welcome to Jace's server!");221    player.sendRichMessage("<yellow>Every block here was placed by hand.");22}

Recap

• The guide teaches Java and Paper together, and every Java idea is tied back to real plugin code.
• Read Start here first. Then follow the suggested order, or take the fast path: first plugin first, Java when you need it.
• Hover any word in a code block for an explanation, read the numbered notes, and use the green arrow to run plain Java examples.
• File mode shows recorded output; live mode (Start Guide.cmd) runs code, compiles plugins and checks practice challenges for real.
• The Practice Arena's Plugin Path gives you a guided plugin challenge after each chapter.
• When stuck: read the whole error, try the Error Doctor and the FAQ, change one thing at a time, then ask with a good question.

Quick quiz

Next steps

• What is a plugin?: servers, clients, Paper, and what a plugin really is.
• Your toolbox: install Java 25, IntelliJ IDEA and learn what Gradle does.
• Your first plugin: if you are taking the fast path, this is your target.