リーダーボード

16 分

リーダーボードの設定

リーダーボードは、各プレイヤーのランキングとハイスコアを保存および管理するための機能を提供するモジュールです。

ステップ 1 : リーダーボードを作成する

リーダーボードを作成するには、ProjectSettings → Zepeto → ZepetoLeaderboard メニューの [Get LeaderboardInfo] ボタンを選択します。

[Add Leaderboard] を選択して新しいリーダーボードを追加します。

既に存在するリーダーボードがある場合、そのリーダーボードが設定画面に表示されます。

ステップ 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、開始ランキング、最終ランキング、リセットルール、前シーズンのランキング情報を取得するためのブール値、および完了時とエラー発生時のコールバック関数が引数として渡されます。

ランキング情報を照会するユーザー情報が自動的に入力され、1回の照会で最大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からメンバー値を使用して、プロフィール写真をロードできます。

📘 以下のガイドを参照してください。 [ユーザー情報]

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内で次のように構成できます。