doc/dgn_comp.txt

   1
   2
   3
   4 DGN_COMP(6)                   1995                    DGN_COMP(6)
   5
   6
   7
   8 NAME
   9      dgn_comp - NetHack dungeon compiler
  10
  11 SYNOPSIS
  12      dgn_comp [ file ]
  13
  14      If no arguments are given, it reads standard input.
  15
  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.
  21
  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.
  26
  27 GRAMMAR
  28      DUNGEON: name bonesmarker ( base , rand ) [ %age ]
  29
  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).
  34
  35      DESCRIPTION: tag
  36
  37      where tag is currently one of HELLISH, MAZELIKE,  or  ROGUE-
  38      LIKE.
  39
  40      ALIGNMENT |  LEVALIGN:  [  lawful  |  neutral  |  chaotic  |
  41      unaligned ]
  42
  43      gives  the  alignment  of  the  dungeon/level  (default   is
  44      unaligned).
  45
  46      ENTRY: level
  47
  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.
  54
  55      PROTOFILE: name
  56
  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.
  60
  61
  62
  63 Dec                      Last change: 12                        1
  64
  65
  66
  67
  68
  69
  70 DGN_COMP(6)                   1995                    DGN_COMP(6)
  71
  72
  73
  74      LEVEL: name bonesmarker @ ( base , rand ) [ %age ]
  75
  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.
  79
  80      RNDLEVEL: name bonesmarker @ (  base  ,  rand  )  [  %age  ]
  81      rndlevs
  82
  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.
  87
  88      CHAINLEVEL: name bonesmarker prev_name + ( base , rand  )  [
  89      %age ]
  90
  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.
  96
  97      RNDCHAINLEVEL: name bonesmarker prev_name + ( base , rand  )
  98      [ %age ] rndlevs
  99
 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.
 106
 107      LEVELDESC: type
 108
 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.
 112
 113      BRANCH: name @ ( base , rand ) [ stair | no_up |  no_down  |
 114      portal ] [ up | down ]
 115
 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.
 126
 127
 128
 129 Dec                      Last change: 12                        2
 130
 131
 132
 133
 134
 135
 136 DGN_COMP(6)                   1995                    DGN_COMP(6)
 137
 138
 139
 140      CHAINBRANCH: name prev_name + ( base ,  rand  )  [  stair  |
 141      no_up | no_down | portal ] [ up | down ]
 142
 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.
 148
 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.
 155
 156      The value base may be in the range  of  1  to  MAXLEVEL  (as
 157      defined in global.h ).
 158
 159      The value rand may be in the range of -1 to MAXLEVEL.
 160
 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).
 164
 165      If rand is 0 the level is located absolutely at base.
 166
 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.
 170
 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.
 176
 177      As a general rule using the dungeon compiler:
 178
 179      If a dungeon has a protofile name associated  with  it  (eg.
 180      tower) that file will be used.
 181
 182      If a special level is present, it will  override  the  above
 183      rule and the appropriate file will be loaded.
 184
 185      If neither of the above are present, the standard  generator
 186      will take over and make a "normal" level.
 187
 188      A level alignment, if present, will override  the  alignment
 189      of the dungeon that it exists within.
 190
 191
 192
 193
 194
 195 Dec                      Last change: 12                        3
 196
 197
 198
 199
 200
 201
 202 DGN_COMP(6)                   1995                    DGN_COMP(6)
 203
 204
 205
 206 EXAMPLE
 207      Here  is  the  current  syntax  of  the  dungeon  compiler's
 208      "language":
 209
 210
 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
 223
 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)
 234
 235      DUNGEON:        "Vlad's Tower" "T" (3, 0)
 236      PROTOFILE:      "tower"
 237      DESCRIPTION:    mazelike
 238      ENTRY:          -1
 239
 240      DUNGEON:        "The Astral Plane" "A" (1, 0)
 241      DESCRIPTION:    mazelike
 242      PROTOFILE:      "endgame"
 243
 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.
 249
 250 AUTHOR
 251      M. Stephenson (from the level  compiler  by  Jean-Christophe
 252      Collet).
 253
 254 SEE ALSO
 255      lev_comp(6), nethack(6)
 256
 257
 258
 259
 260
 261 Dec                      Last change: 12                        4
 262
 263
 264
 265
 266
 267
 268 DGN_COMP(6)                   1995                    DGN_COMP(6)
 269
 270
 271
 272 BUGS
 273      Probably infinite.
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327 Dec                      Last change: 12                        5
 328
 329
 330