Minecraft Plugin Development: Getting Started

There is no plugin that does exactly what you want? Then build it yourself. Developing Minecraft plugins sounds complex, but with basic programming knowledge and the right tools, you can get started faster than you think. In this article, we help you on your way: from the first line of Java to a working plugin on your server.

What you need

Minecraft plugins run on Java. Since version 26.x, Minecraft uses Java 25, and your plugins must be compatible with it. Make sure you have the following installed:

• JDK 25: the Java Development Kit. Download from Adoptium.
• An IDE: IntelliJ IDEA Community (free) is the most popular choice. Eclipse and VS Code also work.
• A build tool: Gradle or Maven. Gradle is newer and faster; Maven is more traditional. Both work fine.
• A test server: a local Paper server to test your plugin without affecting production.

Setting up your project

Create a new Gradle or Maven project in your IDE. Add the Paper API as a dependency. For Gradle, add to build.gradle:

repositories {
    maven { url = "https://repo.papermc.io/repository/maven-public/" }
}
dependencies {
    compileOnly "io.papermc.paper:paper-api:MINECRAFT_VERSION-R0.1-SNAPSHOT"
}

Replace MINECRAFT_VERSION with your target version (e.g. 26.3). The Paper API includes the Bukkit and Spigot APIs, so you have access to everything.

Your first plugin class

Every plugin needs a main class that extends JavaPlugin. This class has two key methods: onEnable() runs when the server loads your plugin, and onDisable() runs when it unloads.

public 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 plugin.yml file

Create a file called plugin.yml (or paper-plugin.yml for the newer Paper plugin system) in src/main/resources/. This tells the server about your plugin:

name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: "26.3"
description: My first Minecraft plugin

Adding a command

Commands are how players interact with your plugin. Register a command in plugin.yml and create a command executor class. Example for a /hello command that greets the player:

In plugin.yml, add:

commands:
  hello:
    description: Say hello
    usage: /hello

In your main class, register the executor in onEnable(). The executor class implements CommandExecutor and handles the logic.

Listening to events

Events let your plugin react to things happening in the game. Want to do something when a player joins? Listen to PlayerJoinEvent. When a block breaks? BlockBreakEvent. Create a class that implements Listener, annotate methods with @EventHandler, and register the listener in your main class.

Building and testing

1. Run gradle build or mvn package in your terminal.
2. The compiled .jar appears in build/libs/ (Gradle) or target/ (Maven).
3. Copy the .jar to your test server's plugins/ folder.
4. Start or restart the server.
5. Test your command or event in-game.

For faster iteration, use a hot-reload plugin like PlugManX so you do not need to restart the entire server after each change.

Common pitfalls

• NullPointerException: the most common error. Always check if objects (players, worlds, items) actually exist before using them.
• Running heavy operations on the main thread: file I/O, database queries, and HTTP requests block the server tick. Use Bukkit.getScheduler().runTaskAsynchronously() for heavy work.
• Not saving configuration: use getConfig() and saveConfig() to persist settings between restarts.
• Hardcoding values: put configurable values in config.yml instead of your source code.

Where to learn more

The Paper documentation is the best starting point. The SpigotMC forums and the PaperMC Discord are active communities where you can ask questions. Looking at the source code of open-source plugins on GitHub is one of the fastest ways to learn patterns and best practices.

Do I need to know Java to make plugins?

Yes, Java is required. You do not need to be an expert, but understanding classes, methods, variables, and basic object-oriented programming is essential. If you are new to Java, spend a few days on a beginner tutorial before diving into plugin development.

Can I use Kotlin instead of Java?

Yes. Kotlin runs on the JVM and works with the Bukkit/Paper API. You need to include the Kotlin runtime in your plugin or shade it into the jar. Several popular plugins are written in Kotlin.

How do I publish my plugin?

Upload it to Modrinth, Hangar (Paper's plugin repository), or the SpigotMC resource section. Include a clear description, version compatibility, and usage instructions.

Test your plugins on your own Minecraft server from HostValues, with full file access and console.