Document explicitly what m-prefix does to each command
[aNetHack.git] / doc / dgn_comp.txt
blob907a4f0a6732c1977e234b140fc30213ab351374
4 DGN_COMP(6)                   1995                    DGN_COMP(6)
8 NAME
9      dgn_comp - NetHack dungeon compiler
11 SYNOPSIS
12      dgn_comp [ file ]
14      If no arguments are given, it reads standard input.
16 DESCRIPTION
17      Dgn_comp is a dungeon compiler for NetHack version  3.2  and
18      higher.  It takes a description file as an argument and pro-
19      duces a dungeon "script" that is to be loaded by NetHack  at
20      runtime.
22      The purpose of this tool is to provide  NetHack  administra-
23      tors and implementors with a convenient way to create a cus-
24      tom dungeon for the game, without having  to  recompile  the
25      entire world.
27 GRAMMAR
28      DUNGEON: name bonesmarker ( base , rand ) [ %age ]
30      where name is the dungeon name, bonesmarker is a letter  for
31      marking  bones  files, ( base , rand ) is the number of lev-
32      els, and %age is its percentage chance  of  being  generated
33      (if absent, 100% chance).
35      DESCRIPTION: tag
37      where tag is currently one of HELLISH, MAZELIKE,  or  ROGUE-
38      LIKE.
40      ALIGNMENT |  LEVALIGN:  [  lawful  |  neutral  |  chaotic  |
41      unaligned ]
43      gives  the  alignment  of  the  dungeon/level  (default   is
44      unaligned).
46      ENTRY: level
48      the dungeon entry point.  The dungeon connection attaches at
49      this  level  of the given dungeon.  If the value of level is
50      negative, the entry level is calculated from the  bottom  of
51      the  dungeon, with -1 being the last level.  If this line is
52      not present  in  a  dungeon  description,  the  entry  level
53      defaults to 1.
55      PROTOFILE: name
57      the prototypical  name  for  dungeon  level  files  in  this
58      dungeon.   For  example,  the PROTOFILE name for the dungeon
59      Vlad's Tower is tower.
63 Dec                      Last change: 12                        1
70 DGN_COMP(6)                   1995                    DGN_COMP(6)
74      LEVEL: name bonesmarker @ ( base , rand ) [ %age ]
76      where name is the level name, bonesmarker is  a  letter  for
77      marking  bones  files,  (  base , rand ) is the location and
78      %age is the generation percentage, as above.
80      RNDLEVEL: name bonesmarker @ (  base  ,  rand  )  [  %age  ]
81      rndlevs
83      where name is the level name, bonesmarker is  a  letter  for
84      marking  bones  files, ( base , rand ) is the location, %age
85      is the generation percentage, as above, and rndlevs  is  the
86      number of similar levels available to choose from.
88      CHAINLEVEL: name bonesmarker prev_name + ( base , rand  )  [
89      %age ]
91      where name is the level name, bonesmarker is  a  letter  for
92      marking  bones  files,  prev_name  is  the  name  of a level
93      defined previously, ( base , rand ) is the offset  from  the
94      level being chained from, and %age is the generation percen-
95      tage.
97      RNDCHAINLEVEL: name bonesmarker prev_name + ( base , rand  )
98      [ %age ] rndlevs
100      where name is the level name, bonesmarker is  a  letter  for
101      marking  bones  files,  prev_name  is  the  name  of a level
102      defined previously, ( base , rand ) is the offset  from  the
103      level being chained from, %age is the generation percentage,
104      and rndlevs is the number of  similar  levels  available  to
105      choose from.
107      LEVELDESC: type
109      where type is the level type, (see DESCRIPTION, above).  The
110      type  is used to override any pre-set value used to describe
111      the entire dungeon, for this level only.
113      BRANCH: name @ ( base , rand ) [ stair | no_up |  no_down  |
114      portal ] [ up | down ]
116      where name is the name of the dungeon to branch  to,  and  (
117      base  ,  rand ) is the location of the branch.  The last two
118      optional arguments are the branch type and branch direction.
119      The  type  of  a branch can be a two-way stair connection, a
120      one-way stair connection, or  a  magic  portal.   A  one-way
121      stair  is  described  by  the  types no_up and no_down which
122      specify which  stair  direction  is  missing.   The  default
123      branch  type  is  stair.   The  direction for a stair can be
124      either up or down; direction is not applicable  to  portals.
125      The default direction is down.
129 Dec                      Last change: 12                        2
136 DGN_COMP(6)                   1995                    DGN_COMP(6)
140      CHAINBRANCH: name prev_name + ( base ,  rand  )  [  stair  |
141      no_up | no_down | portal ] [ up | down ]
143      where name  is  the  name  of  the  dungeon  to  branch  to,
144      prev_name  is  the  name of a previously defined level and (
145      base , rand ) is the offset from  the  level  being  chained
146      from.   The  optional branch type and direction are the same
147      as described above.
149 GENERIC RULES
150      Each dungeon must have a unique bonesmarker , and each  spe-
151      cial level must have a bonesmarker unique within its dungeon
152      (letters may be  reused  in  different  dungeons).   If  the
153      bonesmarker  has  the  special  value "none", no bones files
154      will be created for that level or dungeon.
156      The value base may be in the range  of  1  to  MAXLEVEL  (as
157      defined in global.h ).
159      The value rand may be in the range of -1 to MAXLEVEL.
161      If  rand  is  -1  it  will  be  replaced  with   the   value
162      (num_dunlevs(dungeon)  -  base) during the load process (ie.
163      from here to the end of the dungeon).
165      If rand is 0 the level is located absolutely at base.
167      Branches don't have  a  probability.   Dungeons  do.   If  a
168      dungeon  fails  to  be generated during load, all its levels
169      and branches are skipped.
171      No level or branch may be chained from a level with  a  per-
172      centage  generation  probability.   This  is to prevent non-
173      resolution during the load.  In addition, no branch  may  be
174      made from a dungeon with a percentage generation probability
175      for the same reason.
177      As a general rule using the dungeon compiler:
179      If a dungeon has a protofile name associated  with  it  (eg.
180      tower) that file will be used.
182      If a special level is present, it will  override  the  above
183      rule and the appropriate file will be loaded.
185      If neither of the above are present, the standard  generator
186      will take over and make a "normal" level.
188      A level alignment, if present, will override  the  alignment
189      of the dungeon that it exists within.
195 Dec                      Last change: 12                        3
202 DGN_COMP(6)                   1995                    DGN_COMP(6)
206 EXAMPLE
207      Here  is  the  current  syntax  of  the  dungeon  compiler's
208      "language":
211      #
212      #       The dungeon description file for the "standard" original
213      #       3.0 NetHack.
214      #
215      DUNGEON:        "The Dungeons of Doom" "D" (25, 5)
216      LEVEL:          "rogue" "none" @ (15, 4)
217      LEVEL:          "oracle" "none" @ (5, 7)
218      LEVEL:          "bigroom" "B" @ (12, 3) 15
219      LEVEL:          "medusa" "none" @ (20, 5)
220      CHAINLEVEL:     "castle" "medusa" + (1, 4)
221      CHAINBRANCH:    "Hell" "castle" + (0, 0) no_down
222      BRANCH:         "The Astral Plane" @ (1, 0) no_down up
224      DUNGEON:        "Hell" "H" (25, 5)
225      DESCRIPTION:    mazelike
226      DESCRIPTION:    hellish
227      BRANCH:         "Vlad's Tower" @ (13, 5) up
228      LEVEL:          "wizard" "none" @ (15, 10)
229      LEVEL:          "fakewiz" "A" @ (5, 5)
230      LEVEL:          "fakewiz" "B" @ (10, 5)
231      LEVEL:          "fakewiz" "C" @ (15, 5)
232      LEVEL:          "fakewiz" "D" @ (20, 5)
233      LEVEL:          "fakewiz" "E" @ (25, 5)
235      DUNGEON:        "Vlad's Tower" "T" (3, 0)
236      PROTOFILE:      "tower"
237      DESCRIPTION:    mazelike
238      ENTRY:          -1
240      DUNGEON:        "The Astral Plane" "A" (1, 0)
241      DESCRIPTION:    mazelike
242      PROTOFILE:      "endgame"
244      NOTES:
245      Lines beginning with '#' are considered comments.
246      A special level must be explicitly aligned.   The  alignment
247      of  the  dungeon it is in only applies to non-special levels
248      within that dungeon.
250 AUTHOR
251      M. Stephenson (from the level  compiler  by  Jean-Christophe
252      Collet).
254 SEE ALSO
255      lev_comp(6), nethack(6)
261 Dec                      Last change: 12                        4
268 DGN_COMP(6)                   1995                    DGN_COMP(6)
272 BUGS
273      Probably infinite.
327 Dec                      Last change: 12                        5