Anatomy of a plugin project

A plugin project has a dozen files and folders, and only a few of them are yours to edit. On this page you will learn what every one of them does, read the three Gradle files line by line, see how your code and resources end up inside the jar, and rename a plugin without breaking it.

This page uses the project from Your first plugin. If you have it open in IntelliJ, keep it next to this page and click through the folders as you read.

The whole project at a glance

Here is the first-plugin project after you have run the test server and built the jar once. Hover a name to see what it is for.

That looks like a lot, but it sorts into three groups:

settings.gradle.kts

Gradle reads three files before it builds anything. The first is settings.gradle.kts. The .kts ending means it is written in Kotlin, another programming language. You do not need to learn Kotlin; the build files use a handful of patterns that you can read like a form.

11plugins {22    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"3}4 35rootProject.name = "first-plugin"

gradle.properties

This file holds simple name=value settings that the build file reads. Keeping them here means the values you change most often sit in one short, easy file.

11group=com.example22version=1.0.033minecraftVersion=26.344paperVersion=26.3.build.142-beta55org.gradle.jvmargs=-Xmx2G -Dfile.encoding=UTF-8

build.gradle.kts

This is the build recipe, the most important of the three. Read it top to bottom, one block at a time. Each block is a name followed by braces { } with settings inside.

1plugins {12    java23    id("xyz.jpenilla.run-paper") version "3.1.0"4}5 36val minecraftVersion: String by project47val paperVersion: String by project8 59repositories {610    mavenCentral()711    maven("https://repo.papermc.io/repository/maven-public/")12}13 14dependencies {815    compileOnly("io.papermc.paper:paper-api:$paperVersion")16}17 18java {919    toolchain.languageVersion = JavaLanguageVersion.of(25)20}21 22tasks {23    compileJava {1024        options.encoding = Charsets.UTF_8.name()25    }26 1127    runServer {1228        minecraftVersion(minecraftVersion)1329        jvmArgs("-Xms2G", "-Xmx2G", "-Dcom.mojang.eula.agree=true")30    }31}

Why compileOnly?

Your code uses classes like JavaPlugin and Player, so the compiler needs the Paper API to check your code. But every Paper server already contains the whole API. If Gradle packed the API into your jar as well, your 5 KB plugin would grow to many megabytes, and the server would find two copies of the same classes, which causes strange errors.

compileOnly means exactly that: "use this library while compiling, but do not put it in the jar". Libraries the server does not have are added differently; the Gradle and Maven reference covers that.

Warnings you may see

With Gradle 9.8, a build may end with the lines "Deprecated Gradle features were used in this build, making it incompatible with Gradle 10". If you add --warning-mode all to the command, Gradle explains that the val ... by project style (the two lines near the top of build.gradle.kts) will be removed in Gradle 10. These are warnings, not errors: the build still says BUILD SUCCESSFUL, and your jar is fine.

The Gradle wrapper

You never installed Gradle, yet it runs. That is the job of the Gradle wrapper: gradlew.bat (Windows), gradlew (macOS and Linux) and the gradle/wrapper folder. The first time you build, the wrapper downloads exactly the Gradle version the project asks for and keeps it in your user folder for later. Everyone who opens the project gets the same Gradle, so "it works on my PC" problems are rare.

1distributionBase=GRADLE_USER_HOME2distributionPath=wrapper/dists13distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.0-bin.zip4networkTimeout=100005retries=06retryBackOffMs=5007validateDistributionUrl=true8zipStoreBase=GRADLE_USER_HOME9zipStorePath=wrapper/dists

When you type .\gradlew.bat build in a terminal, you are asking the wrapper to run Gradle's build task. The Build Plugin Jar button does the same thing for you.

src/main/java and packages

All your Java code lives under src/main/java, sorted into packages. A package is a folder of classes with a dotted name, and each dot in the name is one more folder:

The first line of every Java file says which package it belongs to, and it must match the folder the file is in:

1package com.example.firstplugin;

Why does Java bother? Because a class's full name is its package plus its class name: com.example.firstplugin.FirstPlugin. That full name is what you write after main: in plugin.yml, and it is how Paper finds your class inside the jar. Hundreds of plugins have a class called Main or MyListener; the package keeps yours apart from theirs, the way coordinates keep two identical houses apart.

Naming your package

Package names are written as a website address turned around: example.com becomes com.example, then you add your plugin's name. You do not need to own a website. Common choices:

• dev.yourname.pluginname, for example dev.jace.homes.
• io.github.yourname.pluginname, if you have a GitHub account with that name.
• com.example.pluginname, fine for learning and examples (this guide uses it), but pick a real one before you share a plugin.

The rules: all lowercase, letters and digits only, no dashes or spaces, and no part may start with a digit. dev.jace.my-plugin is not allowed; write dev.jace.myplugin. Class names, on the other hand, start with a capital letter: HomesPlugin, JoinListener.

When you want a new class, right-click the package in IntelliJ and choose New›Java Class. IntelliJ puts the file in the right folder and writes the package line for you. For more on packages and the import lines that go with them, see Packages, imports and visibility.

src/main/resources

Everything in src/main/resources is copied into the jar exactly as it is, at the top level of the jar. Two files commonly live here:

• plugin.yml: required. Paper looks for it at the top of every plugin jar. If it is missing or in the wrong folder, the server ignores your jar.
• config.yml: optional. The default settings you ship with the plugin, which server owners can change.

To see the journey of a resource, here is a small plugin that ships a config.yml and reads its welcome message from it. First the file in src/main/resources:

11welcome-message: '<gold>Welcome! <gray>This text comes from config.yml.'

And the main class that uses it:

1package com.example.projectanatomyconfig;2 3import org.bukkit.event.EventHandler;4import org.bukkit.event.Listener;5import org.bukkit.event.player.PlayerJoinEvent;6import org.bukkit.plugin.java.JavaPlugin;7 18public final class ConfigWelcomePlugin extends JavaPlugin implements Listener {9 10    @Override11    public void onEnable() {212        saveDefaultConfig();313        getServer().getPluginManager().registerEvents(this, this);414        getLogger().info("Welcome message: " + getConfig().getString("welcome-message"));15    }16 17    @EventHandler18    public void onJoin(PlayerJoinEvent event) {519        String message = getConfig().getString("welcome-message", "<green>Welcome!");20        event.getPlayer().sendRichMessage(message);21    }22}

Build this plugin, open the jar (a jar is a zip file, so any zip tool can open it, or use the jar tool that comes with Java), and you see your classes in their package folders, with the two resource files at the top:

$ jar tf build\libs\project-anatomy-config-1.0.0.jarMETA-INF/META-INF/MANIFEST.MFcom/com/example/com/example/projectanatomyconfig/com/example/projectanatomyconfig/ConfigWelcomePlugin.classconfig.ymlplugin.yml

When the server starts the plugin, saveDefaultConfig() creates the plugin's data folder, a folder named after the plugin inside the server's plugins folder, and copies config.yml into it. On the test server that is run\plugins\ConfigWelcome\config.yml. The console confirms it read the file:

[14:06:02 INFO]: [ConfigWelcome] Enabling ConfigWelcome v1.0.0[14:06:02 INFO]: [ConfigWelcome] Welcome message: <gold>Welcome! <gray>This text comes from config.yml.

Notice the two copies: the one in src/main/resources is the default you ship, and the one in the data folder is the server owner's. After the first start, editing the file in src does not change the test server's copy; delete run\plugins\ConfigWelcome\config.yml to get the new default. Configuration files goes much further.

The build and run folders

build/ holds everything Gradle makes: compiled classes, copied resources, reports, and the jar in build/libs. run/ is the test server: Paper itself, the worlds, server.properties, logs, and your plugins' data folders. Run Paper Server loads your jar straight from build/libs, so you will not find it in run/plugins.

Both folders are made by tools from your source files, so they are not part of your project's "real" content:

• Deleting build/ is always safe. The next build remakes it. The Gradle task clean does exactly that.
• Deleting run/ resets the test server. Paper is downloaded again (or taken from a cache) and you get a brand-new world. Handy when a test world is a mess; just remember your builds in that world go with it.
• Neither is saved with Git. When you put your project on GitHub, you share the recipe, not the cake. The .gitignore file lists what Git should skip:

1.gradle/12build/23run/4out/35.idea/46*.iml7.kotlin/

Git and GitHub for plugin developers explains Git itself.

Gradle or Maven

Gradle is not the only build tool. Many plugins, and the IntelliJ Minecraft Development wizard, use Maven instead. Both do the same job: download the Paper API, compile, and pack a jar. Only the build files differ. This guide uses Gradle everywhere, but you will meet Maven projects online, so here is the same plugin both ways.

1<?xml version="1.0" encoding="UTF-8"?>2<project xmlns="http://maven.apache.org/POM/4.0.0"3         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"4         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">5    <modelVersion>4.0.0</modelVersion>6 17    <groupId>com.example</groupId>28    <artifactId>first-plugin</artifactId>9    <version>1.0.0</version>10    <packaging>jar</packaging>11 12    <properties>313        <java.version>25</java.version>14        <maven.compiler.release>${java.version}</maven.compiler.release>15        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>16    </properties>17 418    <repositories>19        <repository>20            <id>papermc-repo</id>21            <url>https://repo.papermc.io/repository/maven-public/</url>22        </repository>23    </repositories>24 25    <dependencies>26        <dependency>27            <groupId>io.papermc.paper</groupId>28            <artifactId>paper-api</artifactId>29            <version>26.3.build.142-beta</version>530            <scope>provided</scope>31        </dependency>32    </dependencies>33 34    <build>35        <plugins>36            <plugin>37                <groupId>org.apache.maven.plugins</groupId>638                <artifactId>maven-compiler-plugin</artifactId>39                <version>3.15.0</version>40            </plugin>41        </plugins>42    </build>43</project>

The src folder is identical in both. That is the good news: if you find a Maven plugin online, its Java code works the same way, and you can move it into a Gradle project by copying the src folder and adding its dependencies to build.gradle.kts.

Renaming a plugin safely

Sooner or later you will want a better name than FirstPlugin. A plugin's name appears in several places, and they must stay in step. Here is everything that carries a name, using a rename to Greeter as the example:

Let IntelliJ do the Java part. Renaming by hand misses places; IntelliJ's rename tool, Shift+F6, changes the name everywhere it is used, renames the file, and moves folders for packages. It does not touch plugin.yml reliably, so you update that file yourself.

Here is what happens when you rename the class inside the file but not the file itself. The class is public, so Java insists that the file name matches:

11public final class GreeterPlugin {2}

1package com.example.greeter;2 3import org.bukkit.plugin.java.JavaPlugin;4 5public final class GreeterPlugin extends JavaPlugin {

1name: Greeter2version: '1.0.0'3main: com.example.greeter.GreeterPlugin4api-version: '26.3'5description: My first Paper plugin. It greets players when they join.

Recap

• You edit src/ every day, the build files now and then, and never the generated folders (build/, run/, .gradle/, .idea/).
• settings.gradle.kts names the project; gradle.properties holds the versions; build.gradle.kts is the recipe.
• The Paper API is compileOnly (Maven: provided) because every server already has it.
• The Gradle wrapper (gradlew.bat) downloads the right Gradle for you.
• Packages are folders with dotted, lowercase names, and the package line must match the folder.
• Resources are copied into the jar unchanged; plugin.yml must be in src/main/resources.
• To rename a plugin, change the plugin.yml name, the class, the package and the main: line together.

Quick quiz

Next steps

• Build, install and test: build the jar, install it on a real server and read the console.
• plugin.yml explained: every field the file can have.
• Gradle and Maven reference: more tasks, libraries and settings.