How the Scoreboard Object Works in VelaBoard

The Scoreboard ties together players, teams, and sidebars into one managed context. Learn its lifecycle, player registration, and lookup methods.

Scoreboard is the central manager object in VelaBoard. Every player you track, every team you configure, and every sidebar you display belongs to a Scoreboard instance. Rather than creating sidebars and teams in isolation, you work through a scoreboard so that all of these pieces stay coordinated in a single context.

The scoreboard lifecycle

You never instantiate Scoreboard directly. Instead, obtain one from ScoreboardHandler:

ScoreboardHandler handler = ScoreboardAPI.getHandler();
Scoreboard board = handler.createScoreboard();

Once you have a scoreboard, register players with addPlayer(Player). VelaBoard needs a player to be registered before it can display sidebars or assign them to teams through this scoreboard. When a player leaves or you no longer need to track them, call removePlayer(Player) to clean up.

// Register a player when they join
board.addPlayer(player);

// Remove them when they leave
board.removePlayer(player);

Players

Use getPlayers() to inspect who is currently registered. It returns a Collection<UUID> of all registered player IDs.

Method	Description
addPlayer(Player)	Registers a player with this scoreboard.
removePlayer(Player)	Unregisters a player and cleans up their sidebar state.
getPlayers()	Returns a Collection<UUID> of all registered players.

Teams

Teams group players and entities under shared visual properties like colors, prefixes, and collision rules. The Scoreboard manages the full team lifecycle.

Method	Description
team(String name)	Creates a team with the given name if it does not exist, or retrieves it if it does.
getTeam(String name)	Retrieves an existing team by name. Returns null if not found.
getTeamOf(Player)	Returns the team a player belongs to, or null if they are not on one.
hasTeam(String name)	Returns true if a team with that name exists.
removeTeam(String name)	Deletes the team by name.
clearTeams()	Removes all teams from this scoreboard.

See Team Management in VelaBoard for full team configuration details.

Sidebars

A scoreboard can manage both per-player sidebars (PlayerSidebar) and shared sidebars visible to multiple players (SharedSidebar) at the same time.

Method	Description
createPlayerSidebar(String title)	Creates a new PlayerSidebar with the given title.
createSharedSidebar(String title)	Creates a new SharedSidebar with an auto-generated ID.
createSharedSidebar(String id, String title)	Creates a new SharedSidebar with an explicit ID.
getSidebar(Player)	Returns the active Sidebar for the player (player or shared), or null.
getPlayerSidebar(Player)	Returns the player’s PlayerSidebar specifically, or null.
getSharedSidebar(Player)	Returns the SharedSidebar the player is part of, or null.
getSharedSidebar(String id)	Retrieves a SharedSidebar by its ID, or null.
hasSidebar(Player)	Returns true if the player has any active sidebar.
removePlayerFromSidebar(Player)	Removes the player from their current sidebar.

See Sidebar Types: Player vs Shared for full sidebar configuration details.

A single Scoreboard instance can manage multiple teams and sidebars simultaneously. You do not need separate scoreboard instances for different groups of players or different sidebar types.

Example

The following example creates a scoreboard, registers a player, creates a player sidebar, and checks whether the player has an active sidebar:

ScoreboardHandler handler = ScoreboardAPI.getHandler();
Scoreboard board = handler.createScoreboard();

// Register the player
board.addPlayer(player);

// Create and configure a player sidebar
PlayerSidebar sidebar = board.createPlayerSidebar("§6My Plugin");
sidebar.setLine(0, "§7Score: §f100");
sidebar.setPlayer(player);
sidebar.show();

// Confirm the sidebar is active
if (board.hasSidebar(player)) {
    player.sendMessage("Your sidebar is now visible.");
}