Dungeon Rooms

Procedurally generated dungeons are built using rooms. They consist of a schematic and a set of configurable options. This article will explore some details on setting up a room.

Basic Options

Weight
This is the likelihood of this room being selected during generation. The higher the weight, the more likely this room will generate.

This is relative to the other rooms in this dungeon, so if all rooms have a weight of 5, they'll be equally likely to spawn. But if one room has a weight of 1, it'll be far less likely to spawn than the others.

Spawn Point
This is where the players will spawn if this room is selected as the starting room of the dungeon. The dungeon will ONLY use rooms with a spawn point configure when choosing a starting room.

• Right-click sets the spawn point, or clears it if the block you're looking at is already the spawn point
• Left-click sets the facing direction

A spawn point set in-game is not registered as a start room until the dungeon is reloaded, so run /md reload <dungeon> after saving, or the generator will report that your dungeon has no spawn rooms.

A room is only eligible as the starting room if its Generation Depth minimum is 0. Among the eligible rooms, the odds of being chosen are the room's weight multiplied by its minimum Generation Limit plus one, so a room that must appear at least twice is three times as likely to start the dungeon as an equally weighted room with no minimum.

If you don't have any rooms with a spawn point, the dungeon will choose from any of the valid rooms and try to find a safe spawn point, but this is ill-advised as the player could be placed in an unsafe or trapped position!

Room Rules

Allowed Rooms
This is a whitelist that lets you control what rooms can generate attached to this one. It opens a UI that lets you add and remove rooms from a list. You can also configure how likely a room is to be generated next to this one.

The Add Room button closes the menu and asks you to type the name of the room you want to whitelist. The name must be a room in this dungeon, and it may only contain letters and numbers. If no room in this dungeon has that name, nothing is added and no message is shown.

The Allowed Rooms section further down covers how the whitelist is applied during generation.

Generation Limits
This controls how many times a room is allowed to appear in a dungeon. It supports ranged values so you can require a room appear at least a certain number of times, while also preventing it from appearing TOO many times. Here are some example values:

• 0-3 - There will be anywhere from 0 to 3 instances of this room in the dungeon.
• 1 - The room will ONLY generate once. Useful for loot and exit rooms!
• 2+ - The room must generate AT LEAST twice, and is allowed to generate more.

Ranges also accept >=2, >2, <=5, <5 and 2 to 5.

A maximum of 0 means unlimited, not zero. To stop a room from generating, remove its connectors or take it off every whitelist.

Generation Depth
This controls how far into the dungeon the room can generate, counted as the number of rooms along the connector chain from the starting room. The starting room is depth 1. Note that this is not the same as the total number of rooms in the dungeon, since branches inherit the depth of the room they grow out of. Ranges work the same as the Generation Limits. Here are some examples:

• 0-15 - This room can only generate within 15 rooms of the start.
• 10-20 - This room can only generate between 10 and 20 rooms from the start (inclusively).
• 12+ - This room isn't allowed to generate until at least 12 rooms from the start.

A room can only be picked as the starting room when its depth minimum is 0.
A maximum depth of 0 means the room can never be attached to another room. It can still be used as the starting room if it has a spawn point.

The Room Tool

Editing rooms uses the room tool, a golden axe by default (General.RoomEditorItem in config.yml). You get one automatically when entering edit mode of a procedural dungeon, or with /md roomtool (which needs dungeons.functioneditor). Using the tool itself needs the dungeons.roomeditor permission.

Creating a room

• Left-click a block to set corner 1
• Right-click a block to set corner 2
• Type the room's name in chat. Names may only contain letters and numbers.

Editing a room
Right-click an existing room with the tool to select it and open the room menu.

While editing, a hologram above each room shows its name, Count, Weight and Depth, and a second marker sits on the room's spawn point if it has one.

Connectors and Doors

Connectors must sit on the edge of a room. Each one carries its own Allowed Rooms whitelist, and in MINECRAFTY dungeons a Connector Use Chance (default 50%). Connectors can be copied, cut and pasted between positions.

Every connector has a door, which is just a group of blocks you mark inside the room:

Connectors with no room attached keep their door blocks in place, which is how you wall off unused exits with your own build instead of the surrounding block.

Allowed Rooms

The whitelist is mutual. If room A whitelists room B, B still has to allow A when B has its own whitelist.

By default a room can connect to every other room in the dungeon except itself. Adding a room to its own Allowed Rooms list is not enough to change that: to let a room chain into another copy of itself, open the connector it should chain through and add the room to that connector's Allowed Rooms list.

In the whitelist menu, left and shift-left click add 1 and 5 weight, right and shift-right subtract 1 and 5, and clicking a slot while holding an item changes that entry's icon. Weight never goes below 0.

Blacklists exist in the room's YAML (Config.Blacklist) and are honoured during generation, but there is currently no menu for editing them.

Configuration File

All rooms have their own configuration file in the rooms folder of your map, plus a .struct file holding the captured blocks, biomes and entities. Everything found in the YAML can be modified in-game, but you may also edit it directly. Note that if you modify the config file, you need to reload the dungeon with /md reload [dungeon] or /md reload all!!

Older rooms using Config.MinOccurrences, Config.MaxOccurrences, Config.MinDepth and Config.MaxDepth are converted to the range format automatically the first time they load, and the old keys are removed.

Room rules are held in memory and written when the dungeon is saved, so use /md save or leave edit mode normally after changing them. Setting or clearing a spawn point writes the file immediately.