# Obiettivi per i giochi PlayDrop

Dichiara obiettivi standard e incrementali con icone in catalogue.json, sbloccali e segnala i progressi con sdk.achievements.

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

Gli obiettivi segnano i traguardi del tuo gioco, con un’icona e una descrizione che i giocatori vedono su PlayDrop. Funzionano sia per gli ospiti sia per i giocatori che hanno effettuato l’accesso.

## Dichiara gli obiettivi

```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 lo stesso formato delle chiavi delle [classifiche](https://www.playdrop.ai/it/create/learn/leaderboards).
- `kind` è `STANDARD` (si sblocca una volta) oppure `INCREMENTAL` (si sblocca quando il progresso raggiunge `maxProgress`, un intero positivo).
- `icon` è un PNG nel pacchetto. Usa un’immagine quadrata e chiara che si legga anche a dimensioni ridotte.
- `hidden: true` tiene segreti il nome e la descrizione fino allo sblocco.

Le chiavi pubblicate non si possono rimuovere, e `kind`, `maxProgress` e `hidden` non possono cambiare. Ritira un obiettivo con `"status": "RETIRED"`.

## Sblocca e segnala i progressi

```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` riceve il totale raggiunto finora, mai un incremento. Il progresso può solo aumentare, è limitato a `maxProgress` e sblocca l’obiettivo a quel valore.
- Entrambe le chiamate restituiscono `{ accepted, changed, unlocked, progress, unlockedAt, achievement }`; `changed` è false quando non è successo nulla di nuovo, così puoi mostrare la tua notifica una sola volta.
- `list({ includeHiddenDefinitions: true, includeRetired: true })` include le definizioni nascoste e ritirate.

Sblocca gli obiettivi solo durante il gioco vero, mai nelle anteprime o nelle acquisizioni. Senza alcuna sessione giocatore, le chiamate si risolvono senza salvare nulla.

## Buoni obiettivi

Alterna obiettivi iniziali che insegnano il gioco a traguardi a lungo termine. Indica l’azione, non la ricompensa: «Vinci senza subire danni» dice cosa fare. Una dozzina di obiettivi ben pensati vale più di cento banali.

## Guide correlate

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