# DungLe'Master Mod — Full Documentation

**Minecraft Forge 1.20.1 | ModID: `dungeonmaster`**

DungeonMaster is a server-side RPG framework for Minecraft that transforms the survival experience into a full dungeon-crawl RPG. Players level up, allocate stats, fight scaled enemies, and earn dynamically generated loot — no two items are alike.

---

## Table of Contents

1. [Core Systems Overview](#1-core-systems-overview)
2. [Player Levels & Stats](#2-player-levels--stats)
3. [Skill Progression Menu](#3-skill-progression-menu)
4. [Mob Level Scaling](#4-mob-level-scaling)
5. [XP & Kill Rewards](#5-xp--kill-rewards)
6. [Buff System](#6-buff-system)
7. [Dynamic Loot System](#7-dynamic-loot-system)
8. [Item Requirements & Auto-Unequip](#8-item-requirements--auto-unequip)
9. [Dungeon Rewards (/dungeon reward)](#9-dungeon-rewards-dungeon-reward)
10. [Operator Commands (Full Reference)](#10-operator-commands-full-reference)
11. [Player Commands (Full Reference)](#11-player-commands-full-reference)
12. [GUI Screens Reference](#12-gui-screens-reference)
13. [Config Files](#13-config-files)
14. [Installation & Requirements](#14-installation--requirements)

---

## 1. Core Systems Overview

DungeonMaster adds the following interconnected systems:

| System | Description |
|---|---|
| Player Levels | Players earn XP from kills, level up, gain skill points |
| Stat Allocation | Spend skill points on Strength / Agility / Intelligence |
| Attribute Bonuses | Each stat point grants configurable attribute bonuses (damage, HP, speed, etc.) |
| Mob Scaling | Enemy level and stats scale to nearby players |
| Dynamic Loot | Every reward item is uniquely generated with level, rarity, requirements, and random bonuses |
| Buff System | Operators define persistent buffs (attribute bonuses) that can be assigned to players |
| Dungeon Rewards | After a dungeon run, players receive XP, gold, and dynamically generated items |

All operator settings (stat bonuses, buffs, loot config) are applied only after **`/dungeon restart`** — changes never take effect mid-session automatically.

---

## 2. Player Levels & Stats

### How Leveling Works

- Players start at **Level 1** with 0 XP.
- XP is earned by killing monsters (see [XP & Kill Rewards](#5-xp--kill-rewards)).
- XP required to level up: `100 + (currentLevel - 1) × 25`
- Level 1 → 2: 100 XP
- Level 10 → 11: 325 XP
- Level 50 → 51: 1325 XP
- On level-up, the player gains **1 Skill Point**.
- Level and XP persist through death and reconnect.

### Stats

Each player has three core stats:

| Stat | Key | Default |
|---|---|---|
| Strength | `strength` | 0 |
| Agility | `agility` | 0 |
| Intelligence | `intelligence` | 0 |

Stats are increased by spending Skill Points via the [Progression Menu](#3-skill-progression-menu).

Each stat point provides configurable attribute bonuses — configured by the operator via **`/dungeon stateedit`**.

### Data Persistence

Player data is stored via Forge Capabilities (attached to the `Player` entity) and serialized to NBT. It is correctly copied on death (`PlayerEvent.Clone`) and re-synced on respawn and login.

---

## 3. Skill Progression Menu

The progression menu opens automatically when you press **ESC** in-game (replaces the vanilla pause menu). It is also accessible from the Dungeon Main Menu.

### What It Shows

- Current level and XP bar (current / needed to next level)
- Available Skill Points
- Current values of Strength, Agility, Intelligence
- **"+"** buttons to spend a Skill Point on a stat

### Notes

- Each "+" click spends 1 Skill Point and increases the stat by 1.
- Attribute bonuses (e.g., Strength → +attack damage) apply immediately after spending.
- If you have 0 Skill Points, the "+" buttons are greyed out.

---

## 4. Mob Level Scaling

### Level Calculation

When a hostile monster spawns, its level is calculated from nearby players:

```
averageLevel = average level of all players within 30 blocks
mobLevel = averageLevel ± random(0..3) (minimum: 1)
```

If no players are nearby, the mob spawns at level 1.

### Stat Scaling

The mob's attributes (max HP, attack damage, armor, etc.) are scaled up based on its level using the operator-configured **Mob Scaling Config** (`/dungeon stateedit` → Mobs tab or `dungeonmaster_scaling.json`).

Example: if attack damage is configured for +0.5 per level, a level 20 mob gets +9.5 attack damage on top of its base value.

### Level Visibility

Mob levels are **not permanently shown** above their heads. They appear only when **you personally** are within **5 blocks** of the mob:

- Within 5 blocks: `[Lv. 25] Zombie` appears above the mob
- Beyond 5 blocks: name is hidden (same as vanilla unnamed mob)

This is rendered per-player on the client — other players nearby may or may not see the level depending on their own distance.

---

## 5. XP & Kill Rewards

When a player kills a monster, they receive XP based on the level difference formula configured in `dungeonmaster_xp.json`:

```
xp = baseXP + levelDiffBonus × (mobLevel - playerLevel)
(clamped to a minimum of minXP)
```

- Killing enemies far below your level yields minimal XP (anti-farm protection).
- Killing enemies at or above your level gives full or bonus XP.
- On XP gain, a chat message appears: `+ N опыта / + N XP`
- On level-up: `✦ New level! You are now level N. Skill points available: M`

XP formula parameters are configurable via the `dungeonmaster_xp.json` config file (see [Config Files](#13-config-files)).

---

## 6. Buff System

Buffs are named sets of attribute bonuses that operators create and assign to players. They are separate from stat bonuses — a buff is more like a "class perk" or "equipment set bonus."

### Creating Buffs

Use **`/dungeon editbuff`** to open the Buff Editor GUI:

- Create a named buff (e.g., "Warrior", "Mage")
- Add attribute entries: choose an attribute from the Forge registry, set a value, choose FLAT (add) or PERCENT (multiply)
- Save the buff — it is stored in `dungeonmaster_buffs.json`
- Changes apply after **`/dungeon restart`**

### Assigning Buffs

```
/dungeon buff <player> <buffName>
```

This assigns the named buff to the player. The player receives all attribute modifiers defined in the buff immediately (via transient AttributeModifier, removed on logout or buff change).

### Removing Buffs

```
/dungeon removebuff <player>
```

Removes the current buff from the player.

### Buff Storage

Buff assignments are stored in the player's capability NBT and persist through death/reconnect.

---

## 7. Dynamic Loot System

Every item generated by the dungeon reward system is **unique**. Two identical iron swords can have completely different stats. Items are generated at the moment of the reward, based on the player's current level and stats.

### Item Generation Process

1. **Base item** is chosen randomly from the configured item pool (swords, axes, bows, helmets, etc.)
2. **Item Level** = `playerLevel ± itemLevelVariance` (default variance: ±3)
3. **Requirements** are generated from the player's current stats ± variance:
- Required Level ≈ item level
- Required Strength = player STR ± requirementVariance
- Required Agility = player AGI ± requirementVariance
- Required Intelligence = player INT ± requirementVariance
4. **Rarity** is chosen via weighted random from the 7 tiers (see below)
5. **Bonuses** are rolled from the attribute pool for the item's **category** (Weapon or Armor)
6. All data is written to the `ItemStack` NBT under the `DungeonMasterItem` tag

### Rarity Tiers

| Rarity | Color | Default Weight | Bonus Count |
|---|---|---|---|
| Common | Gray `#808080` | 100 | 1 |
| Uncommon | Turquoise `#40E0D0` | 60 | 1–2 |
| Rare | Blue `#1E90FF` | 30 | 2–3 |
| Super Rare | Purple `#8A2BE2` | 15 | 3–4 |
| Epic | Pink `#FF1493` | 7 | 4–5 |
| Mythic | Orange `#FF8C00` | 3 | 5–6 |
| Legendary | Gold `#FFD700` | 1 | 6–8 |

All weights and bonus counts are fully configurable via `/dungeon lootedit`.

### Item Categories

Items are sorted into categories. Each category has its own attribute pool:

- **Weapon** (swords, axes, bows, crossbows, tridents): attack damage, attack speed, luck
- **Armor** (helmets, chestplates, leggings, boots): max HP, armor, movement speed, knockback resistance

Operators can create additional custom categories (e.g., Accessories, Artifacts, Shields) and assign their own attribute pools via `/dungeon lootedit`.

### Level Scaling

Bonus values scale with item level:
```
finalValue = baseValue × (1.0 + (itemLevel - 1) × valuePerItemLevel)
```
Default `valuePerItemLevel` = 0.08 (8% stronger per level above 1).

### Tooltip Display

When hovering over a generated item, the tooltip shows:
```
[Epic] Item Level: 22
Requirements: Lv. 12 5 Str. 3 Agi. 1 Int.
• +4.8 attack_damage (FLAT)
• +12% movement_speed (PERCENT)
• +2.1 attack_speed (FLAT)
```

---

## 8. Item Requirements & Auto-Unequip

Every generated item has **4 mandatory requirements** that are always displayed:

```
Requirements: Lv. 12 5 Str. 2 Agi. 1 Int.
```

(Values of 0 are shown too — all four always appear.)

### Requirement Checking

Every 10 ticks (0.5 seconds), the server checks all equipment slots (main hand, off hand, head, chest, legs, feet) for each player.

If a player **does not meet** the requirements of an equipped item:

1. The item is automatically **unequipped** (returned to inventory, or dropped on the ground if inventory is full)
2. The player receives a chat message explaining why:
- `Insufficient level. Required: 12 Current: 8`
- `Insufficient Strength. Required: 5 Current: 3`
- `Insufficient Agility. Required: 4 Current: 1`
- `Insufficient Intelligence. Required: 3 Current: 0`
3. The message only appears when the **reason changes** — no chat spam if the player keeps trying to put it back on.

### Attribute Modifiers

When requirements ARE met, the item's bonuses are applied as transient `AttributeModifier` entries on the player. They are removed automatically when the item is unequipped or requirements fail.

---

## 9. Dungeon Rewards (`/dungeon reward`)

After completing a dungeon, the operator runs:

```
/dungeon reward <player>
```

This triggers the reward sequence:

1. **XP** is calculated: `baseXP + xpPerPlayerLevel × playerLevel`
2. **Gold** is given: `baseGold + goldPerPlayerLevel × playerLevel` units of the configured gold item (default: emeralds)
3. **Items** are generated: between `minItems` and `maxItems` unique items
4. All rewards are placed in the player's inventory (or dropped at their feet if full)
5. A **Reward Screen** opens showing:
- XP gained (with level-up indicator if applicable)
- Gold amount and icon
- Each generated item with its icon, rarity color, and subtitle: `Rarity · Lv. N · Bonuses: M`

All reward parameters are configurable via `/dungeon lootedit` → Rewards tab.

---

## 10. Operator Commands (Full Reference)

All operator commands require **permission level 2** (OP).

---

### `/dungeon restart`

Reloads all mod configs from disk and reapplies everything.

**Use this after any change** made via the editor GUIs (`stateedit`, `editbuff`, `lootedit`).

```
/dungeon restart
```

Output: `[DungeonMaster] Configs reloaded. Mob scaling, stat bonuses, buff data, and loot config updated.`

---

### `/dungeon stateedit`

Opens the **Stat Bonus Editor** GUI (operator only).

```
/dungeon stateedit
```

This GUI lets you configure:

**Player Stats tab:**
- Which Minecraft/Forge attribute each stat point improves
- The value per point (flat number or % — toggle with FLAT/PERCENT button)
- Example: Strength → `minecraft:generic.attack_damage` +0.5 FLAT per point

**Mob Scaling tab:**
- Same structure but for mob level scaling
- Example: `minecraft:generic.max_health` +2.0 FLAT per mob level above 1

Changes are saved to `dungeonmaster_scaling.json` and `dungeonmaster_stats.json`. Apply with `/dungeon restart`.

---

### `/dungeon editbuff`

Opens the **Buff Editor** GUI (operator only).

```
/dungeon editbuff
```

Tabs in the GUI:
- **My Buffs**: list of all defined buffs, click to edit
- **Edit Buff**: name field, list of attribute entries (attribute selector, value, FLAT/PERCENT toggle), Save/Delete buttons
- **Add Buff**: create a new named buff

Changes are saved to `dungeonmaster_buffs.json`. Apply with `/dungeon restart`.

---

### `/dungeon buff`

Assigns a buff to a player.

```
/dungeon buff <player> <buffName>
```

- `<player>`: player name (must be online)
- `<buffName>`: exact name of a defined buff (case-sensitive)

Example:
```
/dungeon buff Steve Warrior
```

---

### `/dungeon removebuff`

Removes the current buff from a player.

```
/dungeon removebuff <player>
```

---

### `/dungeon lootedit`

Opens the **Loot & Reward Editor** GUI (operator only).

```
/dungeon lootedit
```

Three tabs:

**Rarities tab:**
- For each of the 7 rarities: Weight, Color (hex #RRGGBB), Min Bonuses, Max Bonuses

**Attributes tab:**
- Select the active item category using the `<` / `>` arrows (or `+` to add a new category, `x` to delete custom ones)
- Edit the category name
- Up to 10 attribute rows per category: attribute selector (click to cycle), min/max value range, mode (FLAT / PERCENT / BOTH)
- "BOTH" means the mode is chosen randomly per item at generation time

**Rewards tab:**
- Base XP, XP per player level
- Base gold, gold per player level
- Gold item ID (e.g., `minecraft:emerald`)
- Min/max items per reward
- Item level variance (±)
- Requirement variance (±)
- Value scale per item level (e.g., `0.08` = 8% stronger per level)

Changes are saved to `dungeonmaster_loot.json`. Apply with `/dungeon restart`.

---

### `/dungeon reward`

Gives a player the full dungeon completion reward.

```
/dungeon reward <player>
```

Triggers XP, gold, and item generation. Opens the Reward Screen for the player.

---

## 11. Player Commands (Full Reference)

Players (no OP required) have access to:

### `/dungeon` (Main Menu)

Opening the main menu also happens automatically on ESC. From the menu:
- View your level and XP
- Open the Progression screen to spend Skill Points
- View your current buff (if any)

No direct chat command for individual features — everything is GUI-driven.

---

## 12. GUI Screens Reference

| Screen | How to Open | Who |
|---|---|---|
| Main Menu (DungeonMaster) | ESC in-game | Everyone |
| Progression / Stat Allocation | From Main Menu → "Прокачка" button | Everyone |
| Custom Inventory | Press E (in survival) | Everyone |
| Buff Editor | `/dungeon editbuff` | Operator |
| Stat Bonus Editor | `/dungeon stateedit` | Operator |
| Loot & Reward Editor | `/dungeon lootedit` | Operator |
| Reward Screen | Triggered by `/dungeon reward` | Everyone (auto-opens) |

---

## 13. Config Files

All config files are stored in the **`config/`** folder of your Minecraft server/client:

| File | Contents |
|---|---|
| `dungeonmaster_stats.json` | Stat bonus entries (STR/AGI/INT → attribute mappings for players) |
| `dungeonmaster_scaling.json` | Mob attribute scaling per level |
| `dungeonmaster_buffs.json` | All defined buffs and their attribute entries |
| `dungeonmaster_loot.json` | Rarity weights, attribute pools per category, reward parameters |
| `dungeonmaster_xp.json` | XP formula parameters (base XP, level-diff bonuses, minimum XP) |

All files are created with sane defaults on first launch. Edit them manually or via the in-game GUIs, then run `/dungeon restart`.

### Example: `dungeonmaster_loot.json` (partial)

```json
{
"rarities": {
"COMMON": { "weight": 100, "color": 8421504, "minBonuses": 1, "maxBonuses": 1 },
"LEGENDARY": { "weight": 1, "color": 16766720, "minBonuses": 6, "maxBonuses": 8 }
},
"categories": [
{
"id": "weapon",
"displayName": "Weapon",
"attributes": [
{ "attribute": "minecraft:generic.attack_damage", "minValue": 1.0, "maxValue": 8.0, "mode": "FLAT" },
{ "attribute": "minecraft:generic.attack_speed", "minValue": 2.0, "maxValue": 15.0, "mode": "BOTH" }
]
},
{
"id": "armor",
"displayName": "Armor",
"attributes": [
{ "attribute": "minecraft:generic.max_health", "minValue": 2.0, "maxValue": 12.0, "mode": "FLAT" },
{ "attribute": "minecraft:generic.armor", "minValue": 1.0, "maxValue": 6.0, "mode": "FLAT" }
]
}
],
"baseXp": 50,
"xpPerPlayerLevel": 5,
"baseGold": 10,
"goldPerPlayerLevel": 2,
"goldItem": "minecraft:emerald",
"minItems": 1,
"maxItems": 3,
"itemLevelVariance": 3,
"requirementVariance": 5,
"valuePerItemLevel": 0.08
}
```

---

## 14. Installation & Requirements

**Requirements:**
- Minecraft 1.20.1
- Forge 47.4.10 or higher
- Java 17+

**Installation:**
1. Install Minecraft Forge 1.20.1
2. Place `dungeonmaster-1.0.0.jar` into the `mods/` folder
3. Launch the server/client once to generate default config files
4. Configure via in-game GUIs (operator) or edit config files directly
5. Run `/dungeon restart` to apply any changes

**Server vs. Client:**
- The mod must be installed on **both server and client** (it uses custom networking packets and GUI screens)
- All game logic (leveling, scaling, loot generation) runs on the server
- GUI rendering and name-tag display run on the client

---

*DungeonMaster — built with Minecraft Forge 1.20.1 | Package: `com.lemxy.dungeonmaster`* U can find the guide on my discord server!