doc/dgn_comp.6

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