---
title: "scoreboard"
---

> Documentation Index
> Fetch the complete documentation index at: https://aesthetic-docs.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# scoreboard

Server-synced scoreboard: objectives, scores, display slots and teams. **Read-only** —
writes would only desync your view. Every function returns `nil` when no world is loaded.

| Function | Returns |
|----------|---------|
| `scoreboard.objectives()` | All objective handles |
| `scoreboard.objective(name)` | Objective by internal name, or `nil` |
| `scoreboard.display(slot)` | Objective in a slot: `"sidebar"`, `"list"`, `"below_name"`, `"sidebar.team.red"`, … |
| `scoreboard.sidebar()` | Sidebar you currently see (team-color slot if set, else plain sidebar) |
| `scoreboard.teams()` | All team handles |
| `scoreboard.team(name)` | Team 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. Text they return are [text](/text) snapshots.

## Objective handle

| Method | Meaning |
|--------|---------|
| `name` | Internal name |
| `display_name` | Sidebar title as text |
| `criterion` | `"dummy"`, `"health"`, `"playerKillCount"`, … |
| `render_type` | `"integer"` or `"hearts"` |
| `slots` | Display slots this objective occupies (empty when hidden) |
| `score(holder)` | One holder's score, or `nil` |
| `entries` | All score rows, sorted like the sidebar (value desc, then name) |

Each entry is `{owner, value, hidden, name, decorated_name, formatted_value}`:

- `name` — row display text
- `decorated_name` — with team prefix/suffix/color
- `formatted_value` — score as the sidebar renders it

The vanilla sidebar skips `hidden` rows and shows at most 15.

## Team handle

| Method | Meaning |
|--------|---------|
| `name`, `display_name`, `formatted_name` | Internal name; display name; bracketed form for 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 team prefix/suffix/color |
| `friendly_fire`, `show_friendly_invisibles` | Team flags |
| `nametag_visibility`, `death_message_visibility` | `"always"`, `"never"`, `"hideForOtherTeams"`, `"hideForOwnTeam"` |
| `collision_rule` | `"always"`, `"never"`, `"pushOtherTeams"`, `"pushOwnTeam"` |

Entities also answer: `e:team()` and `e:team_color()` — handy for ESP coloring.

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

Source: https://aesthetic-docs.pages.dev/scoreboard/index.md