doc/lev_comp.6

   1 .TH LEV_COMP 6 "16 May 1996"
   2 .\" NetHack 3.6  lev_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 lev_comp \- NetHack special levels compiler
   6 .SH SYNOPSIS
   7 .B lev_comp
   8 [
   9 .B \-w
  10 ]
  11 [
  12 .I files
  13 ]
  14 .PP
  15 If no arguments are given, it reads standard input.
  16 .SH DESCRIPTION
  17 .PP
  18 .I Lev_comp
  19 is a special level compiler for NetHack version 3.2 and higher.  It
  20 takes description files as arguments and produces level files that can
  21 be loaded by NetHack at runtime.
  22 .PP
  23 The purpose of this tool is to provide NetHack administrators and
  24 implementors with a convenient way for adding special levels to the
  25 game, or modifying existing ones, without having to recompile the
  26 entire world.
  27 .PP
  28 The
  29 .B \-w
  30 option causes
  31 .I lev_comp
  32 to perform extra checks on the level and display extra warnings, however
  33 these warnings are sometimes superfluous, so they are not normally displayed.
  34
  35 .SH GRAMMAR
  36 .PP
  37 .LP
  38 .nf
  39 .ta +8n +8n +8n +8n
  40
  41 file            : /* nothing */
  42                 | levels
  43                 ;
  44
  45 levels          : level
  46                 | level levels
  47                 ;
  48
  49 level           : maze_level
  50                 | room_level
  51                 ;
  52
  53 maze_level      : maze_def flags lev_init messages regions
  54                 ;
  55
  56 room_level      : level_def flags lev_init messages rreg_init rooms corridors_def
  57                 ;
  58
  59 level_def       : LEVEL_ID ':' string
  60                 ;
  61
  62 lev_init        : /* nothing */
  63                 | LEV_INIT_ID ':' CHAR ',' CHAR ',' BOOLEAN ',' BOOLEAN ',' light_state ',' walled
  64                 ;
  65
  66 walled          : BOOLEAN
  67                 | RANDOM_TYPE
  68                 ;
  69
  70 flags           : /* nothing */
  71                 | FLAGS_ID ':' flag_list
  72                 ;
  73
  74 flag_list       : FLAG_TYPE ',' flag_list
  75                 | FLAG_TYPE
  76                 ;
  77
  78 messages        : /* nothing */
  79                 | message messages
  80                 ;
  81
  82 message         : MESSAGE_ID ':' STRING
  83                 ;
  84
  85 rreg_init       : /* nothing */
  86                 | rreg_init init_rreg
  87                 ;
  88
  89 init_rreg       : RANDOM_OBJECTS_ID ':' object_list
  90                 | RANDOM_MONSTERS_ID ':' monster_list
  91                 ;
  92
  93 rooms           : /* Nothing  -  dummy room for use with INIT_MAP */
  94                 | roomlist
  95                 ;
  96
  97 roomlist        : aroom
  98                 | aroom roomlist
  99                 ;
 100
 101 corridors_def   : random_corridors
 102                 | corridors
 103                 ;
 104
 105 random_corridors: RAND_CORRIDOR_ID
 106                 ;
 107
 108 corridors       : /* nothing */
 109                 | corridors corridor
 110                 ;
 111
 112 corridor        : CORRIDOR_ID ':' corr_spec ',' corr_spec
 113                 | CORRIDOR_ID ':' corr_spec ',' INTEGER
 114                 ;
 115
 116 corr_spec       : '(' INTEGER ',' DIRECTION ',' door_pos ')'
 117                 ;
 118
 119 aroom           : room_def room_details
 120                 | subroom_def room_details
 121                 ;
 122
 123 subroom_def     : SUBROOM_ID ':' room_type ',' light_state ',' subroom_pos ',' room_size ',' string roomfill
 124                 ;
 125
 126 room_def        : ROOM_ID ':' room_type ',' light_state ',' room_pos ',' room_align ',' room_size roomfill
 127                 ;
 128
 129 roomfill        : /* nothing */
 130                 | ',' BOOLEAN
 131                 ;
 132
 133 room_pos        : '(' INTEGER ',' INTEGER ')'
 134                 | RANDOM_TYPE
 135                 ;
 136
 137 subroom_pos     : '(' INTEGER ',' INTEGER ')'
 138                 | RANDOM_TYPE
 139                 ;
 140
 141 room_align      : '(' h_justif ',' v_justif ')'
 142                 | RANDOM_TYPE
 143                 ;
 144
 145 room_size       : '(' INTEGER ',' INTEGER ')'
 146                 | RANDOM_TYPE
 147                 ;
 148
 149 room_details    : /* nothing */
 150                 | room_details room_detail
 151                 ;
 152
 153 room_detail     : room_name
 154                 | room_chance
 155                 | room_door
 156                 | monster_detail
 157                 | object_detail
 158                 | trap_detail
 159                 | altar_detail
 160                 | fountain_detail
 161                 | sink_detail
 162                 | pool_detail
 163                 | gold_detail
 164                 | engraving_detail
 165                 | stair_detail
 166                 ;
 167
 168 room_name       : NAME_ID ':' string
 169                 ;
 170
 171 room_chance     : CHANCE_ID ':' INTEGER
 172                 ;
 173
 174 room_door       : DOOR_ID ':' secret ',' door_state ',' door_wall ',' door_pos
 175                 ;
 176
 177 secret          : BOOLEAN
 178                 | RANDOM_TYPE
 179                 ;
 180
 181 door_wall       : DIRECTION
 182                 | RANDOM_TYPE
 183                 ;
 184
 185 door_pos        : INTEGER
 186                 | RANDOM_TYPE
 187                 ;
 188
 189 maze_def        : MAZE_ID ':' string ',' filling
 190                 ;
 191
 192 filling         : CHAR
 193                 | RANDOM_TYPE
 194                 ;
 195
 196 regions         : aregion
 197                 | aregion regions
 198                 ;
 199
 200 aregion         : map_definition reg_init map_details
 201                 ;
 202
 203 map_definition  : NOMAP_ID
 204                 | map_geometry MAP_ID
 205                 ;
 206
 207 map_geometry    : GEOMETRY_ID ':' h_justif ',' v_justif
 208                 ;
 209
 210 h_justif        : LEFT_OR_RIGHT
 211                 | CENTER
 212                 ;
 213
 214 v_justif        : TOP_OR_BOT
 215                 | CENTER
 216                 ;
 217
 218 reg_init        : /* nothing */
 219                 | reg_init init_reg
 220                 ;
 221
 222 init_reg        : RANDOM_OBJECTS_ID ':' object_list
 223                 | RANDOM_PLACES_ID ':' place_list
 224                 | RANDOM_MONSTERS_ID ':' monster_list
 225                 ;
 226
 227 object_list     : object
 228                 | object ',' object_list
 229                 ;
 230
 231 monster_list    : monster
 232                 | monster ',' monster_list
 233                 ;
 234
 235 place_list      : place
 236                 | place ',' place_list
 237                 ;
 238
 239 map_details     : /* nothing */
 240                 | map_details map_detail
 241                 ;
 242
 243 map_detail      : monster_detail
 244                 | object_detail
 245                 | door_detail
 246                 | trap_detail
 247                 | drawbridge_detail
 248                 | region_detail
 249                 | stair_region
 250                 | portal_region
 251                 | teleprt_region
 252                 | branch_region
 253                 | altar_detail
 254                 | fountain_detail
 255                 | mazewalk_detail
 256                 | wallify_detail
 257                 | ladder_detail
 258                 | stair_detail
 259                 | gold_detail
 260                 | engraving_detail
 261                 | diggable_detail
 262                 | passwall_detail
 263                 ;
 264
 265 monster_detail  : MONSTER_ID chance ':' monster_c ',' m_name ',' coordinate
 266                  monster_infos
 267                 ;
 268
 269 monster_infos   : /* nothing */
 270                 | monster_infos monster_info
 271                 ;
 272
 273 monster_info    : ',' string
 274                 | ',' MON_ATTITUDE
 275                 | ',' MON_ALERTNESS
 276                 | ',' alignment
 277                 | ',' MON_APPEARANCE string
 278                 ;
 279
 280 object_detail   : OBJECT_ID object_desc
 281                 | COBJECT_ID object_desc
 282                 ;
 283
 284 object_desc     : chance ':' object_c ',' o_name ',' object_where object_infos
 285                 ;
 286
 287 object_where    : coordinate
 288                 | CONTAINED
 289                 ;
 290
 291 object_infos    : /* nothing */
 292                 | ',' curse_state ',' monster_id ',' enchantment optional_name
 293                 | ',' curse_state ',' enchantment optional_name
 294                 | ',' monster_id ',' enchantment optional_name
 295                 ;
 296
 297 curse_state     : RANDOM_TYPE
 298                 | CURSE_TYPE
 299                 ;
 300
 301 monster_id      : STRING
 302                 ;
 303
 304 enchantment     : RANDOM_TYPE
 305                 | INTEGER
 306                 ;
 307
 308 optional_name   : /* nothing */
 309                 | ',' NONE
 310                 | ',' STRING
 311                 ;
 312
 313 door_detail     : DOOR_ID ':' door_state ',' coordinate
 314                 ;
 315
 316 trap_detail     : TRAP_ID chance ':' trap_name ',' coordinate
 317                 ;
 318
 319 drawbridge_detail: DRAWBRIDGE_ID ':' coordinate ',' DIRECTION ',' door_state
 320                 ;
 321
 322 mazewalk_detail : MAZEWALK_ID ':' coordinate ',' DIRECTION
 323                 ;
 324
 325 wallify_detail  : WALLIFY_ID
 326                 ;
 327
 328 ladder_detail   : LADDER_ID ':' coordinate ',' UP_OR_DOWN
 329                 ;
 330
 331 stair_detail    : STAIR_ID ':' coordinate ',' UP_OR_DOWN
 332                 ;
 333
 334 stair_region    : STAIR_ID ':' lev_region ',' lev_region ',' UP_OR_DOWN
 335                 ;
 336
 337 portal_region   : PORTAL_ID ':' lev_region ',' lev_region ',' string
 338                 ;
 339
 340 teleprt_region  : TELEPRT_ID ':' lev_region ',' lev_region teleprt_detail
 341                 ;
 342
 343 branch_region   : BRANCH_ID ':' lev_region ',' lev_region
 344                 ;
 345
 346 teleprt_detail  : /* empty */
 347                 | ',' UP_OR_DOWN
 348                 ;
 349
 350 lev_region      : region
 351                 | LEV '(' INTEGER ',' INTEGER ',' INTEGER ',' INTEGER ')'
 352                 ;
 353
 354 fountain_detail : FOUNTAIN_ID ':' coordinate
 355                 ;
 356
 357 sink_detail : SINK_ID ':' coordinate
 358                 ;
 359
 360 pool_detail : POOL_ID ':' coordinate
 361                 ;
 362
 363 diggable_detail : NON_DIGGABLE_ID ':' region
 364                 ;
 365
 366 passwall_detail : NON_PASSWALL_ID ':' region
 367                 ;
 368
 369 region_detail   : REGION_ID ':' region ',' light_state ',' room_type prefilled
 370                 ;
 371
 372 altar_detail    : ALTAR_ID ':' coordinate ',' alignment ',' altar_type
 373                 ;
 374
 375 gold_detail     : GOLD_ID ':' amount ',' coordinate
 376                 ;
 377
 378 engraving_detail: ENGRAVING_ID ':' coordinate ',' engraving_type ',' string
 379                 ;
 380
 381 monster_c       : monster
 382                 | RANDOM_TYPE
 383                 | m_register
 384                 ;
 385
 386 object_c        : object
 387                 | RANDOM_TYPE
 388                 | o_register
 389                 ;
 390
 391 m_name          : string
 392                 | RANDOM_TYPE
 393                 ;
 394
 395 o_name          : string
 396                 | RANDOM_TYPE
 397                 ;
 398
 399 trap_name       : string
 400                 | RANDOM_TYPE
 401                 ;
 402
 403 room_type       : string
 404                 | RANDOM_TYPE
 405                 ;
 406
 407 prefilled       : /* empty */
 408                 | ',' FILLING
 409                 | ',' FILLING ',' BOOLEAN
 410                 ;
 411
 412 coordinate      : coord
 413                 | p_register
 414                 | RANDOM_TYPE
 415                 ;
 416
 417 door_state      : DOOR_STATE
 418                 | RANDOM_TYPE
 419                 ;
 420
 421 light_state     : LIGHT_STATE
 422                 | RANDOM_TYPE
 423                 ;
 424
 425 alignment       : ALIGNMENT
 426                 | a_register
 427                 | RANDOM_TYPE
 428                 ;
 429
 430 altar_type      : ALTAR_TYPE
 431                 | RANDOM_TYPE
 432                 ;
 433
 434 p_register      : P_REGISTER '[' INTEGER ']'
 435                 ;
 436
 437 o_register      : O_REGISTER '[' INTEGER ']'
 438                 ;
 439
 440 m_register      : M_REGISTER '[' INTEGER ']'
 441                 ;
 442
 443 a_register      : A_REGISTER '[' INTEGER ']'
 444                 ;
 445
 446 place           : coord
 447                 ;
 448
 449 monster         : CHAR
 450                 ;
 451
 452 object          : CHAR
 453                 ;
 454
 455 string          : STRING
 456                 ;
 457
 458 amount          : INTEGER
 459                 | RANDOM_TYPE
 460                 ;
 461
 462 chance          : /* empty */
 463                 | PERCENT
 464                 ;
 465
 466 engraving_type  : ENGRAVING_TYPE
 467                 | RANDOM_TYPE
 468                 ;
 469
 470 coord           : '(' INTEGER ',' INTEGER ')'
 471                 ;
 472
 473 region          : '(' INTEGER ',' INTEGER ',' INTEGER ',' INTEGER ')'
 474                 ;
 475 .fi
 476 .PP
 477 .I NOTE:
 478 .br
 479 Lines beginning with '#' are considered comments.
 480 .PP
 481 The contents of a "MAP" description of a maze is a rectangle showing the exact
 482 level map that should be used for the given part of a maze.
 483 Each character in the map corresponds to a location on the screen.
 484 Different location types are denoted using different ASCII characters.
 485 The following characters are recognized.
 486 To give an idea of how these are used, see the EXAMPLE, below.
 487 The maximum size of a map is normally 76 columns by 21 rows.
 488 .LP
 489 .nf
 490 .ta +8n +8n +8n
 491 \&'-'   horizontal wall
 492 \&'|'   vertical wall
 493 \&'+'   a doorway (state is specified in a DOOR declaration)
 494 \&'A'   open air
 495 \&'B'   boundary room location (for bounding unwalled irregular regions)
 496 \&'C'   cloudy air
 497 \&'I'   ice
 498 \&'S'   a secret door
 499 \&'H'   a secret corridor
 500 \&'{'   a fountain
 501 \&'\\'  a throne
 502 \&'K'   a sink
 503 \&'}'   a part of a moat or other deep water
 504 \&'P'   a pool
 505 \&'L'   lava
 506 \&'W'   water (yes, different from a pool)
 507 \&'T'   a tree
 508 \&'F'   iron bars
 509 \&'#'   a corridor
 510 \&'.'   a normal room location (unlit unless lit in a REGION declaration)
 511 \&' '   stone
 512 .fi
 513 .SH EXAMPLE
 514 .PP
 515 Here is an example of a description file (a very simple one):
 516 .LP
 517 .nf
 518 .ta +8n +8n +8n
 519 MAZE : "fortress", random
 520 GEOMETRY : center , center
 521 MAP
 522 }}}}}}}}}
 523 }}}|-|}}}
 524 }}|-.-|}}
 525 }|-...-|}
 526 }|.....|}
 527 }|-...-|}
 528 }}|-.-|}}
 529 }}}|-|}}}
 530 }}}}}}}}}
 531 ENDMAP
 532 MONSTER: '@', "Wizard of Yendor", (4,4)
 533 OBJECT: '"', "Amulet of Yendor", (4,4)
 534 # a hell hound flanking the Wiz on a random side
 535 RANDOM_PLACES: (4,3), (4,5), (3,4), (5,4)
 536 MONSTER: 'd', "hell hound", place[0]
 537 # a chest on another random side
 538 OBJECT: '(', "chest", place[1]
 539 # a sack on a random side, with a diamond and maybe a ruby in it
 540 CONTAINER: '(', "sack", place[2]
 541 OBJECT: '*', "diamond", contained
 542 OBJECT[50%]: '*', "ruby", contained
 543 # a random dragon somewhere
 544 MONSTER: 'D', random, random
 545 # 3 out of 4 chance for a random trap in the EAST end
 546 TRAP[75%]: random, (6,4)
 547 # an electric eel below the SOUTH end
 548 MONSTER: ';', "electric eel", (4,8)
 549 # make the walls non-diggable
 550 NON_DIGGABLE: (0,0,8,8)
 551 TELEPORT_REGION: levregion(0,0,79,20), (0,0,8,8)
 552 .fi
 553 .PP
 554 This example will produce a file named "fortress" that can be integrated into
 555 one of the numerous mazes of the game.
 556 .PP
 557 Note especially the final, TELEPORT_REGION specification.  This says
 558 that level teleports or other non-stairway arrivals on this level can
 559 land anywhere on the level except the area of the map.  This shows the
 560 use of the ``levregion'' prefix allowed in certain region specifications.
 561 Normally, regions apply only to the most recent MAP specification, but
 562 when prefixed with ``levregion'', one can refer to any area of the
 563 level, regardless of the placement of the current MAP in the level.
 564 .SH AUTHOR
 565 .PP
 566 Jean-Christophe Collet, David Cohrs.
 567 .SH "SEE ALSO"
 568 .PP
 569 dgn_comp(6), nethack(6)
 570 .SH BUGS
 571 .PP
 572 Probably infinite.
 573 Most importantly, still needs additional bounds checking.