Scoreboard Library

Component sidebars are a high-level abstraction that allows for cleaner, more modular sidebar design. Instead of managing indices manually, you compose a sidebar using SidebarComponents (static lines, dynamic lines, or animated lines) and wrap them in a ComponentSidebarLayout.

To update the sidebar (e.g., when a dynamic value changes or an animation advances), you must call layout.apply(sidebar) on your Sidebar instance. This should typically be done inside a tick loop.

// 1. Create components
SidebarComponent staticLine = SidebarComponent.staticLine(Component.text("A static line"));

SidebarComponent lines = SidebarComponent.builder()
  .addComponent(staticLine)
  .addStaticLine(Component.text("Another static line"))
  .build();

// 2. Create the layout
ComponentSidebarLayout layout = new ComponentSidebarLayout(
  SidebarComponent.staticLine(Component.text("Sidebar Title")),
  lines
);

// 3. Apply to a sidebar
Sidebar sidebar = scoreboardLibrary.createSidebar();
layout.apply(sidebar);

To use scoreboard-library in a Maven project, add the scoreboard-library-api and scoreboard-library-implementation dependencies. The implementation should be scoped as runtime.

Important: You must shade and relocate these dependencies using the maven-shade-plugin.

If you are targeting server versions that do not have native Adventure support (such as Spigot or Paper versions older than 1.16.5), you must also include adventure-platform-bukkit.

<dependencies>
  <dependency>
    <groupId>net.megavex</groupId>
    <artifactId>scoreboard-library-api</artifactId>
    <version>2.8.2</version>
  </dependency>
  <dependency>
    <groupId>net.megavex</groupId>
    <artifactId>scoreboard-library-implementation</artifactId>
    <version>2.8.2</version>
    <scope>runtime</scope>
  </dependency>

  <!-- If targeting a server version without native Adventure support (Spigot or older than 1.16.5 Paper), add it as well: -->
  <dependency>
    <groupId>net.kyori</groupId>
    <artifactId>adventure-platform-bukkit</artifactId>
    <version>4.4.1</version>
  </dependency>
</dependencies>

To use scoreboard-library in a Gradle project, add mavenCentral() to your repositories. You must include both the api (for compilation) and the implementation (for runtime).

Important: You must shade and relocate these dependencies (using a tool like Shadow) to avoid classpath conflicts.

If you are targeting server versions that do not have native Adventure support (such as Spigot or Paper versions older than 1.16.5), you must also include adventure-platform-bukkit.

repositories {
  mavenCentral()
}

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

  // If targeting a server version without native Adventure support (Spigot or older than 1.16.5 Paper), add it as well:
  implementation("net.kyori:adventure-platform-bukkit:4.4.1")
}

The TeamManager allows you to create and manage Minecraft teams. A key feature is that you can show different properties (like prefixes or display names) of the same team to different players using TeamDisplay.

1. Create a TeamManager via scoreboardLibrary.createTeamManager().
2. Create a team with createIfAbsent(String name).
3. Use team.defaultDisplay() for standard behavior, or team.createDisplay() to create custom views.
4. Assign a specific display to a player using team.display(player, newTeamDisplay).
5. Always call teamManager.close() when finished.

TeamManager teamManager = scoreboardLibrary.createTeamManager();
ScoreboardTeam team = teamManager.createIfAbsent("team_name");

// Configure default display
TeamDisplay teamDisplay = team.defaultDisplay();
teamDisplay.displayName(Component.text("Team Display Name"));
teamDisplay.prefix(Component.text("[Prefix] "));
teamDisplay.suffix(Component.text(" [Suffix]"));
teamDisplay.playerColor(NamedTextColor.RED);
teamDisplay.addEntry(player.getName());

teamManager.addPlayer(player); // Adds player to default TeamDisplay of all teams

// Use a custom display for a specific player
TeamDisplay newTeamDisplay = team.createDisplay();
newTeamDisplay.displayName(Component.text("Other Team Display Name"));
team.display(player, newTeamDisplay);

// Cleanup
teamManager.close();

Use ObjectiveManager to create and display scoreboard objectives (e.g., below the player's name).

1. Create an ObjectiveManager via scoreboardLibrary.createObjectiveManager().
2. Create an objective with create(String name) and set its display name with .value(Component).
3. Set scores for players using .score(playerName, int).
4. Display the objective in a specific slot using .display(ObjectiveDisplaySlot slot, ScoreboardObjective objective).
5. Call objectiveManager.addPlayer(player) to make the objective visible to them.
6. Always call objectiveManager.close() when finished.

ObjectiveManager objectiveManager = scoreboardLibrary.createObjectiveManager();
ScoreboardObjective objective = objectiveManager.create("coolobjective");
objective.value(Component.text("Display name"));
objective.score(player.getName(), 69420);

// Display below the player's name
objectiveManager.display(ObjectiveDisplaySlot.belowName(), objective);

objectiveManager.addPlayer(player);

// Cleanup
objectiveManager.close();

If the built-in static, dynamic, or animated components are insufficient, you can implement the SidebarComponent interface. You must override the draw(@NotNull LineDrawable drawable) method, where you use the drawable object to write your component's content to a specific line.

public class KeyValueSidebarComponent implements SidebarComponent {
  private final Component key;
  private final Supplier<Component> valueSupplier;

  public KeyValueSidebarComponent(@NotNull Component key, @NotNull Supplier<Component> valueSupplier) {
    this.key = key;
    this.valueSupplier = valueSupplier;
  }

  @Override
  public void draw(@NotNull LineDrawable drawable) {
    var value = valueSupplier.get();
    var line = Component.text()
      .append(key)
      .append(Component.text(": "))
      .append(value.colorIfAbsent(NamedTextColor.AQUA))
      .build();

    drawable.drawLine(line);
  }
}