doc/lev_comp.6

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