次の方法で共有

基本ランキングの作成

  • [アーティクル]

このチュートリアルでは、新しいランキング サービスを使用して基本ランキングを作成する方法について説明します。 まずはアーケード ゲームの例から始めましょう。目標は、倒されるまでできるだけ多くの敵を倒すことです。 そうなると、スコアが割り当てられます。 ここで、このゲームで最高のプレイヤーが誰であるかを判断するのに役立つランキングを作成したいと思います。

ランキングの作成

最初のステップは、プレイヤーをランク付けするための主な要素を含むランキング定義を作成することです。 アーケード ゲームでは、スコアに必要な列は 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: この種類のエンティティは、プレイヤーが選択して体験を開始できる一連のキャラクターを持つゲームに関連しています。 この概念を念頭に置いて、キャラクターのランキングを作成するには、まずプレイヤーを作成してから、そのプレイヤーに関連付けられたキャラクターを作成する必要があります。 その後、エンティティ ID として CharacterId を使用し、対応するスコアを持つ行を挿入できます。
  • VersionConfiguration: このパラメーターを使用すると、一定期間後に自分自身をリセットするランキングのバージョン管理戦略を設定できます。 この概念については、「シーズン ランキング」で詳しく説明しています。
  • Columns: ここでは、ランキングに含める列の数を定義します。 この例では、スコアに対して 1 つの列のみを設定します。 また、SortDirection は降順として定義します。つまり、最高スコアを獲得したプレイヤーが最上位になります。

このすべての情報を使用して、例を実行し、最初のランキングを作成する準備が整いました。

ランキング定義の取得

このンぐにデータを追加する前に、データが正しく作成されていることを確認する必要があります。 このアクションを実行するために、ランキング定義を取得する方法の例を示します。

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 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 人のプレイヤーが同じ数の敵を倒したため、同じスコアになっています。 では、誰がトップ プレイヤーになりますか?

その質問に答えるために、私たちは既定で単純なタイブレーカー ポリシーを採用しています。 スコアが達成されたタイムスタンプに基づいて、最優秀プレイヤーを選択します。 それを最初に達成した人がトップ プレイヤーです。 ただし、ゲームの状況によっては、これでは不十分であったり、正確ではない場合があります。 より複雑なタイブレーク機能については、「ランキングをさらに活用する」を参照してください。

現在の例では、ランキングは次のようになります:

Rank エンティティ ID Score 最終更新日
1 "プレイヤー 3" 103 "2024-08-27T20:24:36.738Z"
2 "プレイヤー 2" 102 "2024-08-27T20:24:29.251Z"
3 "プレイヤー 1" 100 "2024-08-27T19:52:26.642Z"
4 "プレイヤー 4" 100 "2024-08-27T20:24:44.552Z"

この例では、"プレーヤー 1" と "プレーヤー 4" の両方のスコアが同じです。 誰が最初に進むかの決定はタイムスタンプによって決まります。 "プレイヤー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: このパラメーターは、ランキング定義の作成時に設定されたランキング名に対応します。

まとめ

このチュートリアルでは、次の操作を行う方法について説明しました:

  • ランキングを作成する
  • ランキングの構成を確認します。
  • ランキング構成を削除します。
  • ランキングを設定します。
  • タイブレークのしくみを理解する。
  • ランキング内のエントリを削除します。

関連項目