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

# Scoreboard

> Per-player sidebar scoreboards without hand-rolling team/objective plumbing.

`xyz.refineryteam.refinerycore.api.scoreboard` provides a per-player sidebar scoreboard abstraction that handles the objective/team plumbing (including per-line team prefixes) so you can push plain strings or Components as lines.

## `ScoreboardManager`

The entry point — tracks one `Scoreboard` per player and, optionally, a repeating update task per player.

```java MainScoreboard.java icon="java" theme={"system"}
ScoreboardManager boards = new ScoreboardManager(plugin);

boards.create(player, sb -> sb
    .title("<gradient:blue:aqua><b>MyServer")
    .lines(
        "",
        "<gray>Rank: <white>%rank%",
        "<gray>Coins: <gold>%coins%",
        ""
    ));

boards.startUpdating(player, 20L, sb -> sb
    .line(1, "<gray>Rank: <white>" + getRank(player))
    .line(2, "<gray>Coins: <gold>" + getCoins(player)));
```

| Method                                                     | Description                                                                                                              |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `create(player, Consumer<ScoreboardBuilder>)`              | Creates (replacing any existing board) and immediately shows a scoreboard for the player, configured via the builder DSL |
| `startUpdating(player, periodTicks, Consumer<Scoreboard>)` | Starts a repeating task that re-applies the given mutator every `periodTicks`, for dynamic content (timers, live stats)  |
| `stopUpdating(player)`                                     | Cancels the repeating update task, if any                                                                                |
| `get(player)`                                              | Returns the player's current `Scoreboard`, or `null`                                                                     |
| `has(player)`                                              | Whether the player currently has a tracked scoreboard                                                                    |
| `remove(player)`                                           | Stops updating and destroys the player's scoreboard                                                                      |
| `shutdown()`                                               | Cancels every tracked update task and destroys every tracked board — **call this from your plugin's `onDisable()`**      |

<Warning>
  `startUpdating`'s repeating task automatically calls `stopUpdating` and stops itself if the player goes offline or their board is removed mid-task — but you should still call `shutdown()` on plugin disable to avoid leaking tasks across a reload.
</Warning>

## `Scoreboard`

The underlying per-player board, obtainable via `ScoreboardManager#get` or by building one directly with `Scoreboard.builder(player)`.

```java MainScoreboard.java icon="java" theme={"system"}
scoreboard.title("<red>Updated Title")
    .line(0, "<gray>New top line")
    .removeLine(3);
```

| Method                                                   | Description                                                                         |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `title(String)` / `title(Component)`                     | Updates the objective's display name                                                |
| `lines(String...)` / `lines(List<String>)`               | Replaces **every** line at once, top to bottom (index 0 is the top line)            |
| `linesComponent(List<Component>)`                        | Same, from pre-built Components                                                     |
| `line(int index, String)` / `line(int index, Component)` | Sets a single line by index, creating it if it doesn't exist yet                    |
| `removeLine(int index)`                                  | Removes a specific line                                                             |
| `clearLines()`                                           | Removes every line                                                                  |
| `getLine(int index)`                                     | Returns the `Component` at that index, or `null`                                    |
| `size()`                                                 | Number of currently-set lines                                                       |
| `player()`                                               | The owning player                                                                   |
| `destroy()`                                              | Restores the player's main scoreboard and unregisters everything this instance owns |

<Note>
  The scoreboard supports at most **15 lines** (`MAX_LINES`) — Minecraft's own sidebar rendering limit. Calling `linesComponent` with more than 15 components throws an `IllegalArgumentException`.
</Note>

Internally, each line is backed by its own `Team` with a unique invisible-color-code "entry" per index, so lines don't collide with real player/team names and can be updated independently without disturbing other lines' scores.

## `ScoreboardBuilder`

Used inside `ScoreboardManager#create`'s configurer lambda for a fluent one-shot setup:

```java MainSCoreboard.java icon="java" theme={"system"}
boards.create(player, sb -> sb
    .title("<bold>Server")
    .line("<gray>Welcome!")
    .blank()
    .line("<white>Rank: <yellow>VIP"));
```

| Method                               | Description                                                                  |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| `title(String)` / `title(Component)` | Sets the board's title                                                       |
| `line(String)` / `line(Component)`   | Appends a line                                                               |
| `blank()`                            | Appends an empty line — shorthand for `line("")`                             |
| `build()`                            | Constructs the final `Scoreboard` (called internally by `ScoreboardManager`) |