Configuration Reference¶

[dungeon]¶

This section holds some basic parameters for the dungeon.

loops

This is the percentage of loops in the dungeon. At 0%, each level of the dungeon will be nearly linear, with a few branches, but never any loops. At 100% you will basically get a grid with every room connected all of its neighbors. For best results, keep this < 30%. Note that certain room types (rooms larger than 1 tile) will also affect the number of possible loops in a level.

min_dist

Minimum distance (in chunks) from the spawn chunk for the automatic placement algorithm.

max_dist

Maximum distance (in chunks) from the spawn chunk. The actual max distance will be the minimum of this value or the edge of the world.

maximize_distance

(True or False) This will attempt to place multiple dungeons as far away from each other as possible given the min/max values above. Setting this to False will ignore distances between dungeons when selecting a location, and give a higher probability of two dungeons appearing right next to each other.

offset

(X, Y, Z) Provide a location offset in blocks for the NW corner of the dungeon. If set, the dungeon will not be buried, but will be rendered at the coordinates you specify.

See also

--offset

force_bury

(True or False) Attempt to calculate Y when using offset.

See also

--force-bury

tower

For tower type entrances, this is the extra hight of the tower in blocks.

ruin_ruins

(True or False) Setting this to False will turn off any attempt to ruin towers and surface buildings.

doors

Percentage of doors to be placed.

torches_top

torches_bottom

Percentage of torches to be placed on a level. The frequency of torches will be scaled between torches_top and torches_bottom from the top level of the dungeon to the bottom.

torches_position

Position of torches on the walls. 1=low, 2=middle, 3=high

chests

This is the density of chests per 10 rooms per level, rounded up. For example, a value of 2 will place five chests per level in a 5x5 dungeon. (25 rooms, 2 chests per 10 = 5 chests) 1 would place three chests per level in a 5x5 dungeon.

double_treasure

(True or False) When set to True, places two max tier chests in treasure rooms, instead of one. Good for harder dungeons being raided by a group of adventurers.

enchant_system

The enchant system decides which kind of enchantments can appear on which kind of items. (magic_items.txt excluded.)

Possible values are:

• table+book

  All legal enchants achieved with an enchanting table or an anvil with enchanted books.

• table

  Only enchants that can be achieved with an enchanting table.

• extended

  As table+book, but weapon enchantments (Sharpness, Smite, Bane of Arthropods, Knockback, Fire Aspect, Looting) can also appear on pickaxes, shovels and axes.

• zistonian

  As Extended, but weapon enchantments can appear on any item that is not normally enchantable. e.g. Signs. This allows the creation of “Zistonian Battle Sign” type items.

  Warning

  Because these do not lose durability when you attack, this is considered extremely overpowered.

• anything

  Complete madness: any enchantment can appear on any item. You probably don’t want to use this value.

spawners

Density of random monster spawners placed 10 rooms per level. This works like chests.

hidden_spawners

(True or False) Hide the randomized spawners behind walls. This will not affect any extra spawners placed by room features or treasure rooms.

SpawnCount

SpawnMaxNearbyEntities

SpawnMinDelay

SpawnMaxDelay

SpawnRequiredPlayerRange

Custom spawner settings. These values will be used for all spawners but can be overridden by values in the YAML file, if provided. The example settings are the defaults. (Uncomment to change.) For more information see: Spawning_behavior

treasure_SpawnCount

treasure_SpawnMaxNearbyEntities

treasure_SpawnMinDelay

treasure_SpawnMaxDelay

treasure_SpawnRequiredPlayerRange

Treasure Room spawner settings. As above, but only applies to spawners in the final treasure room.

fill_caves

(True or False) Fill caves will fill in caves under and around the dungeon in an attempt to concentrate random monster spawns inside the dungeon. In most cases this will result in many more random mobs spawning inside the dungeon.

Warning

Using this will make your dungeons take up a lot more surface area. You won’t be able to place as many dungeons, and in small areas maybe none at all. If you have this turned on, and are unable to place any dungeons, try turning this off.

exit_portal

(True or False) Setting this to true will create a teleporter in the treasure room that will teleport a player to the surface. Works in vanilla Minecraft with command blocks.

Note

You must have command blocks turned on for this to work!

structures

Player structure detection. This is a list of blocks that are considered to be player structures. Any chunks that contain these types of blocks will be excluded from the location algorithm. By default, these are essentially light sources. The thought being that any structures you care about will be lit.

This list will shortcut at the first match, (ie: once a block matches, we won’t bother checking the rest) so for maximum efficiency, order this by most common blocks first. The more blocks you list here the slower the initial terrain pass will be.

These names should match the names in materials.cfg. To disable this feature, just leave this blank.

Example:

structures: Torch, Glass, Wooden Door

Warning

If you change this, you need to delete the chunk cache in your world maps folder. Delete the “mcdungeon_cache” in your world folder if it exists.

river_biomes

This controls whether or not a chunk is excluded from dungeons placement due to its biome content. River_biomes will exclude a chunk if it is more than 20% composed of a listed biome ID. If you want to turn this feature off just set this to -1.

Example, count river and frozen river biomes as river biomes.

river_biomes: 7, 11

Warning

If you change this, you need to delete the chunk cache in your world maps folder. Delete the “mcdungeon_cache” in your world folder if it exists.

use_incomplete_chunks

(True or False) Defaults to False. Change this option to True to force mcdungeon include incomplete chunks in dungeon placement. These chunks are normally excluded because they can cause unexpected results, even crashing MCDungeon. It is included as an option because some map generation methods may not properly mark chunks as complete. Use only as a last resort.

Warning

If you change this, you need to delete the chunk cache in your world maps folder. Delete the “mcdungeon_cache” in your world folder if it exists.

ocean_biomes

This controls whether or not a chunk is excluded from dungeons placement due to its biome content. Ocean_biomes will exclude a chunk if the most common biome in the chunk is one of the listed biome IDs. If you want to turn this feature off just set this to -1.

Example, count ocean, deep ocean, and frozen ocean.

ocean_biomes: 0, 10, 24

Warning

If you change this, you need to delete the chunk cache in your world maps folder. Delete the “mcdungeon_cache” in your world folder if it exists.

secret_rooms

Percent of secret room that will be generated (0 - 100). Secret rooms have quite a few restrictions, so set this high if you want to see them. In general they will only appear in 1x1x1 rooms that have one hallway connected. If you set loops high, you’ll get fewer secret rooms because you will have fewer rooms that are dead ends.

maps

This is the percent chance a map will be generated for a level. The map will be placed in a random chest on an upper level (if one exists).

mapcolor

When the above map items are generated, the item sprite will have scrawlings of this color. Give a hex RGB value.

paintingcolor

As above, but for paintings items.

See also

Custom Paintings

mapstore

mapstore will provide an alternate world in which to store your dungeon maps. If you’re playing vanilla, don’t worry about this. If you’re using Bukkit with multiple worlds (like multiverse) set this to the name of your primary world. This can also be set on the command line, or in interactive mode.

See also

--mapstore

wall

secret_door

floor

subfloor

These set the materials to be used for various surfaces. You can choose most block names in materials.cfg or some special “meta materials” that offer more variable blocks.

meta material	description
meta_mossycobble	Cobblestone with veins of moss.
meta_mossystonebrick	Stone bricks with random cracks and veins of moss.
meta_stonedungeon	Changes as you go deeper. Starts as something like mossy stone bricks and turns to cobble and mossy cobble as levels get deeper.
meta_decoratedsandstone	Mostly regular sandstone with random smooth stones and horizontal bands of “chiseled” sandstone.
meta_decoratedredsandstone	As above, but using the red sandstone variant.

chest_traps

Percent change chests will be trapped. See [chest traps]

skeleton_balconies

Skeleton balconies appear in tall circular pit rooms. This is the percent chance a balcony will appear if the conditions are right. These only appear in pit rooms that are >= 3 deep and have exactly two adjacent halls. If your dungeon is less than four levels, you will not see these.

sand_traps

This is the chance certain pit rooms will be rigged with falling sand traps. There are a number of restrictions on which rooms can contain these, so setting this fairly high will still result in relatively few rooms depending on your config file. To contain a sand trap a pit room must be > 1 level high, and only the top most level in a pit can contain a sand trap.

silverfish

This is the percent chance any stone, cobblestone, or stone brick block will be replaced with a silverfish equivalent. You can use this to discourage tunneling through walls and floors (if your walls and floors are mode of stone, cobblestone, or brick)

Dungeon Features¶

These sections control the probability of a particular feature showing up in the algorithm. Each name is followed by a weight that determines the probability that feature will be chosen relative to the others in the list. These numbers do NOT need to add up to 100. They are only relative to each other. For example, a weight of 40 is twice as likely to be chosen as a weight of 20. These numbers are also not hard, they simply weight the probability of the randomizer. A very low weight may still occasionally be chosen more than a high weight, it’s just unlikely. A weight of zero means that feature will never be chosen.

For example, here Basic will appear about about 25%, Square 25%, and Round 50%

[rooms]
Basic: 5
Square: 5
Round: 10

[entrances.biomeid,biomeid,...]

Splash Potion of Poison: ThrownPotion,5,Potion:{id:"minecraft:splash_potion",tag:{Potion:"minecraft:poison"}}

Item: weight, number

TNT: 10, 1

Item Name(s): chance to appear, min-max, enchantment

Torch: 100,5-20

Iron Sword,Gold Sword,Diamond Sword: 50,1,20

Stone Pickaxe: 20,1,level*3.5

magic_Ulfberht,magic_Durendal,magic_Caladbolg: 20,1,0

[treasure hunt]¶

The treasure hunt section holds configuration parameters for the treasure hunts feature.

locked

Whether or not to lock the final chest.

intermediate

A percentage chance of an additional clue chest being placed at each landmark step. This chest is concealed. This would mean that, rather than all the clues being in the book from the initial chest, half of them are in the intermediate chest and the first book gives clues only on how to find this intermediate chest. If this is 0, then the first clue book takes you all the way to the end. If this is 100, then the clue book only takes you to the next landmark, where you find another book, which takes you to the subsequent landmark, and so on. If locked=true then these intermediate chests are also locked with the same key.

bonus

Percent chance of an extra treasure chest being placed at intermediate way points. This uses the multiplier as below, and is not concealed.

multiplier

This is the number of way points per loot tier, used for bonus chests and for the final chest. So, if this is 1, then a 4-step treasure hunt has a tier 4 loot chest. If it is 2, then you need a 8-step hunt to get tier 4 loot.

spawners

Whether or not to create random spawners at the landmarks.

[landmarks.biomeid,biomeid,...]

Books¶

Books can be added as loot by specifying Written Book in a loot table.

The books folder contains the data for written books. Whenever MCDungeon creates a written book as loot, a random text will be selected from this folder. If there are no files, a book and quill will be substituted.

The default books provided are public domain works sourced from Project Gutenberg

You may add your own books using the following guide:

• Books are simple text files. The file should use the ”.txt” extension.

• The first line is the author, The second the book title and then one line per page of the book.

• As in Minecraft, Books are limited to 256 characters per page and 50 pages per book. Any excess will not be loaded.

• IMPORTANT: It is not enough to just split the text every 256 characters. It is still possible for the text on a page to be too long which will make it look funny in Minecraft. The default texts were split using the help of the Multiplayer Book Paster Another option would be to input the text in to a book in Minecraft to check what works.

• The following escape characters can be used:

  • \n - Produces a new line
  • \s - Produces the section sign
  • \\ - Produces a backslash

  For information about using the section sign for formatting, see: Formatting Codes

• For the moment, only the following characters are supported:

  0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&\'()*+,-./:;<=>?@[\]^_`{|}~
  

  Other characters will be removed.

Custom Items¶

You can add custom items with YAML files. You can also use this to add some items from mods as loot.

The items folder contains the data for customised items. YAML files in this folder can be referenced in loot tables as file_[filename without extension] For example, head_notch.yaml would be referenced as file_head_notch. See default.cfg for more details.

Each custom item is an YAML file containing the nbt tags required to create the inventory item. You may add your own files by editing the defaults with a text editor, taking care to match nbt2yaml‘s format.

Items can be very simple, or potentially a very complex tree of values. The most simple example would be a single short tag, called id and containing the numerical id of the item.

For more information on the format of the tags see Item Structure

Packaged Items:

• Items starting with heads_ are the heads of some famous (and not so famous) minecrafters.
• Items starting with firework_ are various pre-created fireworks, some using rare crafting materials.
• Items starting with magic_box_ are various chest that already contain building materials when placed.

Custom Paintings¶

The paintings folder contains the data for custom paintings. Whenever MCDungeon creates a custom painting as loot, a random painting will be selected from this folder. If there are no files, a blank map will be substituted.

You can add them to your loot tables with the special item Custom Painting

The default paintings provided are public domain works sourced from Wikipedia. The font used for the Latin letters is Aldor’ath Serif.

There are also two custom made guides, one for brewing and one for building circles.

You may add your own paintings using the following guide:

• Paintings consist of two files: A “txt” file containing the painting’s title and lore text; and a “dat” file containing the actual image.
• In the txt file, the first line is the title and then one line per line of lore text.
• The dat file contains the map data in Minecraft’s format. You can convert images to, or create your own maps using a tool like ImageToMap You can also copy dat files directly from the data folder in a Minecraft world.

Custom Spawners¶

The spawners folder contains the data for custom spawners. YAML files in this folder can be referenced as spawner types in dungeon config files in [mobs] tags as file_[filename without extension] For example, Angrypig.yaml would be referenced as file_Angrypig. See default.cfg for more details.

Each custom spawner is an YAML file containing the nbt tags required to create the spawner object. You may add your own files by editing the defaults using a text editor, taking care to match nbt2yaml‘s format.

Spawners can be very simple, or potentially a very complex tree of values. The most simple example would be a single string tag, called EntityId and containing the EntityId of the mob you want to spawn. The Id, x, y and z tags are unnecessary as they are added by MCDungeon.

For more information on the format of the tags see:

• http://www.minecraftwiki.net/wiki/Chunk_format#Tile_Entity_Format
• http://www.minecraftwiki.net/wiki/Chunk_format#Mobs

Custom Shops¶

The shops folder contains the configuration files for villager shops. These are generated in the SecretShops type secret rooms.

Shops have a single [shop] section and then one or more [tradeX] sections, starting from [trade1], [trade2], etc. You can look in the existing trades to help you create your own, and refer to the below information.

In the shop section, the following values should be set:

Name This is the name of the shop, which will be displayed on signs. Maximum four words, which will appear one per line. Each shop keeper has a randomly generated name, you can use {{name}} (normal name) or {{name’s}} (possessive version) to substitute this in to the shop name. e.g. “{{name’s}} shop” becomes “Bob’s shop”

profession_ID ID number of the villager type. Also changes the colour scheme of the room. Farmer 0, Librarian 1, Priest 2, Blacksmith 3, Butcher 4, Nitwit 5

free_sample Item to put in the shop sign. Also acts as a freebie for the discovering adventurer. Just use an item name, e.g. Wood Sword

You can have as many trade sections as you like. Trades contain the following:

chance Percentage chance this trade will appear. 100 will cause the trade to always generate

max_uses The number of times this trade can be activated. This available trades will get refreshed when the villager levels up.

input The input item. (What the player pays.) See format below. input2 (optional) A secondary input item. Normally used for enchanting items etc. See format below. output The output item. (What the player receives) See format below. limited (optional) When True, this trade will never refresh. Use for items that should be very rare or unique.

Input/Output item format:

Item Name[/Item Name/...][,Item Count][,Enchant Levels]

Examples:

Emerald            # One Emerald
Emerald,10         # Ten Emeralds
Emerald/Diamond    # An Emerald or A Diamond
Wooden Sword,1,10  # An enchanted sword

You can use anything you would normally put in a loot table.

Dye Colors¶

dye_colors.txt allows you to define colors to be used for leather armor. The format is:

Name:color

Name

The name of the color.

color

The hex value of the color.

Dyed armour should be referenced as “<name> Leather <type>” in the loot tables.

Example:

Red Leather Chestplate

You can also use ‘Random’ as a color in loot tables to get a randomised dye color.

Example:

Random Leather Boots

Magic Items¶

magic_items.txt can be used to define enchanted items to be used in loot tables.

The format of this file is:

name:base item name,enchant-level,enchant-level...:lore:lore...

name

A unique name for this item. This is used to both reference the item in the loot tables, and is also the name in game.

base item name

The base item name from items.txt

enchant-level

The enchant code (see Enchanting) and enchant level. You can have multiple enchants.

lore

Lore text for the item. Lore text is limited to 50 characters per line and 10 lines. You can use \s to insert the section sign for text formatting.

Examples:

A golden sword with every legal enchantment and lore text:

Masamune:Gold Sword,16-5,17-5,18-5,19-2,20-2,21-3:Cosmic Blade Masamune.:Sharp.

Diving Helmet:

Diving Helmet:Orange Leather Helmet,5-3,6-1:An item from another world.

Enchanted book of Knockback 2:

Book of Knockback:Enchanted Book,19-2:Who's there?

Potions File¶

potions.txt can be used to define customised potions and arrows to be used in loot tables.

The format for potions with multiple effects is:

<name>,<effect id>-<level>-<duration>,<effect id>-<level>-<duration>...<,flag (optional)><,color (optional)>

The format for ‘basic’ potions with only one effect is:

<name>,<effect name><,flag (optional)>

name

For each entry in this file, FOUR items will be created using this name. referenced in loot tables. 1) The potion itself, 2) The splash version of the potion, prefixed by splash ``, 3) The tipped arrow version, with the suffix `` arrow and 4) The lingering version, prefixed by lingering ``. For example, ``Potion of XXX would also produce:

• Splash Potion of XXX
• Potion of XXX arrow
• Lingering Potion of XXX

effect id-level-duration

Effect ids and levels can be found on the minecraft wiki. (see Potion effect) Duration is the time of the effect in game ticks. (20 ticks = 1 second, 1200 ticks = 1 minute) You can have multipe effects.

effect name

The potion effect string. Values can be found on the minecraft wiki. (see Potion Data Values)

flag

The flag can be omitted. Use HIDE_EFFECTS to hide the potion effects in-game, HIDE_PARTICLES to hide the player particles after drinking, or HIDE_ALL to hide both. HIDE_PARTICLES does not work with ‘basic’ potions.

color

The color can be omitted. Otherwise use a hex color code that will determine the color of the potion/arrow etc.

Example:

A mysterious potion with hidden effects:

Potion of Wonder,8-0-1200,12-1-2400,3-2-600,HIDE_EFFECTS,28C3CC

A potion with a single visable effect:

Potion of Raw Chaos,8206,7-22-1

A basic potion:

Potion of Luck,minecraft:luck

Recipes File¶

recipes.txt contains a list of ids for all recipes in the game. When a knowledge book item is generated as loot, one of these will be picked at random. You may add recipes from your mods to this file.