Powerful feature-packed Minecraft scoreboard library

• Features
• Adding to your project
  • Maven
  • Gradle
  • Gradle (Kotlin DSL)
• Basic usage
• Conditional lines
• Conditional titles
• Line limits
• Score number formatting
• Sidebar title animations
• Sidebar Pager

• No flickering (without using a buffer)
• Does not require any additional libraries/plugins on the server
• Easy to use
• Folia support
• Optionally supports Adventure API, MiniMessage, MiniPlaceholders
• Extremely fast, can be used asynchronously
• Cool inbuilt animations
• Inbuilt pager for showing multiple sidebars to the player
• Automatic score management system: sidebar reorders lines automatically
• Everything is at the packet level, so it works with other plugins using scoreboard and/or teams
• Supports up to 30 characters per line on 1.12.2 and below
• No character limit on 1.13 and higher
• Supports hex colors on 1.16 and higher
• Minimized NMS interaction, means that packets are constructed at the byte buffer level and then sent directly to the player's channel.

Instead of manually bundling the library into your JAR file, you can use the standalone plugin.

Simply run ./gradlew clean shadowJar and put the resulting JAR file located in bin folder into your plugins folder.

In other cases, you must use something like shadow (for Gradle) or maven-shade-plugin (for Maven).

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.CatCoderr</groupId>
    <artifactId>ProtocolSidebar</artifactId>
    <version>6.2.10-SNAPSHOT</version>
</dependency>

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.CatCoderr:ProtocolSidebar:6.2.10-SNAPSHOT'
}

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.CatCoderr:ProtocolSidebar:6.2.10-SNAPSHOT")
}

// create sidebar which uses Adventure API
// you can also use other methods from ProtocolSidebar class
// for another text providers such as BungeeCord Chat, MiniMessage...
Sidebar<Component> sidebar = ProtocolSidebar.newAdventureSidebar(
        TextIterators.textFadeHypixel("SIDEBAR"), this);

// let's add some lines
sidebar.addLine(
    Component.text("Just a static line").color(NamedTextColor.GREEN));
// add an empty line
sidebar.addBlankLine();
// also you can add updatable lines which applies to all players receiving this sidebar
sidebar.addUpdatableLine(
    player -> Component.text("Your Hunger: ")
        .append(Component.text(player.getFoodLevel())
        .color(NamedTextColor.GREEN))
    );

sidebar.addBlankLine();
sidebar.addUpdatableLine(
    player -> Component.text("Your Health: ")
        .append(Component.text(player.getHealth())
        .color(NamedTextColor.GREEN))
);
sidebar.addBlankLine();
sidebar.addLine(
    Component.text("https://github.com/CatCoderr/ProtocolSidebar")
        .color(NamedTextColor.YELLOW
));

// update all lines except static ones every 10 ticks
sidebar.updateLinesPeriodically(0, 10);

// ...

// show to the player
sidebar.addViewer(player);
// ...hide from the player
sidebar.removeViewer(player);

The visibility of these lines depends on the condition you set. If the condition is true, the line will be shown, otherwise it will be hidden. It's an updatable line, so it will update along with other updatable lines.

You can use scoreNumberFormat method in both ScoreboardObjective and SidebarLine classes to format score numbers.

This feature is available starting from 1.20.4 version.

// removes scores completely for all lines
sidebar.getObjective().scoreNumberFormatBlank();
// set's custom fixed text for all lines
sidebar.getObjective().scoreNumberFormatFixed(player -> Component.text("Test").color(NamedTextColor.BLUE));

// set's score number format for specific line (overrides objective's format)
var line = sidebar.addLine(Component.text("Some line").color(NamedTextColor.YELLOW));
line.scoreNumberFormatFixed(player -> Component.text("Test").color(NamedTextColor.BLUE));

The title can be chosen per player, so one Sidebar instance can show a different title to each viewer. For example a shorter title for legacy clients.

The simplest form is a function that receives the player:

sidebar.setTitle(player -> isVip(player) ? vipTitle : normalTitle);

For a list of conditions, use ConditionalTitle. Conditions are checked in the order they were added and the first match wins. otherwise is required, because a player matching no condition has to be given some title:

import static me.catcoder.sidebar.util.PlayerPredicates.*;
import static me.catcoder.sidebar.protocol.ProtocolConstants.*;

sidebar.setTitle(ConditionalTitle.<Component>create()
        .when(clientVersionAtMost(MINECRAFT_1_8), Component.text("Legacy"))
        .when(clientVersionAtLeast(MINECRAFT_1_19), Component.text("Modern"))
        .when(player -> player.getName().equals("playerA"), Component.text("Hello!"))
        .otherwise(Component.text("Default")));

Client versions are resolved through ViaVersion. Without ViaVersion installed, every player reports the server version.

The title is resolved for every objective packet, so it is re-evaluated whenever a player is added as a viewer. There is no automatic tick: if your conditions depend on state that changes later (rank, world, game phase), call sidebar.updateTitle().

setTitle snapshots the conditions, so mutating the ConditionalTitle afterwards has no effect.

PlayerPredicates also works with conditional lines:

sidebar.addConditionalLine(player -> Component.text("1.8 only"), clientVersionAtMost(MINECRAFT_1_8));

Setting a plain title again with setTitle(component) clears the conditional title.

To read the title as a specific player sees it, use getObjective().getDisplayName(player). The no-argument getDisplayName() returns the static title only.

A sidebar has two different limits:

• Sidebar.MAX_VISIBLE_LINES (15) how many lines the client renders. Beyond this it shows the highest scored lines and drops the rest.
• Sidebar.MAX_LINES_COUNT (22) how many lines a sidebar can hold. Every line permanently owns one unique invisible team entry, visible or not, and that alphabet runs out at 22.

Since conditional lines are hidden per player, a sidebar may hold more lines than the client renders, as long as no player ever sees more than 15 at once. addLine therefore only rejects what cannot work: a 23rd line of any kind, or a 16th line without a display condition. If a player does end up with more than 15 visible lines, a warning is logged once per sidebar.

Library has built-in title animations, but you can also create your own.

Animations also can be used in updatable lines:

TextIterator animation = TextIterators.textFadeHypixel("Hello World!");
SidebarLine<?> line = sidebar.addUpdatableLine(sidebar.asLineUpdater(animation));

line.updatePeriodically(0, 1, sidebar);

You can also use sidebar pager, which allows you to show player multiple pages of information.

Sidebar<Component> anotherSidebar = ProtocolSidebar.newAdventureSidebar(
        TextIterators.textFadeHypixel("ANOTHER SIDEBAR"), this);

Sidebar<Component> firstSidebar = ProtocolSidebar.newAdventureSidebar(
        TextIterators.textFadeHypixel("SIDEBAR"), this);

SidebarPager<Component> pager = new SidebarPager<>(
        Arrays.asList(firstSidebar, anotherSidebar), 20 * 5, this);

// add page status line to all sidebars in pager
pager.addPageLine((page, maxPage, sidebar) ->
        sidebar.addLine(Component.text("Page " + page + "/" + maxPage)
            .color(NamedTextColor.GREEN)));

pager.applyToAll(Sidebar::addBlankLine);

// ...add some lines

// show to player
pager.show(player);

// ...
// hide from the player
pager.hide(player);