Steamworks 文獻庫
Steam 排行榜

概覽

Steam 支援自動排列和持續更新的排行榜, 並且可在遊戲和社群網頁中展示全球與好友的排行。 每款 Steamworks 遊戲可建立多達 10,000 個排行榜,皆能在新增玩家分數後立即讀取。

每位玩家在所有排行榜上都有一條項目。 排行榜沒有玩家人數限制。 每條項目包含排行榜的分數(int32),和最多可達 64 個 int32 的相關資料。 相關資料可用來儲存使用者達成成績時的遊戲相關資訊。 Steam 不會排序或解析此資料,而如果替使用者建立了新的排行榜,舊的資料便會被取代。

所有的排行榜功能皆在 ISteamUserGameStats.h 中。Steamworks 範例中也實作了兩個排行榜的實例。 您可在 Steamworks 遊戲管理員中閱覽和管理遊戲的排行榜。

開始之前

所有的不同步排行榜函式皆會向 Steam API 呼叫結果傳回一個控制代碼。 您可查閱新手上路文件的呼叫結果段落,了解更多有關如何接收這些結果的資訊。

建立排行榜

排行榜是專屬於各個應用程式的,必須使用 Steamworks 夥伴網站的遊戲管理員,或通過 API 進行設定。

在網頁上建立

您可前往 Steamworks 應用程式管理員的統計與成就 > 排行榜替您的 App ID 建立和管理排行榜。
spacewar_leaderboards

要設定排行榜,必須填入下列欄位:
  • 名稱 - 開發階段內部可合理使用的名稱。
  • 社群名稱 - 如要在社群中心展示此排行榜,在此輸入公開顯示的名稱。 若留空,則不會出現排行榜。
  • 分類方式 - 設置排行榜的排列順序。 如果是排名式的排行榜,使用遞增。 如果是高分榜,使用遞減。
  • 顯示類型 - 決定排行榜顯示的資料類型。 可選擇數字、秒,或毫秒。
  • 寫入 - 如選擇受信任的,用戶端便無法設置分數,而只能由 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 傳入的相關資料將會取代先前的資料。 上傳使用者的排行榜分數時,有兩種更新方式可選擇:

添加使用者自製內容

分數上傳後,您可選擇在項目上添增使用者自製內容, 只須呼叫 ISteamUserStats::AttachLeaderboardUGC 即可。這可以是使用者得到成績時的重播,或是可以與之比賽的過程記錄。 添加的控制代碼在收到項目後即可使用,也可讓其他使用者下載。 若需要關於建立和下載使用者自製內容的資訊,請見 Steam 雲端相關文獻。

一旦添加後,就算使用者更改或刪除了雲端上的檔案,依然可以讀取內容。

接收排行榜項目

ISteamUserStats::DownloadLeaderboardEntries 可使用從 ISteamUserStats::FindLeaderboard 得到的控制代碼來接收排行榜項目。

接收完 GetDownloadedLeaderboardEntry所有的項目後,將會釋放項目資料,而 LeaderboardScoresDownloaded_t 的 SteamLeaderboardEntries_t in 將無法使用。

接收排行榜資訊

有了 FindLeaderboard 傳回的排行榜控制代碼,您可使用下列呼叫接收排行榜的資訊:

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType