DungeonRPG

# Dungeon RPG

Turn Minecraft combat into a replay~~~~able action-RPG adventure. Open dungeon gateways, battle level-scaled monsters and bosses, hunt randomized equipment, discover named unique items, and recycle unwanted gear at a Salvage Station.

> **Current compatibility:** Minecraft Java Edition 26.2 with Fabric Loader and Fabric API.

## Features

- Four themed dungeons with different rooms, enemies, bosses, and rewards
- Dungeon and equipment levels from 1 to 100
- Random Common, Magic, Rare, and Unique equipment
- 65 named unique items with special abilities
- Level-scaled weapons, armor, monsters, XP, and durability
- Treasure chests, boss rewards, Health Orbs, and crafting materials
- Salvaging and repairing through the Salvage Station
- Multiplayer dungeon support

## Installation

### Singleplayer

1. Install the **Fabric Loader** for Minecraft 26.2.
2. Download the matching **Fabric API**.
3. Place both `fabric-api` and `dungeonrpg` `.jar` files in your Minecraft `mods` folder.
4. Start Minecraft using the Fabric profile.

### Multiplayer server

1. Install the Fabric server for Minecraft 26.2.
2. Place Fabric API and Dungeon RPG in the server's `mods` folder.
3. Place the same mods on every player's client.
4. Restart the server.

Do not unzip the mod `.jar` file.

## Quick Start

Dungeon commands require cheats in singleplayer or operator permission on a server.

1. Stand in a flat, open area in the Overworld.
2. Run:

```text
/dungeonrpg dungeon 1
```

3. A purple gateway will appear nearby.
4. Enter the gateway and explore the dungeon.
5. Defeat enemies, search for treasure chests, and defeat the boss.
6. Use the return gateway to leave with your loot.

The number is the dungeon level and can be any value from **1 to 100**:

```text
/dungeonrpg dungeon <level>
```

Start at level 1 and increase the level as your equipment improves. Dungeon type is selected randomly from the dungeons available at that level.

## Dungeons

| Dungeon | Available | Main material | What to expect |
|---|---:|---|---|
| Hollow Crypt | Level 1+ | Arcane Crystal | An undead crypt with rooms, treasure, and a boss encounter |
| Ember Sanctum | Level 1+ | Ember Dust | A fire-themed stronghold filled with dangerous enemies |
| Frostbound Bastion | Level 5+ | Frost Essence | An icy fortress with frozen hazards and enemies |
| Echoing Depths | Level 10+ | Echo Fragment | A large deep-dark dungeon culminating in a Warden encounter |

**Dungeon Coins** can be found in every dungeon. The other special materials only come from their matching dungeon.

At levels 1–4, Hollow Crypt and Ember Sanctum each have a 50% chance. At levels 5–9, Hollow Crypt has a 34% chance while Ember Sanctum and Frostbound Bastion each have a 33% chance. At level 10+, Echoing Depths has a 30% chance, Frostbound Bastion 24%, and the other two 23% each.

### Gateway rules

- Gateways can only be opened in the Overworld.
- Move to a flatter, clearer area if the game cannot find room for the gateway.
- You cannot replace a dungeon while a player is still inside it.
- Defeat the boss before trying to close a completed gateway.
- The gateway remains available briefly after everyone leaves, allowing the group to return safely.

## Loot and Progression

Equipment may appear as **Common**, **Magic**, **Rare**, or **Unique**. Higher rarity gear can have stronger stats and more valuable salvage rewards.

Generated loot includes weapons, bows, shields, and armor. Item stats and durability scale with the dungeon level where the item drops. Unique items keep their named identity and special power while scaling to the current dungeon level, up to level 100.

Useful tips:

- Compare the complete item tooltip, not only its vanilla material.
- Replace low-level equipment before attempting a large difficulty jump.
- Check ordinary and boss-room chests; boss rewards have better loot opportunities.
- Keep matching scraps for repairing favorite items.
- Consume dropped Health Orbs when you need recovery during a run.

## Salvage Station

Every dungeon includes a Salvage Station. You can also build one at your base.

### Build your own

Place the following blocks:

- **Crying Obsidian** on the bottom
- **Lodestone** directly on top as the Salvage Core
- **Anvil** against one side of the Lodestone
- **Grindstone** on the opposite side
- Optional **Crafting Table** beside the station for recipes

The Anvil and Grindstone must face each other across the Lodestone. They may be placed east/west or north/south.

### Scrap equipment

1. Hold an unwanted generated RPG weapon, armor piece, or shield in your main hand.
2. Sneak and use the Salvage Station (`Shift` + right-click).
3. The equipment is destroyed and converted into base scrap.
4. Magic or better equipment also gives an enchantment scrap matching its rarity tier.

Scrapping is permanent, so double-check the item first.

### Repair equipment

1. Hold damaged generated RPG equipment in your main hand.
2. Put the matching base scrap in your offhand.
3. Use any block belonging to the Salvage Station without sneaking.

One matching scrap restores **25% of the item's maximum durability**. For example, Iron Scrap repairs iron equipment and Diamond Scrap repairs diamond equipment.

Use the station with an empty hand to display its instructions in game.

## Crafting Recipes

All Dungeon RPG recipes are shapeless, so the ingredients can be placed anywhere in a crafting grid.

### Dungeon materials

| Ingredients | Result |
|---|---|
| 8 Dungeon Coins | 1 Golden Apple |
| 2 Arcane Crystals + 1 Glass Bottle | 4 Bottles o' Enchanting |
| 4 Echo Fragments + 1 Compass | 1 Recovery Compass |
| 4 Ember Dust + 1 Stick | 1 Blaze Rod |
| 4 Frost Essence + 1 Packed Ice | 2 Blue Ice |

### Scrap recovery

| Ingredients | Result |
|---|---|
| 4 Wood Scrap | 2 Oak Planks |
| 4 Leather Scrap | 1 Leather |
| 4 Stone Scrap | 2 Cobblestone |
| 8 Gold Scrap | 1 Gold Ingot |
| 6 Copper Scrap | 1 Copper Ingot |
| 6 Iron Scrap | 1 Iron Ingot |
| 8 Diamond Scrap | 1 Diamond |
| 8 Netherite Scrap | 1 vanilla Netherite Scrap |

### Enchantment scrap

| Ingredients | Result |
|---|---|
| 4 Magic Enchant Scrap | 1 Rare Enchant Scrap |
| 4 Rare Enchant Scrap | 1 Unique Enchant Scrap |
| 1 Unique Enchant Scrap | 4 Bottles o' Enchanting |

## Commands

These commands are intended for opening dungeons or testing the mod and require command permission.

| Command | Purpose |
|---|---|
| `/dungeonrpg dungeon` | Open a random level-5 dungeon |
| `/dungeonrpg dungeon <1-100>` | Open a dungeon at the chosen level |
| `/dungeonrpg item` | Generate a random level-5 RPG item |
| `/dungeonrpg item <1-100>` | Generate a random RPG item at the chosen level |
| `/dungeonrpg unique` | Generate a level-5 unique item |
| `/dungeonrpg unique <1-100>` | Generate a unique available at the chosen level |

## Troubleshooting

### Minecraft says the mod is missing dependencies

Install the correct Fabric API version and confirm that Fabric Loader, Fabric API, Dungeon RPG, and Minecraft are compatible with version 26.2.

### The mod does not appear in game

- Confirm the `.jar` is directly inside the `mods` folder.
- Do not place the downloaded ZIP or source project in the `mods` folder.
- Launch the Fabric profile rather than the vanilla Minecraft profile.
- Check `latest.log` for a dependency or version error.

### The dungeon command does not work

- Enable cheats in singleplayer or ask a server administrator for operator permission.
- Use a level from 1 through 100.
- Stand in the Overworld.
- Move to a flat, open area if gateway placement fails.

### Multiplayer players cannot join

Make sure the server and every player use the same Minecraft, Fabric Loader, Fabric API, and Dungeon RPG versions.

### A new dungeon cannot be opened

Have every player leave the active dungeon through its return gateway. If the boss is still alive, complete the dungeon first.

## Feedback and Bug Reports

When reporting a problem, include:

- Minecraft version
- Fabric Loader version
- Fabric API version
- Dungeon RPG version
- Whether it happened in singleplayer or multiplayer
- Steps that reproduce the issue
- The relevant section of `.minecraft/logs/latest.log`

Have fun, prepare carefully, and see how far your build can climb toward level 100.