# Scoreboard

`scoreboard` is read-only, since writing would only desync your view. Every function returns
`nil` with no world loaded.

| Function | Returns |
|----------|---------|
| `scoreboard.objectives()` | Every objective handle |
| `scoreboard.objective(name)` | One by internal name, or `nil` |
| `scoreboard.display(slot)` | The objective in a slot: `"sidebar"`, `"list"`, `"below_name"`, `"sidebar.team.red"`, … |
| `scoreboard.sidebar()` | The sidebar you actually see, team-color slot first |
| `scoreboard.teams()` | Every team handle |
| `scoreboard.team(name)` | One by internal name, or `nil` |
| `scoreboard.team_of(holder)` | Team of a score holder (player name), or `nil` |
| `scoreboard.holders()` | Every score holder name the scoreboard knows |

Objective and team handles are live; the text they return are [text](text.md) snapshots.

## Objective

| Method | Returns |
|--------|---------|
| `name()` | Internal name |
| `display_name()` | Sidebar title as text |
| `criterion()` | `"dummy"`, `"health"`, `"playerKillCount"`, … |
| `render_type()` | `"integer"` or `"hearts"` |
| `slots()` | Display slots it occupies, empty when hidden |
| `score(holder)` | One holder's score, or `nil` |
| `entries()` | Every score row, sorted like the sidebar: value descending, then name |

An entry is `{owner, value, hidden, name, decorated_name, formatted_value}`, where `name` is
the row text, `decorated_name` adds the team prefix, suffix and color, and `formatted_value`
is the score as the sidebar renders it. The vanilla sidebar skips `hidden` rows and shows at
most 15.

## Team

| Method | Returns |
|--------|---------|
| `name()`, `display_name()`, `formatted_name()` | Internal name, display name, bracketed form used in death messages |
| `prefix()`, `suffix()` | Text around member names |
| `color()`, `color_rgb()` | Formatting name (`"red"`, `"reset"` when unset) and `0xAARRGGBB`, or `nil` |
| `members()` | Member score holder names |
| `decorate(text_or_string)` | Wraps a name in the team prefix, suffix and color |
| `friendly_fire()`, `show_friendly_invisibles()` | Team flags |
| `nametag_visibility()`, `death_message_visibility()` | `"always"`, `"never"`, `"hideForOtherTeams"`, `"hideForOwnTeam"` |
| `collision_rule()` | `"always"`, `"never"`, `"pushOtherTeams"`, `"pushOwnTeam"` |

Entities answer `e:team()` and `e:team_color()` directly, which is what ESP coloring wants.

```lua
local sidebar = scoreboard.sidebar()
if sidebar then
    print(sidebar:display_name():string())
    for _, entry in ipairs(sidebar:entries()) do
        if not entry.hidden then
            print(entry.decorated_name:string() .. "  " .. entry.value)
        end
    end
end

local team = scoreboard.team_of("Notch")
if team then
    chat.print(team:decorate("Notch"):hover_text("on " .. team:name()))
end
```