> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rpg-leveling.zuxaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> All notable released changes for the RPG Leveling plugin.

***

## \[0.3.10] - 2026-06-17

**Mod version:** 0.3.10 · **Game version:** Hytale 0.5.6

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### 🐛 Fixed

* **Harvest XP awarded twice** - Harvesting a crop no longer grants duplicate XP when multiple game events fire for the same harvest (F-key, sickle pickup, or block break). Farming crops are only credited once; direct-harvest plants (mana/health/stamina) still use the break-block path only.
* **Harvest XP on dry soil blocks** - Breaking or interacting with decorative soil blocks such as **Dry Dirt** (`Soil_Dirt_Dry`) and **Dry Mud** (`Soil_Mud_Dry`) no longer grants crop harvest XP. A seed-name substring match (`Plant_Seeds_Dry`) was incorrectly treating those blocks as crops.

### 🔄 Compatibility

* **Hytale server target** - Updated minimum server version to **`0.5.6`**.

***

## \[0.3.9] - 2026-06-16

**Mod version:** 0.3.9 · **Game version:** Hytale 0.5.5

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### ✨ Added

* **Crop harvest XP** - Earn XP when harvesting mature crops. Configure in **`mods/Zuxaw_RPGLeveling/HarvestingConfig.json`**: **`BlockXPBaseHarvesting`** (default 2.0), tier multipliers **`HarvestTier1Multiplier`** through **`HarvestTier4Multiplier`**, **`EnableHarvestXP`**, **`BlacklistedXPHarvestSeeds`**, **`HarvestXPCooldownSeconds`** (default 45, same plant), and per-seed overrides in **`PlantSeedsTierOverrides`** (seed id or crop block id, e.g. `"Plant_Seeds_Aubergine": 3`). Crop tiers are auto-detected from seed recipes at startup. Run **`/lvl reload`** to apply.
* **Harvest stat** - New allocatable stat with a chance to **double or triple** crop yield on harvest. On proc, you get an in-game notification. Configure in **`mods/Zuxaw_RPGLeveling/StatsLevelConfig.json`**: **`HarvestDoubleChancePerPoint`**, **`HarvestTripleChancePerPoint`**, caps, and **`MaxStatPointsHarvest`**.
* **Tame XP** - Earn XP when you tame a creature. Configure in **`mods/Zuxaw_RPGLeveling/RPGLevelingConfig.json`**: **`EnableTameXP`** (default true), **`TameXpMultiplier`** (default 1.0, same formula as mob kills), and **`BlacklistedTameEntityRoles`** (default `Citizen_`). Run **`/lvl reload`** to apply.
* **Modder API (harvest & tame)** - **`XPSource.HARVEST`** / **`HarvestContext`** and **`XPSource.TAME`** / **`TameContext`** on **`ExperienceGainedEvent`** for third-party mods.
* **Alec's Tamework (optional)** - When **`Alechilles:Alec's Tamework!`** is installed, companion XP from **feed, harvest, and breeding** is mirrored 1:1 to the owner's RPG level. Combat companion XP is not credited. No extra config; loads automatically if Tamework is present.

### 🔄 Compatibility

* **Hytale server target** - Updated minimum server version to **`0.5.5`**.

### Translation

* **Tame notification** - New string for translators in `mods/Zuxaw_RPGLeveling/languages/MessagesLanguageMapping_<lang>.json`: `notifications.creature_tamed` (shown when you tame a creature). English defaults merge on startup or **`/lvl reload`**.
* **Harvest stat and proc notifications** - New strings for translators in `mods/Zuxaw_RPGLeveling/languages/MessagesLanguageMapping_<lang>.json`: `stats.names.harvest`, `stats.descriptions.harvest`, `stats.units.harvest` (Stats GUI), and `notifications.harvest_double_yield` / `notifications.harvest_triple_yield` (double/triple yield when harvesting crops). English defaults merge on startup or **`/lvl reload`**; add or update these keys in non-English language files.

***

## \[0.3.8] - 2026-06-11

**Mod version:** 0.3.8 · **Game version:** Hytale 0.5.4

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### ✨ Added

* **Block XP blacklist** - In `mods/Zuxaw_RPGLeveling/RPGLevelingConfig.json`, **`BlacklistedXPBlocks`** (comma-separated block type IDs) excludes specific blocks from mining/woodcutting XP. Matching is **case-insensitive** (same style as **`BlacklistedEntities`**). Default: **`Tw_Feed_Carnivore,Tw_Feed_Herbivore`** (Animal Husbandry feed troughs). Set to **`""`** to allow XP from all eligible blocks. Run **`/lvl reload`** to apply.

### 🔄 Changed

* **Performance (100+ players) - level progress HUD** - The XP bar refresh no longer re-encodes its UI data on every refresh; the encoded update is cached and only rebuilt when the content actually changes (level, XP, zone or color).

### 🐛 Fixed

* **Console spam from level nameplates** - On some server versions, the server console could flood with `Failed to run task!` and `ArrayIndexOutOfBoundsException` errors every few ticks. That came from the look-at-a-mob level nameplate feature.

* **Leaderboard "Unknown Player"** - The leaderboard no longer shows "Unknown Player" for some entries. Names are resolved from online players, player save files (`DisplayName` / nameplate), and a short session cache when a player has joined this server run. If no name is available yet, the first 8 characters of the player UUID are shown instead.

### 🔄 Compatibility

* **Hytale server target** - Updated minimum server version to **`0.5.4`**.

***

## \[0.3.7] - 2026-06-03

**Mod version:** 0.3.7 · **Game version:** Hytale 0.5.3

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### ⚠️ Important

* **External database - you are responsible for player data** - When database sync is enabled and **`MirrorDataOnly`** is **`false`**, the shared database can overwrite live progression on join, **`/lvl syncdb pull`**, or admin edits. **Always back up** your database **and** `universe/players` **before** turning on two-way sync, running **`/lvl syncdb push`**, editing rows by hand, or any other action that changes stored player data. RPG Leveling does not restore lost progression if a backup was not taken.

### ✨ Added

* **External database as source of truth** - In `mods/Zuxaw_RPGLeveling/DatabaseConfig.json`, set **`MirrorDataOnly`** to **`false`** (with **`Enabled`: true**) so a shared MySQL/MariaDB/PostgreSQL/H2 database holds progression across servers. When a player row exists in the DB, join and **`/lvl syncdb pull`** apply **database** level/XP/stats/classes; missing supplemental fields (claimed rewards, language, HUD prefs, class cooldown, etc.) are filled from `universe/players` and saved back. If there is no row yet, player file data is copied to the database. On first run with an **empty** database, `universe/players` JSON files are imported once. The DB stores the same RPG fields as player save files. Default **`MirrorDataOnly`: true** keeps one-way mirror (game → DB only). Admin **`/lvl syncdb`** (`rpgleveling.command.syncdb`) pulls or pushes after manual SQL edits; **`/lvl syncdb status`** shows the active JDBC URL. Offline admin commands update the database immediately after writing the player file. See [Database sync](database-sync).

* **XP curve overrides - level cost multiplier** - In `mods/Zuxaw_RPGLeveling/XPCurveOverridesConfig.json`, each override row now supports **`LevelCostMultiplier`** (XP needed for the next level in that level range) alongside **`XpRateMultiplier`** (XP earned from kills and block break). Example: `{"From": 50, "To": 79, "XpRateMultiplier": 2.0, "LevelCostMultiplier": 0.5}` doubles XP gains and halves grind to level up at levels 50–79. HUD and `/lvl info` reflect the scaled cost. Existing **`Multiplier`** keys are renamed to **`XpRateMultiplier`** on first start after update (config migration **0.3.7**). Run **`/lvl reload`** to apply. See [XP curve overrides config](config-xp-curve-overrides).

### 🔄 Compatibility

* **Hytale server target** - Updated minimum server version to **`0.5.3`**.

### 🔄 Changed

* **Performance (100+ players) - level nameplates** - Looking at a mob or player to see their level uses far less server time when many people are online.

### 🐛 Fixed

* **Level progress HUD on join** - The XP bar above the hotbar could appear empty, black, or vanish a moment after you join until something updated your XP. It now shows your level and progress reliably as soon as you enter the world.

***

## \[0.3.6] - 2026-05-25

**Mod version:** 0.3.6 · **Game version:** Hytale 0.5.0

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### ✨ Added

* **Per-range XP-earned multipliers** - New file `mods/Zuxaw_RPGLeveling/XPCurveOverridesConfig.json`. Add `Overrides` entries with `From`, `To`, `Multiplier` to multiply XP earned (kills + block break) while the player is in that level range, e.g. `{"From": 50, "To": 79, "Multiplier": 2.0}` doubles XP gains at levels 50–79. Applied on top of `RateExp` and `ZoneRateExp`. Empty by default. Run `/lvl reload` to apply. See [XP curve overrides config](config-xp-curve-overrides).

### 🔄 Compatibility

* **Hytale server target** - Updated minimum server version to **`0.5.0`** (pre-release patchline).
* **Level progress HUD** - Migrated **MultipleHUD** to Hytale's native HUD via the keyed **`HudManager`** API
* **MultipleHUD** - Removed optional **MultipleHUD** integration; no longer required or listed in `manifest.json`.

### 🔄 Changed

* **Performance (100+ players)** - Reduced lag when many players are online: some checks are now cached instead of repeated every tick for every player
* **Max-level HUD / Stats GUI text shows total XP** - At the level cap the HUD used to show **`XP: 3666 / 3666 (MAX)`**, where both numbers were just the same value (there is no "XP needed for next level" at the cap). It now shows **`Level: 100 XP: 1003666 (MAX)`** - the **total XP a player has earned since level 1**, which is the exact same number the **Leaderboard** ranks by, so what's on your HUD and what determines your rank are now the same thing. The **Stats** and **Rewards** GUI player header gets the same treatment (`%.1f XP (MAX)` showing total XP, instead of `%.1f / %.1f XP (MAX)`). Translators: the old **`hud.level_xp_max`** key is replaced by **`hud.level_max`** (one fewer placeholder, default `Level: {0} XP: {1} (MAX)`) - the next **`/lvl reload`** drops the obsolete key and adds the new one in English to every `MessagesLanguageMapping_<lang>.json` for re-translation.

### 🐛 Fixed

* **Random HUD crash (day-one bug)** - The long-standing random kick / disconnect caused by HUD layer collisions with other mods is **definitively fixed**. Our XP bar is now scoped to its own keyed slot (`RPGLeveling_LevelProgress`) via Hytale's native `HudManager`, so it can no longer overwrite or be overwritten by another mod's HUD.
* **Leaderboard fairness at max level** - Players who hit the level cap **keep gaining XP** from kills, blocks, `/lvl addxp`, and other mods (instead of being silently capped at the moment of the level-up). The XP/Class leaderboard now ranks max-level players by the **total XP they keep earning** rather than by the size of the single reward that happened to push them over the cap, so whoever grinds the most ends up on top.

***

## \[0.3.5] - 2026-05-08

**Mod version:** 0.3.5 · **Game version:** Hytale 2026.03.26-89796e57b

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### ✨ Added

* **Per-player language** - Every player can now pick their **own language** in the **Settings → Language** tab of the Stats GUI. The HUD, notifications, level-up titles, zone warnings, kill messages and `/lvl info` all switch to the chosen language right away. The choice is saved on the player and persists across sessions.
* **Server default language** - Server admins can set the default language new players see in `mods/Zuxaw_RPGLeveling/RPGLevelingConfig.json` via the new **`DefaultLanguage`** field (default **`english`**). It is also used for server-wide messages with no specific recipient.
* **Drop-in translations** - Translation files now live in **`mods/Zuxaw_RPGLeveling/languages/`**, one file per language named **`MessagesLanguageMapping_<language>.json`** (e.g. `MessagesLanguageMapping_french.json`). Drop a file in the folder, restart the server (or run **`/lvl reload`**), and the language appears in the in-game picker. Each file declares its own display name, so adding a language is purely "drop the file in".
* **Automatic translation upgrades** - When the plugin adds new messages in an update, missing keys are added to your translation files with the English text so your GUI never shows raw keys. Your existing translations are kept untouched.
* **Legacy translation file migration** - If you previously used `MessagesLanguageMapping.json` (single file), it is moved automatically to the new `languages/` folder on first start after upgrade. If that old file was not English, rename it to the correct suffix (for example `MessagesLanguageMapping_french.json`) and set the language display name inside the file, otherwise it will appear as English in the picker.
* **Public API - player language** - Other mods can set a player’s RPG Leveling UI language using the same codes as files in **`languages/`** (for example **`english`**). They can target someone by account id or by character name (online player first, otherwise an offline profile file when one exists). Clearing the choice falls back to the server **`DefaultLanguage`** in **`RPGLevelingConfig.json`**. After you add new language files, **`/lvl reload`** picks them up.

### 🔄 Changed

* **Performance (high player count)** - Reduced world-thread overhead by
  removing repeated per-tick ECS holder allocations in hot player systems and
  optimizing HUD tick polling, which improves stability when many players are
  connected.

### 🐛 Fixed

* **Rare on-kill passive crash** - Fixed a rare severe server error that could happen when multiple on-kill passive buffs triggered at the same time. Those buffs are now handled safely so the world no longer stops from this case.

***

## \[0.3.4] - 2026-04-02

**Mod version:** 0.3.4 · **Game version:** Hytale 2026.03.26-89796e57b

[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square\&logo=ko-fi\&logoColor=white)](https://ko-fi.com/zuxaw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat-square\&logo=discord\&logoColor=white)](https://discord.gg/nGDQbjMtxY)

### ✨ Added

* **Stats GUI - Settings tab & per-player level HUD** - New **SETTINGS** sidebar tab in the RPG Leveling GUI with **Show** / **Hide level HUD** controls. Preference is stored per player in **`PlayerLevelData`** (**`HideLevelProgressHud`**) and persists across sessions. When the server disables the HUD (**`EnableHUD`**), the tab explains that and hides the toggle. **`LevelProgressHudManager.hideHud`** now actually removes the custom HUD (so it also works while the stats GUI is open and when the HUD is globally off).
* **Stats GUI - per-player notification toggles** - When **`EnableNotification`** is on, **Settings** adds **XP / progression** and (if **`EnablePassiveNotifications`**) **class passive** rows so players can turn off those toasts for themselves (**`HideXpProgressNotifications`**, **`HidePassiveNotifications`** on **`PlayerLevelData`**). Applies to XP gain, level-up / zone / kill / boost / critical / death penalty lines and passive heal-buff-damage popups (**`NotificationPreferenceHelper`**).
* **Command permissions (`rpgleveling.command.*`)** - Admin **`/lvl`** subcommands, **`/classes`**, and each **`xprateboost`** leaf use **`requirePermission`** with a dedicated node (see **`RpgLevelingPermissions`**). **`/lvl gui`** and **`/lvl info`** stay open to all players (no node). Wildcard **`rpgleveling.command.*`** covers the full admin set. **`/lvl info`** shows the admin command list when the sender has any admin node, **`hytale.command.admin`**, the wildcard, or **OP** group. Documented in [Commands](commands) and **MODINFO.md**.
* **XP boost end broadcast** - When a timed **`/lvl xprateboost`** expires on its own, players get the same kind of **large on-screen title** as at start, saying the boost **finished** (**everyone** for a global boost, **only that player** for a personal boost). **`clearall`**, **`clearplayer`**, and **`stop`** cancel the scheduled end notice so there is no “finished” title when an admin stops a boost early. Uses **`EnableNotification`** and new message keys **`notifications.xp_boost_ended_*`**.

### 🔄 Changed

* **Chat placeholders** - Mods that customize chat with format strings (for example **Essentials Plus**) may **need [Placeholder API](https://www.curseforge.com/hytale/mods/placeholder-api)** for **`%rpglevelling_*%`** tokens to show level, XP, and class instead of plain text. RPG Leveling connects to Placeholder API automatically when that mod is on the server.

***

## \[0.3.3] - 2026-03-30

**Mod version:** 0.3.3 · **Game version:** Hytale 2026.03.26-89796e57b

<img src="https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi" />

<img src="https://img.shields.io/badge/Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" />

### API ✨ Added

* **Config Defaults Override API** - External mods can now call **`RPGLevelingAPI.registerConfigDefaults(modId, configurator)`** in their `setup()` to override any RPG Leveling config default (scalar values or array appends). Overrides only apply when the on-disk value matches the bundled default (admin-customized values are never overwritten). Supports **`alsoReplaces`** for updating previous mod overrides across versions. First mod to register a field wins; conflicts are logged at startup.
* **Player class API** - New methods **`getPlayerClassInfo`**, **`getPlayerClassId`**, **`getPlayerClassTier`**, and **`getPlayerAllClassTiers`** let external mods read the player's selected class, display name, tier (0–4), kills in current tier, and all class progress. Available by UUID (Holder-only) or with PlayerRef + entity Ref + Store for world-thread contexts.

### ✨ Added

* **NameplateBuilder (optional)** - When [**Frotty27:NameplateBuilder**](https://docs.nameplatebuilder.frotty27.com/modding/quick-start) and its API are on the server, look-at **level** text is published as nameplate segment **`rpgleveling_level`** via [`register` / `remove`](https://docs.nameplatebuilder.frotty27.com/modding/register-text) so it composes with other segments; otherwise the plugin keeps using the vanilla **Nameplate** component as before.
* **Chat placeholders** - Server chat formats can use **`%rpglevelling_level%`**, **`%rpglevelling_xp%`**, **`%rpglevelling_xp_to_next%`** / **`%rpglevelling_xp_to_level%`**, **`%rpglevelling_max_level%`**, **`%rpglevelling_is_max_level%`**, and class tokens **`%rpglevelling_class%`**, **`%rpglevelling_class_display%`**, **`%rpglevelling_class_name%`**, **`%rpglevelling_class_id%`**, **`%rpglevelling_class_tier%`**.
* **Admin timed XP rate boost** - **`/lvl xprateboost`** (alias **`/lvl xpmult`**) sets an extra XP multiplier for a duration in seconds: **`all <multiplier> <seconds>`** for every player, **`player <name> <multiplier> <seconds>`** for one player (online or resolvable offline), plus **`clearall`**, **`clearplayer <name>`**, and **`stop`** (clears **global and all** per-player boosts at once). Global and per-player boosts **multiply together**. The timed multiplier applies **after** **`RateExp`** and zone rates (e.g. **`RateExp` 3** and timed **×2** ⇒ **6×** vs the raw formula baseline, not 5×). Applies to kills, block XP, and API XP; **`/lvl addxp`** is unchanged. Runtime-only (not persisted). Documented in [Commands](commands) and [Main Plugin Config](config-main).
* **Class change cooldown** - After you **change or clear** your selected class in the Stats GUI, a configurable cooldown applies before you can change again (default **5 minutes**). **`ClassChangeCooldownSeconds`** in **`Classes/ClassesGlobalConfig.json`** controls the wait (**`0`** disables the cooldown). While active, **SET** and **UNSET** show a **remaining time** (`m:ss`) and are disabled; the server also ignores class-change actions during the cooldown.

### 🔄 Changed

* **Level HUD (without MultipleHUD)** - HUD handling when **MultipleHUD** isn’t installed now **avoids full refreshes** on every update, so the level bar **updates more lightly** and **performs better**.

### 🐛 Fixed

* **On-kill timed passives** - In rare cases, when a kill triggered **several** short on-kill buffs at **once** (for example multiple class passives stacking), the server could hit a **severe error** and the world had to **stop or unload**. That situation is now handled safely.
* **Movement Speed stat after water / world change** - The game can reset ground **MovementManager** `baseSpeed` when you **swim, touch water, or change worlds**, while RPG stats are only fully re-applied when **`StatsAppliedMarker`** is cleared-so **Movement Speed** bonuses could appear to **stick at vanilla** until something else refreshed stats. A **MovementSpeedReconciliationSystem** now compares live `baseSpeed` to the RPG-expected value (when using the MovementManager path, not the engine stat-map path) and **re-applies** the stat; it **skips** while timed movement passives like **Overkill** are active so kill buffs are not overwritten.

***

## \[0.3.2] - 2026-03-26

**Mod version:** 0.3.2 · **Game version:** Hytale 2026.03.26-89796e57b

<img src="https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi" />

<img src="https://img.shields.io/badge/Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" />

### 🐛 Fixed

* **Broken world interactions on Release 4 (0.3.1)** - After updating the mod for **Hytale Release 4**, a fault in **mining and woodcutting bonuses** while you target blocks (the same area of the mod that shows up in logs as **MiningDetectionSystem**) could trigger repeated **severe server errors**-for example failed chunk ticking, complaints that the game was busy while loading chunks, or failed chunk loads. The world often **did not fully crash**, but **whole regions** could go into a **weird state** where **doors, crafting stations, and other interactions stopped responding**. This release fixes that so those areas stay usable.

***

## \[0.3.1] - 2026-03-26

**Mod version:** 0.3.1 · **Game version:** Hytale 2026.03.26-89796e57b

<img src="https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi" />

<img src="https://img.shields.io/badge/Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" />

### 🔄 Compatibility

* **Hytale Release 4 (server)** - Mining and woodcutting block bonuses target the current server APIs (block health module and chunk section resolution). Build against the Release 4 server JAR.

### 🔄 Changed

* **Mining / woodcutting (API migration)** - Per-tick block damage while targeting no longer uses removed `BlockState` / `WorldChunk.getState`; it now applies via `BlockHealthChunk.damageBlock`. Chunk refs use `ChunkUtil.chunkCoordinate` with `ChunkStore.getChunkSectionReference` so older SDK stubs without `getChunkSectionReferenceAtBlock` still compile. Swing-time multiplier via `DamageBlockEvent` is unchanged.

### ✨ Added

* **Command `/classes`** - Opens the RPG Leveling GUI directly on the **Classes** tab (same UI as `/lvl gui`). If the class system is disabled, shows a short error instead of opening the GUI.
* **Command alias `/level`** - Equivalent to `/lvl` for the full command tree (e.g. `/level gui`, `/level info`, admin subcommands). `/lvl info` also mentions `/classes` and `/level`.
* **Life Steal - flat HP plus percent** - The Life Steal passive now restores a fixed amount of HP per hit (`HealFlat`) in addition to a percentage of damage dealt (`HealPercent`). Bundled **PassivesConfig** is version **0.3.1**; servers on older passives configs get migration **0.3.1** (flat values per tier, max 2 HP flat at higher tiers). **Why:** percent-only healing barely moved the needle on weak or low-damage weapons because the heal scaled off tiny hit values; adding flat healing keeps Life Steal meaningful on those weapons. The same **0.3.1** migration batch updates **MessagesLanguageMapping.json** (version bump + Life Steal template text) only when `passives.lifesteal.template` still equals the old default English line-custom or translated wording is not overwritten. New migration step option **`whenCurrentEquals`** documents this pattern in [Config migrations](config-migrations).
* **Admin `/lvl resetrewards <player>`** - Clears claimed level-reward flags for one player (online or offline) so they can reclaim from the Rewards GUI; does not remove items already received. **`/lvl resetrewardsall`** does the same for every player. Documented in [Commands](commands). Messages: `commands.resetrewards.*`, `commands.resetrewardsall.*`, and `/lvl info` lines `cmd_resetrewards` / `cmd_resetrewardsall`.
* **`EnablePassiveNotifications`** (`RPGLevelingConfig.json`) - When **`EnableNotification`** is `true`, set **`EnablePassiveNotifications`** to `false` to disable only class **passive** proc popups (heal, buff applied, passive damage line, Hunter's Mark proc, on-kill buffs such as Overkill). Level-up, XP, critical hit, entity killed, class tier-up subtitle, zone warnings, death penalty, and other non-passive notifications still follow **`EnableNotification`** only. Default: `true`. Documented in [Main Plugin Config](config-main).

### 🐛 Fixed

* **Level rewards & full inventory** - Claiming from the Stats GUI **Rewards** tab no longer marks a level as claimed when the configured **item** stacks cannot fully fit in the player’s **storage**. A red chat message tells the player to free space and try again (`gui.rewards.error_inventory_full` in messages). **Claim All** still claims every reward that fits; if any level is skipped for lack of space, the same message is shown once. Rewards with only reset points and/or commands (no items) are unchanged.

***

## \[0.3.0] - 2026-03-14

**Mod version:** 0.3.0 · **Game version:** Hytale 2026.02.19-1a311a592

<img src="https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi" />

<img src="https://img.shields.io/badge/Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" />

### ✨ Added

* **Entity override ExactIdMatch (include matching)** - Entity overrides in InstanceLevelConfig and ZoneLevelConfig support **ExactIdMatch** per entry (default **true**). When set to **false**, the override applies by "include": any NPC whose type ID contains the entry's EntityId gets that override (e.g. EntityId `"skeleton"` with ExactIdMatch false applies to all skeleton variants). Longest matching entry wins.
* **Admin command `/lvl setclasstier <player> <class> <tier>`** - Sets a player's tier for a specific class (0–4). Example: `/lvl setclasstier Zuxaw archery 4`. Works for online and offline players. Class name is case-insensitive (e.g. `archery`, `Archery`).
* **Movement Speed stat** - New allocatable stat that increases player movement speed by a configurable percentage. Config: `MovementSpeedStatValuePerPoint` (e.g. 0.5 = 0.5% per point), `MaxStatPointsMovementSpeed`. Icon: Tree Sap item.
* **Mana Regen stat** - New stat for mana regeneration; especially relevant for the Arcane class and magical weapons. Config: `ManaRegenSpeedValuePerPoint` (e.g. 0.18 = 18% per point), `MaxStatPointsManaRegenSpeed`. Icon: Staff Crystal Ice.

### 🐛 Fixed (for beta player)

* **ImpactBuff world crash** - Fixed `Entity contains component type: ImpactBuff` and `ComponentType is not in archetype: ImpactBuff` when Impact (or Hunter's Mark / Last Stand) procced multiple times in the same tick. The engine's `removeComponent` throws when the entity does not have the component in its archetype, so we now: (1) only call remove when the store already has the buff, and (2) deduplicate adds per player per tick via pending-add sets so at most one add is queued until the store is updated.
* **World crash on Hunter's Mark usage** - Fixed `IllegalArgumentException: Entity contains component type: HunterMarkBuff` when multiple Hunter's Mark (or Impact / Last Stand) buffs were applied in the same tick. Buff application now uses remove-then-add so duplicate components are never queued.
* **Class tier display in GUI** - Tier label now shows "Tier 4/4" at max instead of "Tier 4/5" (tiers are 0–4; the denominator was incorrectly 5).

### 🔄 Changed

* **LifeSteal (passive) - for beta players** - Config migration restores pre-beta heal-per-tier values for PassivesConfig (e.g. max 7% → 12%). If you played during beta and kept the toned-down values, upgrading to 0.3.0 will put LifeSteal back to the original stronger values unless you edit the config after migration.
* **Mana for magical weapons (Arcane)** - Thanks to Arcane class passives, mana is now used in Hytale for magical weapons and is really interesting if you play Arcane.
* **Monster HP per level (+30%)** - Monster life (HP) per level increased by 30% for all difficulty presets. EASY: 1.5% → 2%, NORMAL: 2.5% → 3.25%, HARD: 3.5% → 4.5%, EXTREME: 5% → 6.5%. Higher-level monsters are tankier; player damage is unchanged.
* **Stats application improved** - Stat bonuses are applied in a way that no longer negatively affects you; fixes and refinements so allocated stats only provide benefits.

### 🖥️ UI

* **Interface overhaul** - Almost the entire UI has been redone for a clearer, more consistent experience.

### ⚔️ Class system

* **Classes are templates** - Classes are just templates and are fully customizable. You can override or replace them to fit your server (e.g. a Jedi class with lightsaber boost for a Star Wars–style mod).
* **Class innate bonuses scale with your level** - Class bonuses are based on your global level, so they grow as you level up. No heavy penalty for switching class; your current level still applies.
* **Tier system (T0 → T4)** - The more you play a class, the more you tier it up; each tier unlocks stronger innate bonuses and new passives. Sticking with a class rewards you with better bonuses; you can still change class anytime.
* **6 classes (default set)** - Compatible with modded weapons: add weapons from other mods so they get class bonuses, or define a fully custom class (name, weapons, passives, stats) for any theme.
* **Goal** - Reward specialized playstyles and rebalance weapon diversity; passives add variety and fun. Epic animations when passives trigger may come later.

#### Classes (default set)

| Class       | Weapons                 | Passives                                   |
| ----------- | ----------------------- | ------------------------------------------ |
| **Heavy**   | Axe, Battleaxe          | HighGuard, ThickSkin, Overkill             |
| **Blunt**   | Mace, Club              | Impact, Stubborn, LastStand                |
| **Edge**    | Sword, Longsword, Spear | LifeSteal, DuelFocus, Unscathed, Riposte   |
| **Fang**    | Dagger, Shortbow        | LifeSteal, Backstab, Executioner           |
| **Archery** | Shortbow, Crossbow      | SteadyShot, Opening, HuntersMark           |
| **Arcane**  | Staff, Wand, Spellbook  | ArcaneTransfusion, FullReserve, ManaShield |

### 🎯 Passive system (18 custom passives)

* **Passives per class** - Each class has its own passives; they unlock by tier and trigger in combat (damage dealt, damage taken, on kill).
* **Add or swap passives** - You can add passives to any class or swap which passives a class has; fully configurable per class and tier.
* **Configurable** - Passive names, descriptions, and all values/percentages are configurable per passive and per tier.

#### Passives (all 18)

| Passive               | Effect                                                                              |
| --------------------- | ----------------------------------------------------------------------------------- |
| **HighGuard**         | +% damage when your HP is above a threshold.                                        |
| **ThickSkin**         | When hit and HP below threshold: chance to heal % of damage taken.                  |
| **Overkill**          | On kill: restore % max stamina and gain +% move speed for a short duration.         |
| **Impact**            | On hit: chance to add +% damage for a duration (refreshes on hit).                  |
| **Stubborn**          | When hit and HP below threshold: chance to heal % of damage taken.                  |
| **LastStand**         | First time below % HP: damage reduction + lifesteal for a duration, then cooldown.  |
| **DuelFocus**         | When only one target hit in the last X seconds: +% damage.                          |
| **Unscathed**         | Vs a target that has not damaged you in the last X seconds: +% damage.              |
| **Riposte**           | After block or taking damage: next attack within X seconds gains +% damage.         |
| **LifeSteal**         | % of damage dealt heals you.                                                        |
| **Backstab**          | Hitting from behind: +% damage.                                                     |
| **Executioner**       | When target HP is below %: +% damage (cooldown per target).                         |
| **SteadyShot**        | After not moving for X seconds: next projectile +% damage.                          |
| **Opening**           | Hitting an enemy above % HP: +% damage on that hit.                                 |
| **HuntersMark**       | Hitting the same target X times within X seconds: +% damage from you for X seconds. |
| **ArcaneTransfusion** | When you use stamina on a magical attack, % of max mana is converted to stamina.    |
| **FullReserve**       | When mana above %: +% spell damage.                                                 |
| **ManaShield**        | Use mana to absorb incoming damage: up to % absorbed, mana cost per damage.         |

### ⚙️ Custom config for classes

* **Full configurability** - Class names, descriptions, item icons, stat bonuses per class and tier, weapon lists, and passive lists. Disable an entire class or individual passives; tweak every value and percentage.
* **All names in MessagesLanguageMapping** - Every display name (classes, passives, stats, etc.) is configurable via `MessagesLanguageMapping` so you can localize or rename everything without touching class JSON.

***

## \[0.2.10] - 2026-02-24

**Mod version:** 0.2.10 · **Game version:** Hytale 2026.02.19-1a311a592

### ✨ Added

* **Config migration system** - Config files (RPGLevelingConfig, InstanceLevelConfig, ZoneLevelConfig, LevelRewardsConfig, MessagesLanguageMapping) are now automatically upgraded at startup when their version is older than the latest. A backup (`.bak`) is created before applying migrations.
* **Pet+ mod compatibility** - Pet follower entity roles (Pet\_Follower, Pet\_Follower\_Large, Pet\_Follower\_Large\_Combat) are in the default blacklist so they are excluded from leveling.

### 🐛 Fixed

* **DeathDetectionSystem WorldThread crash (stale entity reference)** - Fixed a crash that could disconnect all players on a world when an entity was removed from the ECS store while death processing was still using its reference (e.g. NPC despawning, player disconnect).

### 🔄 Changed

* **Zone HP thresholds (mob level)** - Updated HP floor/ceiling used for mob level calculation in zones 1–4 (Zone1: 1–168, Zone2: 8–191, Zone3: 17–146, Zone4: 1–271). Thanks to Taboret (Discord) for the values.

***

## \[0.2.9] - 2026-02-17

**Mod version:** 0.2.9 · **Game version:** Hytale 2026.02.17-255364b8e (Update 3)

### 🔄 Compatibility

* **Hytale Update 3** - The mod is now compatible with Hytale's Update 3. If you were waiting to update the game, you can safely do so with this version installed.

### 🐛 Fixed

* **Player join crash (PlayerReadyEvent)** - Fixed a crash that could happen when a player joins the server. The error showed as `Assert not in thread!` in the console. This could affect any server and happened randomly on player connect. Fixed in this version.
* **Profile picture packet error** - Fixed a compatibility issue when sending the player's profile picture to the client, which could cause an error in the console on join.

### 💬 Developer note

Starting with this release, the mod and game version will be specified at the top of each changelog entry so you always know which version of Hytale a given release was built and tested against.

***

## \[0.2.8] - 2026-02-12

### 🐛 Fixed

* **World freeze / world stopping** - Fixed an issue where the mod could freeze or stop the world, requiring the mod to be disabled to recover. The problem was caused by changes made to support the new pre-release from yesterday; the mod no longer supports pre-release and release at the same time - that compatibility layer was the root cause. The mod is now working correctly on **release**. **The mod is incompatible with pre-release for now.** Update to 0.2.8 if you were affected.

### 💬 Sorry for the hassle

Sorry about this. In any case, **your world data is never corrupted or erased** because of a bug like this - the mod does not modify or delete your world saves. If the world seemed stuck, disabling the mod was enough to recover; your data remains intact.

***

## \[0.2.7] - 2026-02-12

### ✨ Added

* **📜 `/lvl resetstatsall`** - Admin command to reset **only allocated stats** for **all players** (online and offline). Each player keeps their current level and XP; allocated stats are cleared and **available stat points** are set to **(level − 1) × StatPointsPerLevel** (from StatsLevelConfig). Use when you want everyone to reallocate stats without losing level progress. OP only. See [Commands](commands#lvl-resetstatsall).
* **📋 BlacklistedEntityRoles** - Config option to exclude NPC **roles** from leveling. NPCs whose role name **contains** a configured string (default: `Citizen_`) get **no level display**, **no HP/damage scaling**, and **no XP** when killed. Uses the NPCEntity component; ideal for Citizen mod NPCs. Matching is **include** (contains).

### 🔄 Changed

* **InstanceLevelConfig** - Removed the built-in `"default"` (1–25) entry. New configs include an example instance `Yungs_HyDungeons_Skeleton_Dungeon` (55–75); add or edit entries for your instance/dungeon worlds. See [Instance Level Config](config-instances).
* **Instance overrides zone (multiworld)** - When a world matches an entry in `InstanceLevelConfig`, that instance’s level range and entity overrides **override** `ZoneLevelConfig`. Main world can use zones; each dungeon/minigame world can have its own level range. See [Instance Level Config](config-instances).
* **ExactIdMatch per instance** - Each instance in `InstanceLevelConfig.json` can have **`ExactIdMatch`** (default: `true`). When `true`, world id must match config `Id` exactly; when `false`, match by **include** (game id contains config Id). See [Instance Level Config](config-instances).

### 💬 Developer note

Release delivery will slow down for a while - I'll be busy and may not be able to answer many messages. I'm currently working on **0.3.0** with a **class system**. Thank you for your patience and support.

***

## \[0.2.6] - 2026-02-09

### 🐛 Fixed

* **📜 Reward command permissions** - Level reward commands (e.g. `eco give 1000 {player}`) now run as the **server console** instead of the claiming player. This fixes "you don't have permission" errors when the player lacks permission for the reward command; the console has full privileges so rewards apply correctly.

### ✨ Added

* **⚙️ Critical Damage stat** - New stat **Critical Damage**: chance to deal a critical hit (damage × random 1.5–2.0). Default **0.2% per point** (e.g. 50 points at 0.2 = 10% chance). Config: `CriticalDamageStatValuePerPoint` (default 0.2), `MaxStatPointsCriticalDamage` (default 50). In the Stats GUI the stat appears next to Damage and uses the **Weapon\_Longsword\_Adamantite\_Saurian** icon. On critical hit the player receives a notification with the damage value.
* **⚙️ Per-stat value per point (StatsLevelConfig)** - Resource stats (Health, Stamina, Mana, Ammo, Oxygen) now have their own config keys: `HealthStatValuePerPoint`, `StaminaStatValuePerPoint`, `ManaStatValuePerPoint`, `AmmoStatValuePerPoint`, `OxygenStatValuePerPoint` (default 1.0 each). See [Stats Level Config](config-stats).

### 🔄 Changed

* **🖼️ Stats GUI rework** - The player's **head skin** is now displayed on both the **Stats** and **Rewards** pages (rendered via [Hyvatar](https://hyvatar.io/), Hytale avatar rendering API). The Stats page also shows **real values** and **number of points** per stat so you can see exactly how your allocations affect your stats and skills.
* **📈 StatPointsPerLevel default** - Default stat points per level up changed from **3** to **5** in `StatsLevelConfig.json` and code. New configs and fallbacks use 5. Existing configs keep their current value until you change it.
* **⚙️ Default Damage and Defense (StatsLevelConfig)** - Default values for `DamageStatValuePerPoint` and `DefenseStatValuePerPoint` are now **1.5** (was 1). Existing configs: set these keys to 1.5 manually to match new defaults.
* **⚙️ Stamina config keys renamed** - `StaminaConsumptionReductionPerPoint` → **`StaminaConsumptionValuePerPoint`** (default 0.01). `StaminaRegenSpeedMultiplierPerPoint` → **`StaminaRegenSpeedValuePerPoint`** (default 0.18). Rename in JSON or run `/lvl reload` after plugin migrates on load.

***

## \[0.2.5] - 2026-02-08

### 🐛 Fixed

* **SLF4J conflict with other mods** - Fixed the "multiple SLF4J bindings" warning when running alongside other mods (e.g. EcotaleMarket). No more red console messages about duplicate bindings.
* **📜 Reward commands (vanilla and other mods)** - fix for running **vanilla** and **other mods’** commands from level rewards.
* **🧩 `/lvl gui` collision with other mods** - When opening the Stats GUI (`/lvl gui`).

### 🔄 Changed

* **`/lvl reload`** - Now reloads **all** config files: RPGLevelingConfig, StatsLevelConfig, and DatabaseConfig are re-read from disk. DatabaseConfig is applied in-memory only; changing JDBC URL or enabling/disabling DB sync still requires a server restart.

***

## \[0.2.4] - 2026-02-07

### ✨ Added

* **🎁 Level Rewards** - New config **LevelRewardsConfig.json** and **Rewards** tab in the Stats GUI (`/lvl gui`). Define per-level rewards: **items** (by Hytale `ItemId` and `Quantity`, added to player storage when claimed), **reset points**, and an optional **command** run when the reward is claimed. Players claim rewards once per level; status shows **Unclaim** or **Claimed**. **Claim All** appears when there is at least one claimable reward and claims every unclaimed reward the player has reached the level for. See [Level Rewards Config](config-level-rewards). **⚠️ Note:** When a player uses **Claim All**, they can claim **every reward from level 1 up to their current level** in one go. It is **recommended to check** `mods/Zuxaw_RPGLeveling/LevelRewardsConfig.json` and ensure the default rewards are suitable for your server. You can **edit the JSON** to add rewards for specific levels, remove existing reward entries you don’t want, or change items and quantities - see [Level Rewards Config](config-level-rewards) for the full format. **📜 Reward commands** - Each reward can have **one** command: `Command` (the command string) and optional `CommandTitle` (label in the Rewards tab); both default to empty and every reward entry includes them in the config. Use the **`{player}`** placeholder in `Command`; it is replaced with the claiming player's username. The plugin runs **`lvl setlevel {player} <level>`** directly (no server CommandManager required): level applies immediately, leaderboard is updated, and the server stays responsive. Other commands are run via the game's CommandManager when available. See [Running a command when a reward is claimed](config-level-rewards#running-a-command-when-a-reward-is-claimed) in the Level Rewards Config docs.
* **🔄 Reset points system** - Players can earn **reset points** from level rewards (`LevelRewardsConfig.json`: `ResetPoints` per reward). Reset points are displayed on the Stats page (e.g. **x5** next to the RESET ALL button). The **RESET ALL** button (Stats GUI, bottom left) consumes **1 reset point** and refunds all allocated stat points; Health/Stamina etc. are clamped to base. Button is disabled when the player has 0 reset points. Data is persisted (store, holder, and external database if enabled).
* **📜 `/lvl setreset <player> <amount>`** - Admin command to set a player's reset points (e.g. `/lvl setreset PlayerName 5`). Works for **online and offline** players. OP only.
* **🔄 `/lvl reload`** - Admin command to reload config files from disk without restarting the server. Reloads **ZoneLevelConfig.json**, **InstanceLevelConfig.json**, **LevelRewardsConfig.json**, **MessagesLanguageMapping.json**, **RPGLevelingConfig.json**, **StatsLevelConfig.json**, and **DatabaseConfig.json** (DatabaseConfig: in-memory only; DB connection changes require restart). OP only.
* **🌍 Disable plugin per world/instance** - In **InstanceLevelConfig.json**, each instance can have **`DisableRPGLeveling`** (default: `false`). When `true`, the plugin has no effect in that world: no HUD, no level scaling, no XP, no stat modifiers (damage/defense/mining/stamina), no death reset. Use for minigame worlds or dungeons where you want vanilla gameplay. See [How to disable the mod for a specific world/instance](disable-per-world).

### 🔄 Changed

* **⚙️ Nameplate options** - **`EnableNameplateLevelDisplay`** (default: `true`): when `true`, nameplates can show level; when `false`, **no** nameplate is modified (players or monsters). **`EnablePlayerLevelNameplate`** (default: `true`): when `false`, only **player** nameplates are left unchanged (monster level still shows when you look at them). Both options are in `RPGLevelingConfig.json` and are written on config save.
* **📜 `/lvl setlevel`** - When setting a player's level, **claimed rewards** for levels above the new level are removed (so the player can reclaim those rewards when they reach the level again). Available stat points are set to `(level - 1) × StatPointsPerLevel` (correct total for the new level). Applies to both online and offline targets.
* **📜 `/lvl resetall`** - Now also clears **claimed reward levels** and sets **reset points to 0** for every affected player (online and offline). Level and stats reset unchanged (level 1, 0 XP, 0 stat points, no allocations).

### 🐛 Fixed

* **⛏️ Mining XP on cracked ore** - Fixed: mining cracked ore (e.g. cracked ore variants) no longer grants XP. You will earn no more XP when mining cracked ore; only full ore/mineral/gem blocks award mining XP.
* **👁️ Nameplate level display** - Console warnings when entities or players disappear while the level nameplate is being updated (e.g. player disconnects or target despawns).
* **🗄️ Database connection / plugin startup** - Fixed error on start when using external database sync (SLF4J).
* **🗄️ Database sync** - External database now stays in sync with player data: sync runs on mod start and again after 10 seconds (so `universe/players` is available if the server loads it later). Offline admin commands (`/lvl setlevel`, `/lvl setpoints`, `/lvl setreset`) now push the updated player from disk to the DB. `/lvl resetall` triggers a full sync from disk so offline resets are reflected in the database.

### 💬 Developer note

Do not hesitate to reach out on my [Discord server](https://discord.gg/nGDQbjMtxY) - especially if you have better ideas for **default reward items** in `LevelRewardsConfig.json`. The current defaults are placeholders; suggestions for more fitting or balanced items per level are welcome.

***

## \[0.2.3] - 2026-02-03

### ✨ Added

* **⛏️ XP for mining and woodcutting** - Earn XP when breaking ore/mineral blocks (mining) and log/tree/trunk blocks (woodcutting). XP scales with **player level** (configurable `BlockXPPlayerLevelFactor`) and **zone level** (per-zone `BlockXPZoneLevelFactor` in `ZoneLevelConfig.json`). Higher-level players and higher-level zones award more XP per block. Config: `EnableBlockXP`, `BlockXPBaseMining`, `BlockXPBaseWood`, `BlockXPPlayerLevelFactor` in `RPGLevelingConfig.json`. API: `XPSource.BLOCK_BREAK`, `BlockBreakContext`, `addXP(..., sourceContext)`.
* **🌍 ZoneRateExp (per-zone XP multiplier)** - In `ZoneLevelConfig.json`, each zone can have `ZoneRateExp` (default 1.0). All XP gained in that zone - **mob kills** and **block break** - is multiplied by this value. Use **2.0** to double XP in the zone, **0.5** to halve it. See [Config Zones](config-zones) and [Formulas](formulas).

***

## \[0.2.2] - 2026-02-02

### ✨ Added

* **⚙️ `EnableNotification`** - Main config option in `RPGLevelingConfig.json`. When `true` (default), all notifications are sent (XP gain, level up, stat points, death penalty, zone warnings, entity killed). When `false`, no notifications are sent.
* **⚙️ `EnableCurrentZoneHudDisplay`** - Main config option in `RPGLevelingConfig.json`. When `true` (default), HUD shows level and current zone/biome. When `false`, HUD shows only level and XP progress bar.

### 🔄 Changed

* **👁️ NPC nameplate level display** - Level is no longer shown in the nameplate for NPCs that survival players can interact with (trade, dialogue, etc.).

### 🐛 Fixed

* **💥 Server crash on XP gain** - Fixed `OutOfMemoryError: Requested array size exceeds VM limit` when sending XP gain notification. Occurs when `xpNeeded` for next level is 0 or invalid (e.g. misconfigured `LevelBaseXP`/`LevelOffset`). Added guard to avoid division by zero and clamp progress bar length to prevent runaway StringBuilder growth.
* **💥 World crash (invalid entity Ref)** - Fixed world crash when resolving player level data with an invalid entity Ref (e.g. after chunk unload or entity despawn).
* **🔄 `/lvl resetall`** - Now correctly resets **available stat points to 0** (and clears allocated stats). Previously, `/lvl resetall` and `/lvl setlevel 1` would incorrectly add allocated points back to available, leaving players with unspent points after a full reset.

***

## \[0.2.1] - 2026-02-01

### 🐛 Fixed

* **📋 Leaderboard "Unknown Player"** - Other players in the leaderboard no longer show as "Unknown Player". Username now read from `DisplayName.RawText` (Hytale's authoritative name) in player JSON files, with fallback to `Nameplate.Text` when needed.

### ✨ Added

* **⚙️ `EnablePlayerLevelNameplate`** - Main config option in `RPGLevelingConfig.json`. When `true` (default), player nameplates show level (e.g. "Username \[Lvl. X]"). When `false`, player nameplates are not modified and show the default name only.
* **🗄️ External database sync** - Sync player data (level, XP, stats) to an external database. Configure via `DatabaseConfig.json` in `mods/Zuxaw_RPGLeveling/`. Supports H2, MySQL, MariaDB, PostgreSQL via JDBC. Data flows **from the game to the DB only** - Hytale storage remains the source of truth. See [Database Sync](database-sync).
* **📋 Leaderboard top 3 player name colors** - Top 3 players now have colored names in the GUI leaderboard: gold (1st), silver (2nd), bronze (3rd). Current player stays highlighted in blue when viewing.

### 🔄 Changed

* **⚔️ Difficulty balance** - Monster→player damage per level reduced for all presets: Easy 0.5%, Normal 1%, Hard 2%, Extreme 4%.

***

## \[0.2.0] - 2026-01-31

**Summary:** 0.2.0 is a major update. Everything that changed between 0.1.10 and 0.2.0 is listed below. If you are upgrading from 0.1.10, you must **manually migrate** config from `mods/RPGLeveling/` to `mods/Zuxaw_RPGLeveling/` - see [Configuration](configuration).

### ✨ Added

* **📌 Instance Level Config (`InstanceLevelConfig.json`)** - Config file in `mods/Zuxaw_RPGLeveling/` for **instances and dungeons** (where zone/biome are unknown). Define level ranges and per-entity overrides per instance. See [Configuration](configuration) → Instance Level Config.
* **🎮 Monster-level XP** - XP from mob kills based on **monster level** (not max health). Higher-level monsters give more base XP.
* **📊 Level-difference multipliers** - How close the monster's level is to yours affects XP. Same-level or ±5 = best; much easier or much harder = reduced XP.
* **🌍 Zones** - 6 zones (Emerald Grove, Howling Sands, Borea, Devastated Lands, Skylands, Poisonlands) with different monster level ranges.
* **👁️ HUD zone display** - HUD shows current zone name and **color**: green = good match (±25 levels), white = too easy (−26+), orange/red/purple = too hard (+26+).
* **🎲 Monster level variation** - ±5 levels per monster in a zone for variety.
* **⚔️ Difficulty scaling** - Monster damage and HP scale with level. Level-gap penalties when underleveled. See [Difficulty Scaling](difficulty-scaling).
* **🎚️ Difficulty presets** - Easy, Normal, Hard, Extreme via `difficultyPreset` in `RPGLevelingConfig.json`.
* **⚙️ `EnableGapLevelXpReducer`** - When `true` (default), XP is reduced when you are underleveled. When `false`, full XP from higher-level monsters.
* **⚙️ `EnableGapLevelDefense`** - When `true` (default), level-gap defense applies. When `false`, gap defense disabled. See [Difficulty Scaling](difficulty-scaling).
* **⚙️ `EnableGapLevelDamageToPlayer`** - When `true` (default), level-gap damage applies. When `false`, no bonus damage from gap. See [Difficulty Scaling](difficulty-scaling).
* **⚙️ `EnableMonsterLevelScale`** - Master toggle. When `true` (default), damage/HP per level, gap damage/defense, level-based XP. When `false`, XP falls back to HP-based; level display still works.
* **📌 `ZoneLevelConfig` entity overrides** - `EntityOverrides` in `ZoneLevelConfig.json`: force specific NPC type IDs to a fixed level, optional `DisableLevelScaling`, or **precise XP** per entity. See [Configuration](configuration).
* **🔌 Public API for mod developers** - Add XP, listen for level ups, get player level. See [API](api).
* **👤 Offline player support for admin commands** - `/lvl setlevel`, `/lvl setpoints`, `/lvl resetstats` work for **offline players**. Success shows *(offline)*. `/lvl resetall` already supported both.
* **🔄 `/lvl resetall`** - Reset level and stats for **all players** (online and offline). OP only.
* **👁️ Entity info display (player nameplates)** - When you look at another player, nameplate shows **"Username \[Lvl. X]"**.
* **📋 `BlacklistedEntities`** - Comma-separated entity type IDs. Blacklisted entities give **no XP** and **no level display**.
* **⚔️ `EnablePVPXp`** - When `true`, killing a player awards XP; when `false` (default), no XP from PvP.
* **⚙️ Config Management** - Configs in `mods/Zuxaw_RPGLeveling/`. Improved handling, backups on modify.

### 🔄 Changed

* **📁 Configuration file structure** - Now **5 files** in `mods/Zuxaw_RPGLeveling/`: `RPGLevelingConfig.json`, `StatsLevelConfig.json`, `MessagesLanguageMapping.json`, `ZoneLevelConfig.json`, `InstanceLevelConfig.json`. Stat-related settings moved to `StatsLevelConfig.json`. Messages file renamed from `messages.json`.
* **🔌 API: `getPlayerLevelInfo(playerRef, store)` - store now required** - The overload without store was removed. Use `getPlayerLevelInfo(playerRef, store)` from the world thread. UUID overload unchanged.
* **📊 Underleveled XP penalties** - Reduced. Now 50% (26–30 levels higher), 60% (31–40), 70% (41–50), 80% (51+). Disable via `EnableGapLevelXpReducer: false`.
* **⚔️ Gap defense (player → monster)** - Reworked tiers. See [Difficulty Scaling](difficulty-scaling).
* **🔋 HP-based toughness** - Monsters scale health with level. Higher-level mobs have more HP.
* **🌍 Early zone ranges** - Default zone levels adjusted: **Emerald Grove** 1–15 (was 1–25), **Howling Sands** 15–50 (was 25–50).
* **⚠️ Manual migration** - When updating from 0.1.9/0.1.10, **manually migrate** config from `mods/RPGLeveling/` to `mods/Zuxaw_RPGLeveling/`. Plugin generates new defaults on first run.

### 🐛 Fixed

* **📌 Config version in RPGLevelingConfig and StatsLevelConfig** - `Version` now always written on save so config files stay in sync with the plugin.
* **🌍 Monster level when crossing zones** - Monster level is locked when it first appears; no drop when luring into a lower zone.
* **👁️ Monster nameplate** - Works on pre-release without white screen/crash; shown only when looking at a monster for performance.
* **👁️ Monster nameplate not showing** - Level is now shown using **Nameplate** component only; custom nameplates from other mods are not overwritten.
* **👁️ Monster nameplate level jump on death** - Spawn-level cache cleared when entity is removed, so level stays correct on corpse until despawn.
* **📊 HUD and GUI XP bar sync** - LevelingService persists `PlayerLevelData` to store after XP/level-up so HUD and GUI stay in sync.
* **👥 Nameplate collision with NPC/Pet mods** - Level display detects existing nameplates and does not replace them.
* **📊 Level progression in `/lvl gui`** - Progress bar and % now use same data source as HUD (API with store).
* **⚔️ XP rewards and level gap** - Player level correctly read from entity store; XP and gap penalties use actual level.
* **🎯 Monster level caching** - Monster levels cached on spawn in `MobLevelData` for consistent XP and display.
* **💰 Trivial XP penalty** - Removed harsh 90% penalty for monsters 25+ levels below; low-level mobs now give full base XP (1.0x).
* **👁️ Player level on nameplate** - Level read from Store; "Username \[Lvl. X]" always shown for online players.
* **📋 Leaderboard player names** - Username stripped from nameplate overlay so leaderboard shows real usernames.
* **👁️ Player level above head** - Level read from entity Store instead of Holder.
* **📋 `BlacklistedStats`** - Now respected in all systems. Blacklisted = hidden in GUI, no allocation, no effect.
* **⛏️ Mining crash** - Fixed critical crash during mining.
* **🌍 Zone config biome remap** - `MissingZoneIds` replaced with `MissingBiomeIds` in `ZoneLevelConfig.json`; biome→zone remapping reliable, no world crash.
* **💀 `ResetLevelOnDeath`** - Now correctly detects deaths and resets level, XP, and stat allocations when enabled.

### 💙 Thank you

A huge thank you to everyone who supported the mod on [Ko-fi](https://ko-fi.com/zuxaw) - **Benzitczo**, **Epickeks**, **aic** - it's really encouraging and means a lot.

Thanks too to everyone who has downloaded the mod, tested the beta, shared feedback, and helped others on [Discord](https://discord.gg/nGDQbjMtxY). You're all part of this adventure, and that's what gives me the strength to keep going.

***

## \[0.1.10] - 2026-01-26

### 🐛 Fixed

* **⛏️ Mining crash fix** - Fixed a critical issue that could cause random crashes during mining sessions.

### ✨ New

* **🤝 PartyPro Compatibility** - [PartyPro](https://www.curseforge.com/hytale/mods/partypro) - RPG Leveling Integration is now 100% compatible with RPG Leveling thanks to the excellent work of Tsumori, its developer. PartyPro allows you to share XP within a party/group, making cooperative gameplay even more rewarding!

### 💬 Developer Note

**🚀 0.2.0 Beta is here!** I've been working hard on a massive rework of the mod, and the beta is now available for testing. Version 0.2.0-beta-5 introduces zones, monster-level XP, difficulty scaling, and much more. Your feedback during this beta phase is crucial to help me polish everything before the stable release. Check out the full changelog below for all the exciting new features!

***

## \[0.1.9] - 2026-01-24

### 📖 Documentation

* **Full documentation live** - We now have [docs](https://docs.rpg-leveling.zuxaw.com/) to help with config issues and give you maximum detail on the mod. Before asking a question (in comments or on Discord): please read the docs first. 90% of the time the answer is already there. I'm alone answering everyone, and it's tough when people don't take the time to read the basics - so check the docs, it'll save us both time. 💙

### 🐛 Fixed

* **🧩 `/lvl gui` crash** - Fixed the `/lvl gui` command crash caused by Hytale's latest update. This should also fix the `/lvl gui` crash for some of you who had it even before the Hytale update.

### 🔜 What's next

* **v0.2.0-beta-5** - Beta available. Underleveled XP reducer, API store required, config version fix, monster level lock, nameplate fix. Switch to 0.2.0-beta-5 in the version selector for beta docs.

***

## \[0.1.8] - 2026-01-21

### 🐛 Fixed

* **🧩 HUD/GUI compatibility** - Opening `/lvl gui` no longer hides then re-shows the Level HUD. Toggling the HUD caused full HUD re-renders (including other HUD mods) and could crash/disconnect some users.

### ⚡ Performance

* **🐲 Monster kills / combat** - Reduced lag when mobs die by simplifying the kill-handling flow and removing heavy/spammy debug output during fights.
* **🏆 Leaderboard** - Opening the leaderboard is much smoother thanks to caching + background refresh; also updates instantly after admin `/lvl setlevel`.
* **🪓 Mining & woodcutting** - Improved block-hit performance by avoiding repeated expensive lookups on every hit.
* **🧩 HUD** - Reduced unnecessary HUD work with smart updating + throttling to keep things stable on busy servers.
* **📝 Logging** - Removed non-essential / laggy logs and enforced using `DebugLogger` everywhere.

***

## \[0.1.7] - 2026-01-20

### 🔄 Changed

* **🎯 Complete HUD Management Rework** - Completely redesigned HUD system architecture for maximum compatibility.
* **⚔️ Damage stat balance (low-damage weapons)** - Rebalanced Damage stat scaling to be fairer for low base-damage weapons (e.g. daggers) while keeping high-damage weapons in check (hybrid scaling instead of pure % scaling).

### ✨ Added

* **🧭 Wayfinder Compatibility** - Full compatibility with Wayfinder mod by Alexr03.
  * **⚠️ Important:** Wayfinder and EyeSpy are NOT compatible with each other.

### ⚠️ Other

* **⚠️ Performance Warning** - EyeSpy can cause performance issues on servers with multiple HUD mods installed. EyeSpy forces all HUD mods/plugins to re-render, which can lead to significant lag on busy servers. They are working on it.

### ⚡ Performance

* **🖥️ Server-side performance improvements** - Massive optimizations to reduce lag spikes during combat and on busy servers.
* **🚀 HUD Performance Improvements** - Massive performance optimizations for HUD system (credit to Alexr03, creator of Wayfinder).

### 💡 Developer Notes

* Thanks to **Alexr03** (creator of Wayfinder) for the inspiration and insights that led to the HUD performance improvements.

***

## \[0.1.6] - 2026-01-20

### 🔄 Changed

* **📊 BaseXP default** - Changed default from 10.0 to **3** for more balanced XP gain from mob kills.
* **⚔️ Damage stat** - Replaced flat damage bonus with a multiplicative formula to be less cheated.
* **🛡️ Defense stat** - Replaced flat reduction with percentage-based, diminishing returns (e.g. 50 pts, 1.0 → \~40% reduction; always at least 20% of damage gets through).
* **📈 StatPointsPerLevel default** - Changed default from **5** to **3** stat points per level up.

### 🐛 Fixed

* **🏆 Leaderboard** - Leaderboard was showing and sorting by XP on the current level only (e.g. 200/450). It now shows and sorts by **total XP earned since the beginning** (cumulative).
* **📜 AddXP command** - `/lvl addxp <player> <xp>` was crashing with `Assert not in thread!`.

### ✨ Added

* **💀 Death Penalty System** - New configurable feature that resets player level to 1 upon death.
  * **Disabled by default** - Set `ResetLevelOnDeath: true` in config to enable.
  * When enabled, players who die will: level reset to 1, lose all XP, have all stat allocations cleared, available stat points reset to 0.
  * Prominent death notification shown when reset occurs.
  * **Configuration:** `"ResetLevelOnDeath": false` is added automatically to `RPGLevelingConfig.json` on next plugin load.

### 💬 How to Enable Death Penalty

1. Open `mods/RPGLeveling/RPGLevelingConfig.json`
2. Find `"ResetLevelOnDeath"` (added automatically if missing)
3. Change `false` to `true`
4. Restart the server or reload the plugin

***

## \[0.1.5] - 2026-01-19

### ✨ Added

* **🌍 Translation Support** - The plugin now supports multiple languages! Server messages, notifications, and GUI elements can be translated.
  * Fully customizable via `messages.json` at `mods/RPGLeveling/messages.json`
  * Easy to create and share community translations
  * English included by default
  * Translation file is automatically generated on first server start
  * See [Translation](translation) for the full guide

### 💬 Community Note

Don't worry if you're one of those people who break into a cold sweat at the mere thought of speaking English - now you can panic in your native language instead! 😅

***

## \[0.1.4] - 2026-01-19

### ✨ Added

* **🏆 Leaderboard System** - New leaderboard page in the GUI showing all players (including offline) ranked by level and XP.
  * Top 100 players with rank, username, level, and XP
  * Highlights your own position
  * Special colors for top 3 (Gold, Silver, Bronze)
* **🎨 Navigation System** - Completely redesigned GUI with modern sidebar navigation.
  * Sidebar with "Stats Management" and "Leaderboard" tabs
  * Active tab highlighting, smooth tab switching
* **🐛 Debug Configuration** - New `Debug` config option.
  * `Debug: false` (default) - clean console, no GUI/leaderboard spam
  * `Debug: true` - detailed debug logging for troubleshooting
  * Automatically added to existing config on server restart

### 🐛 Fixed

* **📝 Console Spam** - Fixed excessive logging from GUI and leaderboard. All debug logs now respect the `Debug` config.
* **👁️ HUD Visibility** - Level progress HUD no longer stays visible when opening Stats GUI; HUD hides/shows correctly with improved state management.

***

## \[0.1.3] - 2026-01-18

### 🐛 Fixed

* **🛡️ Defense stat** - Defense could reduce damage to 0 at high points. Now caps at 80% reduction; at least 20% of damage always gets through.
* **⚔️ Damage stat** - `DamageStatValuePerPoint` and `DefenseStatValuePerPoint` now load correctly from config at startup (workaround for Hytale Config). Default for both: **1**.

### 🔄 Changed

* **📋 BlacklistedStats default** - No stats blacklisted by default. Default is `""` instead of `"StaminaRegenDelay"`.
* **🛡️ DefenseStatValuePerPoint default** - Raised from 0.5 to **1**.
* **⚙️ Default config** - Full default `RPGLevelingConfig.json` documented in MODINFO (Configuration section).

***

## \[0.1.2] - 2026-01-17

### 🐛 Fixed

* **⚙️ MaxStatPoints Params** - Max stat point configuration now works correctly. All limits are properly applied and enforced.
* **🔫 Ammo Stat** - Fixed ammo stat functionality; players can properly allocate points to increase ammo capacity.

### 🔄 Changed

* **⚡ Stamina System Rework** - Replaced `StaminaRegenDelay` with two stats:
  * **StaminaRegenSpeed** - How fast stamina regenerates
  * **StaminaConsumption** - How much stamina is consumed during activities
* **🌍 Exploration Balance** - New stamina stats make exploration more engaging and balanced.
* **📝 BlacklistedStats Configuration** - Fully modifiable in config; admins can customize which stats are hidden.
* **⚙️ Default Configuration Values** - Updated: `MaxStatPointsAmmo` 50→4, new `MaxStatPointsStaminaRegenSpeed` 50, `MaxStatPointsStaminaConsumption` 50, `BlacklistedStats` → "StaminaRegenDelay" only.

### 🗑️ Removed

* **✨ MagicCharges Stat** - Removed for now due to bugs. May return in a future update.

***

## \[0.1.1] - 2026-01-17

### 🐛 Fixed

* **🪵 Woodcutting/Mining Stat Separation** - Woodcutting no longer affected mining blocks and vice versa. Mining and woodcutting are now properly separated.
* **⚖️ Damage Calculation Formula** - Reworked from flat addition to percentage-based multiplier: `damage = baseDamage * (1.0 + statLevel * statValuePerPoint / 25)`.
* **📊 Stat Scaling Balance** - Adjusted so blocks don't break too easily at low levels; level 50 with 50 woodcutting can break trees in 1–2 hits.
* **🔢 Zero Stats Handling** - Zero points in a stat has no negative effect; base performance without penalties.

### 🔄 Changed

* **📐 Mining/Woodcutting Calculation** - Switched to percentage-based multipliers instead of flat damage addition.

***

## \[0.1.0] - 2026-01-17

### ✨ Added

* **⚔️ Damage Skill** - Increases damage dealt to NPCs.
* **🛡️ Defense Skill** - Reduces damage taken from NPCs/entities.
* **🪨 Mining Skill** - Increases damage to stone and ore blocks; mine faster.
* **🪵 Woodcutting Skill** - Increases damage to wood blocks; chop trees faster.
* **⚙️ Maximum Stat Points Configuration** - Per-stat limits (MaxStatPointsHealth, Stamina, Mana, Ammo, Oxygen, StaminaRegenDelay, MagicCharges, Immunity, Damage, Mining, Woodcutting, Defense). Default: 50 per stat.
* **🚫 BlacklistedStats Configuration** - `BlacklistedStats` option (comma-separated) to blacklist specific stats. Default: Ammo, Immunity, MagicCharges, StaminaRegenDelay.

### 🔄 Changed

* **⚡ HUD Performance Optimization** - LevelProgress HUD reworked to use Hytale's native CustomUIHud; better performance and stability.
* **🎨 UI Assets Rework** - All UI assets updated for improved visuals and consistency.

### 🐛 Fixed

* **📝 Log Error Fix** - Fixed spam log errors on server start when players didn't have levelup data yet; proper initialization for new players.

***

## \[0.0.3] - 2026-01-16

### 🐛 Fixed

* **🚨 Critical HUD crash fix** - Fixed critical HUD crashes with incremental updates, removed immediate updates, added proper change detection.

### ✨ Added

* **👁️ EnableHUD configuration option** - Admins can disable the HUD display if desired.

### 🔄 Changed

* **⚡ Optimized HUD updates** - HUD updates only when data actually changes; fewer unnecessary updates, better performance.

***

## \[0.0.2] - 2026-01-16

### 🔄 Changed

* **🎨 HUD Reorganization** - Level progress bar moved to center of screen, just above life and stamina bars for better visibility.
* **⌨️ Command Prefix Rebranding** - Rebranded from `rpglvl` to `lvl` for a shorter, cleaner command.

### 🐛 Fixed

* **🟫 Dirt Block Recipe Bug** - Removed unintended dirt block crafting recipe (10 dirt → 1 dirt in pocket crafting).
* **🧩 CustomUI HUD Crashes** - Fixed "CustomUI HUD" crashes during gameplay.
* **📊 XP Progress Display Bug** - Fixed HUD stuck at 0% XP progress; now shows actual XP percentage.

### 📌 Notes

* **🧩 MultipleHUD Requirement** - When using other HUD mods, install [MultipleHUD](https://www.curseforge.com/hytale/mods/multiplehud); otherwise the level progress HUD won't be visible.

***

## \[0.0.1] - Initial Release

### ✨ Added

* **🎉 Initial release of the RPG Leveling plugin**
* **📈 Basic leveling system**
* **👁️ HUD display for level and XP progress**
* **⚙️ Configuration system**