DungLe'Master

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
2. Player Levels & Stats
3. Skill Progression Menu
4. Mob Level Scaling
5. XP & Kill Rewards
6. Buff System
7. Dynamic Loot System
8. Item Requirements & Auto-Unequip
9. Dungeon Rewards (/dungeon reward)
10. Operator Commands (Full Reference)
11. Player Commands (Full Reference)
12. GUI Screens Reference
13. Config Files
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).
• 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.

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

---

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)

{  
"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!