Des-file format (UnNetHack)

This is a preliminary document of the Des-file format used by UnNetHack.

UnNethack, like Sporkhack started with the new level compiler patch, and added most of the changes from Spork.

A level consists of any number of Header statements, and one or more of Level definitions.

Header statements

FUNCTION

FUNCTION name() { Level statements }

Defines a function. The level statements defined inside the function body will be executed when the function is called. Function must be defined before it can be called. Call the function by using it's name, for example name() Variables defined outside the function cannot be accessed, and variables defined inside the function are gone when the function finishes.

Example:

FUNCTION foobar() {
  OBJECT:'?', random
}
foobar()

INCLUDE

INCLUDE "filename.des"

Includes the contents of the file in the current file.

Level definitions

A level definition consists of LEVEL, followed by an optional FLAGS and any number of Level statements.

LEVEL

LEVEL:"name"

The level is saved as name.des file. The name can be up to 8 characters long.

FLAGS

FLAGS:noteleport,mazelevel

Defines special flags for the whole level. Parameters are a comma-separated list of flags:

• noteleport: Player cannot teleport within the level.
• sheol: Level is a Sheol-type level, with special rules.
• hardfloor: The floor is too hard to dig.
• nommap: magic mapping does not work.
• arboreal: supposedly an outdoor map. Solid walls and secret corridors will be shown as trees, digging makes floor instead of corridor and randomly created corridors are made out of floor instead of corridor.
• shortsighted: Monsters cannot see you from far away.
• noflipx, noflipy and noflip prevent the level from being flipped horizontally, vertically and both.
• mazelevel: level is a "maze" type level. Digging a wall turns it into room floor and mimics prefer mimicing a statue.
• premapped: The level map is automatically known by player (a la Sokoban).
• shroud: Magic mapping doesn't reveal the map permanently.
• stormy: Clouds randomly emit lightning bolts, a la Plane of Air.
• graveyard: Reduced chances of undead corpses.
• sky: Level is open to the sky, so has no ceiling.

Level statements

Level statements include the following commands, variable definitions, FUNCTION definitions, function calls, and Flow control commands.

MESSAGE

MESSAGE:"string"

The message string is shown when player first enters the level. Each message line gets separated with a --more-- -prompt in the game.

Example:

MESSAGE: "Well done, mortal!"
$foo = "Hello, World!"
MESSAGE: $foo

INIT_MAP

INIT_MAP:solidfill, ' '
INIT_MAP:mazegrid,'-'
INIT_MAP:sheollev
INIT_MAP:mines, '.' , ' ', true, true, random, true

Initializes the map with different algorithm.

• solidfill: Fills the level with the specified map character.
• mazegrid: Generates a grid of solid walls and the specified map characters. Use MAZEWALK to carve a maze into it.
• sheollev: Generates a Sheol level. No parameters.
• mines: Creates Gnomish Mines-style levels. Takes several parameters: foreground, background, smoothed, joined, light_state, walled [, filling ]
  • foreground: The "foreground" fill map character. This should be something the player can walk on, as the walkable part will be made out of this.
  • background: The "background" fill map character. This will surround the foreground area, so can be solid or harmful to player.
  • smoothed: is either true or false, and denotes whether the level will be "smoothed". This means that any foreground character surrounded by fewer than 3 foreground characters is changed to background character.
  • joined: is either true or false, and denotes whether the level will be "joined", so that all parts are accessible by walking.
  • light_state: is either lit, unlit, or random.
  • walled: is either true or false. This is equivalent of using a WALLIFY -command.
  • filling: optional fill map character. The "outside" parts of the level will be filled with this.

ALTAR

ALTAR:coord or variable, alignment, altartype

Create an altar.

GRAVE

GRAVE:coord or variable, "Any epitaph message"
GRAVE:coord or variable, random
GRAVE:coord or variable

Creates a grave at given location, with a given epitaph, a random epitaph, or with no text.

MON_GENERATION

Change the monster generation chances for this level.

MON_GENERATION:75%, (9, 'a'), (1, "fire giant")

75% of randomly generated monsters are either ants (90% chance), or fire giants (10% chance).

SOUNDS

Random sounds on this level.

SOUNDS:200, (hear, "falling rocks."), (pline, "Kaboom!"), (verbal, "Mwahahah!"), (feel, "hot!")

1/200 chance each turn to get one of the sounds defined. In this case, "You hear falling rocks.", "Kaboom!", "Mwahahah!", or "You feel hot!"

BRANCH

BRANCH:(x1,y1,x2,y2), (x3,y3,x4,y4)
BRANCH:levregion(x1,y1,x2,y2), levregion(x3,y3,x4,y4)

CORRIDOR

CORRIDOR:(room_number, direction, door_position), (room_number, direction, door_position)
CORRIDOR:(room_number, direction, door_position), any_integer

SHUFFLE

SHUFFLE:any_array_variable

Shuffles the array elements.

Example:

$foo = MONSTER:{ 'd', 'T', 'e', 'L' }
SHUFFLE: $foo

NON_DIGGABLE

NON_DIGGABLE:region_or_variable

Sets the walls inside the region as non-diggable.

Example:

NON_DIGGABLE:(00,00,13,12)

NON_PASSWALL

NON_PASSWALL:region_or_variable

Players and monsters cannot phase through the walls inside the region.

Example:

NON_PASSWALL:(00,00,13,12)

ROOMDOOR

ROOMDOOR:secret, door_state, door_wall, door_pos

Creates a door with certain state on the previously defined ROOM or SUBROOM.

• secret can be one of true, false, or random.
• door_state can be one of open, closed, locked, nodoor, broken, secret, or random.
• door_wall can be one of north, south, west, or east, a pipe-delimited list of those, or random, and tells on what wall of the room the door will be created.
• door_pos is a positive integer value and tells how far from the top or left the door will be.

Example:

ROOMDOOR: false, closed, north|south, random

DOOR

DOOR:door_state, selection

Puts a door on the map.

• door_state can be one of open, closed, locked, nodoor, broken, secret, or random.

WALLWALK

WALLWALK:coord or variable, map character or variable
WALLWALK:coord or variable, map character or variable, 50%
WALLWALK:coord or variable, map character or variable, map character or variable
WALLWALK:coord or variable, map character or variable, map character or variable, 50%

DRAWBRIDGE

DRAWBRIDGE:coord or variable, dir, state

• dir is one of the following: north, east, south or west
• state is one of the following: nodoor, locked, closed, open or random

Note that the drawbridge placement is different from door placement; the coordinate must be a place where the drawbridge would be when it's open, and from that place towards the direction there should be a wall, where the portcullis will be.

Example:

DRAWBRIDGE:(25,18), north, closed

ENGRAVING

ENGRAVING:coord or variable, engraving_type, "string"
ENGRAVING:coord or variable, engraving_type, $stringvariable

engraving_type can be one of dust, engrave, burn, mark, blood, or random.

FOUNTAIN

FOUNTAIN:selection

POOL

POOL:selection

SINK

SINK:selection

TERRAIN

TERRAIN:selection, map_character_or_variable

REPLACE_TERRAIN

REPLACE_TERRAIN:region_or_variable, map_character_or_variable, map_character_or_variable, percentage

SPILL

SPILL:coord or variable, terrain_type, direction, length

PORTAL

PORTAL:(x1,y1,x2,y2), (x3,y3,x4,y4), "string"
PORTAL:levregion(x1,y1,x2,y2), levregion(x3,y3,x4,y4), "string"

RANDOM_CORRIDORS

RANDOM_CORRIDORS
RANDOM_CORRIDORS:style

style is random, or one of the following values:

• 1 = at least one corridor leaves from each room and goes to random room
• 2 = circular path: room1 -> room2 -> room3 -> ... -> room1
• 3 = all roads lead to rome. or to the first room.
• any other value (or leaving style off) will generate normal style corridors.

REGION

REGION:region_or_variable, lightstate, roomtype [, filling [, bool]] [{ Level statements }]

ROOM

ROOM:"roomtype", [ chance, ] lightstate, position, align, size [, fill] { Level statements }

• position can be either random or an approximate location in the form of (1,3) - this is not a coordinate, but an approximate position on the map - the number ranges are 1..5
• align is either random or an approximate adjustment to the location in the form of (horiz, vert), where
  • horiz is one of left, half-left, center, half-right, or right.
  • vert is one of top, center, or bottom.
• size is either random or an exact width and height in the form of (3,5).
• fill is an optional boolean, and tells whether the room should get stocked with random stuff.

The contents (and SUBROOMs) of the room can be defined using the level statements.

SUBROOM

SUBROOM:"roomtype", [ chance, ] lightstate, position, size [, fill] { Level statements }

• position is either random, or an exact position of the room inside the outer room in the form of (4,3).
• size is either random or an exact width and height in the form of (3,5).
• fill is an optional boolean, and tells whether the room should get stocked with random stuff.

The contents (and SUBROOMs) of the room can be defined using the level statements.

GOLD

GOLD:mathematical expression, coord or variable

LADDER

LADDER:coord or variable, direction

Creates a ladder. direction is one of up or down.

STAIR

STAIR:coord or variable, direction

Creates stairs. direction is one of up or down.

TELEPORT_REGION

TELEPORT_REGION:(x1,y1,x2,y2), (x3,y3,x4,y4) [, up_or_down ]
TELEPORT_REGION:levregion(x1,y1,x2,y2), levregion(x3,y3,x4,y4) [, up_or_down ]

TRAP

TRAP:"falling rock", coord or variable
TRAP:random, coord or variable

WALLIFY

WALLIFY
WALLIFY:region_or_variable

Turns walls (in the whole map, or in the defined region) completely surrounded by other walls into solid stone ' '.

NOMAP

NOMAP

Instead of GEOMETRY and MAP, you use this if you think that INIT_MAP creates a good enough random map and you don't want to use any fixed map-parts.

See also MAP

GEOMETRY

This must be immediately followed by a MAP definition. It tells the location of the MAP-part on the level. Two types of GEOMETRY, one takes an approximation of MAP alignment, the other takes an exact coordinate or variable.

GEOMETRY:horiz,vert
GEOMETRY:coord or variable

• horiz is one of left, half-left, center, half-right, or right.
• vert is one of top, center, or bottom.

Both types take an optional boolean value. If it's true, the commands following the map are restricted into that map.

GEOMETRY:center,center,true

MAP

MAP
...
...
...
ENDMAP

This must be immediately preceded by a GEOMETRY definition. You define a map-part by "drawing" with map characters between the MAP and ENDMAP. The map can be up to 21 lines high and each line can be up to 76 chars long. Each line must also be the same length. You can also use numbers inside the map, but those will be ignored; they're considered as line numbers.

See also NOMAP.

MAZEWALK

MAZEWALK:coord or variable, direction
MAZEWALK:coord or variable, direction, stocked
MAZEWALK:coord or variable, direction, stocked, '.'

stocked is a boolean value and tells whether the maze should get stocked with random loot and monsters.

MONSTER

MONSTER:'d', coord or variable
MONSTER:"hill giant", coord or variable
MONSTER:('i', "imp"), coord or variable
MONSTER:random, coord or variable
$foo = MONSTER:'d'
MONSTER:$foo, (5,5)
$arr = MONSTER:{ 'd', 'T', 'y' }
MONSTER:$arr[0], (5,5)

The monster definition can also take a number of optional parameters, separated by commas:

MONSTER:'d', (4,4), "Idefix", peaceful, asleep, law, m_feature "boulder", female, invisible, cancelled, revived, avenge, stunned, confused, fleeing: 40, blinded: 20, paralyzed: 10, seen_traps: all

• "Idefix" is the name of the monster.
• Instead of peaceful, could use hostile.
• Instead of asleep, could use awake.
• Instead of law, could use noalign, neutral, chaos, coaligned, noncoaligned, align[0], align[1], align[2] or align:random.
• m_feature tells the monster to mimic a dungeon feature, a boulder in this case. could also use m_monster or m_object.
• female, invisible, cancelled, revived, avenge, stunned and confused set monster status bits.
• fleeing, blinded and paralyzed set the number of turns the monster will flee, is blinded or is paralyzed, respectively.
• seen_traps tells which traps the monster has seen; parameter is either all or quoted strings of trap names separated by pipe characters (eg. "falling boulder", or "arrow"|"dart"|"bear")

OBJECT

OBJECT:"elven cloak", (5,5)
OBJECT:'?', (5,5)
OBJECT:('/', "wishing"), (5,5)
OBJECT:random, (5,5)
$foo = OBJECT:'/'
OBJECT:$foo, (5,5)
$arr = OBJECT:{ '/', '?', '!' }
OBJECT:$arr[2], (5,5)

The object definition can also take a number of optional parameters, separated by commas:

OBJECT:'?', (5,5), blessed, montype:('d', "little dog"), +4, NAME:"foobar", quantity: 20, buried, invisible, lit, greased, locked, trapped, eroded:2, erodeproof, recharged:3

• blessed can be replaced with uncursed or cursed.
• montype tells eg. what monster statue it is.
• any integer value sets the plusses or minuses for eg. armor or weapon.
• NAME gives the item a name. can also take a variable of string type as a parameter.
• quantity set the number of items.
• buried, trapped, invisible, greased set object states.
• lit or unlit for lamps.
• eroded sets the erosion. Don't use with erodeproof.
• locked (or broken) set the lock state for lockable objects.
• recharged sets the number of times eg. a wand has been recharged.

CONTAINER

CONTAINER:"large chest", (5,5) { Level statements }

Takes the same parameters as OBJECT, but allows defining the contents inside the curly braces. For the contents, use a subset of level statements: OBJECTs, CONTAINERs and flow control commands (LOOP, IF...ELSE and SWITCH); anything else causes undefined behaviour.

Flow control

The following commands affect the order in which commands are executed.

SWITCH

SWITCH [ integer_or_variable ] {
  CASE integer:
     Level statements
     BREAK
  DEFAULT:
     Level statements
     BREAK
} 

The SWITCH behaviour is modeled after the C switch-statement. The BREAK keyword is optional; leaving it out will make execution fall through to the next case.

LOOP

LOOP [ integer_or_variable ] { Level statements }

Example:

LOOP [ 10 ] { OBJECT:random,random }

IF

IF [ percentage ] { Level statements }
IF [ 50% ] { Level statements } ELSE { Level statements }
IF [ math_expression_or_variable compare_operator math_expression_or_variable ] { Level statements }

EXIT

EXIT

Immediately finishes the level script.

variable

Variable names start with a dollar sign, and can contain any alphanumeric characters. Variables must be defined before they can be used. Some variable definitions must have the variable type: TERRAIN, MONSTER, OBJECT and selection.

$foo = 123
$foo = "any string"
$foo = mathematical expression
$bar = $foo
$foo = TERRAIN:'T'
$foo = MONSTER:'d'
$foo = MONSTER:"little dog"
$foo = MONSTER:('d', "little dog")
$foo = MONSTER:random
$foo = OBJECT:'/'
$foo = OBJECT:"elven cloak"
$foo = OBJECT:('?', "identify")
$foo = (40, 12)
$foo = (5,5, 40,12)
$foo = selection:selection

array variable

$foo = { 1, 2, 3, 4, 5 }
$foo = { "string a", "bcdef", "and something" }
$foo = { (1,2), (40,12) }
$foo = { (5,5,40,12), (1,1,20,18), (40,10,50,12) }
$foo = TERRAIN: { 'T', 'L', '.' }
$foo = MONSTER: { 'n', "newt", ('d', "little dog") }
$foo = OBJECT: { '/', "elven cloak", ('?', "identify") }

To access one element of an array variable, use eg. $foo[0] to access variable $foo's first element.

coord or variable

This parameter can be either a coordinate, or a variable of the coordinate type. For example:

GRAVE: (10,5)
$foo = (4,10)
$bar = { (4,10), (3,12), (50,2) }
GRAVE: $foo
GRAVE: $bar[1]

GRAVE: rndcoord(selection)

A random coordinate selected from within the selection

region or variable

This parameter can be either a region, or a variable of the region type. For example:

NON_DIGGABLE:(5,5, 40,12)
$foo = (5,5, 40,12)
NON_DIGGABLE:$foo

mathematical expression

A mathematical expression can consist of plain integer values, D-notations, and the operands '+', '-', '*', '/', and '%'. For example: 1 + 2, or 3d6 * (2 + 3). Negative integer values should be enclosed inside parenthesis: (-1) * (-3)

selection

A selection is a collection of map coordinates. The selection keyword is only needed when defining a variable of selection type.

$foo = selection:coord or variable
$foo = selection:rect region or variable
$foo = selection:fillrect region or variable
$foo = selection:line coord or variable-coord or variable
$foo = selection:randline coord or variable-coord or variable,mathematical expression
$foo = selection:grow (selection)
$foo = selection:grow (list of directions, selection)
$foo = selection:filter (50%, selection))
$foo = selection:filter (selection, selection)
$foo = selection:floodfill coord or variable
$foo = selection:circle (coord or variable, mathematical expression)
$foo = selection:circle (coord or variable, mathematical expression, filled)
$foo = selection:circle (coord or variable, mathematical expression, unfilled)
$foo = selection:ellipse (coord or variable, mathematical expression, mathematical expression)
$foo = selection:ellipse (coord or variable, mathematical expression, mathematical expression, filled)
$foo = selection:ellipse (coord or variable, mathematical expression, mathematical expression, unfilled)
$bar = $foo

Selections can be added together with the '&' operator, for example rect(5,5, 50,18) & rect(10,2, 40,13):

$foo = selection:rect(5,5, 50,18) & rect(10,2, 40,13)

To select a random coordinate from a selection, use rndcoord(selection):

$bar = rndcoord(rect(5,5, 50,18) & rect(10,2, 40,13))