一起玩

PlayDrop 遊戲的排行榜

在 catalogue.json 中宣告排行榜，用 sdk.leaderboards 提交分數，並顯示前幾名與玩家周邊的排名。包含分數類型、限制與更新規則。

排行榜讓玩家有理由重玩，也有排名可以分享。PlayDrop 會儲存每位玩家在每個排行榜上的最佳分數，並顯示在遊戲上。

宣告排行榜

將它加入 catalogue.json 中的遊戲：

json

{
  "leaderboards": [
    { "key": "high-score", "displayName": "High score", "description": "Most points in one run",
      "scoreType": "INTEGER", "sort": "DESC", "unitLabel": "pts" },
    { "key": "best-time", "displayName": "Fastest run", "description": "Time to reach the flag",
      "scoreType": "TIME_MS", "sort": "ASC" }
  ]
}

key：3 到 64 個字元，以小寫字母開頭，其後為小寫字母、數字、_、. 或 -。
scoreType 和 sort 有兩種組合：INTEGER 搭配 DESC（越高越好，分數為 0 以上）或 TIME_MS 搭配 ASC（越低越好，正的毫秒數）。
unitLabel 是選用的顯示文字。

發布後，鍵無法移除，它的 scoreType 和 sort 也無法變更。若要停用，請設定 "status": "RETIRED"。排行榜需要套件。

提交與讀取分數

const result = await sdk.leaderboards.submitScore("high-score", 1200);
// { accepted, improved, previousBestScore, bestScore, rank, previousRank, bestScoreAt, leaderboard }
if (result.improved) showNewBest(result.bestScore, result.rank);

const { leaderboard } = await sdk.leaderboards.get("high-score", { top: 10, aroundMe: 3 });
// leaderboard: { definition, top, player, playerEntry, aroundPlayer }

const { leaderboards } = await sdk.leaderboards.list();

分數必須是安全整數。只有更好的分數才會取代最佳成績。
top 接受 1 到 100 筆紀錄，aroundMe 接受玩家上下各 1 到 20 筆。
list({ includeRetired: true }) 也會傳回已停用的排行榜。

在一局結束時提交，而不是每一幀都提交，且只在 play 階段提交。像處理任何網路呼叫一樣處理遭拒的呼叫；保持遊戲可玩。

訪客與離線

你可以不檢查登入狀態就提交。完全沒有玩家工作階段時，提交會正常完成，但不會儲存。宣告支援裝置資料的主機端（例如支援離線的 PlayDrop App）會保留離線時取得的分數，並在之後同步；它們的離線讀取只會顯示玩家自己的最佳成績，沒有排名。在其他地方，提交需要網路連線。

排行榜不做的事

SDK 中沒有地區、定時重設、賽季或自動發放的每週獎品。若要每週排行榜，請在你自己的設計中納入週次，例如每個賽季在新版本中宣告一個新的鍵。

相關：成就、雲端存檔、分享分數。

一起玩