# Leaderboard

For examples on how to use, refer to [UIService](/scripting/bedwars-scripting/services/uiservice.md).

A leaderboard consists of entries (the rows displayed on the UI). Each entry has a key and a score associated with it.

* Keys refer to the names of what is being ranked on the leaderboard. You can add Players, Teams, or words (strings) to the leaderboard. 
* Scores are the number displayed next to each key. The leaderboard entries are automatically ordered by descending scores. The rank of a key is its place.

### Functions

#### getKeys(): Array<[Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string>

Returns the keys of the leaderboard.

#### addKey(key: [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string, initialScore: number | nil)

Adds a new key to the leaderboard of the given type. You can optionally give the key an initial score, which otherwise defaults to zero.

#### removeKey(key: [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string)

Removes the key from the leaderboard.

#### addScore(key: [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string, amount: number)

Adds the given amount to the current score of the key.

#### subScore(key: [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string, amount: number)

Subtracts the given amount from the current score of the key.

#### setScore(key: [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string, amount: number)

Sets the score of the key to the given amount.

#### getScore(key: [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string): number | nil

Returns the current score of the key. Returns nil if the key is not part of the leaderboard.

#### getPlace(place: number): [Player](/scripting/bedwars-scripting/objects/player.md) | [Team](/scripting/bedwars-scripting/objects/team.md) | string | nil

Returns the key located at the place. Returns nil if there is no key at the place.

#### clear()

Clears all leaderboard entries.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.easy.gg/scripting/bedwars-scripting/objects/leaderboard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.