doc/dgn_comp.6

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