# Logros para juegos de PlayDrop

Declara logros estándar e incrementales con iconos en catalogue.json, desbloquéalos e informa del progreso con sdk.achievements.

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

Los logros marcan objetivos en tu juego, con un icono y una descripción que los jugadores ven en PlayDrop. Funcionan para invitados y para jugadores con la sesión iniciada.

## Declara los logros

```json
{
  "achievements": [
    { "key": "first-win", "displayName": "First flag", "description": "Reach the flag once",
      "kind": "STANDARD", "icon": "achievements/first-win.png" },
    { "key": "collector", "displayName": "Collector", "description": "Collect 100 stars",
      "kind": "INCREMENTAL", "maxProgress": 100, "icon": "achievements/collector.png" },
    { "key": "secret-room", "displayName": "Secret room", "description": "Find the hidden room",
      "kind": "STANDARD", "hidden": true, "icon": "achievements/secret-room.png" }
  ]
}
```

- `key` sigue el mismo formato que las claves de las [clasificaciones](https://www.playdrop.ai/es/create/learn/leaderboards).
- `kind` es `STANDARD` (se desbloquea una vez) o `INCREMENTAL` (se desbloquea cuando el progreso llega a `maxProgress`, un entero positivo).
- `icon` es un PNG incluido en el paquete. Usa una imagen cuadrada y clara que se entienda en tamaños pequeños.
- `hidden: true` mantiene en secreto el nombre y la descripción hasta que se desbloquea.

Las claves publicadas no se pueden eliminar, y `kind`, `maxProgress` y `hidden` no pueden cambiar. Retira un logro con `"status": "RETIRED"`.

## Desbloquea e informa del progreso

```js
await sdk.achievements.unlock("first-win");
await sdk.achievements.setProgressAtLeast("collector", starsCollected);

const { achievements } = await sdk.achievements.list();
const { achievement } = await sdk.achievements.get("collector");
```

- `setProgressAtLeast` recibe el total acumulado hasta el momento, nunca un incremento. El progreso solo sube, tiene como límite `maxProgress` y desbloquea el logro al alcanzarlo.
- Ambas llamadas devuelven `{ accepted, changed, unlocked, progress, unlockedAt, achievement }`; `changed` es false cuando no ha pasado nada nuevo, así que puedes mostrar tu propio aviso una sola vez.
- `list({ includeHiddenDefinitions: true, includeRetired: true })` incluye las definiciones ocultas y retiradas.

Desbloquea logros solo durante partidas reales, nunca en vistas previas ni capturas. Sin ninguna sesión de jugador, las llamadas se resuelven sin guardarse.

## Buenos logros

Combina logros iniciales que enseñen a jugar con objetivos a largo plazo. Nombra la acción, no la recompensa: «Gana sin recibir daño» dice qué hay que hacer. Una docena de logros bien pensados vale más que cien triviales.

## Guías relacionadas

- [Clasificaciones](https://www.playdrop.ai/es/create/learn/leaderboards): 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.
- [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.