> ## 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.

# Overview

> Everything the RPG Leveling plugin adds - XP, zones, difficulty scaling, stats, classes, passives (0.3.9), HUD, GUI, leaderboards, instances, API.

# Overview

**Turn Hytale into a real RPG.** RPG Leveling adds experience, levels, zones, difficulty scaling, and stat-based progression so every fight and every zone feels meaningful. **0.3.9 - The Harvest Moon Update** targets **Hytale 0.5.5**: **crop harvest XP**, new **Harvest** stat (double/triple yield), **tame XP**, and optional **Alec's Tamework** companion XP bridge. **0.3.8** added **`BlacklistedXPBlocks`**, faster level progress HUD for **100+ players**, nameplate console spam fixed, and leaderboard name fixes. **0.3.7** added external database sync and **`LevelCostMultiplier`**; **0.3.6** added per-range XP-earned multipliers and native **`HudManager`** HUD; **0.3.5** added per-player language; **0.3.3** added modder APIs, chat tokens, **`/lvl xprateboost`**, class cooldown, and HUD/stability fixes. A **class system** (from **0.3.1** onward) adds 6 classes, 18 passives, and full customization. One mod, full RPG feel.

***

## Everything you can do

### Classes & passives (0.3.6)

* **6 classes** - Heavy, Blunt, Edge, Fang, Archery, Arcane. Each has its own weapons, innate stat bonuses per tier, and passives that trigger in combat (damage dealt, damage taken, on kill).
* **18 passives** - HighGuard, ThickSkin, Overkill, LastStand, LifeSteal, Backstab, Riposte, ManaShield, and more. Unlock by tier (T0→T4); values scale with your class tier.
* **Tier system** - Play a class to tier it up; each tier unlocks stronger innate bonuses and new passives. Bonuses scale with your **player level**.
* **Fully customizable** - Classes are templates: override names, weapons, passives, and tier bonuses in JSON; add modded weapons (e.g. lightsabers); rename everything in [MessagesLanguageMapping](config-messages). See [Classes configuration](classes-config), [Passives configuration](passives-config), and [Custom class guide](guide-custom-class).

### Leveling & XP

* **Monster-level XP** - XP from mob kills is based on **monster level** (not max health). Higher-level monsters give more base XP.
* **Crop harvest XP (0.3.9)** - Harvest mature crops for XP. Tier multipliers, cooldown, and per-seed overrides in [HarvestingConfig.json](config-harvesting). Stack the **Harvest** stat for bonus yields.
* **Tame XP (0.3.9)** - Taming creatures awards XP (same kill formula, configurable in [RPGLevelingConfig.json](config-main#tame-xp)).
* **Level-difference multipliers** - Monsters near your level = best XP; much easier or much harder = heavy penalties so the best strategy is content that matches you.
* **6 Zones** - Emerald Grove, Howling Sands, Borea, Devastated Lands, Skylands, Poisonlands with different level ranges (default: Emerald Grove 1–15, Howling Sands 15–50, then higher zones).
* **HUD zone display** - Zone name + **color**: **green** = good match (±25 levels), **white** = too easy (−26+), **orange/red/purple** = too hard (+26+). You always know if you're in the right place.
* **Monster level variation** - ±5 levels per monster in a zone for variety.

### Difficulty & combat

* **Difficulty scaling** - Monster **damage** and **HP** scale with level. When you're underleveled, **level-gap penalties** apply: monsters hit harder, you deal less. Gap defense uses EASY/NORMAL/HARD/EXTREME caps. See [Difficulty Scaling](difficulty-scaling).
* **Difficulty presets** - **Easy**, **Normal**, **Hard**, **Extreme**. One setting in `mods/Zuxaw_RPGLeveling/RPGLevelingConfig.json` shapes how punishing gaps are and how tough high-level mobs feel. Balanced progression out of the box.
* **Config toggles** - `EnableGapLevelDefense`, `EnableGapLevelDamageToPlayer`, `EnableMonsterLevelScale`, `EnableGapLevelXpReducer` to turn gap scaling or all monster scaling off. Full control without editing formulas.

### Content & config

* **ZoneLevelConfig entity overrides** - Pin bosses or NPCs to a fixed level (e.g. 150), set **exact XP per kill**, or disable scaling per entity. See [Override entity xp and level](override-for-mod).
* **Instance Level Config** - Works with **dungeon mods** (e.g. [Yung's HyDungeons](https://www.curseforge.com/hytale/mods/yungs-hydungeons)). Set level ranges per instance/dungeon so mobs and XP fit your server. See [Instance & Dungeon mod setup](dungeon-mod-setup).
* **Config files** - Main configs in `mods/Zuxaw_RPGLeveling/`: RPGLevelingConfig, StatsLevelConfig, ZoneLevelConfig, InstanceLevelConfig, LevelRewardsConfig, XPCurveOverridesConfig, **HarvestingConfig** (0.3.9), MessagesLanguageMapping. Class and passive configs in `mods/Zuxaw_RPGLeveling/Classes/` (Class\*.json, PassivesConfig.json, ClassesGlobalConfig.json). See [Configuration](config-overview), [Classes config](classes-config), [Passives config](passives-config).

### Social & admin

* **Nameplate level display** - See **"Username \[Lvl. X]"** on players and **"Lvl. X"** on monsters when you look at them. Disable with `EnableNameplateLevelDisplay: false` in the main config (see [Main Plugin Config](config-main)).
* **PvP XP toggle** - `EnablePVPXp` to enable or disable XP from player kills.
* **Entity blacklist** - `BlacklistedEntities` (no XP, no level display) and `BlacklistedStats` (hidden in GUI, no allocation, no effect in-game). Fully disable stats or mob types you don't want.
* **Block XP blacklist** - `BlacklistedXPBlocks` in [Main Plugin Config](config-main#block-xp-blacklist) excludes block type IDs from mining/woodcutting XP (case-insensitive; default includes Animal Husbandry feed troughs).
* **Offline admin commands** - `/lvl setlevel`, `/lvl setpoints`, `/lvl setreset`, `/lvl resetstats` work for **offline players** (by name; data in `universe/players/`). **`/lvl resetrewards`** / **`/lvl resetrewardsall`** clear only **claimed level reward** flags so players can reclaim (items already received stay in inventory). **`/lvl resetall`** resets all (online + offline). See [Commands](commands).
* **Reset points** - Players can earn reset points from level rewards; the **RESET ALL** button in the Stats GUI refunds all allocated stat points, clears claimed rewards, and sets reset points to 0 (requires at least one reset point). Admins can set reset points with `/lvl setreset <player> <amount>`.

### Modders & compatibility

* **Public API** - Other mods can add XP (e.g. quest rewards), listen for level-ups, get player level. **0.3.9** adds **`XPSource.HARVEST`** / **`HarvestContext`** and **`XPSource.TAME`** / **`TameContext`** on **`ExperienceGainedEvent`**. See [API](api).
* **Alec's Tamework (optional, 0.3.9)** - With [Alec's Tamework!](https://www.curseforge.com/hytale/mods/alecs-tamework) installed, companion feed / harvest / breeding XP mirrors 1:1 to the owner's RPG level (combat companion XP is not credited). No extra config.
* **PartyPro** - [PartyPro](https://www.curseforge.com/hytale/mods/partypro) shares XP in a party (configurable multipliers, max distance). See [Share XP with teammates](party-xp-share).
* **Translation** - Full localization via `MessagesLanguageMapping.json`. Class and passive names are configurable there too. See [Translation](translation).

***

## All stats you can upgrade

You earn **stat points** every level up and spend them in `/lvl gui`. Each stat has a real effect in-game. You can specialize in combat, farming, or survival - or spread points for a hybrid build. **Classes** (0.3.6) add more identity via innate bonuses and passives.

### Combat stats

| Stat        | What it does                                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| **Damage**  | Increases damage dealt to NPCs. Multiplicative scaling (configurable). Stronger hits, faster kills.                  |
| **Defense** | Reduces damage taken from NPCs. Percentage-based, diminishing returns; max 80% reduction. Tank more, survive longer. |

### Farming & gathering stats

| Stat            | What it does                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| **Mining**      | Increases damage to **stone and ore blocks**. Mine faster; more points = fewer hits per block.                |
| **Woodcutting** | Increases damage to **wood blocks**. Chop trees and wood faster.                                              |
| **Harvest**     | Chance to **double or triple** crop yield when harvesting mature crops. In-game notification on proc. *0.3.9* |

### Survival & resources

| Stat        | What it does                   |
| ----------- | ------------------------------ |
| **Health**  | Increases maximum health.      |
| **Stamina** | Increases maximum stamina.     |
| **Mana**    | Increases maximum mana.        |
| **Ammo**    | Increases ammo capacity.       |
| **Oxygen**  | Increases oxygen (underwater). |

### Movement & mana (0.3.6)

| Stat               | What it does                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Movement Speed** | Increases ground movement speed (configurable % per point). Icon: Tree Sap.                                    |
| **Mana Regen**     | Faster mana regeneration. Especially useful for the Arcane class and magical weapons. Icon: Staff Crystal Ice. |

### Stamina tuning

| Stat                   | What it does                                                      |
| ---------------------- | ----------------------------------------------------------------- |
| **StaminaRegenSpeed**  | Faster stamina regeneration.                                      |
| **StaminaConsumption** | Reduces stamina consumed per action. Run, mine, and fight longer. |

All stats have configurable **max points** and **effect per point**. You can blacklist stats you don't want. See [Configuration](config-overview) and [Features](features).

***

## Why progression feels good

The plugin keeps you in a **level band** that fits your character:

| Situation              | XP                  | Combat                      | What it means                                |
| ---------------------- | ------------------- | --------------------------- | -------------------------------------------- |
| **Same level or ±5**   | Best XP             | Fair fight                  | You're in the right zone.                    |
| **6–25 levels higher** | Full XP             | Harder (gap damage/defense) | Challenging but rewarding.                   |
| **26+ levels higher**  | Reduced XP (50–80%) | Very hard                   | Nudges you back to content that matches you. |
| **26+ levels lower**   | Low XP              | Trivial                     | Nudges you into harder zones.                |

**Difficulty presets** (Easy / Normal / Hard / Extreme) control how strong these effects are. You get **balanced game progression** without tuning every number yourself. You can disable underleveled XP reduction, gap defense, or gap damage in config if you want a different pace.

***

## Core loop

1. **Pick a class** (0.3.6) - Choose Heavy, Blunt, Edge, Fang, Archery, or Arcane (or use a server-customized class). Play it to tier up and unlock passives.
2. **Kill mobs** - Gain XP (monster level + level difference).
3. **Use the HUD** - Green zone = best XP; white = too easy; orange/red = too hard.
4. **Level up** - Earn stat points.
5. **Spend points** - Improve Damage, Mining, Defense, Health, Movement Speed, Mana Regen, or any stat you want.
6. **Open `/lvl gui`** - Manage stats, switch class, check leaderboard.

See [Features](features), [Commands](commands), [Classes config](classes-config), [Passives config](passives-config), [Progression](progression), and [Formulas](formulas) for more.