Room System Reference

From DredMod
Jump to: navigation, search

Basic Syntax

All rooms start with an entry that looks something like 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 corresponds 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 note 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 particularly bothered by it.

Room Map

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 area1
 ! Destructible wall
X Impassable tile
Empty space outside the room. (Used for non-rectangular rooms.)
P Wall, plus 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 (to be used only within a store)

1this is used like a door & a shop must be built as if it’s a room within the room.

The above symbols are used basically to draw a map of the room, where # symbols are walls, etc, 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 over-ride them. If you use a 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 dormant, it will appear (and function) as just a normal wall. The others appear as empty floor when dormant. They are triggered by the 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 placing 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 to 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 shop 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 lieu 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 failed 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 keep 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".

Room Flags

These are contained within a data section marked <flags/>. Most room flags are boolean data. 0=False, 1=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 1 to prevent vending machines, uberchests, etc from spawning in the room. Used to make sure narrow passages 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 sometimes misbehave. 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 to use an "S", an "s" and multiple "i" entries 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 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 gains 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 fig.

Room Object Records

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

Clock creates a an object which displays text in 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 Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
name (string, optional) the short name of this object (shown, for example, in tool tips).
description (string, optional) the long description of this object (shown in tool tips).
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 (or all of pngSprite, pngFirst, pngNum, pngRate and sometimes pngAnimate) (sprite, required) sprite to show for this custom object.
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).

customblocker

Creates objects that restrict movement and sometimes line of sight.

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
name (string, optional) the short name of this object (shown, for example, in tool tips).
description (string, optional) the long description of this object (shown in tool tips).
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 (or all of pngSprite, pngFirst, pngNum, pngRate and sometimes pngAnimate) (sprite, required) sprite to show for this custom object.


custombreakable

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

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
name (string, optional) the short name of this object (shown, for example, in tool tips).
description (string, optional) the long description of this object (shown in tool tips).
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 (or all of pngSprite, pngFirst, pngNum, pngRate and sometimes pngAnimate) (sprite, required) sprite to show for this custom object.
hitsNeededToBreak (integer, optional) how many hits are needed to break this custombreakable (default is 1)
hitsTaken (integer, optional) how many hits has this custombreakable already taken (default is 0)
breaking (or all of breakingSprite, breakingFirst, breakingNum, breakingRate and sometimes breakingAnimate) (sprite, optional) sprite to show immediately after this custombreakable has been broken.
broken (or all of brokenSprite, brokenFirst, brokenNum, brokenRate and sometimes brokenAnimate) (sprite, required) sprite to show after this custombreakable has been broken.


customengraving

Used in the main-game to create objects the player cannot interact with. Mostly used for flavor and decoration.

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
name (string, optional) the short name of this object (shown, for example, in tool tips).
description (string, optional) the long description of this object (shown in tool tips).
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 (or all of pngSprite, pngFirst, pngNum, pngRate and sometimes pngAnimate) (sprite, required) sprite to show for this custom object.

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

element

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying 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

Horde creates a small group of monsters of the same type. They are 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 Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
percent (integer, optional) percent chance this item will appear in the dungeon (default is 100)
id (string, optional) string label uniquely identifying this game object within the current room.
name (string, optional) the short name of this object (shown, for example, in tool tips).
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 number 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?)

lever

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying 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 the little treasure rooms.

loot

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
amount (integer, optional) the number of the loot to create.
type (string) the type of the 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.

monster

Creates a single monster.

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
percent (integer, optional) percent chance this item will appear in the dungeon (default is 100)
id (string, optional) string label uniquely identifying this game object within the current room.
name (string, optional) the monster type to be created, as it appears in monDB.xml. Example: name="Kleptoblobby". If you omit this, a random monster of the appropriate level will be spawned.

pedestal

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

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
name (string, required) the name of the pedestal (shown, for example, in tool tips).
text (string, required) the text to be displayed to the player when this pedestal is clicked

trap

Creates a trap at the specified location.

Tag Arguments Description
at (or both X and Y) (point, required) tile X and tile Y where the game object will be created. You may also specify an at location.
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 identifying this game object within the current room.
name (string, optional) the trap type to be created, as it appears in itemDB.xml. Example: name="Boulder Drop Plate".

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.

Room Script Conditions

activated

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

Tag Arguments 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 is 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 for activated, 0 for de-activated.

activated_changed

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

Tag Arguments 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 is 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 for activated, 0 for de-activated.

at

True if the specified game object has the given tile X and tile Y.

Tag Arguments 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 is no game object with label id. The default is notfound="0".
at (or both X and Y) (point, required) the tile X and tile Y to compare the game object's tile X and tile Y to. You may also specify an at location.

entered

True if the player entered this room this game tick.

Tag Arguments 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 entered the room - very unlikely you'd want to test this.

event

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

Tag Arguments 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 is 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.

exited

True if the player exited this room this game tick.

Tag Arguments 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.

isalive

True if the specified monster is alive.

Tag Arguments 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 is no game object with label id. The default is notfound="1".

isdead

True if the specified monster is dead.

Tag Arguments 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 is no game object with label id. The default is notfound="1".

started

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

Tag Arguments 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 is 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 (the default), 0 for stopped. For example, <started id="clock" /> checks if clock is started, and <started id="clock" started="0" /> checks if clock has started="0", meaning that it is stopped.

stopped

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

Tag Arguments 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 is 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 (the default), 0 for started. For example, <stopped id="clock" /> checks if clock is stopped, and <stopped id="clock" stopped="0" /> checks if clock has stopped="0", meaning that it is started.

Room Script Actions

create

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 should be a tag valid in a <room></room> block in rooms.xml. All attributes other than create_type are parsed by the specified tag exactly as if they were in a <room></room> block.

move

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

Tag Arguments Description
id (string, required) A string label uniquely identifying a game object within the current room.
at (or both X and Y) (point, required) the tile X and tile Y to move the game object to. You may also specify an at location.

remove

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

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 (for false) or 1 (for true).

spell

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 (or both sourceX and sourceY) (point, optional) the source position of the spell. If not specified, defaults to player's tile X and tile Y.
targetat (or both targetX and targetY) (point, optional) the target position of the spell. If not specified, defaults to player's tile X and tile Y.

ticker

Display text in the ticker.

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