Skip to main content

​
Overview

SimpleScoreboard provides an easy way to create and manage custom scoreboards for players. It handles automatic updates, supports color themes, and minimizes flickering.

​
Maximum lengths

  • Lines (1.8): 66 chars with color, 70 without
  • Lines (1.13+): 98 chars with color, 104 without
  • Lines (1.18+): 32,889 chars with color, 32,895 without
  • Title (1.8): 30 chars with color, 32 without
  • Title (1.13+): 126 chars with color, 128 without

​
Creating a scoreboard

public class MyScoreboard extends SimpleScoreboard {
    
    public MyScoreboard() {
        super("&6&lMY SERVER", 20); // Title, update delay in ticks
    }
    
    @Override
    protected void onUpdate() {
        // Called every update cycle
        clearRows();
        
        addRows(
            "",
            "&7Players: &f" + Bukkit.getOnlinePlayers().size(),
            "&7Time: &f" + System.currentTimeMillis(),
            ""
        );
    }
}

​
Constructors

​
SimpleScoreboard()

Creates a scoreboard with no title, updating every second. 
SimpleScoreboard scoreboard = new SimpleScoreboard();

​
SimpleScoreboard(String title)

Creates a scoreboard with a title, updating every second.
​
title
String
The scoreboard title. Supports color codes.
SimpleScoreboard scoreboard = new SimpleScoreboard("&6My Server");

​
SimpleScoreboard(String title, int updateDelayTicks)

Creates a scoreboard with a title and custom update interval.
​
title
String
The scoreboard title. Supports color codes.
​
updateDelayTicks
int
How often to update in ticks (20 = 1 second).
SimpleScoreboard scoreboard = new SimpleScoreboard("&6My Server", 40);
Scoreboards require Minecraft 1.7 or higher.

​
Methods

​
show

Shows the scoreboard to a player and starts the update task if not running.
​
player
Player
The player to show the scoreboard to.
scoreboard.show(player);

​
hide

Hides the scoreboard from a player and stops the update task if no viewers remain.
​
player
Player
The player to hide the scoreboard from.
scoreboard.hide(player);

​
isViewing

Checks if a player is currently viewing this scoreboard.
​
player
Player
The player to check.
​
isViewing
boolean
True if the player is viewing this scoreboard.
if (scoreboard.isViewing(player)) {
    scoreboard.hide(player);
}

​
setTitle

Sets the scoreboard title.
​
title
String
The new title. Automatically truncated if too long.
scoreboard.setTitle("&6&lNEW TITLE");

​
getTitle

Gets the current scoreboard title.
​
getTitle
String
The current title.
String title = scoreboard.getTitle();

​
addRows

Adds rows to the scoreboard.
​
entries
Object...
The rows to add. Maximum 15 rows total.
scoreboard.addRows(
    "",
    "&7Player: &f" + player.getName(),
    "&7Rank: &6VIP",
    ""
);
Maximum 15 rows can be added. An error will be thrown if you exceed this limit.

​
setRow

Changes a specific row by index.
​
index
int
The row index (0-based).
​
value
String
The new row value.
scoreboard.setRow(0, "&7Updated row");

​
getRows

Gets the list of rows that you can modify.
​
getRows
List<String>
The mutable list of rows.
List<String> rows = scoreboard.getRows();
rows.add("&7New row");

​
clearRows

Removes all rows from the scoreboard. 
scoreboard.clearRows();

​
removeRow (by index)

Removes a row at the specified index.
​
index
int
The row index to remove.
scoreboard.removeRow(2);

​
removeRow (by content)

Removes all rows that contain the specified text.
​
thatContains
String
Text to search for in rows.
scoreboard.removeRow("Player:");

​
setTheme

Sets a color theme for rows containing ”:” (key: value pairs).
​
primary
ChatColor
Color for the key (before the colon).
​
secondary
ChatColor
Color for the value (after the colon).
scoreboard.setTheme(ChatColor.GOLD, ChatColor.WHITE);
scoreboard.addRows(
    "Players: 10",    // Will be "&6Players: &f10"
    "Mode: survival"  // Will be "&6Mode: &fsurvival"
);

​
setUpdateDelayTicks

Sets how often the scoreboard updates.
​
updateDelayTicks
int
Update interval in ticks (20 = 1 second).
scoreboard.setUpdateDelayTicks(40); // Update every 2 seconds

​
getUpdateDelayTicks

Gets the current update interval.
​
getUpdateDelayTicks
int
The update delay in ticks.
int delay = scoreboard.getUpdateDelayTicks();

​
isRunning

Checks if the scoreboard is currently running and rendering.
​
isRunning
boolean
True if the update task is active.
if (scoreboard.isRunning()) {
    scoreboard.stop();
}

​
stop

Stops the scoreboard and removes it from all viewers. 
scoreboard.stop();

​
Protected methods

​
onUpdate

Called automatically every update cycle. Override to update scoreboard content. 
@Override
protected void onUpdate() {
    clearRows();
    
    addRows(
        "",
        "&7Online: &f" + Bukkit.getOnlinePlayers().size(),
        "&7Balance: &a$" + getBalance(player),
        ""
    );
}

​
replaceVariables

Called for each row to replace custom placeholders. Override for player-specific variables.
​
player
Player
The player viewing the scoreboard.
​
message
String
The row text.
​
replaceVariables
String
The row text with variables replaced.
@Override
protected String replaceVariables(Player player, String message) {
    return message
        .replace("{balance}", String.valueOf(getBalance(player)))
        .replace("{rank}", getRank(player));
}

​
Static methods

​
clearBoards

Clears all registered scoreboards. Usually called on reload. 
SimpleScoreboard.clearBoards();

​
clearBoardsFor

Removes all scoreboards for a specific player.
​
player
Player
The player to clear scoreboards for.
SimpleScoreboard.clearBoardsFor(player);

​
getRegisteredBoards

Gets all registered scoreboards.
​
getRegisteredBoards
List<SimpleScoreboard>
List of all registered scoreboards.
List<SimpleScoreboard> boards = SimpleScoreboard.getRegisteredBoards();

​
Complete example

public class StatsScoreboard extends SimpleScoreboard {
    
    public StatsScoreboard(Player player) {
        super("&6&l" + player.getName(), 20);
        
        setTheme(ChatColor.GRAY, ChatColor.WHITE);
    }
    
    @Override
    protected void onUpdate() {
        clearRows();
        
        addRows(
            "",
            "Rank: {rank}",
            "Balance: ${balance}",
            "",
            "&7play.example.com"
        );
    }
    
    @Override
    protected String replaceVariables(Player player, String message) {
        return message
            .replace("{rank}", getRank(player))
            .replace("{balance}", String.valueOf(getBalance(player)));
    }
    
    private String getRank(Player player) {
        return HookManager.getPlayerPermissionGroup(player);
    }
    
    private double getBalance(Player player) {
        return HookManager.getBalance(player);
    }
}

// Usage
@EventHandler
public void onJoin(PlayerJoinEvent event) {
    StatsScoreboard scoreboard = new StatsScoreboard(event.getPlayer());
    scoreboard.show(event.getPlayer());
}

@EventHandler
public void onQuit(PlayerQuitEvent event) {
    SimpleScoreboard.clearBoardsFor(event.getPlayer());
}

​
Notes

  • Scoreboards automatically handle color codes and long lines
  • The {player} variable is automatically replaced with the player’s name
  • Empty strings create blank lines for spacing
  • Use themes for consistent coloring of key-value pairs
  • The update task automatically stops when no players are viewing

Build docs developers (and LLMs) love

Get started for freeTalk to us