A procedural dungeon generator for Minecraft
Python Other
Latest commit d5ad0df Feb 8, 2017 @orphu 0.17.1 Release
Failed to load latest commit information.
books Another try at one title. Issue #229 Sep 5, 2014
d Remove flower pot ID value image tiles. Issue #381 Nov 19, 2016
extras Add --clean to pyinstaller build script Dec 4, 2016
items Update shop items for 1.1 Issue #375 Add two new shops: Beastmaster a… Oct 30, 2016
namegen Inital name generator commit Mar 13, 2013
names Add piratey name theme to generator Aug 12, 2014
overviewer_icons Add icons for overviewer POI configuration Aug 20, 2014
paintings Merge pull request #250 from sshipway/development Mar 27, 2015
pymclevel @ d5abd5d
shops Add new enchanted book for Sweeping Edge to loot tables. Issue #395 Jan 28, 2017
spawners Remove outdated reference to WitherSkeleon.nbt in spawners readme.txt. Nov 30, 2016
yaml Add back in yaml for pymclevel. Mar 3, 2012
.gitignore Add windows Thumbs.db files to gitignore Jun 9, 2016
.gitmodules Use HTTPS and not SSH for pymclevel submodule. Aug 23, 2014
CHANGELOG.txt 0.17.1 Release Feb 9, 2017
README.md CHANGELOG and README updates for 0.14.2. Apr 15, 2015
cave_demo.py Code cleanup via autopep8. Apr 24, 2014
cave_factory.py Code cleanup via autopep8. Apr 24, 2014
cfg.py Remove left over debugging. Issue #379 Nov 5, 2016
disjoint_set.py Formatting and cleanup. Sep 13, 2013
doors.py Code cleanup via autopep8. Apr 24, 2014
dungeon.py Fix flower pots in generation. Removed varient pots from materials.cf… Nov 5, 2016
dungeon_name_test.py More dungeon adjectives. Adjusted some name probabilities. Aug 29, 2014
dye_colors.txt Add support for new items etc. Mar 13, 2013
features.py Fix flower pots in generation. Removed varient pots from materials.cf… Nov 5, 2016
flaggenerator.py Improvements to banner/flag generator Jan 14, 2017
floors.py Code cleanup via autopep8. Apr 24, 2014
fortunes.txt We should probably remove this fortune Nov 9, 2013
hall_traps.py Fixed sounds for portcullises. Closes #398 Feb 1, 2017
halls.py Door materials are now chosen per dungeon. Mar 20, 2016
inventory.py Fix banner patterns when used as loot. Closes #397 Feb 1, 2017
items.py Adds support for setting CustomPotionColor in potions.txt Closes #368 Oct 29, 2016
items.txt Add Iron Nuggets to items and tier 1 loot tables. Closes #396 Jan 28, 2017
loottable.py Add Sweeping Edge to enchantment functions. Issue #395 Jan 28, 2017
magic_items.txt Add MIGHTY quote to lore of Sweeping Edge book. Issue #395 Jan 28, 2017
mapstore.py Add config setting to alter color of dungeon map and painting map spr… Nov 2, 2016
materials.py Implement string item IDs. Issue #314 Aug 12, 2015
namegenerator.py Add piratey name theme to generator Aug 12, 2014
perlin.py Code cleanup via autopep8. Apr 24, 2014
perlin_test.py Code cleanup via autopep8. Apr 24, 2014
pmeter.py Code cleanup via autopep8. Apr 24, 2014
ruins.py Fix flower pots in generation. Removed varient pots from materials.cf… Nov 5, 2016
shop.py Add 1-3 flyers per secret shop. Issue #240 Sep 14, 2014
utils.py Fix dungeon / treasure hunt detection and info chest name tag. Closes #… Jan 14, 2017



MCDungeon will create a procedurally generated dungeon in a preexisting Minecraft map. It is not yet feature complete, but can already generate dungeons with quite a bit of variety.

Website: http://mcdungeon.bubblemod.org

Documentation: http://mcdungeon-docs.bubblemod.org


  • Automatically finds a good location on a map based on range, size, and depth parameters. Can detect player structures and try not to overwrite them. Avoids placing dungeons in the middle of the ocean.

  • Dungeons can be removed from a map later and the landscape allowed to regenerate.

  • Dungeons can be regenerated in place with a new layout, mobs, and treasure.

  • Can generate multiple dungeons in a map, or try to fill the map with as many dungeons as possible.

  • Generates room layouts based on a random weighted selection of rooms. Rooms are filled with random hallways, floors, room features, and ruins on the surface, all of which are configurable.

  • The density and placement of doors, portcullises, and torches are configurable. Option to place fewer torches as levels go down. Less light == more danger!

  • A "fill caves" mode that will fill in nearby natural caves in an attempt to concentrate random monster spawns inside the dungeon.

  • Places stairwells between levels, and a random entrance with a spiraling staircase. Some entrances have a configurable height so it can be seen from far away.

  • Places chests with loot around the dungeon in (probably) hard to reach places. An arbitrary number of loot tables can be configured to provide variety. The density of chests is configurable. Custom potions, magic items, and armor. The heads of legendary adventurers.

  • Places mob spawners throughout the dungeon. These will likely be near chests, but not always. Mob types are configurable. The density of spawners is configurable. Some 'non-standard' mobs are available. Custom mob spawners can be created with an NBT editor.

  • Optional in-game maps of dungeons.

  • Random placement of secret traps and puzzles.

  • Output floor maps to a terminal with color on ANSI systems.

  • Output entire dungeon maps to HTML.


  • More room, hall, floor, feature, and ruin types.
  • More traps!
  • Harder hard mode!
  • More stuff as Minecraft evolves!


The stand-alone versions for Windows and OS X, include a "launcher" script that will run in interactive mode. For advanced usage, run the mcdungeon executable from the command line like the python version.

List available subcommands and options:

   $ python mcdungeon.py --help
   $ ./mcdungeon --help

Help on a specific subcommand:

   $ python mcdungeon.py <subcommand> --help
   $ ./mcdungeon <subcommand> --help


  • Python 2.7
  • Numpy


These also work for the stand-alone version. Just replace "python mcdungeon.py" with "mcdungeon"

   $ python mcdungeon.py interactive

Run in interactive mode. From here you can add, list, delete or regenerate dungeons.

   $ python mcdungeon.py add Dungeon 5 4 3 --term 1

Load a world named 'Dungeon', generate a 5x4x3 dungeon layout (5 rooms E/W, 4 rooms N/S, and 3 levels deep) and display the results in a terminal window. (In color on ANSI terminals only. Sorry Windows) The world files will not be modified, but are required. Basically a "dry run."

   $ python mcdungeon.py add Dungeon 4-6 4-6 5-8 -n 5 --write

Generate five random dungeons between the sizes of 4x4x5 and 6x6x8 and save them to the world.


Several example configs are included. These can be copied and/or modifed to suit your own tastes.

  • default.cfg

    A little of everything. This one is heavily commented. If you want to know what a config option does, look here.

  • more_mobs.cfg

    This produces maps that are the same as the default, but with more types of monsters and more spawners.

  • caverns.cfg

    Mostly cavern type rooms. Very few "dungeon" looking rooms except the treasure chambers. It's a bit like exploring caves with the occasional dungeon room.

  • maze.cfg

    Basically bumps up the number of corridor type rooms and the number of loops the dungeon layout has. You'll end up with fewer rooms and lots of twisty halls to get lost in.

  • easy_mode.cfg

    Better treasure, fewer monsters and traps. Easier dungeon layout (very linear) and maps of every level.

  • hard_mode.cfg

    Less treasure in upper levels, more confusing dungeon layout (lots of loops) more monster spawners. Hidden spawners. Creepers are more common. Buffed monster spawners. No maps. It also fills in all the surrounding underground caves so that monsters spawn inside the dungeon much more frequently. No exit portals.


Thanks to the following for their code, interest, inspiration, and great ideas! (in no particular order)

BeeTLe BeTHLeHeM, codewarrior, Link1999, SoNick, Commander Keen, Yelik, NoiGren, whoiscraig, ChocolateySyrup, Sevminer, AnderZ EL, SuddenLee, Silre, NuclearDemon, bking1138, BarthVader, koredozo, janxious, compgurusteve, Meindratheal, ChosenLama, JiFish, djchrisblue, sshipway, denemanow.