Skip to content

README_en.md

Latest commit

 

History

History
155 lines (102 loc) · 4.19 KB

README_en.md

File metadata and controls

155 lines (102 loc) · 4.19 KB

Spigot Plugin Development — Getting Started

A step-by-step guide to setting up a local Spigot plugin development environment with IntelliJ IDEA, from project creation to live debugging.

Prerequisites

1. Create the Project

Open IntelliJ IDEA and create a new project with the following settings:

Field Value
Group Plugin
Template Spigot
Build System Maven
Language Java
Minecraft Version 1.21.3 (or your target version)
JDK Java 21

Avoid placing the project on your system drive — permission issues can prevent the server from writing files at runtime.

2. Set Up a Local Debug Server

2a. Create the server directory

Create a folder named run in your project root. This keeps server files separate from your source code.

2b. Download the server JAR

Download the Spigot JAR for your target version from getspigot.org and place it in the run folder.

Tip: Building from source with BuildTools is recommended for production use, but a pre-built JAR is fine for local development.

2c. Create the startup script

Create run/start.bat with the following content, adjusting the paths to match your setup:

@echo off
:start
cd /d "C:\your\project\run"
"C:\Program Files\Eclipse Adoptium\jdk-21.0.10.7-hotspot\bin\java" -jar spigot-1.21.3.jar nogui
pause
goto start

Note the space between java" and -jar — missing it will cause a startup failure.

Run start.bat. The server will stop on first launch asking you to accept the EULA. Open run/eula.txt and set:

eula=true

Run start.bat again. The server will finish initializing and generate all required files.

2d. Configure the server

Open run/server.properties and apply the following settings for local development:

gamemode=creative
server-ip=127.0.0.1
server-port=25565
motd=Local Debug Server

Do not add inline comments to server.properties — they will appear as part of the value.

2e. Connect from Minecraft

Launch Minecraft, go to Multiplayer → Add Server, and enter 127.0.0.1:25565.

3. Configure the Project

Exclude the server directory from IDEA

Go to File → Project Structure → Modules, find the run folder, and mark it as Excluded. This prevents IDEA from indexing server files and slowing down the IDE.

4. Build and Deploy

Build your plugin JAR via the Maven sidebar:

Maven → <Your Project> → Lifecycle → package

This generates a target/ directory containing two JARs:

  • your-plugin.jar — the one to deploy
  • original-your-plugin.jar — the unshaded version, ignore this

Copy your-plugin.jar to run/plugins/.

5. Run Configurations

Set up a run configuration so you can start the debug server directly from IDEA:

  1. Open Edit Configurations (top-right dropdown)
  2. Click + and choose JAR Application
  3. Fill in the fields:
Field Value
Name Spigot 1.21.3
Path to JAR ./run/spigot-1.21.3.jar
Program arguments nogui
Working directory ./run

Enable Allow multiple instances and Store as project file.

Click Debug. Once the server finishes loading, you should see your plugin's startup message in the console — confirming the plugin loaded successfully.

Project Structure

your-project/
├── src/
│   └── main/
│       ├── java/         # Plugin source code
│       └── resources/
│           └── plugin.yml
├── run/                  # Local debug server (excluded from IDEA index)
│   ├── plugins/          # Drop your built JAR here
│   ├── server.properties
│   ├── eula.txt
│   └── start.bat
└── pom.xml

Next Steps

  • Edit src/main/java/.../YourPlugin.java to start building your plugin logic
  • Rebuild with mvn package and restart the server to test changes
  • Use the IDEA debugger with breakpoints for live debugging