doc/nethack.txt

   1 NETHACK(6)                       Games Manual                       NETHACK(6)
   2
   3
   4
   5 NAME
   6        nethack - Exploring The Mazes of Menace
   7
   8 SYNOPSIS
   9        nethack [ -d|--directory directory ] [ -w|--windowtype interface ]
  10        [ --nethackrc:RC-file | --no-nethackrc ] [ -n ] [ -dec | -ibm ]
  11        [ -u playername ] [ -X | -D ] [ -p profession ] [ -r race ] [ -@ ]
  12
  13        Also [ -A|-Arc | -B|-Bar | -C|-Cav | -H|-Hea | -K|-Kni | -M|-Mon |
  14        -P|-Pri | -R|-Rog | -Ran | -S|-Sam | -T|-Tou | -V|-Val | -W|-Wiz ]
  15
  16        nethack [ -d|--directory directory ] -s|--scores [ -v ]
  17        [ -p profession ] [ -r race ] [ playernames ]
  18
  19        nethack [ --usage | --help ] [ --showpaths ]
  20        [ --version[:copy|:dump|:show] ]
  21
  22 DESCRIPTION
  23        NetHack is a display oriented Dungeons & Dragons(tm) - like game.   The
  24        standard tty display and command structure resemble rogue.
  25
  26        Other, more graphical display options exist for most platforms.
  27
  28        To  get started you really only need to know two commands.  The command
  29        ?  will give you a list of the available commands  (as  well  as  other
  30        information)  and the command / will identify the things you see on the
  31        screen.
  32
  33        To win the game (as opposed to merely playing to  beat  other  people's
  34        high  scores)  you  must locate the Amulet of Yendor which is somewhere
  35        below the 20th level of the dungeon and get it out.  Few people achieve
  36        this;  most  never  do.   Those  who have done so go down in history as
  37        heroes among heroes -- and then they find ways of making the game  even
  38        harder.   See  the Guidebook section on Conduct if this game has gotten
  39        too easy for you.
  40
  41        When the game ends, whether by your dying, quitting, or  escaping  from
  42        the  caves, NetHack will give you (a fragment of) the list of top scor-
  43        ers.  The scoring is based on many aspects  of  your  behavior,  but  a
  44        rough estimate is obtained by taking the amount of gold you've found in
  45        the cave plus four times your (real) experience.  Precious  stones  may
  46        be  worth  a lot of gold when brought to the exit.  There is a 10% pen-
  47        alty for getting yourself killed.
  48
  49        The environment variable NETHACKOPTIONS can be used to initialize  many
  50        run-time  options.   The  ?  command  provides  a  description of these
  51        options and syntax.  (The -dec and -ibm command line options are  mutu-
  52        ally  exclusive  and  are equivalent to the decgraphics and ibmgraphics
  53        run-time options described there, and are provided  purely  for  conve-
  54        nience on systems supporting multiple types of terminals.)
  55
  56        Because  the option list can be very long, options may also be included
  57        in a configuration file.  The default is located in your home directory
  58        and  named  .nethackrc  on  UNIX systems (including descendants such as
  59        linux, NetBSD, and macOS).  On Windows, the name is also .nethackrc but
  60        the  location  can vary (see --showpaths below).  On other systems, the
  61        default may be different, possibly NetHack.cnf.  On MS-DOS, the name is
  62        defaults.nh in NetHack's directory (folder), while on VMS|OpenVMS it is
  63        nethack.ini in your home directory.  The default configuration file may
  64        be  overridden  via  the  --nethackrc:rc-file command line option or by
  65        setting NETHACKOPTIONS in your environment to a string consisting of an
  66        @ character followed by the path and filename.
  67
  68        The  -u  playername option supplies the answer to the question "Who are
  69        you?".  It overrides any name from the options or  configuration  file,
  70        USER,  LOGNAME,  or getlogin(), which will otherwise be tried in order.
  71        If none of these provides a useful name, the player will be  asked  for
  72        one.  Player names (in conjunction with uids) are used to identify save
  73        files, so you can have several saved games under different names.  Con-
  74        versely,  you  must  use the appropriate player name to restore a saved
  75        game.
  76
  77        A playername suffix can be used to specify the profession, race, align-
  78        ment and/or gender of the character.  The full syntax of the playername
  79        that includes a suffix is "name-ppp-rrr-aaa-ggg".  "ppp" are  at  least
  80        the  first  three letters of the profession (this can also be specified
  81        using a separate -p profession option).  "rrr" are at least  the  first
  82        three letters of the character's race (this can also be specified using
  83        a separate -r race option).  "aaa" are at least the first three letters
  84        of  the  character's  alignment, and "ggg" are at least the first three
  85        letters of the character's gender.  Any of the parts of the suffix  may
  86        be left out.
  87
  88        -p  profession  can be used to determine the character profession, also
  89        known as the role.  You can specify either the male or female name  for
  90        the  character  role,  or  the first three characters of the role as an
  91        abbreviation.
  92
  93        Likewise, -r race can be used to explicitly request that a race be cho-
  94        sen.
  95
  96        The -A|-Arc | -B|-Bar | -C|-Cav | -H|-Hea | -K|-Kni | -M|-Mon | -P|-Pri
  97        | -R|-Rog | -Ran | -S|-Sam | -T|-Tou | -V|-Val |  -W|-Wiz  options  for
  98        role  selection are maintained for compatibility with older versions of
  99        the program.  They are mutually exclusive and  the  single-letter  form
 100        must  be  uppercase.   Ranger has no single-letter choice because -R is
 101        already used for the Rogue role.
 102
 103        -@  tells  nethack  to  choose  any  omitted  characteristics  (profes-
 104        sion/role, race, gender, alignment) randomly without prompting.  Other-
 105        wise, leaving out any of these characteristics will result in you being
 106        prompted during game startup for the information.
 107
 108        The -n option suppresses printing of any news from the game administra-
 109        tor.
 110
 111        The -X option will start the game in a  special  non-scoring  discovery
 112        mode  (also  known  as  explore mode).  -D will start the game in debug
 113        mode (also known as wizard mode) after changing the character  name  to
 114        "wizard",  if  the  player is allowed.  Otherwise it will switch to -X.
 115        Control of who is allowed to use debug mode is done via the  "WIZARDS="
 116        line in nethack's sysconf file.
 117
 118        The  -d  or  --directory option, which must be the first argument if it
 119        appears, supplies a directory which is to serve as the playground.   It
 120        overrides  the  value from NETHACKDIR, HACKDIR, or the directory speci-
 121        fied  by   the   game   administrator   during   compilation   (usually
 122        /usr/games/lib/nethackdir).   This option is usually only useful to the
 123        game administrator.  The  playground  must  contain  several  auxiliary
 124        files  such  as help files, the list of top scorers, and a subdirectory
 125        save where games are saved.
 126
 127        The -w or --windowtype interface option can be used  to  specify  which
 128        interface  to  use  if the program has been built with support for more
 129        than one.  Specifying a value on the command line overrides  any  value
 130        specified  in the run-time configuration file.  NetHack's #version com-
 131        mand shows available interfaces.
 132
 133        The --nethackrc:RC-file option will use RC-file instead of the  default
 134        run-time   configuration   file   (typically   ~/.nethackrc)   and  the
 135        --no-nethackrc option can be used to skip  any  run-time  configuration
 136        file.
 137
 138        Some options provide feedback and then exit rather than play the game:
 139
 140        The  -s or --scores option alone will print out the list of your scores
 141        on the current version.  An immediately following  -v  reports  on  all
 142        versions present in the score file.  '-s|-s -v' may also be followed by
 143        arguments -p profession and -r race to print the scores  of  particular
 144        roles  and  races  only.   Either  can  be  specified multiple times to
 145        include more than one role or more than one race.  When both are speci-
 146        fied,  score  entries which match either the role or the race (or both)
 147        are printed rather than just entries which match both.  '-s|-s -v'  may
 148        be  followed  by  one  or  more player names to print the scores of the
 149        players mentioned, by 'all' to print out all scores, or by a number  to
 150        print  that many top scores.  Combining names with role or race or both
 151        will report entries which match any of those rather than just the  ones
 152        which match all.
 153
 154        --version  or  --version:show  can be used to cause NetHack to show the
 155        version number, the date and time that the program was built  from  its
 156        source  code, and possibly some auxiliary information about that source
 157        code, then exit.  The optional auxiliary information is git commit hash
 158        (reflecting  the  source code's most recent modification when extracted
 159        from the git version control system, if that is in  use)  if  available
 160        when  the  program  was  built.   On some platforms such as Windows and
 161        macOS, a variation, --version:copy, can be used  to  cause  NetHack  to
 162        show  the  version information, then exit, while also leaving a copy of
 163        that information in the paste buffer or clipboard for potential  inser-
 164        tion into things like bug reports.  On any platform, --version:dump can
 165        be used to show most of the data used when checking whether a save file
 166        or bones file is compatible with the program.  The program will display
 167        a line containing five numbers expressed in hexadecimal, then exit.
 168
 169        --showpaths can be used to cause NetHack to show where it is  expecting
 170        to  find  various  files.   Among other things it shows the path to and
 171        name for the player's run-time configuration file, a  text  file  which
 172        can be edited to customize aspects of how the game operates.
 173
 174        --usage or --help will display information similar to this manual page,
 175        then exit.  Use 'nethack --usage | more' to read it a page at a time.
 176
 177 AUTHORS
 178        Jay Fenlason (+ Kenny Woodland, Mike Thome and  Jon  Payne)  wrote  the
 179        original hack, very much like rogue (but full of bugs).
 180
 181        Andries  Brouwer  continuously  deformed their sources into an entirely
 182        different game.
 183
 184        Mike Stephenson has continued the perversion of sources, adding various
 185        warped  character  classes  and  sadistic  traps  with the help of many
 186        strange people who reside in that place between the worlds, the  Usenet
 187        Zone.   A number of these miscreants are immortalized in the historical
 188        roll of dishonor and various other places.
 189
 190        The resulting mess is now called NetHack, to denote its development  by
 191        the Usenet.  Andries Brouwer has made this request for the distinction,
 192        as he may eventually release a new version of his own.
 193
 194 FILES
 195        Run-time configuration options were discussed above and use a  platform
 196        specific  name  for  a file in a platform specific location.  For Unix,
 197        the name is '.nethackrc' in the user's home directory.
 198
 199        All  other  files   are   in   the   playground   directory,   normally
 200        /usr/games/lib/nethackdir.   If DLB was defined during the compile, the
 201        data files and special levels will be inside a  larger  file,  normally
 202        nhdat, instead of being separate files.
 203
 204        nethack                     The program itself.
 205        Guidebook | Guidebook.txt   NetHack's user manual.
 206        data, oracles, rumors       Data files used by NetHack.
 207        bogusmon                    Another data file.
 208        engrave, epitaph, tribute   Still more data files.
 209        symbols                     Data file holding sets of specifications
 210                                    for how to display monsters, objects, and
 211                                    map features.
 212        options                     Data file containing a description of the
 213                                    build-time option settings.
 214        help, hh, cmdhelp           Help data files.  ('cmdhelp' is obsolete.)
 215        opthelp, optmenu, wizhelp   More help data files.
 216        keyhelp, usagehlp           Even more help data files.
 217        *.lua                       Predefined special levels, dungeon control
 218                                    for special levels, quest texts.
 219        history                     A short history of NetHack.
 220        license                     Rules governing redistribution.
 221        record                      The list of top scorers.
 222        logfile                     An extended list of games played
 223                                    (optional).
 224        xlogfile                    A more detailed version of 'logfile'
 225                                    (also optional).
 226        paniclog                    Record of exceptional conditions
 227                                    discovered during program execution.
 228        xlock.nn                    Description of dungeon level 'nn' of
 229                                    active game 'x' if there's a limit on the
 230                                    number of simultaneously active games.
 231        UUcccccc.nn                 Alternate form for dungeon level 'nn'
 232                                    of active game by user 'UU' playing
 233                                    character named 'cccccc' when there's no
 234                                    limit on number of active games.
 235        perm                        Lock file for xlock.0 or UUcccccc.0.
 236        bonD0.nn                    Descriptions of the ghost and belongings
 237                                    of a deceased adventurer who met his or
 238                                    her demise on level 'nn'.  A subsequent
 239                                    character might encounter this old level.
 240
 241        save/                       A subdirectory containing saved games.
 242
 243        sysconf                     System-wide options.  Required if
 244                                    program is built with 'SYSCF' option
 245                                    enabled, ignored if not.
 246
 247        The  location  of  'sysconf'  is  specified  at build time and can't be
 248        changed except by updating source file "config.h"  and  rebuilding  the
 249        program.
 250
 251        NetHack's  Guidebook  might  not  be  present  if  whoever  packaged or
 252        installed the program distribution neglected to include it.
 253
 254        In a perfect world, 'paniclog' would remain empty.
 255
 256 ENVIRONMENT
 257        USER or LOGNAME         Your login name.
 258        HOME                    Your home directory.
 259        SHELL                   Your shell.
 260        TERM                    The type of your terminal.
 261        HACKPAGER or PAGER      Replacement for default pager.
 262        MAIL                    Mailbox file.
 263        MAILREADER              Replacement for default reader
 264                                (probably /bin/mail or /usr/ucb/mail).
 265        NETHACKDIR or HACKDIR   Playground.
 266        NETHACKOPTIONS          String predefining several NetHack options.
 267
 268        If the same option is specified in both NETHACKOPTIONS and  .nethackrc,
 269        the value assigned in NETHACKOPTIONS takes precedence.
 270
 271        SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode.
 272        DEBUGFILES can be used if the program was built with 'DEBUG' enabled.
 273
 274 SEE ALSO
 275        recover(6)
 276
 277 BUGS
 278        Probably infinite.
 279
 280 COPYRIGHT
 281        This  file  is  Copyright  (C)  Robert Patrick Rankin, 2024 for version
 282        NetHack-3.7:1.31.  NetHack may be freely  redistributed.   See  license
 283        for details.
 284
 285        Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc.
 286
 287
 288
 289 NETHACK                        25 December 2024                     NETHACK(6)