# Ranglijsten voor PlayDrop-games

Declareer ranglijsten in catalogue.json, verstuur scores met sdk.leaderboards en toon de top en de buren van de speler. Scoretypen, limieten en updateregels.

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

Ranglijsten geven spelers een reden om opnieuw te spelen en een positie om te delen. PlayDrop bewaart per ranglijst de beste score van elke speler en toont die bij de game.

## Een ranglijst declareren

Voeg hem toe aan de app in [catalogue.json](https://www.playdrop.ai/nl/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 tot 64 tekens, beginnend met een kleine letter, gevolgd door kleine letters, cijfers, `_`, `.` of `-`.
- `scoreType` en `sort` komen in twee paren: `INTEGER` met `DESC` (hoger wint, scores van 0 of meer) of `TIME_MS` met `ASC` (lager wint, positieve milliseconden).
- `unitLabel` is optionele weergavetekst.

Na publicatie kun je een sleutel niet meer verwijderen en kunnen `scoreType` en `sort` niet veranderen. Stop met het gebruik van een ranglijst met `"status": "RETIRED"`. Ranglijsten hebben een [pakket](https://www.playdrop.ai/nl/create/learn/packaging) nodig.

## Scores versturen en lezen

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

- Scores zijn veilige gehele getallen. Alleen een betere score vervangt het record.
- `top` accepteert 1 tot 100 vermeldingen en `aroundMe` 1 tot 20 aan elke kant van de speler.
- `list({ includeRetired: true })` geeft ook buiten gebruik gestelde ranglijsten terug.

Verstuur scores aan het einde van een ronde, niet elk frame, en alleen in de fase `play`. Handel afgewezen aanroepen af zoals elke netwerkaanroep; houd de game speelbaar.

## Gasten en offline

Je kunt scores versturen zonder het inloggen te controleren. Zonder enige spelersessie slaagt een inzending zonder dat er iets wordt opgeslagen. Hosts die ondersteuning voor apparaatgegevens aangeven, zoals PlayDrop-apps die offline werken, bewaren een offline behaalde score en synchroniseren die later; offline tonen ze alleen het eigen record van de speler, zonder positie. Elders heeft een inzending een verbinding nodig.

## Wat ranglijsten niet doen

De SDK kent geen regio's, geplande resets, seizoenen of automatische wekelijkse prijzen. Wil je een wekelijkse ranglijst, neem de week dan op in je eigen ontwerp, bijvoorbeeld met een nieuwe sleutel per seizoen, gedeclareerd in een nieuwe versie.

Zie ook: [prestaties](https://www.playdrop.ai/nl/create/learn/achievements), [cloudsaves](https://www.playdrop.ai/nl/create/learn/cloud-saves), [een score delen](https://www.playdrop.ai/nl/create/learn/social).

## Gerelateerde gidsen

- [Prestaties](https://www.playdrop.ai/nl/create/learn/achievements): Declareer standaard- en incrementele prestaties met iconen in catalogue.json, ontgrendel ze en meld voortgang met sdk.achievements.
- [Cloudsaves](https://www.playdrop.ai/nl/create/learn/cloud-saves): Sla voortgang op en laad die met sdk.me.appData en sdk.me.updateAppData, voor gasten en ingelogde spelers, met regels voor opslaan, voorbeelden en offline.
- [catalogue.json](https://www.playdrop.ai/nl/create/learn/catalogue-json): De catalogue.json-velden die games gebruiken: identiteit, gamepagina, speelwijzen, weergaven, inloggen, Instant, vooraf laden, media, vertalingen, scores en servers.