A step-by-step guide to setting up your development environment for creating Minecraft plugins using Spigot and IntelliJ IDEA.

Prerequisites

Before you begin, make sure you have the following installed:

• Java Development Kit (JDK) ¡ª Use JDK 17 or 21 depending on your target Minecraft version (1.20+ recommends JDK 21)..
• IntelliJ IDEA ¡ª The Community edition is free and works great. Download from JetBrains.
• BuildTools ¡ª Used to build the Spigot server JAR locally (required by the Spigot licensing model).

Step 1: Build Spigot with BuildTools

Spigot cannot be distributed directly, so you need to build it yourself.

1. Download BuildTools.jar from the SpigotMC BuildTools page.
2. Create a folder (e.g., C:/SpigotBuild) and place BuildTools.jar inside it.
3. Open a terminal in that folder and run:

java -jar BuildTools.jar --rev 1.21

Replace 1.21 with your target Minecraft version. This process may take several minutes.

4. Once complete, you'll find a file named spigot-1.21.jar (or similar) in the same folder. Keep this JAR ¡ª you'll use it as a dependency in your project.

Step 2: Set Up a Local Test Server

Before writing any plugin code, get a local Spigot server running so you have somewhere to test your plugins straight away.

1. Create a folder for your test server (e.g., C:/TestServer).
2. Copy your built spigot-1.21.jar there and rename it to server.jar.
3. Create a start.bat (Windows) or start.sh (Mac/Linux):

java -Xmx2G -Xms1G -jar server.jar nogui

4. Mac/Linux only: Before you can run the script, you may need to make it executable by opening a terminal in the server folder and running:

chmod +x start.sh

5. Run it once to generate files. Accept the EULA by editing eula.txt and setting eula=true.
6. Run again ¡ª your server is now live locally for testing.

Note: Once the server has started, take a look at the folder ¡ª you'll notice a plugins/ directory has been created alongside server.jar. This is where you'll drop your plugin JAR later when it's time to test it.

Step 3: Create a New Maven Project in IntelliJ

1. Open IntelliJ IDEA and select New Project.
2. Choose Java as the language and select Maven as the build system.
3. Set your GroupId (e.g., com.yourname) and ArtifactId (e.g., myplugin).
4. Choose your JDK version and click Create.

Step 4: Configure Your pom.xml

Replace the contents of your pom.xml with the following, adjusting the values as needed:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.yourname</groupId>
    <artifactId>myplugin</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
    </properties>

    <repositories>
        <repository>
            <id>spigot-repo</id>
            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.21-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.0</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals><goal>shade</goal></goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Note: Change the spigot-api version to match your target Minecraft version.

Troubleshooting: Spigot API Not Resolving

After saving your pom.xml, IntelliJ needs to sync the new dependency. If you see errors like Cannot resolve symbol 'bukkit', try the following in order:

1. Reload the Maven project ¡ª Open the Maven panel on the right side of IntelliJ and click the refresh/reload button (circular arrows). Watch the bottom status bar to confirm it's downloading the dependency.
2. Invalidate Caches ¡ª If the import still shows as unresolved after reloading, go to File ¡ú Invalidate Caches ¡ú Invalidate and Restart. Once IntelliJ restarts it will rebuild its index and should recognise the Spigot API correctly.

Step 5: Create the Main Plugin Class

1. Inside src/main/java/com/yourname/myplugin/, create a new Java class called MyPlugin.
2. Extend JavaPlugin and override onEnable and onDisable:

package com.yourname.myplugin;

import org.bukkit.plugin.java.JavaPlugin;

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!");
    }
}

Step 6: Create the plugin.yml

Inside src/main/resources/, create a file named plugin.yml:

name: MyPlugin
version: 1.0
main: com.yourname.myplugin.MyPlugin
api-version: 1.21
description: My first Spigot plugin!
author: YourName

The main field must exactly match the fully qualified name of your main class.

Step 7: Build and Deploy Your Plugin

1. In IntelliJ, open the Maven panel (right side) and run package under Lifecycle.
2. Your compiled plugin JAR will appear in the target/ folder.
3. Copy the JAR into the plugins/ folder of your local Spigot server.
4. Start (or restart) the server and check the console for your plugin's enable message.
5. To confirm your plugin loaded successfully, join the server and run /plugins in chat. Your plugin's name should appear in the list highlighted in green. If it shows in red, the plugin failed to load ¡ª check the console for error messages.

Tips for Faster Development

• Auto-copy on build: Instead of manually copying your JAR to the plugins/ folder every time, you can automate this with Maven. Add the following to the <build> section of your pom.xml, replacing the path with the actual path to your test server's plugins/ folder:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-antrun-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>run</goal></goals>
            <configuration>
                <target>
                    <copy file="${project.build.directory}/${project.artifactId}-${project.version}.jar"
                          todir="C:/TestServer/plugins"/>
                </target>
            </configuration>
        </execution>
    </executions>
</plugin>

Now every time you run package in Maven, your plugin JAR will be automatically copied to the server. Just restart the server (or use /reload confirm) and your changes are live.

• Use /reload confirm in-game or via console to reload plugins without fully restarting (use with caution in development only).
• Enable debug logging with getLogger().info(...) liberally while developing.

Useful Links

Official Documentation & APIs

Downloads & Tools

Community & Help

Learning & Tutorials

Happy coding, and good luck building your plugin!