DGN_COMP(6)                                           DGN_COMP(6)



NAME
       dgn_comp - NetHack dungeon compiler

SYNOPSIS
       dgn_comp [ file ]

       If no arguments are given, it reads standard input.

DESCRIPTION
       Dgn_comp is a dungeon compiler for NetHack version 3.2 and
       higher.  It takes a description file as  an  argument  and
       produces  a  dungeon  "script"  that  is  to  be loaded by
       NetHack at runtime.

       The purpose of this tool is to provide NetHack administra-
       tors  and  implementors  with a convenient way to create a
       custom dungeon for the game, without having  to  recompile
       the entire world.

GRAMMAR
       DUNGEON: name bonesmarker ( base , rand ) [ %age ]

       where  name  is  the dungeon name, bonesmarker is a letter
       for marking bones files, ( base , rand ) is the number  of
       levels,  and %age is its percentage chance of being gener-
       ated (if absent, 100% chance).

       DESCRIPTION: tag

       where tag is currently one of HELLISH, MAZELIKE, TOWN,  or
       ROGUELIKE.

       ALIGNMENT  |  LEVALIGN:  [  lawful  |  neutral | chaotic |
       unaligned ]

       gives the  alignment  of  the  dungeon/level  (default  is
       unaligned).

       PROTOFILE: name

       the prototypical name for dungeon level files in this dun-
       geon.  For example, the PROTOFILE  name  for  the  dungeon
       Vlad's Tower is tower.

       LEVEL: name bonesmarker @ ( base , rand ) [ %age ]

       where  name is the level name, bonesmarker is a letter for
       marking bones files, ( base , rand ) is the  location  and
       %age is the generation percentage, as above.

       RNDLEVEL:  name  bonesmarker  @  (  base , rand ) [ %age ]
       rndlevs

       where name is the level name, bonesmarker is a letter  for
       marking bones files, ( base , rand ) is the location, %age
       is the generation percentage, as above, and rndlevs is the
       number of similar levels available to choose from.

       CHAINLEVEL: name bonesmarker prev_name + ( base , rand ) [
       %age ]

       where name is the level name, bonesmarker is a letter  for
       marking  bones  files,  prev_name  is  the name of a level
       defined previously, ( base , rand ) is the offset from the
       level  being chained from, and %age is the generation per-
       centage.

       RNDCHAINLEVEL: name bonesmarker prev_name + ( base ,  rand
       ) [ %age ] rndlevs

       where  name is the level name, bonesmarker is a letter for
       marking bones files, prev_name is  the  name  of  a  level
       defined previously, ( base , rand ) is the offset from the
       level being chained from, %age is the generation  percent-
       age, and rndlevs is the number of similar levels available
       to choose from.

       LEVELDESC: type

       where type is the level type,  (see  DESCRIPTION,  above).
       The  type  is  used  to override any pre-set value used to
       describe the entire dungeon, for this level only.

       BRANCH: name @ ( base , rand ) [ stair | no_up | no_down |
       portal ] [ up | down ] [ level ]

       where  name is the name of the dungeon to branch to, and (
       base , rand ) is the location of  the  branch.   The  last
       three  optional  arguments  are  the  branch  type, branch
       direction and target level.  The type of a branch can be a
       two-way stair connection, a one-way stair connection, or a
       magic portal.  A one-way stair is described by  the  types
       no_up  and  no_down which specify which stair direction is
       missing.  The default branch type is stair.  The direction
       for  a  stair  can  be either up or down; direction is not
       applicable to portals.  The  default  direction  is  down.
       level is the target dungeon entry point.  The dungeon con-
       nection attaches at this level of the given  dungeon.   If
       the  value of level is negative, the entry level is calcu-
       lated from the bottom of the dungeon, with  -1  being  the
       last  level.   If  this  value is not present in a dungeon
       description, the entry level defaults to 1.

       CHAINBRANCH: name prev_name + ( base , rand )  [  stair  |
       no_up | no_down | portal ] [ up | down ] [ level ]

       where  name  is  the  name  of  the  dungeon to branch to,
       prev_name is the name of a previously defined level and  (
       base  ,  rand ) is the offset from the level being chained
       from.  The optional branch type, direction and  level  are
       the same as described above.

GENERIC RULES
       Each  dungeon  must  have  a unique bonesmarker , and each
       special level must have a bonesmarker  unique  within  its
       dungeon (letters may be reused in different dungeons).  If
       the bonesmarker has the special  value  "none",  no  bones
       files will be created for that level or dungeon.

       The  value  base  may be in the range of 1 to MAXLEVEL (as
       defined in global.h ).

       The value rand may be in the range of -1 to MAXLEVEL.

       If rand is -1 it will be replaced with the value (num_dun-
       levs(dungeon)  -  base)  during the load process (ie. from
       here to the end of the dungeon).

       If rand is 0 the level is located absolutely at base.

       Branches don't have a probability.   Dungeons  do.   If  a
       dungeon  fails to be generated during load, all its levels
       and branches are skipped.

       No level or branch may be chained from a level with a per-
       centage  generation  probability.  This is to prevent non-
       resolution during the load.  In addition, no branch may be
       made from a dungeon with a percentage generation probabil-
       ity for the same reason.

       As a general rule using the dungeon compiler:

       If a dungeon has a protofile name associated with it  (eg.
       tower) that file will be used.

       If  a special level is present, it will override the above
       rule and the appropriate file will be loaded.

       If neither of the above are present, the standard  genera-
       tor will take over and make a "normal" level.

       A level alignment, if present, will override the alignment
       of the dungeon that it exists within.

EXAMPLE
       Here is the current syntax of the dungeon compiler's "lan-
       guage":


       #
       #       The dungeon description file for the "standard" original
       #       3.0 NetHack.
       #
       DUNGEON:        "The Dungeons of Doom" "D" (25, 5)
       LEVEL:          "rogue" "none" @ (15, 4)
       LEVEL:          "oracle" "none" @ (5, 7)
       LEVEL:          "bigroom" "B" @ (12, 3) 15
       LEVEL:          "medusa" "none" @ (20, 5)
       CHAINLEVEL:     "castle" "medusa" + (1, 4)
       CHAINBRANCH:    "Hell" "castle" + (0, 0) no_down
       BRANCH:         "The Astral Plane" @ (1, 0) no_down up

       DUNGEON:        "Hell" "H" (25, 5)
       DESCRIPTION:    mazelike
       DESCRIPTION:    hellish
       BRANCH:         "Vlad's Tower" @ (13, 5) up
       LEVEL:          "wizard" "none" @ (15, 10)
       LEVEL:          "fakewiz" "A" @ (5, 5)
       LEVEL:          "fakewiz" "B" @ (10, 5)
       LEVEL:          "fakewiz" "C" @ (15, 5)
       LEVEL:          "fakewiz" "D" @ (20, 5)
       LEVEL:          "fakewiz" "E" @ (25, 5)

       DUNGEON:        "Vlad's Tower" "T" (3, 0)
       PROTOFILE:      "tower"
       DESCRIPTION:    mazelike
       ENTRY:          -1

       DUNGEON:        "The Astral Plane" "A" (1, 0)
       DESCRIPTION:    mazelike
       PROTOFILE:      "endgame"

       NOTES:
       Lines beginning with '#' are considered comments.
       A special level must be explicitly aligned.  The alignment
       of the dungeon it is in only applies to non-special levels
       within that dungeon.

AUTHOR
       M.  Stephenson (from the level compiler by Jean-Christophe
       Collet).

SEE ALSO
       lev_comp(6), nethack(6)

BUGS
       Probably infinite.



                           12 Dec 1995                DGN_COMP(6)
