Interfaces for websites and mods
Eranio Published on: 15. November 2026
Achievements (Hytale): Interfaces for websites and other plugins
Three ways to work with the data: a read only web interface for your own website, a Java API for other mods, and own achievements from a file. All of them work on your own server without eranio.de and without any panel.
Web interface (read only)
The plugin can answer JSON requests over HTTP. It is off by default.
"webApi": {
"enabled": true,
"port": 8765,
"bind": "127.0.0.1",
"token": "a-long-random-text",
"corsOrigins": ["https://example.org"],
"rateLimitPerMinute": 120,
"trustProxy": false
}
| Key | Meaning |
|---|---|
enabled |
Starts the interface with the server |
port, bind |
Where it listens. 127.0.0.1 is only reachable from the same machine, use a reverse proxy for the internet |
token |
If set, every request needs the header Authorization: Bearer <token>. If empty, anybody who can reach the port can read the public data below |
corsOrigins |
Websites that may call the interface from a browser (* allows all). Needed only for JavaScript on another domain |
rateLimitPerMinute |
Requests per address and minute, 0 switches the limit off |
trustProxy |
Use the X-Forwarded-For header of your reverse proxy as the visitor address for the limit |
The interface only reads. Players with a private profile never appear. It never returns IP addresses or other personal data besides name, UUID and progress.
Endpoints
Every answer is JSON with the field schema (currently 1). Successful answers carry the payload in data, errors carry error with code and message. Time values are ISO 8601 in UTC. Fields are only ever added, never renamed inside schema 1.
| Request | Answer |
|---|---|
GET /api/v1/status |
Plugin version, API version, game, number of achievements and categories, players online and known |
GET /api/v1/players?limit=50&offset=0 |
Players sorted by points (limit 1 to 200). Private profiles are skipped, so a page can be shorter than limit |
GET /api/v1/players/{name or uuid} |
One player with points, unlocked_by_tier, points_by_tier, unlocks and progress. Secret achievements show up in progress only after they are unlocked |
GET /api/v1/leaderboard?by=points&limit=10 |
Ranking by points, unlocked or playtime (limit 1 to 100) with a rank per row |
GET /api/v1/achievements |
The catalog with categories and achievements. Secret ones show ??? and no goal. Includes unlocked_count and rarity_percent |
GET /api/v1/recent?limit=20 |
The latest unlocks of public players |
Example for 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 }
]
}
Example for an error:
{ "schema": 1, "error": { "code": "not_found", "message": "Unknown player" } }
| Status | error.code |
Meaning |
|---|---|---|
| 400 | bad_request |
A parameter has a wrong value |
| 401 | unauthorized |
Token missing or wrong |
| 404 | not_found |
Unknown player or endpoint, or a private profile |
| 405 | method_not_allowed |
Only GET and OPTIONS are accepted |
| 429 | rate_limited |
Too many requests, wait the seconds from the Retry-After header |
| 500 | internal_error |
Unexpected error, see the server log |
Data of players who are online is current. Saved values of players who are offline are at most one minute old.
Examples
curl:
curl -H 'Authorization: Bearer a-long-random-text' 'http://127.0.0.1:8765/api/v1/leaderboard?by=points&limit=5'
Plain PHP with a cache file (asks the server at most once a 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 a-long-random-text\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'] . ' points') . "<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 on a website (needs your domain in corsOrigins, and a read only token is not secret in a browser, so use an empty token or a proxy on your own 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 + ' points';
list.appendChild(li);
});
});
</script>
Security
- Keep
bind: 127.0.0.1and publish the interface through a reverse proxy with HTTPS (nginx, Apache, Caddy). The proxy can also add its own limits. - Set a
tokenas soon as the port is reachable from other machines, and keep it out of JavaScript that visitors can read. For a public leaderboard let your own server fetch the data and cache it, as in the PHP examples. - Only list the websites you really use in
corsOrigins. UsetrustProxy: trueonly when a proxy you control sits in front.
Java API for other mods
The API lives in the package de.eranio.achievements.hytale.api. All methods are static and use only Java standard types, so you can call them directly when you add the Achievements jar as a compileOnly file dependency, or through reflection without any dependency. Without a running Achievements they return empty results or false.
Reading
All methods are static, take and return only Java standard types and never throw. Times are milliseconds since 1970 (UTC).
| Method | Returns |
|---|---|
apiVersion(), pluginVersion(), gameKey() |
Versions (API version 2) and the key default |
categories(), achievements() |
The catalog as maps with names and descriptions in German and English, tier, goal, scope and unlockedCount |
player(uuidOrName) |
A map with uuid, name, points, unlockedByTier, pointsByTier, playtimeSeconds, activeTitle, unlocked (list of id, unlockedAt) and progress (list of id, current, goal). Empty if the player is unknown |
players(limit, offset), leaderboard(by, limit) |
Rows with uuid, name, unlocked, total (points), lastSeen, playtimeSeconds. by is points, unlocked or playtime |
recentUnlocks(limit), serverFirsts() |
The latest unlocks and the server firsts |
progress(player, key) |
The current value of a counter |
Reading touches the storage. Call it away from the main thread on busy servers.
Writing
| Method | Effect |
|---|---|
addProgress(player, key, amount) |
Raises a counter of an online player. Achievements bound to the counter unlock on their own |
raiseProgress(player, key, value) |
Raises a counter to at least this value |
grant(player, id), revoke(player, id) |
Unlocks or removes an achievement of an online player |
registerAchievement(owner, map) |
Adds an achievement at runtime. The map has id, key, goal and optionally category, categoryNameDe, categoryNameEn, categoryIcon, tier, hidden, nameDe, descDe, nameEn, descEn. Returns false for an invalid definition |
unregisterAchievements(owner) |
Removes everything the owner registered and returns how many |
Events and checks
Two ways, use whatever fits your mod:
- Event bus.
AchievementUnlockEvent(cancellable) andAchievementProgressEventin the packagede.eranio.achievements.hytale.apican be registered withgetEventRegistry().registerGlobal(...)when the Achievements jar is on your compile path. - Callbacks without a dependency.
addUnlockCheck(owner, function)receives a map withuuid,name,achievement,tier,keyand vetoes the unlock by returningfalse.addProgressListener(owner, consumer)receivesuuid,name,key,previousandcurrent.removeListeners(owner)removes both kinds.
Example
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();
}
}
If you do not want a compile time dependency, call the same static methods through reflection: Class.forName("de.eranio.achievements.hytale.api.AchievementsApi").
Own achievements from a file
Create mods/Eranio_Achievements/custom-achievements.json (the old name custom-achievements.json still works) next to the bundled catalog. It has the same structure as the bundled achievements.json and is merged on start and on achievementsadmin reload. An id that exists already is replaced.
{
"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 is bronze, silber, gold or legendaer (10, 25, 50 or 100 points). key names the counter that is compared with goal.
Two kinds of triggers:
- Built in counters. The plugin already keeps counters you can use as
key. The most useful ones:
| Counter | Counts |
|---|---|
playtime_seconds, night_seconds, day_seconds |
Time online, at night, by day |
blocks_broken, blocks_placed, items_crafted, items_picked_up |
Blocks and items |
mob_kills, deaths, kills_pvp |
Combat |
collected_<item>, crafted_<item>, placed_<item>, broken_<item> |
One kind of item, with the game id in lower case, for example collected_rock_gem_diamond |
kills_<creature> |
One kind of creature, for example kills_zombie |
zones_discovered, portals_entered, instances_discovered |
Exploration |
times_slept, chests_opened, merchant_trades, mount_uses, mount_seconds |
Everyday play |
food_eaten_total, potions_drunk_total |
Food and potions |
- Manual. A key that no tracker fills (like
helped_playersabove) is only raised by hand or by another mod. From the console or a script:achievementsadmin progress <player> <id or counter> <amount>. For<id or counter>you can give an achievement id or the counter name,<amount>is added. Other mods callAchievementsApi.addProgress.
Tables for MySQL
With storage.type: mysql a website can read the tables directly. Write through the API, not into the tables.
| Table | Columns |
|---|---|
ach_players |
uuid, name, first_join, last_seen (ms), private_profile (1 = hide), active_title, points, achievements (count), playtime_seconds |
ach_counters |
uuid, ckey, value |
ach_sets |
uuid, skey, value (for example visited biomes) |
ach_unlocks |
uuid, achievement, unlocked_at (ms) |
ach_server_counters |
ckey, value (server wide counters) |
ach_server_firsts |
achievement, uuid, name, achieved_at (ms) |
ach_achievements |
The catalog: id, sort, category, category_de, category_en, tier, points, hidden, icon, goal, name_de, desc_de, hint_de, name_en, desc_en, hint_en |
Skip rows with private_profile = 1 on public pages, and do not show hint_* or the texts of secret achievements (hidden = 1) that a player has not unlocked.