Des-file format - Revision history

Phol ende wodan: Update upcoming note, which was a bit terse, and expand on potential plans for after 3.7 is released

2024-11-07T22:10:28Z

Update upcoming note, which was a bit terse, and expand on potential plans for after 3.7 is released

Furey: Add history (first appeared in NetHack 3.0.0) and {{upcoming}} (replaced by Lua files in NetHack 3.7.0).

2024-06-05T16:27:29Z

Add history (first appeared in NetHack 3.0.0) and {{upcoming}} (replaced by Lua files in NetHack 3.7.0).

Furey: Add refsrc's. Rewrite lede.

2024-06-05T15:31:33Z

Add refsrc's. Rewrite lede.

Furey: /* FLAGS */ fix a redlink: closets -> closets

2024-06-05T07:26:16Z

‎FLAGS: fix a redlink: closets -> closets

Furey: oops

2024-06-05T07:22:53Z

oops

Furey: touch up some references.

2024-06-05T07:16:28Z

touch up some references.

Netzhack: /* FLAGS */ extraneous words out

2023-10-04T14:25:01Z

‎FLAGS: extraneous words out

K2: /* OBJECT */ provide example for specific egg types

2021-04-12T15:57:20Z

‎OBJECT: provide example for specific egg types

Netzhack: (x,y) is a pair of coordinates (plural).

2018-08-10T19:11:55Z

(x,y) is a *pair* of coordinates (plural).

Phol ende wodan: /* Variables */ certain ones require type declaration

2018-08-10T16:31:04Z

‎Variables: certain ones require type declaration

@@ Line 8: / Line 8: @@
 des-file format is not a ''real'' programming language: there is no flow control, and the order in which different NetHack features are created is fixed.
-{{upcoming|NetHack 3.7.0|lev_comp and .des files are gone, replaced by Lua files to define special levels.}}
+{{upcoming|NetHack 3.7.0|lev_comp and .des files are gone, replaced by Lua files to define special levels, so the game no longer uses des-file format.
 {{Float right|__TOC__}}

@@ Line 7: / Line 7: @@
 des-file format is not a ''real'' programming language: there is no flow control, and the order in which different NetHack features are created is fixed.
 {{Float right|__TOC__}}
@@ Line 823: / Line 825: @@
 ===Room types===
 "ordinary", "throne", "swamp", "vault", "beehive", "morgue", "barracks", "zoo", "delphi", "temple", "anthole", "cocknest", "leprehall", "shop", "armor shop", "scroll shop", "potion shop", "weapon shop", "food shop", "ring shop", "wand shop", "tool shop", "book shop", "candle shop"
 ==References==

@@ Line 2: / Line 2: @@
 {{for|the corresponding feature in [[NetHack 3.4.3]] and variants based on it|Des-file format (NetHack 3.4.3)}}
 {{for|the corresponding feature in [[UnNetHack]]|Des-file format (UnNetHack)}}
-The '''des-file format''' is the language which is used to describe the [[special level]]s for NetHack. It is compiled into a binary file by [[lev_comp]].
+The '''des-file format''' is the language used to describe the [[special level]]s for NetHack. The [[lev_comp]] utility compiles <tt>.des</tt> files into <tt>.lev</tt> files, and then the NetHack executable loads <tt>.lev</tt> files to run the game.{{refsrc|doc/lev_comp.6|1|nethack=3.6.7}}{{refsrc|doc/lev_comp.txt|1|nethack=3.6.7}}{{refsrc|util/lev_comp.l|1|nethack=3.6.7}}{{refsrc|util/lev_comp.y|1|nethack=3.6.7}}{{refsrc|util/lev_main.c|1|nethack=3.6.7}}
-It is not a ''real'' programming language: there is no flow control, and the order in which different NetHack features are created is fixed.
+The [[Dungeon.def format|dungeon.def]] file ties together all the <tt>.des</tt> files to describe the entire dungeon.
-There are two types of levels you can create: mazes and rooms. For {{sa|MAZE-type levels}} you "draw" one or more maps with ASCII characters and then describe the monsters, objects and so on that are in the map (example: dat/bigroom.des).{{refsrc|dat/bigroom.des|1|nethack=3.6.7}}. For {{sa|ROOM-type levels}}, you describe rooms and their contents (example: dat/oracle.des).{{refsrc|dat/oracle.des|1|nethack=3.6.7}}. The maze-levels are easier to make and understand, and room-type levels do not offer as much control over the level.
+des-file format is not a ''real'' programming language: there is no flow control, and the order in which different NetHack features are created is fixed.
 {{Float right|__TOC__}}
 ==Language syntax==
 === Comments ===
 All lines beginning with <tt>#</tt> are comments and are ignored by the level compiler, except between {{sa|MAP}} and [[#MAP|ENDMAP]].

@@ Line 237: / Line 237: @@
 *<tt>solidify</tt>: Areas outside the specified level map are made undiggable and unphaseable. (Examples: Vlad's Tower, Sokoban, the Astral Plane)
 *<tt>corrmaze</tt>: If the level is a maze (not a maze-type level, an actual maze), the maze uses corridor tiles instead of floor tiles and solid rock instead of walls. Randomly generated mazes have a 1/3 chance of having corrmaze set.
-*<tt>inaccessibles</tt>: If inaccessible areas are generated, generate ways for them to connect to the "accessible" area. This tries first to create a secret door connecting it to the accessible area; if that fails it tries to create a hole or trapdoor; if that fails it tries to create an escape item (teleport items or digging tools). This code is not used for inaccessible [[closets]], which always get a scroll of teleportation.
+*<tt>inaccessibles</tt>: If inaccessible areas are generated, generate ways for them to connect to the "accessible" area. This tries first to create a secret door connecting it to the accessible area; if that fails it tries to create a hole or trapdoor; if that fails it tries to create an escape item (teleport items or digging tools). This code is not used for inaccessible [[closet]]s, which always get a scroll of teleportation.
 Example:

@@ Line 6: / Line 6: @@
 It is not a ''real'' programming language: there is no flow control, and the order in which different NetHack features are created is fixed.
-There are two types of levels you can create: mazes and rooms. For {{sa|MAZE-type levels}} you "draw" one or more maps with ASCII characters and then describe the monsters, objects and so on that are in the map (example: dat/bigroom.des).{{refsrc|dat/bigroom.des|1|nethack-3.6.7}}. For {{sa|ROOM-type levels}}, you describe rooms and their contents (example: dat/oracle.des).{{refsrc|dat/oracle.des|1|nethack-3.6.7}}. The maze-levels are easier to make and understand, and room-type levels do not offer as much control over the level.
+There are two types of levels you can create: mazes and rooms. For {{sa|MAZE-type levels}} you "draw" one or more maps with ASCII characters and then describe the monsters, objects and so on that are in the map (example: dat/bigroom.des).{{refsrc|dat/bigroom.des|1|nethack=3.6.7}}. For {{sa|ROOM-type levels}}, you describe rooms and their contents (example: dat/oracle.des).{{refsrc|dat/oracle.des|1|nethack=3.6.7}}. The maze-levels are easier to make and understand, and room-type levels do not offer as much control over the level.
 [[lev_comp]] will create a .lev-file for each MAZE and LEVEL definition in the file. These .lev-files will be loaded into NetHack to make the special levels. The .lev-files NetHack loads are actually defined in [[Dungeon.def format|dungeon.def]].
@@ Line 688: / Line 688: @@
 Where
 *<tt>cursestate</tt> is one of <tt>blessed</tt>, <tt>uncursed</tt>, <tt>cursed</tt> or <tt>random</tt>.
-*<tt>"monster_id"</tt> is a monster type, as defined in {{refsrc|src/monst.c|1|nethack-3.6.7}}
+*<tt>"monster_id"</tt> is a monster type, as defined in {{refsrc|src/monst.c|1|nethack=3.6.7}}
 *<tt>spe</tt> is an integer, and defines different things depending on what kind of object is generated:
 **enchantment for [[armor]] and [[weapon]]s

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:des-file format}}
 The '''des-file format''' is the language which is used to describe the [[special level]]s for NetHack. It is compiled into a binary file by [[lev_comp]].
 It is not a ''real'' programming language: there is no flow control, and the order in which different NetHack features are created is fixed.
-There are two types of levels you can create: mazes and rooms. For {{sa|MAZE-type levels}} you "draw" one or more maps with ASCII characters and then describe the monsters, objects and so on that are in the map (example: [[Bigroom.des]]). For {{sa|ROOM-type levels}}, you describe rooms and their contents (example: [[Oracle.des]]). The maze-levels are easier to make and understand, and room-type levels do not offer as much control over the level.
+There are two types of levels you can create: mazes and rooms. For {{sa|MAZE-type levels}} you "draw" one or more maps with ASCII characters and then describe the monsters, objects and so on that are in the map (example: dat/bigroom.des).{{refsrc|dat/bigroom.des|1|nethack-3.6.7}}. For {{sa|ROOM-type levels}}, you describe rooms and their contents (example: dat/oracle.des).{{refsrc|dat/oracle.des|1|nethack-3.6.7}}. The maze-levels are easier to make and understand, and room-type levels do not offer as much control over the level.
 [[lev_comp]] will create a .lev-file for each MAZE and LEVEL definition in the file. These .lev-files will be loaded into NetHack to make the special levels. The .lev-files NetHack loads are actually defined in [[Dungeon.def format|dungeon.def]].
 {{Float right|__TOC__}}
@@ Line 690: / Line 688: @@
 Where
 *<tt>cursestate</tt> is one of <tt>blessed</tt>, <tt>uncursed</tt>, <tt>cursed</tt> or <tt>random</tt>.
-*<tt>"monster_id"</tt> is a monster type, as defined in [[monst.c]]
+*<tt>"monster_id"</tt> is a monster type, as defined in {{refsrc|src/monst.c|1|nethack-3.6.7}}
 *<tt>spe</tt> is an integer, and defines different things depending on what kind of object is generated:
 **enchantment for [[armor]] and [[weapon]]s
@@ Line 696: / Line 694: @@
 **historic and gender bit for [[statue]]s. 1 is historic, 2 is male, 4 is female. Adding the values together is possible, so you can create eg. historic, male statue with value 3 and historic, female with 5. Leaving the gender specification out will either result in a random gender, or if the monster is always of certain gender, then the statue will be that gender too. (eg. nymphs)
 **[[tin]]s: 1 means spinach, -1 is home-made.
-**[[container]]s: 1 means the box contains Shroedinger's cat.
+**[[container]]s: 1 means the box contains [[Schroedinger's Cat]].
 **[[oil lamp]]s and [[candle]]s: 0 means the lamp is out of oil.
 **[[Candelabrum]]: how many candles are attached to it.
@@ Line 825: / Line 823: @@
 "ordinary", "throne", "swamp", "vault", "beehive", "morgue", "barracks", "zoo", "delphi", "temple", "anthole", "cocknest", "leprehall", "shop", "armor shop", "scroll shop", "potion shop", "weapon shop", "food shop", "ring shop", "wand shop", "tool shop", "book shop", "candle shop"
-== See also ==
+==References==
-* [[Des-file format (NetHack 3.4.3)]]
+<references/>
 [[Category:Annotations]]
 {{nethack-360}}

@@ Line 233: / Line 233: @@
 *<tt>shortsighted</tt>: Monsters cannot see you from far away.
 *<tt>mazelevel</tt>: Used when a ROOM-type level wants to set the maze level flag to be treated as a maze level, with the corresponding effects.
-*<tt>premapped</tt>: When the player enters the level, it is automatically mapped, including all traps and boulders. This is because it's only used for Sokoban at the moment.
+*<tt>premapped</tt>: When the player enters the level, it is automatically mapped, including all traps and boulders. This is only used for Sokoban at the moment.
 *<tt>shroud</tt>: Unseen locations on the level will not be remembered by the hero, instead of rendering as out-of-sight map, trap, and object glyphs like they normally do. No levels currently use this flag.
 *<tt>graveyard</tt>: Treats the level as a graveyard level (causes graveyard sounds and undead have a reduced chance of leaving corpses).

@@ Line 716: / Line 716: @@
   OBJECT:'`', "statue", (0,0), "forest centaur", 1
   OBJECT:('(', "crystal ball"), (17,08), blessed, 5,name:"The Orb of Fate"
 ===SINK===

@@ Line 29: / Line 29: @@
 |-
 |coord
-|An (x,y) pair of numbers that represents a spot on the last defined MAP or on the whole level if there is none. By convention, coordinates less than 10 have a 0 in them so that all numbers in coordinates are two digits, but this is not required.
+|A coordinate pair, that is, a pair of numbers (x,y) representing a location on the last defined MAP or on the whole level if no MAP is defined, where (0,0) represents the point in the upper left corner. By convention, coordinates less than 10 have a leading 0, so that all coordinates are two digits, but this is not required.
-Also, using ''rndcoord'' on any terrain selection (see below) will select one coordinate at random from that selection and resolve to a single coord.
+Also, using ''rndcoord'' on any terrain selection (see below) will select one pair of coordinates at random from that selection and thus resolves to a single coord.
 |(70,06)
 |-
@@ Line 47: / Line 47: @@
 |-
 |region
-|A rectangular region of the level, expressed with the x and y coordinates of its upper left and lower right corners, respective to the most recently defined MAP. A variation is a ''levregion'', which is the same thing but the coordinates are absolute on the level irrespective of any MAPs.
+|A rectangular region of the level, expressed with the x and y coordinates of its upper left and lower right corners, respective to the most recently defined MAP. A variation is a ''levregion'', which is the same thing except that the coordinates are absolute on the level irrespective of any MAPs.
 |(03,10,64,10)
 levregion(10,18,21,25)
@@ Line 71: / Line 71: @@
 |-
 |selection
-|One, or a combination of multiple, {{sa|terrain selections}} (see below), representing an area of the level that is not necessarily rectangular. Frequently, rndcoord is used on a selection to pick one of its coordinates at random.
+|One, or a combination of multiple, {{sa|terrain selections}} (see below), representing an area of the level that is not necessarily rectangular. Frequently, rndcoord is used on a selection to pick a pair of coordinates in it at random.
 |rect (10,10,20,20) & line (50,50),(60,50) & (61,61)
 |-
@@ Line 105: / Line 105: @@
 === Terrain selections ===
-Many complicated shapes can be generated with terrain selections, and these shapes can even be combined with each other. The easiest way to think of them is as a set of coordinates. These are the available definitions for terrain selections:
+Many complicated shapes can be generated with terrain selections, and these shapes can even be combined with each other. The easiest way to think of them is as a set of points. These are the available definitions for terrain selections:
 {|class="wikitable"
@@ Line 113: / Line 113: @@
 |-
 |''coord''
-|Just a single coordinate point.
+|Just a single point, one pair of coordinates.
 |<tt>(44,12)</tt>
 |-
@@ Line 125: / Line 125: @@
 |-
 |line ''coord'',''coord''
-|A straight line drawn from one coordinate to the other using Bresenham's line algorithm.
+|A straight line drawn from one pair of coordinates to the other using Bresenham's line algorithm.
 |<tt>line (76,03),(55,19)</tt>
 |-
 |randline ''coord'',''coord'',''math expression''
-|A line that is guaranteed to start at one coordinate and finish at the other, but uses a random walk to get there. Specifically, the algorithm uses a form of fractal noise: it takes the midpoint of the line, moves it to a random point nearby no farther than the user-provided roughness (the last argument), then recurses on each resulting half of the line with the roughness reduced to 2/3 of its provided value.
+|A line that is guaranteed to start at one pair of coordinates and finish at the other, but uses a random walk to get there. Specifically, the algorithm uses a form of fractal noise: it takes the midpoint of the line, moves it to a random point nearby no farther than the user-provided roughness (the last argument), then recurses over each resulting half of the line with the roughness reduced to 2/3 of its previous value.
 |<tt>randline (00,10),(75,10),15</tt>
 |-
@@ Line 142: / Line 142: @@
 |-
 |filter(''selection1'',''selection2'')
-|Perform a set intersection operation on the two selections. Coordinates that appear in both separate selections will be kept in the resulting selection; coordinates that appear in only one or the other are removed.
+|Perform a set intersection operation on the two selections. Points that appear in both selections will be kept in the resulting selection; points that appear in only one or the other are removed.
 |<tt>filter(floodfill(23,23), fillrect(20,20,25,25))</tt>
 |-
@@ Line 151: / Line 151: @@
 |-
 |floodfill ''coord''
-|Performs a flood fill from the provided coordinate, adding to the selection all the connected spaces with the same terrain type as the starting location. It does not fill across diagonals.
+|Performs a flood fill from the pair of coordinates provided, adding to the selection all the connected spaces with the same terrain type as the starting location. It does not fill across diagonals.
 |<tt>floodfill (34,15)</tt>
 |-
@@ Line 321: / Line 321: @@
   RANDOM_PLACES:place,...
-With this command you can set up to 10 coordinate registers, which you can access by using <tt>place[N]</tt> instead of a pair of coordinates in any other command. The registers are shuffled at level creation time.
+With this command you can set up to 10 coordinate-pair registers, which you can access by using <tt>place[N]</tt> instead of a pair of coordinates in any other command. The registers are shuffled at level creation time.
 Example:
@@ Line 386: / Line 386: @@
 Places a stair within an area covered by (x1,y1,x2,y2) and not covered by (x3,y3,x4,y4).
 *<tt>updown</tt> is either <tt>up</tt> or <tt>down</tt>, denoting the direction of the stairs.
-If the area is prefixed with <tt>levregion</tt> then the coordinatess are relative to the whole level, otherwise the coordinates are relative to the last-defined {{sa|MAP}}.
+If the area is prefixed with <tt>levregion</tt> then the coordinates are relative to the whole level, otherwise the coordinates are relative to the last-defined {{sa|MAP}}.
 Example:
@@ Line 459: / Line 459: @@
   LADDER:place, updown
-Places a ladder up or down at the given coordinates. See also {{sa|STAIRS}}.
+Places a ladder up or down at the given place. See also {{sa|STAIRS}}.
 *<tt>place</tt> is either a pair of coordinates, a {{sa|RANDOM_PLACES}} place, or <tt>random</tt>
@@ Line 520: / Line 520: @@
 *<tt>chance</tt> is optional; if type is something other than "ordinary", this represents the chance (in percent) that the room will actually be generated as this special room type. Otherwise it will be an ordinary room.
 *<tt>lighted</tt> is one of <tt>lit</tt>, <tt>unlit</tt> or <tt>random</tt>.
-*<tt>pos</tt> is either <tt>random</tt> or <tt>(xpos, ypos)</tt>, where both <tt>xpos</tt> and <tt>ypos</tt> are between 0 and 5. This is an approximate pair of coordinates on the screen.
+*<tt>pos</tt> is either <tt>random</tt> or <tt>(xpos, ypos)</tt>, where both <tt>xpos</tt> and <tt>ypos</tt> are between 0 and 5. This is an approximate position.
 *<tt>align</tt> is either <tt>random</tt> or <tt>(xalign, yalign)</tt> and is the room alignment within the <tt>pos</tt>.
 **<tt>xalign</tt> is one of <tt>left</tt>, <tt>half-left</tt>, <tt>center</tt>, <tt>half-right</tt>, <tt>right</tt> or <tt>random</tt>
@@ Line 584: / Line 584: @@
 ===Common syntax===
-The following commands are common to both MAZE and ROOM-type levels. For the MAZE-levels, the coordinates used are the previously defined MAP, for ROOM-levels, it's either the previously defined ROOM or SUBROOM.
+The following commands are common to both MAZE and ROOM-type levels. For the MAZE levels, the coordinates used are the previously defined MAP, for ROOM-levels, it's either the previously defined ROOM or SUBROOM.
 ===ALTAR===
   ALTAR:place,align,type
-Places an altar on the previously defined map or ROOM or SUBROOM.
+Places an altar in the previously defined map or ROOM or SUBROOM.
 *<tt>place</tt> is either a pair of coordinates, a {{sa|RANDOM_PLACES}} place, or <tt>random</tt>

@@ Line 89: / Line 89: @@
   $mon_index = 1d4 - 1
   MONSTER:($mon_letters[$mon_index],$mon_names[$mon_index]),(10,18)
 === Shorthand for conditionals ===