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.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
corsOriginsnur Websites ein, die du wirklich nutzt.trustProxy: truenur, 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) undAchievementProgressEventim Paketde.eranio.achievements.hytale.apilassen sich mitgetEventRegistry().registerGlobal(...)registrieren, wenn das Achievements-Jar auf deinem Compile-Pfad liegt. - Rückrufe ohne Abhängigkeit.
addUnlockCheck(owner, function)bekommt eine Map mituuid,name,achievement,tier,keyund verhindert die Freischaltung, wenn siefalseliefert.addProgressListener(owner, consumer)bekommtuuid,name,key,previousundcurrent.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
keynutzen 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_playersoben), 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 rufenAchievementsApi.addProgressauf.
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.