> ## Documentation Index
> Fetch the complete documentation index at: https://velas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```java theme={null}
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.

```java theme={null}
// 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](/concepts/teams) 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](/concepts/sidebars) for full sidebar configuration details.

<Note>
  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.
</Note>

## Example

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

```java theme={null}
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.");
}
```