Eranio
Farbthema

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.1 stehen 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-origins nur Websites ein, die du wirklich nutzt. trust-proxy: true nur, 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 sources bindet einen Zähler an eine Spielstatistik, siehe die Konfigurations-Anleitung.
  • Befehls-Zähler. Der Abschnitt commands zä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.