Schnittstellen für Websites und Plugins
Eranio Veröffentlicht am: 15. November 2026
Achievements (Minecraft): Schnittstellen für Websites und andere Plugins
Drei Wege, mit den Daten zu arbeiten: eine lesende Web-Schnittstelle für die eigene Website, eine Java-API für andere Plugins und eigene Erfolge aus einer Datei. Alles läuft auf deinem eigenen Server, ohne eranio.de und ohne Panel.
Web-Schnittstelle (nur lesend)
Das Plugin kann JSON-Anfragen über HTTP beantworten. Sie ist standardmäßig aus.
web-api:
enabled: true
port: 8765
bind: 127.0.0.1
token: 'a-long-random-text'
cors-origins: ['https://example.org']
rate-limit-per-minute: 120
trust-proxy: false
| Schlüssel | Bedeutung |
|---|---|
enabled |
Startet die Schnittstelle mit dem Server |
port, bind |
Wo sie lauscht. 127.0.0.1 ist nur auf demselben Rechner erreichbar, fürs Internet einen Reverse-Proxy davorsetzen |
token |
Wenn gesetzt, braucht jede Anfrage den Header Authorization: Bearer <token>. Leer heißt: wer den Port erreicht, kann die öffentlichen Daten unten lesen |
cors-origins |
Websites, die die Schnittstelle aus dem Browser aufrufen dürfen (* erlaubt alle). Nur nötig für JavaScript auf einer anderen Domain |
rate-limit-per-minute |
Anfragen pro Adresse und Minute, 0 schaltet die Grenze ab |
trust-proxy |
Nimmt den Header X-Forwarded-For deines Reverse-Proxys als Besucheradresse für die Grenze |
Die Schnittstelle liest nur. Spieler mit privatem Profil erscheinen nie. Sie liefert keine IP-Adressen und außer Name, UUID und Fortschritt keine persönlichen Daten.
Endpunkte
Jede Antwort ist JSON mit dem Feld schema (aktuell 1). Erfolgreiche Antworten tragen die Nutzdaten in data, Fehler tragen error mit code und message. Zeitangaben sind ISO 8601 in UTC. Felder kommen innerhalb von Schema 1 nur hinzu und werden nie umbenannt.
| Anfrage | Antwort |
|---|---|
GET /api/v1/status |
Plugin-Version, API-Version, Spiel, Zahl der Erfolge und Kategorien, Spieler online und bekannt |
GET /api/v1/players?limit=50&offset=0 |
Spieler nach Punkten sortiert (limit 1 bis 200). Private Profile fehlen, eine Seite kann deshalb kürzer als limit sein |
GET /api/v1/players/{Name oder UUID} |
Ein Spieler mit Punkten, unlocked_by_tier, points_by_tier, unlocks und progress. Geheime Erfolge stehen erst nach der Freischaltung in progress |
GET /api/v1/leaderboard?by=points&limit=10 |
Rangliste nach points, unlocked oder playtime (limit 1 bis 100) mit rank je Zeile |
GET /api/v1/achievements |
Der Katalog mit categories und achievements. Geheime zeigen ??? und kein Ziel. Dazu unlocked_count und rarity_percent |
GET /api/v1/recent?limit=20 |
Die letzten Freischaltungen öffentlicher Spieler |
Beispiel für GET /api/v1/leaderboard?limit=2:
{
"schema": 1,
"data": [
{ "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Alex", "unlocked": 87, "points": 2310, "playtime_seconds": 412800, "last_seen": "2026-11-15T09:12:44Z", "rank": 1 },
{ "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "Steve", "unlocked": 64, "points": 1675, "playtime_seconds": 301200, "last_seen": "2026-11-14T21:03:10Z", "rank": 2 }
]
}
Beispiel für einen Fehler:
{ "schema": 1, "error": { "code": "not_found", "message": "Unknown player" } }
| Status | error.code |
Bedeutung |
|---|---|---|
| 400 | bad_request |
Ein Parameter hat einen falschen Wert |
| 401 | unauthorized |
Token fehlt oder ist falsch |
| 404 | not_found |
Unbekannter Spieler oder Endpunkt, oder ein privates Profil |
| 405 | method_not_allowed |
Nur GET und OPTIONS werden angenommen |
| 429 | rate_limited |
Zu viele Anfragen, so viele Sekunden warten wie im Header Retry-After |
| 500 | internal_error |
Unerwarteter Fehler, siehe Server-Log |
Daten von Spielern, die online sind, sind aktuell. Gespeicherte Werte von Spielern, die offline sind, sind höchstens eine Minute alt.
Beispiele
curl:
curl -H 'Authorization: Bearer ein-langer-zufallstext' 'http://127.0.0.1:8765/api/v1/leaderboard?by=points&limit=5'
Reines PHP mit Cache-Datei (fragt den Server höchstens einmal pro Minute):
<?php
function leaderboard(): array
{
$cache = sys_get_temp_dir() . '/achievements-leaderboard.json';
if (is_file($cache) && time() - filemtime($cache) < 60) {
return json_decode(file_get_contents($cache), true)['data'];
}
$context = stream_context_create(['http' => [
'header' => "Authorization: Bearer ein-langer-zufallstext\r\n",
'timeout' => 3,
]]);
$body = @file_get_contents('http://127.0.0.1:8765/api/v1/leaderboard?limit=10', false, $context);
if ($body === false) {
return is_file($cache) ? json_decode(file_get_contents($cache), true)['data'] : [];
}
file_put_contents($cache, $body);
return json_decode($body, true)['data'];
}
foreach (leaderboard() as $row) {
echo htmlspecialchars($row['rank'] . '. ' . $row['name'] . ': ' . $row['points'] . ' Punkte') . "<br>\n";
}
Laravel:
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;
$top = Cache::remember('achievements.leaderboard', 60, function () {
return Http::withToken(config('services.achievements.token'))
->timeout(3)
->get(config('services.achievements.url') . '/api/v1/leaderboard', ['limit' => 10])
->throw()
->json('data');
});
JavaScript auf einer Website (deine Domain muss in cors-origins stehen. Ein Token ist im Browser nicht geheim, nimm deshalb kein Token oder einen Proxy auf deinem eigenen Server):
<ol id="top"></ol>
<script>
fetch('https://stats.example.org/api/v1/leaderboard?limit=10')
.then((r) => r.json())
.then((body) => {
const list = document.getElementById('top');
body.data.forEach((row) => {
const li = document.createElement('li');
li.textContent = row.name + ': ' + row.points + ' Punkte';
list.appendChild(li);
});
});
</script>
Sicherheit
- Lass
bind: 127.0.0.1stehen und veröffentliche die Schnittstelle über einen Reverse-Proxy mit HTTPS (nginx, Apache, Caddy). Der Proxy kann eigene Grenzen ergänzen. - Setze ein
token, sobald der Port von anderen Rechnern erreichbar ist, und halte es aus JavaScript heraus, das Besucher lesen können. Für eine öffentliche Rangliste holt dein eigener Server die Daten ab und speichert sie zwischen, wie in den PHP-Beispielen. - Trage in
cors-originsnur Websites ein, die du wirklich nutzt.trust-proxy: truenur, wenn ein Proxy unter deiner Kontrolle davorsitzt.
Java-API für andere Plugins
Die API liegt im Paket de.eranio.achievements.minecraft.api. Du holst sie über den Bukkit-Dienstmanager mit AchievementsApi.get(), das null liefert, wenn Achievements nicht installiert ist. Trage softdepend: [Achievements] (oder depend) in deine plugin.yml ein und binde das kleine Jar Achievements-API-1.0.0.jar als compileOnly-Dateiabhängigkeit ein, es enthält nur die API-Klassen und Ereignisse.
Lesen
| Methode | Ergebnis |
|---|---|
apiVersion(), pluginVersion(), gameKey() |
Versionen und der Spielschlüssel (minecraft) |
categories(), achievements() |
Der Katalog mit Namen und Beschreibungen auf Deutsch und Englisch, Stufe, Punkten, Ziel, Zahl der Freischaltungen und Seltenheit |
player(uuidOrName) |
PlayerInfo mit Punkten, Punkten und Freischaltungen je Stufe, Freischalt-Liste und Fortschritts-Liste |
players(limit, offset), leaderboard(by, limit) |
Zeilen als PlayerSummary, by ist points, unlocked oder playtime |
recentUnlocks(limit) |
Die letzten Freischaltungen öffentlicher Spieler |
progress(uuid, key) |
Der aktuelle Wert eines Zählers |
Lesen greift auf den Speicher zu. Auf ausgelasteten Servern nicht im Haupt-Thread aufrufen.
Schreiben
| Methode | Wirkung |
|---|---|
addProgress(uuid, key, amount) |
Erhöht einen Zähler. An den Zähler gebundene Erfolge schalten sich selbst frei |
raiseProgress(uuid, key, value) |
Hebt einen Zähler mindestens auf diesen Wert |
grant(uuid, id), revoke(uuid, id) |
Schaltet einen Erfolg für einen Spieler, der online ist, frei oder nimmt ihn weg |
registerAchievement(owner, CustomAchievement) |
Fügt zur Laufzeit einen Erfolg hinzu, mit Kategorie, Stufe, Ziel, Symbol und Texten auf Deutsch und Englisch. Freischaltungen bleiben, wenn der Besitzer abgeschaltet wird |
unregisterAchievements(owner) |
Entfernt alles, was der Besitzer registriert hat |
Ereignisse
AchievementUnlockEvent wird vor einer Freischaltung ausgelöst und lässt sich abbrechen. AchievementProgressEvent wird bei jeder Änderung eines Zählers ausgelöst und trägt den Schlüssel, den vorherigen und den aktuellen Wert.
Beispiel
public final class ExampleAddon extends JavaPlugin implements Listener {
private AchievementsApi achievements;
@Override
public void onEnable() {
achievements = AchievementsApi.get();
if (achievements == null) {
getLogger().warning("Achievements is not installed");
return;
}
achievements.registerAchievement(this, CustomAchievement.builder("example_lucky_fisher")
.category("example", "Beispiel-Plugin", "Example plugin", "FISHING_ROD")
.tier("silber")
.icon("COD")
.counter("example_lucky_catches", 10)
.german("Glückspilz", "Fange 10 Mal einen Schatz.")
.english("Lucky angler", "Catch treasure 10 times.")
.build());
getServer().getPluginManager().registerEvents(this, this);
}
@EventHandler
public void onFish(PlayerFishEvent event) {
if (event.getState() == PlayerFishEvent.State.CAUGHT_FISH && event.getCaught() != null) {
achievements.addProgress(event.getPlayer().getUniqueId(), "example_lucky_catches", 1);
}
}
@EventHandler
public void onUnlock(AchievementUnlockEvent event) {
if (event.getPlayer().getWorld().getName().equals("blocked")) {
event.setCancelled(true);
}
}
@EventHandler
public void onProgress(AchievementProgressEvent event) {
if (event.getKey().equals("example_lucky_catches")) {
event.getPlayer().sendMessage("Catches: " + event.getCurrent());
}
}
public int pointsOf(Player player) {
return achievements.player(player.getUniqueId().toString()).map(AchievementsApi.PlayerInfo::points).orElse(0);
}
}
Eigene Erfolge aus einer Datei
Lege plugins/Achievements/custom-achievements.yml neben dem mitgelieferten Katalog an. Sie hat denselben Aufbau und wird beim Start und bei /achievements reload dazugemischt. Eine ID, die es schon gibt, wird ersetzt.
categories:
server:
icon: COMPASS
de: Unser Server
en: Our server
commands:
warps_used: ['/warp', '/home']
achievements:
traveller:
category: server
tier: silber
icon: ENDER_PEARL
key: warps_used
goal: 25
de: {name: "Vielreisender", desc: "Nutze 25 Mal /warp oder /home."}
en: {name: "Frequent traveller", desc: "Use /warp or /home 25 times."}
helper:
category: server
tier: gold
icon: EMERALD
key: helped_players
goal: 10
de: {name: "Helfer", desc: "Hilf 10 Spielern."}
en: {name: "Helper", desc: "Help 10 players."}
Drei Arten von Auslösern:
- Statistik. Der Abschnitt
sourcesbindet einen Zähler an eine Spielstatistik, siehe die Konfigurations-Anleitung. - Befehls-Zähler. Der Abschnitt
commandszählt jedes Mal, wenn ein Spieler einen der genannten Befehle ausführt. - Manuell. Ein Schlüssel ohne Quelle und ohne Befehl wird nur von Hand oder von einem anderen Plugin erhöht. Von der Konsole oder aus einem Skript:
/achievements progress <Spieler> <Erfolg oder Zähler> <Menge>. Bei<Erfolg oder Zähler>geht eine Erfolgs-ID oder der Zählername,<Menge>wird addiert.
Tabellen für MySQL
Mit storage.type: mysql kann eine Website die Tabellen direkt lesen. Geschrieben wird über die API, nicht in die Tabellen.
| Tabelle | Spalten |
|---|---|
ach_players |
uuid, name, first_join, last_seen (ms), private_profile (1 = verbergen), active_title, points, achievements (Anzahl), playtime_seconds |
ach_counters |
uuid, ckey, value |
ach_sets |
uuid, skey, value (zum Beispiel besuchte Biome) |
ach_unlocks |
uuid, achievement, unlocked_at (ms) |
ach_achievements |
Der Katalog: id, sort, category, category_de, category_en, tier, points, hidden, icon, goal, name_de, desc_de, hint_de, name_en, desc_en, hint_en |
Überspringe auf öffentlichen Seiten Zeilen mit private_profile = 1 und zeige weder hint_* noch die Texte geheimer Erfolge (hidden = 1), die ein Spieler nicht freigeschaltet hat.