基本的なリーダーボードを作成する

このチュートリアルでは、新しいリーダーボードサービスを使用して基本的なリーダーボードを作成する方法を紹介します。まず、できるだけ多くの敵を倒し、倒されるまでプレイすることが目的のアーケードゲームを例に始めます。倒されたときに、スコアが割り当てられます。ここでは、このゲームで誰が最強のプレイヤーかを判断するためのリーダーボードを作成します。

リーダーボードを作成する

最初の手順は、プレイヤーをランキング付けするための主要な要素を含むリーダーボード定義を作成することです。今回のアーケードゲームでは、スコア用の列が 1 つあれば十分です。以下の例では、C# SDK を使用してリーダーボード定義を作成する方法を示します。

public static async Task CreateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateLeaderboardDefinitionRequest leaderboardDefinitionRequest = new CreateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = 1000,
        EntityType = "title_player_account",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "arcadeScore",
                SortDirection = LeaderboardSortDirection.Descending,
            }          
        }
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest);
}

次に、この例の主要な要素をいくつか説明します。

AuthenticationContext: このパラメーターは、サービスへの各要求の認証をすべて処理します。詳細な説明については、次のページを参照してください: クイックスタートリーダーボード。
Name: このパラメーターはリーダーボード定義を識別するのに役立ちます。情報を取得するための他の要求にも使用されるため、意味のある名前を選ぶことが重要です。また、この名前は一意である必要があるため、リーダーボードを作成するたびに新しいものを使用する必要があります。
EntityType: このパラメーターは、リーダーボードを作成する対象となるエンティティの種類を指定します。詳細については次を参照してください: エンティティプログラミングモデル。
- title_player_acount: このエンティティの種類は、PlayFab 内のプレイヤーを指します。プレイヤーを作成するには、LoginAsPlayer メソッドを使用できます。詳細は次を参照してください: クイックスタート。
- group: このエンティティの種類は、プレイヤーのグループを指します。通常、この概念は「クラン」や「ギルド」などのゲームに適用されます。詳細については次を参照してください: グループリーダーボード。
- external: このエンティティの種類は、リーダーボードにカスタムデータを追加するために使用します。各行は PlayFab 上の何かに結び付いている必要はなく、独自のデータです。文字列であれば、独自の識別子を EntityId フィールドで使用できます。
- master_player_account: このエンティティの種類は、タイトルをまたぐプレイヤーを指します。この概念は、スタジオが複数のタイトルを持ち、あるタイトルから別のタイトルへ移動したプレイヤーや、同じスタジオの複数のタイトルをプレイしているプレイヤーがいる場合に適用されます。この概念に基づいて、同じスタジオの複数タイトルにまたがるプレイヤーのリーダーボードを作成できます。マスタープレイヤーアカウント ID (PlayFabId とも呼ばれます) を使用して EntityId にマッピングします。
- character: このエンティティの種類は、プレイヤーが選択して冒険を開始できる一連のキャラクターを持つゲームに関連するものです。この概念に基づいてキャラクターのリーダーボードを作成するには、まずプレイヤーを作成し、その後そのプレイヤーに関連付けられたキャラクターを作成する必要があります。作成後、CharacterId をエンティティ ID として使用し、対応するスコアで行を挿入できます。
VersionConfiguration: このパラメーターを使用すると、一定の期間の後にリセットするリーダーボードのバージョン管理戦略を設定できます。この概念については次で詳しく説明します: シーズナルリーダーボード。
Columns: ここでは、リーダーボードが持つ列の数を定義します。この例では、スコア用に 1 列だけ設定しています。また、SortDirection を降順に定義しているため、最高スコアのプレイヤーが最上位に表示されます。1 定義あたりに許可される列の最大数は 5 です。

以上の情報で、サンプルを実行して最初のリーダーボードを作成する準備が整いました。

リーダーボード定義を取得する

このリーダーボードにデータを追加する前に、正しく作成されたことを確認します。この操作を行うために、リーダーボード定義を取得する方法の例を示します。

public static async Task GetLeaderboardDefinition(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetLeaderboardDefinitionRequest leaderboardDefReq = new GetLeaderboardDefinitionRequest()
    {
        Name = leaderboardName
    };

    PlayFabResult<GetLeaderboardDefinitionResponse> getleaderboardDefResult = await leaderboardsAPI.GetLeaderboardDefinitionAsync(leaderboardDefReq);
}

リーダーボード定義を取得するには、作成したリーダーボードの名前を指定します。複数のリーダーボード定義がある場合、次の例を使用してそれらのセットを取得できます。

 public static async Task ListLeaderboards(PlayFabAuthenticationContext context)
 {
     PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
     ListLeaderboardDefinitionsRequest listLbRequest = new ListLeaderboardDefinitionsRequest()  
     {
         AuthenticationContext = context,                
     };
     PlayFabResult<PlayFab.LeaderboardsModels.ListLeaderboardDefinitionsResponse> lbResponse = await leaderboardsAPI.ListLeaderboardDefinitionsAsync(listLbRequest);
    
 }

リーダーボード定義を更新する

リーダーボード定義を更新したい場合は、次のようにできます。

 public static async Task UpdateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName, int sizeLimit, VersionConfiguration version)
 {
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardDefinitionRequest updateLbDefinitionRequest = new UpdateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = sizeLimit,
        VersionConfiguration = version,
     };
     PlayFabResult<PlayFab.ProgressionModels.EmptyResponse> updateLbDefinitionResult = await leaderboardsAPI.UpdateLeaderboardDefinitionAsync(updateLbDefinitionRequest);
           
 }

なお、Columns、EntityType、ResetInterval は更新の一部として変更することはできません。

リーダーボード定義を削除する

リーダーボード定義を削除したい場合は、次のようにできます。

public static async Task DeleteLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteLeaderboardDefinitionRequest deleteLbRequest = new DeleteLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> lbResponse = await leaderboardsAPI.DeleteLeaderboardDefinitionAsync(deleteLbRequest);
}

リーダーボードにデータを追加する

アーケードゲームの例を続けます。ここまでで、リーダーボード定義の作成、取得、必要に応じた削除の方法を学びました。次のステップは、リーダーボードにデータを追加し始めることです。これらはエンティティベースのリーダーボードであるため、エントリはエンティティであることに留意してください。独自の外部 ID を持ち込むこともサポートしています。詳細についてはリーダーボードでさらにできることを参照してください。今回の具体例では、エンティティタイプとして title_player_account を使用しているため、リーダーボードにはプレイヤーが登録されます。ただし、他のエンティティタイプも使用できることを覚えておいてください。詳細は次で確認できます: 利用可能な組み込みエンティティタイプ。それでは、リーダーボードにデータを追加する方法を見ていきましょう。

public static async Task UpdateLeaderboardForPlayer(PlayFabAuthenticationContext context, string leaderboardName, string entityId, int score)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardEntriesRequest updateLeaderboardRequest = new UpdateLeaderboardEntriesRequest()
    {
        Entries = new List<LeaderboardEntryUpdate>()
        {
            new LeaderboardEntryUpdate()
            {
                EntityId = entityId,
                Scores = new List<string> { score.ToString()}                
            }
        },
        AuthenticationContext = context,
        LeaderboardName = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest);
}

次に、この例の主要な要素をいくつか説明します。

Entries: このパラメーターは、リーダーボードに追加される実際の行に対応します。EntityId を持ち、これはリーダーボード内でエンティティを識別する文字列です。このサービスはスタンドアロンコンポーネントであるため、ここで独自の識別子を使用できます。ただし、他の PlayFab サービスを使用している場合は、この値はすべてのサービスで一貫している必要があります。
Scores: このパラメーターは、1 つのエンティティに追加できるスコアのリストに対応します。リーダーボードは複数の列を持てることを思い出してください。これらの概念については次で詳しく確認できます: リーダーボードでさらにできること
Name: このパラメーターは、リーダーボード定義を作成したときに設定したリーダーボードの名前に対応します。

これで、リーダーボードにデータを追加する準備ができました。

リーダーボードからデータを取得する

ここで簡単に振り返りましょう。この時点で、リーダーボードを作成し、設定の詳細をすべて確認し、エンティティの追加を開始しました。ここでは、プレイヤーたちが既にゲームをプレイし始め、すべて素晴らしいスコアを出していると想像しましょう。誰が最強のプレイヤーかを判定します。次の例では、この操作の方法を示します。

public static async Task<List<EntityLeaderboardEntry>> GetLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetEntityLeaderboardRequest getLbRequest = new GetEntityLeaderboardRequest()
    {
        LeaderboardName = leaderboardName,
        StartingPosition = 1,
        PageSize = 20,
        AuthenticationContext = context,
    };

    PlayFabResult<GetEntityLeaderboardResponse> lbResponse = await leaderboardsAPI.GetLeaderboardAsync(getLbRequest);
    
    return lbResponse.Result.Rankings;
}

次に、この例の主要な要素をいくつか説明します。

StartingPosition: このパラメーターは、データをクエリし始める位置を指します。今回はトッププレイヤーが必要なため、このパラメーターを 1 に設定します。また、このパラメーターは PageSize パラメーターと組み合わせて、必要に応じてリーダーボード全体をクエリするために使用します。
PageSize: このパラメーターは、その要求で取得するレコード数を指定します。
Name: このパラメーターは、リーダーボード定義を作成したときに設定したリーダーボード名に対応します。

タイブレーク

さて、ゲームを使うプレイヤーたちが誰が最強かを競っているとしましょう。ここで問題が発生します。2 人のプレイヤーが同じ数の敵を倒したため、同じスコアになりました。では、誰が最上位のプレイヤーになるべきでしょうか? その疑問に答えるため、既定では単純なタイブレークポリシーが用意されています。スコアが達成されたタイムスタンプに基づいて最良のプレイヤーを選びます。最初にそれを達成した方が最上位のプレイヤーとなります。ただし、ゲームの状況によっては、これでは不十分または正確でない場合があります。より複雑なタイブレーク機能については、リーダーボードでさらにできることを参照してください。現在の例のランキングは次のようになります。

ランク	エンティティ ID	スコア	LastUpdated
1	”player 3”	103	”2024-08-27T20:24:36.738Z”
2	”player 2”	102	”2024-08-27T20:24:29.251Z”
3	”player 1”	100	”2024-08-27T19:52:26.642Z”
4	”player 4”	100	”2024-08-27T20:24:44.552Z”

この具体例では、“player 1” と “player 4” のスコアが同じです。どちらが上位になるかはタイムスタンプに基づいて決定されます。“player 1” が先にスコアを達成したため、その理由で最上位となります。

リーダーボードの行を削除する

リーダーボードが期待どおりに動作し、ゲームにはたくさんのプレイヤーがいます。しかし、リーダーボードの上位に上がるために不正を行っているプレイヤーがいるようで、通常とは異なる挙動を目にし始めます。そのような行為は許容できないため、リーダーボードから削除したいと考えます。次の例では、リーダーボードから行を削除する方法を示します。

public static async Task DeleteLeaderboardEntries(PlayFabAuthenticationContext context, string leaderboardName, List<string> entityIds)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteLeaderboardEntriesRequest leaderboardsDelReq = new DeleteLeaderboardEntriesRequest() {
        Name = leaderboardName,
        EntityIds = entityIds
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> delLeaderboardDefResult = await leaderboardsAPI.DeleteLeaderboardEntriesAsync(leaderboardsDelReq);
}

次に、この例の主要な要素をいくつか説明します。

EntityIds: このパラメーターは、削除したいエンティティ ID のリストです。
Name: このパラメーターは、リーダーボード定義を作成したときに設定したリーダーボード名に対応します。

まとめ

このチュートリアルでは、次の操作の方法を学びました:

リーダーボードの作成。
リーダーボードの構成の確認。
リーダーボード構成の更新。
リーダーボード構成の削除。
リーダーボードへのデータの追加。
タイブレークの仕組みの理解。
リーダーボード内のエントリの削除。

XBOX Services

PlayFab

基本的なリーダーボードを作成する

基本的なリーダーボードを作成する

リーダーボードを作成する

リーダーボード定義を取得する

リーダーボード定義を更新する

リーダーボード定義を削除する

リーダーボードにデータを追加する

リーダーボードからデータを取得する

タイブレーク

リーダーボードの行を削除する

まとめ

関連項目

​基本的なリーダーボードを作成する

​リーダーボードを作成する

​リーダーボード定義を取得する

​リーダーボード定義を更新する

​リーダーボード定義を削除する

​リーダーボードにデータを追加する

​リーダーボードからデータを取得する

​タイブレーク

​リーダーボードの行を削除する

​まとめ

​関連項目

基本的なリーダーボードを作成する

リーダーボードを作成する

リーダーボード定義を取得する

リーダーボード定義を更新する

リーダーボード定義を削除する

リーダーボードにデータを追加する

リーダーボードからデータを取得する

タイブレーク

リーダーボードの行を削除する

まとめ

関連項目