# Classifiche per i giochi PlayDrop

Dichiara le classifiche in catalogue.json, invia punteggi con sdk.leaderboards e mostra i primi posti e i vicini del giocatore. Tipi, limiti e aggiornamenti.

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

Le classifiche danno ai giocatori un motivo per rigiocare e una posizione da condividere. PlayDrop memorizza il miglior punteggio di ogni giocatore per ciascuna classifica e lo mostra sul gioco.

## Dichiara una classifica

Aggiungila all’app in [catalogue.json](https://www.playdrop.ai/it/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`: da 3 a 64 caratteri, inizia con una lettera minuscola, poi lettere minuscole, cifre, `_`, `.` o `-`.
- `scoreType` e `sort` formano due coppie: `INTEGER` con `DESC` (vince il più alto, punteggi da 0 in su) oppure `TIME_MS` con `ASC` (vince il più basso, millisecondi positivi).
- `unitLabel` è un testo facoltativo da mostrare.

Una volta pubblicata, una chiave non si può rimuovere e i suoi `scoreType` e `sort` non possono cambiare. Smetti di usarne una con `"status": "RETIRED"`. Le classifiche richiedono un [pacchetto](https://www.playdrop.ai/it/create/learn/packaging).

## Invia e leggi i punteggi

```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 punteggi sono interi sicuri. Solo un punteggio migliore sostituisce il record.
- `top` accetta da 1 a 100 voci e `aroundMe` da 1 a 20 per ogni lato del giocatore.
- `list({ includeRetired: true })` restituisce anche le classifiche ritirate.

Invia il punteggio alla fine di una partita, non a ogni frame, e solo nella fase `play`. Gestisci le chiamate rifiutate come qualsiasi chiamata di rete; mantieni il gioco giocabile.

## Ospiti e offline

Puoi inviare punteggi senza controllare l’accesso. Senza alcuna sessione giocatore, un invio si risolve senza essere salvato. Gli host che dichiarano il supporto ai dati sul dispositivo, come le app PlayDrop che funzionano offline, conservano un punteggio ottenuto offline e lo sincronizzano più tardi; le loro letture offline mostrano solo il record del giocatore, senza posizione. Altrove un invio richiede una connessione.

## Cosa non fanno le classifiche

Nell’SDK non ci sono regioni, azzeramenti programmati, stagioni o premi settimanali automatici. Per una classifica settimanale, includi la settimana nel tuo design, per esempio con una nuova chiave per stagione dichiarata in una nuova versione.

Vedi anche: [obiettivi](https://www.playdrop.ai/it/create/learn/achievements), [salvataggi cloud](https://www.playdrop.ai/it/create/learn/cloud-saves), [condividere un punteggio](https://www.playdrop.ai/it/create/learn/social).

## Guide correlate

- [Obiettivi](https://www.playdrop.ai/it/create/learn/achievements): Dichiara obiettivi standard e incrementali con icone in catalogue.json, sbloccali e segnala i progressi con sdk.achievements.
- [Salvataggi cloud](https://www.playdrop.ai/it/create/learn/cloud-saves): Salva e carica i progressi con sdk.me.appData e sdk.me.updateAppData, per ospiti e giocatori con accesso: regole per scritture, anteprime e gioco offline.
- [catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json): Campi di catalogue.json usati dai giochi PlayDrop: identità, scheda, modalità, superfici, accesso, Instant, precarico, media, traduzioni, punteggi e server.