Player data

One network-wide identity per player, isolated per-game data, currencies, and periodic leaderboards. Look up anyone, online or offline.

Every player has one network-wide identity plus isolated per-game data, so two minigames never clobber each other’s stats. You load a player on join, read and increment from anywhere on your network, and look up any player, online or offline, by UUID or name.

Load on join

fetchPlayerData is the entry point. It upserts the player row (creating it the first time you see them) and returns their full profile: identity, currencies, per-game namespaces, and first/last seen. Pass the gameMode this server runs and the GameType (engine) the player arrived on.

Join.java

// On join: upsert the player and read their profile back.
hive.player()
    .fetchPlayerData(player.uuid(), player.name(), "skywars", GameType.HYTALE)
    .thenAccept(data -> {
      long coins = data.getNamespace("skywars") != null ? /* ... */ 0 : 0;
      welcome(player, data.getCurrencies(), data.getLastSeen());
    });

The returned PlayerData carries everything durable about the player:

Field	What it is
`getUuid()` / `getUsername()`	stable identity
`getFirstSeen()` / `getLastSeen()`	network-wide timestamps
`getCurrencies()`	balances, one `CurrencyBalance` per currency
`getNamespace(name)`	this game’s isolated JSON data
`getGameType()`	the engine the player was first seen on

Game modes scope everything

A gameMode string (default "global") is the dimension that keeps games separate. Statistics, namespaces and leaderboards all live under it, so "wins" in "skywars" is a different number from "wins" in "bedwars", and neither touches the network-wide "global" profile. You pass the mode on every call; there’s no shared bucket to accidentally write into.

Currencies and identity are the exception, they’re network-wide: one wallet, one name, one first/last-seen, shared across every game.

What’s in a player

The profile above is the whole surface, split into four areas:

Statistics & leaderboards - the counter-and-leaderboard primitive. Increment a named stat and the hub keeps the rolling daily/weekly/monthly/lifetime windows for free.
Currencies - network-wide balances on the player, defined per network from the dashboard, for a shared economy across games.
Namespaces - your game’s private, versioned JSON store, invisible to every other game on the network.
Look anyone up - read-only profile and search lookups for /whois, moderation and friend lists; online or offline, never creates a row.

What it connects to

Your minigame’s wins and kills land here automatically when you record them through the match context.
Matchmaking and the server registry feed the live online / connection state these lookups read.

Full reference is rolling out alongside the Hytale beta. Need a field or a lookup that isn’t here yet? Ask us, we answer fast.