---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.4
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: ko/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/ko/llms.txt

# 리더보드

게임 페이지에 상위 플레이어의 결과와 로그인한 사용자의 순위 내 위치를 보여주는 맞춤형 리더보드를 표시할 수 있습니다.

아래 요청이 작동하려면 다음 사항을 확인하세요.
* [SDK를 활성화 및 구성](https://yandex.com/dev/games/doc/ko/sdk/sdk-about.md#use)했으며 해당 개체를 `ysdk` 변수를 통해 사용할 수 있어야 합니다.
* 개발자 대시보드에서 리더보드를 [생성](https://yandex.com/dev/games/doc/ko/concepts/leaderboards.md)했습니다.

{% note alert "알림" %}

개발자 대시보드의 **기술 리더보드 이름** 필드에 해당 이름이 있는 리더보드가 없는 경우 요청은 404 오류를 반환합니다.

{% endnote %}

## 리더보드 설명

이름별로 리더보드에 대한 설명을 가져오려면 `ysdk.leaderboards.get_description()`을 사용합니다:

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

`callback: function` — 호출된 메서드의 핸들러입니다. 형태는 다음과 같습니다:

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

- `description: table` — 리더보드에 대한 설명입니다. 다음과 같은 속성을 포함합니다:

```lua
description: {
  app_id: string,
  dеfault: boolean,
  invert_sort_order: boolean,
  decimal_offset: integer,
  type: string,
  name: string,
  title: {
    en: string,
    ru: string
  }
}
```

**예시**

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

## 새 점수

{% note alert "알림" %}

인증된 사용자만이 요청할 수 있습니다. 필요한 경우 [인증](https://yandex.com/dev/games/doc/ko/sdk/sdk-player.md#auth)을 사용하십시오.

{% endnote %}

플레이어의 점수를 새로 설정하려면 `ysdk.leaderboards.set_score()`를 사용합니다::

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

{% note info "참고" %}

요청은 초당 한 번 이상 전송할 수 없습니다. 그렇지 않으면 오류와 함께 요청이 거부됩니다.

{% endnote %}

## 순위 가져오기

{% note alert "알림" %}

인증된 사용자만 요청이 가능합니다. 필요한 경우 [인증](https://yandex.com/dev/games/doc/ko/sdk/sdk-player.md#auth)을 하십시오.

{% endnote %}

사용자의 순위를 가져오려면 `ysdk.leaderboards.get_player_entry()`를 사용합니다:

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

`callback: function` — 호출된 메서드의 핸들러. 형태는 다음과 같습니다:

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

- `player_entry: table` — 사용자 순위입니다. 다음과 같은 속성을 포함합니다:

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

**예시**

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

## 리더보드 항목

사용자 순위를 표시하려면 `ysdk.leaderboards.get_entries()`를 사용합니다:

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

`callback: function`— 호출된 메서드의 핸들러입니다. 형태는 다음과 같습니다:

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

`entries: table` — 사용자 평점입니다. 속성은 다음과 같습니다:

```lua
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: ko/_includes/button-git-defold.md -->
<a href="https://github.com/yandex-games-plugins/defold">
  <span class="button">저장소</span>
</a>
<!-- endsource: ko/_includes/button-git-defold.md -->