Leaderboards Interface

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

21 分で読める

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 リーダーボードについて考えてみます。現在マイルストーンが存在しないと仮定してこのリーダーボードを作成すると、次のマイルストーンが作成されます。

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

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

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

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

プロパティ
ApiVersionEOS_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 構造体を渡します。

プロパティ
ApiVersionEOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYINDEX_API_LATEST

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

プロパティ
ApiVersionEOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYLEADERBOARDID_API_LATEST
LeaderboardId取得する情報を含むリーダーボードの ID

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

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

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

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

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

プロパティ
ApiVersionEOS_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 構造体とともに呼び出します。

プロパティ
ApiVersionEOS_LEADERBOARDS_QUERYLEADERBOARDUSERSCORES_API_LATEST
UserIds取得するスコアを保持するユーザーを示す EOS_ProductUserId 値の配列
UserIdsCountUserIds パラメータに含まれる ID の数
StatInfo収集するスタッツと、各スタッツのランキング順を決定する際に使用するソート方法
StatInfoCountStatInfo 配列の要素数
StartTimePOSIX タイムスタンプ (オプション) または EOS_LEADERBOARDS_TIME_UNDEFINED。結果には、この時刻より後に生成されたスコアのみが含まれます
EndTimePOSIX タイムスタンプ (オプション) または 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 を使ってこれを解放します。

使用上の制限事項

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

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

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

機能 制限事項
グローバル リーダーボード数

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

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

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

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

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

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

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

機能ユーザーごとの制限デプロイメントごとの制限
1 つのリーダーボード値を取得100 リクエスト / 分-
すべてのリーダーボード値を取得10 リクエスト / 分-
リーダーボードを作成-100 リクエスト / 分
リーダーボードを削除-100 リクエスト / 分