The Dev Environment: Paper, Gradle, and a Test Server

Every plugin tutorial starts with code; every plugin developer starts with a setup. Get the toolchain right once and every project after is a five-minute clone.

Paper, not Bukkit, not Spigot

Paper is the maintained, performant fork with the modern API (paper-api). Spigot API plugins mostly run on Paper; Paper API features (adventure components, better events) don't run on Spigot. Target Paper — it's what real servers run.

The Gradle skeleton

// build.gradle.kts (skeleton)
plugins { java }
repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
}
dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21-R0.1-SNAPSHOT")
}
java { toolchain.languageVersion.set(JavaLanguageVersion.of(21)) }

compileOnly because the server provides the API at runtime — bundling it into your jar is the classic classpath-conflict bug. Java 21 toolchain on modern Paper.

The test loop that doesn't make you quit

Run a Paper server in run/ with eula.txt accepted, symlink your built jar into run/plugins/, and iterate with ./gradlew build + server restart — or Paper's /reload confirm for quick checks (fine for dev, never for prod). A plugin that takes 4 minutes to test teaches you nothing; get the loop under 30 seconds.

Field notes

• Pin the Paper API version to your target Minecraft version — API drift between MC releases is real.
• Keep run/ out of git; the jar is the artifact.
• Log in: server.properties debug=false, and watch logs/latest.log — stack traces are the tutorial.