---
metadata:
  - name: generator
    content: Diplodoc Platform v5.55.2
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/hi/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/ko/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/ru/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/tr/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/vi/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/zh/sdk/defold/leaderboard.md
  - href: en/sdk/defold/leaderboard.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/en/llms.txt

# Leaderboards

<!-- source: en/_includes/script-common.md -->
<!-- source: en/_includes/script/index-js.md -->

<!-- endsource: en/_includes/script/index-js.md -->

<!-- source: en/_includes/script/requirements-js.md -->

<!-- endsource: en/_includes/script/requirements-js.md -->

<!-- source: en/_includes/script/image-modal-js.md -->

<!-- endsource: en/_includes/script/image-modal-js.md -->
<!-- endsource: en/_includes/script-common.md -->

You can display personalized leaderboards on the game page showing the top players' results and the user's position in the ranking.

For the requests below to work, make sure that:

* You've [enabled and configured the SDK](https://yandex.com/dev/games/doc/en/sdk/sdk-about.md#use), and its object is available via the `ysdk` variable.
* You've [created](https://yandex.com/dev/games/doc/en/concepts/leaderboards.md) a leaderboard in the Games Console.

{% note alert %}

If there is no leaderboard with the corresponding name in the **Technical leaderboard name** field in the console, requests will result in a 404 error.

{% endnote %}

## Leaderboard description {#leaderboard-description}

To get a description of a leaderboard by its name, use the `ysdk.leaderboards.get_description()` method:

```lua showLineNumbers
ysdk.leaderboards.get_description(
    leaderboard_name: string,
    callback: function
)
```

`callback: function` — the handler for the invoked method. It looks like:

```lua
function(self, description: table|nil): nil
```

- `description: table` — description of the leaderboard. Contains properties:

```lua showLineNumbers
description: {
  app_id: string,
  default: boolean,
  invert_sort_order: boolean,
  decimal_offset: integer,
  type: string,
  name: string,
  title: {
    en: string,
    ru: string
  }
}
```

**Example**

```lua showLineNumbers
function display_leaderboard()
  ysdk.leaderboards.get_description("highscores",
    function (self, description)
      if description then
        print(
          description.name,
          description.title.en
        )
    end
  end)
end
```

## New score {#new-score}

{% note alert %}

The request is available only for authorized users. If necessary, use [authorization](https://yandex.com/dev/games/doc/en/sdk/defold/player-data.md#auth).

{% endnote %}

To set a new score for a player, use the `ysdk.leaderboards.set_score()` method:

```lua showLineNumbers
ysdk.leaderboards.set_score(
    leaderboard_name: string,
    score: integer,
    extraData: string|nil
)
```

{% note info %}

The request can only be sent once per second, otherwise it will be rejected with an error.

{% endnote %}

## Getting a ranking {#getting-ranking}

{% note alert %}

The request is available only for authorized users. If necessary, use [authorization](https://yandex.com/dev/games/doc/en/sdk/defold/player-data.md#auth).

{% endnote %}

To get a user's ranking, use the `ysdk.leaderboards.get_player_entry()` method:

```lua showLineNumbers
ysdk.leaderboards.get_player_entry(
    leaderboard_name: string,
    callback: function
)
```

`callback: function` — handler of the invoked method. It looks like:

```lua
function(self, player_entry: table|nil): nil
```

- `player_entry: table` — user rating. Contains properties:

```lua showLineNumbers
player_entry: {
  score: integer,
  extraData: string,
  rank: integer,
  avatar_src: {
    small: string,
    medium: string,
    large: string,
  },
  avatar_srcset: {
    small: string,
    medium: string,
    large: string,
  },
  lang: string,
  public_name: string,
  unique_id: string,
  formatted_score: string
}
```

**Example**

```lua showLineNumbers
function display_high_score()
  ysdk.leaderboards.get_player_entry("highscores",
    function (self, player_entry)
      if player_entry then
        print("highscore: " .. player_entry.score)
      end
    end)
end
```

## Leaderboard entries {#leaderboard-entries}

To display users' ratings, use the `ysdk.leaderboards.get_entries()` method:

```lua showLineNumbers
ysdk.leaderboards.get_entries(
    leaderboardName: string,
    callback: function,
    options: {
        include_user: boolean|nil,
        quantity_around: number|nil,
        quantity_top: number|nil
    }
)
```

`callback: function`— the handler of the called method. It looks like:

```lua
function(self, entries: table|nil): nil
```

`entries: table` — users' leaderboard. Contains properties:

```lua showLineNumbers
entries: {
  leaderboard: {
    ...
  },
  ranges: [
    {
      start: integer,
      size: integer
    }
  ],
  userRank: integer,
  entries: [
    {
      score: integer,
      extraData: string,
      rank: integer,
      avatar_src: {
        small: string,
        medium: string,
        large: string,
      },
      avatar_srcset: {
        small: string,
        medium: string,
        large: string,
      },
      lang: string,
      public_name: string,
      unique_id: string,
      formatted_score: string
    },
    ...
  ]
}
```

---


<!-- source: en/_includes/button-git.md -->
<a href="https://github.com/yandex-games-plugins/defold">
  <span class="button">Repository</span>
</a>
<!-- endsource: en/_includes/button-git.md -->