# Conquistas para jogos do PlayDrop

Declare conquistas padrão e incrementais com ícones no catalogue.json, desbloqueie-as e informe o progresso com sdk.achievements.

Source: https://www.playdrop.ai/pt-br/create/learn/achievements

As conquistas marcam objetivos no seu jogo, com um ícone e uma descrição que os jogadores veem no PlayDrop. Elas funcionam para convidados e jogadores logados.

## Declare as conquistas

```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` segue o mesmo formato das chaves de [placar](https://www.playdrop.ai/pt-br/create/learn/leaderboards).
- `kind` é `STANDARD` (desbloqueada uma vez) ou `INCREMENTAL` (desbloqueada quando o progresso chega a `maxProgress`, um inteiro positivo).
- `icon` é um PNG dentro do pacote. Use uma imagem quadrada e nítida, que continue legível em tamanhos pequenos.
- `hidden: true` mantém o nome e a descrição em segredo até o desbloqueio.

Chaves publicadas não podem ser removidas, e `kind`, `maxProgress` e `hidden` não podem mudar. Aposente uma conquista com `"status": "RETIRED"`.

## Desbloqueie e informe o progresso

```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` recebe o total até agora, nunca um incremento. O progresso só aumenta, é limitado a `maxProgress` e desbloqueia a conquista nesse ponto.
- As duas chamadas retornam `{ accepted, changed, unlocked, progress, unlockedAt, achievement }`; `changed` é falso quando nada de novo aconteceu, então você pode mostrar seu próprio aviso uma única vez.
- `list({ includeHiddenDefinitions: true, includeRetired: true })` inclui as definições ocultas e aposentadas.

Desbloqueie só durante o jogo de verdade, nunca em prévias ou capturas. Sem nenhuma sessão de jogador, as chamadas são resolvidas sem que nada seja armazenado.

## Boas conquistas

Misture conquistas iniciais, que ensinam o jogo, com objetivos de longo prazo. Dê nome à ação, não à recompensa: "Vença sem levar dano" diz o que fazer. Uma dúzia de conquistas bem pensadas vale mais que cem triviais.

## Guias relacionados

- [Placares](https://www.playdrop.ai/pt-br/create/learn/leaderboards): Declare placares no catalogue.json, envie pontuações com sdk.leaderboards e mostre o topo e os vizinhos do jogador. Tipos de pontuação, limites e atualizações.
- [Salvamentos na nuvem](https://www.playdrop.ai/pt-br/create/learn/cloud-saves): Salve e carregue o progresso com sdk.me.appData e sdk.me.updateAppData, para convidados e jogadores logados, com as regras de gravação, prévias e modo offline.
- [catalogue.json](https://www.playdrop.ai/pt-br/create/learn/catalogue-json): Os campos do catalogue.json que os jogos do PlayDrop usam: identidade, listagem, modos de jogo, superfícies, login, Instantâneo, pré-carregamento, mídia, traduções, pontuações e servidores.