리더보드

17 분

리더보드 설정하기

리더보드는 각 플레이어의 순위와 최고 점수를 저장하고 관리하는 기능을 제공하는 모듈입니다.

1단계 : 리더보드 생성하기

리더보드를 생성하려면 ProjectSettings → Zepeto → ZepetoLeaderboard 메뉴에서 [리더보드 정보 가져오기] 버튼을 선택하세요.

[리더보드 추가]를 선택하여 새 리더보드를 추가하세요.

이미 존재하는 리더보드가 있다면, 설정 화면에 리더보드가 나타납니다.

2단계 : 리더보드 사용자 정의

[리더보드 추가] 버튼을 선택하면 아래에 표시된 팝업 창이 나타납니다. 각 매개변수 값을 조정할 수 있습니다.

매개변수	설명
이름	리더보드 이름
업데이트 규칙	점수 업데이트 규칙
최대 점수	사용자의 최고 점수를 기록합니다.
최소 점수	사용자의 최저 점수를 기록합니다.
점수 누적	사용자의 점수를 추가하고 기록으로 저장합니다.
ResetInfo(s)	점수가 초기화될 기간을 설정할 수 있습니다. - 이는 리더보드가 매 시즌 업데이트되어야 할 때 유용합니다. - 점수는 기본적으로 초기화되지 않지만, 초기화 기간(매월, 매주, 매일)을 설정하여 조정할 수 있습니다.

3단계 : 점수 초기화 설정

점수 초기화 규칙은 다음과 같습니다:

기간	설명
없음	점수가 초기화되지 않습니다
일	점수는 설정된 시간에 매일 초기화됩니다 (예: 일일 순위)
주	점수는 설정된 날짜와 시간에 매주 초기화됩니다 (예: 주간 순위)
월	점수는 설정된 날짜와 시간에 매월 초기화됩니다 (예: 월간 순위; 최대 일 값은 31이지만, 해당 월에 31일이 없으면 자동으로 해당 월의 마지막 날로 조정됩니다)

4단계 : 리더보드 ID

ZEPETOScript와 리더보드를 사용하려면 리더보드 ID 정보가 필요합니다.

리더보드 정보를 액세스하려면 설정으로 이동할 수 있습니다(프로젝트 설정 메뉴에서 편집 아래 Zepeto → Zepeto 리더보드 → 편집으로 이동) 또는 ZEPETOScript API에서 로드할 수 있습니다.

재설정 규칙이 설정되면 리더보드를 수정할 수 없습니다.

재설정 규칙을 변경하려면 새 리더보드를 만들어야 합니다.

재설정 시간은 UTC+0를 기준으로 합니다. 오프셋이 제공되어 향후 시간대를 변경할 수 있습니다.

점수 기록

LeaderboardAPI.SetScore()는 사용자의 점수를 리더보드에 기록하는 API입니다. 리더보드 ID, 점수 값, 완료 포인트 및 오류 포인트가 인수로 전달됩니다.

점수에 대한 사용자 정보는 자동으로 저장됩니다.

다음은 LeaderboardAPI.SetScore 함수를 로드하는 예입니다.

LeaderboardAPI.SetScore(this.leaderBoardId, this.score, this.OnResult, this.OnError);

다음은 사용자의 점수를 리더보드로 가져오는 코드 템플릿입니다.

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 형식으로 구현)

❗️ 주의 한 번에 100개 이상의 데이터가 로드되면 API 부하 문제 및 속도 제한으로 인해 제대로 작동하지 않을 수 있습니다.

예제 함수 호출

LeaderboardAPI.GetRangeRank() 함수를 호출하는 예제는 다음과 같습니다:

LeaderboardAPI.GetRangeRank(this.leaderboardId, this.startRank, this.endRank, this.resetRule, false, this.OnResult, this.OnError);

다음 코드는 특정 범위의 순위 정보를 로드하는 예제입니다. OnResult에서 Member 값을 사용하여 프로필 사진을 로드할 수 있습니다.

📘 다음 가이드를 참조하십시오. [유저 정보]

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 함수를 로드하는 예는 다음과 같습니다:

LeaderboardAPI.GetAllLeaderboards(this.OnResult, this.OnError);

다음은 전체 리더보드 정보를 로드하는 예입니다.

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 함수를 로드하는 예는 다음과 같습니다:

LeaderboardAPI.GetLeaderboard(this.leaderboardId, this.OnResult, this.OnError);

다음은 특정 리더보드 정보를 로드하는 예입니다.

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에서 다음과 같이 구조화할 수 있습니다.