概覽

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

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

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

開始之前

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

建立排行榜

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

在網頁上建立

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


要設定排行榜，必須填入下列欄位：

• 名稱 - 開發階段內部可合理使用的名稱。
  
• 社群名稱 - 如要在社群中心展示此排行榜，在此輸入公開顯示的名稱。 若留空，則不會出現排行榜。
  
• 分類方式 - 設置排行榜的排列順序。 如果是排名式的排行榜，使用遞增。 如果是高分榜，使用遞減。
  
• 顯示類型 - 決定排行榜顯示的資料類型。 可選擇數字、秒，或毫秒。
  
• 寫入 - 如選擇受信任的，用戶端便無法設置分數，而只能由 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::k_ELeaderboardUploadScoreMethodKeepBest - Steam 會比較使用者的新分數和排行榜中的分數，並從中選擇較佳的一個（遞增的排行榜是最低分，遞減的排行榜則是最高分）。
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Steam 永遠會以新分數取代排行榜中原本的分數。
  
• ISteamUserStats::UploadLeaderboardScore 是不同步的呼叫，而上傳的結果將會以 LeaderboardScoreUploaded_t 呼叫結果傳回。 結果中包含使用者地分數是否改變的旗幟標示，以及使用者的新舊全球排名。 上傳後，Steamworks 排行榜將立刻更新並反映新的分數，並可使用 DownloadLeaderboardEntries 拿到新的項目列表。

添加使用者自製內容

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

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

接收排行榜項目

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

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

接收排行榜資訊

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

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