This guide goes through it in the order a server owner sees it. Everything here works for free and paid resources alike.

Start with the problem, not the name

On SpigotMC's resource list, a server owner sees three things: your icon, your title and your tag line. The tag line is the sentence that sells the click, and most plugins waste it on "A simple plugin that adds…".

Write it as the problem it solves, with the words people search for:

A few rules that hold up:

• Put the platforms and versions in it if they're a selling point ("1.8 to 1.21", "Folia support"). Server owners filter mentally by version before anything else.
• Use the words a server owner would type into search: "economy", "shops", "minigame", "anticheat". SpigotMC's search and Google both read the title and tag line.
• Keep the title short and memorable. If your plugin's name doesn't say what it does, the tag line has to.

The icon matters more than it should. A clean, readable icon at small size (a single shape, strong contrast, no tiny text) gets more clicks than a screenshot squeezed into a square.

The first screen decides

Once someone opens your page, the part above the fold has to answer three questions: what does it do, does it work on my server, and does it look good?

What works:

1. A banner or a hero image that shows the plugin in action, not just its logo.
2. One paragraph saying what it does and for whom, in plain words.
3. Compatibility in bold: server software, Minecraft versions, dependencies (or "no dependencies"). Owners running Paper 1.21 want to know in one glance that they're covered.
4. A GIF or short video of the core feature.

What doesn't: a wall of BBCode-coloured text, a changelog at the top, or a list of 40 commands before anyone knows why they'd want the plugin. Commands and permissions belong further down, or in the Documentation tab.

If you want a structure to copy, we wrote a free SpigotMC resource page template with the BBCode ready.

Make your images and GIFs actually load

SpigotMC doesn't host the images in your description. You link them from somewhere like Imgur, and SpigotMC serves them through its own image proxy. Two things go wrong often:

• Big GIFs don't show. In our experience the proxy stops serving GIFs above roughly 3 MB: the visitor sees a broken image right where your best feature should be. Keep GIFs short (5 to 8 seconds), small (around 600 px wide) and under that size. Convert longer clips to a YouTube video and embed it instead.
• Huge PNGs load slowly. Export screenshots as optimised PNG or JPEG. A description made of a few tall "poster" images, one per section, looks polished and loads fast if each one stays well under a megabyte.

Also: SpigotMC strips 4-byte emojis from descriptions, so 🚀 and friends simply vanish. Use plain symbols like ★ or ✔, or none.

Look alive: updates, replies and reviews

A plugin with a last update two years ago reads as abandoned, even if it works perfectly. Server owners know that a dead plugin breaks on the next Minecraft version.

• Update with every Minecraft release, even when it's only "Tested on 1.21.x, no changes needed". Updated resources show up again in SpigotMC's "latest updates", and the date on your page stays recent.
• Write useful update notes. "Fixed bugs" tells nobody anything. "Fixed shops losing items on restart with MySQL" tells a server owner you care about their data.
• Answer the discussion tab and reviews. A reply under a one-star review ("fixed in 2.3.1, thanks for the report") often turns the review around, and everyone reading it sees a maintained plugin.
• Ask for reviews at the right moment. Not on every join, not in a nagging broadcast. A good moment is after an admin has used the plugin for a few days: a single, polite message to admins with a link to the review page works far better than begging in the description.

Be where server owners look

SpigotMC is the biggest, but it's not the only place people find plugins:

• Modrinth has a growing share of Paper and Purpur users, a clean search with filters by loader and version, and a gallery. Its short summary works like SpigotMC's tag line: write it the same way.
• Hangar is PaperMC's own repository, and some Paper users start there.
• Your own Discord turns downloads into a community: support in one place, update announcements, and people who'll tell you what to build next.
• YouTube showcases still drive installs. Many small channels review plugins; a 3-minute video often brings more downloads than a month of forum posts.

Cross-listing is cheap: the same jar, the same images, a description adapted to each site's format.

Measure the whole path, not just downloads

Downloads are the only number SpigotMC gives you, and it's the least useful one. It doesn't tell you how many people saw your page and left, or how many downloads ended up running on a server, or how many servers kept the plugin a week later.

The path that matters looks like this:

listing views → downloads → servers that install it → servers still running it after a week

Each step tells you something different:

SpigotMC doesn't show authors how many people view their page, but you can measure it with a tracking image in your description. PluginAnalytics does exactly this: an invisible pixel or a live badge on your SpigotMC and Modrinth pages counts views, downloads are read from both sites, and the SDK in your plugin counts the servers that install it and keep it. You see the whole funnel in one chart, and you see whether the new GIF you added last Tuesday changed anything.

Whatever you use, change one thing at a time and give it a week. That's how you find out what actually brings downloads, instead of guessing.

A quick checklist

• Tag line names the problem and the platforms, in words people search for.
• The first screen shows the plugin in action, says what it does and lists compatibility in bold.
• GIFs under about 3 MB, images optimised, no 4-byte emojis.
• An update for every Minecraft version, with update notes that say something.
• Replies to reviews and questions within a few days.
• Listed on Modrinth and Hangar too.
• Views, downloads, installs and retention measured, one change at a time.

Pick one place

Reports scattered across reviews, the discussion tab, DMs and three Discord channels get lost. Choose one main place and say it everywhere (description, plugin.yml, the error message itself):

Many developers use Discord for conversation and GitHub (or a Discord forum channel) for tracking. Whatever you choose, ask people not to report bugs in reviews: point to the right place in your description and reply to the review with the link.

What every report needs

Most bugs depend on the environment. A report without these takes three messages to start:

• Plugin version and server software and version (Paper 1.21.4, Spigot 1.20.1…).
• Other plugins that might interact (permissions, economy, protection).
• What they did, what they expected, what happened.
• The error from the console, in full, through a paste site like mclo.gs, not a screenshot.
• Their config, if the bug might depend on it.

A report template

Pin this, or use it as a GitHub issue template:

Plugin version:
Server software and version (e.g. Paper 1.21.4):
Other relevant plugins:

What I did:
What I expected:
What happened instead:

Console error (paste on https://mclo.gs and link it):

Triage without drowning

• Reproduce first. Same plugin version, same server software, same config. If you can't reproduce it, ask for exactly what's missing.
• Check if it's known. Many reports are the same bug. Merge them and keep a count: three people hitting it means more than one loud one.
• Ask about the version. A good share of reports are already fixed in a newer version. A good update checker reduces these a lot.
• Close the loop. Reply when it's fixed, with the version. People who see their report fixed become your best reviewers.

Reports that carry their own context

The best report is one the owner can send in five seconds, from where the problem happened, that already includes everything above. That's what PluginAnalytics' in-game bug reports and ideas do: the SDK adds /yourplugin report <message> and /yourplugin suggest <message>, and each report arrives in your dashboard with the plugin, Minecraft and server versions, whether it came from a player or an admin, and your plugin's own errors and log lines from the 15 minutes before, with player names, IPs and UUIDs removed. No account, no template, no paste site.

And for the bugs nobody reports at all, error tracking catches them on every server.

Summary

• One main place for reports, said everywhere.
• A template that asks for versions, steps and the full error.
• Reproduce, merge duplicates, check the version, close the loop.
• Make reporting as easy as typing a command, and collect the context automatically.

There are two common ways to do it. Both take a few minutes.

Option 1: bStats

bStats is the classic: free, open source, and used by thousands of plugins. It counts servers and players and shows them on a public page, with charts for versions, platforms and countries, plus custom charts you define.

Setup, in short:

1. Sign in at bstats.org, add your plugin and note its plugin id (a number).
2. Add the bstats-bukkit dependency from Maven Central and shade and relocate it into your jar (bStats checks this; an unrelocated copy refuses to run).
3. Start it in onEnable:

@Override
public void onEnable() {
    int pluginId = 12345; // from your bStats page
    Metrics metrics = new Metrics(this, pluginId);
    metrics.addCustomChart(new SimplePie("storage", () -> getConfig().getString("storage.type")));
}

The bStats docs have the exact Maven and Gradle snippets. Your charts fill in over the next hours.

Good for: a free, public server and player count that you and others can see.

Option 2: PluginAnalytics

PluginAnalytics counts the same servers, privately, and adds what happens inside them: which features are used, where players drop off, which errors hurt, and how your SpigotMC listing converts into installs.

1. Create a project in the dashboard and copy its key.
2. Add the SDK and relocate it (Gradle and Maven snippets).
3. Start it in onEnable:

@Override
public void onEnable() {
    analytics = PluginAnalytics.start(this, "pa_your_key");
}

The first data shows up within a minute, and the dashboard updates live. Servers, versions, platforms, countries, players and your config choices are collected without any more code; custom events are one line each.

Good for: private numbers, product questions and error tracking, on top of the count.

You can run both. They don't conflict, and many developers keep bStats for its public page.

Why the count doesn't match your downloads

Expect the number of servers to be much lower than your downloads, and don't panic:

• Updates are downloads too. An owner who installs every update counts once as a server and twenty times as a download.
• Many downloads never get installed. People download to try, to compare, or for a server they never open.
• Test servers come and go. A server that ran your plugin once and was deleted still shows in your downloads.
• Owners can opt out. Both bStats and PluginAnalytics let server owners turn metrics off (bStats in plugins/bStats/config.yml, PluginAnalytics in plugins/PluginAnalytics/config.yml), so a share of servers never reports. That's how it should be: owners trust plugins that respect it.
• Offline networks and firewalls block outgoing connections, so some servers can't report at all.

The useful number isn't the raw count but its trend, and how it compares with the step before it. If downloads double after an update but servers stay flat, something stops people between the download and a working install.

What a server count can't tell you

A server count answers "how many?". The questions that decide what you build next are different:

• Do they keep it? How many servers that installed it last month still run it today? A rising count can hide a leaky bucket.
• What do they use? Which commands and features get used, and which ones nobody touches?
• Where do they get stuck? How many players start your minigame and how many finish it?
• What breaks? Which errors happen, on which versions, and did the last update fix them?
• Which config choices are common? If 90% of servers keep a default, it's a good default. If everyone changes it, it isn't.

That's the difference between metrics and product analytics. bStats is great at the first. PluginAnalytics was built for the rest: funnels and retention, events, errors, config usage and listing analytics, from one line in onEnable.

Respect the server owner

Whatever you choose:

• Say in your resource description that the plugin collects anonymous usage statistics, and how to turn them off.
• Never collect player names, UUIDs, IP addresses or chat. You don't need them to answer any of the questions above.
• Keep it off the main thread and never let it break the plugin if the service is down.

Both tools do this for you. If you build your own, it's the part people forget.

Supporting it is mostly about scheduling. Here's what changes and how to keep a single jar that runs on Spigot, Paper and Folia.

What's different on Folia

• There's no main thread. Each region of the world ticks on its own thread. The code that touches a block or an entity must run on the thread that owns its region.
• BukkitScheduler doesn't work. Bukkit.getScheduler().runTask(...) and friends throw UnsupportedOperationException on Folia.
• Touching the world from the wrong thread throws. Reading or changing a block, an entity or a player from another region's thread fails with an exception instead of quietly racing.
• Teleporting is asynchronous. Use teleportAsync, which returns a future.

Declare support

Folia only loads plugins that say they support it, in plugin.yml:

folia-supported: true

Only add it once the plugin really works on Folia: owners trust that flag.

Pick the right scheduler

Paper's API (1.20 and later) has four schedulers that work on both Paper and Folia. Use the one that matches what the task touches:

For example, a repeating task per player:

player.getScheduler().runAtFixedRate(plugin, task -> {
    if (!player.isOnline()) { task.cancel(); return; }
    updateScoreboard(player);
}, null, 20L, 20L);

And going from async work back to a player:

Bukkit.getAsyncScheduler().runNow(plugin, t -> {
    Stats stats = database.load(player.getUniqueId());
    player.getScheduler().run(plugin, t2 -> apply(player, stats), null);
});

On Paper these run on the main thread as usual, so the same code works on both.

One jar for Spigot, Paper and Folia

Spigot doesn't have these schedulers. If you want one jar for everything, detect Folia at startup and route through a small wrapper:

public final class Platform {
    public static final boolean FOLIA = classExists("io.papermc.paper.threadedregions.RegionizedServer");

    private static boolean classExists(String name) {
        try { Class.forName(name); return true; } catch (ClassNotFoundException e) { return false; }
    }
}

Then one method per kind of task: on Folia it calls the right Paper scheduler, elsewhere BukkitScheduler. Keep every scheduling call in your plugin going through that wrapper, so a stray Bukkit.getScheduler() can't slip back in. Libraries like FoliaLib do this for you if you'd rather not write it.

Common mistakes

• Iterating all players from one task and changing each of them. On Folia, schedule the change on each player's own scheduler.
• Global managers that tick everything: one task that updates every arena in the world. Split it per region (one region task per arena) or move the computing part to the async scheduler.
• Static caches shared between threads without synchronisation: what was safe with one main thread now races. Use concurrent collections.
• Assuming Bukkit.isPrimaryThread() means "safe to touch anything". On Folia it doesn't.
• Libraries. A dependency that uses BukkitScheduler breaks your plugin on Folia too. Check them, including the analytics or update-checker library you shade. (PluginAnalytics' SDK supports Folia with nothing to configure.)

Test it

Run your plugin on a real Folia server with a few players in different areas of the world, and use every feature. Problems show as exceptions in the console, which is good: they're loud. An error tracker that tags errors by platform (like PluginAnalytics) tells you whether an error only happens on Folia servers, which saves a lot of guessing once the plugin is out.

This guide covers where plugin errors end up, why waiting for reports isn't enough, and how to see every error from every server.

Where your plugin's exceptions go

When your code throws on a server, the server catches it and logs it, so the server keeps running. Each kind of entry point has its own message in the console:

Followed by the stack trace. The server owner sees it, maybe. You don't, unless they copy it and send it to you.

Why "send me your logs" doesn't scale

Asking for logs works when you have ten users. With a thousand servers it breaks down:

• Most owners never report. Reporting takes effort; uninstalling takes one click.
• Reports arrive late and incomplete. "It doesn't work" with no version, no server software and a screenshot of half a stack trace.
• You can't tell how big a bug is. One report could be one server or three hundred.
• You can't tell if your fix worked. No news after an update could mean fixed, or could mean people gave up.

What good error tracking does

Whatever tool you use, or if you build it yourself, these are the parts that matter:

1. Catch errors where they happen. Exceptions that go through your plugin's code, from event handlers, commands, tasks and async threads, plus the ones you catch yourself and want to know about.
2. Group them. The same bug on 500 servers should be one issue with a count, not 500 alerts. Grouping by the exception type and the top frames of your code (without line numbers, so a small edit doesn't split an issue) works well.
3. Keep the context. Plugin version, server software, Minecraft version, Java version. Most plugin bugs only happen on some combination of these.
4. Strip personal data. Stack trace messages often contain player names, UUIDs and IP addresses ("Could not find player Notch at 1.2.3.4"). Replace them before anything leaves the server.
5. Track regressions. When you mark an issue fixed and it happens again in a newer version, you want to know straight away.
6. Never hurt the server. Capture off the main thread, cap how much is sent, and never throw from the error reporter itself.

Report the errors you catch

The server only logs exceptions that escape your code. The ones you catch and swallow are invisible:

try {
    database.save(arena);
} catch (SQLException e) {
    getLogger().warning("Couldn't save arena: " + e.getMessage()); // the stack trace is gone
}

If an error matters enough to log, it usually matters enough to report with its stack trace. Pass the exception to your logger (getLogger().log(Level.WARNING, "Couldn't save arena", e)) or to your error tracker directly.

Options

• Ask for logs (mclo.gs, pastebin, Discord). Free, works for small plugins, misses most errors.
• A general error tracker like Sentry, shaded into your plugin. Powerful, but it's built for web apps: you'll need to scrub player data yourself, map Bukkit's thread model, and watch the event quota of the free plan when one bug fires on thousands of servers.
• A tool built for plugins. PluginAnalytics captures every exception that goes through your plugin on any server with no extra code, groups it into issues, replaces player names, IPs and UUIDs, shows the versions where it was first and last seen, and notifies you of new errors and regressions. It also collects your plugin's own log lines from every server, and for obfuscated plugins it turns stack traces back into your real class names.

Fix the right bug first

Once errors arrive on their own, prioritise by impact, not by how loud the report was:

• How many servers hit it, not how many times. One server in a loop can log a million errors.
• Which versions. A bug only on an old version is fixed by asking people to update. A bug that appeared in your latest release is urgent.
• Where in the flow. An error on startup costs you the install. An error in a rarely used command can wait.

Then ship the fix, mark the issue resolved, and watch: if it comes back in the new version, you'll know before the next review does.

Here's how to find which part of your plugin costs the most, the patterns that usually cause it, and how to fix them.

Measure first: MSPT, not TPS

TPS (ticks per second) stays at 20 until the server is already overloaded, so it hides problems. MSPT (milliseconds per tick) shows how much of the 50 ms budget is used, long before TPS drops.

On Paper, /mspt shows it. A healthy server sits well under 50; if it's at 45 with your plugin and 25 without, you've found a suspect.

Profile with spark

spark is the standard profiler for Minecraft servers, and it ships with recent Paper builds. Run it while the lag happens:

/spark profiler start
... reproduce the lag for a minute or two ...
/spark profiler stop

You get a link to a call tree of the main thread. Open it, search for your plugin's package, and expand the heaviest branches. The method at the bottom of a thick branch is where the time goes.

Useful options:

• --only-ticks-over 50 records only the slow ticks, so a lag spike isn't diluted by normal ticks.
• --thread * includes other threads, if you suspect your async tasks.

spark profiles one server at a time, the one you're on. It's the right tool to fix a lag you can reproduce.

The usual suspects

Most plugin lag comes from a handful of patterns.

Heavy work in PlayerMoveEvent. It fires many times per second per player, including when they only turn their head. Bail out early when the block didn't change:

@EventHandler
public void onMove(PlayerMoveEvent e) {
    Location from = e.getFrom(), to = e.getTo();
    if (to == null || (from.getBlockX() == to.getBlockX() && from.getBlockY() == to.getBlockY() && from.getBlockZ() == to.getBlockZ())) return;
    // the expensive part, now ~20x less often
}

Loops over everything, every tick. Iterating all online players, all entities or all loaded chunks every tick adds up fast. Run it every 10 or 20 ticks if it doesn't need to be instant, or keep a set of only the things you care about.

Database and file I/O on the main thread. A MySQL query that takes 30 ms on a remote database is more than half a tick. Do I/O asynchronously and come back to the main thread with the result:

Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    Stats stats = database.load(uuid);            // off the main thread
    Bukkit.getScheduler().runTask(plugin, () -> apply(player, stats)); // back on it
});

Loading chunks by accident. world.getBlockAt(x, y, z) or getChunkAt on an unloaded chunk loads (or generates) it synchronously. Check world.isChunkLoaded(cx, cz) first, or use Paper's async chunk API.

Updating scoreboards, holograms or boss bars every tick. Players can't read text that changes 20 times a second. Update every second, and only when the value changed.

Recomputing what could be cached. Parsing config values, building item stacks or compiling regexes on every call. Do it once on load and keep the result.

The problem with profiling one server

spark tells you what's slow on the server you're looking at. But your plugin runs on hundreds of servers with different player counts, worlds and configs, and the lag a server owner complains about may only happen with their setup. A few questions spark can't answer:

• How much of a tick does my plugin use on average, across all servers?
• Which of my methods costs the most in real use, not in my test world?
• Did my last release make it slower?

That's what PluginAnalytics' performance view is for. The SDK samples the main thread about ten times a second on every server and records time spent in your plugin's code, by method, and times your event handlers and commands. The dashboard shows the milliseconds per tick your plugin uses, its most expensive methods, and a comparison between versions, so a slow release stands out and notifies you. It's the same idea as spark, aggregated across all the servers running your plugin, with nothing to install for the server owner.

Use both: the aggregate view tells you what to look at, spark on a test server tells you why.

A quick checklist

• Measure MSPT, not TPS.
• Profile the lag with spark while it happens, and search for your package.
• Return early in move events; throttle per-tick loops.
• No database or file I/O on the main thread.
• Don't load chunks by accident.
• Update visual things once a second, not every tick.
• Cache what doesn't change.
• Compare versions: make sure each release isn't slower than the last.

This is the setup we use for our own plugins: Gradle with the shadow plugin, then ProGuard on the shaded jar.

The Gradle task

ProGuard runs on the jar shadow builds, with your libraries already inside and relocated. Add the ProGuard Gradle plugin to the build script's classpath:

// build.gradle.kts
buildscript {
    repositories { mavenCentral() }
    dependencies { classpath("com.guardsquare:proguard-gradle:7.10.0") }
}

Then a task that reads the shadow jar and writes the obfuscated one:

val proguardJar by tasks.registering(proguard.gradle.ProGuardTask::class) {
    dependsOn(tasks.shadowJar)
    configuration("proguard.pro")
    injars(tasks.shadowJar.flatMap { it.archiveFile })
    outjars(layout.buildDirectory.file("libs/${project.name}-${project.version}-obfuscated.jar"))
    // The JDK and the server API: ProGuard needs them to understand your code, and their names stay.
    val jdk = javaToolchains.launcherFor { languageVersion = JavaLanguageVersion.of(17) }.get()
        .metadata.installationPath.dir("jmods").asFile
    for (module in listOf("java.base", "java.logging", "java.sql", "java.desktop")) {
        libraryjars(mapOf("jarfilter" to "!**.jar", "filter" to "!module-info.class"), File(jdk, "$module.jmod"))
    }
    libraryjars(configurations.compileClasspath)
    printmapping(layout.projectDirectory.file("mappings/${project.version}.txt"))
}

libraryjars(configurations.compileClasspath) adds the Spigot or Paper API (your compileOnly dependencies) as a library: it's on the server, not in your jar, so ProGuard must not rename calls into it. Add any other JDK module your code uses to the list.

The rules Bukkit needs

Bukkit finds parts of your plugin by name or by reflection. Those must survive obfuscation:

# proguard.pro
-dontoptimize
-dontnote
-dontwarn

# Annotations (event handlers), generics, inner classes; line numbers for stack traces.
-keepattributes *Annotation*,Signature,InnerClasses,EnclosingMethod,Record,Exceptions,SourceFile,LineNumberTable
-renamesourcefileattribute SourceFile

# The main class named in plugin.yml.
-keep class com.example.myplugin.MyPlugin

# Bukkit calls @EventHandler methods by reflection: keep them (their names can change).
-keepclassmembers,allowobfuscation class * {
    @org.bukkit.event.EventHandler <methods>;
}

# Enum.valueOf needs values() and valueOf().
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

Why -dontoptimize? Optimisation rewrites your code, and the code that runs on servers is then not quite the code you tested. Renaming and shrinking give most of the protection with none of that risk.

Other things to keep, if you use them:

• ConfigurationSerializable classes: Bukkit calls their static deserialize or valueOf and the constructor that takes a Map. Keep those members.
• Anything you load by name: Class.forName("..."), reflection on your own classes, classes listed in config files.
• Shaded libraries that use reflection, like bStats or Gson models: keep their packages, or the classes Gson serialises.
• Your analytics SDK: libraries that report your plugin's own class names (like PluginAnalytics) should stay readable, so keep their relocated package: -keep class com.example.myplugin.libs.analytics.** { *; }.

Test the obfuscated jar, not the normal one

Run the obfuscated jar on a real server before every release. Most ProGuard problems show up at startup (NoSuchMethodError, ClassNotFoundException) or the first time a feature uses reflection. A quick checklist: the plugin enables, commands work, a listener fires, config loads, data saves and loads.

Keep stack traces readable

printmapping writes a file mapping every new name back to the original, a different one for every build. Keep the mapping of every version you release: commit it, or store it next to the release. Without it, a stack trace from that version can't be read.

To read a stack trace by hand, ProGuard ships retrace:

retrace mappings/1.4.0.txt stacktrace.txt

That works when a server owner sends you a trace. For errors you never hear about, PluginAnalytics applies the mapping for you: upload each version's mapping from your build, and the errors, performance data and bug reports from every server show your real class and method names, including data that arrived before you uploaded it. It's one HTTP request after ProGuard:

val uploadMapping by tasks.registering {
    dependsOn(proguardJar)
    doLast {
        val token = providers.gradleProperty("pluginanalytics.token").orNull ?: return@doLast
        val c = java.net.URI("https://pluginanalytics.dev/api/v1/mappings?version=${project.version}").toURL()
            .openConnection() as java.net.HttpURLConnection
        c.requestMethod = "POST"
        c.doOutput = true
        c.setRequestProperty("Authorization", "Bearer $token")
        c.outputStream.use { it.write(file("mappings/${project.version}.txt").readBytes()) }
        check(c.responseCode == 200) { "Mapping upload failed: ${c.responseCode}" }
    }
}

The version must match the version in your plugin.yml, which is what servers report.

Summary

• Shadow first, ProGuard on the shaded jar, the server API as a library jar.
• Keep the main class, @EventHandler methods, enum methods and anything reached by reflection.
• Rename and shrink; skip optimisation.
• Keep line numbers and the mapping of every release.
• Test the obfuscated jar on a real server before you ship it.

Where to read the latest version

SpigotMC has a simple endpoint that returns the latest version string of a resource as plain text:

https://api.spigotmc.org/legacy/update.php?resource=12345

12345 is the number at the end of your resource's URL. The value is the version you typed when you posted the update, so keep those consistent with your plugin.yml.

Modrinth returns the versions of a project, newest first:

https://api.modrinth.com/v2/project/your-slug/version

Read version_number of the first one. Modrinth asks for a User-Agent that identifies your project.

Both APIs can lag a little behind a release, and both can be down. Your plugin must work the same either way.

Check off the main thread

Never make an HTTP request on the main thread: a slow response freezes the server. Check asynchronously, on startup and then every few hours:

Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    try {
        HttpURLConnection c = (HttpURLConnection) new URL("https://api.spigotmc.org/legacy/update.php?resource=12345").openConnection();
        c.setConnectTimeout(5000);
        c.setReadTimeout(5000);
        String latest = new String(c.getInputStream().readAllBytes(), StandardCharsets.UTF_8).trim();
        if (isNewer(latest, plugin.getDescription().getVersion())) this.latest = latest;
    } catch (IOException ignored) {
        // offline or the API is down: try again next time
    }
});

(On Folia, use the async scheduler instead: see making your plugin Folia-compatible.)

Compare versions as numbers

String comparison says 1.10.0 is older than 1.9.2. Compare each number in turn:

static boolean isNewer(String latest, String current) {
    String[] a = latest.split("[^0-9]+"), b = current.split("[^0-9]+");
    for (int i = 0; i < Math.max(a.length, b.length); i++) {
        int x = i < a.length && !a[i].isEmpty() ? Integer.parseInt(a[i]) : 0;
        int y = i < b.length && !b[i].isEmpty() ? Integer.parseInt(b[i]) : 0;
        if (x != y) return x > y;
    }
    return false;
}

Never tell someone running a newer version (a dev build, say) to "update" to an older one.

Tell the right people, once

• Console: one line on startup when an update exists. Not every check.
• In game: only to players with a permission (say yourplugin.update, default op), when they join. Never to regular players.
• Include the link to your resource page, and what changed if it's short ("fixes data loss with MySQL").
• Let owners turn it off in the config. Some networks pin versions on purpose.

Critical updates

Some releases matter more than others: a dupe exploit, data loss, a security fix. Those deserve a stronger message (a warning in the console, a red line for admins) even if the owner usually ignores updates. Decide it per release, not per check, and say why: "Versions below 2.3.1 can lose player data on restart".

Without writing it yourself

PluginAnalytics' update notices do all of the above with no code beyond the SDK: the latest version is read from SpigotMC or Modrinth (or set by hand), admins with the permission get your message on join, you set a minimum version below which the notice becomes a warning, and you change the message in the dashboard without a new release. You also see how many servers are still on each version, which tells you whether people actually update.

Checklist

• Read the version from SpigotMC or Modrinth, with timeouts, off the main thread.
• Compare numbers, not strings.
• One console line; in-game only for admins with a permission.
• Link to the resource and say what changed.
• An option to turn it off.
• A clear warning for critical updates.

The section order that works

1. Hero image: the plugin in action, with its name.
2. One paragraph: what it does and for whom.
3. Compatibility in bold: server software, Minecraft versions, dependencies.
4. Features: 5 to 8 bullets, each starting with the benefit in bold.
5. A GIF or video of the main feature.
6. Getting started: install steps in 3 or 4 lines.
7. Commands and permissions: inside spoilers, so they don't push everything down.
8. Support and links: Discord, wiki, source, bug reports.

Configuration details, the full command list and FAQs fit better in the Documentation tab of your resource, which SpigotMC shows next to the description.

The template

Paste this into the description editor in BB code mode (the [ ] button in the editor's toolbar). Replace the capitalised parts.

[CENTER][IMG]https://i.imgur.com/YOUR_BANNER.png[/IMG][/CENTER]

[SIZE=5][B]PLUGIN NAME[/B][/SIZE] does ONE SENTENCE ABOUT WHAT IT DOES AND FOR WHOM. ONE MORE SENTENCE ON WHAT MAKES IT DIFFERENT.
[B]Works on Spigot, Paper and Folia · Minecraft 1.20 to 1.21.x · No dependencies[/B]

[SIZE=5][B]Features[/B][/SIZE]
[LIST]
[*][B]BENEFIT IN A FEW WORDS:[/B] how it works, in one sentence.
[*][B]BENEFIT IN A FEW WORDS:[/B] how it works, in one sentence.
[*][B]BENEFIT IN A FEW WORDS:[/B] how it works, in one sentence.
[*][B]BENEFIT IN A FEW WORDS:[/B] how it works, in one sentence.
[*][B]Fully configurable:[/B] every message, sound and limit in config.yml.
[/LIST]

[CENTER][IMG]https://i.imgur.com/YOUR_GIF.gif[/IMG][/CENTER]

[SIZE=5][B]Getting started[/B][/SIZE]
[LIST=1]
[*]Drop the jar into your plugins folder and restart.
[*]Edit plugins/PLUGIN NAME/config.yml if you want to change anything.
[*]Run /COMMAND to start.
[/LIST]

[SPOILER="Commands"]
[LIST]
[*][B]/COMMAND[/B]: what it does
[*][B]/COMMAND reload[/B]: reloads the configuration
[/LIST]
[/SPOILER]

[SPOILER="Permissions"]
[LIST]
[*][B]plugin.use[/B]: use the plugin (default: everyone)
[*][B]plugin.admin[/B]: admin commands (default: op)
[/LIST]
[/SPOILER]

[SIZE=5][B]Support[/B][/SIZE]
Questions, bugs or ideas: [URL='https://discord.gg/YOUR_INVITE']join the Discord[/URL]. Please report bugs there instead of in reviews, so they get fixed faster.

For a video instead of a GIF, SpigotMC embeds YouTube with [MEDIA=youtube]VIDEO_ID[/MEDIA], where VIDEO_ID is the part after v= in the link.

The BBCode you'll actually use

SpigotMC's editor understands more tags than these, but these cover a clean page:

Images and GIFs: sizes that work

• Host images on Imgur or similar and link the direct file URL (ending in .png, .jpg or .gif). SpigotMC loads them through its own image proxy.
• Keep GIFs under about 3 MB. In our experience bigger ones aren't served by the proxy and show as broken images. Short loops (5 to 8 seconds) around 600 px wide fit.
• Banners around 1000 px wide look sharp on desktop and scale down on phones.
• A few tall section images ("poster" panels with a heading, a screenshot and two lines of text) look polished. Keep each one well under a megabyte.

Mistakes that break a description

• Editing the BBCode the editor shows you after switching modes. SpigotMC converts between its visual editor and BBCode, and the round trip can break list indentation. Keep your description in a text file, edit that, and paste the whole thing every time.
• Line breaks. SpigotMC shows every line break you type. Write each paragraph on one line, or your text breaks in odd places on wide screens.
• Emojis. 4-byte emojis (🚀, 🔥…) are stripped when you save. Use simple symbols (★, ✔) or none.
• Everything coloured and centred. It looks like a 2012 forum signature. Black text, left-aligned, with one accent colour for section titles reads best.
• A changelog at the top. Put it in the Updates tab, where SpigotMC already keeps it.

Is the new page working?

Change the page, then watch whether more of the people who see it download it. SpigotMC only shows downloads, not views, so you can't tell from SpigotMC alone. A tracking image in the description fixes that: PluginAnalytics' listing tag counts views on SpigotMC and Modrinth, and next to downloads and the servers that install your plugin you see whether the new page converts better than the old one.

For everything else that brings downloads (tag lines, update rhythm, reviews, Modrinth and Hangar), see how to get more downloads on SpigotMC.