Minecraft Plugin Development for Beginners: Your First Plugin in Java (2026)

A Minecraft plugin is a normal Java project with a small amount of extra setup. In this tutorial you will build a working plugin for a Paper server: it greets players when they join and adds a /hello command. Once you understand this one, every other plugin is a matter of adding more event handlers and commands.

//What you need

• ▪JDK 21. It matches servers on Minecraft 1.20.5 and newer. If your server is older, see the Java version guide and pick the matching JDK.
• ▪IntelliJ IDEA Community (free) or any IDE with Maven support. The steps below use IntelliJ.
• ▪A Paper test server on the same Minecraft version you target. Do not test on your production server.

//1. Create the Maven project

1. In IntelliJ choose New Project → Maven and select JDK 21.
2. Set GroupId to com.example, ArtifactId to HelloPluginand Version to 1.0.0.
3. Open pom.xml and add the Paper API. The provided scope means the server supplies the API at runtime, so it stays out of your .jar.

<properties>
  <maven.compiler.release>21</maven.compiler.release>
</properties>

<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.1-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Use the Paper API version that matches your test server. Your IDE should offer to reload the Maven project after the change; accept it.

//2. Write the main class

Create src/main/java/com/example/hello/HelloPlugin.java. The class extends JavaPlugin, so the server knows how to enable and disable it.

package com.example.hello;

import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;

public final class HelloPlugin extends JavaPlugin implements Listener {

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
        getLogger().info("HelloPlugin enabled");
    }

    @EventHandler
    public void onJoin(PlayerJoinEvent event) {
        event.getPlayer().sendMessage("Welcome to the server, " + event.getPlayer().getName() + "!");
    }

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (command.getName().equalsIgnoreCase("hello") && sender instanceof Player player) {
            player.sendMessage("Hello from HelloPlugin!");
            return true;
        }
        return false;
    }
}

onEnable runs when the server loads the plugin. Registering this as a listener is what makes onJoin run when a player connects. onCommand handles any command this plugin declares.

//3. Describe the plugin in plugin.yml

Create src/main/resources/plugin.yml. The server reads this file before it loads any of your code, and it has to sit in the resources folder so Maven copies it to the root of the .jar.

name: HelloPlugin
version: 1.0.0
main: com.example.hello.HelloPlugin
api-version: '1.21'
commands:
  hello:
    description: Says hello to the player
    usage: /hello

The main line must match your class exactly, package and capitalization included. Theapi-version is quoted on purpose. Every field is explained in plugin.yml Explained.

//4. Build the .jar

From the project folder, run:

mvn package
...
[INFO] BUILD SUCCESS

The plugin is now at target/HelloPlugin-1.0.0.jar. That is the only file you need to install.

//5. Test it on a Paper server

1. Stop the test server and copy the .jar into its plugins/ folder.
2. Start the server and look for HelloPlugin enabled in the console.
3. Run /plugins. HelloPlugin should be green.
4. Join with your Minecraft account. You should see the welcome message, and /hello should reply.

Every time you change the code, rebuild and restart the server. A restart is the only reliable way to load the new version, as explained in the installation guide.

//Common first-build errors

package org.bukkit does not exist

The Paper API dependency is missing or was not loaded. Check the pom.xml block above and reload the Maven project.

The plugin does not appear, or the console says "Invalid plugin.yml"

Check that plugin.yml is inside src/main/resources, not src/main/java, and that indentation uses spaces only. A tab is enough to break the file.

UnsupportedClassVersionError

You built with a newer Java than the server runs. Set maven.compiler.release to the server's Java version and rebuild. The Java version guide has the full table.

"Unknown command" when you type /hello

The command is not declared in plugin.yml, or the name does not match the one checked inonCommand.

//Where to go next

Add a config.yml for messages you want to change without rebuilding, or start from the plugin ideas list to pick something players actually ask for.