概要
Steamでは、エントリが自動的に並べ替えられる、永続的なランキングを提供します。 これらのランキングは、ゲーム内やコミュニティWebページ上でグローバルランキングやフレンド内でのランキングを表示するために使用できます。 それぞれのSteamworksタイトルには、最大10,000個のランキングを作成できます。また、個々のランキングは、プレイヤーのスコアの挿入直後に取得可能です。
それぞれのランキングにおいて、プレイヤーあたりのエントリーは一度です。 ランキングごとのプレイヤー数に制限はありません。 それぞれのエントリには、ランキング用のスコア（int32）と、任意で最大64個までの関連データのint32が含まれます。 関連データは、ユーザーのランキング入りが決まったプレイセッション情報に関するゲーム特有の保存に使用できます。 Steamがこのデータを並べ替えたり解析したりすることは無く、また、これはユーザーの新たなランキングエントリが作成された際に置き換えられます。
すべてのランキング関数はISteamUserGameStats.hにあります。Steamworksの事例には、2つのランキングサンプルが実装されています。 また、Steamworksゲーム管理内であなたのゲームのランキングを確認したり管理したりすることができます。
ランキングを始める前に
すべての非同期ランキング関数はハンドルをSteam APIの呼び出し結果に返します。 「はじめに」の「呼び出し結果」セクションで、これらの結果の受け取り方に関する情報を確認できます。
ランキングの作成
ランキングはアプリケーション固有のもので、Steamworksパートナーサイトのゲーム管理ページ、またはAPIを介して設定されます。
Web経由での作成
Steamworksアプリ管理から、
データと実績 -> ランキングを開いて、AppID用のランキングの作成と管理を行うことができます。
ランキングの定義には、次のフィールドに入力する必要があります：
- 名前－ここには、内部開発用に意味のある名前を設定します。
- コミュニティ名－ランキングをコミュニティハブに表示する場合は、ここに一般公開用の名前を設定します。 名前が入力されていない場合は、ランキングは表示されません。
- 並べ替え方法－ランキングの並べ替え順序を設定します。 順位が基準のランキングでは昇順を使用し、 ハイスコアが基準の場合は、降順を使用してください。
- 表示タイプ－ランキングで表示するデータのタイプを決定します。 数値、秒またはミリ秒から選択します。
- 書き込み－これが「信頼済み」に設定されている場合、クライアントによってランキングスコアを設定することはできず、SetLeaderboardScore WebAPIによってのみ設定できます。 デフォルトでは設定されていません。
- 読み取り－これが「フレンド」に設定されている場合、ゲームはユーザーのフレンドのランキングスコアのみを読み取ることができます。すべてのスコアはWebAPIによって常に読み取り可能です。 デフォルトでは設定されていません。
API経由で作成
ゲームのランキングは、
Steamworksアプリ管理、またはプログラムで
ISteamUserStats::FindOrCreateLeaderboardを呼び出すことによって作成することができます。 Steamでは、Steamworksタイトル用すべてののランキングは固有名によって識別されます。 ランキング名はSteamworks APIで識別目的のみに使用され、Steamコミュニティにおいてユーザーに表示されることはありません。 ランキングを作成する場合、以下を選択する必要があります：
- 並べ替え方法－
k_ELeaderboardSortMethodAscending（一番スコアの低いユーザーを一番上に表示）、またはk_ELeaderboardSortMethodDescending（一番スコアの高いユーザーを一番上に表示）
- 表示タイプ－
ELeaderboardDisplayTypeは、ランキングのスコアの意味の説明、およびコミュニティへの表示時にランキングのスコアをフォーマットする際に使用されます。
アプリ管理によってのみランキングを作成する場合は、
ISteamUserStats::FindLeaderboardを使用してランキングのハンドルを取得できます。 FindLeaderboardおよびFindOrCreateLeaderboardは非同期メソッドであり、
ISteamUserStats::LeaderboardFindResult_t呼び出し結果を使用して、指定したランキングのハンドルを返します。
ランキングが作成されると、ゲーム管理を通じてランキング用の並べ替え方法、および表示タイプを修正できます。FindOrCreateLeaderboardが既存のランキング用に呼び出された場合、並べ替え方法や、表示タイプのパラメーターは無視されます。
注意：ランキングがコミュニティハブに表示される場合は、ランキングを定義する際にコミュニティ名フィールドに設定する必要があります。 名前が入力されていない場合は、ランキングは表示されません。
スコアのアップロード
ランキングのスコアをアップロードするには、
ISteamUserStats::UploadLeaderboardScoreを呼び出し、ターゲットとなるランキングのハンドル（FindLeaderboardを通じて取得したもの）とユーザーのスコア、そして必要に応じて新しいスコアを設定するときに生成された関連データを渡します。 ユーザーのランキングのスコアがアップデートされると、
ISteamUserStats::UploadLeaderboardScoreに渡された関連データが、以前に保管されたデータを置き換えます。 ユーザーのランキングのスコアをアップロードする際には、2つのアップデートメソッドからいずれかを選択することができます：
ユーザー生成コンテンツの添付
スコアがアップロードされた後、エントリ用にユーザーが生成したコンテンツをアタッチするオプションがあります。 そうするには、
ISteamUserStats::AttachLeaderboardUGCを呼び出します。このコンテンツは例えば、ユーザーがスコアを達成した瞬間のリプレイや対戦するゴーストなどです。 アタッチされたハンドルはエントリを取得すると利用可能になり、他のユーザーもダウンロードできるようになります。 ユーザー生成コンテンツを作成およびダウンロードするには、Steamクラウドを参照してください。
一旦アタッチされると、クラウド上のファイルがユーザーによって変更または削除された場合でもコンテンツは利用可能です。
ランキングエントリの取得
ISteamUserStats::DownloadLeaderboardEntriesは、
ISteamUserStats::FindLeaderboardを通じて取得したランキングハンドルを使用してランキングのエントリを取得する際に使用されます。
GetDownloadedLeaderboardEntryからダウンロードしたすべてのエントリを取得すると、エントリデータが解放され、LeaderboardScoresDownloaded_t内のSteamLeaderboardEntries_tは無効となります。
ランキング情報の取得
FindLeaderboardから返されたリーダーボードハンドルを使用して、以下のAPIでランキングに関する情報を取得できます：
ISteamUserStats::GetLeaderboardNameISteamUserStats::GetLeaderboardEntryCountISteamUserStats::GetLeaderboardSortMethodISteamUserStats::GetLeaderboardDisplayType
