Eranio
Color theme

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.1 and publish the interface through a reverse proxy with HTTPS (nginx, Apache, Caddy). The proxy can also add its own limits.
  • Set a token as 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. Use trustProxy: true only 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) and AchievementProgressEvent in the package de.eranio.achievements.hytale.api can be registered with getEventRegistry().registerGlobal(...) when the Achievements jar is on your compile path.
  • Callbacks without a dependency. addUnlockCheck(owner, function) receives a map with uuid, name, achievement, tier, key and vetoes the unlock by returning false. addProgressListener(owner, consumer) receives uuid, name, key, previous and current. 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_players above) 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 call AchievementsApi.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.