Skip to content

How to make a Paper plugin in 2026

A Paper plugin is a Java jar that a Paper server loads from its plugins folder. To make one for Minecraft 26.3, install JDK 25, create a Gradle project with io.papermc.paper:paper-api as a compileOnly dependency, write a main class that extends JavaPlugin, name it in plugin.yml, and build the jar with ./gradlew build. Players join with an unmodded game, so they don’t install anything.

Last checked on 3 November 2026. The project below is Linen’s Paper 26.3 template, with its repository list shortened to one line. In that form it built with ./gradlew build that day, and plugin.yml in the jar had the version filled in. The server start in step 7 wasn’t run for this page.

Plugin (Paper, Spigot, Bukkit, Purpur) Mod (Fabric, NeoForge, Forge)
Runs on The server only The client, the server or both
Written against The server API: Bukkit, Spigot or Paper’s The game’s own code, with the loader’s API and Mixin
Good for Commands, server rules, minigames, economy, chat, protection New blocks, items, mobs, textures, rendering
Players install Nothing The mod and its loader, for client-side content

If you need new blocks or items with their own textures, read How to make a Minecraft mod instead. The longer comparison is in Fabric vs NeoForge vs Forge.

  • JDK 25 for 26.x. Paper’s docs: “Paper requires at least Java 25 to run.” Older Minecraft versions need older Javas. See Which Java version.
  • An IDE with Gradle support. Paper’s docs are written for IntelliJ IDEA: “As the Paper team primarily uses IntelliJ IDEA, this guide will be focused on that IDE.”
  • No Paper download. The API comes from PaperMC’s Maven repository, and the run-paper Gradle plugin downloads a test server for you.

The tested project’s build.gradle.kts, in Gradle’s Kotlin language:

plugins {
java
// Downloads Paper from PaperMC and starts a local test server with this plugin: ./gradlew runServer
id("xyz.jpenilla.run-paper") version "3.1.0"
}
group = "net.example.guideplugin"
version = "1.0.0"
repositories {
mavenCentral()
maven("https://repo.papermc.io/repository/maven-public/")
}
dependencies {
// The server provides the API at runtime, so it is never packed into the plugin jar.
compileOnly("io.papermc.paper:paper-api:26.3.build.238-stable")
}
java {
// Minecraft 26.3 servers run on Java 25: compile with a Java 25 toolchain.
toolchain.languageVersion = JavaLanguageVersion.of(25)
}
tasks.withType<JavaCompile>().configureEach {
options.encoding = "UTF-8"
options.release = 25
}
tasks.processResources {
val props = mapOf("version" to project.version.toString())
inputs.properties(props)
filesMatching("plugin.yml") {
expand(props)
}
}
tasks.runServer {
minecraftVersion("26.3")
}
  • compileOnly, because the server already has the API. Paper’s docs use compileOnly("io.papermc.paper:paper-api:26.3.build.+"). The template pins one build so every build is the same.
  • From 26.1 Paper’s API versions look like 26.3.build.238-stable. Paper’s docs: “Before 26.1 (1.21.11 and below), the version string format used was {VERSION}-R0.1-SNAPSHOT.”
  • processResources writes the project version into plugin.yml.

The Gradle wrapper is 9.8.1, and gradle/gradle-daemon-jvm.properties says toolchainVersion=25, so Gradle runs on Java 25 too.

src/main/resources/plugin.yml tells the server what your plugin is:

name: "GuidePlugin"
version: '${version}'
main: net.example.guideplugin.GuidePlugin
description: "Guide Plugin, a server plugin."
author: "Linen"
api-version: '26.3'
commands:
guideplugin:
description: "Shows that Guide Plugin is running."
usage: /<command>
  • main is “the class that extends JavaPlugin and is the entry point to your plugin”, by its full name.
  • api-version is “the version of the Paper API that your plugin is using”. Servers older than it refuse to load the plugin. Without it, the plugin loads as a legacy plugin with a warning.
  • commands lists the commands, and the code connects to them in onEnable.

Paper also has its own paper-plugin.yml format. Paper’s docs call it “experimental and may be subject to change”, and it “will not act as a drop-in replacement for plugin.yml”. A plugin.yml plugin that uses only the Bukkit API also runs on Spigot and Purpur.

Paper’s docs: “Each plugin has a main class that is specified in the plugin’s plugin.yml file. This class must extend JavaPlugin, and is the entry point for the plugin.” The template’s main class only wires things together:

public final class GuidePlugin extends JavaPlugin {
@Override
public void onEnable() {
// Writes config.yml to the plugin's folder on the first start, then reads it.
saveDefaultConfig();
final GuidePluginConfig config = GuidePluginConfig.from(getConfig());
getCommand("guideplugin").setExecutor(new GuidePluginCommand());
getServer().getPluginManager().registerEvents(new JoinListener(config), this);
}
@Override
public void onDisable() {
}
}

onEnable runs when the server enables the plugin: “When a plugin is enabled, its onEnable method is called.” getCommand works on Paper, Spigot, Bukkit and Purpur. The template’s own comment notes that Paper 26.3 marks it obsolete in favour of Paper’s command registration, which Spigot and Bukkit don’t have.

A class that implements CommandExecutor. onCommand returns true when the command was handled:

public final class GuidePluginCommand implements CommandExecutor {
@Override
public boolean onCommand(final CommandSender sender, final Command command, final String label, final String[] args) {
sender.sendMessage("Guide Plugin is running on " + sender.getServer().getVersion() + ".");
return true;
}
}

A class that implements Listener, with an @EventHandler method per event. This one greets each player who joins:

public final class JoinListener implements Listener {
private final GuidePluginConfig config;
public JoinListener(final GuidePluginConfig config) {
this.config = config;
}
@EventHandler
public void onJoin(final PlayerJoinEvent event) {
final Player player = event.getPlayer();
player.sendMessage(config.greetingFor(player.getName()));
}
}

registerEvents(listener, plugin) in onEnable turns it on.

Put the defaults in src/main/resources/config.yml. The template’s:

# Sent to each player who joins. {player} is the player's name.
greeting: "&7Welcome, &f{player}&7!"

saveDefaultConfig() copies it to the plugin’s folder on the server the first time, and getConfig() reads it. The template reads it into a record once:

public record GuidePluginConfig(String greeting) {
public static GuidePluginConfig from(final FileConfiguration file) {
return new GuidePluginConfig(file.getString("greeting", "Welcome, {player}!"));
}
public String greetingFor(final String player) {
// Minecraft marks colours in text with the section sign; config.yml uses & because it is easy to type.
return greeting.replaceAll("&([0-9a-fk-orA-FK-OR])", "\u00A7$1").replace("{player}", player);
}
}

The second argument of getString is the default when the key is missing.

Terminal window
./gradlew build

The test build made build/libs/guideplugin-1.0.0.jar in 45 seconds the first time. Put the jar in a Paper 26.3 server’s plugins folder and start the server. Paper’s docs: “Plugins are loaded from the plugins folder in the server directory.”

Or let run-paper do it:

Terminal window
./gradlew runServer

run-paper “will automatically download a Paper server and run it for you”, with your plugin’s jar (run-task README). Join it from your game at localhost and run /guideplugin.

The code above runs on all four, because it only uses the Bukkit API. What changes is the API dependency you compile against:

Server Dependency Repository
Paper (1.17 and newer) io.papermc.paper:paper-api https://repo.papermc.io/repository/maven-public/
Spigot org.spigotmc:spigot-api https://hub.spigotmc.org/nexus/content/groups/public/
Purpur org.purpurmc.purpur:purpur-api https://repo.purpurmc.org/snapshots

Paper is “a Minecraft game server based on Spigot” that “extends and improves the Bukkit and Spigot APIs” (papermc.io). Compile against Spigot’s API if the plugin must run on Spigot. Compile against Paper’s if you use Paper’s own additions, which Spigot doesn’t have. Older versions and Bukkit are in Set up a Paper plugin.

  • New mod writes this project for Paper, Spigot, Bukkit or Purpur on any version from 1.12.2 to 26.x, with the right API dependency, Java toolchain and api-version, and lists every file before writing it.
  • Linen installs the Java version the project needs.
  • The template keeps one class per job: commands in command/, listeners in listener/, settings in config/.

Checked on 3 November 2026.