# Clasificaciones para juegos de PlayDrop

Declara clasificaciones en catalogue.json, envía puntuaciones con sdk.leaderboards y muestra los mejores puestos y los vecinos del jugador. Tipos, límites y reglas.

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

Las clasificaciones dan a los jugadores un motivo para volver a jugar y una posición que compartir. PlayDrop guarda la mejor puntuación de cada jugador en cada clasificación y la muestra en el juego.

## Declara una clasificación

Añádela a la app en [catalogue.json](https://www.playdrop.ai/es/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`: de 3 a 64 caracteres, empezando por una letra minúscula y seguida de letras minúsculas, dígitos, `_`, `.` o `-`.
- `scoreType` y `sort` van en dos combinaciones: `INTEGER` con `DESC` (gana la más alta, puntuaciones de 0 o más) o `TIME_MS` con `ASC` (gana la más baja, milisegundos positivos).
- `unitLabel` es un texto opcional que se muestra junto a la puntuación.

Una vez publicada, una clave no se puede eliminar y su `scoreType` y su `sort` no pueden cambiar. Deja de usar una con `"status": "RETIRED"`. Las clasificaciones necesitan un [paquete](https://www.playdrop.ai/es/create/learn/packaging).

## Envía y lee puntuaciones

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

- Las puntuaciones son enteros seguros. Solo una puntuación mejor reemplaza al récord.
- `top` acepta de 1 a 100 entradas y `aroundMe` de 1 a 20 a cada lado del jugador.
- `list({ includeRetired: true })` también devuelve las clasificaciones retiradas.

Envía la puntuación al final de una partida, no en cada fotograma, y solo en la fase `play`. Gestiona las llamadas rechazadas como cualquier llamada de red; mantén el juego jugable.

## Invitados y sin conexión

Puedes enviar puntuaciones sin comprobar el inicio de sesión. Sin ninguna sesión de jugador, un envío se resuelve sin guardarse. Los hosts que anuncian compatibilidad con datos en el dispositivo, como las apps de PlayDrop que funcionan sin conexión, conservan una puntuación conseguida sin conexión y la sincronizan más tarde; sus lecturas sin conexión muestran solo el récord del propio jugador, sin posición. En los demás casos, enviar una puntuación requiere conexión.

## Qué no hacen las clasificaciones

El SDK no ofrece regiones, reinicios programados, temporadas ni premios semanales automáticos. Para una clasificación semanal, incluye la semana en tu propio diseño, por ejemplo con una clave nueva por temporada declarada en una nueva versión.

Relacionado: [logros](https://www.playdrop.ai/es/create/learn/achievements), [partidas guardadas en la nube](https://www.playdrop.ai/es/create/learn/cloud-saves), [compartir una puntuación](https://www.playdrop.ai/es/create/learn/social).

## Guías relacionadas

- [Logros](https://www.playdrop.ai/es/create/learn/achievements): Declara logros estándar e incrementales con iconos en catalogue.json, desbloquéalos e informa del progreso con sdk.achievements.
- [Partidas guardadas en la nube](https://www.playdrop.ai/es/create/learn/cloud-saves): Guarda y carga el progreso con sdk.me.appData y sdk.me.updateAppData, para invitados y jugadores con sesión: escrituras, vistas previas y juego sin conexión.
- [catalogue.json](https://www.playdrop.ai/es/create/learn/catalogue-json): Campos de catalogue.json que usan los juegos: identidad, ficha, modos, pantallas, sesión, instantáneo, precarga, medios, idiomas, puntuaciones y servidores.