Eranio
Farbthema

Schnittstellen für Websites und Mods

Eranio Veröffentlicht am: 15. November 2026

Achievements (Hytale): 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 Mods 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.

"webApi": {
  "enabled": true,
  "port": 8765,
  "bind": "127.0.0.1",
  "token": "a-long-random-text",
  "corsOrigins": ["https://example.org"],
  "rateLimitPerMinute": 120,
  "trustProxy": 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
corsOrigins Websites, die die Schnittstelle aus dem Browser aufrufen dürfen (* erlaubt alle). Nur nötig für JavaScript auf einer anderen Domain
rateLimitPerMinute Anfragen pro Adresse und Minute, 0 schaltet die Grenze ab
trustProxy 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 corsOrigins 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 corsOrigins nur Websites ein, die du wirklich nutzt. trustProxy: true nur, wenn ein Proxy unter deiner Kontrolle davorsitzt.

Java-API für andere Mods

Die API liegt im Paket de.eranio.achievements.hytale.api. Alle Methoden sind statisch und nutzen nur Java-Standardtypen. Du rufst sie direkt auf, wenn du das Achievements-Jar als compileOnly-Dateiabhängigkeit einbindest, oder per Reflection ganz ohne Abhängigkeit. Ohne laufendes Achievements liefern sie leere Ergebnisse oder false.

Lesen

Alle Methoden sind statisch, nehmen und liefern nur Java-Standardtypen und werfen nie eine Ausnahme. Zeiten sind Millisekunden seit 1970 (UTC).

Methode Ergebnis
apiVersion(), pluginVersion(), gameKey() Versionen (API-Version 2) und der Schlüssel default
categories(), achievements() Der Katalog als Maps mit Namen und Beschreibungen auf Deutsch und Englisch, Stufe, Ziel, Bereich und unlockedCount
player(uuidOrName) Eine Map mit uuid, name, points, unlockedByTier, pointsByTier, playtimeSeconds, activeTitle, unlocked (Liste aus id, unlockedAt) und progress (Liste aus id, current, goal). Leer, wenn der Spieler unbekannt ist
players(limit, offset), leaderboard(by, limit) Zeilen mit uuid, name, unlocked, total (Punkte), lastSeen, playtimeSeconds. by ist points, unlocked oder playtime
recentUnlocks(limit), serverFirsts() Die letzten Freischaltungen und die Server-Premieren
progress(player, 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(player, key, amount) Erhöht einen Zähler eines Spielers, der online ist. An den Zähler gebundene Erfolge schalten sich selbst frei
raiseProgress(player, key, value) Hebt einen Zähler mindestens auf diesen Wert
grant(player, id), revoke(player, id) Schaltet einen Erfolg für einen Spieler, der online ist, frei oder nimmt ihn weg
registerAchievement(owner, map) Fügt zur Laufzeit einen Erfolg hinzu. Die Map hat id, key, goal und optional category, categoryNameDe, categoryNameEn, categoryIcon, tier, hidden, nameDe, descDe, nameEn, descEn. Liefert false bei ungültiger Definition
unregisterAchievements(owner) Entfernt alles, was der Besitzer registriert hat, und liefert die Anzahl

Ereignisse und Prüfungen

Zwei Wege, nimm den, der zu deiner Mod passt:

  • Ereignisbus. AchievementUnlockEvent (abbrechbar) und AchievementProgressEvent im Paket de.eranio.achievements.hytale.api lassen sich mit getEventRegistry().registerGlobal(...) registrieren, wenn das Achievements-Jar auf deinem Compile-Pfad liegt.
  • Rückrufe ohne Abhängigkeit. addUnlockCheck(owner, function) bekommt eine Map mit uuid, name, achievement, tier, key und verhindert die Freischaltung, wenn sie false liefert. addProgressListener(owner, consumer) bekommt uuid, name, key, previous und current. removeListeners(owner) entfernt beide Arten.

Beispiel

public final class ExampleAddon extends JavaPlugin {

    private static final String OWNER = "ExampleAddon";

    public ExampleAddon(@Nonnull JavaPluginInit init) {
        super(init);
    }

    @Override
    protected void setup() {
        super.setup();
        AchievementsApi.registerAchievement(OWNER, Map.ofEntries(
            Map.entry("id", "example_visitor"),
            Map.entry("category", "example"),
            Map.entry("categoryNameDe", "Beispiel-Mod"),
            Map.entry("categoryNameEn", "Example mod"),
            Map.entry("tier", "silber"),
            Map.entry("key", "example_visits"),
            Map.entry("goal", 10),
            Map.entry("nameDe", "Stammgast"),
            Map.entry("descDe", "Besuche den Ort 10 Mal."),
            Map.entry("nameEn", "Regular"),
            Map.entry("descEn", "Visit the place 10 times.")));

        AchievementsApi.addUnlockCheck(OWNER, info -> !"Griefer".equals(info.get("name")));
        AchievementsApi.addProgressListener(OWNER, info -> {
            if ("example_visits".equals(info.get("key")) && ((Number) info.get("current")).longValue() == 5) {
                greetHalfway(String.valueOf(info.get("name")));
            }
        });

        getEventRegistry().registerGlobal(AchievementUnlockEvent.class, event -> {
            if (event.getAchievementId().equals("example_visitor")) {
                greetHalfway(event.getPlayerName());
            }
        });
        getEventRegistry().registerGlobal(AchievementProgressEvent.class, event -> {
            if (event.getKey().equals("example_visits")) {
                greetHalfway(event.getPlayerName());
            }
        });
    }

    public void playerVisited(String playerName) {
        AchievementsApi.addProgress(playerName, "example_visits", 1);
    }

    public long totalPoints(String playerName) {
        Object points = AchievementsApi.player(playerName).get("points");
        return points instanceof Number number ? number.longValue() : 0;
    }

    private void greetHalfway(String playerName) {
    }

    @Override
    protected void shutdown() {
        AchievementsApi.unregisterAchievements(OWNER);
        AchievementsApi.removeListeners(OWNER);
        super.shutdown();
    }
}

Willst du keine Abhängigkeit zur Compile-Zeit, rufst du dieselben statischen Methoden per Reflection auf: Class.forName("de.eranio.achievements.hytale.api.AchievementsApi").


Eigene Erfolge aus einer Datei

Lege mods/Eranio_Achievements/custom-achievements.json (der alte Name custom-achievements.json geht weiter) neben dem mitgelieferten Katalog an. Sie hat denselben Aufbau wie die mitgelieferte achievements.json und wird beim Start und bei achievementsadmin reload dazugemischt. Eine ID, die es schon gibt, wird ersetzt.

{
  "categories": {
    "server": { "icon": "trophy", "de": "Unser Server", "en": "Our server" }
  },
  "achievements": {
    "diamond_hoarder": {
      "category": "server",
      "tier": "silber",
      "key": "collected_rock_gem_diamond",
      "goal": 500,
      "de": { "name": "Diamantenhort", "desc": "Sammle 500 Diamanten." },
      "en": { "name": "Diamond hoard", "desc": "Collect 500 diamonds." }
    },
    "helper": {
      "category": "server",
      "tier": "gold",
      "key": "helped_players",
      "goal": 10,
      "hidden": true,
      "de": { "name": "Helfer", "desc": "Hilf 10 Spielern." },
      "en": { "name": "Helper", "desc": "Help 10 players." }
    }
  }
}

tier ist bronze, silber, gold oder legendaer (10, 25, 50 oder 100 Punkte). key nennt den Zähler, der mit goal verglichen wird.

Zwei Arten von Auslösern:

  • Eingebaute Zähler. Das Plugin führt schon Zähler, die du als key nutzen kannst. Die wichtigsten:
Zähler Zählt
playtime_seconds, night_seconds, day_seconds Zeit online, nachts, tagsüber
blocks_broken, blocks_placed, items_crafted, items_picked_up Blöcke und Gegenstände
mob_kills, deaths, kills_pvp Kampf
collected_<item>, crafted_<item>, placed_<item>, broken_<item> Eine Gegenstandsart, mit der Spiel-ID in Kleinbuchstaben, zum Beispiel collected_rock_gem_diamond
kills_<creature> Eine Kreaturenart, zum Beispiel kills_zombie
zones_discovered, portals_entered, instances_discovered Erkundung
times_slept, chests_opened, merchant_trades, mount_uses, mount_seconds Alltag im Spiel
food_eaten_total, potions_drunk_total Essen und Tränke
  • Manuell. Ein Schlüssel, den kein Beobachter füllt (wie helped_players oben), wird nur von Hand oder von einer anderen Mod erhöht. Von der Konsole oder aus einem Skript: achievementsadmin progress <Spieler> <Erfolg oder Zähler> <Menge>. Bei <Erfolg oder Zähler> geht eine Erfolgs-ID oder der Zählername, <Menge> wird addiert. Andere Mods rufen AchievementsApi.addProgress auf.

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_server_counters ckey, value (serverweite Zähler)
ach_server_firsts achievement, uuid, name, achieved_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.