# Erfolge für PlayDrop-Spiele

Standard- und Fortschrittserfolge mit Symbolen in catalogue.json deklarieren, freischalten und Fortschritt mit sdk.achievements melden.

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

Erfolge markieren Ziele in deinem Spiel, mit einem Symbol und einer Beschreibung, die Spieler auf PlayDrop sehen. Sie funktionieren für Gäste und angemeldete Spieler.

## Erfolge deklarieren

```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` folgt demselben Format wie die Schlüssel von [Bestenlisten](https://www.playdrop.ai/de/create/learn/leaderboards).
- `kind` ist `STANDARD` (wird einmal freigeschaltet) oder `INCREMENTAL` (wird freigeschaltet, wenn der Fortschritt `maxProgress` erreicht, eine positive ganze Zahl).
- `icon` ist ein PNG im Paket. Verwende ein klares, quadratisches Bild, das auch in kleiner Größe gut erkennbar ist.
- `hidden: true` hält Name und Beschreibung geheim, bis der Erfolg freigeschaltet ist.

Veröffentlichte Schlüssel können nicht entfernt werden, und `kind`, `maxProgress` und `hidden` können sich nicht mehr ändern. Lege einen Erfolg mit `"status": "RETIRED"` still.

## Freischalten und Fortschritt melden

```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` nimmt den bisherigen Gesamtwert entgegen, niemals eine Differenz. Der Fortschritt steigt nur, ist auf `maxProgress` begrenzt und schaltet dort den Erfolg frei.
- Beide Aufrufe liefern `{ accepted, changed, unlocked, progress, unlockedAt, achievement }`; `changed` ist false, wenn nichts Neues passiert ist, sodass du deinen eigenen Hinweis nur einmal zeigst.
- `list({ includeHiddenDefinitions: true, includeRetired: true })` enthält auch versteckte und stillgelegte Definitionen.

Schalte Erfolge nur beim echten Spielen frei, niemals in Vorschauen oder Aufnahmen. Ganz ohne Spielersitzung werden die Aufrufe erfolgreich abgeschlossen, aber nicht gespeichert.

## Gute Erfolge

Mische frühe Erfolge, die das Spiel beibringen, mit langfristigen Zielen. Benenne die Aktion, nicht die Belohnung: „Gewinne, ohne Schaden zu nehmen“ sagt, was zu tun ist. Ein Dutzend durchdachter Erfolge ist besser als hundert belanglose.

## Verwandte Anleitungen

- [Bestenlisten](https://www.playdrop.ai/de/create/learn/leaderboards): Bestenlisten in catalogue.json deklarieren, Punkte mit sdk.leaderboards senden, Spitzenplätze und Nachbarn des Spielers zeigen. Punktarten, Grenzen, Update-Regeln.
- [Cloud-Spielstände](https://www.playdrop.ai/de/create/learn/cloud-saves): Spielerfortschritt mit sdk.me.appData und sdk.me.updateAppData speichern und laden, für Gäste und Angemeldete; Regeln für Schreiben, Vorschau und Offline.
- [catalogue.json](https://www.playdrop.ai/de/create/learn/catalogue-json): Die catalogue.json-Felder, die PlayDrop-Spiele verwenden: Identität, Texte, Spielweise, Formate, Anmeldung, Sofort, Vorladen, Medien, Übersetzungen, Punktestände und Server.