---
title: 리더보드
slug: world-sdk-guide-kr/4umwiv3E6yurK2q0k2u5F
docTags:
createdAt: 2024-09-02T08:34:13.135Z
---
## 리더보드 설정하기
리더보드는 각 플레이어의 순위와 최고 점수를 저장하고 관리하는 기능을 제공하는 모듈입니다.
### 1단계 : 리더보드 생성하기
리더보드를 생성하려면 ProjectSettings → Zepeto → ZepetoLeaderboard 메뉴에서 \[리더보드 정보 가져오기] 버튼을 선택하세요.
\[리더보드 추가]를 선택하여 새 리더보드를 추가하세요.
이미 존재하는 리더보드가 있다면, 설정 화면에 리더보드가 나타납니다.
### 2단계 : 리더보드 사용자 정의
\[리더보드 추가] 버튼을 선택하면 아래에 표시된 팝업 창이 나타납니다. 각 매개변수 값을 조정할 수 있습니다.
| **매개변수** | **설명** |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 이름 | 리더보드 이름 |
| 업데이트 규칙 | 점수 업데이트 규칙 |
| 최대 점수 | 사용자의 최고 점수를 기록합니다. |
| 최소 점수 | 사용자의 최저 점수를 기록합니다. |
| 점수 누적 | 사용자의 점수를 추가하고 기록으로 저장합니다. |
| ResetInfo(s) | 점수가 초기화될 기간을 설정할 수 있습니다.
- 이는 리더보드가 매 시즌 업데이트되어야 할 때 유용합니다.
- 점수는 기본적으로 초기화되지 않지만, 초기화 기간(매월, 매주, 매일)을 설정하여 조정할 수 있습니다. |
### 3단계 : 점수 초기화 설정
점수 초기화 규칙은 다음과 같습니다:
| **기간** | **설명** |
| ------ | ------------------------------------------------------------------------------------------- |
| 없음 | 점수가 초기화되지 않습니다 |
| 일 | 점수는 설정된 시간에 매일 초기화됩니다 (예: 일일 순위) |
| 주 | 점수는 설정된 날짜와 시간에 매주 초기화됩니다 (예: 주간 순위) |
| 월 | 점수는 설정된 날짜와 시간에 매월 초기화됩니다 (예: 월간 순위; 최대 일 값은 31이지만, 해당 월에 31일이 없으면 자동으로 해당 월의 마지막 날로 조정됩니다) |
### 4단계 : 리더보드 ID
ZEPETOScript와 리더보드를 사용하려면 리더보드 ID 정보가 필요합니다.
리더보드 정보를 액세스하려면 설정으로 이동할 수 있습니다(프로젝트 설정 메뉴에서 편집 아래 Zepeto → Zepeto 리더보드 → 편집으로 이동) 또는 ZEPETOScript API에서 로드할 수 있습니다.
:::hint{type="danger"}
- 재설정 규칙이 설정되면 리더보드를 수정할 수 없습니다.
- 재설정 규칙을 변경하려면 새 리더보드를 만들어야 합니다.
- 재설정 시간은 UTC+0를 기준으로 합니다. 오프셋이 제공되어 향후 시간대를 변경할 수 있습니다.
:::
## 점수 기록
LeaderboardAPI.SetScore()는 사용자의 점수를 리더보드에 기록하는 API입니다.
리더보드 ID, 점수 값, 완료 포인트 및 오류 포인트가 인수로 전달됩니다.
점수에 대한 사용자 정보는 자동으로 저장됩니다.
다음은 LeaderboardAPI.SetScore 함수를 로드하는 예입니다.
```typescript
LeaderboardAPI.SetScore(this.leaderBoardId, this.score, this.OnResult, this.OnError);
```
다음은 사용자의 점수를 리더보드로 가져오는 코드 템플릿입니다.
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { SetScoreResponse, LeaderboardAPI } from 'ZEPETO.Script.Leaderboard';
export default class SetScoreExample extends ZepetoScriptBehaviour {
public leaderboardId: string;
public score: number;
Start() {
LeaderboardAPI.SetScore(this.leaderboardId, this.score, this.OnResult, this.OnError);
}
OnResult(result: SetScoreResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
}
OnError(error: string) {
console.error(error);
}
}
```
## 순위 검색 세부정보
### 특정 범위의 순위 정보 가져오기
LeaderboardAPI.GetRangeRank() 함수를 사용하여 특정 범위의 순위 세부정보를 로드합니다.
리더보드 ID, 시작 순위, 마지막 순위, 리셋 규칙 및 지난 시즌의 순위 정보를 검색하기 위한 불리언 값과 완료 시점 및 오류 발생 시점의 콜백 함수가 인수로 전달됩니다.
순위 정보를 문의하는 사용자 정보가 자동으로 입력되며, 한 번의 문의로 최대 100개의 순위 정보를 처리할 수 있습니다 (예: 1로 페이지 매김~~100, 101~~200 형식으로 구현)
:::hint{type="danger"}
**❗️ 주의**
한 번에 100개 이상의 데이터가 로드되면 API 부하 문제 및 속도 제한으로 인해 제대로 작동하지 않을 수 있습니다.
:::
### 예제 함수 호출
LeaderboardAPI.GetRangeRank() 함수를 호출하는 예제는 다음과 같습니다:
```typescript
LeaderboardAPI.GetRangeRank(this.leaderboardId, this.startRank, this.endRank, this.resetRule, false, this.OnResult, this.OnError);
```
다음 코드는 특정 범위의 순위 정보를 로드하는 예제입니다.
OnResult에서 Member 값을 사용하여 프로필 사진을 로드할 수 있습니다.
:::hint{type="info"}
**📘 **다음 가이드를 참조하십시오. \[[유저 정보](docId\:FEzF1tvNnXNDjuI8c2YGZ)]
:::
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GetRangeRankResponse, LeaderboardAPI, ResetRule } from 'ZEPETO.Script.Leaderboard';
export default class GetRangeRankExample extends ZepetoScriptBehaviour {
public leaderboardId: string;
public startRank: number;
public endRank: number;
public resetRule: ResetRule;
Start() {
LeaderboardAPI.GetRangeRank(this.leaderboardId, this.startRank, this.endRank, this.resetRule, false,
this.OnResult, this.OnError);
}
OnResult(result: GetRangeRankResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
if (result.rankInfo.myRank) {
console.log(`member: ${result.rankInfo.myRank.member}, rank: ${result.rankInfo.myRank.rank},
score: ${result.rankInfo.myRank.score}, name: ${result.rankInfo.myRank.name}`);
}
if (result.rankInfo.rankList) {
for (let i = 0; i < result.rankInfo.rankList.length; ++i) {
const rank = result.rankInfo.rankList.get_Item(i);
console.log(`i: ${i}, member: ${rank.member}, rank: ${rank.rank}, score: ${rank.score}, name: ${rank.name}`);
}
}
}
OnError(error: string) {
console.error(error);
}
}
```
## 리더보드 세부정보 검색
### 모든 리더보드 검색
LeaderboardAPI.GetAllLeaderboards 함수를 사용하여 지정된 월드의 모든 리더보드 정보를 로드합니다.
완료 시점부터 오류 발생 시점까지의 콜백 함수가 인수로 전달됩니다.
LeaderboardAPI.GetAllLeaderboards 함수를 로드하는 예는 다음과 같습니다:
```typescript
LeaderboardAPI.GetAllLeaderboards(this.OnResult, this.OnError);
```
다음은 전체 리더보드 정보를 로드하는 예입니다.
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GetAllLeaderboardsResponse, LeaderboardAPI } from 'ZEPETO.Script.Leaderboard';
export default class GetAllLeaderboardExample extends ZepetoScriptBehaviour {
Start() {
LeaderboardAPI.GetAllLeaderboards(this.OnResult, this.OnError);
}
OnResult(result: GetAllLeaderboardsResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
if (result.leaderboards) {
for (let i = 0; i < result.leaderboards.length; ++i) {
const leaderboard = result.leaderboards[i];
console.log(`i: ${i}, id: ${leaderboard.id}, name: ${leaderboard.name}`);
}
}
}
OnError(error: string) {
console.error(error);
}
}
```
### 특정 리더보드 검색
LeaderboardAPI.GetLeaderboards 함수를 사용하여 특정 리더보드 정보를 로드합니다.
리더보드 ID, 완료 시간, 오류 발생 시간에 대한 콜백 함수가 인수로 전달됩니다.
LeaderboardAPI.GetLeaderboard 함수를 로드하는 예는 다음과 같습니다:
```typescript
LeaderboardAPI.GetLeaderboard(this.leaderboardId, this.OnResult, this.OnError);
```
다음은 특정 리더보드 정보를 로드하는 예입니다.
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GetLeaderboardResponse, LeaderboardAPI } from 'ZEPETO.Script.Leaderboard';
export default class GetLeaderboardExample extends ZepetoScriptBehaviour {
public leaderboardId: string;
Start() {
LeaderboardAPI.GetLeaderboard(this.leaderboardId, this.OnResult, this.OnError);
}
OnResult(result: GetLeaderboardResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
if (result.leaderboard) {
console.log(`id: ${result.leaderboard.id}, name: ${result.leaderboard.name}`);
}
}
OnError(error: string) {
console.error(error);
}
}
```
## 리더보드 사용 예시
- 다음은 공식 ZEPETO 월드 슬라임 파티에 적용된 리더보드의 예입니다.
- 특정 범위 내에서 순위를 가져오기 위해 API 호출을 설정하고 읽고 활용함으로써 UI에서 다음과 같이 구조화할 수 있습니다.
