Building Custom Scoreboards in Minecraft with scoreboard-library

Building a custom server? You'll want control over your scoreboard. scoreboard-library gives you that without stepping on other plugins' toes. It's a Java library that works at the packet level, so it plays nice with everything else on your server.

What scoreboard-library Does

At its core, this is a library for Paper and Spigot servers that lets you build and display scoreboards using Java code. But here's the thing that sets it apart: instead of trying to manage the scoreboard system directly through Bukkit's API (which can conflict with other plugins), it works directly with the network packets Minecraft clients receive.

Think of it like this: every scoreboard change is a message sent from server to client. Most plugins go through Bukkit's scoreboard API, which can create bottlenecks if multiple plugins are trying to update things at once. This library bypasses that and sends the exact packets needed, cleanly and efficiently.

It supports everything from simple static lines to complex dynamic scoreboards with team-based displays, and it works across a massive range of versions: Paper 1.7.10 all the way to 26.1.2. If you've got an older server or a newer one, this'll work.

Why This Matters for Your Server

The biggest headache with scoreboards on multiplayer servers is plugin conflicts. You've probably had this happen: install a shop plugin, a scoreboard plugin, an economy plugin... and suddenly the scoreboard flickers or stops working because two plugins are fighting over the same data. This library dodges that entirely because it operates at the packet level, meaning it doesn't care what other plugins are doing.

Another real advantage is performance. Everything is fully asynchronous, so updating scoreboards won't stall your main server thread. If you're running on tight hardware (or just want to keep your tick rate clean), that matters.

For modern servers (1.20.4+), you get access to newer features like score display names and custom score formatting, which the standard Bukkit API doesn't expose. And if you're using Folia (Paper's experimental parallelized server), this library supports it, though you'll need to handle thread safety yourself (more on that later).

There's also ViaVersion support built in. Here's the thing, if players on older clients (1.12.2) connect to a newer server through ViaVersion, the library automatically optimizes the packets sent to them to maximize sidebar line length. That's the kind of detail that shows real server admin understanding.

Getting It Set Up

Installation depends on whether you're using Gradle or Maven. Here's the Gradle approach (the modern default for most plugin devs):

repositories {
 mavenCentral()
}

dependencies {
 implementation("net.megavex:scoreboard-library-api:2.7.4")
 runtimeOnly("net.megavex:scoreboard-library-implementation:2.7.4")
}

If you're targeting older Paper versions without native Adventure support, add this too:

implementation("net.kyori:adventure-platform-bukkit:4.4.1")

Make sure you shade and relocate these dependencies in your final JAR (Shadow plugin is the standard choice).

For Maven users, it's similar but in XML format (the repo has docs for that). Once you've got it in your build config, initialization is simple:

ScoreboardLibrary scoreboardLibrary;
try {
 scoreboardLibrary = ScoreboardLibrary.loadScoreboardLibrary(plugin);
} catch (NoPacketAdapterAvailableException e) {
 scoreboardLibrary = new NoopScoreboardLibrary();
}

On plugin shutdown, call scoreboardLibrary.close() to clean up. That's the bare-bones setup.

The Features That Make It Worth Using

Sidebars are the main thing. You can have up to 42 characters per line on older clients (depends on formatting), and essentially no limit on newer versions. That means you can display meaningful information, not just truncated snippets.

Teams are another powerful feature. You can show different scoreboard properties to different players. One player sees one team display, another sees something else based on your logic. It's genuinely useful for things like faction servers or RPG setups where different players see different information.

The library also handles translatable components automatically. If your server uses Minecraft's built-in translation system, this library will translate scoreboard text for each player based on their client language settings. It even updates automatically if they change their language in game settings.

And because it uses the Adventure library, you get full color and formatting support. Component-based building means you're not limited to old-school color codes.

Dynamic updates are fully async, so you can safely update scoreboards from anywhere in your code without worrying about thread safety issues on the main thread.

Where It Gets Tricky

First thing: if you're running Folia, Sidebar and TeamManager objects aren't thread-safe. You need to add synchronization to ensure they're only accessed from one thread. It's not a deal-breaker, but it's something you need to architect around.

Second, version compatibility is broad but not universal. The library supports 1.7.10 to 26.1.2, but if you're on an unsupported version, you get the no-op fallback (it won't error, but scoreboards just won't display). So that project maintainer updates the supported list as new versions release, so check the latest release notes.

Third (and this caught me initially): you need to handle shading and dependency relocation correctly. If you don't shade and relocate the dependencies properly, you'll run into conflicts if another plugin also depends on Adventure or the library. It's standard plugin development practice, but if you're new to plugin dev, it's a step that's easy to miss.

Also, remember to call sidebar.close() when you're done with a sidebar. If you forget, you're leaving packet handlers open, which could accumulate memory leaks over time on long-running servers.

Should You Use This?

If you're building a plugin that needs custom scoreboards and you want to avoid the mess of conflicting APIs, this is genuinely one of the best options available. The packet-level approach is clever, the async design is solid, and the feature set is full.

If your server is simple and you only need one scoreboard that never conflicts with anything else, you might be fine with Bukkit's built-in system. But the moment you start adding other plugins, you'll wish you'd used this.

One more thing: the project is actively maintained (latest release is 2.7.4 as of April 2026), and the Discord community is responsive. If you hit a wall, there's actual support.

For server admins looking to fine-tune player experience, or plugin developers building the next generation of Paper server plugins, this is worth the setup time. And if you need help managing your server's configuration or player data, minecraft.how has some useful tools like a Minecraft whitelist creator and a block search tool that complement custom server setups.