Skip to main content
Paper is a high-performance Minecraft server that extends the Bukkit API with additional features and improvements. This guide will help you create your first Paper plugin.

​
Prerequisites

  • Java Development Kit (JDK) 21 or higher
  • A Java IDE (IntelliJ IDEA recommended)
  • Basic knowledge of Java programming

​
Project Setup

1

Add Paper API Dependency

Configure your build tool to include the Paper API dependency.
<repositories>
    <repository>
        <id>papermc</id>
        <url>https://repo.papermc.io/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.papermc.paper</groupId>
        <artifactId>paper-api</artifactId>
        <version>1.21.11-R0.1-SNAPSHOT</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
The provided scope (Maven) or compileOnly (Gradle) is used because the Paper server already includes the API at runtime.
2

Create Main Plugin Class

Create a class that extends JavaPlugin. This is the entry point for your plugin.
package com.example.myplugin;

import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getLogger().info("MyPlugin has been enabled!");
    }

    @Override
    public void onDisable() {
        getLogger().info("MyPlugin has been disabled!");
    }
}
The onEnable() method is called when your plugin is loaded, and onDisable() is called when it’s unloaded.
3

Create paper-plugin.yml

Create a paper-plugin.yml file in your src/main/resources directory to describe your plugin.
name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: '1.21'
description: My first Paper plugin
author: YourName
See the paper-plugin.yml reference for all available options.
4

Build and Test

Build your plugin JAR file and place it in the plugins folder of your Paper server.
mvn clean package
Your compiled plugin will be in the target (Maven) or build/libs (Gradle) directory.

​
Key Classes and Interfaces

​
JavaPlugin

The JavaPlugin class (package: org.bukkit.plugin.java.JavaPlugin) is the base class for all plugins. It provides:
  • Lifecycle methods: onLoad(), onEnable(), onDisable()
  • Server access: getServer() returns the Server instance
  • Data folder: getDataFolder() returns your plugin’s data directory
  • Logger: getLogger() returns a logger for your plugin
  • Configuration: getConfig(), saveConfig(), reloadConfig()
  • Metadata: getPluginMeta() returns plugin information

​
PluginMeta

The PluginMeta interface (package: io.papermc.paper.plugin.configuration.PluginMeta) provides access to plugin metadata: 
PluginMeta meta = getPluginMeta();
String name = meta.getName();
String version = meta.getVersion();
List<String> authors = meta.getAuthors();
String mainClass = meta.getMainClass();

​
Static Plugin Access

You can get a reference to your plugin instance from anywhere in your code: 
MyPlugin plugin = JavaPlugin.getPlugin(MyPlugin.class);
Do not call getPlugin() from static initializers, as this will throw an IllegalStateException.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us