MCDungeon Tool Wiki

MCDungeon Tool is a Python-based map editing utility designed to generate random, procedural dungeons and scavenger hunt-like treasure quests within existing Minecraft maps. It functions as a standalone program, modifying world files directly rather than being an in-game mod.

This tool offers extensive customization for dungeon generation, allowing players to control various aspects of the structures, from room layouts and trap placements to mob spawners and loot tables. It can automatically find suitable locations for dungeons based on specified parameters and can even detect existing player structures to avoid overwriting them.

Key features include the ability to generate multiple dungeons, regenerate existing ones with new layouts, and even remove dungeons, allowing the landscape to revert. It also supports outputting floor maps to a terminal or entire dungeon maps to HTML, and can generate Points of Interest (POI) for use with tools like Minecraft Overviewer.

MCDungeon Tool is not an in-game mod; it does not generate dungeons on the fly or modify Minecraft's core files. Users are advised to back up their maps before using the tool, as it directly modifies world data.

Most of MCDungeon's customization is managed through configuration files, typically located in a configs/ folder. These files follow an INI-style format, using sections and key: value pairs to define various generation parameters. A default.cfg file serves as a starting point, and sample configurations are often provided in an example_configs folder.

Dungeon Features ([dungeon])

This section controls fundamental dungeon parameters:

• loops: Percentage of loops in the dungeon. Lower values (e.g., <30%) result in more linear layouts, while higher values create grid-like structures.
• min_dist: Minimum distance in chunks from the spawn chunk for automatic dungeon placement.
• max_dist: Maximum distance in chunks from the spawn chunk.
• maximize_distance: (True/False) If true, attempts to place multiple dungeons as far apart as possible. If false, ignores inter-dungeon distance, potentially placing them closer.
• offset: (X, Y, Z) Provides a block-based location offset for the dungeon's northwest corner, overriding automatic burial.
• force_bury: (True/False) Attempts to calculate the Y-coordinate when offset is used.
• tower: Extra height in blocks for tower-type entrances.
• ruin_ruins: (True/False) If false, prevents the ruining of towers and surface buildings.
• doors: Percentage of doors to be placed within the dungeon.

Rooms ([rooms])

This section defines the types, sizes, and weights of rooms used in dungeon generation. It allows for a random weighted selection of room layouts, which are then filled with various features.

Halls ([halls])

Configures the types of hallways, including their features and potential traps.

Floors ([floors])

Determines the materials and patterns used for dungeon floors.

Features ([features])

This section specifies various room features and surface ruins that can be generated within and around dungeons.

Stairwells ([stairwells])

Controls the generation and types of stairwells connecting different levels of the dungeon.

Secret Rooms ([secret rooms])

Defines parameters for the random placement and characteristics of secret rooms.

Entrances ([entrances])

Configures the various forms dungeon entrances can take, including tower entrances with spiraling staircases.

Treasure Rooms ([treasure rooms])

Each dungeon includes a special room at its lowest level containing high-tier loot chests. Examples of treasure rooms include:

• A large room with Blaze spawners and additional high-tier mob spawners.
• A burial chamber filled with sarcophagi.
• A secret Illager library.
• A large pit room with archers and lava.
• An ancient throne room.
• A natural cave with hidden spider spawners.
• A deactivated portal to The End.

Mobs ([mobs])

This section configures the types and density of mob spawners placed throughout the dungeon. It also allows for the inclusion of 'non-standard' mob types.

Traps ([hall traps], [projectile traps], [chest traps])

These sections detail the random placement and types of various traps:

• Hall Traps: Traps found within hallways.
• Projectile Traps: Traps that launch projectiles.
• Chest Traps: Traps associated with chests.
• Pit rooms can also be rigged with falling sand traps under specific conditions.

Loot Tables ([tier])

An arbitrary number of loot tables can be configured to provide variety in dungeon chests. This section defines the contents and tiers of loot found in chests.

Treasure Hunt ([treasure hunt])

Configures parameters for generating scavenger hunt-like treasure quests.

Landmarks ([landmarks], [landmark_mobs])

These sections define surface landmarks that can be generated and the mobs associated with them.

MCDungeon Tool supports advanced customization through dedicated files for various custom content types.

• Books: Allows for the definition of custom books found within dungeons.
• Custom Items: Enables the inclusion of custom items with defined properties.
• Custom Paintings: Supports custom paintings for dungeon decoration.
• Custom Spawners: Provides options for configuring custom mob spawners.
• Custom Shops: Allows for the creation of custom shops within dungeons.
• Dye Colors: Configures available dye colors.
• Magic Items: Defines properties for custom magic items.
• Potions File: Manages custom potion effects and recipes.
• Recipes File: Enables the addition of custom crafting recipes for items found or used in dungeons.

MCDungeon Tool implements several core mechanics to create dynamic and varied dungeon experiences.

• Procedural Generation: Dungeons are generated with random, complex layouts, ensuring unique experiences with each creation.
• Intelligent Placement: The tool automatically identifies suitable locations on a map based on range, size, and depth parameters. It can also detect existing player structures and attempt to avoid overwriting them.
• Dungeon Management: Dungeons can be removed from a map, allowing the landscape to regenerate, or regenerated in place with new layouts, mobs, and treasure.
• Multi-Dungeon Support: Capable of generating multiple dungeons within a single map, or filling the map with as many dungeons as possible.
• Configurable Elements: Almost every aspect of dungeon generation is configurable, including:
  • Room layouts based on weighted selections.
  • Hallways, traps, floors, and room features.
  • Density and placement of doors, portcullises, and torches.
  • Option for fewer torches on lower levels to increase difficulty.
• Hard Mode: An optional 'hard mode' attempts to fill in nearby natural caves, concentrating monster spawns inside the dungeon for increased challenge.
• Navigation: Stairwells connect dungeon levels, and tower entrances often feature spiraling staircases. Entrances can take many forms.
• Exiting Dungeons: An optional command block-powered portal can be placed at the bottom of a dungeon to teleport players out.
• Treasure and Mobs: Chests with loot are placed in hard-to-reach locations, with configurable density and arbitrary loot tables. Mob spawners are placed throughout, often near chests, with configurable types and density, including some 'non-standard' mobs.
• Secrets: Random placement of secret traps and secret rooms adds an element of discovery.
• Output Options: The tool can output floor maps to a terminal (with color on ANSI systems) and entire dungeon maps to HTML. It also provides Point of Interest (POI) information for tools like Minecraft Overviewer.