# Bestenlisten für PlayDrop-Spiele

Bestenlisten in catalogue.json deklarieren, Punkte mit sdk.leaderboards senden, Spitzenplätze und Nachbarn des Spielers zeigen. Punktarten, Grenzen, Update-Regeln.

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

Bestenlisten geben Spielern einen Grund, noch einmal zu spielen, und eine Platzierung zum Teilen. PlayDrop speichert für jeden Spieler den besten Punktwert pro Bestenliste und zeigt ihn beim Spiel an.

## Bestenliste deklarieren

Füge sie in der [catalogue.json](https://www.playdrop.ai/de/create/learn/catalogue-json) zur App hinzu:

```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 bis 64 Zeichen, beginnend mit einem Kleinbuchstaben, dann Kleinbuchstaben, Ziffern, `_`, `.` oder `-`.
- `scoreType` und `sort` gibt es in zwei Paaren: `INTEGER` mit `DESC` (der höhere Wert gewinnt, Punktwerte ab 0) oder `TIME_MS` mit `ASC` (der niedrigere Wert gewinnt, positive Millisekunden).
- `unitLabel` ist ein optionaler Anzeigetext.

Nach der Veröffentlichung kann ein Schlüssel nicht mehr entfernt werden, und sein `scoreType` und `sort` können sich nicht ändern. Lege eine Bestenliste mit `"status": "RETIRED"` still. Bestenlisten brauchen ein [Paket](https://www.playdrop.ai/de/create/learn/packaging).

## Punktwerte senden und lesen

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

- Punktwerte sind sichere Ganzzahlen. Nur ein besserer Wert ersetzt den Bestwert.
- `top` akzeptiert 1 bis 100 Einträge und `aroundMe` 1 bis 20 auf jeder Seite des Spielers.
- `list({ includeRetired: true })` liefert auch stillgelegte Bestenlisten.

Sende am Ende eines Durchgangs, nicht in jedem Frame, und nur in der Phase `play`. Behandle abgelehnte Aufrufe wie jeden Netzwerkaufruf und halte das Spiel spielbar.

## Gäste und offline

Du kannst Punktwerte senden, ohne die Anmeldung zu prüfen. Ganz ohne Spielersitzung wird eine Einsendung erfolgreich abgeschlossen, aber nicht gespeichert. Hosts, die Unterstützung für Gerätedaten angeben, etwa offlinefähige PlayDrop-Apps, behalten einen offline erzielten Punktwert und synchronisieren ihn später; ihre Offline-Abfragen zeigen nur den eigenen Bestwert des Spielers, ohne Platzierung. Anderswo braucht eine Einsendung eine Verbindung.

## Was Bestenlisten nicht können

Im SDK gibt es keine Regionen, geplanten Zurücksetzungen, Saisons oder automatischen Wochenpreise. Für eine Wochenbestenliste baue die Woche in dein eigenes Design ein, zum Beispiel mit einem neuen Schlüssel pro Saison, deklariert in einer neuen Version.

Verwandt: [Erfolge](https://www.playdrop.ai/de/create/learn/achievements), [Cloud-Spielstände](https://www.playdrop.ai/de/create/learn/cloud-saves), [Punktwert teilen](https://www.playdrop.ai/de/create/learn/social).

## Verwandte Anleitungen

- [Erfolge](https://www.playdrop.ai/de/create/learn/achievements): Standard- und Fortschrittserfolge mit Symbolen in catalogue.json deklarieren, freischalten und Fortschritt mit sdk.achievements melden.
- [Cloud-Spielstände](https://www.playdrop.ai/de/create/learn/cloud-saves): Spielerfortschritt mit sdk.me.appData und sdk.me.updateAppData speichern und laden, für Gäste und Angemeldete; Regeln für Schreiben, Vorschau und Offline.
- [catalogue.json](https://www.playdrop.ai/de/create/learn/catalogue-json): Die catalogue.json-Felder, die PlayDrop-Spiele verwenden: Identität, Texte, Spielweise, Formate, Anmeldung, Sofort, Vorladen, Medien, Übersetzungen, Punktestände und Server.