Leaderboards インターフェース

オンライン リーダーボードを処理するためのインターフェースです。

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

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

Leaderboards インターフェースでは複数のリーダーボードを設定および管理しますが、スコア データの提供は行いません。リーダーボードでは、Stats インターフェース で作成されて維持されるデータを利用します。

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

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

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

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

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

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

スタッツとマイルストーン

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

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

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

リーダーボード タイプ

説明

マイルストーン参照 #

Singleton リーダーボード

単一の集計ウィンドウで定義されるリーダーボード (開始 / 終了タイムスタンプ ペア).

2

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

Leaderboards_Milestones.png

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

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

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

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

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

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

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

スコアリング方法

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

スコア集約タイプ

リーダーボードの動作

EOS_LSA_Min

リーダーボードは、プレイヤーによって報告された最低スコアを使用します。最低のスコアを保持するプレイヤーが一位のポジションを獲得します。

EOS_LSA_Max

リーダーボードは、プレイヤーによって報告された最高スコアを使用します。最高のスコアを保持するプレイヤーが一位のポジションを獲得します。

EOS_LSA_Sum

リーダーボードは、各プレイヤーによって報告されたスコアをすべて蓄積します。最高の合計スコアを保持するプレイヤーが一位のポジションを獲得します。

EOS_LSA_Latest

リーダーボードは、プレイヤーによって報告された直近のスコアを使用します。最高のスコアを保持するプレイヤーが一位のポジションを獲得します。

リーダーボードに EOS_LSA_Latest を使用すると、リーダーボードのエントリが不安定になる場合があります。たとえば、レベルに対して収集されたオブジェクトの数を追跡する Latest 統計情報について考えてみます。前の実行中に十分なパフォーマンスを発揮してプレイヤーはこの統計情報のリーダーボードに配置されていても、その後のレベルのプレイスルーにより、パフォーマンスが落ちると、プレーヤーがリーダーボードから削除される可能性があります。一般に、統計値/集計を直接制御するために使用する場合を除き、EOS_LSA_Latest で定義されたステータスでリーダーボードを使用することは推奨しません。たとえば、プレーヤーごとにカスタム計算された ELO を含むリーダーボードなどです。 LATEST リーダーボードを使用する場合は、次の点に注意してください。

  1. リーダーボードは、上位 2000 エントリの集計のみを保持し、上位 1000 のランキングのみを表示できます。2001 位以下にランク付けされたプレーヤーに関連付けられた値は、システムでは保持されません。そのようなプレーヤーがリーダーボードにランク付けされるためには、そのユーザーの統計が発行 (また再発行) される必要があります。

    1. エミッション間で大きく変動する LATEST 統計値は、(1) に比べてプレイヤー エクスペリエンスが低下します。時間の経過とともにプレーヤーごとに値が単調になるのが理想的な統計です。

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

リーダーボードの情報にアクセスする

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

プロパティ

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDDEFINITIONS_API_LATEST

StartTime

リーダーボードの開始時刻の POSIX タイムスタンプ (オプション) または EOS_LEADERBOARDS_TIME_UNDEFINED

EndTime

リーダーボードの終了時刻の POSIX タイムスタンプ (オプション) または EOS_LEADERBOARDS_TIME_UNDEFINED

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

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

プロパティ

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYINDEX_API_LATEST

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

プロパティ

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYLEADERBOARDID_API_LATEST

LeaderboardId

取得する情報を含むリーダーボードの ID

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

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

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

ランク付けされたワールドワイド データを取得する

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

プロパティ

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDRANKS_API_LATEST

LeaderboardId

取得する情報を含むリーダーボードの ID

操作を完了すると、タイプ 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 構造体とともに呼び出します。

プロパティ

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDUSERSCORES_API_LATEST

UserIds

取得するスコアを保持するユーザーを示す EOS_ProductUserId 値の配列

UserIdsCount

UserIds パラメータに含まれる ID の数

StatInfo

収集するスタッツと、各スタッツのランキング順を決定する際に使用するソート方法

StatInfoCount

StatInfo 配列の要素数

StartTime

POSIX タイムスタンプ (オプション) または EOS_LEADERBOARDS_TIME_UNDEFINED。結果には、この時刻より後に生成されたスコアのみが含まれます

EndTime

POSIX タイムスタンプ (オプション) または EOS_LEADERBOARDS_TIME_UNDEFINED。結果には、この時刻より前に生成されたスコアのみが含まれます

この方法で収集するスコアは指定した方法でソートされますが、これにあたってリーダーボードは必要ありません。これらのスコアにはグローバルなランク付けは行われません。StatInfo フィールドには比較するスタッツと、クエリで取得した他のユーザーのスコアに対するランキング方法の両方が含まれています。

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

使用上の制限事項

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

スロットリング、使用クォータ、ベストプラクティスの一般情報については、「

[](Overview#ServiceUsageLimitations)
」を参照してください。

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

機能

制限事項

グローバル リーダーボード数

利用可能なマイルストーンによる制限。Leaderboards インターフェース を参照してください。

グローバル リーダーボード エントリの合計

1000 (+1000 オーバーフローについては Leaderboards インターフェース を参照してください。)

フレンド リーダーボード数

詳細は「統計情報」 を参照してください。

フレンド リーダーボードは統計情報へ直接クエリすることで作成され、グローバル リーダーボードの制限による影響は受けません。

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

機能

ユーザーごとの制限

デプロイメントごとの制限

1 つのリーダーボード値を取得

100 リクエスト / 分

すべてのリーダーボード値を取得

10 リクエスト / 分

リーダーボードを作成

100 リクエスト / 分

リーダーボードを削除

100 リクエスト / 分