Room System Reference - dredmor-com/dungeons-of-dredmor GitHub Wiki

This page will inform you about the ins and outs of room creation in Dungeons of Dredmor. There's quite the amount of events, so fasten your seatbelt.

1. Basic Syntax
   1.1. Room Map
   1.2. Room Flags
2. Room Object Records
   2.1. clock
   2.2. customblocker
   2.3. custombreakable
   2.4. customengraving
   2.5. element
   2.6. horde
   2.7. lever
   2.8. loot
   2.9. monster
   2.10. pedestal
   2.11. trap
3. Room Script Conditions
   3.1. activated
   3.2. activated_changed
   3.3. at
   3.4. entered
   3.5. event
   3.6. exited
   3.7. isalive
   3.8. isdead
   3.9. started
   3.10. stopped
4. Room Script Actions
   4.1. create
   4.2. move
   4.3. remove
   4.4. set
   4.5. spell
   4.6. trigger

All rooms start with an entry similar to this: <room width="11" height="21" name="My cool room"> And is closed with a </room> line. In between those entries, you'll place an ascii map of the room, your codes for objects and spawns, and any scripts the room runs.

The width and height are defined in number of tiles in-game, which also correspond to number of characters in the room map for width, and number of rows in the room map for height. The count here includes the first character and first row, which is important to nite because the coordinate system in the room map itself doesn't include the first ones and thus starts at 0,0.

Room name is mostly irrelevant, and used only for seeds in branchDB and for debugging purposes. DoD 1.0.8 had several rooms with the same name, but didn't seem to be particularily bothered by it.

Symbol	In-game representation
#	Wall
.	Floor
W	Water
L	Lava
I	Ice
G	Goo
D	Door (Up/Down). (This designates the center of the door.)
d	Door (Left/Right). (This designates the center of the door).
S	Shopkeeper
s	Shopkeeper Block Area. This is used like a door and a shop must be built as if it's a room within the room.
!	Destructible Wall
X	Impassable tile
	Empty space outside teh room. (Used for non-rectangular rooms.)
P	Wall, plus a random Painting or Tapestry (note, will not always be placed).
@	Random Blocker (note, will not always be placed).
^	Random Floor Decoration (note, will not always be placed).
i	Sales pedestal (only for use within stores).

The above symbols are used basically to draw a map of the room, where # symbols are walls, and so on, as explained in the chart. A few important twists and turns you should know about:

• W, L, I and G usually correspond to Water, Lava, Ice and Goo, respectively, but not always. Individual floors can override them. If you use W in a room, for example, it will show up as Water on the first floor, but as Ice on the frozen level. IIRC, that's set up in branchDB.xml.
• P, @ and ^ will often lie dormant and not do anything. If "P" is dominant, it will appear (and function= as just a normal wall. The others appear as empty floor when dormant. They are triggered by random name of the room. In text.xml, you can associate PNG files with specific words. If those words end up in the name of the room, they will cause the associated image to spawn in that position. So if you're in "the Chapel of Cake", you'll find a cake statue where the @ is and a framed painting of a cake where the "P" is.
• X makes an impassable tile that looks like normal dungeon floor. It's mainly used when plscing a customblocker that's 2-tiles high and supposed to represent a north-south running object (such as a north-south coffin or sarcophagus). It prevents the player from walking through the second space. It can also be used to make invisible walls, but that's evil and totally happening in Interior Dredmorating 2.0. You read it here first.
• S, s and i are all Brax-related. "S" is where he stands normally. "s" is where he moves when you pick up an object from a sales pedestal. All the shops in the main game feature the following customengraving with the x and y coordinates set to match the "S" space: <customengraving name="Small Carpet" x="8" y="6" passable="1" png="dungeon/rug_small.spr"/>. Be careful when placing Brax. Ideally, there should not be a straight line of "."s between Brax and the door. Otherwise, you run the risk of a gargoyle (or other wall-based) trap spawning outside the hsop and causing the gargoyle head to spawn in line with Brax. If this happens, a random monster stepping on the trap will injure Brax and make him hostile to the player.
• The x and y coordinates of objects (see below) placed in the room reference the room map. The upper left corner is x="0" y="0". Each point of x value indicates one space further right/east. Each point of y value increments one space further down/south.
• In addition to the symbols mentioned above, the digits 0 to 9 may be placed on the map. These must be defined later in the room block, and can be used with the at= tag to place objects in liew of using x= and y=. If you leave them undefined, the game will default to placing walls at the places on the map marked by numbers. If you're testing a room and you find a wall where there isn't supposed to be one, that probably means you vailed to define a number or at= entry.
• Whenever possible, all walls should be two tiles high. If you're going to place one "#", there should be another of the same symbol directly above or below it. This is to leep the dungeon looking uniform and to prevent the player from seeing diagonally through the walls into other rooms. Ideally, the only places where a "#" appears without another directly above or below it is on the two spaces horizontally adjacent to a "D".

These are contained within a data section marked <flags/>. Most room flags are boolean data, where 0 is false and 1 is true. In most cases, you need only put the flag if the value is 1. Any flag not listed for the room defaults to 0.

Flag	Arguments	Description
special	boolean, optional	Set to 1 to prevent the room from spawning more than once per floor.
nomonsters	boolean, optional	Set to 1 to prevent the monsters from being in the room when the door is first opened.
notraps	boolean, optional	Set to 1 to prevent traps from spawning in the room.
notreasure	boolean, optional	Set to 1 to prevent loot from spawning in the room.
noblockers	boolean, optional	Set to 1o to prevent vending machines, uberchests, ets from spawning in the room. Used to make sure narrow passaged don't get obstructed.
minLevel	integer	Defines the earliest dungeon floor this room can start appearing on. The floor the player spawns on in a new game is "0", despite common sense making you think that would be floor 1. In general, all level numbers are 1 less than what you probably expect them to be.
maxLevel	integer	Defines the deepest dungeon level this room can appear in. See notes on minLevel.
shop	boolean, optional	Set to one to make the room a shop. See below.
zoo	boolean, optional	Set to one to make the room a zoo. See below.

A few things you need to know:

• Nomonsters, notraps, notreasure and noblockers all misbehave sometimes. They're about 98% effective, but will surprise you from time to time by just getting skipped when the level is generated, and there's nothing you can do about it. Your very clean and spartan room will, from time to time, be packed to the gills with traps and loot. Learn to live with it.
• The special="1" flag sometimes misbehaves as well. When it does, it causes the room to spawn twice on a single level. This is rare.
• Shops have some special rules. You'll need an "S", an "s" and multiple "i" entrues on the room map to tell the game where to spawn Brax and his loot. Never put monsters in a room with Brax. It has been demonstrated that putting the <monster> or <horde> command inside a shop will sometimes cause Brax to glitch out, randomly grow hostile, look like another monster or completely vanish. It's uncontrollable, and sometimes causes the items and shop pedestals to vanish as well.
• Zoos turn the entire rectangular area defined by the map and height and width tags into a giant zoo. Every "." space inside that area will have a high chance of generating a monster. All "." and " " tiles within the map space will be revealed when the player first vains line-of-sight to any of them. Oddly-shaped zoos tend to misbehave. It is strongly recommended that all zoos have a rectangular outer border, otherwise you'll get crazy bugs and ripple effects.
• Remember, the floor the player starts on in a new game is numbered "0", not "1", but only in rooms.xml. The first floor uses rooms with minLevel="0", but monsters with level="1" and items with quality="1". Go figure.

This section details all the nifty objects you can put in a room, from vending machines and treasure to teleport levers and diggle gods.

Clock creates an object which displays next to the ticker each turn based on how many turns remain and then stops itself when it reaches 0, which can be checked for in scripts. The animation of the sprite has no bearing on which turn it is.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).
description	string, optional	the long description of this object (shown in tooltips).
passable	boolean, optional	set to 1 if the player can walk over this object, 0 if not.
visblock	boolean, optional	set to 1 if this object blocks the player's visibility, 0 if not.
png	sprite, required	sprite to show for this custom object. You may use either of the options presented.
pngSprite pngFirst pngNum pngRate (sometimes) pngAnimate
initial	integer, required	the number of ticks on the clock face initially.
remaining	integer, optional	the number of ticks on the clock face remaining (default is same as initial).
started	boolean, optional	set to 1 if the lever should be started and counting down to 0, 0 if not (default is 1 meaning clock is not started).

Creates objects that restrict movement and sometimes line of sight.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).
description	string, optional	the long description of this object (shown in tooltips).
passable	boolean, optional	set to 1 if the player can walk over this object, 0 if not.
visblock	boolean, optional	set to 1 if this object blocks the player's visibility, 0 if not.
png	sprite, required	sprite to show for this custom object. You may use either of the options presented.
pngSprite pngFirst pngNum pngRate (sometimes) pngAnimate

Creates items that block movement, but can be broken apart by attacking them.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).
description	string, optional	the long description of this object (shown in tooltips).
passable	boolean, optional	set to 1 if the player can walk over this object, 0 if not.
visblock	boolean, optional	set to 1 if this object blocks the player's visibility, 0 if not.
png	sprite, required	sprite to show for this custom object. You may use either of the options presented.
pngSprite pngFirst pngNum pngRate (sometimes) pngAnimate
hitsNeededToBreak	integer, optional	how many hits are needed to break this custombreakable (default is 0).
hitsTaken	integer, optional	how many hits has this custombreakable already taken (default is 0)
breaking	sprite, optional	sprite to show immediately after this custombreakable has been broken. You may use either of the options presented.
breakingSprite breakingFirst breakingNum breakingRate (sometimes) breakingAnimate
broken	sprite, required	sprite to show after this custombreakable has been broken. You may use either of the options presented.
brokenSprite brokenFirst brokenNum brokenRate (sometimes) brokenAnimate

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).
description	string, optional	the long description of this object (shown in tooltips).
passable	boolean, optional	set to 1 if the player can walk over this object, 0 if not.
visblock	boolean, optional	set to 1 if this object blocks the player's visibility, 0 if not.
png	sprite, required	sprite to show for this custom object. You may use either of the options presented.
pngSprite pngFirst pngNum pngRate (sometimes) pngAnimate

As of DoD 1.0.10, the name and description of customengravings never display, not even on mouse-over.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
type	string, required	the type of element to be created, currently one of: bookshelf (can set contents to the name of an item as it appears in itemDB.xml, for example contents="Copper Bolt"). lever (mostly used to control scripts). lutefiskstatue portal (this spawns a mysterious portal. It will only work if the player has ROTDG installed). anvil (Krong) statue (Inconsequentia) dredmorstatue (XP when broken) evilchest freezer bbq fountain craftvending foodvending boltvending drinkvending throwvending dirt
contents	string, optional	the name of an item as it appears in itemDB.xml, for example contents="Copper Bolt". Only valid for type="bookshelf".

Horde creates a small group of monsters of the same type. They're given a random regiment name. One monster is designated the leader and recolored. If the leader dies, this sometimes causes the other monsters to flee (depends on monster AI settings, as well as situation).

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).
min	integer, optional	the minimum number of monsters that will appear in the horde (default taken from minimum horde size in tweakDB.xml).
additional	integer, optional	up to this many additional monsters will appear in the horde (default taken from additional horde size in tweakDB.xml).

Supposedly, min sets the minimum nuymber of monsters in the horde, and additional sets the maximum that could be added to the minimum with the game selecting a random number within the range of min to min+additional. However, tests (using DoD 1.0.9) with min="1" and additional="0" resulted in a horde of 4 or 5, so something's not working as advertised (or additional="0" is bugged, perhaps?)

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
activated	boolean, optional	set to 1 if the lever should be activated, 0 if not (default is 0).

You must define via script what the lever does. This is not how the game makes those levers that open little treasure rooms.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
amount	integer, optional	the number of loot to create.
type	string	the type of loot to create. A list of valid types can be found on Item Types: Loot Types.
subtype	string optional	the name of an item as it appears in itemDB.xml, for example, subtype="Copper Ingot".
artifact	boolean, optional	set to 1 if the loot should be an artifact, 0 if not.

Type="potion" and type="wand" are notorious for sometimes disregarding the special="1" tags on the items they call.

Creates a single monster.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).

This creates a book on a stand. When you click on the bookk, a window pops open to display text. An example would be the "tome of fire or ice" room, or the Emergency Dungeon Warning System in YHTNTEP.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, required	the short name of this object (shown, for example, in tooltips).
text	string, required	the text to be displayed to the player when this pedestal is clicked.

Creates a trap at the specified location.

Tag	Argument	Description
at	point, required	Tile at (X,Y) where the game object will be created. You may use either of these two.
'x' and 'y'	integers, required
percent	integer, optional	percent chance this item will appear in the dungeon (default is 100).
can_push	integer, optional	set to 1 if the player can push this game object around the dungeon, 0 if not.
id	string, optional	string label uniquely identiying this game object within the current room.
name	string, optional	the short name of this object (shown, for example, in tooltips).

If you name a trap that uses a wall-mounted launcher, the at= or x= y= will dictate where the trigger mechanism spawns. The launcher will appear on the first wall or breakable wall in a straight line north of the trigger. Note that if it spawns on a "!" wall it will make it very difficult for the player to access whatever is behind that breakable wall.

True if the specified lever has activation state equal to activated.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). In this case, the condition would check that the lever is not activated.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".
activated	boolean, optional	the activation state to compare the lever's current activation state to 1 (activated) or 0 (de-activated).

True if the specified lever had its activation state changed to activated this game tick.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). In this case, the condition would check that the lever has not changed right now (very niche use).
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="1".
activated	integer, optional	the activation state to compare the lever's new activation state to 1 (activated) or 0 (de-activated).

True if the specified game object has the given tile (X,Y).

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). In this case, the condition would check that the object is not at those coordinates.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".
at	point, required	the tile (X,Y) to compare the game object's tile (X,Y) to. You may use either of the options.
X and Y	integers, required

True if the player entered this room this game tick.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). In this case, the condition would check that the player had not just entered the room - very unlikely you'd want to test this.

True if the specified event was triggered by the specified game object on this game tick.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). In this case, the condition would check that the event has not been just triggered.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".
event_type	string, required	the triggered event. Currently, hit (for custombreakable game objects), broken (for custombreakable game objects) are supported.

True if the player exited this room this game tick.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). In this case, the condition would check that the player has not just left the room - very unlikely you'd want to test this.

True if the specified monster is alive.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). For example, <isalive id="monster" not="1"/> is equivalent to <isdead id="monster"/>.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".

True if the specified monster is dead.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). For example, <isdead id="monster" not="1"/> is equivalent to <isalive id="monster"/>.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".

True if the specified clock has started state equal to started.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). For example, <started id="clock" not="1"/> is equivalent to <stopped id="clock"/>.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".
started	boolean, optional	the started state to compare the clock's current started state to -- 1 for started (default), 0 for stopped. For example, <started id="clock"/> checks if the clock is started, and <started id="clock" started="0"/> checks if clock has started="0", meaning that it has stopped.

True if the specified clock has stopped state equal to stopped.

Tag	Argument	Description
not	boolean, optional	set to 1 to take the boolean not of this condition (default is 0). For example, <stopped id="clock" not="1"/> is equivalent to <started id="clock"/>.
id	string, required	A string label uniquely identifying a game object within the current room.
notfound	boolean, optional	what to return if there's no game object with label id. The default is notfound="0".
stopped	boolean, optional	the stopped state to compare the clock's current stopped state to -- 1 for stopped (default), 0 for started. For example, <stoppedid="clock"/> checks if the clock is stopped, and <stopped id="clock" started="0"/> checks if clock has stopped="0", meaning that it has started.

Create a brand new game object at a certain tile.

Tag	Arguments	Description
create_type	string, required	the type of game object to create. This whould be a tag valid in a <room></room> block in rooms.xml. All sttributes other than create_type are parsed by the specified tag exactly as if they were in a <room></room> block.

Move a game object to a new tile of the level.

Tag	Arguments	Description
id	string, required	A string label uniquely identifying an game object within the current room.
at	point, required	the tile (X,Y) to move the game object to. You may use either of the options.
X and Y	integers, required

Remove a game object from the game entirely.

Tag	Arguments	Description
id	string, required	A string label uniquely identifying a game object within the current room.

Set a property on an existing game object.

Tag	Arguments	Description
id	string, required	A string label uniquely identifying a game object within the current room.
set_type	string, required	the property to set. Currently, passable (for customblocker game objects), started (for clock game objects), stopped (for clock game objects) are supported.
value	integer, required	the value to set the property to. Currently, all values are either 0 (false) or 1 (true).

Cast a spell.

Tag	Arguments	Description
casts	string, required	the spell name to be cast, as it appears in spellDB.xml. Example: casts="Weak Firebolt".
sourceat	point, optional	the source position (X,Y) of the spell. If not specified, defaults to the player's position. You may use either of the options.
sourceX and sourceY	integers, optional
targetat	point, optional	the target position (X,Y) of the spell. If not specified, defaults to the player's position. You may use either of the options.
targetX and targetY	integers, optional

Display text in the ticker

Tag	Arguments	Description
text	string, required	the text to display in the ticker. (Special thanks to forum user Aquaman for much of this into!)