Steam のランキングを作る手順｜リーダーボードの設定・スコアの送信・表示

作る前に知ること

Steam は、エントリーが自動的に並べ替えられる、永続的なランキングを提供します。ランキングは、ゲーム内やコミュニティ Web ページ上で、グローバルランキングやフレンド内でのランキングを表示するために使用できます。

ランキングについて、次のことが決まっています。

• 1つの Steamworks タイトルには、最大10,000個のランキングを作成できます。
• 個々のランキングは、プレイヤーのスコアの挿入直後に取得可能です。
• それぞれのランキングで、プレイヤーあたりのエントリーは一度です。
• ランキングごとのプレイヤー数に制限はありません。
• それぞれのエントリーには、ランキング用のスコア（int32）と、任意で最大64個までの関連データの int32 が含まれます。
• 関連データは、ユーザーのランキング入りが決まったプレイセッションの情報の保存に使用できます。Steam がこのデータを並べ替えたり解析したりすることはなく、ユーザーの新たなランキングエントリーが作成された際に置き換えられます。

すべての非同期ランキング関数は、ハンドルを Steam API の呼び出し結果に返します。Steamworks のゲーム管理では、ゲームのランキングを確認したり管理したりできます。

Steam で選べる機能の全体はSteam で実装が要る仕様に、実績と統計はSteam の実績の設定の手順にあります。

管理画面でランキングを作る

ランキングはアプリケーション固有のもので、Steamworks パートナーサイトのゲーム管理ページ、または API を介して設定されます。

Steamworks のアプリ管理から「データと実績」＞「ランキング」を開くと、AppID 用のランキングの作成と管理を行えます。ランキングを定義するには、次のフィールドに入力する必要があります。

並べ替え方法の昇順は一番スコアの低いユーザーを一番上に表示し、降順は一番スコアの高いユーザーを一番上に表示します。

ランキングが作成されると、ゲーム管理者を通じてランキングの並べ替え方法と表示タイプを変更できます。

API でランキングを作る・探す

ランキングは、Steamworks のアプリ管理、またはプログラムで ISteamUserStats::FindOrCreateLeaderboard を呼び出すことによって作成できます。

• Steam では、Steamworks タイトル用のすべてのランキングが固有名によって識別されます。ランキング名は Steamworks API で識別目的のみに使用され、Steam コミュニティでユーザーに表示されることはありません。
• ランキング名は、UTF-8 エンコードで最大128バイト（k_cchLeaderboardNameMax）です。
• ランキングを作成するときは、並べ替え方法と表示タイプを選びます。並べ替え方法は、k_ELeaderboardSortMethodAscending（一番スコアの低いユーザーを一番上に表示）または k_ELeaderboardSortMethodDescending（一番スコアの高いユーザーを一番上に表示）です。
• 表示タイプの ELeaderboardDisplayType は、ランキングのスコアの意味の説明と、コミュニティへの表示時にランキングのスコアをフォーマットする際に使用されます。

ELeaderboardDisplayType の k_ELeaderboardDisplayTypeNumeric（1）は、スコアが単なる数値であることを表します。k_ELeaderboardDisplayTypeTimeSeconds（2）は秒単位での時間を、k_ELeaderboardDisplayTypeTimeMilliSeconds（3）は、ミリ秒単位での時間を表します。

k_ELeaderboardSortMethodNone と k_ELeaderboardDisplayTypeNone は、ランキングが無効のときにのみ使用される値です。FindOrCreateLeaderboard の eLeaderboardSortMethod と eLeaderboardDisplayType に渡すことはできず、これらを渡すと未定義の動作です。

この関数で作成したランキングは、Steam コミュニティには自動で表示されません。Steamworks Web サイトのアプリ管理パネル内のコミュニティ名フィールドに、手動で設定する必要があります。

アプリ管理だけでランキングを作成する場合は、ISteamUserStats::FindLeaderboard を使用してランキングのハンドルを取得できます。FindLeaderboard と FindOrCreateLeaderboard は非同期メソッドで、LeaderboardFindResult_t 呼び出し結果を使用して、指定したランキングのハンドルを返します。この結果の m_hSteamLeaderboard は、検索されたランキングへのハンドルで、ランキングが見つからなければ 0 です。m_bLeaderboardFound は、ランキングがあれば 1、無ければ 0 です。

他のランキング関数を呼び出す前に、FindLeaderboard または FindOrCreateLeaderboard を呼び出して、アクセスしたい各ランキングの、ゲームセッションに有効なハンドルを取得する必要があります。

既存のランキングに対して FindOrCreateLeaderboard が呼び出される際は、並び替え方法と表示タイプのパラメーターは無視されます。

Web API の ISteamLeaderboards にも FindOrCreateLeaderboard があります。この呼び出しには、パブリッシャー API キーが必要です。sortmethod はこのランキングに使用する並べ替え方法（デフォルトは昇順）、displaytype はこのランキングの表示方法（デフォルトは数値）です。createifnotfound が true で、ランキングが存在しない場合は作成されます（デフォルトは true）。onlytrustedwrites が true の場合、ランキングスコアはクライアントによって設定できなくなり、SetLeaderboardScore Web API 経由でパブリッシャーによってのみ設定可能になります（デフォルトは false）。onlyfriendsreads が true の場合、ランキングスコアはクライアントによってフレンド用にのみ読み込まれ、スコアはパブリッシャーによって常に読み込まれます（デフォルトは false）。

パブリッシャー API キーが必要なこの API は、セキュリティ保護されたサーバー上から呼び出し、直接クライアントからは使用しません。

スコアを送る

ランキングのスコアは、ISteamUserStats::UploadLeaderboardScore で送ります。この関数には、対象のランキングのハンドル（FindLeaderboard を通じて取得したもの）、ユーザーのスコア、そして必要に応じて新しいスコアを設定したときに生成された関連データを渡します。ユーザーのランキングのスコアが更新されると、渡された関連データが、以前に保管されたデータを置き換えます。

ユーザーのランキングのスコアをアップロードするときは、2つのアップデートメソッドからいずれかを選択できます。

関連データの配列（pScoreDetails）はオプションで、要素の数（cScoreDetailsCount）は k_cLeaderboardDetailsMax（64）を超えてはなりません。関連データは、ゲームで定義されたオプションの情報で、ユーザーがスコアを取得した方法の概要を示します。たとえば、レーススタイルの時間をベースとしたランキングでは、プレイヤーが各チェックポイントを通過した時点のタイムスタンプを保存できます。収集品がある場合は、ビットフィールドをブール値として使用し、プレイスルーで拾ったアイテムを保存できます。

Steam へのスコアのアップロードは、10分につき10回までと制限されており、一度にこの関数を呼び出しできる回数は1回です。

UploadLeaderboardScore は非同期呼び出しで、アップロードの結果は LeaderboardScoreUploaded_t の呼び出し結果で返されます。この結果には、ユーザーのスコアが変更されたかどうかのフラグ情報と、ユーザーの新旧グローバルランクが含まれます。

m_bSuccess は、呼び出しが成功した場合は 1、失敗した場合は 0 です。m_nScore は設定が試行されたスコアです。m_bScoreChanged が true となるのは、ランキング上のスコアが変わった場合で、既存のスコアの方が良い場合には false です。m_nGlobalRankNew はこのランキング上のユーザーの新しいグローバルランク、m_nGlobalRankPrevious はこのランキングでのユーザーの以前のグローバルランクで、ユーザーに過去のランキングエントリーがない場合は 0 です。

m_bSuccess が 0 になる例には、送信された詳細の量が k_cLeaderboardDetailsMax を超えている場合と、ランキングが Steamworks Web サイトのアプリ管理画面で「Trusted」に設定されていて、Steam Web API から送信されたスコアのみを受け付ける場合があります。

アップロードすると、Steamworks のランキングは直ちに新しいスコアを反映するようにアップデートされ、新しいエントリー順は DownloadLeaderboardEntries を通じて取得できます。

書き込みを「信頼済み」にしたとき

書き込みが「信頼済み」に設定されているランキングのスコアは、クライアントでは設定できず、SetLeaderboardScore Web API 経由でのみ設定できます。ISteamLeaderboards の SetLeaderboardScore は POST で呼び出し、key（Steamworks Web API パブリッシャー認証キー）、appid（ゲームの AppID）、leaderboardid（対象ランキングの数値 ID で、GetLeaderboardsForGame から取得可能）、steamid（スコアを設定する SteamID）、score（このユーザー用に設定するスコアの int32）、scoremethod（使用するアップデート方法で、KeepBest または ForceUpdate）を渡します。ゲーム特定のスコア獲得方法の詳細を渡す details は最大256バイトです。

ユーザー生成コンテンツを付ける

スコアがアップロードされたあとに、エントリー用にユーザーが生成したコンテンツをアタッチするオプションがあります。そのときは ISteamUserStats::AttachLeaderboardUGC を呼び出します。このコンテンツは、たとえば、ユーザーがスコアを達成した瞬間のリプレイや、対戦するゴーストなどです。この関数には、ランキングのハンドルと、ISteamRemoteStorage::FileShare を使用して共有されたユーザー生成コンテンツのハンドルを渡します。結果は LeaderboardUGCSet_t の呼び出し結果で返されます。

アタッチされたハンドルは、エントリーが取得されると利用可能になり、GetDownloadedLeaderboardEntry で取得する LeaderboardEntry_t.m_hUGC から、他のユーザーもアクセスできます。一旦アタッチされると、クラウド上のファイルがユーザーによって変更または削除された場合でも、コンテンツは利用可能です。

順位のデータを取り出す

ランキングのエントリーは、ISteamUserStats::DownloadLeaderboardEntries で取得します。引数は、FindLeaderboard または FindOrCreateLeaderboard で取得したランキングハンドル、データリクエストのタイプ（ELeaderboardDataRequest）、取得を始めるインデックス、最後のインデックスです。存在する数よりも多くのエントリーをリクエストでき、その場合は存在する分の値が返ります。

ELeaderboardDataRequest には、次の値があります。

k_ELeaderboardDataRequestGlobalAroundUser では、現在のユーザーがランキングで5位のとき、開始を -2、終了を 2 とすると、3位から7位の5つのエントリーを返します。ユーザーがエントリーする前にランキング内に十分な数のエントリーが無かった場合、Steam は範囲を調節して、リクエストされたエントリー数を返します。たとえば、ユーザーがランキング内で1位のときに、開始が -2、終了が 2 と設定されていた場合には、Steam はランキングの上位5位を返します。開始を -4、終了を 5 にすると、現在のユーザーの前の4人、現在のユーザー、現在のユーザーの後の5人の、10個のエントリーをダウンロードできます。

たとえば「サーバー上の全ユーザー」など、任意のユーザーセットのエントリーをダウンロードしたい場合は、DownloadLeaderboardEntriesForUsers に Steam ID の配列を渡します。一度にダウンロード可能な最大のユーザー数は100で、一度に処理できる呼び出し回数は1回です。ユーザーが指定のランキングにエントリーしていない場合、そのユーザーは結果に含まれません。ユーザー数が100を超える場合や、いずれかの Steam ID が無効な場合は、エラーを示す k_uAPICallInvalid を返します。

DownloadLeaderboardEntries は、LeaderboardScoresDownloaded_t の呼び出し結果で結果を返します。この結果の m_hSteamLeaderboard は、これらのエントリーが属するランキングへのハンドルです。m_hSteamLeaderboardEntries は GetDownloadedLeaderboardEntry に渡されるハンドルで、ダウンロードした各エントリーの情報を取得します。m_cEntryCount はダウンロードしたエントリーの数です。

呼び出し後、ダウンロードした各エントリーの情報を取得するには、GetDownloadedLeaderboardEntry を使用する必要があります。この関数は1つのランキングエントリーのデータを取得します。ダウンロードされたエントリーをすべて取得するには、0から m_cEntryCount までの for ループを使用する必要があります。エントリーの詳細は、必要に応じて pDetails 経由で返されます。これが NULL の場合、cDetailsMax は 0 である必要があります。すべてのエントリーにアクセスすると、データが解放され、SteamLeaderboardEntries_t ハンドルは無効になります。

ゲームへ組み込む流れ

SteamAPI_Init の呼び出しは Steam 全体を初期化するもので、最初に呼び出される必要があります。Steam のすべてのコールバックを確実に処理するために、新たなメッセージを定期的にチェックする必要があります。これは、SteamAPI_RunCallbacks の呼び出しをゲームループに追加することで実現できます。SteamAPI_Shutdown の呼び出しは、Steam をシャットダウンするものなので、アプリケーションを閉じる前に呼び出す必要があります。

SteamAPI_Init が失敗して appID が見つからないというメッセージが出るときは、steam_appid.txt ファイルが所定の場所にない可能性があります。実行中の Steam のインスタンスが見つからないというメッセージが出るときは、Steam クライアントが実行されていない可能性があります。

ランキングの情報を取る

FindLeaderboard または FindOrCreateLeaderboard から返されたランキングハンドルを使用して、次の API でランキングに関する情報を取得できます。

GetLeaderboardEntryCount の値は、FindLeaderboard または FindOrCreateLeaderboard の最初の呼び出し時にランキングごとにキャッシュされ、DownloadLeaderboardEntries・DownloadLeaderboardEntriesForUsers・UploadLeaderboardScore への呼び出しが成功するたびにリフレッシュされます。

情報源

• Steamworks — Steamランキング（作成・スコアのアップロード・ユーザー生成コンテンツの添付・エントリーの取得・ランキング情報の取得）https://partner.steamgames.com/doc/features/leaderboards確認日 2026-10-21
• Steamworks — ステップバイステップ：ランキング（管理画面のフィールド・組み込みの流れ・エラーの例）https://partner.steamgames.com/doc/features/leaderboards/guide確認日 2026-10-21
• Steamworks — ISteamUserStats インターフェイス（ランキングの関数・結果・列挙型・定数）https://partner.steamgames.com/doc/api/ISteamUserStats確認日 2026-10-21
• Steamworks — ISteamLeaderboards インターフェイス（Web API の FindOrCreateLeaderboard・SetLeaderboardScore）https://partner.steamgames.com/doc/webapi/ISteamLeaderboards確認日 2026-10-21