Leaderboards Interface

Leaderboards インターフェース を使用することで、Epic Online Services (EOS) をご利用のデベロッパーはプレイヤー ベース全体を基にスコアをランキングできるようになり、プレイヤーがフレンドや世界中のプレイヤーとスコアを競い合うことのできる環境を提供できます。それぞれのゲームは複数のリーダーボードをサポートしており、さまざまなソースからスコアを収集して、各種スコアリング モードでランキングを行うことができます。

Leaderboards インターフェースを利用するには、Platform (プラットフォーム) インターフェース関数の EOS_Platform_GetLeaderboardsInterface で EOS_HLeaderboards ハンドルを取得する必要があります。すべての Leaderboards インターフェースの関数には 1 つ目のパラメータとしてこのハンドルが必要です。操作の完了時にコールバックをトリガーできるよう、EOS_HPlatform ハンドルがティックすることを必ず確認してください。

ゲーム内からリーダーボードにアクセスするには、事前に Developer Portal (デベロッパー ポータル) を使って、リーダーボードで追跡するスタッツを設定し (詳細については「Stats Interface」を参照)、リーダーボード自体を定義する必要があります。リーダーボードの定義では次のことを設定します。

• リーダーボードで追跡するスタッツ (またはスコア)

• リーダーボードによるプレイヤーのランキング方法

• リーダーボードの全体的なライフスパンの開始および終了時刻

スタッツとリーダーボードの設定が完了したら、EOS SDK を通じてこれらにアクセスできるようになります。

EOS リーダーボードは EOS スタッツシステムによって稼働します。それぞれのリーダーボードでは、追跡するスコアとして特定のスタッツを使用します。詳細については「Stats インターフェース」を参照してください。

Leaderboards インターフェースは、ランク付けされた世界規模のデータ、およびランク付けされていないフレンド データのクエリをサポートします。システム内のスタッツは、友達、クラン、またはその他のグループベースのリーダーボードとして使用することが可能で、個々のプレーヤーのスタッツを照会するだけで表示されます。それに対して、グローバル リーダーボードには特定の構成が必要です。スケーラビリティの理由から、使用できるグローバルリーダーボード数と、追跡するリーダーボードの実際のエントリの数の両方を制限しています。グローバル リーダーボード全体を追跡するのではなく、上位 1000 (+ 1000 オーバーフロー) のスコアのみを追跡します。開発者がリーダーボードから特定のエントリの削除を選択する場合があるため (不正行為、スマーフィング、プライバシーのオプトアウト、またはその他の理由から)、追加の1000 エントリを保持します。そのため、これらが削除された後、上位 1000 を埋めるために追加の値を保持します。上位 1000 エントリのみを追跡することで、大多数のプレーヤーはリーダーボードに表示されなくなりますが、グローバル リーダーボードはトッププレーヤーにのみ価値を提供するため、これは良いと考えています。フレンド リーダーボードやその他の小さな非公開のグループは、さらに多くのインタラクティビティと価値をプレイヤーに提供し、有意義なフィードバックによって合理的に達成することができる目標をプレイヤーに与えます。

各リーダーボードは、リーダーボードの状態の正確な計算に必要とされるスタッツ集計をビン化するために、多くのスタッツ マイルストーンを参照します。1 人のユーザーが所有できるリーダーボードの数は、任意のユーザー アカウントに含むことができるスタッツ マイルストーンの数の関数です。次の表は、この関数をリーダーボードのタイプ別に示したものです (現在サポートされているタイプは 1 つのみです)。

リーダーボードを作成する場合、マイルストーンは参照される (読み取り、再利用)、またはユーザーによって/ユーザーのために定義された既存のマイルストーンのセットに関連して作成されます。 たとえば、10月31日の 08：00 〜 16：00 の間に stat total_apples_collected (SUM) でプレーヤーをランク付けするように定義された Singleton リーダーボードについて考えてみます。現在マイルストーンが存在しないと仮定してこのリーダーボードを作成すると、次のマイルストーンが作成されます。

タイムスタンプが 08:00 から 16:00 の間に発生する total_apples_collectedに対して生成されたスタッツは、playerId ごとに単一の合計値として集約されます。すべてのプレーヤーの場合、これらの値は定義された Singleton リーダーボードにランク付けされます。

次は、マイルストーンの再利用を強調するために、上記と同じ時間帯内に別のスタッツ total_pumpkins_collected があり、2 つ目の Singleton リーダーボードが必要であることを考えてみます。この新しいリーダーボードを作成すると、 total_apples_collected に対して作成されたものと同じマイルストーンが参照/再利用されますが、使用可能なマイルストーン数がさらに減ることはありません。

マイルストーンは、リーダーボードから参照されなければ、システムによって自動的に削除されます。

まとめると次のようになります。

• グローバル リーダーボードの合計：利用可能なマイルストーンによって制限されます (上記を参照)

• マイルストーンの最大数 (デフォルト)：100

• グローバル リーダーボード エントリの合計：1000 (+1000 オーバーフロー)

Leaderboards インターフェースでは、さまざまなゲームやランキング システムに対応するために、複数のスコアリング方法が用意されています。リーダーボードでは、スコア集約タイプ に従ってスコアを計算してランキングできます。リーダーボードには、リーダーボードに割り当てられたスタッツで使用されているものと同じ集約タイプを使用する必要があります。利用可能なスコア集約タイプは次のとおりです。

さらに、リーダーボードでスコア値として使用されるスタッツの名前を指定する必要もあります。

リーダーボードの情報にアクセスするにはリーダーボード ID が必要です。この ID は、Developer Portal から取得してゲームに直接追加するか、ゲームに関連付けられているすべてのリーダーボードについて、EOS SDK に対してクエリを実行できます。これを行うには、次の情報で初期化された EOS_Leaderboards_QueryLeaderboardDefinitionsOptions 構造体を含む EOS_Leaderboards_QueryLeaderboardDefinitions を呼び出します。

この操作を完了すると、タイプ EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallback のコールバックは、成功 / 失敗を示す EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallbackInfo 構造体とともに実行されます。成功の場合は、提示した条件に適合するリーダーボードのリストがローカル キャッシュに含まれます。次に EOS_Leaderboards_GetLeaderboardDefinitionCount を使用して、システムで検出されたリーダーボード定義の数を確認し、EOS_Leaderboards_CopyLeaderboardDefinitionByIndex を呼び出して各リーダーボードのコピーを取得します。目的のリーダーボードの ID がすでにリストに含まれていることがわかっている場合は、代わりに EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId を呼び出してそのボードの定義のコピーを取得できます。

EOS_Leaderboards_CopyLeaderboardDefinitionByIndex を呼び出す際は、次の設定で初期化された EOS_Leaderboards_CopyLeaderboardDefinitionByIndexOptions 構造体を渡します。

EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId を呼び出す際は、次の設定で初期化された EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardIdOptions 構造体を渡します。

いずれの場合でも、リーダーボードを定義する情報のコピーを取得できます (タイプ EOS_Leaderboards_Definition)。この情報が不要になったら、EOS_Leaderboards_LeaderboardDefinition_Release を呼び出してこれを解放します。

通常、プレイヤーはワールド全体のリーダーボード データか、フレンドのみのデータを表示する傾向があります。リーダーボード インターフェースには、これらの範囲でデータを取得するためのクエリ方法がそれぞれ用意されています。

リーダーボードのワールドワイド ランキングを表示するには、EOS_Leaderboards_QueryLeaderboardRanks を EOS_Leaderboards_QueryLeaderboardRanksOptions 構造体とともに呼び出します。構造体を次の設定で初期化します。構造体を次のように初期化します。

操作を完了すると、タイプ EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallback のコールバックは、成功 / 失敗を示す EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallbackInfo データ構造体とともに実行されます。成功の場合は、リクエストしたデータが EOS SDK キャッシュに含まれます。レコードの数を確認するには EOS_Leaderboards_GetLeaderboardRecordCount を呼び出し、個別のレコードのコピーを取得するには EOS_Leaderboards_CopyLeaderboardRecordByIndex を呼び出します。ID が判明している特定のユーザーのレコードが必要な場合は、EOS_Leaderboards_CopyLeaderboardRecordByUserId を呼び出します。いずれの関数も、キャッシュされたレコードのコピーを EOS_Leaderboards_LeaderboardRecord の形式で返します。これらのコピーが不要になった場合は、EOS_Leaderboards_LeaderboardRecord_Release を使ってこれらを解放します。

プレイヤーに対してそのフレンドのスコア レコードを表示する場合は、EOS_Leaderboards_QueryLeaderboardUserScores を使用します。この関数を次の設定で初期化した EOS_Leaderboards_QueryLeaderboardUserScoresOptions 構造体とともに呼び出します。

操作を完了すると、タイプ EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallback のコールバックは、成功 / 失敗を示す EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallbackInfo データ構造体とともに実行されます。呼び出しが成功の場合は、フレンドのスコアの順序付けされたレコードがキャッシュに含まれます。利用可能なレコードの数を取得するには EOS_Leaderboards_GetLeaderboardUserScoreCount 関数を、インデックスごとにスコアを取得するには EOS_Leaderboards_CopyLeaderboardUserScoreByIndex を、ユーザー ID ごとにスコアを取得するには EOS_Leaderboards_CopyLeaderboardUserScoreByUserId を使用できます。いずれの場合でも、適切な EOS_Leaderboards_LeaderboardUserScore データのコピーを取得できます。このデータが不要になったら、EOS_Leaderboards_LeaderboardUserScore_Release を使ってこれを解放します。

それぞれのゲームは複数のリーダーボードをサポートしており、さまざまなソースからスコアを収集して、各種スコアリング モードでランキングを行うことができます。

スロットリング、使用クォータ、ベストプラクティスの一般情報については、「サービス使用上の制限事項」を参照してください。

以下の制限事項はリーダーボードのデプロイメントの使用全体に適用されます。

ユーザーごと、またはデプロイメントごとに適用される使用レート制限もあります。ユーザーごとの制限は、ゲームをプレイし既存のリーダーボードを表示する個々のユーザーに適用されます。デプロイメントごとの制限は、これらのリーダーボードを作成または削除するコールに適用されます。