# Rankingi w grach PlayDrop

Zadeklaruj rankingi w catalogue.json, wysyłaj wyniki przez sdk.leaderboards i pokazuj czołówkę oraz sąsiadów gracza. Typy wyników, limity i zasady zmian.

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

Rankingi dają graczom powód, by grać ponownie, i pozycję, którą mogą się pochwalić. PlayDrop przechowuje najlepszy wynik każdego gracza w każdym rankingu i pokazuje go przy grze.

## Zadeklaruj ranking

Dodaj go do aplikacji w [catalogue.json](https://www.playdrop.ai/pl/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`: od 3 do 64 znaków, zaczyna się małą literą, po której następują małe litery, cyfry, `_`, `.` lub `-`.
- `scoreType` i `sort` występują w dwóch parach: `INTEGER` z `DESC` (wygrywa wyższy, wyniki od 0 wzwyż) lub `TIME_MS` z `ASC` (wygrywa niższy, dodatnie milisekundy).
- `unitLabel` to opcjonalny tekst do wyświetlania.

Po publikacji klucza nie można usunąć, a jego `scoreType` i `sort` nie mogą się zmienić. Aby przestać go używać, ustaw `"status": "RETIRED"`. Rankingi wymagają [pakietu](https://www.playdrop.ai/pl/create/learn/packaging).

## Wysyłaj i odczytuj wyniki

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

- Wyniki to bezpieczne liczby całkowite. Tylko lepszy wynik zastępuje rekord.
- `top` przyjmuje od 1 do 100 wpisów, a `aroundMe` od 1 do 20 po każdej stronie gracza.
- `list({ includeRetired: true })` zwraca też wycofane rankingi.

Wysyłaj wynik na koniec rozgrywki, a nie w każdej klatce, i tylko w fazie `play`. Obsługuj odrzucone wywołania jak każde wywołanie sieciowe; gra musi pozostać grywalna.

## Goście i tryb offline

Możesz wysyłać wyniki bez sprawdzania logowania. Bez żadnej sesji gracza wysłanie kończy się powodzeniem, ale wynik nie zostaje zapisany. Hosty obsługujące dane na urządzeniu, takie jak aplikacje PlayDrop działające offline, zachowują wynik zdobyty offline i synchronizują go później; ich odczyty offline pokazują tylko najlepszy wynik gracza, bez pozycji. W innych miejscach wysłanie wyniku wymaga połączenia.

## Czego rankingi nie robią

SDK nie oferuje regionów, zaplanowanych resetów, sezonów ani automatycznych cotygodniowych nagród. Jeśli chcesz mieć ranking tygodniowy, uwzględnij tydzień we własnym projekcie, na przykład nowy klucz na sezon zadeklarowany w nowej wersji.

Powiązane: [osiągnięcia](https://www.playdrop.ai/pl/create/learn/achievements), [zapisy w chmurze](https://www.playdrop.ai/pl/create/learn/cloud-saves), [udostępnianie wyniku](https://www.playdrop.ai/pl/create/learn/social).

## Powiązane poradniki

- [Osiągnięcia](https://www.playdrop.ai/pl/create/learn/achievements): Zadeklaruj osiągnięcia standardowe i przyrostowe z ikonami w catalogue.json, odblokowuj je i zgłaszaj postęp przez sdk.achievements.
- [Zapisy w chmurze](https://www.playdrop.ai/pl/create/learn/cloud-saves): Zapisuj i wczytuj postępy graczy przez sdk.me.appData i sdk.me.updateAppData, dla gości i zalogowanych, z zasadami zapisu, podglądów i gry offline.
- [catalogue.json](https://www.playdrop.ai/pl/create/learn/catalogue-json): Pola catalogue.json gier PlayDrop: tożsamość, strona gry, tryby gry, powierzchnie, logowanie, Instant, wstępne ładowanie, media, tłumaczenia, wyniki i serwery.