# Dungeon Crawl — Instanced Dungeon Builder

Dungeon Crawl is a Forge 1.20.1 mod that lets server owners and map creators build custom, repeatable dungeon experiences directly inside Minecraft.

Create a dungeon from an existing build, select its boundaries, add enemy encounters, import custom 3D monsters, design bosses and attack patterns, create quests, configure loot, and send each party into its own temporary dungeon instance.

The original dungeon build remains untouched. Each run receives a private copy inside the Dungeon Instances dimension.

## Important

Dungeon Crawl is currently in active development. Back up important worlds before testing new versions.

Commands and the administration interface require cheats or operator permission.

## Main Features

### Visual Dungeon Editor

Use the Dungeon Controller item to open the administration interface.

The editor contains organized pages for:

- Dungeon maps
- Custom mobs
- Rooms
- Presets
- Model items
- Complex attacks
- Mob AI
- Dungeon rules
- Parties

The interface uses a purple-and-gold design and includes buttons, model dropdowns, live previews, and shortcuts to the main editing tools.

Give yourself the controller with:

`/give @s dungeoncrawl:dungeon_controller`

Right-click the controller to open the editor.

### Dungeon Guide Book

Dungeon Crawl includes an in-game guide that explains how to create a dungeon step by step.

The guide contains:

- Nine instructional pages
- Annotated interface diagrams
- A real custom Pitlord model screenshot
- Direct buttons to editor pages
- Setup instructions
- Model-import instructions
- Troubleshooting information
- Party and instance explanations

Craft the guide using:

- 1 Book
- 1 Compass
- 1 Amethyst Shard

You can also obtain it with:

`/give @s dungeoncrawl:dungeon_guide`

### Create Dungeons From Existing Builds

You can turn an existing Minecraft structure into a reusable dungeon template.

Each dungeon can have:

- A unique dungeon ID
- An opening or lobby position
- An entry position
- A finish position
- Two template boundary corners
- A time limit
- Enemy encounter points
- Boss encounters
- Quest requirements
- Custom loot
- Automation rules
- Checkpoints

The selected structure becomes the dungeon template.

### Large Dungeon Support

Dungeon Crawl supports extremely large dungeon templates.

Current safety limits:

- Up to 50,000,000 blocks per template
- Up to 7,000 blocks wide or deep

Large templates are copied gradually to reduce server freezing.

Copying processes up to 32,768 blocks per tick, while cleanup processes up to 65,536 blocks per tick. Progress is reported every 10%.

The dungeon timer does not begin until the private copy has finished loading.

### Private Dungeon Instances

Every dungeon run is created inside the dedicated dimension:

`dungeoncrawl:dungeon_instances`

When a player or party begins a dungeon:

1. The selected template is copied to a private location.
2. Dungeon markers and encounters are translated to the new location.
3. Players are teleported to the private entry point.
4. The timer begins after copying finishes.
5. The private copy is removed after completion, failure, or timeout.

The original dungeon structure remains unchanged.

Blocks and block entities, including containers such as chests, are copied into the instance.

### Party Support

Players can enter dungeons together as a party.

Party features include:

- Party invitations
- Accepting invitations
- Leaving a party
- Party disbanding
- Party-leader dungeon starts
- Shared dungeon progress
- Shared encounters
- Shared quest progress
- Shared checkpoints
- Shared boss state
- Shared completion results

Every party receives its own private dungeon copy.

If any party member dies during the run, the entire dungeon run fails. Living players are returned immediately, and the dead player is returned after respawning.

### Custom Enemy Encounters

Place enemy spawn points throughout a dungeon and configure:

- Mob profile
- Number of enemies
- Activation radius
- Health
- Damage
- Movement speed
- Armor
- Attack reach
- Attack cooldown
- Hitbox width
- Hitbox height
- AI behavior
- Attack animation
- Custom drops

Enemies can spawn when players approach their encounter area.

### Custom Mob AI

Custom mob profiles support several behavior modes:

- Aggressive
- Guard
- Passive
- Stationary
- Flee

These modes allow creators to build regular enemies, defensive guards, environmental characters, stationary hazards, and mobs that avoid players.

### Custom Hitboxes

Imported monsters are not limited to the standard zombie-sized hitbox.

Each mob profile can have a configurable:

- Hitbox width
- Hitbox height
- Attack reach
- Model scale

This makes it possible to create small creatures, large monsters, and oversized bosses.

### Complex Attack Patterns

Custom mobs can use multi-step attack patterns.

Each attack step can configure:

- Animation
- Wind-up time
- Damage multiplier
- Attack reach
- Forward lunge
- Area-of-effect range

Attack patterns can combine multiple steps to create abilities such as:

- Fast combos
- Heavy delayed strikes
- Lunging attacks
- Wide area attacks
- Boss attack sequences
- Animated slashes
- Multi-stage abilities

### Custom Attack Animations

BBMODEL monsters can use animations created in Blockbench.

Animations can be selected for attacks, allowing the model’s arms, body, weapons, and other bones to move during abilities.

The preview animation speed has been adjusted so moving limbs can be inspected more easily.

### OBJ Model Importing

Dungeon Crawl can load custom OBJ models for enemies and model items.

Place the model folder inside:

`<Minecraft instance>/dungeoncrawl/models/<model_name>/`

Keep the model and texture files together inside that folder, then run:

`/dungeon reload`

You can select successfully loaded models from the model dropdown instead of entering every resource path manually.

### Blockbench BBMODEL Support

Dungeon Crawl supports `.bbmodel` files exported or saved by Blockbench.

BBMODEL support includes:

- Model geometry
- Bone hierarchy
- Pivot points
- UV information
- Embedded or accompanying textures
- GeckoLib animation integration
- Live 3D preview
- Animated mob rendering

Place the BBMODEL and its required textures inside a folder under:

`<Minecraft instance>/dungeoncrawl/models/<model_name>/`

Then reload Dungeon Crawl.

For multiplayer, every player who needs to see an imported model should have the same external model folder.

### Live 3D Model Preview

The mob and item editors contain a live 3D preview.

The preview helps verify:

- Texture placement
- Model orientation
- Scale
- Animation
- Model selection
- Imported geometry

This lets creators inspect a model before spawning it into a dungeon.

### Model Dropdowns

Successfully loaded external models appear in dropdown menus.

This removes the need to manually search for or repeatedly type model paths.

Mob models and item models are separated so model items do not appear inside the mob selection list.

### Custom Model Items

Imported models can also be turned into usable Minecraft items.

Supported item categories include:

- Generic items
- Weapons
- Shields
- Helmets
- Chestplates
- Leggings
- Boots

Model items can be:

- Held
- Dropped
- Stored in inventories
- Given through the editor
- Used as weapons
- Used as shields
- Equipped as armor

The mod includes example model items such as:

- Barrel Knight
- Pitchfork
- Wooden Bucket
- Wooden Wheel
- Blocking Wheel

### Boss Encounters

Each dungeon can have a configured boss encounter.

Bosses can use:

- Imported OBJ or BBMODEL visuals
- Custom health
- Custom damage
- Custom armor
- Custom movement speed
- Large hitboxes
- Extended attack reach
- Custom attack cooldowns
- Complex attack patterns
- Custom animations
- Custom loot
- AI behavior settings

Bosses can be placed at the end of a dungeon and connected to quests or automation rules.

### Dungeon Quests

Dungeons can require players to complete objectives before finishing.

Quest settings include:

- Required mob profile
- Required kill count
- Shared party progress
- Automation condition support

Quest completion can unlock later events, checkpoints, bosses, messages, or dungeon completion.

### Custom Loot

Custom enemies and bosses can have their own drop configurations.

This allows dungeon creators to choose what enemies reward and build dungeon-specific progression.

### Dungeon Automation

Dungeon Crawl includes a Trigger → Condition → Function automation system.

Automation rules are stored persistently with dungeon data.

Available triggers include:

- Area entered
- Mob killed
- Block interacted with
- Block broken
- Dungeon started

Available conditions include:

- Always
- Quest completed
- Minimum kills reached
- Minimum player count
- Time remaining is below a selected value

Available functions include:

- Display a message
- Spawn a custom mob
- Set a checkpoint
- Teleport players to a checkpoint
- Play a sound
- Run a command
- Complete the dungeon

A single automation can run multiple functions, allowing creators to build scripted dungeon sequences without writing Java code.

Examples include:

- Enter a room and close the exits.
- Spawn several waves of enemies.
- Wait until the quest kill count is reached.
- Display a boss message.
- Spawn the boss.
- Set a checkpoint after the boss dies.
- Complete the dungeon when players reach the exit.

### Edit Mode

Edit Mode lets creators work on a dungeon without accidentally starting it.

Use:

`/dungeon edit <dungeon_id>`

Disable it with:

`/dungeon editoff`

While Edit Mode is active, special markers show important dungeon locations.

Markers are only visible to the player editing the dungeon.

Marker types include:

- Portal marker for the dungeon opening
- Green villager marker for the entry point
- Firework marker for the finish point
- Flame markers for enemy encounters
- Soul-flame marker for the boss
- Enchantment markers for automation locations

Looking near a marker displays an action-bar label explaining what it represents.

### Dungeon List

The Map page displays all created dungeons.

Creators can review their dungeon IDs and select the dungeon they want to edit instead of having to remember every name.

The command version is:

`/dungeon list`

## Basic Setup

A normal dungeon setup follows these steps:

1. Build the dungeon in the normal world.
2. Create a dungeon ID.
3. Enable Edit Mode for that dungeon.
4. Set the opening position.
5. Set the dungeon entry position.
6. Set the finish position.
7. Select template corner one.
8. Select template corner two.
9. Set the time limit.
10. Add enemy encounter points.
11. Configure the quest.
12. Configure the boss.
13. Add loot and automation rules.
14. Save the dungeon.
15. Start a test run.
16. Disable Edit Mode when finished.

## Useful Commands

All Dungeon Crawl administration commands require cheats or operator permission.

Main commands:

- `/dungeon create <id>`
- `/dungeon list`
- `/dungeon delete <id>`
- `/dungeon edit <id>`
- `/dungeon editoff`
- `/dungeon setopening <id>`
- `/dungeon setentry <id>`
- `/dungeon setfinish <id>`
- `/dungeon setcorner1 <id>`
- `/dungeon setcorner2 <id>`
- `/dungeon time <id> <seconds>`
- `/dungeon addspawn ...`
- `/dungeon quest ...`
- `/dungeon boss ...`
- `/dungeon start <id>`
- `/dungeon save`
- `/dungeon reload`

Party commands:

- `/dungeon party invite <player>`
- `/dungeon party accept <player>`
- `/dungeon party leave`

Custom mob tools:

- `/dungeon mob create ...`
- `/dungeon mob spawn ...`
- `/dungeon mob stats ...`
- `/dungeon mob hitbox ...`
- `/dungeon mob attack ...`
- `/dungeon mob behavior ...`
- `/dungeon mob model ...`
- `/dungeon mob pattern ...`
- `/dungeon mob drop ...`

Model-item tools:

- `/dungeon item give ...`

Automation tools:

- `/dungeon automation create ...`
- `/dungeon automation condition ...`
- `/dungeon automation function ...`
- `/dungeon automation remove ...`

The in-game administration GUI is recommended for most setup tasks.

## Requirements

- Minecraft 1.20.1
- Minecraft Forge 47 or newer
- GeckoLib 4.4.9
- Java 17

GeckoLib is a required dependency and must be installed.

Dungeon Crawl must be installed on both the server and connecting clients.

## Installation

1. Install Minecraft Forge for Minecraft 1.20.1.
2. Install GeckoLib 4.4.9.
3. Place the Dungeon Crawl JAR inside the `mods` folder.
4. Start Minecraft.
5. Create or open a world with cheats enabled.
6. Give yourself the Dungeon Controller or Dungeon Guide.
7. Begin creating your first dungeon.

## Compatibility

Dungeon Crawl is an original Forge mod inspired by visual and scripted dungeon-building systems.

It does not require CustomNPCs, MythicMobs, or MythicDungeons.

Custom model assets must be supplied separately unless they are included with Dungeon Crawl or its example content.

## Current Version

Version: 0.2.0

Minecraft: 1.20.1

Mod Loader: Forge

License: MIT

Author: V-Fusion

QWEN DUNGEON CRAWL