# Bảng xếp hạng cho game PlayDrop

Khai báo bảng xếp hạng trong catalogue.json, gửi điểm bằng sdk.leaderboards, hiển thị hạng đầu và người chơi xung quanh. Loại điểm, giới hạn và quy tắc cập nhật.

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

Bảng xếp hạng cho người chơi một lý do để chơi lại và một thứ hạng để chia sẻ. PlayDrop lưu điểm cao nhất của từng người chơi trên mỗi bảng xếp hạng và hiển thị nó trên game.

## Khai báo một bảng xếp hạng

Thêm nó vào ứng dụng trong [catalogue.json](https://www.playdrop.ai/vi/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 đến 64 ký tự, bắt đầu bằng một chữ cái thường, tiếp theo là chữ cái thường, chữ số, `_`, `.` hoặc `-`.
- `scoreType` và `sort` đi theo hai cặp: `INTEGER` với `DESC` (cao hơn thắng, điểm từ 0 trở lên) hoặc `TIME_MS` với `ASC` (thấp hơn thắng, số mili giây dương).
- `unitLabel` là văn bản hiển thị tùy chọn.

Sau khi xuất bản, không thể xóa một khóa và không thể đổi `scoreType` hay `sort` của nó. Hãy ngừng dùng một bảng bằng `"status": "RETIRED"`. Bảng xếp hạng cần một [gói](https://www.playdrop.ai/vi/create/learn/packaging).

## Gửi và đọc điểm

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

- Điểm là số nguyên an toàn. Chỉ điểm tốt hơn mới thay thế kỷ lục.
- `top` chấp nhận từ 1 đến 100 mục và `aroundMe` từ 1 đến 20 mục ở mỗi phía của người chơi.
- `list({ includeRetired: true })` trả về cả các bảng đã ngừng dùng.

Hãy gửi điểm vào cuối một lượt chơi, không phải ở mỗi khung hình, và chỉ trong giai đoạn `play`. Xử lý các lệnh gọi bị từ chối như mọi lệnh gọi mạng khác; giữ cho game vẫn chơi được.

## Khách và chơi ngoại tuyến

Bạn có thể gửi điểm mà không cần kiểm tra đăng nhập. Khi hoàn toàn không có phiên người chơi, lần gửi vẫn hoàn tất nhưng không được lưu. Các host có hỗ trợ dữ liệu trên thiết bị, như các ứng dụng PlayDrop chơi được ngoại tuyến, giữ điểm đạt được khi ngoại tuyến và đồng bộ sau; khi đọc ngoại tuyến, chúng chỉ hiển thị kỷ lục của chính người chơi, không có thứ hạng. Ở những nơi khác, việc gửi điểm cần kết nối mạng.

## Những gì bảng xếp hạng không làm

SDK không có khu vực, đặt lại theo lịch, mùa giải hay tự động trao giải hằng tuần. Để có bảng xếp hạng theo tuần, hãy đưa tuần vào thiết kế của riêng bạn, chẳng hạn một khóa mới cho mỗi mùa được khai báo trong một phiên bản mới.

Liên quan: [thành tích](https://www.playdrop.ai/vi/create/learn/achievements), [lưu đám mây](https://www.playdrop.ai/vi/create/learn/cloud-saves), [chia sẻ điểm](https://www.playdrop.ai/vi/create/learn/social).

## Hướng dẫn liên quan

- [Thành tích](https://www.playdrop.ai/vi/create/learn/achievements): Khai báo thành tích thường và thành tích tích lũy kèm biểu tượng trong catalogue.json, mở khóa và báo tiến trình bằng sdk.achievements.
- [Lưu đám mây](https://www.playdrop.ai/vi/create/learn/cloud-saves): Lưu và tải tiến trình người chơi bằng sdk.me.appData và updateAppData, cho khách và người chơi đã đăng nhập, kèm quy tắc ghi, xem trước và chơi ngoại tuyến.
- [catalogue.json](https://www.playdrop.ai/vi/create/learn/catalogue-json): Các trường catalogue.json game PlayDrop dùng: định danh, trang giới thiệu, chế độ chơi, màn hình, đăng nhập, Instant, tải trước, media, bản dịch, điểm và máy chủ.