doc/dgn_comp.6

   1 .TH DGN_COMP 6 "12 Dec 1995"
   2 .UC 4
   3 .SH NAME
   4 dgn_comp \- NetHack dungeon compiler
   5 .SH SYNOPSIS
   6 .B dgn_comp
   7 [
   8 .I file
   9 ]
  10 .PP
  11 If no arguments are given, it reads standard input.
  12 .SH DESCRIPTION
  13 .PP
  14 .I Dgn_comp
  15 is a dungeon compiler for NetHack version 3.2 and higher.  It
  16 takes a description file as an argument and produces a dungeon "script"
  17 that is to be loaded by NetHack at runtime.
  18 .PP
  19 The purpose of this tool is to provide NetHack administrators and
  20 implementors with a convenient way to create a custom dungeon for the
  21 game, without having to recompile the entire world.
  22 .SH GRAMMAR
  23 .PP
  24 DUNGEON:
  25 .B name
  26 .B bonesmarker
  27 (
  28 .B base
  29 ,
  30 .B rand
  31 ) [
  32 .B %age
  33 ]
  34 .PP
  35 where
  36 .B name
  37 is the dungeon name,
  38 .B bonesmarker
  39 is a letter for marking bones files, (
  40 .B base
  41 ,
  42 .B rand
  43 ) is the number of levels, and
  44 .B %age
  45 is its percentage chance of being generated (if absent, 100% chance).
  46
  47 DESCRIPTION:
  48 .B tag
  49 .PP
  50 where
  51 .B tag
  52 is currently one of
  53 .BR HELLISH ,
  54 .BR MAZELIKE ,
  55 or
  56 .BR ROGUELIKE .
  57
  58 ALIGNMENT | LEVALIGN: [
  59 .B lawful
  60 |
  61 .B neutral
  62 |
  63 .B chaotic
  64 |
  65 .B unaligned
  66 ]
  67 .PP
  68 gives the alignment of the dungeon/level (default is unaligned).
  69
  70 ENTRY:
  71 .B level
  72 .PP
  73 the dungeon entry point.  The dungeon connection attaches at this
  74 level of the given dungeon.
  75 If the value of
  76 .B level
  77 is negative, the entry level is calculated from the bottom of the
  78 dungeon, with -1 being the last level.
  79 If this line is not present in a dungeon description, the entry level
  80 defaults to 1.
  81
  82 PROTOFILE:
  83 .B name
  84 .PP
  85 the prototypical name for dungeon level files in this dungeon.
  86 For example, the PROTOFILE name for the dungeon
  87 .I Vlad's Tower
  88 is
  89 .IR tower .
  90
  91 LEVEL:
  92 .B name
  93 .B bonesmarker
  94 @ (
  95 .B base
  96 ,
  97 .B rand
  98 ) [
  99 .B %age
 100 ]
 101 .PP
 102 where
 103 .B name
 104 is the level name,
 105 .B bonesmarker
 106 is a letter for marking bones files, (
 107 .B base
 108 ,
 109 .B rand
 110 ) is the location and
 111 .B %age
 112 is the generation percentage, as above.
 113
 114 RNDLEVEL:
 115 .B name
 116 .B bonesmarker
 117 @ (
 118 .B base
 119 ,
 120 .B rand
 121 )
 122 [
 123 .B %age
 124 ]
 125 .B rndlevs
 126 .PP
 127 where
 128 .B name
 129 is the level name,
 130 .B bonesmarker
 131 is a letter for marking bones files, (
 132 .B base
 133 ,
 134 .B rand
 135 ) is the location,
 136 .B %age
 137 is the generation percentage, as above, and
 138 .B rndlevs
 139 is the number of similar levels available to choose from.
 140
 141 CHAINLEVEL:
 142 .B name
 143 .B bonesmarker
 144 .B prev_name
 145 + (
 146 .B base
 147 ,
 148 .B rand
 149 ) [
 150 .B %age
 151 ]
 152 .PP
 153 where
 154 .B name
 155 is the level name,
 156 .B bonesmarker
 157 is a letter for marking bones files,
 158 .B prev_name
 159 is the name of a level defined previously, (
 160 .B base
 161 ,
 162 .B rand
 163 ) is the
 164 .I offset
 165 from the level being chained from, and
 166 .B %age
 167 is the generation percentage.
 168
 169 RNDCHAINLEVEL:
 170 .B name
 171 .B bonesmarker
 172 .B prev_name
 173 + (
 174 .B base
 175 ,
 176 .B rand
 177 ) [
 178 .B %age
 179 ]
 180 .B rndlevs
 181 .PP
 182 where
 183 .B name
 184 is the level name,
 185 .B bonesmarker
 186 is a letter for marking bones files,
 187 .B prev_name
 188 is the name of a level defined previously, (
 189 .B base
 190 ,
 191 .B rand
 192 ) is the
 193 .I offset
 194 from the level being chained from,
 195 .B %age
 196 is the generation percentage, and
 197 .B rndlevs
 198 is the number of similar levels available to choose from.
 199
 200 LEVELDESC:
 201 .B type
 202 .PP
 203 where
 204 .B type
 205 is the level type, (see DESCRIPTION, above). The
 206 .B type
 207 is used to override any pre-set value used to describe the entire dungeon,
 208 for this level only.
 209
 210 BRANCH:
 211 .B name
 212 @ (
 213 .B base
 214 ,
 215 .B rand
 216 ) [
 217 .B stair
 218 |
 219 .B no_up
 220 |
 221 .B no_down
 222 |
 223 .B portal
 224 ] [
 225 .B up
 226 |
 227 .B down
 228 ]
 229 .PP
 230 where
 231 .B name
 232 is the name of the dungeon to branch to, and (
 233 .B base
 234 ,
 235 .B rand
 236 ) is the location of the branch.
 237 The last two optional arguments are
 238 the branch type and branch direction.
 239 The type of a branch can be a two-way stair connection,
 240 a one-way stair connection, or a magic portal.
 241 A one-way stair is described by the types
 242 .B no_up
 243 and
 244 .B no_down
 245 which specify which stair direction is missing.
 246 The default branch type is
 247 .BR stair .
 248 The direction for a stair can be either up or down; direction is not
 249 applicable to portals.  The default direction is
 250 .BR down .
 251
 252 CHAINBRANCH:
 253 .B name
 254 .B prev_name
 255 + (
 256 .B base
 257 ,
 258 .B rand
 259 ) [
 260 .B stair
 261 |
 262 .B no_up
 263 |
 264 .B no_down
 265 |
 266 .B portal
 267 ] [
 268 .B up
 269 |
 270 .B down
 271 ]
 272 .PP
 273 where
 274 .B name
 275 is the name of the dungeon to branch to,
 276 .B prev_name
 277 is the name of a previously defined
 278 .B level
 279 and (
 280 .B base
 281 ,
 282 .B rand
 283 ) is the
 284 .I offset
 285 from the level being chained from.
 286 The optional branch type and direction are the same as described above.
 287 .SH GENERIC RULES
 288 .PP
 289 Each dungeon must have a unique
 290 .B bonesmarker ,
 291 and each special level must have a
 292 .B bonesmarker
 293 unique within its dungeon (letters may be reused in different dungeons).
 294 If the
 295 .B bonesmarker
 296 has the special value "none", no bones files will be created for that
 297 level or dungeon.
 298 .PP
 299 The value
 300 .B base
 301 may be in the range of 1 to
 302 .B MAXLEVEL
 303 (as defined in
 304 .I global.h
 305 ).
 306 .PP
 307 The value
 308 .B rand
 309 may be in the range of -1 to
 310 .BR MAXLEVEL .
 311 .PP
 312 If
 313 .B rand
 314 is -1 it will be replaced with the value (num_dunlevs(dungeon) - base)
 315 during the load process (ie. from here to the end of the dungeon).
 316 .PP
 317 If
 318 .B rand
 319 is 0 the level is located absolutely at
 320 .BR base .
 321 .PP
 322 Branches don't have a probability.  Dungeons do.  If a dungeon fails
 323 to be generated during load, all its levels and branches are skipped.
 324 .PP
 325 No level or branch may be chained from a level with a percentage generation
 326 probability.  This is to prevent non-resolution during the load.
 327 In addition, no branch may be made from a dungeon with a percentage
 328 generation probability for the same reason.
 329 .PP
 330 As a general rule using the dungeon compiler:
 331 .PP
 332 If a dungeon has a
 333 .B protofile
 334 name associated with it
 335 .RI ( eg.
 336 .BR tower )
 337 that file will be used.
 338 .PP
 339 If a special level is present, it will override the above rule and
 340 the appropriate file will be loaded.
 341 .PP
 342 If neither of the above are present, the standard generator will
 343 take over and make a "normal" level.
 344 .PP
 345 A level alignment, if present, will override
 346 the alignment of the dungeon that it exists within.
 347 .SH EXAMPLE
 348 .PP
 349 Here is the current syntax of the dungeon compiler's "language":
 350
 351 .LP
 352 .nf
 353 .ta +8n +8n +8n
 354 #
 355 #       The dungeon description file for the "standard" original
 356 #       3.0 NetHack.
 357 #
 358 DUNGEON:        "The Dungeons of Doom" "D" (25, 5)
 359 LEVEL:          "rogue" "none" @ (15, 4)
 360 LEVEL:          "oracle" "none" @ (5, 7)
 361 LEVEL:          "bigroom" "B" @ (12, 3) 15
 362 LEVEL:          "medusa" "none" @ (20, 5)
 363 CHAINLEVEL:     "castle" "medusa" + (1, 4)
 364 CHAINBRANCH:    "Hell" "castle" + (0, 0) no_down
 365 BRANCH:         "The Astral Plane" @ (1, 0) no_down up
 366
 367 DUNGEON:        "Hell" "H" (25, 5)
 368 DESCRIPTION:    mazelike
 369 DESCRIPTION:    hellish
 370 BRANCH:         "Vlad's Tower" @ (13, 5) up
 371 LEVEL:          "wizard" "none" @ (15, 10)
 372 LEVEL:          "fakewiz" "A" @ (5, 5)
 373 LEVEL:          "fakewiz" "B" @ (10, 5)
 374 LEVEL:          "fakewiz" "C" @ (15, 5)
 375 LEVEL:          "fakewiz" "D" @ (20, 5)
 376 LEVEL:          "fakewiz" "E" @ (25, 5)
 377
 378 DUNGEON:        "Vlad's Tower" "T" (3, 0)
 379 PROTOFILE:      "tower"
 380 DESCRIPTION:    mazelike
 381 ENTRY:          -1
 382
 383 DUNGEON:        "The Astral Plane" "A" (1, 0)
 384 DESCRIPTION:    mazelike
 385 PROTOFILE:      "endgame"
 386 .fi
 387 .PP
 388 .I NOTES:
 389 .br
 390 Lines beginning with '#' are considered comments.
 391 .br
 392 A special level must be explicitly aligned.  The alignment of the dungeon
 393 it is in only applies to non-special levels within that dungeon.
 394 .SH AUTHOR
 395 .PP
 396 M. Stephenson (from the level compiler by Jean-Christophe Collet).
 397 .SH "SEE ALSO"
 398 .PP
 399 lev_comp(6), nethack(6)
 400 .SH BUGS
 401 .PP
 402 Probably infinite.