Erfolge

Base: /api/achievements

Katalog, Rangliste und Spielerfortschritt eines optionalen Erfolge-Plugins

Verarbeitung: AchievementsHandler

Endpunkte

GET /api/achievements/status Erfolge-Status abfragen GET /api/achievements/categories Kategorien auflisten GET /api/achievements/achievements Erfolge auflisten GET /api/achievements/players Spieler auflisten GET /api/achievements/player/{name} Spielerprofil abfragen GET /api/achievements/recent Letzte Freischaltungen GET /api/achievements/server-firsts Server-Premieren auflisten POST /api/achievements/grant Erfolg vergeben POST /api/achievements/revoke Erfolg entziehen

GET /api/achievements/status

Erfolge-Status abfragen

Zeigt, ob ein Erfolge-Plugin installiert ist, und falls ja dessen API-Version, Plugin-Version und Variante (gameKey).

Antwort-Beispiel

{
  "available": true,
  "apiVersion": 1,
  "pluginVersion": "1.3.5",
  "gameKey": "vulkim"
}

cURL

curl -X GET 'http://localhost:5550/api/achievements/status' \
  -H 'X-Admin-Token: YOUR_TOKEN'

`gameKey` ist normalerweise default. Eine angepasste Variante wie Vulkim meldet ihren eigenen Schlüssel. Ist kein Erfolge-Plugin installiert, antwortet dieser Endpunkt trotzdem mit 200 und nur available: false, alle anderen Erfolge-Endpunkte liefern dann 404.

Internes Verhalten

Sucht zuerst das allgemeine Erfolge-Plugin, dann die Vulkim-Variante, über eine feste Klassenliste.

GET /api/achievements/categories

Kategorien auflisten

Liefert alle Erfolge-Kategorien mit Symbol, deutschem und englischem Namen und der Anzahl Erfolge je Kategorie.

Antwort-Beispiel

[
  {
    "id": "zeit",
    "icon": "clock",
    "name_de": "Spielzeit",
    "name_en": "Playtime",
    "total": 8
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/categories' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Ruft die categories-Methode des erkannten Erfolge-Plugins per Reflection auf.

GET /api/achievements/achievements

Erfolge auflisten

Liefert den vollständigen Erfolge-Katalog mit Kategorie, Stufe, Ziel, Geltungsbereich, deutschem und englischem Namen und Beschreibung, ob er geheim ist, und wie oft er serverweit schon freigeschaltet wurde.

Antwort-Beispiel

[
  {
    "id": "spielzeit_10h",
    "category": "zeit",
    "tier": "bronze",
    "hidden": false,
    "goal": 36000,
    "scope": "personal",
    "name_de": "Durchhalten",
    "name_en": "Staying Power",
    "desc_de": "Verbringe 10 Stunden auf dem Server",
    "desc_en": "Spend 10 hours on the server",
    "unlockedCount": 42
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/achievements' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Ruft die achievements-Methode per Reflection auf, unlockedCount stammt aus einer separaten Zählung je Erfolg.

GET /api/achievements/players

Spieler auflisten

Liefert eine Seite der Spieler mit Anzahl Freischaltungen, Gesamtpunkten, letztem Login und Spielzeit.

Parameter

Name	Typ	Pflicht	Beschreibung
`limit`	integer	Nein	Seitengröße, Standard 25, maximal 500
`offset`	integer	Nein	Versatz für die nächste Seite, Standard 0

Antwort-Beispiel

[
  {
    "uuid": "5a6a1c2e-0000-0000-0000-000000000000",
    "name": "Eranio",
    "unlocked": 12,
    "total": 340,
    "lastSeen": 1760000000000,
    "playtimeSeconds": 54000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/players?limit=25&offset=0' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Liest eine Seite der Spielerliste aus der Speicherschicht des Plugins, keine Reflection nötig.

GET /api/achievements/player/{name}

Spielerprofil abfragen

Liefert Spielzeit, aktiven Titel, freigeschaltete Erfolge mit Zeitpunkt und den Fortschritt bei laufenden Erfolgen für einen Spieler.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername oder UUID

Antwort-Beispiel

{
  "uuid": "5a6a1c2e-0000-0000-0000-000000000000",
  "name": "Eranio",
  "playtimeSeconds": 54000,
  "activeTitle": "Spielzeit Meister",
  "unlocked": [
    {
      "id": "spielzeit_10h",
      "unlockedAt": 1759999999000
    }
  ],
  "progress": [
    {
      "id": "spielzeit_50h",
      "current": 36000,
      "goal": 180000
    }
  ]
}

cURL

curl -X GET 'http://localhost:5550/api/achievements/player/Eranio' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Löst den Namen zuerst über das laufende Online-Profil auf, sonst über die Speicherschicht. Antwortet mit 404 bei unbekanntem Spieler.

GET /api/achievements/recent

Letzte Freischaltungen

Liefert die zuletzt freigeschalteten Erfolge serverweit mit Spieler, Erfolg und Zeitpunkt.

Parameter

Name	Typ	Pflicht	Beschreibung
`limit`	integer	Nein	Anzahl, Standard 20, maximal 200

Antwort-Beispiel

[
  {
    "player": "Eranio",
    "achievement": "spielzeit_10h",
    "at": 1759999999000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/recent?limit=20' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Liest die letzten Freischaltungen aus der Speicherschicht, neueste zuerst.

GET /api/achievements/server-firsts

Server-Premieren auflisten

Liefert zu jedem als Server-Premiere geltenden Erfolg, wer ihn als Erster auf dem Server freigeschaltet hat.

Antwort-Beispiel

[
  {
    "achievement": "erster_boss",
    "uuid": "5a6a1c2e-0000-0000-0000-000000000000",
    "name": "Eranio",
    "at": 1759999999000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/server-firsts' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Liest die gespeicherten Server-Premieren aus der Speicherschicht.

POST /api/achievements/grant

Erfolg vergeben

Schaltet einen Erfolg für einen Spieler frei.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`player`	string	Ja	Spielername oder UUID, muss online sein
`id`	string	Ja	ID des Erfolgs

Antwort-Beispiel

{
  "success": true,
  "player": "Eranio",
  "id": "spielzeit_10h"
}

cURL

curl -X POST 'http://localhost:5550/api/achievements/grant' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"player": "Eranio", "id": "spielzeit_10h"}'

Funktioniert nur, solange der Spieler online ist, das Plugin braucht dafür ein geladenes Profil.

Internes Verhalten

Löst den Spieler über das Online-Profil auf und schaltet den Katalogeintrag frei.

POST /api/achievements/revoke

Erfolg entziehen

Entzieht einem Spieler einen bereits freigeschalteten Erfolg wieder.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`player`	string	Ja	Spielername oder UUID, muss online sein
`id`	string	Ja	ID des Erfolgs

Antwort-Beispiel

{
  "success": true,
  "player": "Eranio",
  "id": "spielzeit_10h"
}

cURL

curl -X POST 'http://localhost:5550/api/achievements/revoke' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"player": "Eranio", "id": "spielzeit_10h"}'

Funktioniert nur, solange der Spieler online ist.

Internes Verhalten

Löst den Spieler über das Online-Profil auf, entzieht den Erfolg und löscht den Eintrag zusätzlich asynchron aus der Speicherschicht.