How to Set Up Your First Java Plugin Development Environment

Before You Write a Single Line of Code

The hardest part of Minecraft Java plugin development is not the code, it is getting the environment configured correctly the first time. A proper minecraft java plugin development setup includes a JDK, an IDE, a build tool, the Paper API as a dependency, and a local test server. Skip any of these and you will waste hours troubleshooting issues that have nothing to do with your plugin logic.

This guide targets Paper 1.21+ with Java 21, which is the current standard as of 2026.

Step 1, Install JDK 21

You need the Java Development Kit (not just the runtime). Download one of these:

• Eclipse Adoptium (Temurin), adoptium.net, the most popular open-source distribution.
• Amazon Corretto, aws.amazon.com/corretto, well-maintained, LTS support.
• Oracle JDK, free for development under the current license, but Adoptium is simpler.

After installation, verify from a terminal:

java -version
javac -version

Both should report version 21 or higher. If javac is not found, your PATH is not set correctly, search for "add Java to PATH" for your OS.

Step 2, Install an IDE

You can technically write Java in Notepad, but an IDE provides autocompletion, error highlighting, debugging, and build integration. For your first project, use IntelliJ IDEA Community Edition, it is free, powerful, and has the best Gradle/Maven support. See our full comparison in Best Free IDEs for Minecraft Plugin Development.

Download it from jetbrains.com/idea and install with default settings. On first launch, select the "New Project" wizard, we will use it in the next step.

Step 3, Create a Gradle Project

Gradle is the build tool that manages dependencies and compiles your plugin into a jar. In IntelliJ:

1. Click New Project.
2. Set the name (e.g., MyFirstPlugin), the language to Java, and the build system to Gradle.
3. Set the JDK to version 21 (the one you installed in Step 1).
4. Choose Groovy as the Gradle DSL (Kotlin DSL works too, but Groovy has more community examples).
5. Set the GroupId to something like com.yourname.myfirstplugin.
6. Click Create.

IntelliJ will generate the project structure. Open build.gradle and add the Paper API repository and dependency:

repositories {
    mavenCentral()
    maven {
        name = "papermc"
        url = "https://repo.papermc.io/repository/maven-public/"
    }
}

dependencies {
    compileOnly "io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT"
}

Click the Gradle sync button (elephant icon) to download the Paper API. This gives you access to the entire server API with full autocompletion.

Step 4, Write Your Main Class

Create a new Java class at src/main/java/com/yourname/myfirstplugin/MyFirstPlugin.java:

package com.yourname.myfirstplugin;

import org.bukkit.plugin.java.JavaPlugin;

public class MyFirstPlugin extends JavaPlugin {

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

    @Override
    public void onDisable() {
        getLogger().info("MyFirstPlugin has been disabled!");
    }
}

Step 5, Create plugin.yml

Create the file src/main/resources/plugin.yml:

name: MyFirstPlugin
version: 1.0.0
main: com.yourname.myfirstplugin.MyFirstPlugin
api-version: "1.21"
description: My first Paper plugin
author: YourName

This file tells the server how to load your plugin. The main field must match your class's fully qualified name exactly.

Step 6, Build the Jar

Run the Gradle build task. In IntelliJ, open the Gradle panel on the right, navigate to Tasks → build → build, and double-click it. Or from the terminal:

./gradlew build

Your compiled plugin jar appears in build/libs/. Copy it to your test server's plugins folder.

Step 7, Set Up a Local Test Server

Download the latest Paper jar from papermc.io. Create a folder, place the jar inside, and run:

java -jar paper-1.21.4.jar

Accept the EULA by editing eula.txt, then restart. Drop your plugin jar into the plugins folder and restart again. Check the console for your "MyFirstPlugin has been enabled!" message. If you see it, your minecraft java plugin development setup is complete.

For troubleshooting server startup issues, see Fix Server Not Starting and How to Read Minecraft Server Console Logs.

What to Build Next

• Add an event listener, react to player joins, block breaks, or chat messages.
• Register a command, create a custom command with tab completion.
• Add a config file, let server owners customize your plugin without editing code.
• Use Spark to profile your plugin and make sure it does not hurt server performance.

A working development environment is the foundation everything else is built on. Get this right once and every future plugin project starts with a simple Gradle init instead of hours of setup.

Want to see custom plugins in action? Join Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.