# Papan peringkat untuk game PlayDrop

Deklarasikan papan peringkat di catalogue.json, kirim skor lewat sdk.leaderboards, tampilkan peringkat teratas dan sekitar pemain. Jenis skor, batas, aturan.

Source: https://www.playdrop.ai/id/create/learn/leaderboards

Papan peringkat memberi pemain alasan untuk bermain lagi dan peringkat untuk dibagikan. PlayDrop menyimpan skor terbaik setiap pemain per papan peringkat dan menampilkannya di game.

## Deklarasikan papan peringkat

Tambahkan ke aplikasi di [catalogue.json](https://www.playdrop.ai/id/create/learn/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 sampai 64 karakter, diawali huruf kecil, lalu huruf kecil, angka, `_`, `.`, atau `-`.
- `scoreType` dan `sort` hadir dalam dua pasangan: `INTEGER` dengan `DESC` (yang lebih tinggi menang, skor 0 atau lebih) atau `TIME_MS` dengan `ASC` (yang lebih rendah menang, milidetik positif).
- `unitLabel` adalah teks tampilan opsional.

Setelah diterbitkan, kunci tidak bisa dihapus dan `scoreType` serta `sort`-nya tidak bisa diubah. Berhenti memakai papan peringkat dengan `"status": "RETIRED"`. Papan peringkat memerlukan [paket](https://www.playdrop.ai/id/create/learn/packaging).

## Kirim dan baca skor

```js
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();
```

- Skor berupa bilangan bulat aman. Hanya skor yang lebih baik yang menggantikan skor terbaik.
- `top` menerima 1 sampai 100 entri dan `aroundMe` 1 sampai 20 di setiap sisi pemain.
- `list({ includeRetired: true })` juga mengembalikan papan peringkat yang sudah pensiun.

Kirim skor di akhir permainan, bukan di setiap frame, dan hanya pada fase `play`. Tangani panggilan yang ditolak seperti panggilan jaringan lainnya; pastikan game tetap bisa dimainkan.

## Tamu dan offline

Anda bisa mengirim skor tanpa memeriksa login. Tanpa sesi pemain sama sekali, pengiriman selesai tanpa disimpan. Host yang menyatakan dukungan data perangkat, seperti aplikasi PlayDrop yang bisa offline, menyimpan skor yang dibuat secara offline dan menyinkronkannya nanti; pembacaan offline di sana hanya menampilkan skor terbaik pemain itu sendiri, tanpa peringkat. Di tempat lain, pengiriman skor memerlukan koneksi.

## Yang tidak dilakukan papan peringkat

Tidak ada wilayah, reset terjadwal, musim, atau hadiah mingguan otomatis di SDK. Untuk papan peringkat mingguan, masukkan minggu ke dalam rancangan Anda sendiri, misalnya kunci baru per musim yang dideklarasikan di versi baru.

Terkait: [pencapaian](https://www.playdrop.ai/id/create/learn/achievements), [simpanan cloud](https://www.playdrop.ai/id/create/learn/cloud-saves), [membagikan skor](https://www.playdrop.ai/id/create/learn/social).

## Panduan terkait

- [Pencapaian](https://www.playdrop.ai/id/create/learn/achievements): Deklarasikan pencapaian standar dan bertahap dengan ikon di catalogue.json, lalu buka dan laporkan progresnya dengan sdk.achievements.
- [Simpanan cloud](https://www.playdrop.ai/id/create/learn/cloud-saves): Simpan dan muat progres dengan sdk.me.appData dan sdk.me.updateAppData untuk tamu dan pemain yang sudah masuk, plus aturan penulisan, pratinjau, dan offline.
- [catalogue.json](https://www.playdrop.ai/id/create/learn/catalogue-json): Field catalogue.json yang dipakai game PlayDrop: identitas, listingan, mode bermain, permukaan, login, Instan, pramuat, media, terjemahan, skor, dan server.