In this blog post, I’ll explain how to create and customize scoreboards using the Spigot/Paper API. Whether you’re a beginner or an experienced developer, this guide will help you understand the key components. Please note, that some features are only available from 1.20.3.

What is a Scoreboard?

A scoreboard in Minecraft is made up of several components, which can be confusing at first. Let’s break them down:

1. ScoreboardManager

The ScoreboardManager manages all the Scoreboards on the Spigot/Paper server. You can use it to:

• Create a new scoreboard per player with getNewScoreboard().
• Access the main server scoreboard with getMainScoreboard().

2. Objective

The objective defines the goal of the scoreboard. It consists of:

• Name: The internal name of the objective. Must be unique!
• Criteria: What the scoreboard tracks.
• DisplayName: The visible title in the sidebar/belowName.
• RenderType (optional): How scores are displayed.
• NumberFormat (optional + only for Paper): Styled Score.

/scoreboard objectives add [objective/internal name] [criteria] [displayName]

2.1 Criteria

The criteria determine whether scores update automatically or manually:

• Built-in Trackers: like health, armor,…
• Custom Criteria: with “dummy“, but you’ll need to create and manage the scores yourself!

2.2 DisplaySlot

This determines where the scoreboard appears:

• Sidebar: The right-side panel per player or per team (Spigot and Paper use different naming!)
• BelowName:  Shown under player nametags (e.g., HP in BedWars).
• PlayerList: Appears next to names in the tab menu.

2.3 RenderType:

Scores can be displayed as:

• Numbers (Default)
• Hearts (Only works in PLAYER_LIST and requires Survival/Hardcore mode).

/scoreboard objectives add <name> health

/scoreboard objectives setdisplay list <name>

/scoreboard objectives modify <name> rendertype hearts

2.4 NumberFormat

The NumberFormat stylizes the numeric score. There are several cool options:

• blank()
• fixed(ComponentLike)
• styled(Style)
• And more, but not going to cover.

2.4.1 Blank

The blank function clears the score, making it completely empty.

objective.numberFormat(blank());

2.3.2 Fixed

Changes the numeric scores into text components:

objective.numberFormat(NumberFormat.fixed(Component.text(" points")
				.color(NamedTextColor.GRAY)
				.decoration(TextDecoration.BOLD, true)));

2.4.3 Styled

This allows you to style your score!

// Create a text style with bold and blue
Style scoreStyle = Style.style()
				.color(NamedTextColor.BLUE)
				.decoration(TextDecoration.BOLD, true)
				.build();

// Apply the styled number format
		objective.numberFormat(NumberFormat.styled(scoreStyle));

// Add some scores
		objective.getScore("Player1").setScore(100);  // Will appear as bold blue "100"
		objective.getScore("Player2").setScore(200);  // Will appear as bold blue "200"

You could even create fancy styles like:

Style fancyStyle = Style.style()
    .color(NamedTextColor.AQUA)
    .decoration(TextDecoration.BOLD, true)
    .decoration(TextDecoration.ITALIC, false)
    .font(Key.key("minecraft:alt"))
    .build();

3. Scores

Lastly, you can add more lines to the scoreboard with scores. Scores can be added to an objective with setScore().

Changing the entry (the text before the score) can also be easily done with scores:

    // Remove old entry
    scoreboard.resetScores("oldWord");

    // Add new entry
    Score newScore = objective.getScore("newWord");
    newScore.setScore(yourScore);

/scoreboard players set [player] [objective/internal name] [score]

What about Teams?

Teams open up a whole new range of possibilities with scoreboards. They’re meant for grouping people and provide cool features like:

• Prefix and Suffix
• Team Options
• Team-Specific DisplaySlot
• Team-Specific Criteria

⚠ Important Note: If a player leaves, they lose their team and scores!

Prefix and Suffix

A prefix and suffix could provide extra information about the team. For example:

[Puddingland] <username> Squad Alpha

Team Options

Teams can have lots of tweaks. Find them all here.

Team-Specific DisplaySlot

The displaySlot can be configured that the sidebar scoreboard is only visible for a specific team. Find all the possibilities here. Note, that the Paper and Spigot API naming don’t match!

To create a team, you need to assign the color with setColor(). So, naming your team “blue” won’t work. Also, don’t forget to add the player to your colored team!

Team team = scoreboard.registerNewTeam("TheBestBlueTeam");  
team.setPrefix("[Blue] "); // Don’t forget the trailing space!  
team.setSuffix(" ★");  
team.setColor(ChatColor.BLUE);  

// Add a player to the team  
Player player = Bukkit.getPlayer("PlayerName"); //Change this...
team.addEntry(player.getName());  

Specific Team Criteria

The amount of times your team is killed or the amount of times you kill a team, is specified with TEAM_KILL_COLOR or KILLED_BY_TEAM_COLOR.

If you’ve got any questions about scoreboards in Spigot/Paper or suggestions, let me know!