Your first plugin, step by step

On this page you will make a real Paper plugin from nothing: get a project, write a few lines of Java, start a Paper 26.3 test server with one click, join it from Minecraft, and see your plugin greet you in chat. Then you will build the plugin into a jar file you could put on any server.

You do not need to understand every word yet. This page is about getting something working and seeing the whole journey once. Every piece you touch here has its own chapter later, and the last section maps each piece to the page that explains it.

What you will build

Your first plugin does two small things. When the server starts, it writes a line in the server's console, the text window where the server reports what it is doing. When a player joins, it sends that player a welcome message in chat:

The gold and gray lines come from your plugin. The yellow line is Minecraft's normal join message, which the server sends last, after every plugin has had its turn. Small, but it uses the same pieces as every big plugin: a main class the server starts, a listener that reacts to something players do, and a jar file that carries it all.

Step 1: get a project

A plugin starts life as a project: a folder with your code, a few settings files, and a recipe that tells Gradle how to turn your code into a plugin. Gradle is the build tool: it downloads the Paper code your plugin needs and packs everything into a jar. Nobody types those settings files from scratch; you start from a ready-made project. Pick one of these ways:

$ cd C:\Users\jacec\IdeaProjects\paper-templates$ .\new-plugin.cmd -Name FirstPlugin -Open

Step 2: open the project in IntelliJ

1. Open the folder

   Start IntelliJ IDEA and choose File›Open... (or Open on the welcome screen). Select the project folder itself, the one that contains build.gradle.kts, and click OK. Do not pick a folder above it or a single file inside it.

   Open File or Project

   ⌂ Hide path

   C:\Users\you\IdeaProjects\first-plugin

   C:\

   Users

   you

   Desktop

   Documents

   IdeaProjects

   Gfirst-plugin1

   paper-templates

   Downloads

   Drag and drop a file into the space above to quickly locate it

   ? OK2 Cancel

2. Trust the project

   IntelliJ asks whether you trust this project, because opening a Gradle project runs its build script. You made it (or downloaded it from this guide), so click Trust Project.

    

   !

   Trust and Open Project 'first-plugin'?

   IntelliJ IDEA provides features that may automatically execute code contained in this project, for example, while importing it or building it.

   If you don't trust the source, preview the project in safe mode.

   Trust projects in C:\Users\you\IdeaProjects1

   Trust Project2 Preview in Safe Mode Don't Open

3. Wait for Gradle

   The first time, Gradle downloads itself and the Paper API, the code library that lets your plugin talk to the server. A progress bar runs at the bottom of the window. This can take a few minutes on the first project and a few seconds after that. Until it finishes, IntelliJ may underline code in red because it does not know the Paper classes yet. That is normal; wait for the bar to disappear.

4. Find your files

   The project tree on the left shows your files. Click the small arrows to open src, main, java, and the folders inside, until you see FirstPlugin.java. Also open resources to find plugin.yml.

   Project+

   first-pluginC:\Users\you\IdeaProjects\first-plugin

   .gradle

   .idea

   .run

   build

   gradle

   run

   src

   main

   java

   com.example.firstplugin

   CFirstPlugin1

   resources

   Yplugin.yml2

   G.gitignore

   Kbuild.gradle.kts3

   Pgradle.properties

   >gradlew

   >gradlew.bat

   Ksettings.gradle.kts

   External Libraries

   Scratches and Consoles

These are the only two files you will change on this page:

The folder com/example/firstplugin may show up in IntelliJ as one line, com.example.firstplugin. That is the same thing, written with dots: a package, which is Java's word for a folder of code. Anatomy of a plugin project goes through every other file in the project.

Step 3: write the main class

Every plugin has exactly one main class. A class is a block of Java code with a name; the main class is the one Paper creates when your plugin starts. Double-click FirstPlugin.java to open it, and make it look exactly like this. If you used the starter download, it already does.

11package com.example.firstplugin;2 23import org.bukkit.plugin.java.JavaPlugin;4 35public final class FirstPlugin extends JavaPlugin {6 57    @Override68    public void onEnable() {79        getLogger().info("Hello! FirstPlugin is up and running.");10    }11 12    @Override813    public void onDisable() {914        getLogger().info("Goodbye! FirstPlugin is shutting down.");15    }16}

Notice what is missing: you never call onEnable yourself, and there is no "start here" line. Paper is the program that runs. Your plugin is a set of methods that Paper calls at the right moments. That is the biggest difference between plugin code and the small Java programs in How code reads.

Now open plugin.yml. This small file is how Paper finds your main class inside the jar:

11name: FirstPlugin22version: '1.0.0'33main: com.example.firstplugin.FirstPlugin44api-version: '26.3'55description: My first Paper plugin.

plugin.yml explained covers every other field you can put here.

Step 4: start a test server

You do not need to download or set up a Minecraft server. The project includes a run configuration called Run Paper Server: a saved button that builds your plugin, downloads Paper 26.3, and starts a server on your own PC with your plugin already loaded.

1. Pick Run Paper Server

   At the top of the IntelliJ window there is a drop-down list next to a green triangle. Choose Run Paper Server in it.

   FPfirst-plugin GRun Paper Server 1 2 3

   Current File

   GRun Paper Server

   GBuild Plugin Jar

   Edit Configurations...

2. Press the green Run button

   A Run window opens at the bottom. The first time, the server is downloaded first, so give it a minute. Later starts take a few seconds.

3. Watch for your line

   The console fills with text. Look for the lines that start with [FirstPlugin]. When you see Done, the server is ready.

This is what the first run looks like (many lines are left out where you see ...):

> Task :compileJava> Task :processResources> Task :classes> Task :jar> Task :runServerFetching latest Paper build for version 26.3...Latest build for 26.3 is 143.Downloading Paper 26.3 build 143...Starting Paper...[14:02:03 INFO]: [bootstrap] Loading Paper 26.3-143-main@ff3655a (2026-10-02T14:13:32Z) for Minecraft 26.3[14:02:03 INFO]: [PluginInitializerManager] Bukkit plugins (1): - FirstPlugin (1.0.0)...[14:02:07 WARN]: You have used the Paper command line EULA agreement flag....[14:02:08 INFO]: Starting Minecraft server on *:25565[14:02:08 INFO]: [FirstPlugin] Loading server plugin FirstPlugin v1.0.0[14:02:09 INFO]: Preparing level "world"...[14:02:11 INFO]: [FirstPlugin] Enabling FirstPlugin v1.0.0[14:02:11 INFO]: [FirstPlugin] Hello! FirstPlugin is up and running....[14:02:12 INFO]: Done (9.299s)! For help, type "help"

Read it from the top. The > Task lines are Gradle: it compiles your code (turns your Java text into a form the computer can run) and packs it into a jar, the single file a plugin is shipped in. Then it downloads Paper and starts it. Paper lists the plugins it found, says it is loading yours, builds the world, and then enables it. "Enabling" is the moment Paper calls your onEnable method, which is why your "Hello!" line comes right after it.

A few lines look scary but are normal on a test server:

• The EULA lines. Every Minecraft server must accept Mojang's EULA (the rules for running a server). The test server accepts it with a setting in the build file, and Paper reminds you of that with these yellow warnings.
• WARNING: A terminally deprecated method in sun.misc.Unsafe has been called. This comes from a library inside Paper, not from your plugin. Ignore it.

The Run window is also a server console you can type into. Click in it, type plugins and press Enter. The server lists your plugin, in green because it is enabled:

$ plugins[14:02:20 INFO]: Server Plugins (1):[14:02:20 INFO]: Bukkit Plugins:[14:02:20 INFO]:  - FirstPlugin

Commands typed in the console have no slash in front. In the game you would type /plugins.

Step 5: join your server

Leave the server running. Start Minecraft Java Edition 26.3, click Multiplayer, then Direct Connection, type localhost as the server address, and click Join Server. localhost means "this computer".

You arrive in a fresh world. Nothing special happens yet, because so far your plugin only writes to the console. Back in IntelliJ the console shows you joining:

[14:03:41 INFO]: Steve[/127.0.0.1:52134] logged in with entity id 87 at ([world]8.5, 64.0, 8.5)[14:03:41 INFO]: Steve joined the game

Step 6: greet players with a listener

Now make the plugin do something players can see. When something happens in the game, such as a player joining, Paper creates an event and offers it to every plugin that wants it. A listener is a class that says "tell me about these events". You need two changes: a new listener class, and one line in the main class that hands the listener to Paper.

Create the listener class

1. Make a new class

   In the project tree, right-click the com.example.firstplugin package and choose New›Java Class. Type JoinListener and press Enter. IntelliJ creates JoinListener.java next to FirstPlugin.java, with the package line already filled in.

2. Type the code

   Make the file look exactly like the code below. When IntelliJ shows a name in red, click it and press Alt+Enter to add the missing import line. If it offers several classes with the same name, pick the one from org.bukkit.

11package com.example.firstplugin;2 23import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7 38public final class JoinListener implements Listener {9 410    @EventHandler511    public void onJoin(PlayerJoinEvent event) {612        Player player = event.getPlayer();713        player.sendRichMessage("<gold>Welcome to the server, " + player.getName() + "!");814        player.sendRichMessage("<gray>This message comes from your very first plugin.");15    }16}

Gluing the name into the message is safe here because Minecraft names only contain letters, digits and underscores. For text that players type themselves, such as chat, you will use placeholders instead; MiniMessage shows how.

Register the listener

A listener does nothing until Paper knows about it. Open FirstPlugin.java and add one line at the start of onEnable:

1package com.example.firstplugin;2 3import org.bukkit.plugin.java.JavaPlugin;4 5public final class FirstPlugin extends JavaPlugin {6 7    @Override8    public void onEnable() {19        getServer().getPluginManager().registerEvents(new JoinListener(), this);210        getLogger().info("Hello! FirstPlugin is up and running.");11    }12 13    @Override14    public void onDisable() {15        getLogger().info("Goodbye! FirstPlugin is shutting down.");16    }17}

Try it

Your server is still running the old version of the plugin. Java code cannot be swapped into a running server safely, so you restart it:

1. Click in the console, type stop and press Enter. The server saves the world and shuts down. Your onDisable line appears on the way out: [FirstPlugin] Goodbye! FirstPlugin is shutting down.
2. Press the green Run button again. Gradle compiles your new code and builds a new jar before the server starts, so you never need to build by hand while testing.
3. In Minecraft, join localhost again.

That is your plugin talking. Only you see the gold and gray lines, because the code sends them to player, the player who joined.

The edit-run loop

What you just did is how every plugin developer works, all day: change the code, run the server, test in the game, stop the server, and go again.

Try one round now. Change <gold> to <aqua> in JoinListener, stop the server, run it, and join again. The welcome line is now aqua. A few habits make the loop smooth:

• Stop with stop. Typing stop saves the world cleanly. The red square Stop button in IntelliJ also works, but it can end the server abruptly, like pulling a plug, so use stop when you can.
• Stay in the game. When the server stops, Minecraft shows "Connection Lost". Click Back to Server List; once the server is up again, join from the list.
• Read the console after every start. If your code has a problem, the console says so in red. Fixing it right away is much easier than guessing later.
• Never use reload commands to load new code. Stop and start the server instead. Build, install and test explains why.

Step 7: build the plugin jar

Run Paper Server builds a jar for its own use. When you want to give the plugin to a real server, build it on purpose. Pick Build Plugin Jar in the run drop-down and press the green Run button. Or open the terminal in IntelliJ (View›Tool Windows›Terminal) and type:

$ .\gradlew.bat build> Task :compileJava> Task :processResources> Task :classes> Task :jar> Task :assemble> Task :compileTestJava NO-SOURCE> Task :processTestResources NO-SOURCE> Task :testClasses UP-TO-DATE> Task :test NO-SOURCE> Task :check UP-TO-DATE> Task :buildBUILD SUCCESSFUL in 9s3 actionable tasks: 3 executed

BUILD SUCCESSFUL means the jar is ready. You find it in the project's build\libs folder. In IntelliJ, open build and then libs in the project tree; in File Explorer, right-click the jar in IntelliJ and choose Open In›Explorer.

The jar's name is the project name plus the version: first-plugin-start-1.0.0.jar for the starter download, or first-plugin-1.0.0.jar if you used new-plugin.cmd. That single file is your whole plugin. Copy it into the plugins folder of any Paper 26.3 server, restart that server, and your welcome message works there too. Build, install and test covers installing in detail.

When something goes wrong

Almost every first-plugin problem is one of these. The console nearly always tells you which, so read it from the first red line.

For any other message, paste it into the Error Doctor, or look it up in the Error encyclopedia.

What you just did

You touched almost every part of plugin development in one page. Here is each piece in plain words, and where to learn it properly:

You can download the finished plugin from this page to compare it with yours, or open it in the Compile Lab to edit and compile it in your browser.

1Player player = event.getPlayer();2player.sendRichMessage("<aqua><bold>Welcome to Skyreach, " + player.getName() + "!");3player.sendRichMessage("<gray>This message comes from your very first plugin.");4player.sendRichMessage("<yellow>Type /help if you are lost.");

10@EventHandler11public void onJoin(PlayerJoinEvent event) {12    Player player = event.getPlayer();113    int online = player.getServer().getOnlinePlayers().size();14    player.sendRichMessage("<gold>Welcome to the server, " + player.getName() + "!");215    player.sendRichMessage("<gray>Players online right now: <green>" + online);16    player.sendRichMessage("<aqua>Have fun and be nice!");17}

Recap

• A plugin project is a folder with your Java code, plugin.yml and a Gradle build recipe. Start from the starter download or new-plugin.cmd.
• The main class extends JavaPlugin. Paper calls its onEnable when the plugin starts and onDisable when it stops.
• plugin.yml tells Paper the plugin's name, version, main class and api-version. The main line must match your class exactly.
• A listener class implements Listener, has @EventHandler methods, and must be registered in onEnable.
• Run Paper Server builds your plugin and starts a test server; join it with localhost. Stop it with stop and run again after every change.
• Build Plugin Jar (or .\gradlew.bat build) puts the finished jar in build\libs.

Quick quiz

Next steps

• Anatomy of a plugin project: what every other file in your project does.
• Build, install and test: put your jar on a real server and read the console like a pro.
• How code reads: start learning the Java behind the lines you just typed.
• Practice Arena: small challenges to try once you know a bit more.