Room Tutorial - dredmor-com/dungeons-of-dredmor GitHub Wiki

Here, you will learn about the basics of making rooms in Dungeons of Dredmor. As always, remember that the minimum setup is necessary for testing and seeing your changes: proper directory structure and minimal mod information.

1. So You Want to Make a Custom Room?
   1.1. Testing a Room
2. Basic Room 1: Floor Plans and Syntax
3. Basic Room 2: Breakable Walls, Blocker and Item Placement
   3.1. Breakable Walls
   3.2. Loot Tags
   3.3. Custom Blockers

Below are two examples about how to use the information on the Room System Reference page to create custom rooms which will spawn within the game.

To test a specific room, add a 'rooms.xml' file in your mod and boot the game with the argument: -debug-flag -testroom "[Room Name]" -x [X Position] -y [Y Position]. When you're using Steam, right click Dungeons of Dredmor, select Properties>General>Set Launch Options..., and paste the above code. Lastly, make sure you've activated your mod in the launcher, that [Room Name] exists in any rooms.xml and that you can spawn at [X Position][Y Position].

The next one is a very basic room implementation.

<room width="9" height="9" name="Basic Room">
    <row text="####D####"/>
    <row text="###...###"/>
    <row text="##.....##"/>
    <row text="#.......#"/>
    <row text="d.......d"/>
    <row text="#.......#"/>
    <row text="##..@..##"/>
    <row text="###...###"/>
    <row text="####D####"/>
    <flags minLevel="0" maxLevel="1"/>
</room>

The intent with the design of the room system was to make a representation in fixed width text as close to how the room would actually look as possible. Going through the symbols quickly using the Room System Reference, you can see that:

• The # symbols are walls.
• The D and d are doors, vertical and horizontal, respectively.
• The @ is a random "blocker". A blocker is somethiung like a candlestick, a rock or any other piece of debris that restricts movement through this space.

There are a few other components here that are absolutely required in order to not cause issues with the game.

• The <room> and </room> tags at the top and borrom of the room must exist as the first and last things in a room's definition.
• The <room> tag at the top must contain the width and height of the room. In this case, we can count 9 vertical lines from the top to the bottom of the room, and 9 columns.
• The <room> tag must include a name for the room, and it must be unique. This name will not be the random name assigned to the room in the game, but simply serves to identify it within the code.
• The room must have doors in order to be selected by the dungeon generator. Typically speaking, themore doors the room has, the higher the chances of it being included.
• Finally, the <flags> tag just before the end is required if the room is to be selected by the dungeon generator, as a minlevel and maxlevel must be set. A value of 0 represents the starting floor, where a velue of 15 allows the room to be spawned on the lowest dungeon floor.

Below is a snippet of the XML from rooms.xml within the game folder.

<room width="9" height="10" name="Magic Library">
    <row text="#########"/>
    <row text="#4###P###"/>
    <row text="#!##...##"/>
    <row text="#!.....##"/>
    <row text="#.......#"/>
    <row text="d.^1235.d"/>
    <row text="#.......#"/>
    <row text="##..@..##"/>
    <row text="###...###"/>
    <row text="####D####"/>
    <flags minLevel="0" maxLevel="1" noblockers="1" special="1"/>
    <element type="bookshelf" at="1" />
    <loot type="wand" at="4"/>
 
    <customblocker name="Dusty Bookcase" x="2" y="3" png="dungeon/shelfB0.png" 
    description="The shelves are covered with trash and dubious-looking stains."/>
    <customblocker name="Old Shelves" at="2" png="dungeon/shelfA0.png" 
    description="On these shelves there's an old shopping list and a glass of milk someone left out for a couple decades."/>
    <customblocker name="Dirty Bookshelf" at="3" png="dungeon/shelfB1.png" 
    description="Nothing of value remains, it's mostly just ticket stubs, trashy fanfic, and pull-tabs."/>
    <customblocker name="Ancient-looking Shelving Unit" at="5" png="dungeon/shelfA1.png" 
    description="There are strange outlines in the dust covering this shelf. Something was recently moved but you have no idea what it could have been."/>
    <!--<customblocker name="Some Kind of Rack" x="6" y="5" png="dungeon/weapon_rack.png" 
    description="It looks nice, if a bit lonely." percent="50"/>-->
    <loot type="potion" x="4" y="2" percent="75" />
</room>

The Magic Library is one of the rooms that exists within the core game. It's very similar to the basic room described above in terms of size and shape, but has some more sophisticated XML included.

First, notice that the room itself is a bit different. There's a 4 in the top left corner and below, some ! symbols. The 4 is a reference location, most easily described as a standard floor tile that can be used as a location for things sich as customblocker objects. The ! symbols are breakable walls. The intent here, of course, being that, by breaking the walls, you may access whatever is hidden at space 4. Below the <flags> tag, we see a <loot> tag which references location 4 for placing a wand.

Loot tags can be placed anywhere within a room entry below <room...> and above </room>, and require either a reference location with at or the desired X and Y locations of the object, as mentioned in the loot section of the Room System Reference. There are additional attributes that may be set within the loot tag, such as the type or the percentage chance that they will appear.

There are two loot tags in this room. The first, just below the room layout, describes the placement of a wand and uses the at tag to define its location, in this case, at position 4 of the layout. The other loot tag is second from the bottom and uses the alternative method of defining its location: definition of x and y coordinates. Referencing the X and Y position should be considered the default mechanism for placement, whereas the at variables like 4 are used as shorthand whenever it's simpler.

Below the first loot tag are a number of [customblocker] tags, describing (in this case) various bookshelves. The only required attributes for a custom blocker tag are the location (either with at or x and y), and the image PNG file. Since this room was themed to look like an old library, we decided to stuff it with some images of old bookcases. Note that the syntax uses a forward slash instead of a backslask, unlike typical Windows paths, and the base directory it looks in is the base game directory; for Steam users running Windows 7, this will be C:\Program Files (x86)\Steam\steamapps\common\dungeons of dredmor\dungeon.

Lastly, there is a custom blocker tag named "Some Kind of Rack" that has been "commented out" by placing <!-- at the beginning and --> at the end. Commenting out a tag object causes it to be completely ignored by the game. Tags or even whole rooms can be commented out, making this tool very good for debugging your XML. It is worth noting, however, that having one set of commenting brackets inside another can cause problems, so this should be avoided.