diff --git a/doc/Gbk-1pg-sfx.mn b/doc/Gbk-1pg-sfx.mn index d00b37f5f..9008ac440 100644 --- a/doc/Gbk-1pg-sfx.mn +++ b/doc/Gbk-1pg-sfx.mn @@ -1,8 +1,3 @@ .\" suffux to Guidebook.mn for 'roff version of Guidebook written as one page .br -.\" add a marker that precedes hundreds of blank lines which pad out the page -EOF--EOF -. -.\" post process with "sed -e '/EOF--EOF/,12345D'" to remove trailing junk -.\" (also removes Unix trademark footnote; that ought to be kept but the -.\" generic "all trademarks are held by respective owners" is still present) +.pl \n(nlu diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index c302200e4..62a7ef492 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -1,8 +1,7 @@ -.\" $NHDT-Branch: NetHack-3.6-Mar2020 $:$NHDT-Revision: 1.347 $ $NHDT-Date: 1583508684 2020/03/06 15:31:24 $ +.\" $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.614 $ $NHDT-Date: 1770881338 2026/02/11 23:28:58 $ .\" .\" This is an excerpt from the 'roff' man page from the 'groff' package. -.\" NetHack's Guidebook.mn currently does *not* adhere to these guidelines. -.\"||| +.\"+-- .\"| o Never include empty or blank lines in a roff document. Instead, use .\"| the empty request (a line consisting of a dot only) or a line comment .\"| .\" if a structuring element is needed. @@ -13,18 +12,55 @@ .\"| is handled differently depending on whether it terminates an abbrevi- .\"| ation or a sentence. To distinguish both cases, do a line break af- .\"| ter each sentence. -.\"||| +.\"+-- +.\" Guidebook.mn has been updated to adhere to the first two guidelines +.\" but does not yet fully honor the third. New changes should do so. .\" . -.so tmac.nh \" extra macros which aren't in tmac.n +.\" Usage: +.\" to produce Guidebook.ps: +.\" cat Guidebook.mn |tbl tmac.n - |groff >Guidebook.ps +.\" to produce Guidebook.txt: +.\" cat Guidebook.mn |tbl tmac.n - |groff -c -Tascii |col -bx >Guidebook.txt +.\" with an optional filtering step between 'cat' and 'tbl': +.\" cat... |../util/makedefs --grep --input - --output - |tbl... . -.ds h0 "NetHack Guidebook -.ds h1 +.if n \{\ +.po 5n +.ll 70n +.lt 70n +.\} +. +.\" Load extra macros that "tmac.n" doesn't define. +.de So +.ie \n(.g&(\n(.x=1)&(\n(.y>22) .soquiet \\$1 +.el .so \\$1 +.. +. +.So tmac.nh +.if !\n(nH So doc/tmac.nh +. +.if !\n(nH \{\ +.tm fatal error: cannot locate "tmac.nh" macro package +.ab +.\} +. +.rm So +. +.\" building Guidebook.txt doesn't have CR font available; groff 1.23 issues +.\" a warning each time any font can't be loaded; earlier versions silently +.\" proceeded so lack of CR (fixed-width, moot for plain text) didn't matter +.if n .do ftr CR R \" if formatting for a terminal, substitute R for CR +. \" (the substitution affects both '\f' and '.ft') +. +.ds h0 NetHack Guidebook +.ds h1 \" empty .ds h2 % -.ds vr "NetHack 3.6 -.ds f0 "\*(vr -.ds f1 -.ds f2 "February 3, 2023 +.ds vr NetHack 5.0.0 +.ds f0 \*(vr +.ds f1 \" empty +.\"DO NOT REMOVE NH_DATESUB .ds f2 Date(%B %-d, %Y) +.ds f2 May 2, 2026 . .\" A note on some special characters: .\" \(lq = left double quote @@ -32,9 +68,11 @@ .\" \(oq = left (open) single quote .\" \(cq = right (close) single quote \(aq = apostrophe / single quote .\" - = hyphen \- = minus sign -.\" \(em = M-sized dash +.\" \(rs = backslash \(em = dash as wide as 'M' is tall .\" ^ = small circumflex punctuation \(ha = larger circumflex character .\" ~ = small tilde punctuation \(ti = larger tilde character +.\" +.\" See groff_man_style(7) or groff_char(7) for more on these. . . .\" finally, start the actual Guidebook... @@ -44,7 +82,7 @@ A Guide to the Mazes of Menace (Guidebook for NetHack) .au Original version - Eric S. Raymond -(Edited and expanded for 3.6 by Mike Stephenson and others) +(Edited and expanded for \*(vr by Mike Stephenson and others) .sp 1 \*(f2 .hn 1 @@ -92,7 +130,7 @@ travel, you see the ancient ruins that mark the entrance to the Mazes of Menace. It is late at night, so you make camp at the entrance and spend the night sleeping under the open skies. In the morning, you gather your gear, eat what may be your last meal outside, and enter the -dungeon... +dungeon.... . .hn 1 What is going on here? @@ -106,7 +144,8 @@ will vary with your background and training: .pg \fIArcheologists\fP understand dungeons pretty well; this enables them to move quickly and sneak up on the local nasties. They start equipped -with the tools for a proper scientific expedition. +with the tools for a proper scientific expedition, and are able to read +ancient languages. .pg \fIBarbarians\fP are warriors out of the hinterland, hardened to battle. They begin their quests with naught but uncommon strength, a trusty hauberk, @@ -229,9 +268,20 @@ replaces the \(lqYou see ...\(rq descriptions of text adventure games. Figure 1 is a sample of what a NetHack screen might look like. The way the screen looks for you depends on your platform. . +.\" (Either generated by hand or else the composite of two different +.\" situations. Originally the character had only reached a second room +.\" (unchanged here) by turn 257 (now changed to 752) and was already +.\" Weak from hunger (now changed to just Hungry) and also lacked any of +.\" Tourist's starting gold. Confusion is added to include a +.\" condition.) +.\" +.\" Width is constrained by the margins of plain text output +.\" (Guidebook.txt). Text output might show an extra space inboard of +.\" the left and right box boundaries that does not appear in PostScript +.\" output. This behavior is specific to GNU tbl. .BR 2 .ft CR \" set font to constant-width Roman -.TS S +.TS center box tab(~); L. The bat bites! @@ -245,25 +295,50 @@ The bat bites! -Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral -Dlvl:1 $:0 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:257 Weak +Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral +Dlvl:1 $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:752 Hungry Conf .TE -.ft \" revert to previous font +.ft R .ce 1 +.if t .sp 0.5v Figure 1 . +.BR 1 +.ft CR +.TS +center box tab(~); +L. +.\" Use trailing spaces to force the same width as Figure 1. +Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 \& +Neutral $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 Hungry \& +Dlvl:1 T:752 Conf \& +.TE +.ft R +.ce 1 +.if t .sp 0.5v +Figure 2 +. .hn 2 The status lines (bottom) .pg -The bottom two lines of the screen contain several cryptic pieces of -information describing your current status. If either status line -becomes longer than the width of the screen, you might not see all of -it. Here are explanations of what the various status items mean -(though your configuration may not have all the status items listed -below): -.lp "Rank " -Your character's name and professional ranking (based on the -experience level, see below). +The bottom two (or three) lines of the screen contain several cryptic +pieces of information describing your current status. +Figure 1 shows the traditional two-line status area below the map. +Figure 2 shows just the status area, when the +.op statuslines:3 +option has been set (not all interfaces support this option). +If any status line becomes wider than the screen, you might not see all +of it due to truncation. +When the numbers grow bigger and multiple \fIconditions\fP are present, +the two-line format will run out of room on the second line, but +.op statuslines:2 +is the default because a basic 24-line terminal isn't tall enough for +the third line. +.pg +Here are explanations of what the various status items mean: +.lp "Title " +Your character's name and professional ranking (based on role and +\fIexperience level\fP, see below). .lp Strength A measure of your character's strength; one of your six basic attributes. A human character's attributes can range from 3 to 18 inclusive; @@ -284,7 +359,7 @@ can carry. With sufficiently high strength, the contribution to carrying capacity from your constitution no longer matters. .lp Intelligence Intelligence affects your ability to cast spells and read spellbooks. -.lp Wisdom +.lp "Wisdom " Wisdom comes from your practical experience (especially when dealing with magic). It affects your magical energy. .lp Charisma @@ -302,7 +377,7 @@ How deep you are in the dungeon. You start at level one and the number increases as you go deeper into the dungeon. Some levels are special, and are identified by a name and not a number. The Amulet of Yendor is reputed to be somewhere beneath the twentieth level. -.lp "Gold " +.lp "Gold " The number of gold pieces you are openly carrying. Gold which you have concealed in containers is not counted. .lp "Hit Points" @@ -311,21 +386,31 @@ damage you can take before you die. The more you get hit in a fight, the lower they get. You can regain hit points by resting, or by using certain magical items or spells. The number in parentheses is the maximum number your hit points can reach. -.lp Power +.lp "Power " Spell points. This tells you how much mystic energy (\fImana\fP) you have available for spell casting. Again, resting will regenerate the amount available. .lp "Armor Class" A measure of how effectively your armor stops blows from unfriendly -creatures. The lower this number is, the more effective the armor; it +creatures. +The lower this number is, the more effective the armor; it is quite possible to have negative armor class. +See the \fIArmor\fP subsection of \fIObjects\fP for more information. .lp Experience -Your current experience level and experience points. As you -adventure, you gain experience points. At certain experience point -totals, you gain an experience level. The more experienced you are, -the better you fight and withstand magical attacks. Many dungeons -show only your experience level here. -.lp "Time " +Your current experience level. +If the +.op showexp +option is set, it will be followed by a slash and experience points. +As you adventure, you gain experience points. +At certain experience point totals, you gain an experience level. +The more experienced you are, the better you fight and withstand magical +attacks. +(By the time your level reaches double digits, the usefulness of showing +the points with it has dropped significantly. +You can use the \(oq\f(CRO\fP\(cq command to turn +.op showexp +off to avoid using up the limited status line space.) +.lp "Time " The number of turns elapsed so far, displayed if you have the .op time option set. @@ -339,7 +424,7 @@ Not shown when \fBNormal\fP. .lp "" Encumbrance: an indication of how what you are carrying affects your ability to move. -Values are \fBUnencumbered\fP, \fBEncumbered\fP, \fBStressed\fP, +Values are \fBUnencumbered\fP, \fBBurdened\fP, \fBStressed\fP, \fBStrained\fP, \fBOvertaxed\fP, and \fBOverloaded\fP. Not shown when \fBUnencumbered\fP. .lp "" @@ -359,7 +444,15 @@ Movement modifiers: .lp "" Other conditions and modifiers exist, but there isn't enough room to display them with the other status fields. -The \(oq\(haX\(cq command shows all relevant status conditions. +.\" Don't give the next paragraph a first-line indent. +.nr @p \n(pi \" Save mn's paragraph indentation. +.nr pi 0 +.pg +The \f(CR#attributes\fP command (default key \f(CR\(haX\fP) will show +all current status information in unabbreviated format. +It also shows other information which might be included on the status +lines if those had more room. +.nr pi \n(@p \" Restore mn's paragraph indentation. .hn 2 The message line (top) .pg @@ -379,69 +472,89 @@ option. The map (rest of the screen) .pg The rest of the screen is the map of the level as you have explored it -so far. Each symbol on the screen represents something. You can set -various graphics options to change some of the symbols the game uses; -otherwise, the game will use default symbols. Here is a list of what the -default symbols mean: -.lp "\\- and | " -The walls of a room, or an open door. Or a grave (|). -.lp . -The floor of a room, ice, or a doorless doorway. -.lp # -A corridor, or iron bars, or a tree, or possibly a kitchen sink (if -your dungeon has sinks), or a drawbridge. -.lp > +so far. +Each symbol on the screen represents something. +You can set various graphics options to change some of the symbols the +game uses; otherwise, the game will use default symbols. +Here is a list of what the default symbols mean: +.lp \f(CR\\-\fP +The horizontal or corner walls of a room, or an open east/west door. +.lp \f(CR|\fP +The vertical walls of a room, or an open north/south door, or a grave. +.lp \f(CR.\fP +The floor of a room, or ice, or a doorless doorway, or the span of an +open drawbridge. +.lp \f(CR#\fP +A corridor, or iron bars, or a tree, or the portcullis of a closed +drawbridge. +.lp "" +Note: engravings in corridors also appear as \f(CR#\fP but are shown in +a different color from normal corridor locations. +.lp \f(CR>\fP Stairs down: a way to the next level. -.lp < +.lp \f(CR<\fP Stairs up: a way to the previous level. -.lp + +.lp \f(CR+\fP A closed door, or a spellbook containing a spell you may be able to learn. -.lp @ -Your character or a human. -.lp $ +.lp \f(CR@\fP +Your character or a human or an elf. +.lp \f(CR$\fP A pile of gold. -.lp \(ha \" ^ +.lp \f(CR\(ha\fP \" \(ha == 'hat' == full sized caret ^ A trap (once you have detected it). -.lp ) +.lp \f(CR)\fP A weapon. -.lp [ +.lp \f(CR[\fP A suit or piece of armor. -.lp % +.lp \f(CR%\fP Something edible (not necessarily healthy). -.lp ? +.lp \f(CR?\fP A scroll. -.lp / +.lp \f(CR/\fP A wand. -.lp = +.lp \f(CR=\fP A ring. -.lp ! +.lp \f(CR!\fP A potion. -.lp ( +.lp \f(CR(\fP A useful item (pick-axe, key, lamp...). -.lp \(dq \" \(dq == double quote +.lp \f(CR\(dq\fP \" \(dq == double quote An amulet or a spider web. -.lp * +.lp \f(CR*\fP A gem or rock (possibly valuable, possibly worthless). -.lp \` -A boulder or statue. -.lp 0 +.lp \f(CR\`\fP +A boulder or statue or an engraving on the floor of a room. +.lp "" +Note: statues are displayed as if they were the monsters they depict +so won't appear as a \fIgrave accent\fP (aka \fIback-tick\fP). +.lp \f(CR0\fP An iron ball. -.lp _ +.lp \f(CR_\fP An altar, or an iron chain. -.lp { -A fountain. -.lp } -A pool of water or moat or a pool of lava. -.lp \\\\ +.lp \f(CR{\fP +A fountain or a sink. +.lp \f(CR}\fP +A pool of water or moat or a wall of water +or a pool of lava or a wall of lava. +.lp \f(CR\\\\\fP An opulent throne. -.lp "a-zA-Z and other symbols" +.lp "\f(CRa\fP-\f(CRz\fP\ \ \fIand\fP" +.lp "\f(CRA\fP-\f(CRH\fP\f(CRJ\fP-\f(CRZ\fP\ \ \fIand\fP" +.lp "\f(CR@&\(aq:;\fP" \" \(aq == apostrophe / single quote Letters and certain other symbols represent the various inhabitants -of the Mazes of Menace. Watch out, they can be nasty and vicious. +of the Mazes of Menace. +Watch out, they can be nasty and vicious. Sometimes, however, they can be helpful. -.lp I -This marks the last known location of an invisible or otherwise unseen -monster. Note that the monster could have moved. -The \(oqF\(cq and \(oqm\(cq commands may be useful here. +.lp \f(CRI\fP +Rather than a specific type of monster, this marks the last known +location of an invisible or otherwise unseen monster. +Note that the monster could have moved. +The \(oqs\(cq, \(oqF\(cq, and \(oqm\(cq commands may be useful here. +.lp \f(CR1\fP-\f(CR5\fP +The digits 1 through 5 may be displayed, marking unseen monsters sensed +via the \fIWarning\fP attribute. +Less dangerous monsters are indicated by lower values, more dangerous by +higher values. .pg You need not memorize all these symbols; you can ask the game what any symbol represents with the \(oq/\(cq command (see the next section for @@ -542,30 +655,28 @@ Go up to the previous level (if you are on a staircase or ladder). .lp > Go down to the next level (if you are on a staircase or ladder). .lp [yuhjklbn] -Go one step in the direction indicated (see Figure 2). If you sense -or remember -a monster there, you will fight the monster instead. Only these -one-step movement commands cause you to fight monsters; the others -(below) are \(lqsafe.\(rq -.sd -.\" note: the two number pad layouts are separated by a tab on each line; -.\" converting those tabs to spaces will screw up the formatting; -.\" the '(if ... set)' line starts with -.\" and is intended to line up with the right hand layout rather -.\" than be centered. -.TS S -center; -c c. +Go one step in the direction indicated (see Figure 3). +If you sense or remember a monster there, you will fight the monster +instead. +Only these one-step movement commands cause you to fight monsters; the +others (below) are \(lqsafe.\(rq +.ft CR +.tr -\-@\(rs +.TS +box center expand; +C C. y k u 7 8 9 -\e | / \e | / +@ | / @ | / h- . -l 4- . -6 -/ | \e / | \e +/ | @ / | @ b j n 1 2 3 -\ (if \fBnumber_pad\fP is set) +\fR(\fBnumber_pad\fP off) \fR(\fBnumber_pad\fP on) .TE -.ed +.tr --@@ +.ft R +.if t .sp 0.5v .ce 1 -Figure 2 +Figure 3 . .lp [YUHJKLBN] Go in that direction until you hit a wall or run into something. @@ -573,33 +684,53 @@ Go in that direction until you hit a wall or run into something. Prefix: move without picking up objects or fighting (even if you remember a monster there). .lp "" -A few non-movement commands use the \(oqm\(cq prefix to request operating -via menu (to temporarily override the -.op menustyle:Traditional +A few non-movement commands use the \(oq\f(CRm\fP\(cq prefix to request +operating via menu (to temporarily override the +.op menustyle \f(CR:traditional\fP option). -Primarily useful for \(oq,\(cq (pickup) when there is only one class of -objects present (where there won't be any \(lqwhat kinds of objects?\(rq -prompt, -so no opportunity to answer \(oqm\(cq at that prompt). -.lp "" -A few other commands (eat food, offer sacrifice, apply tinning-kit) use -the \(oqm\(cq prefix to skip checking for applicable objects on the floor -and go straight to checking inventory, -or (for \(lq#loot\(rq to remove a saddle), -skip containers and go straight to adjacent monsters. +Primarily useful for \(oq\f(CR,\fP\(cq (pickup) when there is only one class +of objects present (where there won't be any \(lqwhat kinds of objects?\(rq +prompt, so no opportunity to answer \(oqm\(cq at that prompt). +.lp "" The prefix will make \(lq#travel\(rq command show a menu of interesting targets in sight. +It can also be used with the \(oq\f(CR\\\fP\(cq (known, show a +list of all discovered objects) and the \(oq\f(CR\`\fP\(cq (knownclass, +show a list of discovered objects in a particular class) commands to offer +a menu of several sorting alternatives (which sets a new value for the +.op sortdiscoveries +option); also for \(lq#vanquished\(rq and \(lq#genocided\(rq commands +to offer a sorting menu. +.lp "" +A few other commands (eat food, offer sacrifice, apply tinning-kit, +drink/quaff, dip, tip container) use +the \(oq\f(CRm\fP\(cq prefix to skip checking for applicable objects on +the floor and go straight to checking inventory, +or (for \(lq#loot\(rq to remove a saddle), +skip containers and go straight to adjacent monsters. +.lp "" In debug mode (aka \(lqwizard mode\(rq), the \(oqm\(cq prefix may also be used with the \(lq#teleport\(rq and \(lq#wizlevelport\(rq commands. .lp F[yuhjklbn] Prefix: fight a monster (even if you only guess one is there). -.lp M[yuhjklbn] -Prefix: move far, no pickup. .lp "g[yuhjklbn]" Prefix: move until something interesting is found. -.lp "G[yuhjklbn] or [yuhjklbn]" -Prefix: same as \(oqg\(cq, but forking of corridors is not considered +.lp "G[yuhjklbn] or +[yuhjklbn]" +Prefix: similar to \(oqg\(cq, but forking of corridors is not considered interesting. +.lp "" +Note: + means holding the or key +down like while typing and releasing , then releasing +. \(ha is used as shorthand elsewhere in the Guidebook to mean +the same thing. Control characters are case-insensitive so \(hax and \(haX are +the same. +.lp "M[yuhjklbn]" +Old versions supported \(oq\f(CRM\fP\(cq as a movement prefix which +combined the effect of \(oq\f(CRm\fP\(cq with \f(CR\fP+. +That is no longer supported as a prefix but similar effect can be achieved +by using \(oq\f(CRm\fP\(cq and \f(CRG\fP in combination. +\f(CRm\fP can also be used in combination with \f(CRg\fP, +\f(CR\fP+, or \f(CR\fP+. .lp _ Travel to a map location via a shortest-path algorithm. .lp "" @@ -608,25 +739,30 @@ is computed over map locations the hero knows about (e.g. seen or previously traversed). If there is no known path, a guess is made instead. Stops on most of -the same conditions as the \(oqG\(cq command, but without picking up -objects, similar to the \(oqM\(cq command. +the same conditions as the \(oq\f(CRG\fP\(cq prefix, but without picking up +objects, so implicitly forces the \(oq\f(CRm\fP\(cq prefix. For ports with mouse support, the command is also invoked when a mouse-click takes place on a location other than the current position. .lp . Wait or rest, do nothing for one turn. +Precede with the \(oqm\(cq prefix +to wait for a turn even next to a hostile monster, if +.op safe_wait +is on. .lp a Apply (use) a tool (pick-axe, key, lamp...). .lp "" If used on a wand, that wand will be broken, releasing its magic in the -process. Confirmation is required. +process. +Confirmation is required. .lp A Remove one or more worn items, such as armor. .lp "" Use \(oqT\(cq (take off) to take off only one piece of armor or \(oqR\(cq (remove) to take off only one accessory. .lp \(haA -Redo the previous command. +Repeat the previous command. .lp c Close a door. .lp C @@ -644,7 +780,7 @@ Drop several things. .lp "" In answer to the question .lp "" -\(lqWhat kinds of things do you want to drop? [!%= BUCXaium]\(rq +\(lqWhat kinds of things do you want to drop? [!%= BUCXPaium]\(rq .lp "" you should type zero or more object symbols possibly followed by \(oqa\(cq and/or \(oqi\(cq and/or \(oqu\(cq and/or \(oqm\(cq. @@ -659,6 +795,8 @@ drop all objects known to be uncursed. drop all objects known to be cursed. .PL DX drop all objects of unknown B/U/C status. +.PL DP +drop objects picked up last. .PL Da drop all objects, without asking for confirmation. .PL Di @@ -671,10 +809,13 @@ use a menu to pick which object(s) to drop. drop only unpaid food. .PE The last example shows a combination. -There are three categories of object filtering: class (\(oq!\(cq for +There are four categories of object filtering: class (\(oq!\(cq for potions, \(oq?\(cq for scrolls, and so on), shop status (\(oqu\(cq for -unpaid, in other words, owned by the shop), and bless/curse state -(\(oqB\(cq, \(oqU\(cq, \(oqC\(cq, and \(oqX\(cq as shown above). +unpaid, in other words, owned by the shop), bless/curse state +(\(oqB\(cq, \(oqU\(cq, \(oqC\(cq, and \(oqX\(cq as shown above), +and novelty (\(oqP\(cq, recently picked up items; controlled by picking +up or dropping things rather than by any time factor). +.lp "" If you specify more than one value in a category (such as \(lq!?\(rq for potions and scrolls or \(lqBU\(rq for blessed and uncursed), an inventory object will meet the criteria if it matches any of the specified @@ -723,6 +864,17 @@ You may select ammunition with a previous \(oqQ\(cq command, or let the computer pick something appropriate if .op autoquiver is true. +If your wielded weapon has the throw-and-return property, your quiver +is empty, and +.op autoquiver +is false, you will throw that wielded weapon instead of filling the quiver. +This will also automatically use a polearm if wielded. +If +.op fireassist +is true, firing will automatically try to wield a launcher (for example, +a bow or a sling) matching the ammo in the quiver; this might take multiple +turns, and get interrupted by a monster. +Remember to swap back to your main melee weapon afterwards. .lp "" See also \(oqt\(cq (throw) for more general throwing and shooting. .lp i @@ -746,6 +898,8 @@ list all items known to be uncursed; list all items known to be cursed; .PL IX list all items whose bless/curse status is unknown; +.PL IP +list items picked up last; .PL I$ count your money. .PE @@ -764,6 +918,7 @@ The available options are listed later in this Guidebook. Options are usually set before the game rather than with the \(oqO\(cq command; see the section on options below. +Precede \(oqO\(cq with the \(oqm\(cq prefix to show advanced options. .lp \(haO Show overview. .lp "" @@ -792,13 +947,17 @@ For some interfaces, the behavior can be varied via the option. .lp q Quaff (drink) something (potion, water, etc). +.lp "" +When there is a fountain or sink present, it asks whether to drink +from that. +If that is declined, then it offers a chance to choose a potion from +inventory. +Precede \(oqq\(cq with the \(oqm\(cq prefix to skip asking about +drinking from a fountain or sink. .lp Q Select an object for your quiver, quiver sack, or just generally at the ready (only one of these is available at a time). You can then throw this (or one of these) using the \(oqf\(cq command. -.lp "" -(In versions prior to 3.3 this was the command to quit -the game, which has been moved to \(lq#quit\(rq.) .lp r Read a scroll or spellbook. .lp R @@ -808,7 +967,7 @@ If you're wearing more than one, you'll be prompted for which one to remove. When you're only wearing one, then by default it will be removed without asking, but you can set the -.op paranoid_confirmation +.op paranoid_confirmation:Remove option to require a prompt. .lp "" This command may also be used to take off armor. @@ -822,6 +981,10 @@ Redraw the screen. .lp s Search for secret doors and traps around you. It usually takes several tries to find something. +Precede with the \(oqm\(cq prefix to search for a turn +even next to a hostile monster, if +.op safe_wait +is on. .lp "" Can also be used to figure out whether there is still a monster at an adjacent \(lqremembered, unseen monster\(rq marker. @@ -849,7 +1012,7 @@ If you throw an arrow while not wielding a bow, you are throwing it by hand and it will generally be less effective than when shot. .lp "" See also \(oqf\(cq (fire) for throwing or shooting an item pre-selected -via the \(oqQ\(cq (quiver) command. +via the \(oqQ\(cq (quiver) command, with some extra assistance. .lp T Take off armor. .lp "" @@ -859,7 +1022,7 @@ and/or a shirt, or a suit covering a shirt, as if the underlying items weren't there.) When you're only wearing one, then by default it will be taken off without asking, but you can set the -.op paranoid_confirmation +.op paranoid_confirmation:Remove option to require a prompt. .lp "" This command may also be used to remove accessories. @@ -871,9 +1034,16 @@ choices but will accept an item of armor and attempt to take it off.) .lp \(haT Teleport, if you have the ability. .lp v -Display version number. +Display a list of significant events in the current game, also shown by +\f(CR#chronicle\fP. +.lp "" +\(oq\f(CRv\fP\(cq used to display the game's version number. +Use \(oq\f(CRV\fP\(cq for that now. .lp V -Display the game history. +Display version number. +.lp "" +\(oq\f(CRV\fP\(cq used to display a summary of the game's history. +Still available via \f(CR#history\fP. .lp w Wield weapon. .sd @@ -902,9 +1072,9 @@ the exchange still takes place. Toggle two-weapon combat, if your character can do it. Also available via the \(lq#twoweapon\(rq extended command. .lp "" -(In versions prior to 3.6 this was the command to switch from normal +(In versions prior to 3.6 this keystroke ran the command to switch from normal play to \(lqexplore mode\(rq, also known as \(lqdiscovery mode\(rq, -which has now been moved to \(lq#exploremode\(rq.) +which has now been moved to \(lq#exploremode\(rq and M-X.) .lp \(haX Display basic information about your character. .lp "" @@ -938,6 +1108,7 @@ Suspend the game .\" .UX: print "UNIX" now and a trademark footnote at bottom of current page; .\" 2nd arg (literal '(') _precedes_ it, 1st arg (quoted string) follows it .UX " versions with job control only)." ( +See \(lq#suspend\(rq below for more details. .lp : Look at what is here. .lp ; @@ -968,7 +1139,7 @@ Tell what equipment you are using. Combines the preceding five type-specific commands into one. .lp $ -Count your gold pieces. +Report the gold you're carrying, possibly shop credit and/or debt too. .lp + List the spells you know. .lp "" @@ -987,10 +1158,43 @@ be added to the end of the list rather than be inserted into the sorted ordering.) .lp \\\\ Show what types of objects have been discovered. +.lp "" +May be preceded by \(oq\f(CRm\fP\(cq to select preferred display order. .lp \` Show discovered types for one class of objects. +.lp "" +May be preceded by \(oq\f(CRm\fP\(cq to select preferred display order. +.lp | +If persistent inventory display is supported and enabled (with the +.op perm_invent +option), interact with it instead of with the map. +.lp "" +Allows scrolling with the +menu_first_page, menu_previous_page, +menu_next_page, and menu_last_page +keys (\(oq\f(CR\(ha\fP\(cq, \(oq\f(CR<\fP\(cq, +\(oq\f(CR>\fP\(cq, \(oq\f(CR|\fP\(cq by default). +Some interfaces also support menu_shift_left and menu_shift_right +keys (\(oq\f(CR{\fP\(cq and \(oq\f(CR}\fP\(cq by default). +Use the \fIReturn\fP (aka \fIEnter\fP) or \fIEscape\fP key to +resume play. .lp ! Escape to a shell. +See \(lq#shell\(rq below for more details. +.lp Del +Show map without obstructions. +You can view the explored portion of the current level's map without +monsters; without monsters and objects; or without monsters, objects, +and traps. +.lp "" +The key is also shown as on some keyboards or +on others. +It is sometimes displayed as \(ha? even though that is not an actual +control character. +.lp "" +Many terminals have an option to swap the and keys, +so typing the key might not execute this command. +If that happens, you can use the extended command \(lq#terrain\(rq instead. .lp # Perform an extended command. .lp "" @@ -1020,8 +1224,8 @@ slot to another so that it has a letter which is more meaningful for you or that it will appear in a particular location when inventory listings are displayed. You can move to a currently empty slot, or if the destination is -occupied \(em and won't merge \(em the item there will swap slots with the one -being moved. +occupied\(emand won't merge\(emthe +item there will swap slots with the one being moved. \(lq#adjust\(rq can also be used to split a stack of objects; when choosing the item to adjust, enter a count prior to its letter. .lp "" @@ -1050,6 +1254,9 @@ Autocompletes. Default key is \(oqM-A\(cq, and also \(oq\(haN\(cq if .op number_pad is on. +.lp "" +Preceding #annotate with the \(oqm\(cq prefix is the same as +#overview with the prefix. .lp "#apply " Apply (use) a tool such as a pick-axe, a key, or a lamp. Default key is \(oqa\(cq. @@ -1068,6 +1275,10 @@ Toggle the .op autopickup option on/off. Default key is \(oq@\(cq. +.lp "#bugreport" +Bring up a browser window to submit a report to the NetHack Development Team. +Can be disabled at the time the program is built; when enabled, +CRASHREPORTURL must be set in the system configuration file. .lp "#call " Call (name) a monster, or an object in inventory, on the floor, or in the discoveries list, or add an annotation for the @@ -1079,19 +1290,31 @@ Default key is \(oqZ\(cq. .lp "#chat " Talk to someone. Default key is \(oqM-c\(cq. +.lp "#chronicle" +Show a list of important game events. +Default key is \(oqv\(cq. .lp "#close " Close a door. Default key is \(oqc\(cq. .lp "#conduct " List voluntary challenges you have maintained. +.\" [only in wizard mode:] +.\" Also lists various achievements representing progress toward ultimate +.\" ascension if any have been attained. Autocompletes. Default key is \(oqM-C\(cq. .lp "" See the section below entitled \(lqConduct\(rq for details. +.lp #debugfuzzer +Start the fuzz tester. +Debug mode only. .lp "#dip " Dip an object into something. Autocompletes. Default key is \(oqM-d\(cq. +.lp "" +The \(oqm\(cq prefix skips dipping into a fountain or pool if there +is one at your location. .lp "#down " Go down a staircase. Default key is \(oq>\(cq. @@ -1113,20 +1336,43 @@ Advance or check weapon and spell skills. Autocompletes. Default key is \(oqM-e\(cq. .lp #exploremode -Enter the explore mode. +Switch from normal play to non-scoring explore mode. +Default key is \(oqM-X\(cq. .lp "" Requires confirmation; default response is \f(CRn\fP (no). To really switch to explore mode, respond with \f(CRy\fP. You can set the .op paranoid_confirmation:quit option to require a response of \f(CRyes\fP instead. +.lp "#fight " +Prefix key to force fight a direction, even if you see nothing +to fight there. +Default key is \(oqF\(cq, or \(oq\-\(cq with +.op number_pad .lp "#fire " -Fire ammunition from quiver. +Fire ammunition from quiver, possibly autowielding a launcher, +or hit with a wielded polearm. Default key is \(oqf\(cq. .lp "#force " Force a lock. Autocompletes. Default key is \(oqM-f\(cq. +.lp #genocided +List any monster types which have been genocided. +In explore mode and debug mode it also shows types which have become +extinct. +.lp "" +The display order is the same as is used by #vanquished. +The \(oqm\(cq prefix brings up a menu of available sorting orders, and +doing that for either #genocided or #vanquished changes the order for both. +.lp "" +If the sorting order is \(lqcount high to low\(rq or \(lqcount low to high\(rq +(which are applicable for #vanquished), that will be ignored +for #genocided and alphabetical will be used instead. +The menu omits those two choices when used for #genocide. +.lp "" +Autocompletes. +Default key is \(oqM-g\(cq. .lp "#glance " Show what type of thing a map symbol corresponds to. Default key is \(oq;\(cq. @@ -1136,10 +1382,17 @@ Default key is \(oq?\(cq, and also \(oqh\(cq if .op number_pad is on. .lp #herecmdmenu -Show a menu of possible actions in your current location. +Show a menu of possible actions directed at your current location. +The menu is limited to a subset of the likeliest actions, not an +exhaustive set of all possibilities. +Autocompletes. +.lp "" +If mouse support is enabled and the +.op herecmd_menu +option is On, clicking on the hero (or steed when mounted) will +execute this command. .lp "#history " -Show long version and game history. -Default key is \(oqV\(cq. +Show a summary of the game's development. .lp #inventory Show your inventory. Default key is \(oqi\(cq. @@ -1163,10 +1416,16 @@ Default key is \(oq\(haD\(cq, and \(oqk\(cq if is on. .lp "#known " Show what object types have been discovered. -Default key is \(oq\\\(cq. +Default key is \(oq\f(CR\\\fP\(cq. +.lp "" +The \(oq\f(CRm\fP\(cq prefix allows assigning a new value to the +.op sortdiscoveries +option to control the order in which the discoveries are displayed. .lp #knownclass Show discovered types for one class of objects. -Default key is \(oq\`\(cq. +Default key is \(oq\f(CR\`\fP\(cq. +.lp "" +The \(oq\f(CRm\fP\(cq prefix operates the same as for \(lq#known\(rq. .lp #levelchange Change your experience level. Autocompletes. @@ -1178,6 +1437,8 @@ Debug mode only. .lp "#look " Look at what is here, under you. Default key is \(oq:\(cq. +.lp #lookaround +Describe what you can see, or remember, of your surroundings. .lp "#loot " Loot a box or bag on the floor beneath you, or the saddle from a steed standing next to you. @@ -1211,14 +1472,30 @@ Default key is \(oqo\(cq. .lp "#options " Show and change option settings. Default key is \(oqO\(cq. +Precede with the \(oqm\(cq prefix to show advanced options. +.lp #optionsfull +Show advanced game option settings. +No default key. +Precede with the \(oqm\(cq prefix to execute the simpler options command. +(Mainly useful if you use \f(CRBINDING=O:optionsfull\fP to switch +\(oq\f(CRO\fP\(cq from simple options back to traditional advanced options.) .lp #overview Display information you've discovered about the dungeon. -Any visited -level (unless forgotten due to amnesia) with an annotation is included, +Any visited level +.\" [note: amnesia no longer causes levels to be forgotten so exclude this] +.\" (unless forgotten due to amnesia) +with an annotation is included, and many things (altars, thrones, fountains, and so on; extra stairs leading to another dungeon branch) trigger an automatic annotation. If dungeon overview is chosen during end-of-game disclosure, every visited level will be included regardless of annotations. +.lp "" +Precede #overview with the \(oqm\(cq prefix to display the dungeon +overview as a menu where you can select any visited level to add or +remove an annotation without needing to return to that level. +This will also force all visited levels to be displayed rather than just +the \(lqinteresting\(rq subset. +.lp "" Autocompletes. Default keys are \(oq\(haO\(cq, and \(oqM-O\(cq. .\" DON'T PANIC! @@ -1236,6 +1513,14 @@ option to require a response of \f(CRyes\fP instead. .lp "#pay " Pay your shopping bill. Default key is \(oqp\(cq. +.lp "#perminv " +If persistent inventory display is supported and enabled (with the +.op perm_invent +option), interact with it instead of with the map. +You'll be prompted for menu scrolling keystrokes such +as \(oq\f(CR>\fP\(cq and \(oq\f(CR<\fP\(cq. +Press \f(CRReturn\fP or \f(CREscape\fP to resume normal play. +Default key is \(oq|\(cq. .lp "#pickup " Pick up things at the current location. Default key is \(oq,\(cq. @@ -1266,10 +1551,12 @@ Default key is \(oqP\(cq. .lp "#quaff " Quaff (drink) something. Default key is \(oqq\(cq. +.lp "" +The \(oqm\(cq prefix skips drinking from a fountain or sink if there +is one at your location. .lp "#quit " Quit the program without saving your game. Autocompletes. -Default key is \(oqM-q\(cq. .lp "" Since using this command by accident would throw away the current game, you are asked to confirm your intent before quitting. @@ -1292,6 +1579,17 @@ is on. .lp "#remove " Remove an accessory (ring, amulet, etc). Default key is \(oqR\(cq. +.lp "#repeat " +Repeat the previous command. +Default key is \(oq\(haA\(cq. +.lp "#reqmenu " +Prefix key to modify the behavior or request menu from some commands. +Prevents autopickup when used with movement commands. +Default key is \(oqm\(cq. +.lp "#retravel" +Travel to a previously selected travel destination. +Default key is \(oqC-_\(cq. +See also #travel. .lp "#ride " Ride (or stop riding) a saddled creature. Autocompletes. @@ -1300,46 +1598,97 @@ Default key is \(oqM-R\(cq. Rub a lamp or a stone. Autocompletes. Default key is \(oqM-r\(cq. +.lp "#run " +Prefix key to run towards a direction. +Default key is \(oqG\(cq when +.op number_pad +is off, +\(oq5\(cq when +.op number_pad +is set to 1 or 3, +otherwise \(oqM-5\(cq when it is set to 2 or 4. +.lp "#rush " +Prefix key to rush towards a direction. +Default is \(oqg\(cq when +.op number_pad +is off, +\(oqM-5\(cq when +.op number_pad +is set to 1 or 3, +otherwise \(oq5\(cq when it is set to 2 or 4. .lp "#save " Save the game and exit the program. Default key is \(oqS\(cq. +.lp "#saveoptions" +Save configuration options to the config file. +This will overwrite the file, removing all comments, so if you have +manually edited the config file, don't use this. .lp "#search " Search for traps and secret doors around you. Default key is \(oqs\(cq. .lp "#seeall " Show all equipment in use. Default key is \(oq*\(cq. +.lp "" +Will display in-use items in a menu even when there is only one. .lp #seeamulet Show the amulet currently worn. Default key is \(oq\(dq\(cq. \" double quote +.lp "" +Using the \(oq\f(CRm\fP\(cq prefix will force the display of a worn +amulet in a menu rather than with just a message. .lp #seearmor Show the armor currently worn. Default key is \(oq[\(cq. -.lp "#seegold " -Count your gold. -Default key is \(oq$\(cq. -.lp "#seenv " -Show seen vectors. -Autocompletes. -Debug mode only. +.lp "" +Will display worn armor in a menu even when there is only thing worn. .lp #seerings Show the ring(s) currently worn. Default key is \(oq=\(cq. -.lp #seespells -List and reorder known spells. -Default key is \(oq+\(cq. +.lp "" +Will display worn rings in a menu if there are two (or there is +just one and is a meat ring rather than a \(lqreal\(rq ring). +Use the \(oq\f(CRm\fP\(cq prefix to force a menu for one ring. .lp #seetools Show the tools currently in use. Default key is \(oq(\(cq. -.lp "#seetrap " -Show the type of an adjacent trap. -Default key is \(oq\(ha\(cq. \" 'hat' (circumflex character) +.lp "" +Will display the result in a message if there is one tool in use (worn +blindfold or towel or lenses, lit lamp(s) and/or candle(s), leashes +attached to pets). +Will display a menu if there are more than one or if the command is +preceded by the \(oq\f(CRm\fP\(cq prefix. .lp #seeweapon Show the weapon currently wielded. Default key is \(oq)\(cq. +.lp "" +If dual-wielding, a separate message about the secondary weapon will be +given. +Using the \(oq\f(CRm\fP\(cq prefix will force a menu and it will include +primary weapon, alternate weapon even when not dual-wielding, and also +whatever is currently assigned to the quiver slot. .lp "#shell " -Do a shell escape. +Do a shell escape, switching from NetHack to a subprocess. +Can be disabled at the time the program is built. +When enabled, access for specific users can be controlled by the system +configuration file. +Use the shell command \(oq\f(CRexit\fP\(cq to return to the game. Default key is \(oq!\(cq. +.lp "#showgold" +Report the gold in your inventory, including gold you know about in +containers you're carrying. If you are inside a shop, report any credit +or debt you have in that shop. +Default key is \(oq$\(cq. +.lp #showspells +List and reorder known spells. +Default key is \(oq+\(cq. +.lp "#showtrap" +Describe an adjacent trap, possibly covered by objects or a monster. +To be eligible, the trap must already be discovered. +(The \(lq#terrain\(rq command can display your map with all objects and +monsters temporarily removed, making it possible to see all discovered +traps.) +Default key is \(oq\(ha\(cq. \" 'hat' (circumflex character) .lp "#sit " Sit down. Autocompletes. @@ -1349,7 +1698,12 @@ Show memory usage statistics. Autocompletes. Debug mode only. .lp "#suspend " -Suspend the game. +Suspend the game, switching from NetHack to the terminal it was started +from without performing save-and-exit. +Can be disabled at the time the program is built. +When enabled, mainly useful for \fItty\fP and \fIcurses\fP interfaces on +.UX \. \" yields "UNIX." +Use the shell command \(oq\f(CRfg\fP\(cq to return to the game. Default key is \(oq\(haZ\(cq. .lp "#swap " Swap wielded and secondary weapons. @@ -1364,10 +1718,30 @@ Default key is \(oqA\(cq. Teleport around the level. Default key is \(oq\(haT\(cq. .lp "#terrain " -Show bare map without displaying monsters, objects, or traps. +Show map without obstructions. +In normal play you can view the explored portion of the current level's +map without monsters; without monsters and objects; or without monsters, +objects, and traps. +.lp "" +If there are visible clouds of gas in view, they are treated like traps +when deciding whether to show them or the floor underneath them. +.lp "" +In explore mode, you can choose to view the full map rather than just +its explored portion. +In debug mode there are additional choices. +.lp "" Autocompletes. +Default key is \(oq\(cq or \(oq\(cq (see \fIDel\fP above). .lp #therecmdmenu -Show a menu of possible actions in a location next to you. +Show a menu of possible actions directed at a location next to you. +The menu is limited to a subset of the likeliest actions, not an +exhaustive set of all possibilities. +Autocompletes. +.\"--invoking it by mouse seems to be broken +.\" .lp "" +.\" If mouse support is enabled and the +.\" .op herecmd_menu +.\" option is On, clicking on an adjacent location will execute this command. .lp "#throw " Throw something. Default key is \(oqt\(cq. @@ -1377,9 +1751,31 @@ Autocompletes. Debug mode only. .lp "#tip " Tip over a container (bag or box) to pour out its contents. +When there are containers on the floor, the game will prompt to pick one +of them or \(lqtip something being carried\(rq. +If the latter is chosen, there will be another prompt for which item +from inventory to tip. +.lp "" +The \(oq\f(CRm\fP\(cq prefix makes the command skip containers on the +floor and pick one from inventory, except for the special case of +.op menustyle \f(CR:traditional\fP +with two or more containers present; that situation will start with the +floor container menu. +.lp "" Autocompletes. Default key is \(oqM-T\(cq. -The \(oqm\(cq prefix makes the command use a menu. +.lp "#toggle " +Toggle a boolean option on or off. +Requires a parameter in parenthesis, the name of the option to toggle. +The option must be settable in-game. +.lp "" +For example: +.sd +.ft CR +BIND=':toggle(price_quotes) +BIND=@:toggle(autopickup) +.ft +.ed .lp "#travel " Travel to a specific location on the map. Default key is \(oq_\(cq. \" underscore @@ -1389,6 +1785,7 @@ When picking a target with cursor and the .op autodescribe option is on, the top line will show \(lq(no travel path)\(rq if your character does not know of a path to that location. +See also #retravel. .lp "#turn " Turn undead away. Autocompletes. @@ -1414,16 +1811,41 @@ In some circumstances it can also be used to rescue trapped monsters. Go up a staircase. Default key is \(oq<\(cq. .lp #vanquished -List vanquished monsters. +List vanquished monsters by type and count. +.lp "" +Note that the vanquished monsters list includes all monsters killed by +traps and each other as well as by you, and omits any which got removed +from the game without being killed (perhaps by genocide, or by a mollified +shopkeeper dismissing summoned Kops) or were already corpses when placed +on the map. +.lp "" +Using the \(lqrequest menu\(rq prefix prior to #vanquished brings up +a menu of sorting orders available (provided that the vanquished monsters +list contains at least two types of monsters). +Whichever ordering is picked gets assigned to the +.op sortvanquished +option so is remembered for subsequent #vanquished requests. +The \(lq#genocided\(rq command shares this sorting order. +.lp "" +During end-of-game disclosure, when asked whether to show vanquished +monsters answering \(oq\f(CRa\fP\(cq will let you choose from the sort menu. +.lp "" Autocompletes. -Debug mode only. +Default key is \(oqM-V\(cq. .lp "#version " Print compile time options for this version of NetHack. +.lp "" +The second paragraph lists the user interface(s) that are included. +If there are more than one, you can use the +.op windowtype +option in your run-time configuration file to select the one you want. +.lp "" Autocompletes. Default key is \(oqM-v\(cq. .lp #versionshort -Show version string. -Default key is \(oqv\(cq. +Show the program's version number, plus the date and time that the +running copy was built from sources (not the version's release date). +Default key is \(oqV\(cq. .lp "#vision " Show vision array. Autocompletes. @@ -1449,13 +1871,20 @@ Default key is \(oqw\(cq. Wipe off your face. Autocompletes. Default key is \(oqM-w\(cq. +.lp "#wizborn " +Show monster birth, death, genocide, and extinct statistics. +Debug mode only. .lp "#wizbury " Bury objects under and around you. Autocompletes. Debug mode only. +.lp #wizcast +Cast any spell. +Debug mode only. .lp #wizdetect -Search for hidden things (secret doors or traps or unseen monsters) +Reveal hidden things (secret doors or traps or unseen monsters) within a modest radius. +No time elapses. Autocompletes. Debug mode only. Default key is \(oq\(haE\(cq. @@ -1474,6 +1903,12 @@ Default key is \(oq\(haI\(cq. Set one or more intrinsic attributes. Autocompletes. Debug mode only. +.lp "#wizkill " +Remove monsters from play by just pointing at them. +By default the hero gets credit or blame for killing the targets. +Precede this command with the \(oq\f(CRm\fP\(cq prefix to override that. +Autocompletes. +Debug mode only. .lp #wizlevelport Teleport to another level. Autocompletes. @@ -1485,7 +1920,16 @@ Autocompletes. Debug mode only. Default key is \(oq\(haF\(cq. .lp #wizrumorcheck -Verify rumor boundaries. +Verify rumor boundaries by displaying first and last true rumors and +first and last false rumors. +.lp "" +Also displays first, second, and last random engravings, epitaphs, +and hallucinatory monsters. +.lp "" +Autocompletes. +Debug mode only. +.lp #wizseenv +Show map locations' seen vectors. Autocompletes. Debug mode only. .lp #wizsmell @@ -1501,6 +1945,7 @@ Wish for something. Autocompletes. Debug mode only. Default key is \(oq\(haW\(cq. +Precede this command with the \(oq\f(CRm\fP\(cq prefix to show a wish history menu. .lp "#wmode " Show wall modes. Autocompletes. @@ -1517,16 +1962,24 @@ with another key, modifies it by setting the \(lqmeta\(rq [8th, or \(lqhigh\(rq] bit), you can invoke many extended commands by meta-ing the first letter of the command. .pg -In \fINT\fP, \fIOS/2\fP, \fIPC\fP and \fIST\fP \fINetHack\fP, -the \(lqAlt\(rq key can be used in this fashion; -on the \fIAmiga\fP, set the -.op altmeta -option to get this behavior. +On \fIWindows\fP and \fIMS-DOS\fP, +the \(lqAlt\(rq key can be used in this fashion. On other systems, if typing \(lqAlt\(rq plus another key transmits a two character sequence consisting of an \fBEscape\fP followed by the other key, you may set the .op altmeta -option to have NetHack combine them into meta+key. +option to have NetHack combine them into meta+. +(This combining action only takes place when NetHack is expecting a +command to execute, not when accepting input to name something or to +make a wish.) +.pg +Unlike control characters, where \(hax and \(haX denote the same thing, +meta characters are case-sensitive: M-x and M-X represent different things. +Some commands which can be run via a meta character require that the +letter be capitalized because the lower-case equivalent is used for +another command, so the three key combination meta+Shift+ is needed. +.BR 1 +. .lp M-? #? (not supported by all platforms) .lp M-2 @@ -1547,6 +2000,8 @@ option is enabled) #enhance .lp M-f #force +.lp M-g +#genocided .lp M-i #invoke .lp M-j @@ -1563,8 +2018,6 @@ option is enabled) #overview .lp M-p #pray -.lp M-q -#quit .lp M-r #rub .lp M-R @@ -1579,8 +2032,12 @@ option is enabled) #untrap .lp M-v #version +.lp M-V +#vanquished .lp M-w #wipe +.lp M-X +#exploremode .lp "" .pg If the @@ -1599,6 +2056,7 @@ option is on, some additional letter commands are available: .lp u #untrap . +.BR 1 \"blank line for extra separation; plain text output looks better .hn 1 Rooms and corridors .pg @@ -1607,49 +2065,146 @@ Any lit areas within your line of sight will be displayed; dark areas are only displayed if they are within one space of you. Walls and corridors remain on the map as you explore them. .pg -Secret corridors are hidden. You can find them with the \(oqs\(cq (search) -command. +Secret corridors are hidden and appear to be solid rock. +You can find them with the \(oqs\(cq (search) command when adjacent +to them. +Multiple search attempts may be needed. +When searching is successful, secret corridors become ordinary open +corridor locations. +Mapping magic reveals secret corridors, so converts them into ordinary +corridors and shows them as such. .hn 2 Doorways .pg -Doorways connect rooms and corridors. Some doorways have no doors; -you can walk right through. Others have doors in them, which may be -open, closed, or locked. To open a closed door, use the \(oqo\(cq (open) +Doorways connect rooms and corridors. +Some doorways have no doors; you can walk right through. +Others have doors in them, which may be open, closed, or locked. +To open a closed door, use the \(oqo\(cq (open) command; to close it again, use the \(oqc\(cq (close) command. -.pg -You can get through a locked door by using a tool to pick the lock -with the \(oqa\(cq (apply) command, or by kicking it open with -the \(oq\(haD\(cq (kick) command. +By default the +.op autoopen +option is enabled, so simply attempting to walk onto a closed door's +location will attempt to open it without needing \(oqo\(cq. +Opening via +.op autoopen +will not work if you are \fIconfused\fP or \fIstunned\fP or suffer from +the \fIfumbling\fP attribute. .pg Open doors cannot be entered diagonally; you must approach them -straight on, horizontally or vertically. Doorways without doors are -not restricted in this fashion. -.pg -Doors can be useful for shutting out monsters. Most monsters cannot -open doors, although a few don't need to (for example, ghosts can walk through -doors). -.pg -Secret doors are hidden. You can find them with the \(oqs\(cq (search) -command. Once found they are in all ways equivalent to normal doors. +straight on, horizontally or vertically. +Doorways without doors are +not restricted in this fashion except on one particular level +.\" the rogue level +(described by \(lq#overview\(rq as \(lqa primitive area\(rq). +.pg +Unlocking magic exists but usually won't be available early on. +You can get through a locked door without magic by first using an +unlocking tool with the \(oqa\(cq (apply) command, and then opening it. +By default the +.op autounlock +option is also enabled, so if you attempt to open (via \(oqo\(cq or +.op autoopen) +a locked door while carrying an unlocking tool, you'll be asked whether +to use it on the door's lock. +Alternatively, you can break a closed door (whether locked or not) down +by kicking it via the \(oq\(haD\(cq (kick) command. +Kicking down a door destroys it and makes a lot of noise which might +wake sleeping monsters. +.pg +Some closed doors are booby-trapped and will explode if an attempt is made +to open (when unlocked) or unlock (when locked) or kick down. +Like kicking, an explosion destroys the door and makes a lot of noise. +The \(lq#untrap\(rq command can be used to search a door for traps but +might take multiple attempts to find one. +When one is found, you'll be asked whether to try to disarm it. +If you accede, success will eliminate the trap but +failure will set off the trap's explosion. +(If you decline, you effectively forget that a trap was found there.) +.pg +Closed doors can be useful for shutting out monsters. +Most monsters cannot open closed doors, although a few don't need to +(for example, ghosts can walk through doors and fog clouds can flow +under them). +Some monsters who can open doors can also use unlocking tools. +And some (giants) can smash doors. +.pg +Secret doors are hidden and appear to be ordinary wall (from inside a +room) or solid rock (from outside). +You can find them with the \(oqs\(cq (search) command but it might +take multiple tries (possibly many tries if your luck is poor). +Once found they are in all ways equivalent to normal doors. +Mapping magic does not reveal secret doors. .hn 2 Traps (\(oq\(ha\(cq) .pg -There are traps throughout the dungeon to snare the unwary delver. +There are traps throughout the dungeon to snare the unwary intruder. For example, you may suddenly fall into a pit and be stuck for a few -turns trying to climb out. -Traps don't appear on your map until you -see one triggered by moving onto it, see something fall into it, or you -discover it with the \(oqs\(cq (search) command. -Monsters can fall prey to -traps, too, which can be a very useful defensive strategy. +turns trying to climb out (see below). +A trap usually won't appear on your map until you trigger it by moving +onto it, you see someone else trigger it, or you discover it with +the \(oqs\(cq (search) command (multiple attempts are often needed; +if your luck is poor, many attempts might be needed). +\fIWands of secret door detection\fP and \fIspell of detect unseen\fP +also reveal traps within a modest radius but only if the trap is also +within line-of-sight (whether you can see at the time or not). +There is also other magic which can reveal traps. .pg -There is a special pre-mapped branch of the dungeon based on the -classic computer game \(lqSokoban.\(rq -The goal is to push the boulders into the pits or holes. +Monsters can fall prey to +traps, too, which can potentially be used as a defensive strategy. +Unfortunately traps can be harmful to your pet(s) as well. +Monsters, including pets, usually will avoid moving onto a trap which +is shown on your map if they have encountered that type of trap before. +.pg +Some traps such as pits, bear traps, and webs hold you in one place. +You can escape by simply trying to move to an adjacent spot and repeat +as needed; eventually you will get free. +.pg +Other traps can send you to different locations. +Teleporters send you elsewhere on the same dungeon level. +Level teleporters send you to a random dungeon level, the destination +chosen from a few levels lower all the way to the top. +These traps choose a new destination each time they're activated. +Trap doors and holes also send you to another level, but one which is +always below the current level. +Usually that will be the next level down but it can be farther. +Unlike (level) teleporters, the destination level of a particular trap door +or hole is persistent, so falling into one will bring you to the same level +each time\(emthough not necessarily the same spot on the level. +Magic portals behave similarly, but with some additional variation. +Some portals are two-way and their remote destination is always the same: +another portal which can take you back. +Others are one-way and send you to a specific destination level but not +necessarily to a specific location there. +.pg +There is a special multi-level branch of the dungeon with pre-mapped levels +based on the classic computer game \(lq\fISokoban\fP.\(rq +In that game, you operate as a warehouse worker who pushes crates around +obstacles to position them at designated locations. +In NetHack, the goal is to push boulders into pits or holes until those +traps have all been nullified, giving access to whatever is beyond them. +In the Sokoban game, you can only move in the four cardinal compass +directions, and a crate in its final destination blocks further access +to that spot. +In the Sokoban levels of NetHack, you can move diagonally (unless that +would let you pass between two neighboring boulders) but you can only +push boulders in the four cardinal directions, and a boulder which fills +a pit or hole removes both the boulder and the trap so opens up normal +access to that spot. With careful foresight, it is possible to complete all of the levels according to the traditional rules of Sokoban. -Some allowances are permitted in case the player gets stuck; -however, they will lower your luck. +(Hint: to solve Sokoban puzzles, you often need to move things away from +their eventual destinations in order to open up more room to maneuver.) +Since NetHack does not support an \fIundo\fP capability, some allowances +are permitted in case you get stuck. +For example, each level has at least one extra boulder. +Also, it is possible to drop everything in order to be able to squeeze +into the same location as a boulder (and then presumably move past it), +or to destroy a boulder with magic or tools, or to create new boulders +with a \fIscroll of earth\fP. +However, doing such things will lower your luck without any specific +message given about that. +See the \fIConduct\fP section for information about getting feedback for +your actions in Sokoban. .hn 2 Stairs and ladders (\(oq<\(cq, \(oq>\(cq) .pg @@ -1708,16 +2263,17 @@ If you drop something in a shop by accident, the shopkeeper will usually claim ownership without offering any compensation. You'll have to buy it back if you want to reclaim it. .pg -Shopkeepers sometimes run out of money. When that happens, you'll be -offered credit instead of gold when you try to sell something. Credit -can be used to pay for purchases, but it is only good in the shop where -it was obtained; other shopkeepers won't honor it. (If you happen to +Shopkeepers sometime run out of money. +When that happens, you'll be +offered credit instead of gold when you try to sell something. +Credit can be used to pay for purchases, but it is only good in the shop +where it was obtained; other shopkeepers won't honor it. +(If you happen to find a \(lqcredit card\(rq in the dungeon, don't bother trying to use it in shops; shopkeepers will not accept it.) .pg -The \(oq$\(cq command, which reports the amount of gold you are carrying -(in inventory, not inside bags or boxes), will also show current shop -debt or credit, if any. +The \(oq$\(cq command, which reports the amount of gold you are carrying, +will also show current shop debt or credit, if any. The \(lqIu\(rq command lists unpaid items (those which still belong to the shop) if you are carrying any. The \(lqIx\(rq command shows an inventory-like display of any unpaid @@ -1733,12 +2289,107 @@ The price of a given item can vary due to a variety of factors. A shopkeeper treats the spot immediately inside the door as if it were outside the shop. .lp * 2 -While the shopkeeper watches you like a hawk, he will generally ignore +While the shopkeeper watches you like a hawk, he or she will generally ignore any other customers. .lp * 2 If a shop is \(lqclosed for inventory,\(rq it will not open of its own accord. .lp * 2 Shops do not get restocked with new items, regardless of inventory depletion. +.hn 2 +Movement feedback +.pg +Moving around the map usually provides no +feedback\(emother than drawing the hero at the new location\(emunless +you step on an object or pile of objects, +or on a trap, or attempt to move onto a spot where a monster is located. +There are several options which can be used to augment the normal feedback. +.pg +The +.op pile_limit +option controls how many objects can be in a +pile\(emsharing the same map location\(emfor +the game to state \(lqthere are objects here\(rq instead of listing them. +The default is \f(CR5\fP. +Setting it to \f(CR1\fP would always give that message instead of listing +any objects. +Setting it to \f(CR0\fP is a special case which will always list all +objects no matter how big a pile is. +Note that the number refers to the count of separate stacks of objects +present rather than the sum of the quantities of those stacks (so +\f(CR7 arrows\fP or \f(CR25 gold pieces\fP will each count as 1 rather +than as 7 and 25, respectively, and total to 2 when both are at the +same location). +.pg +The \(lqnopickup\(rq command prefix (default \(oq\f(CRm\fP\(cq) can be +used before a movement direction to step on objects without attempting +auto-pickup and without giving feedback about them. +.pg +The +.op mention_walls +option controls whether you get feedback if you try to walk into a wall +or solid stone or off the edge of the map. +Normally nothing happens (unless the hero is blind and no wall is shown, +then the wall that is being bumped into will be drawn on the map). +This option also gives feedback when rushing or running stops for +some non-obvious reason. +.pg +The +.op mention_decor +option controls whether you get feedback when walking on \(lqfurniture.\(rq +Normally stepping onto stairs or a fountain or an altar or various other +things doesn't elicit anything unless it is covered by one or more objects +so is obscured on the map. +Setting this option to true will describe such things even when they +aren't obscured. +Doorless doorways and open doors aren't considered worthy of mention; +closed doors (if you can move onto their spots) and broken doors are. +Assuming that you're able to do so, moving onto water or lava or ice +will give feedback if not yet on that type of terrain but not repeat it +(unless there has been some intervening message) when moving from water +to another water spot, or lava to lava, or ice to ice. +Moving off of any of those back onto \(lqnormal\(rq terrain will give one +message too, unless there is feedback about one or more objects, in which +case the back on land circumstance is implied. +.pg +The +.op confirm +and +.op safe_pet +options control what happens when you try to move onto a peaceful monster's +spot or a tame one's spot. +.\" getting away from "Movement feedback" here; oh well... +.pg +The \(lqnopickup\(rq command prefix (default \(oq\f(CRm\fP\(cq) is +also the move-without-attacking prefix and can be used to try to step +onto a visible monster's spot without the move being considered an attack +(see the \fIFighting\fP subsection of \fIMonsters\fP below). +The \(lqfight\(rq command prefix (default \(oq\f(CRF\fP\(cq; +also \(oq\f(CR\-\fP\(cq if +.op number_pad +is on) can be used to force an attack, when guessing where an unseen +monster is or when deliberately attacking a peaceful or tame creature. +.pg +The +.op run_mode +option controls how frequently the map gets redrawn when moving more +than one step in a single command (so when rushing, running, or traveling). +.hn 2 +Rogue level +.pg +One dungeon level (occurring in mid to late teens of the main dungeon) +is a tribute to the ancestor game \fIhack\fP's inspiration \fIrogue\fP. +.pg +It is usually displayed differently from other levels: possibly in +characters instead of tiles, or without line-drawing symbols if already +in characters; also, gold is shown as \f(CR*\fP rather than \f(CR$\fP +and stairs are shown as \f(CR%\fP rather than \f(CR<\fP and \f(CR>\fP. +There are some minor differences in actual game play: doorways lack +doors; a scroll, wand, or spell of light used in a room lights up the +whole room rather than within a radius around your character. +And monsters represented by lower-case letters aren't randomly +generated on the rogue level. +.pg +The slight strangeness of this level is a feature, not a bug.... . .hn 1 Monsters @@ -1764,8 +2415,10 @@ shopkeeper or the Oracle of Delphi can produce useful results. Fighting .pg If you see a monster and you wish to fight it, just attempt to walk -into it. Many monsters you find will mind their own business unless -you attack them. Some of them are very dangerous when angered. +into it. +Many monsters you find will mind their own business unless +you attack them. +Some of them are very dangerous when angered. Remember: discretion is the better part of valor. .pg In most circumstances, if you attempt to attack a peaceful monster by @@ -1773,7 +2426,7 @@ moving into its location, you'll be asked to confirm your intent. By default an answer of \(oqy\(cq acknowledges that intent, which can be error prone if you're using \(oqy\(cq to move. You can set the -.op paranoid_confirmation +.op paranoid_confirmation:attack option to require a response of \(lqyes\(rq instead. .pg If you can't see a monster (if it is invisible, or if you are blinded), @@ -1855,9 +2508,9 @@ Moving to a location where you can't see or sense a monster any more will result in it disappearing from your map, similarly if it is the one who moved rather than you. .pg -However, if you encounter a monster which you can't see or sense \(em -perhaps it is invisible and has just tapped you on the noggin \(em -a special \(lqremembered, unseen monster\(rq marker will be displayed at +However, if you encounter a monster which you can't see or +sense\(emperhaps it is invisible and has just tapped you on the noggin\(ema +special \(lqremembered, unseen monster\(rq marker will be displayed at the location where you think it is. That will persist until you have proven that there is no monster there, even if the unseen monster @@ -1868,11 +2521,11 @@ location ordinarily wouldn't be seen any more. Objects .pg When you find something in the dungeon, it is common to want to pick -it up. In NetHack, this is accomplished automatically by walking over -the object (unless you turn off the +it up. In NetHack, this is accomplished by using the \(oq,\(cq command. +If .op autopickup -option (see below), or move with the \(oqm\(cq prefix (see above)), or -manually by using the \(oq,\(cq command. +option is on, you will automatically pick up the object +by walking over, unless you move with the \(oqm\(cq prefix. .pg If you're carrying too many items, NetHack will tell you so and you won't be able to pick up anything more. @@ -1892,8 +2545,8 @@ to discard some of what you're carrying or collapse under its weight. .pg NetHack will tell you how badly you have loaded yourself. If you are encumbered, one of the conditions -\(lq\fIBurdened\fP\(rq, \(lq\fIStressed\fP\(rq, \(lq\fIStrained\fP\(rq, -\(lq\fIOvertaxed\fP\(rq or \(lq\fIOverloaded\fP\(rq will be +\f(CRBurdened\fP, \f(CRStressed\fP, \f(CRStrained\fP, +\f(CROvertaxed\fP, or \f(CROverloaded\fP will be shown on the bottom line status display. .pg When you pick up an object, it is assigned an inventory letter. Many @@ -1929,9 +2582,10 @@ usually, but not always, bear negative enchantments that make them less effective in combat. Other cursed objects may act poorly or detrimentally in other ways. .pg -Objects can also be blessed. Blessed items usually work better or -more beneficially than normal uncursed items. For example, a blessed -weapon will do more damage against demons. +Objects can also be blessed instead. +Blessed items usually work better or more beneficially than normal +uncursed items. +For example, a blessed weapon will do slightly more damage against demons. .pg Objects which are neither cursed nor blessed are referred to as uncursed. They could just as easily have been described as unblessed, but the @@ -1941,20 +2595,78 @@ that what you will. .pg There are magical means of bestowing or removing curses upon objects, so even if you are stuck with one, you can still have the curse -lifted and the item removed. Priests and Priestesses have an innate +lifted and the item removed. +Priests and Priestesses have an innate sensitivity to this property in any object, so they can more easily avoid cursed objects than other character roles. +Dropping objects onto an altar will reveal their bless or curse state +provided that you can see them land. .pg An item with unknown status will be reported in your inventory with no prefix. An item which you know the state of will be distinguished in your inventory -by the presence of the word \(lqcursed\(rq, \(lquncursed\(rq or -\(lqblessed\(rq in the description of the item. -In some cases \(lquncursed\(rq will be omitted as being redundant when +by the presence of the word \f(CRcursed\fP, \f(CRuncursed\fP, or +\f(CRblessed\fP in the description of the item. +In some cases \f(CRuncursed\fP will be omitted as being redundant when enough other information is displayed. The .op implicit_uncursed -option can be used to control this; toggle it off to have \(lquncursed\(rq +option can be used to control this; toggle it off to have \f(CRuncursed\fP be displayed even when that can be deduced from other attributes. +.pg +Sometimes the bless or curse state of objects is referred to as their +\(lq\f(CRBUC\fP\(rq attribute, for Blessed, Uncursed, or Cursed state, +or \(lq\f(CRBUCX\fP\(rq for Blessed, Uncursed, Cursed, or unknown. +(The term \fIbeatitude\fP is occasionally used as well.) +.hn 2 +Artifacts +.pg +Some objects have been imbued with special powers and are known as +\fBArtifacts\fP. +They have specific types (such as long sword or orcish dagger) and distinct +names such as \fIGiantslayer\fP or \fIGrimtooth\fP. +Artifact weapons typically do more damage than their ordinary counterparts. +Some do extra damage against all monsters, others only against specific +types of monsters so aren't better than regular weapons against other types. +Some confer defensive capabilities when wielded or have other powers that +aren't listed here. +.pg +You might find them simply lying on the floor, including but not limited +to inside shops, or be granted as a reward for \(lq#offer\(rq on an +altar to your patron deity. +A few might be dropped by monsters, or might be converted from an ordinary +object of the same type via assigning the right name. +.\" should we mention dipping for Excalibur here? +Or you might wish for them, if you happen to be granted a wish, but such +wishes can fail. +.pg +Some artifacts have a specific alignment, others don't. +You won't obtain aligned ones that have a different alignment from yours +via offering and might get a shock if you attempt to wish for any of those +or find one and attempt to use it. +.pg +Each role has a distinct artifact that is contained in the \fIQuest\fP +dungeon branch. +These are commonly known as quest artifacts. +All are aligned and most are non-weapons. +They won't be found randomly. +.pg +The \(oq\f(CR\\\fP\(cq and \(oq\f(CR\`a\fP\(cq commands will +list artifacts that you have fully identified (knowing the name and item +type isn't sufficient). +.hn 2 +Relics +.pg +There are three unique items that are named and have limited special +powers but aren't classified as artifacts. +Each is guarded by a particular monster and you'll need to collect all +three for use late in the game. +.\" The relics are listed in the same order as the Oracle's message about +.\" them rather than in the order they need to be used for the invocation. +They are \fIthe Bell of Opening\fP, +\fIthe Book of the Dead\fP, and +\fIthe Candelabrum of Invocation\fP. +Their corresponding descriptions when not yet identified are +silver bell, papyrus spellbook, and candelabrum. .hn 2 Weapons (\(oq)\(cq) .pg @@ -1982,11 +2694,14 @@ Most weapons are subject to some type of damage like rust. Such \(lqerosion\(rq damage can be repaired. .pg The chance that an attack will successfully hit a monster, and the amount -of damage such a hit will do, depends upon many factors. Among them are: +of damage such a hit will do, depends upon many factors. +Among them are: type of weapon, quality of weapon (enchantment and/or erosion), experience -level, strength, dexterity, encumbrance, and proficiency (see below). The -monster's armor class \(em a general defense rating, not necessarily due to -wearing of armor \(em is a factor too; also, some monsters are particularly +level, strength, dexterity, encumbrance, and proficiency (see below). +The monster's armor +class\(ema general defense rating, not necessarily due to wearing of +armor\(emis +a factor too; also, some monsters are particularly vulnerable to certain types of weapons. .pg Many weapons can be wielded in one hand; some require both hands. @@ -2016,8 +2731,14 @@ Some of the more obscure weapons (such as the \fIaklys\fP, \fIlucern hammer\fP, and \fIbec-de-corbin\fP) are defined in an appendix to \fIUnearthed Arcana\fP, an AD&D supplement. .pg +Some interfaces support the +.op weaponstatus +option. +When it is enabled, an extra status condition is displayed, describing +the currently wielded weapon. +.pg The commands to use weapons are \(oqw\(cq (wield), \(oqt\(cq (throw), -\(oqf\(cq (fire, an alternate way of throwing), \(oqQ\(cq (quiver), +\(oqf\(cq (fire), \(oqQ\(cq (quiver), \(oqx\(cq (exchange), \(oqX\(cq (twoweapon), and \(lq#enhance\(rq (see below). .hn 3 @@ -2035,6 +2756,16 @@ Arrows can be thrown by hand, but can be thrown much farther and will be more likely to hit when thrown while you are wielding a bow. .pg +Some weapons will return when thrown. +A boomerang\(emprovided it fails to hit anything\(emis an obvious example. +If an aklys (thonged club) is thrown while it is wielded, it will return +even when it hits something. +A sufficiently strong hero can throw the warhammer \fIMjollnir\fP; +when thrown by a \fIValkyrie\fP it will return too. +However, aklyses and \fIMjollnir\fP occasionally fail to return. +Returning thrown objects occasionally fail to be caught, sometimes even +hitting the thrower, but when caught they become re-wielded. +.pg You can simplify the throwing operation by using the \(oqQ\(cq command to select your preferred \(lqmissile\(rq, then using the \(oqf\(cq command to throw it. @@ -2045,12 +2776,19 @@ There is also an option, which has NetHack choose another item to automatically fill your quiver (or quiver sack, or have at the ready) when the inventory slot used for \(oqQ\(cq runs out. -.pg -Some characters have the ability to fire a volley of multiple items in a -single turn. +If your quiver is empty, +.op autoquiver +is false, and you are wielding a weapon which returns when thrown, +you will throw that weapon instead of filling the quiver. +The fire command also has extra assistance, if +.op fireassist +is on it will try to wield a launcher matching the ammo in the quiver. +.pg +Some characters have the ability to throw or shoot a volley of multiple +items (from the same stack) in a single action. Knowing how to load several rounds of ammunition at -once \(em or hold several missiles in your hand \(em and still hit a -target is not an easy task. +once\(emor hold several missiles in your hand\(emand +still hit a target is not an easy task. Rangers are among those who are adept at this task, as are those with a high level of proficiency in the relevant weapon skill (in bow skill if you're wielding one to @@ -2119,15 +2857,18 @@ and which to ignore. .hn 3 Two-Weapon combat .pg -Some characters can use two weapons at once. Setting things up to +Some characters can use two weapons at once. +Setting things up to do so can seem cumbersome but becomes second nature with use. To wield two weapons, you need to use the \(lq#twoweapon\(rq command. But first you need to have a weapon in each hand. (Note that your two weapons are not fully equal; the one in the hand you normally wield with is considered primary and the other -one is considered secondary. The most noticeable difference is -after you stop \(em or before you begin, for that matter \(em wielding -two weapons at once. The primary is your wielded weapon and the +one is considered secondary. +The most noticeable difference is after you +stop\(emor before you begin, for that matter\(emwielding +two weapons at once. +The primary is your wielded weapon and the secondary is just an item in your inventory that's been designated as alternate weapon.) .pg @@ -2167,36 +2908,46 @@ protection than others. Your armor class is a measure of this protection. Armor class (AC) is measured as in AD&D, with 10 being the equivalent of no armor, and lower numbers meaning better armor. Each suit of armor which exists in AD&D gives the same protection in -NetHack. Here is an (incomplete) list of the armor classes provided by -various suits of armor: +NetHack. +.pg +Here is a list of the armor class values provided by suits of armor: . -.TS S +.\" Replace the old one suit per line table with a more condensed one. +.\" AC4 and AC7 have been split into two lines to accommodate plain text +.\" output (Guidebook.txt). AC4 needs it to reduce overall width; after +.\" that, AC7 became the longest and the table looks better by shortening +.\" it to get the second column (number) closer to the text on most lines. +.\" Both AC4 and AC7 have trailing tab plus empty comment on their first +.\" line and leading spaces to indent their second line. +.TS center; -a n. -dragon scale mail 1 -plate mail 3 -crystal plate mail 3 -bronze plate mail 4 -splint mail 4 -banded mail 4 -dwarvish mithril-coat 4 -elven mithril-coat 5 -chain mail 5 -orcish chain mail 6 -scale mail 6 -dragon scales 7 -studded leather armor 7 -ring mail 7 -orcish ring mail 8 -leather armor 8 -leather jacket 9 -no armor 10 +l r. +Dragon scale mail 1 +Plate mail, Crystal plate mail 3 +Bronze plate mail, Splint mail, \& + Banded mail, Dwarvish mithril-coat 4 +Chain mail, Elven mithril-coat 5 +Scale mail, Orcish chain mail 6 +Ring mail, Studded leather armor, \& + Dragon scales 7 +Leather armor, Orcish ring mail 8 +Leather jacket 9 +none 10 .TE .pg -You can also wear other pieces of armor (for example helmets, boots, shields, cloaks) -to lower your armor class even further, but you can only wear one item -of each category (one suit of armor, one cloak, one helmet, one -shield, and so on) at a time. +You can also wear other pieces of armor (cloak over suit, shirt under +suit, helmet, gloves, boots, shield) to lower your armor class even +further. +.\"--too obvious to mention unless we include polymorph into ettin or maralith +.\" You can wear at most one item of each category (one suit of armor, one +.\" cloak, one helmet, one shield, and so on) at a time. +Most of these provide a one or two point improvement to AC (making the +overall value smaller and eventually negative) but can also be +enchanted. +Shirts are an exception; they don't provide any protection unless enchanted. +Some cloaks also don't improve AC when unenchanted but all cloaks offer +some protection against rust or corrosion to suits worn under them and +against some monster \fItouch\fP attacks. .pg If a piece of armor is enchanted, its armor protection will be better (or worse) than normal, and its \(lqplus\(rq (or minus) will subtract from @@ -2212,9 +2963,24 @@ addition to being unremovable. Many types of armor are subject to some kind of damage like rust. Such damage can be repaired. Some types of armor may inhibit spell casting. .pg +The +.op nudist +option can be set (prior to game start) to attempt to play the entire +game without wearing any armor (a self-imposed challenge which is +extremely difficult to accomplish). +.pg +Some interfaces support the +.op armorstatus +option. +When it is enabled, an extra status condition is displayed, summarizing +currently worn armor. +.pg The commands to use armor are \(oqW\(cq (wear) and \(oqT\(cq (take off). -The \(oqA\(cq command can also be used to take off armor as well as other +The \(oqA\(cq command can be used to take off armor as well as other worn items. +Also, \(oqP\(cq (put on) and \(oqR\(cq (remove) which are normally for +accessories can be used for armor, but pieces of armor won't be shown +as likely candidates in a prompt for choosing what to put on or remove. .hn 2 Food (\(oq%\(cq) .pg @@ -2253,8 +3019,16 @@ magic spells on them). .pg One of the most useful of these is the \fIscroll of identify\fP, which can be used to determine what another object is, whether it is cursed or -blessed, and how many uses it has left. Some objects of subtle -enchantment are difficult to identify without these. +blessed, and how many uses it has left. +Some objects of subtle enchantment are difficult to identify without these. +.pg +A scroll whose label is known can be read even when the hero is blind. +If a scroll has been discovered, it will be listed in inventory by type +rather than by label, but the label is known in that situation even though +it isn't shown. +.pg +Many scrolls produce a different effect from usual if they are blessed or +cursed, or read while the hero is confused. .pg A mail daemon may run up and deliver mail to you as a \fIscroll of mail\fP (on versions compiled with this feature). @@ -2326,20 +3100,31 @@ Rings are very useful items, since they are relatively permanent magic, unlike the usually fleeting effects of potions, scrolls, and wands. .pg -Putting on a ring activates its magic. You can wear only two -rings, one on each ring finger. +Putting on a ring activates its magic. +You can wear at most two rings at any time, one on the ring finger of +each hand. .pg -Most rings also cause you to grow hungry more rapidly, the rate +Most worn rings also cause you to grow hungry more rapidly, the rate varying with the type of ring. .pg +When wearing gloves, rings are worn underneath. +If the gloves are cursed, rings cannot be put on and any already being +worn cannot be removed. +When worn gloves aren't cursed, you don't have to manually take them +off before putting on or removing a ring and then re-wear them after. +That's done implicitly to avoid unnecessary tedium. +.pg The commands to use rings are \(oqP\(cq (put on) and \(oqR\(cq (remove). +\(oqA\(cq, \(oqW\(cq, and \(oqT\(cq can also be used; see \fIAmulets\fP. .hn 2 Spellbooks (\(oq+\(cq) .pg Spellbooks are tomes of mighty magic. When studied with the \(oqr\(cq (read) command, they transfer to the reader the knowledge of a spell (and -therefore eventually become unreadable) \(em unless the attempt backfires. +therefore eventually become +unreadable)\(emunless +the attempt backfires. Reading a cursed spellbook or one with mystic runes beyond your ken can be harmful to your health! .pg @@ -2394,6 +3179,21 @@ have a limited number of uses, akin to wand charges. For example, lamps burn out after a while. Other tools are containers, which objects can be placed into or taken out of. .pg +Some tools (such as a blindfold) can be \fIworn\fP and can be put on and +removed like other accessories (rings, amulets); see \fIAmulets\fP. +Other tools (such as pick-axe) can be wielded as weapons in addition to +being applied for their usual purpose, and in some cases (again, pick-axe) +become wielded as a weapon even when applied. +.pg +.\" Mentioned here because of the old method of attempting "Zen" conduct: +.\" restart until there's a blindfold in starting inventory and put it on +.\" first thing. +The +.op blind +option can be set (prior to game start) to attempt to play the entire +game without being able to see (a self-imposed challenge which is +very difficult to accomplish). +.pg The command to use a tool is \(oqa\(cq (apply). .hn 3 Containers @@ -2413,6 +3213,30 @@ Some chests are trapped, causing nasty things to happen when you unlock or open them. You can check for and try to deactivate traps with the \(lq#untrap\(rq extended command. +.pg +When the contents of a container are known, that container will be +described as something like \(lqa sack containing 3 items\(rq. +In this example, the 3 refers to number of \fIstacks\fP of compatible +items, not to the total number of individual items. +So a sack holding 2 sky blue potions, 7 arrows, and 350 gold pieces would be +described as having 3 items rather than 10 or 359. +And you would need to have 3 unused inventory slots available in order +to take everything out (for the case where the items you remove don't +combine into bigger stacks with things you're already carrying). +.pg +If a chest or large box is described as \(lqbroken\(rq, that means that it +can't be locked rather than that it no longer functions as a container. +.pg +The \fIapply\fP and \fIloot\fP commands allow you to take out and/or +put in an arbitrary number of items in a single operation. +If you want to take everything out of a container, you can use the +\(lq#tip\(rq command to pour the contents onto the floor. +This may be your only way to get things out if your hands are stuck +to a cursed two-handed weapon. +When your hands aren't stuck, you have the potential to pour the +contents into another container. +(As of this writing, the other container must be carried rather than on +the floor.) .hn 2 Amulets (\(oq"\(cq) .pg @@ -2421,28 +3245,52 @@ rings, amulets have various magical properties, some beneficial, some harmful, which are activated by putting them on. .pg Only one amulet may be worn at a time, around your neck. +Like wearing rings, wearing an amulet affects your metabolism, causing +you to grow hungry more rapidly. .pg The commands to use amulets are the same as for rings, \(oqP\(cq (put on) and \(oqR\(cq (remove). +\(oqA\(cq can be used to remove various worn items including amulets. +Also, \(oqW\(cq (wear) and \(oqT\(cq (take off) which are normally for +armor can be used for amulets and other accessories (rings and eyewear), +but accessories won't be shown as likely candidates in a prompt for +choosing what to wear or take off. .hn 2 Gems (\(oq*\(cq) .pg -Some gems are valuable, and can be sold for a lot of gold. They are also -a far more efficient way of carrying your riches. Valuable gems increase -your score if you bring them with you when you exit. +Some gems are valuable, and can be sold for a lot of gold. +They are also a far more efficient way of carrying your riches. +Valuable gems increase your score if you bring them with you when you exit. .pg Other small rocks are also categorized as gems, but they are much less -valuable. All rocks, however, can be used as projectile weapons (if you -have a sling). In the most desperate of cases, you can still throw them -by hand. +valuable. +All rocks, however, can be used as projectile weapons (if you have a sling). +In the most desperate of cases, you can still throw them by hand. .hn 2 Large rocks (\(oq\`\(cq) .pg -Statues and boulders are not particularly useful, and are generally -heavy. It is rumored that some statues are not what they seem. -.pg -Very large humanoids (giants and their ilk) have been known to use boulders -as weapons. +Statues and boulders are not particularly useful, and are generally heavy. +It is rumored that some statues are not what they seem. +.pg +Boulders occasionally block your path. +You can push one forward (by attempting to walk onto its spot) +when nothing blocks \fIits\fP path, or you can +smash it into a pile of small rocks with breaking magic or a pick-axe. +It is possible to move onto a boulder's location if certain conditions +are met; ordinarily one of those conditions is that pushing it any +further be blocked. +Using the move-without-picking-up prefix (default key \(oq\f(CRm\fP\(cq) +prior to the direction of movement will attempt to move to a boulder's +location without pushing it in addition to the prefix's usual action of +suppressing auto-pickup at the destination. +.pg +Very large humanoids (giants and their ilk) have been known to pick up +boulders and use them as missile weapons. +.pg +Unlike boulders, statues can't be pushed, but don't need to be because +they don't block movement. +.\" 'rumor' above is about statue traps; this is a hint about statue contents +They can be smashed into rocks though. .pg For some configurations of the program, statues are no longer shown as \(oq\f(CR\`\fP\(cq but by the letter representing the monster they depict @@ -2454,6 +3302,19 @@ Gold adds to your score, and you can buy things in shops with it. There are a number of monsters in the dungeon that may be influenced by the amount of gold you are carrying (shopkeepers aside). +.pg +Gold pieces are the only type of object where bless/curse state does not +apply. +They're always uncursed but never described as uncursed even if you turn +off the +.op implicit_uncursed +option. +You can set the +.op goldX +option if you prefer to have gold pieces be treated as bless/curse state +\fIunknown\fP rather than as known to be uncursed. +Only matters when you're using an object selection prompt that can filter +by \(lq\f(CRBUCX\fP\(rq state. . .hn 2 Persistence of Objects @@ -2461,13 +3322,13 @@ Persistence of Objects Normally, if you have seen an object at a particular map location and move to another location where you can't directly see that object any more, it will continue to be displayed on your map. -That remains the case even if it is not actually there any more \(em -perhaps a monster has picked it up or it has rotted away \(em -until you can see or feel that location again. +That remains the case even if it is not actually there any +more\(emperhaps a monster has picked it up or it has rotted away\(emuntil +you can see or feel that location again. One notable exception is that if the object gets covered by the \(lqremembered, unseen monster\(rq marker. When that marker is later removed -after you've verified that no monster is there, you will forget that +after you've verified that no monster is there, you will have forgotten that there was any object there regardless of whether the unseen monster actually took the object. If the object is still there, then once you see or feel that location @@ -2560,6 +3421,14 @@ not penalized for being spoken to by an angry god, priest(ess), or other religious figure; a true atheist would hear the words but attach no special meaning to them. .pg +A pauper starts the game with no possessions, no spells, and no weapon or +spell skills (and if playing as a knight, your pony will not have a saddle). +Can only be initiated by starting a new game with \f(CROPTIONS=pauper\fP +set in your run-time configurtion file or \f(CRNETHACKOPTIONS\fP environment +variable. +Once the game is underway, you can acquire and use items, spells, and skills +in the usual way. +.pg Most players fight with a wielded weapon (or tool intended to be wielded as a weapon). Another challenge is to win the game without using such a wielded weapon. You are still permitted to throw, @@ -2571,7 +3440,7 @@ In NetHack, a pacifist refuses to cause the death of any other monster difficult challenge, although it is still possible to gain experience by other means. .pg -An illiterate character cannot read or write. +An illiterate character does not read or write. This includes reading a scroll, spellbook, fortune cookie message, or t-shirt; writing a scroll; or making an engraving of anything other than a single \(lqX\(rq @@ -2584,6 +3453,32 @@ knowledge of spells) in your starting inventory is assumed to be learned from your teachers prior to the start of the game and isn't counted. .pg +There is a side-branch to the main dungeon called \(lqSokoban,\(rq briefly +described in the earlier section about \fITraps\fP. +As mentioned there, the goal is to push boulders into pits and/or holes +to plug those in order to both get the boulders out of the way and be +able to go past the traps. +There are some special \(lqrules\(rq that are active when in that branch +of the dungeon. +Some rules can't be bypassed, such as being unable to push a boulder +diagonally. +Other rules can, such as not smashing boulders with magic or tools, +but doing so causes you to receive a luck penalty. +No message about that is given at the time, but it is tracked as a conduct. +The #conduct command and end of game disclosure will report whether +you have abided by the special rules of Sokoban, and if not, how many +times you violated them, providing you with a way to discover which +actions incur bad luck so that you can be better informed about whether +or not to avoid repeating those actions in the future. +(Note: the Sokoban conduct will only be displayed if you have +entered the Sokoban branch of the dungeon during the current game. +Once that has happened, it becomes part of disclosed conduct even if +you haven't done anything interesting there. +Ending the game with \(lqnever broke the Sokoban rules\(rq conduct is most +meaningful if you also manage to perform +the \(lqobtained the Sokoban prize\(rq achievement +(see \fIAchievements\fP below).) +.pg There are several other challenges tracked by the game. It is possible to eliminate one or more species of monsters by genocide; playing without @@ -2602,6 +3497,98 @@ wish for any items is a challenge, as is a game without wishing for an artifact (even if the artifact immediately disappears). When the game offers you an opportunity to make a wish for an item, you may choose \(lqnothing\(rq if you want to decline. +.hn 2 +Achievements +.pg +End of game disclosure will also display various achievements +representing progress toward ultimate ascension, if any have been +attained. +They aren't directly related to \fIconduct\fP but are grouped with +it because they fall into the same category of \(lqbragging rights\(rq +and to limit the number of questions during disclosure. +Listed here roughly in order of difficulty and not necessarily in the order +in which you might accomplish them. +.sp +.TS +center; +L Lz2 L. +\fIRank\fP \- Attained rank title \fIRank\fP. +Shop \- Entered a shop. +Temple \- Entered a temple. +Mines \- Entered the Gnomish Mines. +Town \- Entered Mine Town. +Oracle \- Consulted the Oracle of Delphi. +Novel \- Read a passage from a Discworld Novel. +Sokoban \- Entered Sokoban. +Big Room \- Entered the Big Room. +Soko-Prize \- T{ +Explored to the top of Sokoban and found a special item there. +T} +Mines' End \- T{ +Explored to the bottom of the Gnomish Mines and found a special item +there. +T} +Medusa \- Defeated Medusa. +Tune \- T{ +Discovered the tune that can be used to open and close the drawbridge on +the Castle level. +T} +Bell \- Acquired the Bell of Opening. +Gehennom \- Entered Gehennom. +Candle \- Acquired the Candelabrum of Invocation. +Book \- Acquired the Book of the Dead. +Invocation \- T{ +Gained access to the bottommost level of Gehennom. +T} +Amulet \- Acquired the fabled Amulet of Yendor. +Endgame \- Reached the Elemental Planes. +Astral \- Reached the Astral Plane level. +Blind \- Blind from birth. +Deaf \- Deaf from birth. +Nudist \- Never wore any armor. +Pauper \- Started out with no possessions. +Ascended \- Delivered the Amulet to its final destination. +.TE +.sp +.lp "Notes: " +.pg +Achievements are recorded and subsequently reported in the order in which +they happen during your current game rather than the order listed here. +.pg +There are nine \fI\fP titles for each role, bestowed at experience +levels 1, 3, 6, 10, 14, 18, 22, 26, and 30. +The one for experience level 1 is not recorded as an achievement. +Losing enough levels to revert to lower rank(s) does not discard the +corresponding achievement(s). +.pg +There's no guaranteed \fINovel\fP so the achievement to read one might +not always be attainable (except perhaps by \fIwishing\fP). +Similarly, the \fIBig Room\fP level is not always present. +Unlike with the Novel, there's no way to wish for this opportunity. +.pg +The \(lqspecial items\(rq hidden in \fIMines'\~End\fP and \fISokoban\fP +are not unique but are considered to be prizes or rewards +for exploring those levels since doing so is not necessary to complete +the game. +Finding other instances of the same objects doesn't record the +corresponding achievement. +.pg +The \fIMedusa\fP achievement is recorded if she dies for any reason, +even if you are not directly responsible, and only if she dies. +.pg +The 5-note \fItune\fP can be learned via trial and error with a musical +instrument played closely +enough\(embut not too close!\(emto +the Castle level's drawbridge or can be given to you via prayer boon. +.pg +\fIBlind\fP, \fIDeaf\fP, \fINudist\fP, +and \fIPauper\fP are also conducts, and they can only be +enabled by setting the correspondingly named option in NETHACKOPTIONS +or run-time configuration file prior to game start. +In the case of \fIBlind\fP and \fIDeaf\fP, the option also enforces the +conduct. +They aren't really significant accomplishments unless/until you make +substantial progress into the dungeon. . .hn 1 Options @@ -2623,48 +3610,53 @@ for system administrators. .hn 2 Using a configuration file .pg -.\" hw: don't hyphenate file names -.hw .nethackrc defaults.nh nethack.exe nethackW.exe +.\" hw: don't hyphenate file names; percent-sign doesn't need special handling +.hw .nethackrc defaults.nh nethack.exe nethackW.exe %USERPROFILE%\\NetHack\\ The default name of the configuration file varies on different operating systems. .pg On .UX , Linux, -and Mac OS X it is \(lq.nethackrc\(rq in the user's home directory. +and macOS it is \(lq.nethackrc\(rq in the user's home directory. The file may not exist, but it is a normal ASCII text file and can be created with any text editor. .pg -On Windows, it is \(lq.nethackrc\(rq in the folder -\(lq\\%USERPROFILE%\\NetHack\\(rq. The file may not exist, +On Windows, the name is \(lq.nethackrc\(rq located in the folder +\(lq%USERPROFILE%\\NetHack\\\(rq. +The file may not exist, but it is a normal ASCII text file can can be created with any text editor. After running NetHack for the first time, you should find a default template for the configuration file named \(lq.nethackrc.template\(rq -in \(lq\\%USERPROFILE%\\NetHack\\(rq. -If you had not created the configuration file, NetHack will create -the configuration file for you using the default template file. +in \(lq%USERPROFILE%\\NetHack\\\(rq. +If you have not created the configuration file, NetHack will create +one for you using the default template file. .pg On MS-DOS, it is \(lqdefaults.nh\(rq in the same folder as nethack.exe. .pg -Any line in the configuration file starting with \(oq#\(cq is treated -as a comment. +Any line in the configuration file starting with \(oq\f(CR#\fP\(cq is treated +as a comment and ignored. Empty lines are ignored. .pg -Any line beginning with \(oq[\(cq and ending in \(oq]\(cq is considered -a section marker. +Any line beginning with \(oq\f(CR[\fP\(cq and ending in \(oq\f(CR]\fP\(cq +is a section marker (the closing \(oq\f(CR]\fP\(cq can be followed +by whitespace and then an arbitrary comment beginning with \(oq\f(CR#\fP\(cq). The text between the square brackets is the section name. -Lines after a section marker belong to that section, and are -ignored unless a CHOOSE statement was used to select that section. -Section names are case insensitive. -.pg -You can use different configuration statements in the file, some +Section markers are only valid after a CHOOSE directive and their names +are case-insensitive. +Lines after a section marker belong to that section up until another +section starts or a marker without a name is encountered or the file ends. +Lines within sections are ignored unless a CHOOSE directive has selected +that section. +.pg +You can use different configuration directives in the file, some of which can be used multiple times. -In general, the statements are +In general, the directives are written in capital letters, followed by an equals sign, followed by -settings particular to that statement. +settings particular to that directive. .pg -Here is a list of allowed statements: +Here is a list of allowed directives: .lp OPTIONS There are two types of options, boolean and compound options. Boolean options toggle a setting on or off, while compound options @@ -2672,8 +3664,8 @@ take more diverse values. Prefix a boolean option with \(lqno\(rq or \(oq!\(cq to turn it off. For compound options, the option name and value are separated by a colon. Some options are persistent, and apply only to new games. -You can specify multiple OPTIONS statements, and multiple options -separated by commas in a single OPTIONS statement. +You can specify multiple OPTIONS directives, and multiple options +separated by commas in a single OPTIONS directive. (Comma separated options are processed from right to left.) .lp "" Example: @@ -2725,8 +3717,8 @@ Set exceptions to the option. See the \(lqConfiguring Autopickup Exceptions\(rq section. .lp BINDINGS -Change the key bindings of some special keys, menu accelerators, or -extended commands. +Change the key bindings of some special keys, menu accelerators, +extended commands, or mouse buttons. You can specify multiple bindings. Format is key followed by the command, separated by a colon. See the \(lqChanging Key Bindings\(rq section for more information. @@ -2737,7 +3729,8 @@ Example: .ed .lp CHOOSE Chooses at random one of the comma-separated parameters as an active -section name. Lines in other sections are ignored. +section name. +Lines in other sections are ignored. .lp "" Example: .sd @@ -2748,16 +3741,22 @@ CHOOSE=char A,char B OPTIONS=role:arc,race:dwa,align:law,gender:fem [char B] OPTIONS=role:wiz,race:elf,align:cha,gender:mal +[] #end of CHOOSE +OPTIONS=!rest_on_space .ft \" revert to previous font .ed +.lp "" +If \f(CR[]\fP is present, the preceding section is closed and no new +section begins; whatever follows will be common to all sections. +Otherwise the last section extends to the end of the options file. .lp MENUCOLOR Highlight menu lines with different colors. See the \(lqConfiguring Menu Colors\(rq section. .lp MSGTYPE -Change the way messages are shown in the top status line. +Change the way messages are shown in the top line. See the \(lqConfiguring Message Types\(rq section. .lp ROGUESYMBOLS -Custom symbols for for the rogue level's symbol set. +Custom symbols for the rogue level's symbol set. See \fISYMBOLS\fP below. .lp SOUND Define a sound mapping. @@ -2773,13 +3772,14 @@ See the \(lqModifying NetHack Symbols\(rq section. Example: .sd \f(CR# replace small punctuation (tick marks) with digits\fP -\f(CRSYMBOLS=S_boulder:0,S_golem:7\fP +\f(CRSYMBOLS=S_golem:7\fP .ed .lp WIZKIT Debug mode only: extra items to add to initial inventory. Value is the name of a text file containing a list of item names, one per line, up to a maximum of 128 lines. Each line is processed by the function that handles wishing. +Entries are added to the wish history; see the wizwish-command. .lp "" Example: .sd @@ -2789,13 +3789,12 @@ Example: .pg \ \" dummy paragraph to force some separation [.BR isn't working as intended] .pg -.SD n \" suppress indentation +.SD n \" begin display without indentation Here is an example of configuration file contents: .ED .\" [conditional indentation; see description of NETHACKOPTIONS below] -.ds sD i \" assume proportional, indentation acceptable and preferred -.\" Check for fixed-width font; 'f' will be same width as 'F'. -.if (\w'f'p)=(\w'F'p) .ds sD n \" if same width, suppress indentation +.ds sD i \" typesetter; display indentation acceptable and preferred +.if n .ds sD n \" terminal; suppress indentation .SD \*(sD \" string variable sD will expand to either 'i' or 'n' .ft CR \" set font to constant-width Roman # Set your character's role, race, gender, and alignment. @@ -2809,7 +3808,8 @@ OPTIONS=color # Display things in color if possible OPTIONS=lit_corridor # Show lit corridors differently OPTIONS=hilite_pet,hilite_pile # Replace small punctuation (tick marks) with digits -SYMBOLS=S_boulder:0,S_golem:7 +OPTIONS=boulder:0 +SYMBOLS=S_golem:7 # # No startup splash screen. Windows GUI only. OPTIONS=!splash_screen @@ -2841,12 +3841,8 @@ you would enter the command .\" but the 'setenv' example is too wide for Guidebook.txt unless the .\" indentation is suppressed (.SD n). Even though the second example .\" can be indented, it should match the first or they'll both look odd. -.\" groff has a built-in register allowing recognition of '-T', but we -.\" can't rely on that. Assume Guidebook.ps uses a proportional font -.\" and Guidebook.txt a fixed-width one and test which sort we're using. -.ds sD i \" assume proportional, indentation acceptable and preferred -.\" Check for fixed-width font; 'f' will be same width as 'F'. -.if (\w'f'p)=(\w'F'p) .ds sD n \" if same width, suppress indentation +.ds sD i \" typesetter; display indentation acceptable and preferred +.if n .ds sD n \" terminal; suppress indentation .SD \*(sD \f(CR% setenv NETHACKOPTIONS "color,\\!leg,name:Blue Meanie,fruit:lime"\fP .ED @@ -2859,10 +3855,10 @@ to that shell), or the pair of commands in \fIsh\fP, \fIksh\fP, or \fIbash\fP. .pg The NETHACKOPTIONS value is effectively the same as a single OPTIONS -statement in a configuration file. +directive in a configuration file. The \(lqOPTIONS=\(rq prefix is implied and comma separated options are processed from right to left. -Other types of configuration statements such as BIND or MSGTYPE are +Other types of configuration directives such as BIND or MSGTYPE are not allowed. .pg Instead of a comma-separated list of options, @@ -2881,35 +3877,73 @@ Some of the options listed may be inactive in your dungeon. Some options are persistent, and are saved and reloaded along with the game. Changing a persistent option in the configuration file applies only to new games. +. +.\" .lp usage: +.\" Option names which are 8 or more characters long don't need to be quoted. +.\" Ones less that 8 should be enclosed within double quotes and padded with +.\" trailing spaces. +. +.lp accessiblemsg +Add location or direction information to messages (default is off). .lp acoustics Enable messages about what your character hears (default on). Note that this has nothing to do with your computer's audio capabilities. Persistent. -.lp align -Your starting alignment (align:lawful, align:neutral, or align:chaotic). +.lp alignment +Your starting alignment (\f(CRalign:lawful\fP, \f(CRalign:neutral\fP, or +\f(CRalign:chaotic\fP). You may specify just the first letter. -The default is to randomly pick an appropriate alignment. -If you prefix the value with \(oq!\(cq or \(lqno\(rq, you will -exclude that alignment from being picked randomly. -Cannot be set with the \(oqO\(cq command. +Many roles and the non-human races restrict which alignments are allowed. +See +.op role +for a description of how to use negation to exclude choices. +.lp "" +If \f(CRalign\fP is not specified, there is no default value; +player will be prompted unless role and/or race forces a choice for alignment. +Cannot be set with the \(oq\f(CRO\fP\(cq command. Persistent. +.lp armorstatus +Display an extra status condition which summarizes currently worn armor +(default off, not supported by all interfaces). +.lp "" +For the usual case where more than one piece of armor is worn, a list of +letters is shown in the following order: +.sd +\f(CRG\fP - gloves; +\f(CRC\fP - cloak; +\f(CRA\fP - suit; +\f(CRU\fP - shirt; +\f(CRH\fP - helmet; +\f(CRB\fP - boots; +\f(CRS\fP - shield. +.ed .lp autodescribe Automatically describe the terrain under cursor when asked to get a location on the map (default true). The .op whatis_coord option controls whether the description includes map coordinates. -.lp autodig +.lp "autodig " Automatically dig if you are wielding a digging tool and moving into a place -that can be dug (default false). Persistent. +that can be dug (default false). +Persistent. .lp autoopen -Walking into a door attempts to open it (default true). Persistent. -.lp "autopickup " -Automatically pick up things onto which you move (default on). Persistent. +Walking into a closed door attempts to open it (default true). +Persistent. +.lp autopickup +Automatically pick up things onto which you move (default off). +Persistent. +.lp "" See .op pickup_types -to refine the behavior. -.lp "autoquiver " +and also +.op autopickup_exception +for ways to refine the behavior. +.lp "" +Note: prior to version 5.0.0, the default for +.op autopickup +was \fIon\fP. +.lp autoquiver This option controls what happens when you attempt the \(oqf\(cq (fire) command when nothing is quivered or readied (default false). When true, the computer will fill @@ -2922,18 +3956,53 @@ with the \(oqQ\(cq command instead. If no weapon is found or the option is false, the \(oqt\(cq (throw) command is executed instead. Persistent. -.lp blind +.lp autounlock +Controls what action to take when attempting to walk into a locked door +or to loot a locked container. +Takes a plus-sign separated list of values: +.PS Apply-Key +.PL Untrap +prompt about whether to attempt to find a trap; +it might fail to find one even when present; if it does find one, it +will ask whether you want to try to disarm the trap; if you decline, +your character will forget that the door or box is trapped; +.PL Apply-Key +if carrying a key or other unlocking tool, prompt about using it; +.PL Kick +kick the door (if you omit untrap or decline to attempt untrap and +you omit apply-key or you lack a key or you decline to use the key; +has no effect on containers); +.PL Force +try to force a container's lid with your currently +wielded weapon (if you omit untrap or decline to attempt untrap and +you omit apply-key or you lack a key or you decline to use the key; +has no effect on doors); +.PL None +none of the above; can't be combined with the other choices. +.PE +Omitting the value is treated as if \f(CRautounlock:apply-key\fP. +Preceding \f(CRautounlock\fP with \(oq!\(cq or \(lqno\(rq is treated as +\f(CRautounlock:none\fP. +.lp "" +Applying a key might set off a trap if the door or container is trapped. +Successfully kicking a door will break it and wake up nearby monsters. +Successfully forcing a container open will break its lock and might also +destroy some of its contents or damage your weapon or both. +.lp "" +The default is Apply-Key. +Persistent. +.lp "blind " Start the character permanently blind (default false). Persistent. -.lp bones +.lp "bones " Allow saving and loading bones files (default true). Persistent. -.lp boulder +.lp "boulder " Set the character used to display boulders (default is the \(lqlarge rock\(rq class symbol, \(oq\`\(cq). -.lp catname +.lp "catname " Name your starting cat (for example \(lqcatname:Morris\(rq). -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp character Synonym for \(lqrole\(rq to pick the type of your character (for example \(lqcharacter:Monk\(rq). @@ -2943,16 +4012,6 @@ for more details. .lp checkpoint Save game state after each level change, for possible recovery after program crash (default on). Persistent. -.lp checkspace -Check free disk space before writing files to disk (default on). -You may have to turn this off if you have more than 2 GB free space -on the partition used for your save and level files -(because too much space might overflow the calculation and end up -looking like insufficient space). -Only applies when MFLOPPY was defined during compilation. -.lp clicklook -Allows looking at things on the screen by navigating the mouse -over them and clicking the right mouse button (default off). .lp cmdassist Have the game provide some additional command assistance for new players if it detects some anticipated mistakes (default on). @@ -2961,6 +4020,16 @@ Have user confirm attacks on pets, shopkeepers, and other peaceable creatures (default on). Persistent. .lp dark_room Show out-of-sight areas of lit rooms (default on). Persistent. +.lp "deaf " +Start the character permanently deaf (default false). +Persistent. +.lp dropped_nopick +If this option is on, items you dropped will not be automatically +picked up, even if +.op autopickup +is also on and they are in +.op pickup_types +or match a positive autopickup exception (default on). Persistent. .lp disclose Controls what information the program reveals when the game ends. Value is a space separated list of prompting/category pairs @@ -2974,7 +4043,7 @@ The possibilities are: .CC a "disclose your attributes;" .CC v "summarize monsters that have been vanquished;" .CC g "list monster species that have been genocided;" -.CC c "display your conduct;" +.CC c "display your conduct; also achievements, if any;" .CC o "display dungeon overview." .ei .ed @@ -2988,8 +4057,8 @@ lets you refine how it behaves. Here are the valid prefixes: .CC \- "do not disclose it and do not prompt." .ei .ed -The listing of vanquished monsters can be sorted, -so there are two additional choices for \(oqv\(cq: +The listings of vanquished monsters and of genocided types can be sorted, +so there are two additional choices for \(oqv\(cq and \(oqg\(cq: .sd .si .CC ? "prompt you and default to ask on the prompt;" @@ -2999,8 +4068,9 @@ so there are two additional choices for \(oqv\(cq: Asking refers to picking one of the orderings from a menu. The \(oq+\(cq disclose without prompting choice, or being prompted and answering \(oqy\(cq rather than \(oqa\(cq, -will default to showing monsters in the traditional order, -from high level to low level. +will default to showing monsters in the order specified by the +.op sortvanquished +option. .lp "" Omitted categories are implicitly added with \(oqn\(cq prefix. Specified categories with omitted prefix implicitly use \(oq+\(cq prefix. @@ -3020,10 +4090,10 @@ Note that the vanquished monsters list includes all monsters killed by traps and each other as well as by you. And the dungeon overview shows all levels you had visited but does not reveal things about them that you hadn't discovered. -.lp dogname +.lp "dogname " Name your starting dog (for example \(lqdogname:Fang\(rq). -Cannot be set with the \(oqO\(cq command. -.lp extmenu +Cannot be set with the \(oq\f(CRO\fP\(cq command. +.lp "extmenu " Changes the extended commands interface to pop-up a menu of available commands. It is keystroke compatible with the traditional interface except that it @@ -3034,10 +4104,14 @@ For the X11 interface, which always uses a menu for choosing an extended command, it controls whether the menu shows all available commands (on) or just the subset of commands which have traditionally been considered extended ones (off). -.lp female -An obsolete synonym for \(lqgender:female\(rq. -Cannot be set with the \(oqO\(cq command. -.lp fixinv +.lp "female " +An obsolete synonym for \(lq\f(CRgender:female\fP\(rq. +Cannot be set with the \(oq\f(CRO\fP\(cq command. +.lp fireassist +This option controls what happens when you attempt the \(oqf\(cq (fire) +and don't have an appropriate launcher, such as a bow or a sling, wielded. +If on, you will automatically wield the launcher. Default is on. +.lp "fixinv " An object's inventory letter sticks to it when it's dropped (default on). If this is off, dropping an object shifts all the remaining inventory letters. Persistent. @@ -3051,16 +4125,24 @@ Basically a nostalgic whimsy that NetHack uses from time to time. You should set this to something you find more appetizing than slime mold. Apples, oranges, pears, bananas, and melons already exist in NetHack, so don't use those. -.lp gender -Your starting gender (gender:male or gender:female). +.lp "gender " +Your starting gender (\f(CRgender:male\fP or \f(CRgender:female\fP). You may specify just the first letter. Although you can -still denote your gender using the \(lqmale\(rq and \(lqfemale\(rq -options, the \(lqgender\(rq option will take precedence. -The default is to randomly pick an appropriate gender. -If you prefix the value with \(oq!\(cq or \(lqno\(rq, you will -exclude that gender from being picked randomly. -Cannot be set with the \(oqO\(cq command. +still denote your gender using either of the deprecated +.op male +and +.op female +options, if the +.op gender +option is also present it will take precedence. +See +.op role +for a description of how to use negation to exclude choices. +.lp "" +If \f(CRgender\fP is not specified, there is no default value; +player will be prompted unless role and/or race forces a choice for gender. +Cannot be set with the \(oq\f(CRO\fP\(cq command. Persistent. .lp "goldX " When filtering objects based on bless/curse state (BUCX), whether to @@ -3087,7 +4169,7 @@ The behavior of this option depends on the type of windowing you use. In text windowing, text highlighting or inverse video is often used; with tiles, generally displays a heart symbol near pets. .lp "" -With the curses interface, the +With the tty or curses interface, the .op petattr option controls how to highlight pets and setting it will turn the .op hilite_pet @@ -3099,22 +4181,47 @@ In text windowing, text highlighting or inverse video is often used; with tiles, generally displays a small plus-symbol beside the object on the top of the pile. .lp hitpointbar -Show a hit point bar graph behind your name and title. -Only available for TTY and Windows GUI, and only when statushilites is on. +Show a hit point bar graph behind your name and title in the status +display (default off). +.lp "" +The \(lqcurses\(rq interface supports it even if the status highlighting +feature has been disabled when building the program. +The \(lqtty\(rq and \(lqmswin\(rq (aka \(lqWindows GUI\(rq) interfaces +support it only if status highlighting is left enabled when building. +You don't need to set up any highlighting rules in order to display +the bar. +If there is one for hitpoints in effect and it specifies color, that +color will be used for the bar. +However if it specifies video attributes, they will be ignored in +favor of \fIinverse\fP. +For tty and curses, \fIblink\fP will also be used if the current +hitpoint value is at or below the \fIcritical HP\fP threshold. +.lp "" +The \(lqQt\(rq interface also supports hitpointbar, by drawing +a solid bar above the name and title with a hard-coded color scheme. +(As of this writing, having the bar enabled unintentionally inhibits +resizing the status panel. +To resize that, use the \f(CR#optionsfull\fP command to toggle the +\fIhitpointbar\fP option off, perform the resize while it's off, then +use the same command to toggle it back on.) .lp horsename Name your starting horse (for example \(lqhorsename:Trigger\(rq). -Cannot be set with the \(oqO\(cq command. -.lp ignintr +Cannot be set with the \(oq\f(CRO\fP\(cq command. +.lp "ignintr " Ignore interrupt signals, including breaks (default off). Persistent. .lp implicit_uncursed -Omit "uncursed" from inventory lists, if possible (default on). -.lp legacy +Omit \(lquncursed\(rq from object descriptions when it can be deduced from +other aspects of the description (default on). +Persistent. +.lp "" +If you use menu coloring, you may want to turn this off. +.lp "legacy " Display an introductory message when starting the game (default on). Persistent. .lp lit_corridor Show corridor squares seen by night vision or a light source held by your character as lit (default off). Persistent. -.lp lootabc +.lp "lootabc " When using a menu to interact with a container, use the old \(oqa\(cq, \(oqb\(cq, and \(oqc\(cq keyboard shortcuts rather than the mnemonics \(oqo\(cq, \(oqi\(cq, and \(oqb\(cq @@ -3123,19 +4230,31 @@ Persistent. .lp "mail " Enable mail delivery during the game (default on). Persistent. .lp "male " -An obsolete synonym for \(lqgender:male\(rq. -Cannot be set with the \(oqO\(cq command. +An obsolete synonym for \(lq\f(CRgender:male\fP\(rq. +Cannot be set with the \(oq\f(CRO\fP\(cq command. +.lp mention_decor +Give feedback when walking onto various dungeon features such as stairs, +fountains, or altars which are ordinarily only described when covered +by one or more objects (default off). +Cannot be set with the \(oq\f(CRO\fP\(cq command. +Persistent. +.lp mention_map +Give feedback when interesting map locations change (default off). .lp mention_walls Give feedback when walking against a wall (default off). +Persistent. .lp menucolors Enable coloring menu lines (default off). See \(lqConfiguring Menu Colors\(rq on how to configure the colors. .lp menustyle -Controls the interface used when you need to choose various objects (in -response to the Drop command, for instance). The value specified should -be the first letter of one of the following: traditional, combination, -full, or partial. -Traditional was the only interface available for +Controls the method used when you need to choose various objects (in +response to the \f(CRDrop\fP (aka \f(CRdroptype\fP) command, for instance). +The value specified should be the first letter of one of the following: +traditional, combination, full, or partial. +Default is \f(CRfull\fP. +Persistent. +.lp "" +Traditional was the only method available for very early versions; it consists of a prompt for object class characters, followed by an object-by-object prompt for all items matching the selected object class(es). @@ -3145,72 +4264,112 @@ prompting one-by-one. Full displays a menu of object classes rather than a character prompt, and then a menu of matching objects for selection. +(Choosing its \(oqA\(cq (Autoselect-All) choice skips the second menu. +To avoid choosing that by accident, +set \f(CRparanoid_confirm:AutoAll\fP to require confirmation.) Partial skips the object class filtering and immediately displays a menu of all objects. -Persistent. .lp menu_deselect_all -Menu character accelerator to deselect all items in a menu. -Implemented by the Amiga, Gem, X11 and tty ports. +Key to deselect all items in a menu. Default \(oq\-\(cq. .lp menu_deselect_page -Menu character accelerator to deselect all items on this page of a menu. -Implemented by the Amiga, Gem and tty ports. +Key to deselect all items on this page of a menu. Default \(oq\\\(cq. .lp menu_first_page -Menu character accelerator to jump to the first page in a menu. -Implemented by the Amiga, Gem and tty ports. +Key to jump to the first page in a menu. Default \(oq\(ha\(cq. .lp menu_headings Controls how the headings in a menu are highlighted. -Values are \(lqnone\(rq, \(lqbold\(rq, \(lqdim\(rq, \(lqunderline\(rq, -\(lqblink\(rq, or \(lqinverse\(rq. +Takes a text attribute, or text color and attribute separated by ampersand. +For allowed attributes and colors, see \(lqConfiguring Menu Colors\(rq. Not all ports can actually display all types. .lp menu_invert_all -Menu character accelerator to invert all items in a menu. -Implemented by the Amiga, Gem, X11 and tty ports. +Key to invert all items in a menu. Default \(oq@\(cq. .lp menu_invert_page -Menu character accelerator to invert all items on this page of a menu. -Implemented by the Amiga, Gem and tty ports. +Key to invert all items on this page of a menu. Default \(oq\(ti\(cq. \" ~ .lp menu_last_page -Menu character accelerator to jump to the last page in a menu. -Implemented by the Amiga, Gem and tty ports. +Key to jump to the last page in a menu. Default \(oq|\(cq. .lp menu_next_page -Menu character accelerator to goto the next menu page. -Implemented by the Amiga, Gem and tty ports. +Key to go to the next menu page. Default \(oq>\(cq. .lp menu_objsyms -Show object symbols in menu headings in menus where -the object symbols act as menu accelerators (default off). +." [originally menu_objsyms was a boolean] +." Show object symbols in menu headings in menus where +." the object symbols act as menu accelerators (default off). +Inventory and other object menus are normally separated by object class +(weapons, armor, and so forth), with a menu header line at the beginning +of each group. +You can have menus add the display symbol for the class of objects for +each header line. +You can also add the display symbol for the individual item in each menu +entry. +For a tiles map, that would be a small rendition of an object's tile. +For a text map, it is the same character as is used for the object's +class, which would be most useful when there are no headers separating +objects among classes. +Possible values are +.PS "5\ -\ One-or-other" +.PL "0\ -\ None" +no symbols for either header lines or menu entries; +.PL "1\ -\ Headers" +show symbols on header lines but not entries; +.PL "2\ -\ Entries" +show symbols on menu entry lines but not headers; +.PL "3\ -\ Both" +show symbols on headers and entries; +.PL "4\ -\ Conditional" +only show symbols for entries if there are no headers; +.PL "5\ -\ One-or-other" +show symbols on headers, or on entries if no headers. +.PE +Supported by tty and curses. +When setting the value, it can be specified by digit or keyword. +The default value is \f(CRConditional\fP (4). .lp menu_overlay Do not clear the screen before drawing menus, and align menus to the right edge of the screen. Only for the tty port. (default on) .lp menu_previous_page -Menu character accelerator to goto the previous menu page. -Implemented by the Amiga, Gem and tty ports. +Key to go to the previous menu page. Default \(oq<\(cq. .lp menu_search -Menu character accelerator to search for a menu item. -Implemented by the Amiga, Gem, X11 and tty ports. +Key to search for some text and toggle selection state of matching menu items. Default \(oq:\(cq. .lp menu_select_all -Menu character accelerator to select all items in a menu. -Implemented by the Amiga, Gem, X11 and tty ports. +Key to select all items in a menu. Default \(oq.\(cq. .lp menu_select_page -Menu character accelerator to select all items on this page of a menu. -Implemented by the Amiga, Gem and tty ports. +Key to select all items on this page of a menu. Default \(oq,\(cq. +.lp menu_shift_left +Key to scroll a menu\(emone which has been +scrolled right\(emback to the left. +Implemented for +.op perm_invent +only by curses and X11. +Default \(oq{\(cq. +.lp menu_shift_right +Key to scroll a menu which has text beyond the +right edge to the right. +Implemented for +.op perm_invent +only by curses and X11. +Default \(oq}\(cq. ." .lp menu_tab_sep ." Format menu entries using TAB to separate columns (default off). ." Only applicable to some menus, and only useful to some interfaces. ." Debug mode only. +.lp mon_movement +Show a message when hero notices a monster movement (default is off). .lp monpolycontrol Prompt for new form whenever any monster changes shape (default off). Debug mode only. +.lp montelecontrol +Prompt for destination whenever any monster gets teleported (default off). +Debug mode only. .lp mouse_support Allow use of the mouse for input and travel. Valid settings are: @@ -3228,7 +4387,7 @@ is the same as specifying 0. .lp msghistory The number of top line messages to keep (and be able to recall with \(oq\(haP\(cq) (default 20). -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp msg_window Allows you to change the way recalled messages are displayed. Currently it is only supported for tty (all four choices) and for curses @@ -3252,12 +4411,17 @@ the role (that is, by suffixing one of If .op "\-@" is used for the role, then a random one will be automatically chosen. -Cannot be set with the \(oqO\(cq command. +.lp "" +On some systems, the default is the player's user name; +on others, there is no default and the player will be prompted. +The former can made to behave like the latter by specifying a generic name +such as ``player''. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp "news " Read the NetHack news file, if present (default on). Since the news is shown at the beginning of the game, there's no point in setting this with the \(oqO\(cq command. -.lp nudist +.lp "nudist " Start the character with no armor (default false). Persistent. .lp "null " Send padding nulls to the terminal (default on). Persistent. @@ -3298,12 +4462,13 @@ symbols for the various object types. Any omitted types are filled in at the end from the previous order. .lp paranoid_confirmation A space separated list of specific situations where alternate -prompting is desired. The default is paranoid_confirmation:pray. +prompting is desired. +The default is \(lqparanoid_confirmation:pray swim trap\(rq. .PS Were-change .PL Confirm for any prompts which are set to require \(lqyes\(rq rather than \(oqy\(cq, also require \(lqno\(rq to reject instead of accepting any non-yes response -as no +as no; changes pray and AutoAll to require \(lqyes\(rq or \(oqno\(cq too; .PL quit require \(lqyes\(rq rather than \(oqy\(cq to confirm quitting the game or switching into non-scoring explore mode; @@ -3314,90 +4479,165 @@ useful in normal play; applies to explore mode); require \(lqyes\(rq rather than \(oqy\(cq to confirm saving bones data when dying in debug mode; .PL attack -require \(lqyes\(rq rather than \(oqy\(cq to confirm attacking a peaceful monster; +require \(lqyes\(rq rather than \(oqy\(cq to confirm attacking +a peaceful monster; .PL wand-break -require \(lqyes\(rq rather than \(oqy\(cq to confirm breaking a wand; +require \(lqyes\(rq rather than \(oqy\(cq to confirm breaking +a wand with the \f(CRapply\fP command; .PL eating -require \(lqyes\(rq rather than \(oqy\(cq to confirm whether to continue eating; +require \(lqyes\(rq rather than \(oqy\(cq to confirm whether to +continue eating; .PL Were-change -require \(lqyes\(rq rather than \(oqy\(cq to confirm changing form due to lycanthropy -when hero has polymorph control; +require \(lqyes\(rq rather than \(oqy\(cq to confirm changing form due +to lycanthropy when hero has polymorph control; .PL pray require \(oqy\(cq to confirm an attempt to pray rather than immediately praying; on by default; +(to require \(lqyes\(rq rather than just \(oqy\(cq, set Confirm too); +.PL trap +require \(oqy\(cq to confirm an attempt to move into or onto a known trap, +unless doing so is considered to be harmless; +when enabled, this confirmation is also used for moving into visible +gas cloud regions; +(to require \(lqyes\(rq rather than just \(oqy\(cq, set Confirm too); +confirmation can be skipped by using the \(oq\f(CRm\fP\(cq movement prefix; +.PL swim +prevent walking into water or lava; on by default; (to deliberately step +onto/into such terrain when this is set, use the \(oq\f(CRm\fP\(cq +movement prefix when adjacent); +.PL AutoAll +require confirmation when the \(oqA\(cq (Autoselect-All) choice is selected +in object class filtering menus for \f(CRmenustyle:Full\fP; +(to require \(lqyes\(rq rather than just \(oqy\(cq, set Confirm too); .PL Remove require selection from inventory for \(oqR\(cq and \(oqT\(cq -commands even when wearing just one applicable item. +commands even when wearing just one applicable item; .PL all turn on all of the above. .PE -By default, the pray choice is enabled, the others disabled. -To disable it without setting -any of the other choices, use \(lqparanoid_confirmation:none\(rq. -To keep -it enabled while setting any of the others, include it in the list, -such as \(lqparanoid_confirmation:attack pray Remove\(rq. +By default, the pray, swim, and trap choices are enabled, the others disabled. +To disable them without setting +any of the other choices, use \f(CRparanoid_confirmation:none\fP. +To keep them enabled while setting any of the others, you can +include them in the new list, such as +\f(CRparanoid_confirmation:attack pray swim Remove\fP +or you can precede the first entry in the list with a plus sign, +\f(CRparanoid_confirmation:+attack Remove\fP. +To remove an entry that has been previously set without removing others, +precede the first entry in the list with a minus sign, +\f(CRparanoid_confirmation:-swim\fP. +To both add some new entries and remove some old ones, you can use +multiple \fIparanoid_confirmation\fP option settings, or you can +use the \(oq\f(CR+\fP\(cq form and list entries to be added by their name +and entries to be removed by \(oq\f(CR!\fP\(cq and name. +The positive (no \(oq!\(cq) and negative (with \(oq!\(cq) entries +can be intermixed. +.lp pauper +Start the character with no possessions (default false). Persistent. +.lp "" +Also start with no spells or skills, which are tied to starting equipment. +Does not inhibit acquiring and using items, spells, and skills once play +has started. .lp perm_invent -If true, always display your current inventory in a window. This only +If true, always display your current inventory in a window (default false). +.lp "" +This only makes sense for windowing system interfaces that implement this feature. +For those that do, the +.op perminv_mode +option can be used to refine what gets displayed +for \fIperm_invent\fP. +Setting that to a value other than \fInone\fP +while \fIperm_invent\fP is false will change it to true. +.lp perminv_mode +Augments the +.op perm_invent +option. +Value is one of +.PS "\f(CRin-use\fP" +.PL "\f(CRnone\fP" +behave as if \fIperm_invent\fP is false; +.PL "\f(CRall\fP" +show all inventory except for gold; +.PL "\f(CRfull\fP" +show full inventory including gold; +.PL "\f(CRin-use\fP" +only show items which are in use (worn, wielded, lit lamp). +.\" %if these get uncommented, change .PS argument to "\f(CRgold+grid\fP" +.\" %and the terminator for in-use to semi-colon. +.\" .PL "\f(CRon+grid\fP" +.\" special for tty only, show \fIall\fP plus unused inventory letters; +.\" .PL "\f(CRgold+grid\fP" +.\" special for tty only, show \fIfull\fP plus unused inventory letters. +.PE +Default is \fInone\fP but if \fIperm_invent\fP gets set to true +while it is \fInone\fP it will be changed to \fIall\fP. +.lp "" +Note: if gold has been equipped in quiver/ammo-pouch then it will be +included for \fIall\fP despite that mode normally omitting gold. .\" petattr is a wincap option but we'll document it here... -.lp petattr +.lp "petattr " Specifies one or more text highlighting attributes to use when showing pets on the map. Effectively a superset of the .op hilite_pet boolean option. -Curses interface only; value is one or more of the following letters. -.sd -.si -.CC n "Normal text (no highlighting)" -.CC i "Inverse video (default)" -.CC b "Bold text" -.CC u "Underlined text" -.CC k "blinKing text" -.CC d "Dim text" -.CC t "iTalic text" -.CC l "Left line indicator" -.CC r "Right line indicator" -.ei -.ed -Some of those choices might not work, particularly the final three, +Curses or tty interface only; value is one of +none, bold, dim, underline, italic, blink, and inverse. +Some of those choices might not work, depending upon terminal hardware or terminal emulation software. -.lp "" -Currently multiple highlight-style letters can be combined by simply -stringing them together (for example, \(lqbk\(rq), but in the future -they might require being separated by plus signs (such as \(lqb+k\(rq, -which works already). -When using the \(oqn\(cq choice, it should be specified on its own, -not in combination with any of the other letters. -.lp pettype +.lp "pettype " Specify the type of your initial pet, if you are playing a character class that uses multiple types of pets; or choose to have no initial pet at all. Possible values are \(lqcat\(rq, \(lqdog\(rq, \(lqhorse\(rq, and \(lqnone\(rq. If the choice is not allowed for the role you are currently playing, it will be silently ignored. For example, \(lqhorse\(rq will only be honored when playing a knight. -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp pickup_burden When you pick up an item that would exceed this encumbrance level (Unencumbered, Burdened, streSsed, straiNed, overTaxed, or overLoaded), you will be asked if you want to continue. (Default \(oqS\(cq). Persistent. +.lp pickup_stolen +If this option is on and +.op autopickup +is also on, try to pick up things that a monster stole from you, even if they +aren't in +.op pickup_types +or match an autopickup exception. +Default is on. +Persistent. .lp pickup_thrown If this option is on and .op autopickup is also on, try to pick up things that you threw, even if they aren't in .op pickup_types -or match an autopickup exception. Default is on. Persistent. +or match an autopickup exception. +Default is on. +Persistent. .lp pickup_types Specify the object types to be picked up when .op autopickup -is on. Default is all types. You can use +is on. +Default is all types. +Persistent. +.lp "" +The value is a list of object symbols, such as +\f(CRpickup_types:$?!\fP to pick up gold, scrolls, and potions. +You can use .op autopickup_exception -configuration file lines to further refine -.op autopickup -behavior. Persistent. +configuration file lines to further refine \f(CRautopickup\fP behavior. +.lp "" +There is no way to set \f(CRpickup_types\fP to \(lq\fInone\fP\(rq. +(Setting it to an empty value reverts to \(lq\fIall\fP\(rq.) +If you want to avoid automatically picking up any types of items but do +want to have \f(CRautopickup\fP on in order to have +\f(CRautopickup_exception\fP settings control what you do and don't pick +up, you can set \f(CRpickup_types\fP to \(oq\f(CR.\fP\(cq. +That is the type symbol for \fIvenom\fP and you won't come across +any venom items so won't unintentionally pick such up. .lp pile_limit When walking across a pile of objects on the floor, threshold at which the message \(lqthere are few/several/many objects here\(rq is given instead @@ -3416,41 +4656,99 @@ user name (on multi-user systems) or specifying a particular character name (on single-user systems) or it might be disabled entirely. Requesting it when not allowed or not possible results in explore mode instead. Default is normal play. +.lp price_quotes +Whenever the game mentions the name of an object you haven't identified yet, +it also mentions the range of buy and sell prices you have seen for that +item (to help narrow down what it could be). +The price shown is the unit price for one item (even when you are looking at +a stack of multiple items). +Many players may want to turn this on while identifying objects, and then +turn it back off again for general play. +Default is off. .lp pushweapon Using the \(oqw\(cq (wield) command when already wielding something pushes the old item into your alternate weapon slot (default off). Likewise for the \(oqa\(cq (apply) command if it causes the applied item to become wielded. Persistent. +.lp query_menu +Use a menu when asked specific yes/no queries, instead of a prompt. +.lp quick_farsight +When set, usually prevents the \(lqyou sense your surroundings\(rq message +where play pauses to allow you to browse the map whenever clairvoyance +randomly activates. +Some situations, such as being underwater or engulfed, ignore this option. +It does not affect the clairvoyance spell where pausing to examine revealed +objects or monsters is less intrusive. +Default is off. Persistent. .lp "race " -Selects your race (for example, \(lqrace:human\(rq). -Default is random. -If you prefix the value with \(oq!\(cq or \(lqno\(rq, you will -exclude that race from being picked randomly. -Cannot be set with the \(oqO\(cq command. +Selects your race (for example, \f(CRrace:human\fP). +Choices are \f(CRhuman\fP, \f(CRdwarf\fP, \f(CRelf\fP, \f(CRgnome\fP, and +\f(CRorc\fP but most roles restrict which of the non-human races are allowed. +See +.op role +for a description of how to use negation to exclude choices. +.lp "" +If \f(CRrace\fP is not specified, there is no default value; +player will be prompted unless role forces a choice for race. +Cannot be set with the \(oq\f(CRO\fP\(cq command. Persistent. +.lp reroll +Allows rerolling your character's starting inventory and attributes (default +false). Persistent. +.lp "" +Note that rerolling your character is not a recommended way to play if aiming +merely to win (a lucky start has a much smaller influence on whether or not +you win the game than your actions later in the game). This option exists +partly as an acknowledgement that some players will insist on doing so anyway, +and partly because rerolling may be necessary for certain types of challenge +games. .lp rest_on_space Make the space bar a synonym for the \(oq.\(cq (#wait) command (default off). Persistent. .lp "role " -Pick your type of character (for example \(lqrole:Samurai\(rq); -synonym for \(lqcharacter\(rq. -See \(lqname\(rq for an alternate method of specifying your role. -Normally only the first letter of the value is examined; \(oqr\(cq is an -exception with \(lqRogue\(rq, \(lqRanger\(rq, and \(lqrandom\(rq values. -If you prefix the value with \(oq!\(cq or \(lqno\(rq, you will -exclude that role from being picked randomly. -Cannot be set with the \(oqO\(cq command. +Pick your type of character (for example, \f(CRrole:Samurai\fP); +synonym for +.op character. +See +.op name +for an alternate method of specifying your role. +.\" Normally only the first letter of the value is examined; \(oqr\(cq is an +.\" exception with \(lqRogue\(rq, \(lqRanger\(rq, and \(lqrandom\(rq values. +.lp "" +This option can also be used to limit selection when role is chosen +randomly. +Use a space-separated list of roles and either negate each one or negate +the option itself instead. +Negation is accomplished in the same manner as with \fIboolean options\fP, +by prefixing the option or its value(s) with \(oq!\(cq or \(lqno\(rq. +.BR 0 +Examples: +.sd +.ft CR \" constant-width Roman +OPTIONS=role:!arc !bar !kni +OPTIONS=!role:arc bar kni +.ft \" revert to previous font +.ed +There can be multiple instances of the +.op role +option if they're all negations. +.\" Only one positive value is allowed, and if present, it overrides any +.\" negations. +.lp "" +If \f(CRrole\fP is not specified, there is no default value; +player will be prompted. +Cannot be set with the \(oq\f(CRO\fP\(cq command. Persistent. .lp roguesymset This option may be used to select one of the named symbol sets found within \(lqsymbols\(rq to alter the symbols displayed on the screen on the rogue level. -.lp rlecomp +.lp "rlecomp " When writing out a save file, perform run length compression of the map. Not all ports support run length compression. It has no effect on reading an existing save file. -.lp runmode +.lp "runmode " Controls the amount of screen updating for the map window when engaged in multi-turn movement (running via shift+direction or control+direction and so forth, or via the travel command or mouse click). @@ -3474,48 +4772,134 @@ Persistent. .lp safe_pet Prevent you from (knowingly) attacking your pets (default on). Persistent. +.lp safe_wait +Prevents you from waiting or searching when next to a hostile monster +(default on). Persistent. .lp sanity_check Evaluate monsters, objects, and map prior to each turn (default off). Debug mode only. -.lp scores +.lp "scores " Control what parts of the score list you are shown at the end (for example \(lqscores:5 top scores/4 around my score/own scores\(rq). Only the first letter of each category (\(oqt\(cq, \(oqa\(cq, or \(oqo\(cq) is necessary. Persistent. -.lp showexp +.lp showdamage +Whenever your character takes damage, show a message of the damage taken, +and the amount of hit points left. +.lp "showexp " Show your accumulated experience points on bottom line (default off). Persistent. .lp showrace Display yourself as the glyph for your race, rather than the glyph -for your role (default off). Note that this setting affects only +for your role (default off). +Note that this setting affects only the appearance of the display, not the way the game treats you. Persistent. .lp showscore Show your approximate accumulated score on bottom line (default off). +By default, this feature is suppressed when building the program. +Persistent. +.lp showvers +Include the game's version number on the status lines (default off). +Potentially useful if you switch between different versions or variants, +or you are making screenshots or streaming video. +Using the +.op statuslines:3 +option is recommended so that there will be more room available for +status information, unless you're using NetHack's \fIQt\fP interface +or your terminal emulator window displays fewer than 25 lines. Persistent. +.lp "" +The +.op versinfo +option provides limited control over what information +.op showvers +displays. .lp "silent " -Suppress terminal beeps (default on). Persistent. +Suppress terminal beeps (default on). +Persistent. +.lp sortdiscoveries +Controls the sorting behavior for the output of the \(oq\f(CR\\\fP\(cq +and \(oq\f(CR\`\fP\(cq commands. +Persistent. +.lp "" +The possible values are: +.PS \f(CRo\fP +.PL \f(CRo\fP +list object types by class, in discovery order within each class; +default; +.PL \f(CRs\fP +list object types by +.op sortloot +classification: by class, by sub-class within class for classes which +have substantial groupings (like helmets, boots, gloves, and so forth +for armor), with object types partly-discovered via assigned name coming +before fully identified types; +.PL \f(CRc\fP +list by class, alphabetically within each class; +.PL \f(CRa\fP +list alphabetically across all classes. +.PE +Can be interactively set via the \(oq\f(CRO\fP\(cq command or via using +the \(oq\f(CRm\fP\(cq prefix before the \(oq\f(CR\\\fP\(cq +or \(oq\f(CR\`\fP\(cq command. .lp sortloot Controls the sorting behavior of the pickup lists for inventory and #loot commands and some others. Persistent. +.lp "" The possible values are: -.PS full +.PS none \" note: with proportional font, "none" is wider than "full" or "loot" .PL full always sort the lists; .PL loot only sort the lists that don't use inventory letters, like with the #loot and pickup commands; .PL none -show lists the traditional way without sorting. +show lists the traditional way without sorting; +default. .PE .lp sortpack Sort the pack contents by type when displaying inventory (default on). Persistent. -.lp sparkle +.lp sortvanquished +Controls the sorting behavior for the output of the #vanquished command +and also for the #genocided command. +Persistent. +.lp "" +The possible values are: +.PS \f(CRC\fP +.PL \f(CRt\fP +traditional\(emorder by monster level; ties are broken by internal +monster index; +default; +.PL \f(CRd\fP +order by monster difficulty rating; ties broken by internal index; +.PL \f(CRa\fP +order alphabetically, first any unique monsters then all the others; +.\" note: 'A' and 'C' can be set in RC file or NETHACKOPTIONS but not by 'O' +.\" .PL \f(CRA\fP +.\" order alphabetically, unique monsters intermixed with other monsters; +.\" .PL \f(CRC\fP +.\" order by monster class, by high to low level within each class; +.PL \f(CRc\fP +order by monster class, by low to high level within each class; +.PL \f(CRn\fP +order by count, high to low; ties are broken by internal monster index; +.PL \f(CRz\fP +order by count, low to high; ties broken by internal index. +.PE +Can be interactively set via the \(oq\f(CRm O\fP\(cq command or via using +the \(oq\f(CRm\fP\(cq prefix before either the #vanquished command +or the #genocided command. +.lp "sounds " +Allow sounds to be emitted from an integrated sound library (default on). +.lp "sparkle " Display a sparkly effect when a monster (including yourself) is hit by an attack to which it is resistant (default on). Persistent. +.lp spot_monsters +Show a message when hero notices a monster (default is off). .lp standout Boldface monsters and \(lq\fB\-\-More\-\-\fP\(rq (default off). Persistent. @@ -3529,10 +4913,13 @@ Allow updates to the status lines at the bottom of the screen (default true). This option may be set to a NetHack version level to suppress alert notification messages about feature changes for that and prior versions (for example \(lqsuppress_alert:3.3.1\(rq). -.lp symset +.lp "symset " This option may be used to select one of the named symbol sets found within \(lqsymbols\(rq to alter the symbols displayed on the screen. Use \(lqsymset:default\(rq to explicitly select the default symbols. +.lp terrainstatus +Display an extra status condition describing the spot beneath the hero's +feet (default off, not supported by all interfaces). .lp "time " Show the elapsed game time in turns on bottom line (default off). Persistent. @@ -3540,10 +4927,13 @@ Persistent. When pausing momentarily for display effect, such as with explosions and moving objects, use a timer rather than sending extra characters to the screen. -(Applies to \(lqtty\(rq interface only; \(lqX11\(rq interface always -uses a timer based delay. +(Applies to \(lqtty\(rq and \(lqcurses\(rq interfaces only; \(lqX11\(rq interface always +uses a timer-based delay. The default is on if configured into the program.) Persistent. +.lp "tips " +Show some helpful tips during gameplay (default on). +Persistent. .lp tombstone Draw a tombstone graphic upon your death (default on). Persistent. @@ -3552,15 +4942,34 @@ Put the ending display in a NetHack window instead of on stdout (default off). Setting this option makes the score list visible when a windowing version of NetHack is started without a parent window, but it no longer leaves the score list around after game end on a terminal or emulating window. -.lp travel -Allow the travel command (default on). Turning this option off will -prevent the game from attempting unintended moves if you make inadvertent -mouse clicks on the map window. Persistent. +.lp "travel " +Allow the travel command via mouse click (default on). +Turning this option off will prevent the game from attempting unintended +moves if you make inadvertent mouse clicks on the map window. +Does not affect traveling via the \(oq\f(CR_\fP\(cq (\(lq#travel\(rq) command. +Persistent. ." .lp travel_debug ." Display intended path during each step of travel (default off). ." Debug mode only. -.lp verbose +.lp tutorial +Play a tutorial level at the start of the game. +Setting this option on or off in the config file will skip the query. +.lp "verbose " Provide more commentary during the game (default on). Persistent. +.lp versinfo +Controls what the +.op showvers +option displays on the status lines. +.lp weaponstatus +Display an extra status condition which describes currently wielded weapon +(default off, not supported by all interfaces). +.lp "" +Some possible displayed values are: +.sd +\f(CRbare-hnds\fP - no weapon and no gloves; +\f(CRempty-hnd\fP - no weapon but gloves are worn; +\f(CRdual-weps\fP - wielding two weapons. +.ed .lp whatis_coord When using the \(oq/\(cq or \(oq;\(cq commands to look around on the map with .op autodescribe @@ -3592,9 +5001,10 @@ next and previous targets, allows filtering the possible targets. .CC a "in same area only" .ei .ed -The area-filter tries to be slightly predictive \(em if you're standing -on a doorway, -it will consider the area on the side of the door you were last moving towards. +The area-filter tries to be slightly +predictive\(emif +you're standing on a doorway, it will consider the area on the side of +the door you were last moving towards. .lp "" Filtering can also be changed when getting a location with the \(lqgetpos.filter\(rq key. @@ -3611,7 +5021,7 @@ move by skipping the same glyphs. When the program has been built to support multiple interfaces, select which one to use, such as \(lqtty\(rq or \(lqX11\(rq (default depends on build-time settings; use \(lq#version\(rq to check). -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp "" When used, it should be the first option set since its value might enable or disable the availability of various other options. @@ -3649,10 +5059,22 @@ Where to align or place the message window (top, bottom, left, or right) .lp align_status Where to align or place the status window (top, bottom, left, or right). .lp ascii_map -If NetHack can, it should display an ascii character map if it can. -.lp color +.hw DECgraphics IBMgraphics \" don't hyphenate these +If NetHack can, it should display the map using simple +characters (letters and punctuation) rather than \fItiles\fP graphics. +In some cases, characters can be augmented with line-drawing symbols; +use the +.op symset +option to select a symbol set such as \fIDECgraphics\fP +or \fIIBMgraphics\fP if your display supports them. +Setting +.op ascii_map +to \fITrue\fP forces +.op tiled_map +to be \fIFalse\fP. +.lp "color " If NetHack can, it should display color if it can for different monsters, -objects, and dungeon features. +objects, and dungeon features (default on). .lp eight_bit_tty If NetHack can, it should pass eight-bit character values (for example, specified with the @@ -3679,9 +5101,9 @@ If NetHack can, it should use this size font for the status window. .lp font_size_text If NetHack can, it should use this size font for text windows. .lp fullscreen -If NetHack can, it should try and display on the entire screen rather than +If NetHack can, it should try to display on the entire screen rather than in a window. -.lp guicolor +.lp "guicolor " Use color text and/or highlighting attributes when displaying some non-map data (such as menu selector letters). Curses interface only; default is on. @@ -3699,7 +5121,7 @@ If NetHack can, it should preload tiles into memory. For example, in the protected mode MS-DOS version, control whether tiles get pre-loaded into RAM at the start of the game. Doing so enhances performance of the tile graphics, but uses more memory. (default on). -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp scroll_amount If NetHack can, it should scroll the display by this number of cells when the hero reaches the scroll_margin. @@ -3718,8 +5140,34 @@ If NetHack can, it should display an opening splash screen when it starts up (default yes). .lp statuslines Number of lines for traditional below-the-map status display. -Acceptable values are 2 and 3 (default is 2). -Curses and tty interfaces only. +Acceptable values are \f(CR2\fP and \f(CR3\fP (default is \f(CR2\fP). +.lp "" +When set to \f(CR3\fP, the \f(CRtty\fP interface moves some fields around and +mainly shows status conditions on their own line. +A display capable of showing at least 25 lines is recommended. +The value can be toggled back and forth during the game with the +\(oq\f(CRO\fP\(cq command. +.lp "" +The \f(CRcurses\fP interface does likewise if the +.op align_status +option is set to \fItop\fP or \fIbottom\fP but ignores +.op statuslines +when set to \fIleft\fP or \fIright\fP. +.lp "" +The \f(CRQt\fP interface already displays more than 3 lines for status +so uses the +.op statuslines +value differently. +A value of \f(CR3\fP renders status in the \f(CRQt\fP interface's +original format, with the status window spread out vertically. +A value of \f(CR2\fP makes status be slightly condensed, moving some +fields to different lines to eliminate one whole line, reducing the +height needed. +(If NetHack has been built using a version of \f(CRQt\fP +older than \f(CRqt-5.9\fP, +.op statuslines +can only be set in the run-time configuration file or via NETHACKOPTIONS, +not during play with the \(oq\f(CRO\fP\(cq command.) .lp "term_cols\ \ \fIand\fP" .lp term_rows Curses interface only. @@ -3727,14 +5175,25 @@ Number of columns and rows to use for the display. Curses will attempt to resize to the values specified but will settle for smaller sizes if they are too big. Default is the current window size. -.lp tiled_map -If NetHack can, it should display a tiled map if it can. .lp tile_file Specify the name of an alternative tile file to override the default. +.lp "" +Note: the X11 interface uses X resources rather than NetHack's options +to select an alternate tile file. +See \f(CRNetHack.ad\fP, the sample X \(lqapplication defaults\(rq file. .lp tile_height Specify the preferred height of each tile in a tile capable port. .lp tile_width Specify the preferred width of each tile in a tile capable port +.lp tiled_map +If NetHack can, it should display the map using \fItiles\fP graphics +rather than simple characters (letters and punctuation, possibly +augmented by line-drawing symbols). +Setting +.op tiled_map +to \fITrue\fP forces +.op ascii_map +to be \fIFalse\fP. .lp use_darkgray Use bold black instead of blue for black glyphs (TTY only). .lp use_inverse @@ -3751,31 +5210,43 @@ Acceptable values are .si .CC 0 "off, never show borders" .CC 1 "on, always show borders" -.CC 2 "auto, on if display is at least (24+2)x(80+2)\ \ (default)" +.CC 2 "auto, on if display is at least (24+2)x(80+2) [default]" +.CC 3 "on, except forced off for perm_invent" +.CC 4 "auto, except forced off for perm_invent" .ei .ed .lp "" (The 26x82 size threshold for \(oq2\(cq refers to number of rows and columns of the display. -A width of at least 110 columns (80+2+26+2) is needed for +A width of at least 110 columns (80+2+26+2) is needed to show borders if .op align_status -set to \f(CRleft\fP or \f(CRright\fP.) +is set to \f(CRleft\fP or \f(CRright\fP.) +.lp "" +The persistent inventory window, when enabled, can grow until it is +too big to fit on most displays, resulting in truncation of its contents. +If borders are forced on (1) or the display is big enough to show them (2), +setting the value to 3 or 4 instead will keep borders for the map, message, +and status windows but have room for two additional lines of inventory +plus widen each inventory line by two columns. .lp windowcolors -If NetHack can, it should display windows with the specified -foreground/background colors. Windows GUI only. The format is +If NetHack can, it should display all windows of a particular style +with the specified foreground and background colors. +Windows GUI and curses windowport only. +The format is .si -.lp "OPTION=windowcolors:wintype foreground/background" +.lp "\f(CROPTION=windowcolors:\fIstyle foreground\f(CR/\fIbackground\fR" .ei -.pg -where wintype is one of \(lqmenu\(rq, \(lqmessage\(rq, \(lqstatus\(rq, +.lp "" +where \fIstyle\fP is one of \(lqmenu\(rq, \(lqmessage\(rq, \(lqstatus\(rq, or \(lqtext\(rq, and -foreground and background are colors, either a hexadecimal \\'#rrggbb', +\fIforeground\fP and \fIbackground\fP are colors, either numeric (hash +sign followed by three pairs of hexadecimal digits, \fI#rrggbb\fP), one of the named colors (black, red, green, brown, -blue, magenta, cyan, orange, brightgreen, yellow, brightblue, -brightmagenta, brightcyan, white, trueblack, gray, purple, +blue, magenta, cyan, orange, bright-green, yellow, bright-blue, +bright-magenta, bright-cyan, white, gray, purple, silver, maroon, fuchsia, lime, olive, navy, teal, aqua), -or one of Windows UI colors (activeborder, activecaption, -appworkspace, background, btnface, btnshadow, btntext, +or (for Windows only) one of Windows UI colors (trueblack, activeborder, +activecaption, appworkspace, background, btnface, btnshadow, btntext, captiontext, graytext, greytext, highlight, highlighttext, inactiveborder, inactivecaption, menu, menutext, scrollbar, window, windowframe, windowtext). @@ -3783,6 +5254,22 @@ window, windowframe, windowtext). If NetHack can, it should wrap long lines of text if they don't fit in the visible area of the window. .hn 2 +Crash Report Options +.pg +Please note that NetHack does not send \fBany\fP information off your +computer unless you manually click submit on a form. +.si +.lp "OPTION=crash_email:\fIemail_address\fP +.lp "OPTION=crash_name:\fIyour_name\fP +.ei +These options are used only to save you some typing on the crash +report and #bugreport forms. +.si +.lp "OPTION=crash_urlmax:\fIbytes\fP +.ei +This option is used to limit the length of the URLs generated and is only +needed if your browser cannot handle arbitrarily long URLs. +.hn 2 Platform-specific Customization options .pg Here are explanations of options that are used by specific platforms or ports @@ -3791,19 +5278,17 @@ to customize and change the port behavior. Select an alternate way to handle keystrokes (Win32 tty NetHack only). The name of the handling type is one of \(lqdefault\(rq, \(lqray\(rq, \(lq340\(rq. -.lp altmeta -On Amiga, this option controls whether typing \(lqAlt\(rq plus another key -functions as a meta-shift for that key (default on). -.lp altmeta -On other (non-Amiga) systems where this option is available, it can be +.lp "altmeta " +On systems where this option is available, it can be set to tell NetHack to convert a two character sequence beginning with ESC into a meta-shifted version of the second character (default off). .lp "" This conversion is only done for commands, not for other input prompts. Note that typing one or more digits as a count prefix prior to a -command \(em preceded by \fBn\fP if the +command\(empreceded by \fBn\fP if the .op number_pad -option is set \(em is also subject to this conversion, so attempting to +option is set\(emis +also subject to this conversion, so attempting to abort the count by typing ESC will leave NetHack waiting for another character to complete the two character sequence. Type a second ESC to finish cancelling such a count. @@ -3813,49 +5298,49 @@ Use BIOS calls to update the screen display quickly and to read the keyboard (allowing the use of arrow keys to move) on machines with an IBM PC compatible BIOS ROM (default off, OS/2, PC, and ST NetHack only). -.lp flush -(default off, Amiga NetHack only). -.lp "MACgraphics" -(default on, Mac NetHack only). -.lp page_wait -(default on, Mac NetHack only). .lp "rawio " Force raw (non-cbreak) mode for faster output and more bulletproof input (MS-DOS sometimes treats \(oq\(haP\(cq as a printer toggle without it) (default off, OS/2, PC, and ST NetHack only). Note: DEC Rainbows hang if this is turned on. -Cannot be set with the \(oqO\(cq command. -.lp soundcard -(default on, PC NetHack only). -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp subkeyvalue (Win32 tty NetHack only). May be used to alter the value of keystrokes that the operating system returns to NetHack to help compensate for international keyboard issues. OPTIONS=subkeyvalue:171/92 will return 92 to NetHack, if 171 was originally going to be returned. -You can use multiple subkeyvalue statements in the configuration file +You can use multiple subkeyvalue assignments in the configuration file if needed. -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp video Set the video mode used (PC NetHack only). -Values are \(lqautodetect\(rq, \(lqdefault\(rq, or \(lqvga\(rq. -Setting \(lqvga\(rq (or \(lqautodetect\(rq with vga hardware present) -will cause the game to display tiles. -Cannot be set with the \(oqO\(cq command. +Values are \(lqautodetect\(rq, \(lqdefault\(rq, \(lqvga\(rq, or \(lqvesa\(rq. +Setting \(lqvesa\(rq will cause the game to display tiles, using the full +capability of the VGA hardware. +Setting \(lqvga\(rq will cause the game to display tiles, fixed at 640x480 +in 16 colors, a mode that is compatible with all VGA hardware. Third party +tilesets will probably not work. +Setting \(lqautodetect\(rq attempts \(lqvesa\(rq, then \(lqvga\(rq, and +finally sets \(lqdefault\(rq if neither of those modes works. +Cannot be set with the \(oq\f(CRO\fP\(cq command. +.lp video_height +Set the VGA mode resolution height (MS-DOS only, with video:vesa) +.lp video_width +Set the VGA mode resolution width (MS-DOS only, with video:vesa) .lp videocolors Set the color palette for PC systems using NO_TERMS (default 4-2-6-1-5-3-15-12-10-14-9-13-11, (PC NetHack only). The order of colors is red, green, brown, blue, magenta, cyan, bright.white, bright.red, bright.green, yellow, bright.blue, bright.magenta, and bright.cyan. -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .lp videoshades Set the intensity level of the three gray scales available (default dark normal light, PC NetHack only). If the game display is difficult to read, try adjusting these scales; if this does not correct the problem, try !color. -Cannot be set with the \(oqO\(cq command. +Cannot be set with the \(oq\f(CRO\fP\(cq command. .hn 2 Regular Expressions .pg @@ -3863,7 +5348,9 @@ Regular expressions are normally POSIX extended regular expressions. It is possible to compile NetHack without regular expression support on a platform where there is no regular expression library. While this is not true of any modern platform, if your NetHack was built this way, patterns are instead glob -patterns. This applies to Autopickup exceptions, Message types, Menu colors, +patterns; regardless, this document refers to both as \(oqregular +expressions.\(cq +This applies to Autopickup exceptions, Message types, Menu colors, and User sounds. .hn 2 Configuring Autopickup Exceptions @@ -3912,9 +5399,11 @@ rules and not saved with the game. .lp "Here are some examples:" .sd .si +.ft CR autopickup_exception="<*arrow" autopickup_exception=">*corpse" autopickup_exception=">* cursed*" +.ft .ei .ed .\" (this paragraph would look better unindented but can't use .lp hack...) @@ -3931,13 +5420,14 @@ menu accelerator keys, and extended commands, by using BIND stanzas in the configuration file. Format is key, followed by the command to bind to, separated by a colon. The key can be a single character (\(lqx\(rq), a control key (\(lq\(haX\(rq, -\(lqC-x\(rq), a meta key (\(lqM-x\(rq), or a three-digit decimal ASCII code. +\(lqC-x\(rq), a meta key (\(lqM-x\(rq), a mouse button, +or a three-digit decimal ASCII code. .pg For example: .sd .si BIND=\(haX:getpos.autodescribe -BIND={:menu_first_page +BIND=\\:menu_first_page BIND=v:loot .ei .ed @@ -3949,7 +5439,11 @@ You can also bind the \(lq\(rq, \(lq\(rq, and \(lq\(rq keys. .lp "Menu accelerator keys" The menu control or accelerator keys can also be rebound via OPTIONS lines in the configuration file. -You cannot bind object symbols into menu accelerators. +You cannot bind object symbols or selection letters into menu accelerators. +Some interfaces only support some of the menu accelerators. +.lp "Mouse buttons" +You can bind \(lqmouse1\(rq or \(lqmouse2\(rq to \(lqnothing\(rq, +\(lqtherecmdmenu\(rq, \(lqclicklook\(rq, or \(lqmouseaction\(rq. .lp "Special command keys" Below are the special commands you can rebind. Some of them can be bound to @@ -3963,29 +5457,23 @@ With .op number_pad only. Default is \(oqn\(cq. -.lp doinv -Show inventory. -With -.op number_pad -only. -Default is \(oq0\(cq. -.lp fight -Prefix key to force fight a direction. -Default is \(oqF\(cq. -.lp fight.numpad -Prefix key to force fight a direction. -With -.op number_pad -only. -Default is \(oq\-\(cq. .lp getdir.help When asked for a direction, the key to show the help. Default is \(oq?\(cq. +.lp getdir.mouse +When asked for a direction, the key to initiate a simulated mouse click. +You will be asked to pick a location. +Use movement keystrokes to move the cursor around the map, then type +the getpos.pick.once key (default \(oq\f(CR,\fP\(cq) +or the getpos.pick key (default \(oq\f(CR.\fP\(cq) +to finish as if performing a left or right click. +Only useful when using the \f(CR#therecmdmenu\fP command. +Default is \(oq_\(cq. \" underscore .lp getdir.self When asked for a direction, the key to target yourself. Default is \(oq.\(cq. .lp getdir.self2 -When asked for a direction, the key to target yourself. +When asked for a direction, an alternate key to target yourself. Default is \(oqs\(cq. .lp getpos.autodescribe When asked for a location, the key to toggle autodescribe. @@ -4036,10 +5524,14 @@ Default is \(oq\(dq\(cq. \" double quote .lp getpos.pick When asked for a location, the key to choose the location, and possibly ask for more info. +When simulating a mouse click after being asked for a direction (see +getdir.mouse above), the key to use to respond as right click. Default is \(oq.\(cq. .lp getpos.pick.once When asked for a location, the key to choose the location, and skip asking for more info. +When simulating a mouse click after being asked for a direction, +the key to respond as left click. Default is \(oq,\(cq. .lp getpos.pick.quick When asked for a location, the key to choose the location, skip asking for @@ -4068,39 +5560,6 @@ Default is \(oqz\(cq. .lp getpos.valid.prev When asked for a location, the key to go to previous closest valid location. Default is \(oqZ\(cq. -.lp nopickup -Prefix key to move without picking up items. -Default is \(oqm\(cq. -.lp redraw -Key to redraw the screen. -Default is \(oq\(haR\(cq. -.lp redraw.numpad -Key to redraw the screen. -With -.op number_pad -only. -Default is \(oq\(haL\(cq. -.lp repeat -Key to repeat previous command. -Default is \(oq\(haA\(cq. -.lp reqmenu -Prefix key to request menu from some commands. -Default is \(oqm\(cq. -.lp run -Prefix key to run towards a direction. -Default is \(oqG\(cq. -.lp run.nopickup -Prefix key to run towards a direction without picking up items on the way. -Default is \(oqM\(cq. -.lp run.numpad -Prefix key to run towards a direction. -With -.op number_pad -only. -Default is \(oq5\(cq. -.lp rush -Prefix key to rush towards a direction. -Default is \(oqg\(cq. .hn 2 Configuring Message Types .pg @@ -4137,8 +5596,10 @@ Here's an example of message types using NetHack's internal pattern matching facility: .sd .si +.ft CR MSGTYPE=stop "You feel hungry." MSGTYPE=hide "You displaced *." +.ft .ei .ed specifies that whenever a message \(lqYou feel hungry\(rq is shown, @@ -4180,7 +5641,7 @@ orange, light-green, yellow, light-blue, light-magenta, light-cyan, and white. And \f(CRno-color\fP, the default foreground color, which isn't necessarily the same as any of the other colors. .lp "" -Allowed attributes are none, bold, dim, underline, blink, and inverse. +Allowed attributes are none, bold, dim, italic, underline, blink, and inverse. \(lqNormal\(rq is a synonym for \(lqnone\(rq. Note that the platform used may interpret the attributes any way it wants. @@ -4224,19 +5685,34 @@ The directory that houses the sound files to be played. .lp SOUND An entry that maps a sound file to a user-specified message pattern. Each SOUND entry is broken down into the following parts: -.PS "sound file" +.PS "sound index" .PL MESG -message window mapping (the only one supported in 3.6); +message window mapping (the only one supported in 5.0.0); +.PL msgtype +optional; message type to use, see \(lqConfiguring Message Types\(rq .PL pattern the pattern to match; .PL "sound file" the sound file to play; .PL volume -the volume to be set while playing the sound file. +the volume to be set while playing the sound file; +.PL "sound index" +optional; the index corresponding to a sound file. .PE .lp "" -The pattern should be a POSIX extended regular expression. +The pattern should be a regular expression. .pg +For example: +.sd +.si +.ft CR +SOUNDDIR=C:\\nethack\\sounds +SOUND=MESG "This door is locked" "lock.wav" 100 +SOUND=MESG hide "^You miss the " "swing.wav" 75 +.ft +.ei +.ed +.BR 0 \" without this, the next section seems too close to this one .hn 2 Configuring Status Hilites .pg @@ -4247,7 +5723,9 @@ change the color or appearance of fields in the status display. .pg The format for defining status colors is: .SD n -\f(CROPTION=hilite_status:\fIfield-name\fP/\fIbehavior\fP/\fIcolor\fP&\fIattributes\fP\fP +.\" was "\f(CR...\fI...\fP\fP" but font changes don't nest so final \fP didn't +.\" restore the pre-\f(CR font; assume that was Roman and explicitly use \fR +\f(CROPTION=hilite_status:\fIfield-name\fP/\fIbehavior\fP/\fIcolor\fP&\fIattributes\fP\fR .ED .pg For example, the following line in your configuration file will cause @@ -4270,7 +5748,7 @@ orange, light-green, yellow, light-blue, light-magenta, light-cyan, and white. And \(lqno-color\(rq, the default foreground color on the display, which is not necessarily the same as black or white or any of the other colors. .pg -Allowed attributes are none, bold, dim, underline, blink, and inverse. +Allowed attributes are none, bold, dim, underline, italic, blink, and inverse. \(lqNormal\(rq is a synonym for \(lqnone\(rq; they should not be used in combination with any of the other attributes. .pg @@ -4290,7 +5768,7 @@ the \f(CRtty\fP interface) rather than all at once, the only way a situation like that can be controlled is to specify just one attribute. .pg You can adjust the appearance of the following status fields: -.TS S +.TS center; c c c. .\"TABLE_START @@ -4321,6 +5799,11 @@ for stone through termill, \(lqminor_troubles\(rq for blind through hallu, Allowed behaviors are \(lqalways\(rq, \(lqup\(rq, \(lqdown\(rq, \(lqchanged\(rq, a percentage or absolute number threshold, or text to match against. +For the \fIhitpoints\fP field, the additional behavior \(lqcriticalhp\(rq +is available. +It overrides other behavior rules if +hit points are at or below the \fImajor problem\fP threshold +(which varies depending upon maximum hit points and experience level). .si .lp "*" \(lqalways\(rq will set the default attributes for that field. @@ -4376,6 +5859,12 @@ it also matches when value is below or above. If the prefix is \(oq<\(cq or \(oq>\(cq, only match when strictly above or below. .lp "*" +criticalhp only applies to the hitpoints field and only +when current hit points are below a threshold (which varies by maximum +hit points and experience level). +When the threshold is met, a criticalhp rule takes precedence over all +other hitpoints rules. +.lp "*" text match sets the attribute when the field value matches the text. Text matches can only be used for \(lqalignment\(rq, @@ -4395,6 +5884,7 @@ to 0. Example hilites: .sd .si +.ft CR OPTION=hilite_status: gold/up/yellow/down/brown OPTION=hilite_status: characteristics/up/green/down/red OPTION=hilite_status: hitpoints/100%/gray&normal @@ -4405,9 +5895,10 @@ OPTION=hilite_status: hitpoints/<33%/red&bold OPTION=hilite_status: hitpoints/<15%/red&inverse OPTION=hilite_status: condition/major/orange&inverse OPTION=hilite_status: condition/lev+fly/red&inverse +.ft .ei .ed -.pg +.BR 0 \" without this, the next section seems too close to this one .hn 2 Modifying NetHack Symbols .pg @@ -4442,7 +5933,7 @@ control character. .\" to be too wide when generating plain text output. Two spaces leaves .\" some room between the symbol character and name.) Entries in first .\" column now use constant-width Roman font to approximate TeX tt font. -.TS S +.TS center; l s s l1fCR l1 l. @@ -4470,6 +5961,10 @@ b S_blob (blob) ( S_boomright (boomerang open right) \` S_boulder (boulder) \- S_brcorn (bottom right corner) +> S_brdnladder (branch ladder down) +> S_brdnstair (branch staircase down) +< S_brupladder (branch ladder up) +< S_brupstair (branch staircase up) C S_centaur (centaur) \&_ S_chain (iron chain) # S_cloud (cloud) @@ -4487,15 +5982,17 @@ d S_dog (dog or other canine) D S_dragon (dragon) ; S_eel (sea monster) E S_elemental (elemental) -/ S_explode1 (explosion top left) -\- S_explode2 (explosion top center) -\\ S_explode3 (explosion top right) -| S_explode4 (explosion middle left) -\ S_explode5 (explosion middle center) -| S_explode6 (explosion middle right) -\\ S_explode7 (explosion bottom left) -\- S_explode8 (explosion bottom center) -/ S_explode9 (explosion bottom right) +# S_engrcorr (engraving in a corridor) +\` S_engroom (engraving in a room) +/ S_expl_tl (explosion top left) +\- S_expl_tc (explosion top center) +\\ S_expl_tr (explosion top right) +| S_expl_ml (explosion middle left) +\ S_expl_mc (explosion middle center) +| S_expl_mr (explosion middle right) +\\ S_expl_bl (explosion bottom left) +\- S_expl_bc (explosion bottom center) +/ S_expl_br (explosion bottom right) e S_eye (eye or sphere) \(ha S_falling_rock_trap (falling rock trap) f S_feline (cat or other feline) @@ -4529,6 +6026,7 @@ k S_kobold (kobold) K S_kop (Keystone Kop) \(ha S_land_mine (land mine) } S_lava (molten lava) +} S_lavawall (wall of lava) l S_leprechaun (leprechaun) \(ha S_level_teleporter (level teleporter) L S_lich (lich) @@ -4575,8 +6073,7 @@ s S_spider (arachnid or centipede) @ S_ss3 (magic shield 3 of 4) * S_ss4 (magic shield 4 of 4) \(ha S_statue_trap (statue trap) -\ S_stone (solid rock or unexplored terrain -\ \ \ or dark part of a room) +\ S_stone (solid rock) ] S_strange_obj (strange object) \- S_sw_bc (swallow bottom center) \\ S_sw_bl (swallow bottom left) @@ -4600,6 +6097,7 @@ T S_troll (troll) | S_trwall (wall) \- S_tuwall (wall) U S_umber (umber hulk) +\ S_unexplored (unexplored terrain) u S_unicorn (unicorn or horse) < S_upladder (ladder up) < S_upstair (staircase up) @@ -4644,12 +6142,49 @@ Statues and boulders are the rock being referred to, but since version 3.6.0, statues are displayed as the monster they depict. So S_rock is only used for boulders and not used at all if overridden by the more specific S_boulder. +.hn 2 +Customizing Map Glyph Representations Using Unicode +.pg +If your platform or terminal supports the display of UTF-8 character +sequences, you can customize your game display by assigning Unicode +codepoint values and \fIred-green-blue\fP colors to glyph +representations. The customizations can be specified for use with a symset that +has a UTF8 handler within the symbols file such as the enhanced1 set, or +individually within your nethack.rc file. +.pg +The format for defining a glyph representation is: +.SD n +.ft CR +OPTIONS=glyph:\fIglyphid\fP/\fIU+nnnn\fP/\fIR-G-B\fP +.ft +.ED .pg +The window port that is active needs to provide support for displaying +UTF-8 character sequences and explicit red-green-blue colors in order +for the glyph representation to be visible. +For example, the following line in your configuration file will cause +the glyph representation for glyphid G_pool to use Unicode codepoint +U+224B and the color represented by R-G-B value 0-0-160: +.SD n +.ft CR +OPTIONS=glyph:G_pool/U+224B/0-0-160 +.ft +.ED +The list of acceptable glyphid's can be produced by +\fBnethack \-\-dumpglyphids\fP. +Individual NetHack glyphs can be specified using the G_ prefix, +or you can use an S_ symbol for a glyphid and store the custom +representation for all NetHack glyphs that would map to that +particular symbol. +.pg +You will need to select a symset with a UTF8 handler to enable the +display of the customizations, such as the Enhanced symset. .hn 2 Configuring NetHack for Play by the Blind .pg NetHack can be set up to use only standard ASCII characters for making -maps of the dungeons. This makes the MS-DOS versions of NetHack completely +maps of the dungeons. This makes even the MS-DOS versions of NetHack +(which use special line-drawing characters by default) completely accessible to the blind who use speech and/or Braille access technologies. Players will require a good working knowledge of their screen-reader's review features, and will have to know how to navigate horizontally and @@ -4675,29 +6210,10 @@ the capability, set the environment variable NETHACK_MSGHANDLER to an executable, which will be executed with the game message as the program's only parameter. .pg -While it is not difficult for experienced users to edit the \fBdefaults.nh\fP -file to accomplish this, novices may find this task somewhat daunting. -Included within the \(lqsymbols\(rq file of all official distributions -of NetHack is a symset called \fBNHAccess\fP. -Selecting that symset in your -configuration file will cause the game to run in a manner accessible -to the blind. -After you have gained some experience with the game -and with editing files, you may want to alter settings via \fBSYMBOLS=\fP -and \fBROGUESYMBOLS=\fP -in your configuration file to better suit your preferences. -See the previous section for the special symbols S_pet_override -to force a consistent symbol for all pets and -S_hero_override to force a unique symbol for the player character -if \fBaccessibility\fP is enabled in the sysconf file. -.pg The most crucial settings to make the game more accessible are: .pg -.lp symset:NHAccess +.lp symset:plain Load a symbol set appropriate for use by blind players. -.lp roguesymset:NHAccess -Load a symbol set for the rogue level that is appropriate for -use by blind players. .lp menustyle:traditional This will assist in the interface to speech synthesizers. .lp nomenu_overlay @@ -4708,8 +6224,19 @@ If this is the case, disable the .op number_pad option and use the traditional Rogue-like commands. +.lp paranoid_confirmation:swim +Prevent walking into water or lava. +.lp accessiblemsg +Adds direction or location information to messages. +.lp spot_monsters +Shows a message when hero notices a monster; combine with accessiblemsg. +.lp mon_movement +Shows a message when hero notices a monster movement; +combine with spot_monsters and accessiblemsg. .lp autodescribe Automatically describe the terrain under the cursor when targeting. +.lp mention_map +Give feedback messages when interesting map locations change. .lp mention_walls Give feedback messages when walking towards a wall or when travel command was interrupted. @@ -4726,6 +6253,8 @@ of moving 8 units at a time. Prevent updates to the status lines at the bottom of the screen, if your screen-reader reads those lines. The same information can be seen via the \(lq#attributes\(rq command. +.lp showdamage +Give a message of damage taken and how many hit points are left. .hn 2 Global Configuration for System Administrators .pg @@ -4755,6 +6284,10 @@ escape command (!). The syntax is the same as WIZARDS. EXPLORERS\ =\ A list of users who are allowed to use the explore mode. The syntax is the same as WIZARDS. .lp +MSGHANDLER\ =\ A path and filename of executable. Whenever a message-window +message is shown, NetHack runs this program. The program will get +the message as the only parameter. +.lp MAXPLAYERS\ =\ Limit the maximum number of games that can be running at the same time. .lp @@ -4773,7 +6306,7 @@ CHECK_SAVE_UID\ =\ 0 or 1 to disable or enable, respectively, the UID (used identification number) checking for save files (to verify that the user who is restoring is the same one who saved). .pg -The following options affect the score file: +The following four options affect the score file: .pg .lp PERSMAX\ =\ Maximum number of entries for one person. @@ -4785,42 +6318,68 @@ POINTSMIN\ =\ Minimum number of points to get an entry in the score file. PERS_IS_UID\ =\ 0 or 1 to use user names or numeric userids, respectively, to identify unique people for the score file. .lp +HIDEUSAGE\ =\ 0 or 1 to control whether the help menu entry for command +line usage is shown or suppressed. +.lp MAX_STATUENAME_RANK\ =\ Maximum number of score file entries to use for random statue names (default is 10). .lp -ACCESSIBILITY\ =\ 0 or 1 to disable or enable, respectively, the ability for players -to set S_pet_override and S_hero_override symbols in their configuration file. +ACCESSIBILITY\ =\ 0 or 1 to disable or enable, respectively, the ability +for players to set S_pet_override and S_hero_override symbols in their +configuration file. .lp PORTABLE_DEVICE_PATHS\ =\ 0 or 1 Windows OS only, the game will look -for all of its external files, and write to all of its output files in one place -rather than at the standard locations. +for all of its external files, and write to all of its output files in +one place rather than at the standard locations. .lp DUMPLOGFILE\ =\ A filename where the end-of-game dumplog is saved. -Not defining this will prevent dumplog from being created. Only available -if your game is compiled with DUMPLOG. Allows the following placeholders: +Not defining this will prevent dumplog from being created. +Only available if your game is compiled with DUMPLOG. +Allows the following placeholders: +.in +4n .\" note: %M is not an entry in the table, but 'M' is the widest letter .PS %M .\" \f(CR = set font to constant-width Roman; approximation of {\tt ...} in TeX -.PL %% +.PL \f(CR%%\fP literal \(oq\f(CR%\fP\(cq -.PL %v -version (eg. \(lq\f(CR3.6.3\-0\fP\(rq) -.PL %u +.PL \f(CR%v\fP +version (eg. \(lq\f(CR5.0.0\-0\fP\(rq) +.PL \f(CR%u\fP game UID -.PL %t +.PL \f(CR%t\fP game start time, UNIX timestamp format -.PL %T +.PL \f(CR%T\fP current time, UNIX timestamp format -.PL %d +.PL \f(CR%d\fP game start time, YYYYMMDDhhmmss format -.PL %D +.PL \f(CR%D\fP current time, YYYYMMDDhhmmss format -.PL %n +.PL \f(CR%n\fP player name -.PL %N +.PL \f(CR%N\fP first character of player name .PE +.in -4n +.lp +LIVELOG\ =\ A bit-mask of types of events that should be written to +the \fIlivelog\fP file if one is present. +The sample \fIsysconf\fP file accompanying the program contains a +comment which lists the meaning of the various bits used. +Intended for server systems supporting simultaneous play by multiple +players (to be clear, each one running a separate single player game), +for displaying their game progress to observers. +Only relevant if the program was built with LIVELOG enabled. +When available, it should be left commented out on single player +installations because over time the file could grow to be extremely +large unless it is actively maintained. . +.lp +CRASHREPORTURL\ =\ If set to +\f(CRhttps://www.nethack.org/links/cr-37BETA.html\fP +and support is compiled in, brings up a browser window pre-populated with +the information needed to report a problem if the game panics or ends +up in an internally inconsistent state, or if the #bugreport command is +invoked. .hn 1 Scoring .pg @@ -4898,39 +6457,53 @@ Credits .pg The original \fIhack\fP game was modeled on the Berkeley .UX -\fIrogue\fP game. Large portions of this paper were shamelessly +\fIrogue\fP game. Large portions of this document were shamelessly cribbed from \fIA Guide to the Dungeons of Doom\fP, by Michael C. Toy and Kenneth C. R. C. Arnold. Small portions were adapted from \fIFurther Exploration of the Dungeons of Doom\fP, by Ken Arromdee. .pg -NetHack is the product of literally dozens of people's work. +NetHack is the product of literally scores of people's work. Main events in the course of the game development are described below: . .pg \fBJay Fenlason\fP wrote the original Hack, with help from -\fBKenny Woodland\fP, \fBMike Thome\fP and \fBJon Payne\fP. +\fBKenny Woodland\fP, \fBMike Thome\fP, and \fBJon Payne\fP. .pg -\fBAndries Brouwer\fP did a major re-write, transforming Hack into a -very different game, and published (at least) three versions (1.0.1, -1.0.2, and 1.0.3) for +\fBAndries Brouwer\fP did a major re-write while at +Stichting Mathematisch Centrum (now Centrum Wiskunde & Informatica), +transforming Hack into a very different game. +He published the Hack source code for use on .UX -machines to the Usenet. +systems by posting that to Usenet +newsgroup \fInet.sources\fP (later renamed \fIcomp.sources\fP) +releasing version 1.0 in December of 1984, then versions 1.0.1, 1.0.2, +and finally 1.0.3 in July of 1985. +Usenet newsgroup \fInet.games.hack\fP (later +renamed \fIrec.games.hack\fP, eventually replaced +by \fIrec.games.roguelike.nethack\fP) +was created for discussing it. .pg \fBDon G. Kneller\fP ported Hack 1.0.3 to Microsoft C and MS-DOS, producing PC HACK 1.01e, added support for DEC Rainbow graphics in version 1.03g, and went -on to produce at least four more versions (3.0, 3.2, 3.51, and 3.6). +on to produce at least four more versions (3.0, 3.2, 3.51, and 3.6; +note that these are old Hack version numbers, not contemporary NetHack ones). .pg \fBR. Black\fP ported PC HACK 3.51 to Lattice C and the Atari 520/1040ST, producing ST Hack 1.03. .pg \fBMike Stephenson\fP merged these various versions back together, -incorporating many of the added features, and produced NetHack 1.4. +incorporating many of the added features, and produced NetHack version 1.4 +in 1987. He then coordinated a cast of thousands in enhancing and debugging NetHack 1.4 and released NetHack versions 2.2 and 2.3. -.pg -Later, Mike coordinated a major rewrite of the game, heading a -team which included \fBKen Arromdee\fP, \fBJean-Christophe Collet\fP, \fBSteve -Creps\fP, \fBEric Hendrickson\fP, \fBIzchak Miller\fP, \fBJohn Rupley\fP, +Like Hack, they were released by posting their source code to Usenet where +they remained available in various archives accessible +via \fIftp\fP and \fIuucp\fP after expiring from the newsgroup. +.pg +Later, Mike coordinated a major re-write of the game, heading a +team which included \fBKen Arromdee\fP, \fBJean-Christophe Collet\fP, +\fBSteve Creps\fP, \fBEric Hendrickson\fP, \fBIzchak Miller\fP, +\fBEric S. Raymond\fP, \fBJohn Rupley\fP, \fBMike Threepoint\fP, and \fBJanet Walz\fP, to produce NetHack 3.0c. .pg NetHack 3.0 was ported to the Atari by \fBEric R. Smith\fP, to OS/2 by @@ -4945,15 +6518,28 @@ NetHack 3.0 to the Macintosh. Along with various other Dungeoneers, they continued to enhance the PC, Macintosh, and Amiga ports through the later revisions of 3.0. .pg +Version 3.0 went through ten relatively rapidly released \(lqpatch-level\(rq +revisions. +Versions at the time were known as 3.0 for the base release and variously +as \(lq3.0a\(rq through \(lq3.0j\(rq, +\(lq3.0\ patchlevel\ 1\(rq through \(lq3.0\ patchlevel\ 10\(rq, +or \(lq3.0pl1\(rq through \(lq3.0pl10\(rq +rather than 3.0.0 and 3.0.1 through 3.0.10; +the three component numbering scheme began to be used with 3.1.0. +.pg Headed by \fBMike Stephenson\fP and coordinated by \fBIzchak Miller\fP and -\fBJanet Walz\fP, the NetHack Development Team which now included \fBKen Arromdee\fP, +\fBJanet Walz\fP, the NetHack Development Team which now included +\fBKen Arromdee\fP, \fBDavid Cohrs\fP, \fBJean-Christophe Collet\fP, \fBKevin Darcy\fP, \fBMatt Day\fP, \fBTimo Hakulinen\fP, \fBSteve Linhart\fP, \fBDean Luick\fP, -\fBPat Rankin\fP, \fBEric Raymond\fP, and \fBEric Smith\fP undertook a radical -revision of 3.0. They re-structured the game's design, and re-wrote major -parts of the code. They added multiple dungeons, a new display, special +\fBPat Rankin\fP, \fBEric Raymond\fP, and \fBEric Smith\fP undertook a +radical revision of 3.0. +They re-structured the game's design, and re-wrote major +parts of the code. +They added multiple dungeons, a new display, special individual character quests, a new endgame and many other new features, and produced NetHack 3.1. +Version 3.1.0 was released in January of 1993. .pg \fBKen Lorber\fP, \fBGregg Wonderly\fP and \fBGreg Olson\fP, with help from \fBRichard Addison\fP, \fBMike Passaretti\fP, and \fBOlaf Seibert\fP, @@ -4975,34 +6561,57 @@ ported NetHack 3.1 to the Atari. \fBPat Rankin\fP, with help from \fBJoshua Delahunty\fP, was responsible for the VMS version of NetHack 3.1. \fBMichael Allison\fP ported NetHack 3.1 to Windows NT. .pg -\fBDean Luick\fP, with help from \fBDavid Cohrs\fP, developed NetHack -3.1 for X11. -\fBWarwick Allison\fP wrote a tiled version of NetHack for the Atari; -he later contributed the tiles to the NetHack Development Team and tile support was -then added to other platforms. +\fBDean Luick\fP, with help from \fBDavid Cohrs\fP, developed +NetHack 3.1 for X11. +It drew the map as text rather than graphically but +included \f(CRnh10.bdf\fP, an optionally used custom X11 font which has +tiny images in place of letters and punctuation, a precursor of tiles. +Those images don't extend to individual monster and object types, just +replacements for monster and object classes (so one custom image for all +\(lq\f(CRa\fP\(rq insects and another for all \(lq\f(CR[\fP\(rq armor and so +forth, not separate images for beetles and ants or for cloaks and boots). +.pg +\fBWarwick Allison\fP wrote a graphically displayed version of NetHack +for the Atari where the tiny pictures were described as \(lqicons\(rq and +were distinct for specific types of monsters and objects rather than just +their classes. +He contributed them to the \fBNetHack Development Team\fP which rechristened +them \(lqtiles\(rq, original usage which has subsequently been picked up +by various other games. +NetHack's tiles support was then implemented on other platforms +(initially MS-DOS but eventually Windows, Qt, and X11 too). .pg The 3.2 NetHack Development Team, comprised of \fBMichael Allison\fP, \fBKen Arromdee\fP, \fBDavid Cohrs\fP, \fBJessie Collet\fP, \fBSteve Creps\fP, \fBKevin Darcy\fP, \fBTimo Hakulinen\fP, \fBSteve Linhart\fP, \fBDean Luick\fP, \fBPat Rankin\fP, \fBEric Smith\fP, \fBMike Stephenson\fP, -\fBJanet Walz\fP, and \fBPaul Winner\fP, released version 3.2 in April of +\fBJanet Walz\fP, and \fBPaul Winner\fP, released version 3.2.0 in April of 1996. .pg -Version 3.2 marked the tenth anniversary of the formation of the development -team. In a testament to their dedication to the game, all thirteen members -of the original NetHack Development Team remained on the team at the start of work -on that release. During the interval between the release of 3.1.3 -and 3.2, one of the founding members of the NetHack Development Team, \fBDr. Izchak -Miller\fP, was diagnosed with cancer and passed away. That release of the +Version 3.2 marked the tenth anniversary of the formation of the +development team. +In a testament to their dedication to the game, all thirteen members +of the original NetHack Development Team remained on the team at the +start of work on that release. +During the interval between the release of 3.1.3 +and 3.2.0, one of the founding members of the NetHack Development Team, +\fBDr. Izchak Miller\fP, was diagnosed with cancer and passed away. +That release of the game was dedicated to him by the development and porting teams. .pg +Version 3.2 proved to be more stable than previous versions. +Many bugs were fixed, abuses eliminated, and game features tuned for +better game play. +.pg During the lifespan of NetHack 3.1 and 3.2, several enthusiasts of the game added their own modifications to the game and made these \(lqvariants\(rq publicly available: .pg \fBTom Proudfoot\fP and \fBYuval Oren\fP created NetHack++, -which was quickly renamed NetHack--. +which was quickly renamed NetHack-- +when some people incorrectly assumed that it was a conversion of the +\fIC\fP source code to \fIC++\fP. Working independently, \fBStephen White\fP wrote NetHack Plus. \fBTom Proudfoot\fP later merged NetHack Plus and his own NetHack-- to produce SLASH. @@ -5012,11 +6621,24 @@ casting system with the Wizard Patch. .pg \fBWarren Cheung\fP combined SLASH with the Wizard Patch to produce Slash'EM, and with the help of \fBKevin Hugo\fP, added more features. -Kevin later joined the -NetHack Development Team and incorporated the best of these ideas in NetHack 3.3. +Kevin later joined the NetHack Development Team and incorporated the best +of these ideas into NetHack 3.3. .pg The final update to 3.2 was the bug fix release 3.2.3, which was released simultaneously with 3.3.0 in December 1999 just in time for the Year 2000. +Because of the newer version, 3.2.3 was released as a source code patch only, +without any ready-to-play distribution for systems that usually had such. +.pg +(To anyone considering resurrecting an old version: all versions before +3.2.3 had a \fIY2K\fP bug. +The high scores file and the log file contained +dates which were formatted using a two-digit year, and 1999's year 99 was +followed by 2000's year 100. +That got written out successfully but it +unintentionally introduced an extra column in the file layout which prevented +score entries from being read back in correctly, interfering with insertion +of new high scores and with retrieval of old character names to use for +random ghost and statue names in the current game.) .pg The 3.3 NetHack Development Team, consisting of \fBMichael Allison\fP, \fBKen Arromdee\fP, @@ -5083,16 +6705,18 @@ during the tenure of 3.4.3. It was during that same period that several new variants emerged within the NetHack community. Notably sporkhack by \fBDerek S. Ray\fP, unnethack by \fBPatric Mueller\fP, nitrohack and its successors originally by \fBDaniel Thaler\fP and then by \fBAlex Smith\fP, -and Dynahack by \fBTung Nguyen\fP. Some of those variants continue to be +and Dynahack by \fBTung Nguyen\fP. +Some of those variants continue to be developed, maintained, and enjoyed by the community to this day. .pg In September 2014, an interim snapshot of the code under development was -released publicly by other parties. Since that code was a work-in-progress +released publicly by other parties. +Since that code was a work-in-progress and had not gone through the process of debugging it as a suitable release, it was decided that the version numbers present on that code snapshot would -be retired and never used in an official NetHack release. An announcement -was posted on the NetHack Development Team's official -.UR nethack.org +be retired and never used in an official NetHack release. +An announcement was posted on the NetHack Development Team's official +.UR https://www.nethack.org website to that effect, stating that there would never be a 3.4.4, 3.5, or 3.5.0 official release version. @@ -5109,9 +6733,10 @@ In early 2015, ahead of the release of 3.6.0, new members \fBSean Hunt\fP, \fBPasi Kallinen\fP, and \fBDerek S. Ray\fP joined the NetHack Development Team. .pg -Near the end of the development of 3.6.0, one of the significant inspirations for many of -the humorous and fun features found in the game, author Terry Pratchett, -passed away. NetHack 3.6.0 introduced a tribute to him. +Near the end of the development of 3.6.0, one of the significant +inspirations for many of the humorous and fun features found in the +game, author Terry Pratchett, passed away. +NetHack 3.6.0 introduced a tribute to him. .pg 3.6.0 was released in December 2015, and merged work done by the development team since the release of 3.4.3 with some of the beloved community @@ -5124,7 +6749,7 @@ various flavors and maintained the X11 interface. .pg \fBKen Lorber\fP, \fBHaoyang Wang\fP, \fBPat Rankin\fP, and \fBDean Luick\fP -maintained the port of NetHack 3.6 for Mac OSX. +maintained the port of NetHack 3.6 for MacOS. .pg \fBMichael Allison\fP, \fBDavid Cohrs\fP, \fBBart House\fP, \fBPasi Kallinen\fP, \fBAlex Kompel\fP, \fBDion Nicolaas\fP, @@ -5136,7 +6761,7 @@ hindered by limited access. \fBKevin Smolkowski\fP has updated and tested it for the most recent version of OpenVMS (V8.4 as of this writing) on Alpha and Integrity (aka Itanium aka IA64) but not VAX. .pg -\fBRay Chason\fP resurrected the msdos port for 3.6 and contributed the +\fBRay Chason\fP resurrected the MS-DOS port for 3.6 and contributed the necessary updates to the community at large. .pg In late April 2018, several hundred bug fixes for 3.6.0 and @@ -5166,81 +6791,156 @@ and a small number of bug fixes. NetHack 3.6.6 was released on March 8, 2020 containing a security fix and some bug fixes. .pg -NetHack 3.6.7 was released in February 2023 containing a security fix and +NetHack 3.6.7 was released on February 16, 2023 containing a security fix and some bug fixes. .pg +Development work for the major release to follow NetHack 3.6 began in 2015 +around the same time as NetHack 3.6.0 was being released. That development +work continued in parallel to each of the NetHack 3.6 releases from 2015 +through 2023, and continued until the end of April 2026. For the first time, +that development was shared publicly on GitHub and SourceForge as it occurred. +It was done under the label NetHack-3.7 work-in-progress (WIP), although the +version number for the next release had not yet been solidified. +.pg +Exposure of the development to the public brought many good things, and some +challenges. People were able to observe and criticize changes and new features +almost immediately, and they often did. The GitHub pull request system made +it straightforward for people to contribute directly to development. +Contributions resolved many, many bugs in the game and we thank all the +contributors. +.pg +In early 2026, with the game development getting stable enough to consider +initiating an official release, the devteam reviewed the nature and number of +changes in the game. It was clear that there was sufficient depth and +breadth to warrant a major release and version 5.0 was decided on. +That's a new major release over 3.x, without opening up any ambiguity +or confusion with existing variants that there might have been had it +been released as version 4.0. +.pg +NetHack 5.0.0 was released on May 2, 2026. +.pg +The source code for NetHack 5.0.0 was modified and modernized to be +compliant with the C99 standard. The 5.0.0 release contained over 3100 fixes, +changes, and updated features. +.pg +NetHack 5.0 was the first version to replace the lex and yacc level +and dungeon compilers of past versions, with a new Lua interpreter-based +approach to provide those elements. Lua is also used for the quest texts +in NetHack 5.0.0. The entire development team acknowledges the work +done by \fBPasi Kallinen\fP to make that happen. +.pg +At the time of the NetHack 5.0 release, the core development team, +active and erstwhile, included \fBWarwick Allison\fP, \fBMichael Allison\fP, +\fBKen Arromdee\fP, \fBDavid Cohrs\fP, \fBJessie Collet\fP, \fBBart House\fP, +\fBKevin Hugo\fP, \fBPasi Kallinen\fP, \fBKen Lorber\fP, \fBDean Luick\fP, +\fBPat Rankin\fP, \fBDerek S. Ray\fP, \fBAlex Smith\fP, \fBPatric Mueller\fP, +\fBMike Stephenson\fP, \fBJanet Walz\fP, \fBPaul Winner\fP. +.pg +\fBKen Lorber\fP, \fBPat Rankin\fP, \fBPatrick Mueller\fP and +\fBMichael Allison\fP helped ensure that NetHack 5.0 would run +on macOS. +.pg +\fBIngo Paschke\fP somehow managed to revive a NetHack 5.0 port for the Amiga, +using a cross-compiler on a modern platform to do so. His work was shared so +others can straightforwardly produce NetHack 5.0 for the Amiga thanks to his +efforts. +.pg +\fBRay Chason\fP contributed the majority of maintenance work for the +NetHack 5.0 MS-DOS port, including porting the curses interface to it. +\fBMichael Allison\fP ensured that NetHack 5.0 core changes continued to +work with the msdos port and keep it alive. Cross-compiling the MS-DOS +port has helped make that possible and mostly painless. +.pg +People that contributed to the Windows port of NetHack 5.0 since the +development of NetHack 5.0 began over eleven years ago, included +\fBMichael Allison\fP, \fBDavid Cohrs\fP, \fBBart House\fP, +\fBPasi Kallinen\fP, \fBAlex Kompel\fP, \fBDion Nicolaas\fP, +\fBDerek S. Ray\fP and \fBYitzhak Sapir\fP. +.pg +With sadness, the devteam would like to acknowledge and remember the past +contributions from the late \fBRon Van Iwaarden\fP, who was the sole maintainer +of NetHack for OS/2 for several past NetHack releases. Ron will be missed. +.pg The official NetHack web site is maintained by \fBKen Lorber\fP at .UR https://www.nethack.org/ . +.BR 1 .pg .hn 2 -SPECIAL THANKS +Special Thanks .pg On behalf of the NetHack community, thank you very much once again to \fBM. Drew Streib\fP and \fBPasi Kallinen\fP for providing a public NetHack server at nethack.alt.org. Thanks to \fBKeith Simpson\fP and \fBAndy Thomson\fP for hardfought.org. Thanks to all those unnamed dungeoneers who invest their time and effort into annual -NetHack tournaments such as Junethack, The November NetHack Tournament +NetHack tournaments such as Junethack, The November NetHack Tournament, and in days past, devnull.net (gone for now, but not forgotten). +.\" .pg +.\" .ce +.\" - - - - - - - - - -\ \ \ \ \" when centered, the dashes look a little too +.\" . \" far to right, so pad them with a few spaces +.BR 1 .pg -.ce -- - - - - - - - - -\ \ \ \ \" when centered, the dashes look a little too far -. \" to the right, so pad them with a few spaces +.hn 2 +Dungeoneers .pg From time to time, some depraved individual out there in netland sends a particularly intriguing modification to help out with the game. The NetHack Development Team sometimes makes note of the names of the worst of these miscreants in this, the list of Dungeoneers: +.BR 1 . -.TS S +.TS center; c2 c2 c. .\"TABLE_START -Adam Aronow J. Ali Harlow Mikko Juola -Alex Kompel Janet Walz Nathan Eady -Alex Smith Janne Salmijarvi Norm Meluch -Andreas Dorn Jean-Christophe Collet Olaf Seibert -Andy Church Jeff Bailey Pasi Kallinen -Andy Swanson Jochen Erwied Pat Rankin -Andy Thomson John Kallen Patric Mueller -Ari Huttunen John Rupley Paul Winner -Bart House John S. Bien Pierre Martineau -Benson I. Margulies Johnny Lee Ralf Brown -Bill Dyer Jon W{tte Ray Chason -Boudewijn Waijers Jonathan Handler Richard Addison -Bruce Cox Joshua Delahunty Richard Beigel -Bruce Holloway Karl Garrison Richard P. Hughey -Bruce Mewborne Keizo Yamamoto Rob Menke -Carl Schelin Keith Simpson Robin Bandy -Chris Russo Ken Arnold Robin Johnson -David Cohrs Ken Arromdee Roderick Schertler -David Damerell Ken Lorber Roland McGrath -David Gentzel Ken Washikita Ron Van Iwaarden -David Hairston Kevin Darcy Ronnen Miller -Dean Luick Kevin Hugo Ross Brown -Del Lamb Kevin Sitze Sascha Wostmann -Derek S. Ray Kevin Smolkowski Scott Bigham -Deron Meranda Kevin Sweet Scott R. Turner -Dion Nicolaas Lars Huttar Sean Hunt -Dylan O'Donnell Leon Arnott Stephen Spackman -Eric Backus M. Drew Streib Stefan Thielscher -Eric Hendrickson Malcolm Ryan Stephen White -Eric R. Smith Mark Gooderum Steve Creps -Eric S. Raymond Mark Modrall Steve Linhart -Erik Andersen Marvin Bressler Steve VanDevender -Fredrik Ljungdahl Matthew Day Teemu Suikki -Frederick Roeber Merlyn LeRoy Tim Lennan -Gil Neiger Michael Allison Timo Hakulinen -Greg Laskin Michael Feir Tom Almy -Greg Olson Michael Hamel Tom West -Gregg Wonderly Michael Sokolov Warren Cheung -Hao-yang Wang Mike Engber Warwick Allison -Helge Hafting Mike Gallop Yitzhak Sapir -Irina Rempt-Drijfhout Mike Passaretti -Izchak Miller Mike Stephenson +Adam Aronow Irina Rempt-Drijfhout Mike Gallop +Alex Kompel Izchak Miller Mike Passaretti +Alex Smith J. Ali Harlow Mike Stephenson +Andreas Dorn Janet Walz Mikko Juola +Andy Church Janne Salmijarvi Nathan Eady +Andy Swanson Jean-Christophe Collet Norm Meluch +Andy Thomson Jeff Bailey Olaf Seibert +Ari Huttunen Jochen Erwied Pasi Kallinen +Bart House John Kallen Pat Rankin +Benson I. Margulies John Rupley Patric Mueller +Bill Dyer John S. Bien Paul Winner +Boudewijn Waijers Johnny Lee Pierre Martineau +Bruce Cox Jon W{tte Ralf Brown +Bruce Holloway Jonathan Handler Ray Chason +Bruce Mewborne Joshua Delahunty Richard Addison +Cameron Root Karl Garrison Richard Beigel +Carl Schelin Keizo Yamamoto Richard P. Hughey +Chris Russo Keith Simpson Rob Menke +David Cohrs Ken Arnold Robin Bandy +David Damerell Ken Arromdee Robin Johnson +David Gentzel Ken Lorber Roderick Schertler +David Hairston Ken Washikita Roland McGrath +Dean Luick Kestrel Gregorich-Trevor Ron Van Iwaarden +Del Lamb Kevin Darcy Ronnen Miller +Derek S. Ray Kevin Hugo Ross Brown +Deron Meranda Kevin Sitze Sascha Wostmann +Dion Nicolaas Kevin Smolkowski Scott Bigham +Dylan O'Donnell Kevin Sweet Scott R. Turner +Eric Backus Lars Huttar Sean Hunt +Eric Hendrickson Leon Arnott Stephen Spackman +Eric R. Smith M. Drew Streib Stefan Thielscher +Eric S. Raymond Malcolm Ryan Stephen White +Erik Andersen Mark Gooderum Steve Creps +Fredrik Ljungdahl Mark Modrall Steve Linhart +Frederick Roeber Marvin Bressler Steve VanDevender +G. Branden Robinson Matthew Day Teemu Suikki +Gil Neiger Merlyn LeRoy Tim Lennan +Greg Laskin Michael Allison Timo Hakulinen +Greg Olson Michael Feir Tom Almy +Gregg Wonderly Michael Hamel Tom West +Hao-yang Wang Michael Meyer Warren Cheung +Helge Hafting Michael Sokolov Warwick Allison +Ingo Paschke Mike Engber Yitzhak Sapir .\"TABLE_END Do not delete this line. .TE +.BR 1 .pg .\"Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. .\"Lattice is a trademark of Lattice, Inc. diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex index 7d9e320e2..6f129f090 100644 --- a/doc/Guidebook.tex +++ b/doc/Guidebook.tex @@ -1,34 +1,13 @@ -\documentstyle[titlepage,longtable]{article} -% NetHack 3.6 Guidebook.tex $NHDT-Date: 1431192762 2015/12/16 17:32:42 $ $NHDT-Branch: master $:$NHDT-Revision: 1.60 $ */ -%+% we're still limping along in LaTeX 2.09 compatibility mode -%-%\documentclass{article} -%-%\usepackage{hyperref} % before longtable -%-%% if hyperref isn't available, we can get by with this instead -%-%%\RequirePackage[errorshow]{tracefnt} \DeclareSymbolFont{typewriter}{OT1}{cmtt}{m}{n} -%-%\usepackage{longtable} -\textheight 220mm -\textwidth 160mm -\oddsidemargin 0mm -\evensidemargin 0mm -\topmargin 0mm - -\newcommand{\nd}{\noindent} - -\newcommand{\tb}[1]{\tt #1 \hfill} -\newcommand{\bb}[1]{\bf #1 \hfill} -\newcommand{\ib}[1]{\it #1 \hfill} - -\newcommand{\blist}[1] -{\begin{list}{$\bullet$} - {\leftmargin 30mm \topsep 2mm \partopsep 0mm \parsep 0mm \itemsep 1mm - \labelwidth 28mm \labelsep 2mm - #1}} - -\newcommand{\elist}{\end{list}} - -% this will make \tt underscores look better, but requires that -% math subscripts will never be used in this document -\catcode`\_=12 +% NetHack 5.0 Guidebook.tex $NHDT-Date: 1770881338 2026/02/11 23:28:58 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.596 $ */ +\documentclass[titlepage]{article} +\usepackage[hidelinks]{hyperref} +\usepackage{longtable} +\usepackage{enumitem} +\usepackage[a4paper, text={160mm, 220mm}, centering]{geometry} + +\setlist[description]{leftmargin=30mm, topsep=2mm, partopsep=0mm, parsep=0mm, itemsep=1mm, labelwidth=28mm, labelsep=2mm} + +\hyphenation{CRASHREPORTURL} \begin{document} % @@ -40,12 +19,13 @@ %.mt \title{\LARGE A Guide to the Mazes of Menace:\\ -\Large Guidebook for {\it NetHack\/}} +\Large Guidebook for \textit{NetHack}} %.au \author{Original version - Eric S. Raymond\\ -(Edited and expanded for 3.6 by Mike Stephenson and others)} -\date{February 3, 2023} +(Edited and expanded for 5.0.0 by Mike Stephenson and others)} +%DO NOT REMOVE NH_DATESUB \date{Date(%B %-d, %Y)} +\date{May 2, 2026} \maketitle @@ -91,7 +71,7 @@ \section{Introduction} of your success being posted on the inn's walls getting lower and lower. %.pg -\nd In the morning you awake, collect your belongings, and +\noindent In the morning you awake, collect your belongings, and set off for the dungeon. After several days of uneventful travel, you see the ancient ruins that mark the entrance to the Mazes of Menace. It is late at night, so you make camp at the entrance @@ -103,7 +83,7 @@ \section{Introduction} \section{What is going on here?} %.pg -You have just begun a game of {\it NetHack}. Your goal is to grab as much +You have just begun a game of \textit{NetHack}. Your goal is to grab as much treasure as you can, retrieve the Amulet of Yendor, and escape the Mazes of Menace alive. @@ -113,24 +93,25 @@ \section{What is going on here?} %.pg % -\blist{} -\item[\bb{Archeologists}]% +\begin{description} +\item[Archeologists] understand dungeons pretty well; this enables them to move quickly and sneak up on the local nasties. They start equipped -with the tools for a proper scientific expedition. +with the tools for a proper scientific expedition, and are able to read +ancient languages. %.pg % -\item[\bb{Barbarians}]% +\item[Barbarians] are warriors out of the hinterland, hardened to battle. They begin their quests with naught but uncommon strength, a trusty hauberk, and a great two-handed sword. %.pg % -\item[\bb{Cavemen {\rm and} Cavewomen}] +\item[Cavemen \textrm{\textmd{and}} Cavewomen] start with exceptional strength, but unfortunately, neolithic weapons. %.pg % -\item[\bb{Healers}]% +\item[Healers] are wise in medicine and apothecary. They know the herbs and simples that can restore vitality, ease pain, anesthetize, and neutralize @@ -139,61 +120,61 @@ \section{What is going on here?} amounts of money, with which they enter the dungeon. %.pg % -\item[\bb{Knights}]% +\item[Knights] are distinguished from the common skirmisher by their devotion to the ideals of chivalry and by the surpassing excellence of their armor. %.pg % -\item[\bb{Monks}]% +\item[Monks] are ascetics, who by rigorous practice of physical and mental disciplines have become capable of fighting as effectively without weapons as with. They wear no armor but make up for it with increased mobility. %.pg % -\item[\bb{Priests {\rm and} Priestesses}]% +\item[Priests \textrm{\textmd{and}} Priestesses] are clerics militant, crusaders advancing the cause of righteousness with arms, armor, and arts thaumaturgic. Their ability to commune with deities via prayer occasionally extricates them from peril, but can also put them in it. %.pg % -\item[\bb{Rangers}]% +\item[Rangers] are most at home in the woods, and some say slightly out of place in a dungeon. They are, however, experts in archery as well as tracking and stealthy movement. %.pg % -\item[\bb{Rogues}]% +\item[Rogues] are agile and stealthy thieves, with knowledge of locks, traps, and poisons. Their advantage lies in surprise, which they employ to great advantage. %.pg % -\item[\bb{Samurai}]% +\item[Samurai] are the elite warriors of feudal Nippon. They are lightly armored and quick, and wear the % -{\it dai-sho}, two swords of the deadliest +\textit{dai-sho}, two swords of the deadliest keenness. %.pg % -\item[\bb{Tourists}]% +\item[Tourists] start out with lots of gold (suitable for shopping with), a credit card, lots of food, some maps, and an expensive camera. Most monsters don't like being photographed. %.pg % -\item[\bb{Valkyries}]% +\item[Valkyries] are hardy warrior women. Their upbringing in the harsh Northlands makes them strong, inures them to extremes of cold, and instills in them stealth and cunning. %.pg % -\item[\bb{Wizards}]% +\item[Wizards] start out with a knowledge of magic, a selection of magical items, and a particular affinity for dweomercraft. Although seemingly weak and easy to overcome at first sight, an experienced Wizard is a deadly foe. -\elist +\end{description} %.pg You may also choose the race of your character (within limits; most @@ -201,39 +182,39 @@ \section{What is going on here?} %.pg % -\blist{} -\item[\bb{Dwarves}]% +\begin{description} +\item[Dwarves] are smaller than humans or elves, but are stocky and solid individuals. Dwarves' most notable trait is their great expertise in mining and metalwork. Dwarvish armor is said to be second in quality not even to the mithril armor of the Elves. %.pg % -\item[\bb{Elves}]% +\item[Elves] are agile, quick, and perceptive; very little of what goes on will escape an Elf. The quality of Elven craftsmanship often gives them an advantage in arms and armor. %.pg % -\item[\bb{Gnomes}]% +\item[Gnomes] are smaller than but generally similar to dwarves. Gnomes are known to be expert miners, and it is known that a secret underground mine complex built by this race exists within the Mazes of Menace, filled with both riches and danger. %.pg % -\item[\bb{Humans}]% +\item[Humans] are by far the most common race of the surface world, and are thus the norm to which other races are often compared. Although they have no special abilities, they can succeed in any role. %.pg % -\item[\bb{Orcs}]% +\item[Orcs] are a cruel and barbaric race that hate every living thing (including other orcs). Above all others, Orcs hate Elves with a passion unequalled, and will go out of their way to kill one at any opportunity. The armor and weapons fashioned by the Orcs are typically of inferior quality. -\elist +\end{description} %.hn 1 \section{What do all those things on the screen mean?} @@ -243,28 +224,28 @@ \section{What do all those things on the screen mean?} it appears on the screen in front of you. %.pg -When {\it NetHack\/}'s ancestor {\it rogue\/} first appeared, its screen +When \textit{NetHack}'s ancestor \textit{rogue} first appeared, its screen orientation was almost unique among computer fantasy games. Since then, screen orientation has become the norm rather than the -exception; {\it NetHack\/} continues this fine tradition. Unlike text +exception; \textit{NetHack} continues this fine tradition. Unlike text adventure games that accept commands in pseudo-English sentences and -explain the results in words, {\it NetHack\/} commands are all one or two +explain the results in words, \textit{NetHack} commands are all one or two keystrokes and the results are displayed graphically on the screen. A minimum screen size of 24 lines by 80 columns is recommended; if the screen is larger, only a $21\times80$ section will be used for the map. %.pg -{\it NetHack\/} can even be played by blind players, with the assistance of +\textit{NetHack} can even be played by blind players, with the assistance of Braille readers or speech synthesisers. Instructions for configuring -{\it NetHack\/} for the blind are included later in this document. +\textit{NetHack} for the blind are included later in this document. %.pg -{\it NetHack\/} generates a new dungeon every time you play it; even the +\textit{NetHack} generates a new dungeon every time you play it; even the authors still find it an entertaining and exciting game despite having won several times. %.pg -{\it NetHack\/} offers a variety of display options. The options available to +\textit{NetHack} offers a variety of display options. The options available to you will vary from port to port, depending on the capabilities of your hardware and software, and whether various compile-time options were enabled when your executable was created. The three possible display @@ -278,13 +259,21 @@ \section{What do all those things on the screen mean?} use the default ASCII characters from the monochrome character display when referring to things you might see on the screen during your game. %.pg -In order to understand what is going on in {\it NetHack}, first you must -understand what {\it NetHack\/} is doing with the screen. The {\it NetHack\/} +In order to understand what is going on in \textit{NetHack}, first you must +understand what \textit{NetHack} is doing with the screen. The \textit{NetHack} screen replaces the ``You see \ldots'' descriptions of text adventure games. -Figure 1 is a sample of what a {\it NetHack\/} screen might look like. +Figure 1 is a sample of what a \textit{NetHack} screen might look like. The way the screen looks for you depends on your platform. %.BR 2 +% (Either generated by hand or else the composite of two different +% situations. Originally the character had only reached a second room +% (unchanged here) by turn 257 (now changed to 752) and was already +% Weak from hunger (now changed to just Hungry) and also lacked any of +% Tourist's starting gold. Confusion is added to include a condition.) +% +% Width is forced to match similar figure in Guidebook.mn where it is +% constrained by the margins of plain text output (Guidebook.txt). \vbox{ \begin{verbatim} The bat bites! @@ -298,32 +287,54 @@ \section{What do all those things on the screen mean?} - Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral - Dlvl:1 $:0 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:257 Weak + Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral + Dlvl:1 $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:752 Hungry Conf \end{verbatim} \begin{center} Figure 1 \end{center} } +% 3-line status includes trailing spaces to force the width to match the +% 2-line data above; unlike Guidebook.pm, we can't add a trailing comment +% to make them visible +\vbox{ +\begin{verbatim} + Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 + Neutral $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 Hungry + Dlvl:1 T:752 Conf +\end{verbatim} +\begin{center} +Figure 2 +\end{center} +} + %.hn 2 \subsection*{The status lines (bottom)} +The bottom two (or three) lines of the screen contain several cryptic +pieces of information describing your current status. +Figure 1 shows the traditional two-line status area below the map. +Figure 2 shows just the status area, when the \textit{statuslines:3} +option has been set (not all interfaces support this option). +If any status line becomes wider than the screen, you might not see all +of it due to truncation. +When the numbers grow bigger and multiple \textit{conditions} are present, +the two-line format will run out of room on the second line, but +\textit{statuslines:2} +is the default because a basic 24-line terminal isn't tall enough for +the third line. + %.pg -The bottom two lines of the screen contain several cryptic pieces of -information describing your current status. If either status line -becomes longer than the width of the screen, you might not see all of -it. Here are explanations of what the various status items mean -(though your configuration may not have all the status items listed -below): +Here are explanations of what the various status items mean: %.lp -\blist{} -\item[\bb{Rank}] -Your character's name and professional ranking (based on the -experience level, see below). +\begin{description} +\item[Title] +Your character's name and professional ranking (based on role and +\textit{experience level}, see below). %.lp -\item[\bb{Strength}] +\item[Strength] A measure of your character's strength; one of your six basic attributes. A human character's attributes can range from 3 to 18 inclusive; non-humans may exceed these limits @@ -333,112 +344,125 @@ \subsection*{The status lines (bottom)} successfully you perform physical tasks, how much damage you do in combat, and how much loot you can carry. %.lp -\item[\bb{Dexterity}] +\item[Dexterity] Dexterity affects your chances to hit in combat, to avoid traps, and do other tasks requiring agility or manipulation of objects. %.lp -\item[\bb{Constitution}] +\item[Constitution] Constitution affects your ability to recover from injuries and other strains on your stamina. When strength is low or modest, constitution also affects how much you can carry. With sufficiently high strength, the contribution to carrying capacity from your constitution no longer matters. %.lp -\item[\bb{Intelligence}] +\item[Intelligence] Intelligence affects your ability to cast spells and read spellbooks. %.lp -\item[\bb{Wisdom}] +\item[Wisdom] Wisdom comes from your practical experience (especially when dealing with magic). It affects your magical energy. %.lp -\item[\bb{Charisma}] +\item[Charisma] Charisma affects how certain creatures react toward you. In particular, it can affect the prices shopkeepers offer you. %.lp -\item[\bb{Alignment}] +\item[Alignment] % -{\it Lawful}, {\it Neutral\/} or {\it Chaotic}. Often, Lawful is -taken as good and Chaotic is evil, but legal and ethical do not always +\textit{Lawful}, \textit{Neutral} or \textit{Chaotic}. Often, Lawful is +taken as good and Chaotic as evil, but legal and ethical do not always coincide. Your alignment influences how other monsters react toward you. Monsters of a like alignment are more likely to be non-aggressive, while those of an opposing alignment are more likely to be seriously offended at your presence. %.lp -\item[\bb{Dungeon Level}] +\item[Dungeon Level] How deep you are in the dungeon. You start at level one and the number increases as you go deeper into the dungeon. Some levels are special, and are identified by a name and not a number. The Amulet of Yendor is reputed to be somewhere beneath the twentieth level. %.lp -\item[\bb{Gold}] +\item[Gold] The number of gold pieces you are openly carrying. Gold which you have concealed in containers is not counted. %.lp -\item[\bb{Hit Points}] +\item[Hit Points] Your current and maximum hit points. Hit points indicate how much damage you can take before you die. The more you get hit in a fight, the lower they get. You can regain hit points by resting, or by using certain magical items or spells. The number in parentheses is the maximum number your hit points can reach. %.lp -\item[\bb{Power}] -Spell points. This tells you how much mystic energy ({\it mana\/}) +\item[Power] +Spell points. This tells you how much mystic energy (\textit{mana}) you have available for spell casting. Again, resting will regenerate the amount available. %.lp -\item[\bb{Armor Class}] +\item[Armor Class] A measure of how effectively your armor stops blows from unfriendly creatures. The lower this number is, the more effective the armor; it is quite possible to have negative armor class. -%.lp -\item[\bb{Experience}] -Your current experience level and experience points. As you -adventure, you gain experience points. At certain experience point -totals, you gain an experience level. The more experienced you are, -the better you fight and withstand magical attacks. Many dungeons -show only your experience level here. -%.lp -\item[\bb{Time}] +See the \textit{Armor} subsection of \textit{Objects} for more information. +%.lp +\item[Experience] +Your current experience level. +If the \textit{showexp} +option is set, it will be followed by a slash and experience points. +As you adventure, you gain experience points. +At certain experience point totals, you gain an experience level. +The more experienced you are, the better you fight and withstand magical +attacks. +(By the time your level reaches double digits, the usefulness of showing +the points with it has dropped significantly. +You can use the `\texttt{O}' command to turn \textit{showexp} +off to avoid using up the limited status line space.) +%.lp +\item[Time] The number of turns elapsed so far, displayed if you have the -{\it time\/} option set. +\textit{time} option set. %.lp -\item[\bb{Status}] +\item[Status] Hunger: your current hunger status. -Values are {\it Satiated}, {\it Not~Hungry\/} (or {\it Normal\/}), -{\it Hungry}, {\it Weak}, and {\it Fainting}. +Values are \textit{Satiated}, \textit{Not~Hungry} (or \textit{Normal}), +\textit{Hungry}, \textit{Weak}, and \textit{Fainting}. %.\" not mentioned: Fainted -Not shown when {\it Normal}. +Not shown when \textit{Normal}. %.lp "" Encumbrance: an indication of how what you are carrying affects your ability to move. -Values are {\it Unencumbered}, {\it Encumbered}, {\it Stressed}, -{\it Strained}, {\it Overtaxed}, and {\it Overloaded}. -Not shown when {\it Unencumbered}. +Values are \textit{Unencumbered}, \textit{Burdened}, \textit{Stressed}, +\textit{Strained}, \textit{Overtaxed}, and \textit{Overloaded}. +Not shown when \textit{Unencumbered}. %.lp "" Fatal~conditions: -{\it Stone\/} (aka {\it Petrifying}, turning to stone), -{\it Slime\/} (turning into green slime), -{\it Strngl\/} (being strangled), -{\it FoodPois\/} (suffering from acute food poisoning), -{\it TermIll\/} (suffering from a terminal illness). +\textit{Stone} (aka \textit{Petrifying}, turning to stone), +\textit{Slime} (turning into green slime), +\textit{Strngl} (being strangled), +\textit{FoodPois} (suffering from acute food poisoning), +\textit{TermIll} (suffering from a terminal illness). %.lp "" Non-fatal~conditions: -{\it Blind\/} (can't see), {\it Deaf\/} (can't hear), -{\it Stun\/} (stunned), {\it Conf\/} (confused), {\it Hallu\/} (hallucinating). +\textit{Blind} (can't see), \textit{Deaf} (can't hear), +\textit{Stun} (stunned), \textit{Conf} (confused), \textit{Hallu} (hallucinating). %.lp "" Movement~modifiers: -{\it Lev\/} (levitating), {\it Fly\/} (flying), {\it Ride\/} (riding). +\textit{Lev} (levitating), \textit{Fly} (flying), \textit{Ride} (riding). %.lp "" Other conditions and modifiers exist, but there isn't enough room to -display them with the other status fields. The `{\tt \^{}X}' command shows -all relevant status conditions. -\elist +display them with the other status fields. +\\ +% unindented paragraph +The \texttt{\#attributes} command (default key \texttt{\textasciicircum X}) will show +all current status information in unabbreviated format. +It also shows other information which might be included on the status +lines if those had more room. + +\end{description} %.hn 2 \subsection*{The message line (top)} @@ -446,14 +470,14 @@ \subsection*{The message line (top)} %.pg The top line of the screen is reserved for messages that describe things that are impossible to represent visually. If you see a -``{\tt --More--}'' on the top line, this means that {\it NetHack\/} has +``\texttt{--More--}'' on the top line, this means that \textit{NetHack} has another message to display on the screen, but it wants to make certain that you've read the one that is there first. To read the next message, just press the space bar. %.pg To change how and what messages are shown on the message line, -see ``{\it Configuring Message Types\/}`` and the {\it verbose\/} +see ``\textit{Configuring Message Types}`` and the \textit{verbose} option. %.hn 2 @@ -467,98 +491,90 @@ \subsection*{The map (rest of the screen)} game will use default symbols. Here is a list of what the default symbols mean: -\blist{} -%.lp -\item[\tb{- {\rm and} |}] -The walls of a room, or an open door. Or a grave ({\tt |}). -%.lp -\item[\tb{.}] -The floor of a room, ice, or a doorless doorway. -%.lp -\item[\tb{\#}] -A corridor, or iron bars, or a tree, or possibly a kitchen sink (if -your dungeon has sinks), or a drawbridge. -%.lp -\item[\tb{>}] +\begin{description}[font=\mdseries\ttfamily] +\item[-] +The horizontal or corner walls of a room, or an open east/west door. +\item[|] +The vertical walls of a room, or an open north/south door, or a grave. +\item[.] +The floor of a room, or ice, or a doorless doorway, or the span of an +open drawbridge. +\item[\#] +A corridor, or iron bars, or a tree, or the portcullis of a closed +drawbridge.\\ +%.lp "" +Note: engravings in corridors also appear as \# but are shown in +a different color from normal corridor locations. +\item[>] Stairs down: a way to the next level. -%.lp -\item[\tb{<}] +\item[<] Stairs up: a way to the previous level. -%.lp -\item[\tb{+}] +\item[+] A closed door, or a spellbook containing a spell you may be able to learn. -%.lp -\item[\tb{@}] -Your character or a human. -%.lp -\item[\tb{\$}] +\item[@] +Your character or a human or an elf. +\item[\textdollar] A pile of gold. -%.lp -\item[\tb{\^}] +\item[\textasciicircum] A trap (once you have detected it). -%.lp -\item[\tb{)}] +\item[)] A weapon. -%.lp -\item[\tb{[}] +\item[{[}] A suit or piece of armor. -%.lp -\item[\tb{\%}] +\item[\%] Something edible (not necessarily healthy). -%.lp -\item[\tb{?}] +\item[?] A scroll. -%.lp -\item[\tb{/}] +\item[/] A wand. -%.lp -\item[\tb{=}] +\item[=] A ring. -%.lp -\item[\tb{!}] +\item[!] A potion. -%.lp -\item[\tb{(}] +\item[(] A useful item (pick-axe, key, lamp \ldots). -%.lp -\item[\tb{"}] +\item["] An amulet or a spider web. -%.lp -\item[\tb{*}] +\item[*] A gem or rock (possibly valuable, possibly worthless). -%.lp -\item[\tb{\`}] -A boulder or statue. -%.lp -\item[\tb{0}] +\item[\textasciigrave] +A boulder or statue or an engraving on the floor of a room.\\ +%.lp "" +Note: statues are displayed as if they were the monsters they depict +so won't appear as a \textit{grave accent} (aka \textit{back-tick}). +\item[0] An iron ball. -%.lp -\item[\tb{_}] +\item[\textunderscore] An altar, or an iron chain. -%.lp -\item[\tb{\{}] -A fountain. -%.lp -\item[\tb{\}}] -A pool of water or moat or a pool of lava. -%.lp -\item[\tb{$\backslash$}] +\item[\textbraceleft] +A fountain or a sink. +\item[\textbraceright] +A pool of water or moat or a wall of water +or a pool of lava or a wall of lava. +\item[\textbackslash] An opulent throne. -%.lp -\item[\tb{a-zA-Z {\rm \& other symbols}}] +\item[a-z \textrm{\textmd{and}}] +\item[A-HJ-Z \textrm{\textmd{and}}] +\item[@\&\textquotesingle :;] Letters and certain other symbols represent the various inhabitants -of the Mazes of Menace. Watch out, they can be nasty and vicious. +of the Mazes of Menace. +Watch out, they can be nasty and vicious. Sometimes, however, they can be helpful. -%.lp -\item[\tb{I}] -This marks the last known location of an invisible or otherwise unseen -monster. Note that the monster could have moved. -The `{\tt F}' and `{\tt m}' commands may be useful here. - -\elist +\item[I] +Rather than a specific type of monster, this marks the last known +location of an invisible or otherwise unseen monster. +Note that the monster could have moved. +The `\texttt{s}', `\texttt{F}', and `\texttt{m}' commands may be useful here. +\item[1-5] +The digits 1 through 5 may be displayed, marking unseen monsters sensed +via the \textit{Warning} attribute. +Less dangerous monsters are indicated by lower values, more dangerous by +higher values. + +\end{description} %.pg You need not memorize all these symbols; you can ask the game what any -symbol represents with the `{\tt /}' command (see the next section for +symbol represents with the `\texttt{/}' command (see the next section for more info). %.hn 1 @@ -568,23 +584,23 @@ \section{Commands} Commands can be initiated by typing one or two characters to which the command is bound to, or typing the command name in the extended commands entry. Some commands, -like ``{\tt search}'', do not require that any more information be collected -by {\it NetHack\/}. Other commands might require additional information, for +like ``\texttt{search}'', do not require that any more information be collected +by \textit{NetHack}. Other commands might require additional information, for example a direction, or an object to be used. For those commands that -require additional information, {\it NetHack\/} will present you with either +require additional information, \textit{NetHack} will present you with either a menu of choices, or with a command line prompt requesting information. Which you are presented with will depend chiefly on how you have set the -`{\it menustyle\/}' +`\textit{menustyle}' option. %.pg -For example, a common question in the form ``{\tt What do you want to +For example, a common question in the form ``\texttt{What do you want to use? [a-zA-Z\ ?*]}'', asks you to choose an object you are carrying. -Here, ``{\tt a-zA-Z}'' are the inventory letters of your possible choices. -Typing `{\tt ?}' gives you an inventory list of these items, so you can see -what each letter refers to. In this example, there is also a `{\tt *}' +Here, ``\texttt{a-zA-Z}'' are the inventory letters of your possible choices. +Typing `\texttt{?}' gives you an inventory list of these items, so you can see +what each letter refers to. In this example, there is also a `\texttt{*}' indicating that you may choose an object not on the list, if you -wanted to use something unexpected. Typing a `{\tt *}' lists your entire +wanted to use something unexpected. Typing a `\texttt{*}' lists your entire inventory, so you can see the inventory letters of every object you're carrying. Finally, if you change your mind and decide you don't want to do this command after all, you can press the `ESC' key to abort the @@ -592,50 +608,50 @@ \section{Commands} %.pg You can put a number before some commands to repeat them that many -times; for example, ``{\tt 10s}'' will search ten times. If you have the -{\it number\verb+_+pad\/} -option set, you must type `{\tt n}' to prefix a count, so the example above -would be typed ``{\tt n10s}'' instead. Commands for which counts make no +times; for example, ``\texttt{10s}'' will search ten times. If you have the +\textit{number\textunderscore pad} +option set, you must type `\texttt{n}' to prefix a count, so the example above +would be typed ``\texttt{n10s}'' instead. Commands for which counts make no sense ignore them. In addition, movement commands can be prefixed for greater control (see below). To cancel a count or a prefix, press the `ESC' key. %.pg The list of commands is rather long, but it can be read at any time -during the game through the `{\tt ?}' command, which accesses a menu of +during the game through the `\texttt{?}' command, which accesses a menu of helpful texts. Here are the default key bindings for your reference: -\blist{} +\begin{description}[font=\mdseries\ttfamily] %.lp -\item[\tb{?}] +\item[?] Help menu: display one of several help texts available. %.lp -\item[\tb{/}] -The {\tt whatis} command, to +\item[/] +The \texttt{whatis} command, to tell what a symbol represents. You may choose to specify a location or type a symbol (or even a whole word) to explain. Specifying a location is done by moving the cursor to a particular spot -on the map and then pressing one of `{\tt .}', `{\tt ,}', `{\tt ;}', -or `{\tt :}'. `{\tt .}' will explain the symbol at the chosen location, -information, then let you pick another location; -conditionally check for ``{\tt More info?}'' depending upon whether the -`{\it help\/}' +on the map and then pressing one of `\texttt{.}', `\texttt{,}', `\texttt{;}', +or `\texttt{:}'. `\texttt{.}' will explain the symbol at the chosen location, +conditionally check for ``\texttt{More info?}'' depending upon whether the +`\textit{help}' option is on, and then you will be asked to pick another location; -`{\tt ,}' will explain the symbol but skip any additional -`{\tt ;}' will skip additional info and also not bother asking -you to choose another location to examine; `{\tt :}' will show additional +`\texttt{,}' will explain the symbol but skip any additional +information, then let you pick another location; +`\texttt{;}' will skip additional info and also not bother asking +you to choose another location to examine; `\texttt{:}' will show additional info, if any, without asking for confirmation. When picking a location, -pressing the {\tt ESC} key will terminate this command, or pressing `{\tt ?}' +pressing the \texttt{ESC} key will terminate this command, or pressing `\texttt{?}' will give a brief reminder about how it works. %.lp "" If the -{\it autodescribe\/} +\textit{autodescribe} option is on, a short description of what you see at each location is -shown as you move the cursor. Typing `{\tt \#}' while picking a location will +shown as you move the cursor. Typing `\texttt{\#}' while picking a location will toggle that option on or off. The -{\it whatis\verb+_+coord\/} +\textit{whatis\textunderscore coord} option controls whether the short description includes map coordinates. %.lp "" @@ -646,21 +662,21 @@ \section{Commands} You may also request a description of nearby monsters, all monsters currently displayed, nearby objects, or all objects. The -{\it whatis\verb+_+coord\/} +\textit{whatis\textunderscore coord} option controls which format of map coordinate is included with their descriptions. %.lp -\item[\tb{\&}] +\item[\&] Tell what a command does. %.lp -\item[\tb{<}] +\item[<] Go up to the previous level (if you are on a staircase or ladder). %.lp -\item[\tb{>}] +\item[>] Go down to the next level (if you are on a staircase or ladder). %.lp -\item[\tb{[yuhjklbn]}] -Go one step in the direction indicated (see Figure 2). If you sense +\item[{[yuhjklbn]}] +Go one step in the direction indicated (see Figure 3). If you sense or remember a monster there, you will fight the monster instead. Only these one-step movement commands cause you to fight monsters; the others @@ -673,186 +689,248 @@ \section{Commands} \verb+ h- . -l + & \verb+ 4- . -6 +\\ \verb+ / | \ + & \verb+ / | \ +\\ \verb+ b j n + & \verb+ 1 2 3 +\\ - & (if {\it number\verb+_+pad\/} set) + & (if \textit{number\textunderscore pad} set) \end{tabular} \end{center} %.ed \begin{center} -Figure 2 +Figure 3 \end{center} %.lp -\item[\tb{[YUHJKLBN]}] +\item[{[YUHJKLBN]}] Go in that direction until you hit a wall or run into something. %.lp -\item[\tb{m[yuhjklbn]}] +\item[m{[yuhjklbn]}] Prefix: move without picking up objects or fighting (even if you remember a monster there).\\ %.lp "" -A few non-movement commands use the `{\tt m}' prefix to request operating -via menu (to temporarily override the -{\it menustyle:Traditional\/} +A few non-movement commands use the `\texttt{m}' prefix to request +operating via menu (to temporarily override the +\textit{menustyle:Traditional} option). -Primarily useful for `{\tt ,}' (pickup) when there is only one class of +Primarily useful for `\texttt{,}' (pickup) when there is only one class of objects present (where there won't be any ``what kinds of objects?'' prompt, -so no opportunity to answer `{\tt m}' at that prompt).\\ -%.lp "" -A few other commands (eat food, offer sacrifice, apply tinning-kit) use -the `{\tt m}' prefix to skip checking for applicable objects on the floor -and go straight to checking inventory, -or (for ``{\tt \#loot}'' to remove a saddle), -skip containers and go straight to adjacent monsters. The prefix will -make ``{\tt \#travel}'' command show a menu of interesting targets in sight. -In debug mode (aka ``wizard mode''), the `{\tt m}' prefix may also be -used with the ``{\tt \#teleport}'' and ``{\tt \#wizlevelport}'' commands. -%.lp -\item[\tb{F[yuhjklbn]}] -Prefix: fight a monster (even if you only guess one is there). +so no opportunity to answer `\texttt{m}' at that prompt). +\\ +%.lp "" +The prefix will +make ``\texttt{\#travel}'' command show a menu of interesting targets in sight. +It can also be used with the `\texttt{\textbackslash}' (known, show a +list of all discovered objects) and the `\texttt{\`{}}' (knownclass, +show a list of discovered objects in a particular class) commands to offer +a menu of several sorting alternatives (which sets a new value for the +\textit{sortdiscoveries} +option); also for ``\texttt{\#vanquished}'' and ``\texttt{\#genocided}'' commands +to offer a sorting menu. +\\ +%.lp "" +A few other commands (eat food, offer sacrifice, apply tinning-kit, +drink/quaff, dip, tip container) use +the `\texttt{m}' prefix to skip checking for applicable objects on +the floor and go straight to checking inventory, +or (for ``\texttt{\#loot}'' to remove a saddle), +skip containers and go straight to adjacent monsters. +\\ +%.lp "" +In debug mode (aka ``wizard mode''), the `\texttt{m}' prefix may also be +used with the ``\texttt{\#teleport}'' and ``\texttt{\#wizlevelport}'' commands. %.lp -\item[\tb{M[yuhjklbn]}] -Prefix: Move far, no pickup. +\item[F{[yuhjklbn]}] +Prefix: fight a monster (even if you only guess one is there). %.lp -\item[\tb{g[yuhjklbn]}] +\item[g{[yuhjklbn]}] Prefix: Move until something interesting is found. %.lp -\item[\tb{G[yuhjklbn] {\rm or} [yuhjklbn]}] -Prefix: Same as `{\tt g}', but forking of corridors is not considered +\item[G{[yuhjklbn]} \textrm{\textmd{or}} +{[yuhjklbn]}] +Prefix: Similar to `\texttt{g}', but forking of corridors is not considered interesting. -%.lp -\item[\tb{_}] +\\ +Note: \texttt{+} means holding the \texttt{} or +\texttt{} key down like \texttt{} while typing and releasing +\texttt{}, then releasing \texttt{}. \texttt{\textasciicircum } is used as +shorthand elsewhere in the Guidebook to mean the same thing. Control +characters are case-insensitive so \texttt{\textasciicircum x} and \texttt{\textasciicircum X} are the same. +%.lp +\item[M{[yuhjklbn]}] +Old versions supported `\texttt{M}' as a movement prefix which +combined the effect of `\texttt{m}' with \texttt{+}. +That is no longer supported as a prefix but similar effect can be achieved +by using \texttt{m} and \texttt{G} in combination. +\texttt{m} can also be used in combination with \texttt{g}, +\texttt{+}, or \texttt{+}. +%.lp +\item[\textunderscore] Travel to a map location via a shortest-path algorithm.\\ %.lp "" The shortest path is computed over map locations the hero knows about (e.g. seen or -previously traversed). If there is no known path, a guess is made instead. +previously traversed). +If there is no known path, a guess is made instead. Stops on most of -the same conditions as the `G' command, but without picking up -objects, similar to the `M' command. For ports with mouse +the same conditions as the `\texttt{G}' command, but without picking up +objects, so implicitly forces the `\texttt{m}' prefix. +For ports with mouse support, the command is also invoked when a mouse-click takes place on a location other than the current position. %.lp -\item[\tb{.}] +\item[.] Wait or rest, do nothing for one turn. +Precede with the `\texttt{m}' prefix +to wait for a turn even next to a hostile monster, if \textit{safe\textunderscore wait} +is on. %.lp -\item[\tb{a}] +\item[a] Apply (use) a tool (pick-axe, key, lamp \ldots).\\ %.lp "" If used on a wand, that wand will be broken, releasing its magic in the -process. Confirmation is required. +process. +Confirmation is required. %.lp -\item[\tb{A}] +\item[A] Remove one or more worn items, such as armor.\\ %.lp "" -Use `{\tt T}' (take off) to take off only one piece of armor -or `{\tt R}' (remove) to take off only one accessory. +Use `\texttt{T}' (take off) to take off only one piece of armor +or `\texttt{R}' (remove) to take off only one accessory. %.lp -\item[\tb{\^{}A}] -Redo the previous command. +\item[\textasciicircum A] +Repeat the previous command. %.lp -\item[\tb{c}] +\item[c] Close a door. %.lp -\item[\tb{C}] -Call (name) a monster, an individual object, or an object type.\\ +\item[C] +Call (name) a monster, an individual object, or a type of object.\\ %.lp "" -Same as extended command ``{\tt \#name}''. +Same as extended command ``\texttt{\#name}''. %.lp -\item[\tb{\^{}C}] +\item[\textasciicircum C] Panic button. Quit the game. %.lp -\item[\tb{d}] +\item[d] Drop something.\\ -For example {\tt d7a} --- drop seven items of object -{\it a}. +For example \texttt{d7a} --- drop seven items of object +\textit{a}. %.lp -\item[\tb{D}] +\item[D] Drop several things.\\ %.lp "" In answer to the question\\ -``{\tt What kinds of things do you want to drop? [!\%= BUCXaium]}''\\ +``\texttt{What kinds of things do you want to drop? [!\%= BUCXPaium]}''\\ you should type zero or more object symbols possibly followed by -`{\tt a}' and/or `{\tt i}' and/or `{\tt u}' and/or `{\tt m}'. +`\texttt{a}' and/or `\texttt{i}' and/or `\texttt{u}' and/or `\texttt{m}'. In addition, one or more of the bless\-ed/\-un\-curs\-ed/\-curs\-ed groups may be typed.\\ %.sd %.si -{\tt DB} --- drop all objects known to be blessed.\\ -{\tt DU} --- drop all objects known to be uncursed.\\ -{\tt DC} --- drop all objects known to be cursed.\\ -{\tt DX} --- drop all objects of unknown B/U/C status.\\ -{\tt Da} --- drop all objects, without asking for confirmation.\\ -{\tt Di} --- examine your inventory before dropping anything.\\ -{\tt Du} --- drop only unpaid objects (when in a shop).\\ -{\tt Dm} --- use a menu to pick which object(s) to drop.\\ -{\tt D\%u} --- drop only unpaid food. +\texttt{DB} --- drop all objects known to be blessed.\\ +\texttt{DU} --- drop all objects known to be uncursed.\\ +\texttt{DC} --- drop all objects known to be cursed.\\ +\texttt{DX} --- drop all objects of unknown B/U/C status.\\ +\texttt{DP} --- drop objects picked up last.\\ +\texttt{Da} --- drop all objects, without asking for confirmation.\\ +\texttt{Di} --- examine your inventory before dropping anything.\\ +\texttt{Du} --- drop only unpaid objects (when in a shop).\\ +\texttt{Dm} --- use a menu to pick which object(s) to drop.\\ +\texttt{D\%u} --- drop only unpaid food. %.ei %.ed -%.lp -\item[\tb{\^{}D}] +The last example shows a combination. +There are four categories of object filtering: class (`\texttt{!}' for +potions, `\texttt{?}' for scrolls, and so on), shop status (`\texttt{u}' for +unpaid, in other words, owned by the shop), bless/curse state +(`\texttt{B}', `\texttt{U}', `\texttt{C}', and `\texttt{X}' as shown above), +and novelty (`\texttt{P}', recently picked up items; controlled by picking +up or dropping things rather than by any time factor). +%.lp "" +\\ +If you specify more than one value in a category (such as ``\texttt{!?}'' for +potions and scrolls or ``\texttt{BU}'' for blessed and uncursed), an inventory +object will meet the criteria if it matches any of the specified +values (so ``\texttt{!?}'' means `\texttt{!}' or `\texttt{?}'). +If you specify more than one category, an inventory object must meet +each of the category criteria (so ``\texttt{\%u}'' means class `\texttt{\%}' and +unpaid `\texttt{u}'). +Lastly, you may specify multiple values within multiple categories: +``\texttt{!?BU}'' will select all potions and scrolls which are known to be +blessed or uncursed. +(In versions prior to 3.6, filter combinations behaved differently.) +%.lp +\item[\textasciicircum D] Kick something (usually a door). %.lp -\item[\tb{e}] +\item[e] Eat food.\\ %.lp "" Normally checks for edible item(s) on the floor, then if none are found or none are chosen, checks for edible item(s) in inventory. -Precede `{\tt e}' with the `{\tt m}' prefix to bypass attempting to eat +Precede `\texttt{e}' with the `\texttt{m}' prefix to bypass attempting to eat anything off the floor.\\ %.lp "" If you attempt to eat while already satiated, you might choke to death. If you risk it, you will be asked whether -to ``continue eating?'' {\it if you survive the first bite\/}. +to ``continue eating?'' \textit{if you survive the first bite}. You can set the -{\it paranoid\verb+_+confirmation:eating\/} -option to require a response of ``{\tt yes}'' instead of just `{\tt y}'. +\textit{paranoid\textunderscore confirmation:eating} +option to require a response of ``\texttt{yes}'' instead of just `\texttt{y}'. %.lp % Make sure Elbereth is not hyphenated below, the exact spelling matters. -% (Only specified here to parallel Guidebook.mn; use of \tt font implicity +% (Only specified here to parallel Guidebook.mn; use of \tt font implicitly % prevents automatic hyphenation in TeX and LaTeX.) \hyphenation{Elbereth} %override the deduced syllable breaks -\item[\tb{E}] +\item[E] Engrave a message on the floor.\\ %.sd %.si -{\tt E-} --- write in the dust with your fingers.\\ +\texttt{E-} --- write in the dust with your fingers.\\ %.ei %.ed %.lp "" -Engraving the word ``{\tt Elbereth}'' will cause most monsters to not attack +Engraving the word ``\texttt{Elbereth}'' will cause most monsters to not attack you hand-to-hand (but if you attack, you will rub it out); this is often useful to give yourself a breather. %.lp -\item[\tb{f}] +\item[f] Fire (shoot or throw) one of the objects placed in your quiver (or quiver sack, or that you have at the ready). -You may select ammunition with a previous `{\tt Q}' command, or let the -computer pick something appropriate if {\it autoquiver\/} is true.\\ +You may select ammunition with a previous `\texttt{Q}' command, or let the +computer pick something appropriate if \textit{autoquiver} is true. +If your wielded weapon has the throw-and-return property, your quiver +is empty, and \textit{autoquiver} +is false, you will throw that wielded weapon instead of filling the quiver. +This will also automatically use a polearm if wielded. +If \textit{fireassist} is true, firing will automatically try to wield a launcher +(for example, a bow or a sling) matching the ammo in the quiver; this might +take multiple turns, and get interrupted by a monster. +Remember to swap back to your main melee weapon afterwards. %.lp "" -See also `{\tt t}' (throw) for more general throwing and shooting. +\\ +See also `\texttt{t}' (throw) for more general throwing and shooting. %.lp -\item[\tb{i}] +\item[i] List your inventory (everything you're carrying). %.lp -\item[\tb{I}] +\item[I] List selected parts of your inventory, usually be specifying the character -for a particular set of objects, like `{\tt [}' for armor or `{\tt !}' +for a particular set of objects, like `\texttt{[}' for armor or `\texttt{!}' for potions.\\ %.sd %.si -{\tt I*} --- list all gems in inventory;\\ -{\tt Iu} --- list all unpaid items;\\ -{\tt Ix} --- list all used up items that are on your shopping bill;\\ -{\tt IB} --- list all items known to be blessed;\\ -{\tt IU} --- list all items known to be uncursed;\\ -{\tt IC} --- list all items known to be cursed;\\ -{\tt IX} --- list all items whose bless/curse status is unknown;\\ -{\tt I\$} --- count your money. +\texttt{I*} --- list all gems in inventory;\\ +\texttt{Iu} --- list all unpaid items;\\ +\texttt{Ix} --- list all used up items that are on your shopping bill;\\ +\texttt{IB} --- list all items known to be blessed;\\ +\texttt{IU} --- list all items known to be uncursed;\\ +\texttt{IC} --- list all items known to be cursed;\\ +\texttt{IX} --- list all items whose bless/curse status is unknown;\\ +\texttt{IP} --- list items picked up last;\\ +\texttt{I\$} --- count your money. %.ei %.ed %.lp -\item[\tb{o}] +\item[o] Open a door. %.lp -\item[\tb{O}] +\item[O] Set options.\\ %.lp "" A menu showing the current option values will be @@ -862,78 +940,85 @@ \section{Commands} a further menu or prompt will appear once you've closed this menu. The available options are listed later in this Guidebook. Options are usually set before the -game rather than with the `{\tt O}' command; see the section on options below. +game rather than with the `\texttt{O}' command; see the section on options below. +Precede \texttt{O} with the \texttt{m} prefix to show advanced options. %.lp -\item[\tb{\^{}O}] +\item[\textasciicircum O] Show overview.\\ %.lp "" -Shortcut for the ``{\tt \#overview}'': +Shortcut for ``\texttt{\#overview}'': list interesting dungeon levels visited.\\ %.lp "" -(Prior to 3.6.0, `{\tt \^{}O}' was a debug mode command which listed +(Prior to 3.6.0, `\texttt{\textasciicircum O}' was a debug mode command which listed the placement of all special levels. -Use ``{\tt \#wizwhere}'' to run that command.) +Use ``\texttt{\#wizwhere}'' to run that command.) %.lp -\item[\tb{p}] +\item[p] Pay your shopping bill. %.lp -\item[\tb{P}] -Put on an accessory (ring, amulet, blindfold).\\ +\item[P] +Put on an accessory (ring, amulet, or blindfold).\\ %.lp "" This command may also be used to wear armor. The prompt for which inventory item to use will only list accessories, but choosing an unlisted item of armor will attempt to wear it. -(See the `{\tt W}' command below. It lists armor as the inventory +(See the `\texttt{W}' command below. It lists armor as the inventory choices but will accept an accessory and attempt to put that on.) %.lp -\item[\tb{\^{}P}] +\item[\textasciicircum P] Repeat previous message.\\ %.lp "" -Subsequent {\tt \^{}P}'s repeat earlier messages. +Subsequent \texttt{\textasciicircum P}'s repeat earlier messages. For some interfaces, the behavior can be varied via the -{\it msg\verb+_+window\/} option. +\textit{msg\textunderscore window} option. %.lp -\item[\tb{q}] -Quaff (drink) something (potion, water, etc). -%.lp -\item[\tb{Q}] +\item[q] +Quaff (drink) something (potion, water, etc).\\ +%.lp "" +When there is a fountain or sink present, it asks whether to drink +from that. +If that is declined, then it offers a chance to choose a potion from +inventory. +Precede \texttt{q} with the \texttt{m} prefix to skip asking about +drinking from a fountain or sink. +%.lp +\item[Q] Select an object for your quiver, quiver sack, or just generally at the ready (only one of these is available at a time). You can then throw -this (or one of these) using -the `f' command.\\ -%.lp "" -(In versions prior to 3.3 this was the command to quit -the game, which has been moved to ``{\tt \#quit}''.) +this (or one of these) using the `\texttt{f}' command. %.lp -\item[\tb{r}] +\item[r] Read a scroll or spellbook. %.lp -\item[\tb{R}] +\item[R] Remove a worn accessory (ring, amulet, or blindfold).\\ %.lp "" If you're wearing more than one, you'll be prompted for which one to remove. When you're only wearing one, then by default it will be removed without asking, but you can set the -{\it paranoid\verb+_+confirmation\/} +\textit{paranoid\textunderscore confirmation:Remove} option to require a prompt.\\ %.lp "" This command may also be used to take off armor. The prompt for which inventory item to remove only lists worn accessories, but an item of worn armor can be chosen. -(See the `{\tt T}' command below. It lists armor as the inventory +(See the `\texttt{T}' command below. It lists armor as the inventory choices but will accept an accessory and attempt to remove it.) %.lp -\item[\tb{\^{}R}] +\item[\textasciicircum R] Redraw the screen. %.lp -\item[\tb{s}] +\item[s] Search for secret doors and traps around you. -It usually takes several tries to find something.\\ +It usually takes several tries to find something. +Precede with the `\texttt{m}' prefix to wait for a turn +even next to a hostile monster, if \textit{safe\textunderscore wait} +is on.\\ %.lp "" Can also be used to figure out whether there is still a monster at an adjacent ``remembered, unseen monster'' marker. %.lp -\item[\tb{S}] +\item[S] Save the game (which suspends play and exits the program). The saved game will be restored automatically the next time you play using the same character name.\\ @@ -948,7 +1033,7 @@ \section{Commands} There is no ``save current game state and keep playing'' command, not even in explore mode where saved game files can be kept and re-used. %.lp -\item[\tb{t}] +\item[t] Throw an object or shoot a projectile.\\ %.lp "" There's no separate ``shoot'' command. @@ -957,10 +1042,10 @@ \section{Commands} If you ``throw'' an arrow while not wielding a bow, you are throwing it by hand and it will generally be less effective than when shot.\\ %.lp "" -See also `{\tt f}' (fire) for throwing or shooting an item pre-selected -via the `{\tt Q}' (quiver) command. +See also `\texttt{f}' (fire) for throwing or shooting an item pre-selected +via the `\texttt{Q}' (quiver) command, with some extra assistance. %.lp -\item[\tb{T}] +\item[T] Take off armor.\\ %.lp "" If you're wearing more than one piece, you'll be prompted for which @@ -969,396 +1054,542 @@ \section{Commands} weren't there.) When you're only wearing one, then by default it will be taken off without asking, but you can set the -{\it paranoid\verb+_+confirmation\/} +\textit{paranoid\textunderscore confirmation:Remove} option to require a prompt.\\ %.lp "" This command may also be used to remove accessories. The prompt for which inventory item to take off only lists worn armor, but a worn accessory can be chosen. -(See the `{\tt R}' command above. It lists accessories as the inventory +(See the `\texttt{R}' command above. It lists accessories as the inventory choices but will accept an item of armor and attempt to take it off.) %.lp -\item[\tb{\^{}T}] +\item[\textasciicircum T] Teleport, if you have the ability. %.lp -\item[\tb{v}] -Display version number. +\item[v] +Display a list of significant events in the current game, also shown by +\texttt{\#chronicle}. +\\ +%.lp "" +`\texttt{v}' used to display the game's version number. +Use `\texttt{V}' for that now. + %.lp -\item[\tb{V}] -Display the game history. +\item[V] +Display version number. +\\ +%.lp "" +`\texttt{V}' used to display a summary of the game's history. +Still available via \texttt{\#history}. %.lp -\item[\tb{w}] +\item[w] Wield weapon.\\ %.sd %.si -{\tt w-} --- wield nothing, use your bare (or gloved) hands.\\ +\texttt{w-} --- wield nothing, use your bare (or gloved) hands.\\ %.ei %.ed -Some characters can wield two weapons at once; use the `{\tt X}' command -(or the ``{\tt \#twoweapon}'' extended command) to do so. +Some characters can wield two weapons at once; use the `\texttt{X}' command +(or the ``\texttt{\#twoweapon}'' extended command) to do so. %.lp -\item[\tb{W}] +\item[W] Wear armor.\\ %.lp "" This command may also be used to put on an accessory (ring, amulet, or blindfold). The prompt for which inventory item to use will only list armor, but choosing an unlisted accessory will attempt to put it on. -(See the `{\tt P}' command above. It lists accessories as the inventory +(See the `\texttt{P}' command above. It lists accessories as the inventory choices but will accept an item of armor and attempt to wear it.) %.lp -\item[\tb{x}] +\item[x] Exchange your wielded weapon with the item in your alternate weapon slot.\\ %.lp "" The latter is used as your secondary weapon when engaging in two-weapon combat. Note that if one of these slots is empty, the exchange still takes place. %.lp -\item[\tb{X}] +\item[X] Toggle two-weapon combat, if your character can do it. Also available -via the ``{\tt \#twoweapon}'' extended command.\\ +via the ``\texttt{\#twoweapon}'' extended command.\\ %.lp "" -(In versions prior to 3.6 this was the command to switch from normal +(In versions prior to 3.6 this keystroke ran the command to switch from normal play to ``explore mode'', also known as ``discovery mode'', which has now -been moved to ``{\tt \#exploremode}''.) +been moved to ``\texttt{\#exploremode}'' and \texttt{M-X}.) %.lp -\item[\tb{\^{}X}] +\item[\textasciicircum X] Display basic information about your character.\\ %.lp "" Displays name, role, race, gender (unless role name makes that -redundant, such as {\tt Caveman} or {\tt Priestess}), and alignment, +redundant, such as \texttt{Caveman} or \texttt{Priestess}), and alignment, along with your patron deity and his or her opposition. It also shows most of the various items of information from the status line(s) in a less terse form, including several additional things which don't appear in the normal status display due to space considerations.\\ %.lp "" -In normal play, that's all that `{\tt \^{}X}' displays. +In normal play, that's all that `\texttt{\textasciicircum X}' displays. In explore mode, the role and status feedback is augmented by the -information provided by {\it enlightenment\/} magic. +information provided by \textit{enlightenment} magic. %.lp -\item[\tb{z}] +\item[z] Zap a wand.\\ %.sd %.si -{\tt z.} --- to aim at yourself, use `{\tt .}' for the direction. +\texttt{z.} --- to aim at yourself, use `\texttt{.}' for the direction. %.ei %.ed %.lp -\item[\tb{Z}] +\item[Z] Zap (cast) a spell.\\ %.sd %.si -{\tt Z.} --- to aim at yourself, use `{\tt .}' for the direction. +\texttt{Z.} --- to cast at yourself, use `\texttt{.}' for the direction. %.ei %.ed %.lp -\item[\tb{\^{}Z}] +\item[\textasciicircum Z] Suspend the game (UNIX versions with job control only). +See ``\#suspend'' below for more details. %.lp -\item[\tb{:}] +\item[:] Look at what is here. %.lp -\item[\tb{;}] +\item[;] Show what type of thing a visible symbol corresponds to. %.lp -\item[\tb{,}] -Pick up some things.\\ +\item[,] +Pick up some things from the floor beneath you.\\ %.lp "" -May be preceded by `{\tt m}' to force a selection menu. +May be preceded by `\texttt{m}' to force a selection menu. %.lp -\item[\tb{@}] -Toggle the {\it autopickup\/} option on and off. +\item[@] +Toggle the \textit{autopickup} option on and off. %.lp -\item[\tb{\^{}}] +\item[\textasciicircum] Ask for the type of an adjacent trap you found earlier. %.lp -\item[\tb{)}] +\item[)] Tell what weapon you are wielding. %.lp -\item[\tb{[}] +\item[{]}] Tell what armor you are wearing. %.lp -\item[\tb{=}] +\item[=] Tell what rings you are wearing. %.lp -\item[\tb{"}] +\item["] Tell what amulet you are wearing. %.lp -\item[\tb{(}] +\item[(] Tell what tools you are using. %.lp -\item[\tb{*}] +\item[*] Tell what equipment you are using.\\ %.lp "" Combines the preceding five type-specific commands into one. %.lp -\item[\tb{\$}] -Count your gold pieces. +\item[\$] +Report the gold you're carrying, possibly shop credit and/or debt too. %.lp -\item[\tb{+}] +\item[+] List the spells you know.\\ %.lp "" Using this command, you can also rearrange the order in which your spells are listed, either by sorting the entire list or by picking one spell from the menu then picking another to swap places with it. Swapping pairs of spells changes their casting letters, -so the change lasts after the current `{\tt +}' command finishes. Sorting +so the change lasts after the current `\texttt{+}' command finishes. Sorting the whole list is temporary. To make the most recent sort order persist -beyond the current `{\tt +}' command, choose the sort option again and then +beyond the current `\texttt{+}' command, choose the sort option again and then pick ``reassign casting letters''. (Any spells learned after that will be added to the end of the list rather than be inserted into the sorted ordering.) %.lp -\item[\tb{$\backslash$}] +\item[\textbackslash] Show what types of objects have been discovered. +\\ +%.lp "" +May be preceded by `\texttt{m}' to select preferred display order. %.lp -\item[\tb{\`}] +\item[\textasciigrave] Show discovered types for one class of objects. +\\ +%.lp "" +May be preceded by `\texttt{m}' to select preferred display order. + +%.lp +\item[|] +If persistent inventory display is supported and enabled (with the +\textit{perm\textunderscore invent} +option), interact with it instead of with the map. +\\ +%.lp "" +Allows scrolling with the +menu\textunderscore first\textunderscore page, menu\textunderscore previous\textunderscore page, +menu\textunderscore next\textunderscore page, and menu\textunderscore last\textunderscore page +keys (`\texttt{\textasciicircum}', `\texttt{<}', `\texttt{>}', `\texttt{|}' by default). +Some interfaces also support menu\textunderscore shift\textunderscore left and menu\textunderscore shift\textunderscore right +keys (`\texttt{\textbraceleft}' and `\texttt{\textbraceright}' by default). +Use the \textit{Return} (aka \textit{Enter}) or \textit{Escape} key to +resume play. + %.lp -\item[\tb{!}] +\item[!] Escape to a shell. +See ``\#shell'' below for more details. +%.lp +\item[Del] +Show map without obstructions. +You can view the explored portion of the current level's map without +monsters; without monsters and objects; or without monsters, objects, +and traps.\\ +%.lp "" +The \texttt{} key is also shown as \texttt{} on some keyboards or +\texttt{} on others. +It is sometimes displayed as \texttt{\textasciicircum ?} even though that is not an actual +control character.\\ +%.lp "" +Many terminals have an option to swap the \texttt{} and \texttt{} +keys, so typing the \texttt{} key might not execute this command. +If that happens, you can use the extended command ``\texttt{\#terrain}'' instead. %.lp -\item[\tb{\#}] +\item[\#] Perform an extended command.\\ %.lp "" -As you can see, the authors of {\it NetHack\/} +As you can see, the authors of \textit{NetHack} used up all the letters, so this is a way to introduce the less frequently used commands. What extended commands are available depends on what features the game was compiled with. %.lp -\item[\tb{\#adjust}] +\item[\#adjust] Adjust inventory letters (most useful when the -{\it fixinv\/} -option is ``on''). Autocompletes. Default key is `{\tt M-a}'.\\ +\textit{fixinv} +option is ``on''). Autocompletes. Default key is `\texttt{M-a}'.\\ %.lp "" This command allows you to move an item from one particular inventory slot to another so that it has a letter which is more meaningful for you or that it will appear in a particular location when inventory listings are displayed. You can move to a currently empty slot, or if the destination is -occupied---and won't merge---the item there will swap slots with the one -being moved. -``{\tt \#adjust}'' can also be used to split a stack of objects; when +occupied---and won't merge---the +item there will swap slots with the one being moved. +``\texttt{\#adjust}'' can also be used to split a stack of objects; when choosing the item to adjust, enter a count prior to its letter.\\ %.lp "" Adjusting without a count used to collect all compatible stacks when moving to the destination. That behavior has been changed; to gather -compatible stacks, ``{\tt \#adjust}'' a stack into its own inventory slot. +compatible stacks, ``\texttt{\#adjust}'' a stack into its own inventory slot. If it has a name assigned, other stacks with the same name or with no name will merge provided that all their other attributes match. If it does not have a name, only other stacks with no name are eligible. In either case, otherwise compatible stacks with a different name -will not be merged. This contrasts with using ``{\tt \#adjust}'' to move +will not be merged. This contrasts with using ``\texttt{\#adjust}'' to move from one slot to a different slot. In that situation, moving (no count given) a compatible stack will merge if either stack has a name when the other doesn't and give that name to the result, while splitting (count given) will ignore the source stack's name when deciding whether to merge with the destination stack. %.lp -\item[\tb{\#annotate}] +\item[\#annotate] Allows you to specify one line of text to associate with the current dungeon level. All levels with annotations are displayed by the -``{\tt \#overview}'' command. Autocompletes. -Default key is `{\tt M-A}', -and also `{\tt \^{}N}' if {\it number\verb+_+pad\/} is on. +``\texttt{\#overview}'' command. Autocompletes. +Default key is `\texttt{M-A}', +and also `\texttt{\textasciicircum N}' if \textit{number\textunderscore pad} is on. +\\ +%.lp "" +Preceding \#annotate with the `\texttt{m}' prefix is the same as +\#overview with the prefix. %.lp -\item[\tb{\#apply}] +\item[\#apply] Apply (use) a tool such as a pick-axe, a key, or a lamp. -Default key is `{\tt a}'.\\ +Default key is `\texttt{a}'.\\ %.lp "" -If the tool used acts on items on the floor, using the `{\tt m}' prefix +If the tool used acts on items on the floor, using the `\texttt{m}' prefix skips those items.\\ %.lp "" If used on a wand, that wand will be broken, releasing its magic in the process. Confirmation is required. %.lp -\item[\tb{\#attributes}] -Show your attributes. Default key is `{\tt \^{}X}'. +\item[\#attributes] +Show your attributes. Default key is `\texttt{\textasciicircum X}'. %.lp -\item[\tb{\#autopickup}] -Toggle the {\it autopickup\/} option. Default key is `{\tt @}'. +\item[\#autopickup] +Toggle the \textit{autopickup} option. Default key is `\texttt{@}'. %.lp -\item[\tb{\#call}] +\item[\#bugreport] +Bring up a browser window to submit a report to the \textit{NetHack Development +Team}. +Can be disabled at the time the program is built; when enabled, +CRASHREPORTURL must be set in the system configuration file. +%.lp +\item[\#call] Call (name) a monster, or an object in inventory, on the floor, or in the discoveries list, or add an annotation for the -current level (same as ``{\tt \#annotate}''). Default key is `{\tt C}'. +current level (same as ``\texttt{\#annotate}''). Default key is `\texttt{C}'. +%.lp +\item[\#cast] +Cast a spell. Default key is `\texttt{Z}'. %.lp -\item[\tb{\#cast}] -Cast a spell. Default key is `{\tt Z}'. +\item[\#chat] +Talk to someone. Default key is `\texttt{M-c}'. %.lp -\item[\tb{\#chat}] -Talk to someone. Default key is `{\tt M-c}'. +\item[\#chronicle] +Show a list of important game events. Default key is `\texttt{v}'. %.lp -\item[\tb{\#close}] -Close a door. Default key is `{\tt c}'. +\item[\#close] +Close a door. Default key is `\texttt{c}'. %.lp -\item[\tb{\#conduct}] +\item[\#conduct] List voluntary challenges you have maintained. Autocompletes. -Default key is `{\tt M-C}'.\\ +Default key is `\texttt{M-C}'.\\ %.lp "" See the section below entitled ``Conduct'' for details. %.lp -\item[\tb{\#dip}] -Dip an object into something. Autocompletes. Default key is `{\tt M-d}'. +\item[\#debugfuzzer] +Start the fuzz tester. +Debug mode only. +%.lp +\item[\#dip] +Dip an object into something. Autocompletes. Default key is `\texttt{M-d}'.\\ +%.lp "" +The \texttt{m} prefix skips dipping into a fountain or pool if there +is one at your location. %.lp -\item[\tb{\#down}] -Go down a staircase. Default key is `{\tt >}'. +\item[\#down] +Go down a staircase. Default key is `\texttt{>}'. %.lp -\item[\tb{\#drop}] -Drop an item. Default key is `{\tt d}'. +\item[\#drop] +Drop an item. Default key is `\texttt{d}'. %.lp -\item[\tb{\#droptype}] -Drop specific item types. Default key is `{\tt D}'. +\item[\#droptype] +Drop specific item types. Default key is `\texttt{D}'. %.lp -\item[\tb{\#eat}] -Eat something. Default key is `{\tt e}'. -The `{\tt m}' prefix skips eating items on the floor. +\item[\#eat] +Eat something. Default key is `\texttt{e}'. +The `\texttt{m}' prefix skips eating items on the floor. %.lp -\item[\tb{\#engrave}] -Engrave writing on the floor. Default key is `{\tt E}'. +\item[\#engrave] +Engrave writing on the floor. Default key is `\texttt{E}'. %.lp -\item[\tb{\#enhance}] +\item[\#enhance] Advance or check weapon and spell skills. Autocompletes. -Default key is `{\tt M-e}'. +Default key is `\texttt{M-e}'. %.lp -\item[\tb{\#exploremode}] -Enter the explore mode.\\ +\item[\#exploremode] +Switch from normal play to non-scoring explore mode. +Default key is `\texttt{M-X}'.\\ %.lp "" -Requires confirmation; default response is `{\tt n}' (no). -To really switch to explore mode, respond with `{\tt y}'. +Requires confirmation; default response is `\texttt{n}' (no). +To really switch to explore mode, respond with `\texttt{y}'. You can set the -{\it paranoid\verb+_+confirmation:quit\/} -option to require a response of ``{\tt yes}'' instead. -%.lp -\item[\tb{\#fire}] -Fire ammunition from quiver. Default key is `{\tt f}'. -%.lp -\item[\tb{\#force}] -Force a lock. Autocompletes. Default key is `{\tt M-f}'. +\textit{paranoid\textunderscore confirmation:quit} +option to require a response of ``\texttt{yes}'' instead. +%.lp +\item[\#fight] +Prefix key to force fight a direction, even if you see nothing +to fight there. +Default key is `\texttt{F}', or `\texttt{-}' with +\textit{number\textunderscore pad} +%.lp +\item[\#fire] +Fire ammunition from quiver, possibly autowielding a launcher, +or hit with a wielded polearm. +Default key is `\texttt{f}'. +%.lp +\item[\#force] +Force a lock. Autocompletes. Default key is `\texttt{M-f}'. +%.lp +\item[\#genocided] +List any monster types which have been genocided. +In explore mode and debug mode it also shows types which have become +extinct. +\\ +%.lp "" +The display order is the same as is used by \texttt{\#vanquished}. +The `\texttt{m}' prefix brings up a menu of available sorting orders, and +doing that for either \texttt{\#genocided} or \texttt{\#vanquished} changes the order for both. +\\ +%.lp "" +If the sorting order is ``count high to low'' or ``count low to high'' +(which are applicable for \texttt{\#vanquished}), that will be ignored +for \texttt{\#genocided} and alphabetical will be used instead. +The menu omits those two choices when used for \texttt{\#genocide}. +\\ +%.lp "" +Autocompletes. +Default key is `\texttt{M-g}'. %.lp -\item[\tb{\#glance}] -Show what type of thing a map symbol corresponds to. Default key is `{\tt ;}'. +\item[\#glance] +Show what type of thing a map symbol corresponds to. Default key is `\texttt{;}'. %.lp -\item[\tb{\#help}] +\item[\#help] Show the help menu. -Default key is `{\tt ?}', -and also `{\tt h}' if {\it number\verb+_+pad\/} is on. -%.lp -\item[\tb{\#herecmdmenu}] -Show a menu of possible actions in your current location. +Default key is `\texttt{?}', +and also `\texttt{h}' if \textit{number\textunderscore pad} is on. +%.lp +\item[\#herecmdmenu] +Show a menu of possible actions directed at your current location. +The menu is limited to a subset of the likeliest actions, not an +exhaustive set of all possibilities. +Autocompletes.\\ +%.lp "" +If mouse support is enabled and the \textit{herecmd\textunderscore menu} +option is On, clicking on the hero (or steed when mounted) will +execute this command. %.lp -\item[\tb{\#history}] -Show long version and game history. Default key is `{\tt V}'. +\item[\#history] +Show a summary of the game's development. %.lp -\item[\tb{\#inventory}] -Show your inventory. Default key is `{\tt i}'. +\item[\#inventory] +Show your inventory. Default key is `\texttt{i}'. %.lp -\item[\tb{\#inventtype}] -Inventory specific item types. Default key is `{\tt I}'. +\item[\#inventtype] +Inventory specific item types. Default key is `\texttt{I}'. %.lp -\item[\tb{\#invoke}] -Invoke an object's special powers. Autocompletes. Default key is `{\tt M-i}'. +\item[\#invoke] +Invoke an object's special powers. Autocompletes. Default key is `\texttt{M-i}'. %.lp -\item[\tb{\#jump}] +\item[\#jump] Jump to another location. Autocompletes. -Default key is `{\tt M-j}', -and also `{\tt j}' if {\it number\verb+_+pad\/} is on. +Default key is `\texttt{M-j}', +and also `\texttt{j}' if \textit{number\textunderscore pad} is on. %.lp -\item[\tb{\#kick}] +\item[\#kick] Kick something. -Default key is `{\tt \^{}D}', -and also `{\tt k}' if {\it number\verb+_+pad\/} is on. +Default key is `\texttt{\textasciicircum D}', +and also `\texttt{k}' if \textit{number\textunderscore pad} is on. %.lp -\item[\tb{\#known}] +\item[\#known] Show what object types have been discovered. -Default key is `{\tt $\backslash$}'. +Default key is `\texttt{\textbackslash}'. +\\ +%.lp "" +The `\texttt{m}' prefix allows assigning a new value to the +\textit{sortdiscoveries} +option to control the order in which the discoveries are displayed. %.lp -\item[\tb{\#knownclass}] +\item[\#knownclass] Show discovered types for one class of objects. -Default key is `{\tt `}'. +Default key is `\texttt{`}'. +\\ +%.lp "" +The `\texttt{m}' prefix operates the same as for \texttt{\#known}. %.lp -\item[\tb{\#levelchange}] +\item[\#levelchange] Change your experience level. Autocompletes. Debug mode only. %.lp -\item[\tb{\#lightsources}] +\item[\#lightsources] Show mobile light sources. Autocompletes. Debug mode only. %.lp -\item[\tb{\#look}] -Look at what is here, under you. Default key is `{\tt :}'. +\item[\#look] +Look at what is here, under you. Default key is `\texttt{:}'. %.lp -\item[\tb{\#loot}] +\item[\#lookaround] +Describe what you can see, or remember, of your surroundings. +%.lp +\item[\#loot] Loot a box or bag on the floor beneath you, or the saddle from a steed standing next to you. Autocompletes. -Default key is `{\tt M-l}', -and also `{\tt l}' if {\it number\verb+_+pad\/} is on. -Precede with the `{\tt m}' prefix to skip containers at your location +Precede with the `\texttt{m}' prefix to skip containers at your location and go directly to removing a saddle. +Default key is `\texttt{M-l}', +and also `\texttt{l}' if \textit{number\textunderscore pad} is on. %.lp -\item[\tb{\#monster}] +\item[\#monster] Use a monster's special ability (when polymorphed into monster form). -Autocompletes. Default key is `{\tt M-m}'. +Autocompletes. Default key is `\texttt{M-m}'. %.lp -\item[\tb{\#name}] +\item[\#name] Name a monster, an individual object, or a type of object. -Same as ``{\tt \#call}''. +Same as ``\texttt{\#call}''. Autocompletes. -Default keys are `{\tt N}', `{\tt M-n}', and `{\tt M-N}'. +Default keys are `\texttt{N}', `\texttt{M-n}', and `\texttt{M-N}'. %.lp -\item[\tb{\#offer}] -Offer a sacrifice to the gods. Autocompletes. Default key is `{\tt M-o}'.\\ +\item[\#offer] +Offer a sacrifice to the gods. Autocompletes. Default key is `\texttt{M-o}'.\\ %.lp "" You'll need to find an altar to have any chance at success. Corpses of recently killed monsters are the fodder of choice. %.lp "" -The `{\tt m}' prefix skips offering any items which are on the altar.\\ -%.lp -\item[\tb{\#open}] -Open a door. Default key is `{\tt o}'. -%.lp -\item[\tb{\#options}] -Show and change option settings. Default key is `{\tt O}'. -%.lp -\item[\tb{\#overview}] -Display information you've discovered about the dungeon. Any visited -level (unless forgotten due to amnesia) with an annotation is included, +The `\texttt{m}' prefix skips offering any items which are on the altar.\\ +%.lp +\item[\#open] +Open a door. Default key is `\texttt{o}'. +%.lp +\item[\#options] +Show and change option settings. Default key is `\texttt{O}'. +Precede with the \texttt{m} prefix to show advanced options. +%.lp +\item[\#optionsfull] +Show advanced game option settings. +No default key. +Precede with the `\texttt{m}' prefix to execute the simpler options command. +(Mainly useful if you use \texttt{BINDING=O:optionsfull} to switch +`\texttt{O}' from simple options back to traditional advanced options.) +%.lp +\item[\#overview] +Display information you've discovered about the dungeon. +Any visited level +% [note: amnesia no longer causes levels to be forgotten so exclude this] +% (unless forgotten due to amnesia) +with an annotation is included, and many things (altars, thrones, fountains, and so on; extra stairs leading to another dungeon branch) trigger an automatic annotation. If dungeon overview is chosen during end-of-game disclosure, every visited -level will be included regardless of annotations. Autocompletes. -Default keys are `{\tt \^{}O}', and `{\tt M-O}'. -%.lp +level will be included regardless of annotations. +\\ +%.lp "" +Precede \#overview with the `\texttt{m}' prefix to display the dungeon +overview as a menu where you can select any visited level to add or +remove an annotation without needing to return to that level. +This will also force all visited levels to be displayed rather than just +the ``interesting'' subset. +\\ +%.lp "" +Autocompletes. +Default keys are `\texttt{\textasciicircum O}', and `\texttt{M-O}'. % DON'T PANIC! -\item[\tb{\#panic}] +%.lp +\item[\#panic] Test the panic routine. Terminates the current game. Autocompletes. Debug mode only.\\ %.lp "" -Asks for confirmation; default is `{\tt n}' (no); continue playing. -To really panic, respond with `{\tt y}'. +Asks for confirmation; default is `\texttt{n}' (no); continue playing. +To really panic, respond with `\texttt{y}'. You can set the -{\it paranoid\verb+_+confirmation:quit\/} -option to require a response of ``{\tt yes}'' instead. +\textit{paranoid\textunderscore confirmation:quit} +option to require a response of ``\texttt{yes}'' instead. +%.lp +\item[\#pay] +Pay your shopping bill. Default key is `\texttt{p}'. %.lp -\item[\tb{\#pay}] -Pay your shopping bill. Default key is `{\tt p}'. +\item[\#perminv] +If persistent inventory display is supported and enabled (with the +\textit{perm\textunderscore invent} option), interact with it instead of with the map. +You'll be prompted for menu scrolling keystrokes such +as `\texttt{>}' and `\texttt{<}'. +Press \texttt{Return} or \texttt{Escape} to resume normal play. +Default key is \texttt{|}. %.lp -\item[\tb{\#pickup}] -Pick up things at the current location. Default key is `{\tt ,}'. -The `{\tt m}' prefix forces use of a menu. +\item[\#pickup] +Pick up things at the current location. Default key is `\texttt{,}'. +The `\texttt{m}' prefix forces use of a menu. %.lp -\item[\tb{\#polyself}] +\item[\#polyself] Polymorph self. Autocompletes. Debug mode only. %.lp -\item[\tb{\#pray}] -Pray to the gods for help. Autocompletes. Default key is `{\tt M-p}'.\\ +\item[\#pray] +Pray to the gods for help. Autocompletes. Default key is `\texttt{M-p}'.\\ %.lp "" Praying too soon after receiving prior help is a bad idea. (Hint: entering the dungeon alive is treated as having received help. @@ -1366,394 +1597,603 @@ \section{Commands} Since using this command by accident can cause trouble, there is an option to make you confirm your intent before praying. It is enabled by default, and you can reset the -{\it paranoid\verb+_+confirmation\/} +\textit{paranoid\textunderscore confirmation} option to disable it. %.lp -\item[\tb{\#prevmsg}] -Show previously displayed game messages. Default key is `{\tt \^{}P}'. +\item[\#prevmsg] +Show previously displayed game messages. Default key is `\texttt{\textasciicircum P}'. %.lp -\item[\tb{\#puton}] -Put on an accessory (ring, amulet, etc). Default key is `{\tt P}'. +\item[\#puton] +Put on an accessory (ring, amulet, etc). Default key is `\texttt{P}'. %.lp -\item[\tb{\#quaff}] -Quaff (drink) something. Default key is `{\tt q}'. +\item[\#quaff] +Quaff (drink) something. Default key is `\texttt{q}'.\\ +%.lp "" +The \texttt{m} prefix skips drinking from a fountain or sink if there +is one at your location. %.lp -\item[\tb{\#quit}] -Quit the program without saving your game. Autocompletes. -Default key is `{\tt M-q}'.\\ +\item[\#quit] +Quit the program without saving your game. Autocompletes.\\ %.lp "" Since using this command by accident would throw away the current game, you are asked to confirm your intent before quitting. -Default response is `{\tt n}' (no); continue playing. -To really quit, respond with `{\tt y}'. +Default response is `\texttt{n}' (no); continue playing. +To really quit, respond with `\texttt{y}'. You can set the -{\it paranoid\verb+_+confirmation:quit\/} -option to require a response of ``{\tt yes}'' instead. +\textit{paranoid\textunderscore confirmation:quit} +option to require a response of ``\texttt{yes}'' instead. %.lp -\item[\tb{\#quiver}] -Select ammunition for quiver. Default key is `{\tt Q}'. +\item[\#quiver] +Select ammunition for quiver. Default key is `\texttt{Q}'. %.lp -\item[\tb{\#read}] -Read a scroll, a spellbook, or something else. Default key is `{\tt r}'. +\item[\#read] +Read a scroll, a spellbook, or something else. Default key is `\texttt{r}'. %.lp -\item[\tb{\#redraw}] +\item[\#redraw] Redraw the screen. -Default key is `{\tt \^{}R}', -and also `{\tt \^{}L}' if {\it number\verb+_+pad\/} is on. -%.lp -\item[\tb{\#remove}] -Remove an accessory (ring, amulet, etc). Default key is `{\tt R}'. -%.lp -\item[\tb{\#ride}] -Ride (or stop riding) a saddled creature. Autocompletes. -Default key is `{\tt M-R}'. -%.lp -\item[\tb{\#rub}] -Rub a lamp or a stone. Autocompletes. Default key is `{\tt M-r}'. -%.lp -\item[\tb{\#save}] -Save the game and exit the program. -Default key is `{\tt S}'. -%.lp -\item[\tb{\#search}] -Search for traps and secret doors around you. Default key is `{\tt s}'. +Default key is `\texttt{\textasciicircum R}', +and also `\texttt{\textasciicircum L}' if \textit{number\textunderscore pad} is on. %.lp -\item[\tb{\#seeall}] -Show all equipment in use. Default key is `{\tt *}'. +\item[\#remove] +Remove an accessory (ring, amulet, etc). Default key is `\texttt{R}'. %.lp -\item[\tb{\#seeamulet}] -Show the amulet currently worn. Default key is `{\tt "}'. +\item[\#repeat] +Repeat the previous command. +Default key is~`\texttt{\textasciicircum A}'. %.lp -\item[\tb{\#seearmor}] -Show the armor currently worn. Default key is `{\tt [}'. +\item[\#reqmenu] +Prefix key to modify the behavior or request menu from some commands. +Prevents autopickup when used with movement commands. +Default key is `\texttt{m}'. %.lp -\item[\tb{\#seegold}] -Count your gold. Default key is `{\tt \$}'. +\item[\#retravel] +Travel to a previously selected travel destination. +Default key is `\texttt{C-\textunderscore }'. +See also \texttt{\#travel}. %.lp -\item[\tb{\#seenv}] -Show seen vectors. -Autocompletes. -Debug mode only. -%.lp -\item[\tb{\#seerings}] -Show the ring(s) currently worn. Default key is `{\tt =}'. +\item[\#ride] +Ride (or stop riding) a saddled creature. Autocompletes. +Default key is `\texttt{M-R}'. +%.lp +\item[\#rub] +Rub a lamp or a stone. Autocompletes. Default key is `\texttt{M-r}'. +%.lp +\item[\#run] +Prefix key to run towards a direction. +Default key is `\texttt{G}' when +\textit{number\textunderscore pad} +is off, +`\texttt{5}' when +\textit{number\textunderscore pad} +is set to 1~or~3, +otherwise `\texttt{M-5}' when it is set to 2~or~4. +%.lp +\item[\#rush] +Prefix key to rush towards a direction. +Default key is `\texttt{g}' when +\textit{number\textunderscore pad} +is off, +`\texttt{M-5}' when +\textit{number\textunderscore pad} +is set to 1~or~3, +otherwise `\texttt{5}' when it is set to 2~or~4. +%.lp +\item[\#save] +Save the game and exit the program. +Default key is `\texttt{S}'. %.lp -\item[\tb{\#seespells}] -List and reorder known spells. Default key is `{\tt +}'. +\item[\#saveoptions] +Save configuration options to the config file. +This will overwrite the file, removing all comments, so if you have +manually edited the config file, don't use this. %.lp -\item[\tb{\#seetools}] -Show the tools currently in use. Default key is `{\tt (}'. +\item[\#search] +Search for traps and secret doors around you. Default key is `\texttt{s}'. %.lp -\item[\tb{\#seetrap}] -Show the type of an adjacent trap. Default key is `{\tt \^{}}'. +\item[\#seeall] +Show all equipment in use. Default key is `\texttt{*}'. +%.lp "" +\\ +Will display in-use items in a menu even when there is only one. %.lp -\item[\tb{\#seeweapon}] -Show the weapon currently wielded. Default key is `{\tt )}'. +\item[\#seeamulet] +Show the amulet currently worn. Default key is `\texttt{"}'. +%.lp "" +\\ +Using the `\texttt{m}' prefix will force the display of a worn +amulet in a menu rather than with just a message. %.lp -\item[\tb{\#shell}] -Do a shell escape. Default key is `{\tt !}'. +\item[\#seearmor] +Show the armor currently worn. Default key is `\texttt{[}'. +%.lp "" +\\ +Will display worn armor in a menu even when there is only thing worn. %.lp -\item[\tb{\#sit}] -Sit down. Autocompletes. Default key is `{\tt M-s}'. +\item[\#seerings] +Show the ring(s) currently worn. Default key is `\texttt{=}'. +%.lp "" +Will display worn rings in a menu if there are two (or there is +just one and is a meat ring rather than a ``real'' ring). +Use the `\texttt{m}' prefix to force a menu for one ring. %.lp -\item[\tb{\#stats}] +\item[\#seetools] +Show the tools currently in use. Default key is `\texttt{(}'. +%.lp "" +Will display the result in a message if there is one tool in use (worn +blindfold or towel or lenses, lit lamp(s) and/or candle(s), leashes +attached to pets). +Will display a menu if there are more than one or if the command is +preceded by the `\texttt{m}' prefix. +%.lp +\item[\#seeweapon] +Show the weapon currently wielded. Default key is `\texttt{)}'. +%.lp "" +If dual-wielding, a separate message about the secondary weapon will be +given. +Using the `\texttt{m}' prefix will force a menu and it will include +primary weapon, alternate weapon even when not dual-wielding, and also +whatever is currently assigned to the quiver slot. +%.lp +\item[\#shell] +Do a shell escape, switching from NetHack to a subprocess. +Can be disabled at the time the program is built. +When enabled, access for specific users can be controlled by the system +configuration file. +Use the shell command `\texttt{exit}' to return to the game. +Default key is `\texttt{!}'. +%.lp +\item[\#showgold] +Report the gold in your inventory, including gold you know about in +containers you're carrying. If you are inside a shop, report any credit +or debt you have in that shop. +Default key is `\texttt{\$}'. +%.lp +\item[\#showspells] +List and reorder known spells. +Default key is `\texttt{+}'. +%.lp +\item[\#showtrap] +Describe an adjacent trap, possibly covered by objects or a monster. +To be eligible, the trap must already be discovered. +(The ``\texttt{\#terrain}'' command can display your map with all objects and +monsters temporarily removed, making it possible to see all discovered +traps.) +Default key is `\texttt{\textasciicircum }'. +%.lp +\item[\#sit] +Sit down. Autocompletes. Default key is `\texttt{M-s}'. +%.lp +\item[\#stats] Show memory usage statistics. Autocompletes. Debug mode only. %.lp -\item[\tb{\#suspend}] -Suspend the game. Default key is `{\tt \^{}Z}'. -%.lp -\item[\tb{\#swap}] -Swap wielded and secondary weapons. Default key is `{\tt x}'. -%.lp -\item[\tb{\#takeoff}] -Take off one piece of armor. Default key is `{\tt T}'. -%.lp -\item[\tb{\#takeoffall}] -Remove all armor. Default key is `{\tt A}'. -%.lp -\item[\tb{\#teleport}] -Teleport around the level. Default key is `{\tt \^{}T}'. -%.lp -\item[\tb{\#terrain}] -Show bare map without displaying monsters, objects, or traps. +\item[\#suspend] +Suspend the game, switching from NetHack to the terminal it was started +from without performing save-and-exit. +Can be disabled at the time the program is built. +When enabled, mainly useful for \textit{tty} and \textit{curses} interfaces on +%.UX \. \" yields "UNIX." +UNIX. +Use the shell command `\texttt{fg}' to return to the game. +Default key is `\texttt{\textasciicircum Z}'. +%.lp +\item[\#swap] +Swap wielded and secondary weapons. Default key is `\texttt{x}'. +%.lp +\item[\#takeoff] +Take off one piece of armor. Default key is `\texttt{T}'. +%.lp +\item[\#takeoffall] +Remove all armor. Default key is `\texttt{A}'. +%.lp +\item[\#teleport] +Teleport around the level. Default key is `\texttt{\textasciicircum T}'. +%.lp +\item[\#terrain] +Show map without obstructions. +In normal play you can view the explored portion of the current level's +map without monsters; without monsters and objects; or without monsters, +objects, and traps.\\ +%.lp "" +If there are visible clouds of gas in view, they are treated like traps +when deciding whether to show them or the floor underneath them.\\ +%.lp "" +In explore mode, you can choose to view the full map rather than just +its explored portion. +In debug mode there are additional choices.\\ +%.lp "" Autocompletes. +Default key is `\texttt{}' or `\texttt{}' (see \textit{Del} above). %.lp -\item[\tb{\#therecmdmenu}] -Show a menu of possible actions in a location next to you. +\item[\#therecmdmenu] +Show a menu of possible actions directed at a location next to you. +The menu is limited to a subset of the likeliest actions, not an +exhaustive set of all possibilities. +Autocompletes. +%%--invoking it by mouse seems to be broken +%% \\ +%% .lp "" +%% If mouse support is enabled and the \textit{herecmd\textunderscore menu} +%% option is On, clicking on an adjacent location will execute this command. %.lp -\item[\tb{\#throw}] -Throw something. Default key is `{\tt t}'. +\item[\#throw] +Throw something. Default key is `\texttt{t}'. %.lp -\item[\tb{\#timeout}] +\item[\#timeout] Look at the timeout queue. Autocompletes. Debug mode only. %.lp -\item[\tb{\#tip}] +\item[\#tip] Tip over a container (bag or box) to pour out its contents. -Autocompletes. Default key is `{\tt M-T}'. -The `{\tt m}' prefix makes the command use a menu. +When there are containers on the floor, the game will prompt to pick one +of them or ``tip something being carried''. +\\ +%.lp "" +If the latter is chosen, there will be another prompt for which item +from inventory to tip. +The `\texttt{m}' prefix makes the command skip containers on the +floor and pick one from inventory, except for the special case of +\textit{menustyle:Traditional} +with two or more containers present; that situation will start with the +floor container menu. +\\ +%.lp "" +Autocompletes. Default key is `\texttt{M-T}'. +%.lp +\item[\#toggle] +Toggle a boolean option on or off. +Requires a parameter in parenthesis, the name of the option to toggle. +The option must be settable in-game. + +%.lp "" +For example: +%.sd +\begin{verbatim} + BIND=':toggle(price_quotes) + BIND=@:toggle(autopickup) +\end{verbatim} +%.ed + %.lp -\item[\tb{\#travel}] +\item[\#travel] Travel to a specific location on the map. -Default key is `{\tt \verb+_+}'. +Default key is `\texttt{\textunderscore }'. Using the ``request menu'' prefix shows a menu of interesting targets in sight without asking to move the cursor. -When picking a target with cursor and the {\it autodescribe\/} +When picking a target with cursor and the \textit{autodescribe} option is on, the top line will show ``(no travel path)'' if your character does not know of a path to that location. +See also \texttt{\#retravel}. %.lp -\item[\tb{\#turn}] -Turn undead away. Autocompletes. Default key is `{\tt M-t}'. +\item[\#turn] +Turn undead away. Autocompletes. Default key is `\texttt{M-t}'. %.lp -\item[\tb{\#twoweapon}] +\item[\#twoweapon] Toggle two-weapon combat on or off. Autocompletes. -Default key is `{\tt X}', -and also `{\tt M-2}' if {\it number\verb+_+pad\/} is off.\\ +Default key is `\texttt{X}', +and also `\texttt{M-2}' if \textit{number\textunderscore pad} is off.\\ %.lp "" Note that you must use suitable weapons for this type of combat, or it will be automatically turned off. %.lp -\item[\tb{\#untrap}] +\item[\#untrap] Untrap something (trap, door, or chest). -Default key is `{\tt M-u}', and `{\tt u}' if {\it number\verb+_+pad\/} is on.\\ +Default key is `\texttt{M-u}', and `\texttt{u}' if \textit{number\textunderscore pad} is on.\\ %.lp "" In some circumstances it can also be used to rescue trapped monsters. %.lp -\item[\tb{\#up}] -Go up a staircase. Default key is `{\tt <}'. +\item[\#up] +Go up a staircase. Default key is `\texttt{<}'. %.lp -\item[\tb{\#vanquished}] -List vanquished monsters. +\item[\#vanquished] +List vanquished monsters by type and count. +\\ +%.lp "" +Note that the vanquished monsters list includes all monsters killed by +traps and each other as well as by you, and omits any which got removed +from the game without being killed (perhaps by genocide, or by a mollified +shopkeeper dismissing summoned Kops) or were already corpses when placed +on the map. +\\ +%.lp "" +Using the ``request menu'' prefix prior to \#vanquished brings up +a menu of sorting orders available (provided that the vanquished monsters +list contains at least two types of monsters). +Whichever ordering is picked gets assigned to the \textit{sortvanquished} +option so is remembered for subsequent \#vanquished requests. +The \texttt{\#genocided} command shares this sorting order. +\\ +%.lp "" +During end-of-game disclosure, when asked whether to show vanquished +monsters answering `\texttt{a}' will let you choose from the sort menu. +\\ +%.lp "" Autocompletes. -Debug mode only. +Default key is `\texttt{M-V}'. %.lp -\item[\tb{\#version}] -Print compile time options for this version of {\it NetHack\/}. -Autocompletes. Default key is `{\tt M-v}'. +\item[\#version] +Print compile time options for this version of \textit{NetHack}. + +%.lp +The second paragraph lists the user interface(s) that are included. +If there are more than one, you can use the \textit{windowtype} +option in your run-time configuration file to select the one you want. + +%.lp +Autocompletes. Default key is `\texttt{M-v}'. %.lp -\item[\tb{\#versionshort}] -Show version string. Default key is `{\tt v}'. +\item[\#versionshort] +Show the program's version number, plus the date and time that the +running copy was built from sources (not the version's release date). +Default key is `\texttt{V}'. %.lp -\item[\tb{\#vision}] +\item[\#vision] Show vision array. Autocompletes. Debug mode only. %.lp -\item[\tb{\#wait}] +\item[\#wait] Rest one move while doing nothing. -Default key is `{\tt .}', and also `{\tt{ }}' if -{\it rest\verb+_+on\verb+_+space\/} is on. +Default key is `\texttt{.}', and also `{\tt{ }}' if +\textit{rest\textunderscore on\textunderscore space} is on. %.lp -\item[\tb{\#wear}] -Wear a piece of armor. Default key is `{\tt W}'. +\item[\#wear] +Wear a piece of armor. Default key is `\texttt{W}'. %.lp -\item[\tb{\#whatdoes}] -Tell what a key does. Default key is `{\tt \&}'. +\item[\#whatdoes] +Tell what a key does. Default key is `\texttt{\&}'. %.lp -\item[\tb{\#whatis}] -Show what type of thing a symbol corresponds to. Default key is `{\tt /}'. +\item[\#whatis] +Show what type of thing a symbol corresponds to. Default key is `\texttt{/}'. %.lp -\item[\tb{\#wield}] -Wield a weapon. Default key is `{\tt w}'. +\item[\#wield] +Wield a weapon. Default key is `\texttt{w}'. %.lp -\item[\tb{\#wipe}] -Wipe off your face. Autocompletes. Default key is `{\tt M-w}'. +\item[\#wipe] +Wipe off your face. Autocompletes. Default key is `\texttt{M-w}'. %.lp -\item[\tb{\#wizbury}] +\item[\#wizborn] +Show monster birth, death, genocide, and extinct statistics. +Debug mode only. +%.lp +\item[\#wizbury] Bury objects under and around you. Autocompletes. Debug mode only. %.lp -\item[\tb{\#wizdetect}] -Search for hidden things (secret doors or traps or unseen monsters) +\item[\#wizcast] +Cast any spell. +Debug mode only. +%.lp +\item[\#wizdetect] +Reveal hidden things (secret doors or traps or unseen monsters) within a modest radius. +No time elapses. Autocompletes. Debug mode only. -Default key is `{\tt \^{}E}'. +Default key is `\texttt{\textasciicircum E}'. %.lp -\item[\tb{\#wizgenesis}] +\item[\#wizgenesis] Create a monster. May be prefixed by a count to create more than one. Autocompletes. Debug mode only. -Default key is `{\tt \^{}G}'. +Default key is `\texttt{\textasciicircum G}'. %.lp -\item[\tb{\#wizidentify}] +\item[\#wizidentify] Identify all items in inventory. Autocompletes. Debug mode only. -Default key is `{\tt \^{}I}'. +Default key is `\texttt{\textasciicircum I}'. %.lp -\item[\tb{\#wizintrinsic}] +\item[\#wizintrinsic] Set one or more intrinsic attributes. Autocompletes. Debug mode only. %.lp -\item[\tb{\#wizlevelport}] +\item[\#wizkill] +Remove monsters from play by just pointing at them. +By default the hero gets credit or blame for killing the targets. +Precede this command with the `\texttt{m}' prefix to override that. +Autocompletes. +Debug mode only. +%.lp +\item[\#wizlevelport] Teleport to another level. Autocompletes. Debug mode only. -Default key is `{\tt \^{}V}'. +Default key is `\texttt{\textasciicircum V}'. %.lp -\item[\tb{\#wizmap}] +\item[\#wizmap] Map the level. Autocompletes. Debug mode only. -Default key is `{\tt \^{}F}'. +Default key is `\texttt{\textasciicircum F}'. +%.lp +\item[\#wizrumorcheck] +Verify rumor boundaries by displaying first and last true rumors and +first and last false rumors.\\ +%.lp "" +Also displays first, second, and last random engravings, epitaphs, +and hallucinatory monsters.\\ +%.lp "" +Autocompletes. +Debug mode only. %.lp -\item[\tb{\#wizrumorcheck}] -Verify rumor boundaries. +\item[\#wizseenv] +Show map locations' seen vectors. Autocompletes. Debug mode only. %.lp -\item[\tb{\#wizsmell}] +\item[\#wizsmell] Smell monster. Autocompletes. Debug mode only. %.lp -\item[\tb{\#wizwhere}] +\item[\#wizwhere] Show locations of special levels. Autocompletes. Debug mode only. %.lp -\item[\tb{\#wizwish}] +\item[\#wizwish] Wish for something. Autocompletes. Debug mode only. -Default key is `{\tt \^{}W}'. +Default key is `\texttt{\textasciicircum W}'. +Precede this command with the `\texttt{m}' prefix to show a wish history menu. %.lp -\item[\tb{\#wmode}] +\item[\#wmode] Show wall modes. Autocompletes. Debug mode only. %.lp -\item[\tb{\#zap}] -Zap a wand. Default key is `{\tt z}'. +\item[\#zap] +Zap a wand. Default key is `\texttt{z}'. %.lp -\item[\tb{\#?}] +\item[\#?] Help menu: get the list of available extended commands. -\elist +\end{description} %.pg -\nd If your keyboard has a meta key (which, when pressed in combination +\noindent If your keyboard has a meta key (which, when pressed in combination with another key, modifies it by setting the `meta' [8th, or `high'] bit), you can invoke many extended commands by meta-ing the first letter of the command. -In {\it NT, OS/2, PC\/ {\rm and} ST NetHack}, -the `Alt' key can be used in this fashion; -on the {\it Amiga}, set the {\it altmeta\/} option to get this behavior. + +On \textit{Windows} and \textit{MS-DOS}, +the `Alt' key can be used in this fashion. On other systems, if typing `Alt' plus another key transmits a -two character sequence consisting of an {\tt Escape} -followed by the other key, you may set the {\it altmeta\/} -option to have {\it NetHack\/} combine them into meta\+key. -\blist{} +two character sequence consisting of an \texttt{Escape} +followed by the other key, you may set the \textit{altmeta} +option to have \textit{NetHack} combine them into \texttt{meta+}. +(This combining action only takes place when NetHack is expecting a +command to execute, not when accepting input to name something or to +make a wish.) + +%.pg +Unlike control characters, where \texttt{\textasciicircum x} and \texttt{\textasciicircum X} denote the same +thing, meta characters are case-sensitive: \texttt{M-x} and \texttt{M-X} +represent different things. Some commands which can be run via a meta +character require that the letter be capitalized because the lower-case +equivalent is used for another command, so the three key combination +\texttt{meta+Shift+letter} is needed. + +%.BR 1 +\begin{description}[font=\mdseries\ttfamily] %.lp -\item[\tb{M-?}] +\item[M-?] {\tt\#?} (not supported by all platforms) %.lp -\item[\tb{M-2}] -{\tt\#twoweapon} (unless the {\it number\verb+_+pad\/} option is enabled) +\item[M-2] +{\tt\#twoweapon} (unless the \textit{number\textunderscore pad} option is enabled) %.lp -\item[\tb{M-a}] +\item[M-a] {\tt\#adjust} %.lp -\item[\tb{M-A}] +\item[M-A] {\tt\#annotate} %.lp -\item[\tb{M-c}] +\item[M-c] {\tt\#chat} %.lp -\item[\tb{M-C}] +\item[M-C] {\tt\#conduct} %.lp -\item[\tb{M-d}] +\item[M-d] {\tt\#dip} %.lp -\item[\tb{M-e}] +\item[M-e] {\tt\#enhance} %.lp -\item[\tb{M-f}] +\item[M-f] {\tt\#force} %.lp -\item[\tb{M-i}] +\item[M-g] +{\tt\#genocided} +%.lp +\item[M-i] {\tt\#invoke} %.lp -\item[\tb{M-j}] +\item[M-j] {\tt\#jump} %.lp -\item[\tb{M-l}] +\item[M-l] {\tt\#loot} %.lp -\item[\tb{M-m}] +\item[M-m] {\tt\#monster} %.lp -\item[\tb{M-n}] +\item[M-n] {\tt\#name} %.lp -\item[\tb{M-o}] +\item[M-o] {\tt\#offer} %.lp -\item[\tb{M-O}] +\item[M-O] {\tt\#overview} %.lp -\item[\tb{M-p}] +\item[M-p] {\tt\#pray} %.Ip -\item[\tb{M-q}] -{\tt\#quit} -%.lp -\item[\tb{M-r}] +\item[M-r] {\tt\#rub} %.lp -\item[\tb{M-R}] +\item[M-R] {\tt\#ride} %.lp -\item[\tb{M-s}] +\item[M-s] {\tt\#sit} %.lp -\item[\tb{M-t}] +\item[M-t] {\tt\#turn} %.lp -\item[\tb{M-T}] +\item[M-T] {\tt\#tip} %.lp -\item[\tb{M-u}] +\item[M-u] {\tt\#untrap} %.lp -\item[\tb{M-v}] +\item[M-v] {\tt\#version} %.lp -\item[\tb{M-w}] +\item[M-V] +{\tt\#vanquished} +%.lp +\item[M-w] {\tt\#wipe} -\elist +%.lp +\item[M-X] +{\tt\#exploremode} +\end{description} %.pg -\nd If the {\it number\verb+_+pad\/} option is on, some additional letter commands +\noindent If the \textit{number\textunderscore pad} option is on, some additional letter commands are available: -\blist{} +\begin{description}[font=\mdseries\ttfamily] %.lp -\item[\tb{h}] +\item[h] {\tt\#help} %.lp -\item[\tb{j}] +\item[j] {\tt\#jump} %.lp -\item[\tb{k}] +\item[k] {\tt\#kick} %.lp -\item[\tb{l}] +\item[l] {\tt\#loot} %.lp -\item[\tb{N}] +\item[N] {\tt\#name} %.lp -\item[\tb{u}] +\item[u] {\tt\#untrap} -\elist +\end{description} + +%.BR 1 \"blank line for extra separation; plain text output looks better %.hn 1 \section{Rooms and corridors} @@ -1765,62 +2205,166 @@ \section{Rooms and corridors} Walls and corridors remain on the map as you explore them. %.pg -Secret corridors are hidden. You can find them with the `{\tt s}' (search) -command. +Secret corridors are hidden and appear to be solid rock. +You can find them with the `\texttt{s}' (search) command when adjacent +to them. +Multiple search attempts may be needed. +When searching is successful, secret corridors become ordinary open +corridor locations. +Mapping magic reveals secret corridors, so converts them into ordinary +corridors and shows them as such. %.hn 2 \subsection*{Doorways} %.pg -Doorways connect rooms and corridors. Some doorways have no doors; -you can walk right through. Others have doors in them, which may be -open, closed, or locked. To open a closed door, use the `{\tt o}' (open) -command; to close it again, use the `{\tt c}' (close) command. - -%.pg -You can get through a locked door by using a tool to pick the lock -with the `{\tt a}' (apply) command, or by kicking it open with the -`{\tt \^{}D}' (kick) command. +Doorways connect rooms and corridors. +Some doorways have no doors; you can walk right through. +Others have doors in them, which may be open, closed, or locked. +To open a closed door, use the `\texttt{o}' (open) +command; to close it again, use the `\texttt{c}' (close) command. +By default the +\textit{autoopen} +option is enabled, so simply attempting to walk onto a closed door's +location will attempt to open it without needing `\texttt{o}'. +Opening via +\textit{autoopen} +will not work if you are \textit{confused} or \textit{stunned} or suffer from +the \textit{fumbling} attribute. %.pg Open doors cannot be entered diagonally; you must approach them -straight on, horizontally or vertically. Doorways without doors are -not restricted in this fashion. - -%.pg -Doors can be useful for shutting out monsters. Most monsters cannot -open doors, although a few don't need to (for example, ghosts can walk through -doors). - -%.pg -Secret doors are hidden. You can find them with the `{\tt s}' (search) -command. Once found they are in all ways equivalent to normal doors. +straight on, horizontally or vertically. +Doorways without doors are +not restricted in this fashion except on one particular level +%.\" the rogue level +(described by ``\texttt{\#overview}'' as ``a primitive area''). + +%.pg +Unlocking magic exists but usually won't be available early on. +You can get through a locked door without magic by first using an +unlocking tool with the `\texttt{a}' (apply) command, and then opening it. +By default the +\textit{autounlock} +option is also enabled, so if you attempt to open (via `\texttt{o}' or +\textit{autoopen}) +a locked door while carrying an unlocking tool, you'll be asked whether +to use it on the door's lock. +Alternatively, you can break a closed door (whether locked or not) down +by kicking it via the ``\texttt{\textasciicircum D}'' (kick) command. +Kicking down a door destroys it and makes a lot of noise which might +wake sleeping monsters. + +%.pg +Some closed doors are booby-trapped and will explode if an attempt is made +to open (when unlocked) or unlock (when locked) or kick down. +Like kicking, an explosion destroys the door and makes a lot of noise. +The ``\texttt{\#untrap}'' command can be used to search a door for traps but +might take multiple attempts to find one. +When one is found, you'll be asked whether to try to disarm it. +If you accede, success will eliminate the trap but +failure will set off the trap's explosion. +(If you decline, you effectively forget that a trap was found there.) + +%.pg +Closed doors can be useful for shutting out monsters. +Most monsters cannot open closed doors, although a few don't need to +(for example, ghosts can walk through doors and fog clouds can flow +under them). +Some monsters who can open doors can also use unlocking tools. +And some (giants) can smash doors. + +%.pg +Secret doors are hidden and appear to be ordinary wall (from inside a +room) or solid rock (from outside). +You can find them with the `\texttt{s}' (search) command but it might +take multiple tries (possibly many tries if your luck is poor). +Once found they are in all ways equivalent to normal doors. +Mapping magic does not reveal secret doors. %.hn 2 -\subsection*{Traps (`{\tt \^{}}')} +\subsection*{Traps (`\texttt{\textasciicircum }')} %.pg -There are traps throughout the dungeon to snare the unwary delver. +There are traps throughout the dungeon to snare the unwary intruder. For example, you may suddenly fall into a pit and be stuck for a few -turns trying to climb out. Traps don't appear on your map until you -see one triggered by moving onto it, see something fall into it, or you -discover it with the `{\tt s}' (search) command. Monsters can fall prey to -traps, too, which can be a very useful defensive strategy. - -%.pg -There is a special pre-mapped branch of the dungeon based on the -classic computer game ``{\tt Sokoban}.'' The goal is to push the boulders -into the pits or holes. With careful foresight, it is possible to -complete all of the levels according to the traditional rules of -Sokoban. Some allowances are permitted in case the player gets stuck; -however, they will lower your luck. +turns trying to climb out (see below). +A trap usually won't appear on your map until you trigger it by moving +onto it, you see someone else trigger it, or you discover it with +the `\texttt{s}' (search) command (multiple attempts are often needed; +if your luck is poor, many attempts might be needed). +\textit{Wands of secret door detection} and the spell of \textit{detect unseen} +also reveal traps within a modest radius but only if the trap is also within +line-of-sight (whether you can see at the time or not). +There is also other magic which can reveal traps. + +%.pg +Monsters can fall prey to +traps, too, which can potentially be used as a defensive strategy. +Unfortunately traps can be harmful to your pet(s) as well. +Monsters, including pets, usually will avoid moving onto a trap which +is shown on your map if they have encountered that type of trap before. + +%.pg +Some traps such as pits, bear traps, and webs hold you in one place. +You can escape by simply trying to move to an adjacent spot and repeat +as needed; eventually you will get free. + +%.pg +Other traps can send you to different locations. +Teleporters send you elsewhere on the same dungeon level. +Level teleporters send you to a random dungeon level, the destination +chosen from a few levels lower all the way to the top. +These traps choose a new destination each time they're activated. +Trap doors and holes also send you to another level, but one which is +always below the current level. +Usually that will be the next level down but it can be farther. +Unlike (level) teleporters, the destination level of a particular trap door +or hole is persistent, so falling into one will bring you to the same level +each time---though not necessarily the same spot on the level. +Magic portals behave similarly, but with some additional variation. +Some portals are two-way and their remote destination is always the same: +another portal which can take you back. +Others are one-way and send you to a specific destination level but not +necessarily to a specific location there. + +%.pg +There is a special multi-level branch of the dungeon with pre-mapped levels +based on the classic computer game ``\textit{Sokoban}.'' +In that game, you operate as a warehouse worker who pushes crates around +obstacles to position them at designated locations. +In NetHack, the goal is to push boulders into pits or holes until those +traps have all been nullified, giving access to whatever is beyond them. +In the Sokoban game, you can only move in the four cardinal compass +directions, and a crate in its final destination blocks further access +to that spot. +In the Sokoban levels of NetHack, you can move diagonally (unless that +would let you pass between two neighboring boulders) but you can only +push boulders in the four cardinal directions, and a boulder which fills +a pit or hole removes both the boulder and the trap so opens up normal +access to that spot. +With careful foresight, it is possible to complete all of the levels +according to the traditional rules of Sokoban. +(Hint: to solve Sokoban puzzles, you often need to move things away from +their eventual destinations in order to open up more room to maneuver.) +Since NetHack does not support an \textit{undo} capability, some allowances +are permitted in case you get stuck. +For example, each level has at least one extra boulder. +Also, it is possible to drop everything in order to be able to squeeze +into the same location as a boulder (and then presumably move past it), +or to destroy a boulder with magic or tools, or to create new boulders +with a \textit{scroll of earth}. +However, doing such things will lower your luck without any specific +message given about that. +See the \textit{Conduct} section for information about getting feedback for +your actions in Sokoban. %.hn 2 -\subsection*{Stairs and ladders (`{\tt <}', `{\tt >}')} +\subsection*{Stairs and ladders (`\texttt{<}', `\texttt{>}')} %.pg In general, each level in the dungeon will have a staircase going up -(`{\tt <}') to the previous level and another going down (`{\tt >}') +(`\texttt{<}') to the previous level and another going down (`\texttt{>}') to the next level. There are some exceptions though. For instance, fairly early in the dungeon you will find a level with two down staircases, one @@ -1859,8 +2403,8 @@ \subsection*{Shops and shopping} %.pg Occasionally you will run across a room with a shopkeeper near the door and many items lying on the floor. You can buy items by picking them -up and then using the `{\tt p}' command. You can inquire about the price -of an item prior to picking it up by using the ``{\tt \#chat}'' command +up and then using the `\texttt{p}' command. You can inquire about the price +of an item prior to picking it up by using the ``\texttt{\#chat}'' command while standing on it. Using an item prior to paying for it will incur a charge, and the shopkeeper won't allow you to leave the shop until you have paid any debt you owe. @@ -1878,20 +2422,22 @@ \subsection*{Shops and shopping} it back if you want to reclaim it. %.pg -Shopkeepers sometimes run out of money. When that happens, you'll be -offered credit instead of gold when you try to sell something. Credit -can be used to pay for purchases, but it is only good in the shop where -it was obtained; other shopkeepers won't honor it. (If you happen to +Shopkeepers sometime run out of money. +When that happens, you'll be +offered credit instead of gold when you try to sell something. +Credit can be used to pay for purchases, but it is only good in the shop +where it was obtained; other shopkeepers won't honor it. +(If you happen to find a ``credit card'' in the dungeon, don't bother trying to use it in shops; shopkeepers will not accept it.) %.pg -The {\tt \$} command, which reports the amount of gold you are carrying -(in inventory, not inside bags or boxes), will also show current shop -debt or credit, if any. The {\tt Iu} command lists unpaid items -(those which still belong to the shop) if you are carrying any. -The {\tt Ix} command shows an inventory-like display of any unpaid -items which have been used up, along with other shop fees, if any. +The \texttt{\$} command, which reports the amount of gold you are carrying, +will also show current shop debt or credit, if any. +The \texttt{Iu} command lists unpaid items (those which still belong to the +shop) if you are carrying any. +The \texttt{Ix} command shows an inventory-like display of any unpaid items +which have been used up, along with other shop fees, if any. %.hn 3 \subsubsection*{Shop idiosyncrasies} @@ -1902,24 +2448,132 @@ \subsubsection*{Shop idiosyncrasies} \begin{itemize} % note: a bullet is the default item label so we could omit [$\bullet$] here %.lp \(bu 2 -\item[$\bullet$] +\item The price of a given item can vary due to a variety of factors. %.lp \(bu 2 -\item[$\bullet$] +\item A shopkeeper treats the spot immediately inside the door as if it were outside the shop. %.lp \(bu 2 -\item[$\bullet$] -While the shopkeeper watches you like a hawk, he will generally ignore +\item +While the shopkeeper watches you like a hawk, he or she will generally ignore any other customers. %.lp \(bu 2 -\item[$\bullet$] +\item If a shop is ``closed for inventory,'' it will not open of its own accord. %.lp \(bu 2 -\item[$\bullet$] +\item Shops do not get restocked with new items, regardless of inventory depletion. \end{itemize} +%.hn 2 +\subsection*{Movement feedback} + +%.pg +Moving around the map usually provides no +feedback---other than drawing the hero at the new location---unless +you step on an object or pile of objects, +or on a trap, or attempt to move onto a spot where a monster is located. +There are several options which can be used to augment the normal feedback. + +%.pg +The +\textit{pile\textunderscore limit} +option controls how many objects can be in a +pile---sharing the same map location---for +the game to state ``there are objects here'' instead of listing them. +The default is \texttt{5}. +Setting it to \texttt{1} would always give that message instead of listing +any objects. +Setting it to \texttt{0} is a special case which will always list all +objects no matter how big a pile is. +Note that the number refers to the count of separate stacks of objects +present rather than the sum of the quantities of those stacks (so +\texttt{7 arrows} or \texttt{25 gold pieces} will each count as 1 rather +than as 7 and 25, respectively, and total to 2 when both are at the +same location). + +%.pg +The \texttt{nopickup} command prefix (default `\texttt{m}') can be +used before a movement direction to step on objects without attempting +auto-pickup and without giving feedback about them. + +%.pg +The +\textit{mention\textunderscore walls} +option controls whether you get feedback if you try to walk into a wall +or solid stone or off the edge of the map. +Normally nothing happens (unless the hero is blind and no wall is shown, +then the wall that is being bumped into will be drawn on the map). +This option also gives feedback when rushing or running stops for +some non-obvious reason. + +%.pg +The +\textit{mention\textunderscore decor} +option controls whether you get feedback when walking on ``furniture.'' +Normally stepping onto stairs or a fountain or an altar or various other +things doesn't elicit anything unless it is covered by one or more objects +so is obscured on the map. +Setting this option to true will describe such things even when they +aren't obscured. +Doorless doorways and open doors aren't considered worthy of mention; +closed doors (if you can move onto their spots) and broken doors are. +Assuming that you're able to do so, moving onto water or lava or ice +will give feedback if not yet on that type of terrain but not repeat it +(unless there has been some intervening message) when moving from water +to another water spot, or lava to lava, or ice to ice. +Moving off of any of those back onto ``normal'' terrain will give one +message too, unless there is feedback about one or more objects, in which +case the back on land circumstance is implied. + +%.pg +The +\textit{confirm} +and +\textit{safe\textunderscore pet} +options control what happens when you try to move onto a peaceful monster's +spot or a tame one's spot. + +%.\" getting away from "Movement feedback" here; oh well... +%.pg +The \texttt{nopickup} command prefix (default `\texttt{m}') is +also the move-without-attacking prefix and can be used to try to step +onto a visible monster's spot without the move being considered an attack +(see the \textit{Fighting} subsection of \textit{Monsters} below). +The `\texttt{fight}' command prefix (default `\texttt{F}'; +also `\texttt{-}' if +\textit{number\textunderscore pad} +is on) can be used to force an attack, when guessing where an unseen +monster is or when deliberately attacking a peaceful or tame creature. + +%.pg +The +\textit{run\textunderscore mode} +option controls how frequently the map gets redrawn when moving more +than one step in a single command (so when rushing, running, or traveling). + +%.hn 2 +\subsection*{Rogue level} + +%.pg +One dungeon level (occurring in mid to late teens of the main dungeon) +is a tribute to the ancestor game \textit{hack}'s inspiration \textit{rogue}. + +%.pg +It is usually displayed differently from other levels: possibly in +characters instead of tiles, or without line-drawing symbols if already +in characters; also, gold is shown as \texttt{*} rather than \texttt{\textdollar} +and stairs are shown as \texttt{\%} rather than \texttt{<} and \texttt{>}. +There are some minor differences in actual game play: doorways lack +doors; a scroll, wand, or spell of light used in a room lights up the +whole room rather than within a radius around your character. +And monsters represented by lower-case letters aren't randomly +generated on the rogue level. + +%.pg +The slight strangeness of this level is a feature, not a bug.... + %.hn 1 \section{Monsters} @@ -1930,16 +2584,16 @@ \section{Monsters} very well). %.pg -The commands `{\tt /}' and `{\tt ;}' may be used to obtain information +The commands `\texttt{/}' and `\texttt{;}' may be used to obtain information about those -monsters who are displayed on the screen. The command ``{\tt \#name}'' -(by default bound to `{\tt C}'), allows you +monsters who are displayed on the screen. The command ``\texttt{\#name}'' +(by default bound to `\texttt{C}'), allows you to assign a name to a monster, which may be useful to help distinguish one from another when multiple monsters are present. Assigning a name which is just a space will remove any prior name. %.pg -The extended command ``{\tt \#chat}'' can be used to interact with an adjacent +The extended command ``\texttt{\#chat}'' can be used to interact with an adjacent monster. There is no actual dialog (in other words, you don't get to choose what you'll say), but chatting with some monsters such as a shopkeeper or the Oracle of Delphi can produce useful results. @@ -1956,27 +2610,27 @@ \subsection*{Fighting} %.pg In most circumstances, if you attempt to attack a peaceful monster by moving into its location, you'll be asked to confirm your intent. By -default an answer of `{\tt y}' acknowledges that intent, -which can be error prone if you're using `{\tt y}' to move. You can set the -{\it paranoid\verb+_+confirmation\/} -option to require a response of ``{\tt yes}'' instead. +default an answer of `\texttt{y}' acknowledges that intent, +which can be error prone if you're using `\texttt{y}' to move. You can set the +\textit{paranoid\textunderscore confirmation:attack} +option to require a response of ``\texttt{yes}'' instead. %.pg If you can't see a monster (if it is invisible, or if you are blinded), -the symbol `I' will be shown when you learn of its presence. +the symbol `\texttt{I}' will be shown when you learn of its presence. If you attempt to walk into it, you will try to fight it just like a monster that you can see; of course, if the monster has moved, you will attack empty air. If you guess -that the monster has moved and you don't wish to fight, you can use the `m' -command to move without fighting; likewise, if you don't remember a monster -but want to try fighting anyway, you can use the `F' command. +that the monster has moved and you don't wish to fight, you can use the +`\texttt{m}' command to move without fighting; likewise, if you don't remember +a monster but want to try fighting anyway, you can use the `\texttt{F}' command. %.hn 2 \subsection*{Your pet} %.pg -You start the game with a little dog (`{\tt d}'), kitten (`{\tt f}'), -or pony (`{\tt u}'), which follows +You start the game with a little dog (`\texttt{d}'), kitten (`\texttt{f}'), +or pony (`\texttt{u}'), which follows you about the dungeon and fights monsters with you. Like you, your pet needs food to survive. Dogs and cats usually feed themselves on fresh carrion and other meats; @@ -2009,22 +2663,22 @@ \subsection*{Steeds} you saddle it up is difficult to say the least. Many a dungeoneer has had to resort to magic and wizardry in order to forge the alliance. Once you do have the beast under your control however, you can -easily climb in and out of the saddle with the ``{\tt \#ride}'' command. Lead +easily climb in and out of the saddle with the ``\texttt{\#ride}'' command. Lead the beast around the dungeon when riding, in the same manner as you would move yourself. It is the beast that you will see displayed on the map. %.pg -Riding skill is managed by the ``{\tt \#enhance}'' command. See the section +Riding skill is managed by the ``\texttt{\#enhance}'' command. See the section on Weapon proficiency for more information about that. %.pg -Use the `{\tt a}' (apply) command and pick a saddle in your inventory to +Use the `\texttt{a}' (apply) command and pick a saddle in your inventory to attempt to put that saddle on an adjacent creature. If successful, it will be transferred to that creature's inventory. %.pg -Use the ``{\tt \#loot}'' command while adjacent to a saddled creature to +Use the ``\texttt{\#loot}'' command while adjacent to a saddled creature to try to remove the saddle from that creature. If successful, it will be transferred to your inventory. @@ -2052,8 +2706,8 @@ \subsection*{Persistence of Monsters} %.pg However, if you encounter a monster which you can't see or -sense---perhaps it is invisible and has just tapped you on the -noggin---a special ``remembered, unseen monster'' marker will be displayed at +sense---perhaps it is invisible and has just tapped you on the noggin---a +special ``remembered, unseen monster'' marker will be displayed at the location where you think it is. That will persist until you have proven that there is no monster there, even if the unseen monster @@ -2065,12 +2719,11 @@ \section{Objects} %.pg When you find something in the dungeon, it is common to want to pick -it up. In {\it NetHack}, this is accomplished automatically by walking over -the object (unless you turn off the {\it autopickup\/} -option (see below), or move with the `{\tt m}' prefix (see above)), or -manually by using the `{\tt ,}' command. +it up. In \textit{NetHack}, this is accomplished by using the `\texttt{,}' command. +If \textit{autopickup} option is on, you will automatically pick up the object +by walking over it, unless you move with the `\texttt{m}' prefix. %.pg -If you're carrying too many items, {\it NetHack\/} will tell you so and you +If you're carrying too many items, \textit{NetHack} will tell you so and you won't be able to pick up anything more. Otherwise, it will add the object(s) to your pack and tell you what you just picked up. %.pg @@ -2085,16 +2738,16 @@ \section{Objects} to cope with it. Eventually, you'll be so overloaded that you'll either have to discard some of what you're carrying or collapse under its weight. %.pg -{\it NetHack\/} will tell you how badly you have loaded yourself. +\textit{NetHack} will tell you how badly you have loaded yourself. If you are encumbered, one of the conditions -``{\it Burdened\/}'', ``{\it Stressed\/}'', ``{\it Strained\/}'', -``{\it Overtaxed\/}'' or ``{\it Overloaded\/}'' will be +\texttt{Burdened}, \texttt{Stressed}, \texttt{Strained}, +\texttt{Overtaxed}, or \texttt{Overloaded} will be shown on the bottom line status display. %.pg When you pick up an object, it is assigned an inventory letter. Many commands that operate on objects must ask you to find out which object -you want to use. When {\it NetHack\/} asks you to choose a particular object +you want to use. When \textit{NetHack} asks you to choose a particular object you are carrying, you are usually presented with a list of inventory letters to choose from (see Commands, above). @@ -2105,13 +2758,13 @@ \section{Objects} the same type. However, the descriptions will vary from game to game. %.pg -When you use one of these objects, if its effect is obvious, {\it NetHack\/} +When you use one of these objects, if its effect is obvious, \textit{NetHack} will remember what it is for you. If its effect isn't extremely obvious, you will be asked what you want to call this type of object -so you will recognize it later. You can also use the ``{\tt \#name}'' +so you will recognize it later. You can also use the ``\texttt{\#name}'' command, for the same purpose at any time, to name all objects of a particular type or just an individual object. -When you use ``{\tt \#name}'' on an object which has already been named, +When you use ``\texttt{\#name}'' on an object which has already been named, specifying a space as the value will remove the prior name instead of assigning a new one. @@ -2129,9 +2782,10 @@ \subsection*{Curses and Blessings} detrimentally in other ways. %.pg -Objects can also be blessed. Blessed items usually work better or -more beneficially than normal uncursed items. For example, a blessed -weapon will do more damage against demons. +Objects can also be blessed instead. +Blessed items usually work better or more beneficially than normal +uncursed items. +For example, a blessed weapon will do slightly more damage against demons. %.pg Objects which are neither cursed nor blessed are referred to as uncursed. @@ -2142,24 +2796,91 @@ \subsection*{Curses and Blessings} %.pg There are magical means of bestowing or removing curses upon objects, so even if you are stuck with one, you can still have the curse -lifted and the item removed. Priests and Priestesses have an innate +lifted and the item removed. +Priests and Priestesses have an innate sensitivity to this property in any object, so they can more easily avoid cursed objects than other character roles. +Dropping objects onto an altar will reveal their bless or curse state +provided that you can see them land. %.pg An item with unknown status will be reported in your inventory with no prefix. An item which you know the state of will be distinguished in your inventory -by the presence of the word ``cursed'', ``uncursed'' or ``blessed'' in the -description of the item. -In some cases ``uncursed'' will be omitted as being redundant when +by the presence of the word \texttt{cursed}, \texttt{uncursed} or +\texttt{blessed} in the description of the item. +In some cases \texttt{uncursed} will be omitted as being redundant when enough other information is displayed. The -{\it implicit\verb+_+uncursed\/} -option can be used to control this; toggle it off to have ``uncursed'' +\textit{implicit\textunderscore uncursed} +option can be used to control this; toggle it off to have \texttt{uncursed} be displayed even when that can be deduced from other attributes. +%.pg +Sometimes the bless or curse state of objects is referred to as their +``\texttt{BUC}'' attribute, for Blessed, Uncursed, or Cursed state, +or ``\texttt{BUCX}'' for Blessed, Uncursed, Cursed, or unknown. +(The term \textit{beatitude} is occasionally used as well.) + +%.hn 2 +\subsection*{Artifacts} + +%.pg +Some objects have been imbued with special powers and are known as +\textit{Artifacts}. +They have specific types (such as long sword or orcish dagger) and distinct +names such as \textit{Giantslayer} or \textit{Grimtooth}. +Artifact weapons typically do more damage than their ordinary counterparts. +Some do extra damage against all monsters, others only against specific +types of monsters so aren't better than regular weapons against other types. +Some confer defensive capabilities when wielded or have other powers that +aren't listed here. + +%.pg +You might find them simply lying on the floor, including but not limited +to inside shops, or be granted as a reward for ``\texttt{\#offer}'' on an +altar to your patron deity. +A few might be dropped by monsters, or might be converted from an ordinary +object of the same type via assigning the right name. +% should we mention dipping for Excalibur here? +Or you might wish for them, if you happen to be granted a wish, but such +wishes can fail. + +%.pg +Some artifacts have a specific alignment, others don't. +You won't obtain aligned ones that have a different alignment from yours +via offering and might get a shock if you attempt to wish for any of those +or find one and attempt to use it. + +%pg +Each role has a distinct artifact that is contained in the \textit{Quest} +dungeon branch. +These are commonly known as quest artifacts. +All are aligned and most are non-weapons. +They won't be found randomly. + +%.pg +The `\texttt{\textbackslash}' and `\texttt{\textasciigrave{}a}' commands will +list artifacts that you have fully identified (knowing the name and item +type isn't sufficient). + +%.hn 2 +\subsection*{Relics} + +%.pg +There are three unique items that are named and have limited special +powers but aren't classified as artifacts. +Each is guarded by a particular monster and you'll need to collect all +three for use late in the game. +% The relics are listed in the same order as the Oracle's message about +% them rather than in the order they need to be used for the invocation. +They are \textit{the Bell of Opening}, +\textit{the Book of the Dead}, and +\textit{the Candelabrum of Invocation}. +Their corresponding descriptions when not yet identified are +silver bell, papyrus spellbook, and candelabrum. + %.hn 2 -\subsection*{Weapons (`{\tt )}')} +\subsection*{Weapons (`\texttt{)}')} %.pg Given a chance, most monsters in the Mazes of Menace will gratuitously try to @@ -2191,19 +2912,20 @@ \subsection*{Weapons (`{\tt )}')} of damage such a hit will do, depends upon many factors. Among them are: type of weapon, quality of weapon (enchantment and/or erosion), experience level, strength, dexterity, encumbrance, and proficiency (see below). The -monster's armor class---a general defense rating, not necessarily due to -wearing of armor---is a factor too; also, some monsters are particularly +monster's armor +class---a general defense rating, not necessarily due to wearing of armor---is +a factor too; also, some monsters are particularly vulnerable to certain types of weapons. %.pg Many weapons can be wielded in one hand; some require both hands. When wielding a two-handed weapon, you can not wear a shield, and vice versa. When wielding a one-handed weapon, you can have another -weapon ready to use by setting things up with the `{\tt x}' command, which +weapon ready to use by setting things up with the `\texttt{x}' command, which exchanges your primary (the one being wielded) and alternate weapons. And if you have proficiency in the ``two weapon combat'' skill, you may wield both weapons simultaneously as primary and secondary; use the -`{\tt X}' command to engage or disengage that. +`\texttt{X}' command to engage or disengage that. Only some types of characters (barbarians, for instance) have the necessary skill available. Even with that skill, using two weapons at once incurs a penalty in the chance to hit your target compared to using just one @@ -2211,30 +2933,35 @@ \subsection*{Weapons (`{\tt )}')} %.pg There might be times when you'd rather not wield any weapon at all. -To accomplish that, wield `{\tt -}', or else use the `{\tt A}' command which +To accomplish that, wield `\texttt{-}', or else use the `\texttt{A}' command which allows you to unwield the current weapon in addition to taking off other worn items. %.pg Those of you in the audience who are AD\&D players, be aware that each weapon which existed in AD\&D does roughly the same damage to monsters in -{\it NetHack}. Some of the more obscure weapons (such as the % -{\it aklys}, {\it lucern hammer}, and {\it bec-de-corbin\/}) are defined -in an appendix to {\it Unearthed Arcana}, an AD\&D supplement. +\textit{NetHack}. Some of the more obscure weapons (such as the +\textit{aklys}, \textit{lucern hammer}, and \textit{bec-de-corbin}) are defined +in an appendix to \textit{Unearthed Arcana}, an AD\&D supplement. %.pg -The commands to use weapons are `{\tt w}' (wield), `{\tt t}' (throw), -`{\tt f}' (fire, an alternate way of throwing), `{\tt Q}' (quiver), -`{\tt x}' (exchange), `{\tt X}' (twoweapon), and ``{\tt \#enhance}'' +Some interfaces support the \texttt{weaponstatus} option. +When it is enabled, an extra status condition is displayed, describing +the currently wielded weapon. + +%.pg +The commands to use weapons are `\texttt{w}' (wield), `\texttt{t}' (throw), +`\texttt{f}' (fire), `\texttt{Q}' (quiver), +`\texttt{x}' (exchange), `\texttt{X}' (twoweapon), and ``\texttt{\#enhance}'' (see below). %.hn 3 \subsection*{Throwing and shooting} %.pg -You can throw just about anything via the `{\tt t}' command. It will prompt -for the item to throw; picking `{\tt ?}' will list things in your inventory -which are considered likely to be thrown, or picking `{\tt *}' will list +You can throw just about anything via the `\texttt{t}' command. It will prompt +for the item to throw; picking `\texttt{?}' will list things in your inventory +which are considered likely to be thrown, or picking `\texttt{*}' will list your entire inventory. After you've chosen what to throw, you will be prompted for a direction rather than for a specific target. The distance something can be thrown depends mainly on the type of object @@ -2243,33 +2970,51 @@ \subsection*{Throwing and shooting} wielding a bow. %.pg -You can simplify the throwing operation by using the `{\tt Q}' command to -select your preferred ``missile'', then using the `{\tt f}' command to +Some weapons will return when thrown. +A boomerang---provided it fails to hit anything---is an obvious example. +If an aklys (thonged club) is thrown while it is wielded, it will return +even when it hits something. +A sufficiently strong hero can throw the warhammer \textit{Mjollnir}; +when thrown by a \textit{Valkyrie} it will return too. +However, aklyses and \textit{Mjollnir} occasionally fail to return. +Returning thrown objects occasionally fail to be caught, sometimes even +hitting the thrower, but when caught they become re-wielded. + +%.pg +You can simplify the throwing operation by using the `\texttt{Q}' command to +select your preferred ``missile'', then using the `\texttt{f}' command to throw it. You'll be prompted for a direction as above, but you don't -have to specify which item to throw each time you use `{\tt f}'. There is +have to specify which item to throw each time you use `\texttt{f}'. There is also an option, -{\it autoquiver}, -which has {\it NetHack\/} choose another item to automatically fill your +\textit{autoquiver}, +which has \textit{NetHack} choose another item to automatically fill your quiver (or quiver sack, or have at the ready) when the inventory slot used -for `{\tt Q}' runs out. - -%.pg -Some characters have the ability to fire a volley of multiple items in a -single turn. Knowing how to load several rounds of ammunition at -once---or hold several missiles in your hand---and still hit a -target is not an easy task. Rangers are among those who are adept +for `\texttt{Q}' runs out. +If your quiver is empty, \textit{autoquiver} +is false, and you are wielding a weapon which returns when thrown, +you will throw that weapon instead of filling the quiver. +The fire command also has extra assistance, if \textit{fireassist} +is on it will try to wield a launcher matching the ammo in the quiver. + +%.pg +Some characters have the ability to throw or shoot a volley of multiple +items (from the same stack) in a single action. +Knowing how to load several rounds of ammunition at +once---or hold several missiles in your hand---and +still hit a target is not an easy task. +Rangers are among those who are adept at this task, as are those with a high level of proficiency in the relevant weapon skill (in bow skill if you're wielding one to shoot arrows, in crossbow skill if you're wielding one to shoot bolts, or in sling skill if you're wielding one to shoot stones). The number of items that the character has a chance to fire varies from turn to turn. You can explicitly limit the number of shots by using a -numeric prefix before the `{\tt t}' or `{\tt f}' command. -For example, ``{\tt 2f}'' (or ``{\tt n2f}'' if using -{\it number\verb+_+pad\/} +numeric prefix before the `\texttt{t}' or `\texttt{f}' command. +For example, ``\texttt{2f}'' (or ``\texttt{n2f}'' if using +\textit{number\textunderscore pad} mode) would ensure that at most 2 arrows are shot even if you could have fired 3. If you specify -a larger number than would have been shot (``{\tt 4f}'' in this example), +a larger number than would have been shot (``\texttt{4f}'' in this example), you'll just end up shooting the same number (3, here) as if no limit had been specified. Once the volley is in motion, all of the items will travel in the same direction; if the first ones kill a monster, @@ -2293,14 +3038,14 @@ \subsection*{Weapon proficiency} skilled in daggers or staves but not in swords or bows. %.pg -The ``{\tt \#enhance}'' extended command is used to review current weapons +The ``\texttt{\#enhance}'' extended command is used to review current weapons proficiency (also spell proficiency) and to choose which skill(s) to improve when you've used one or more skills enough to become eligible to do so. The skill rankings are ``none'' (sometimes also referred to as ``restricted'', because you won't be able to advance), ``unskilled'', ``basic'', ``skilled'', and ``expert''. Restricted skills simply will not appear in the list -shown by ``{\tt \#enhance}''. +shown by ``\texttt{\#enhance}''. (Divine intervention might unrestrict a particular skill, in which case it will start at unskilled and be limited to basic.) Some characters can enhance their barehanded combat or martial arts skill @@ -2316,7 +3061,7 @@ \subsection*{Weapon proficiency} the next skill level (unless you've already reached the limit for this skill). Once such training reaches the threshold for that next level, you'll be told that you feel more confident in your skills. At that -point you can use ``{\tt \#enhance}'' to increase one or more skills. +point you can use ``\texttt{\#enhance}'' to increase one or more skills. Such skills are not increased automatically because there is a limit to your total overall skills, so you need to actively choose which skills to enhance @@ -2328,47 +3073,49 @@ \subsection*{Two-Weapon combat} %.pg Some characters can use two weapons at once. Setting things up to do so can seem cumbersome but becomes second nature with use. -To wield two weapons, you need to use the ``{\tt \#twoweapon}'' command. +To wield two weapons, you need to use the ``\texttt{\#twoweapon}'' command. But first you need to have a weapon in each hand. (Note that your two weapons are not fully equal; the one in the hand you normally wield with is considered primary and the other -one is considered secondary. The most noticeable difference is -after you stop---or before you begin, for that matter---wielding -two weapons at once. The primary is your wielded weapon and the +one is considered secondary. +The most noticeable difference is after you +stop---or before you begin, for that matter---wielding +two weapons at once. +The primary is your wielded weapon and the secondary is just an item in your inventory that's been designated as alternate weapon.) %.pg If your primary weapon is wielded but your off hand is empty or has -the wrong weapon, use the sequence `{\tt x}', `{\tt w}', `{\tt x}' to +the wrong weapon, use the sequence `\texttt{x}', `\texttt{w}', `\texttt{x}' to first swap your primary into your off hand, wield whatever you want as secondary weapon, then swap them both back into the intended hands. If your secondary or alternate weapon is correct but your primary -one is not, simply use `{\tt w}' to wield the primary. +one is not, simply use `\texttt{w}' to wield the primary. Lastly, if neither hand holds the correct weapon, -use `{\tt w}', `{\tt x}', `{\tt w}' +use `\texttt{w}', `\texttt{x}', `\texttt{w}' to first wield the intended secondary, swap it to off hand, and then wield the primary. %.pg The whole process can be simplified via use of the -{\it pushweapon\/} -option. When it is enabled, then using `{\tt w}' to wield something +\textit{pushweapon} +option. When it is enabled, then using `\texttt{w}' to wield something causes the currently wielded weapon to become your alternate weapon. -So the sequence `{\tt w}', `{\tt w}' can be used to first wield the weapon you +So the sequence `\texttt{w}', `\texttt{w}' can be used to first wield the weapon you intend to be secondary, and then wield the one you want as primary which will push the first into secondary position. %.pg -When in two-weapon combat mode, using the `{\tt X}' command +When in two-weapon combat mode, using the `\texttt{X}' command toggles back to single-weapon mode. Throwing or dropping either of the weapons or having one of them be stolen or destroyed will also make you revert to single-weapon combat. %.hn 2 -\subsection*{Armor (`{\tt [}')} +\subsection*{Armor (`\texttt{[}')} %.pg Lots of unfriendly things lurk about; you need armor to protect @@ -2377,8 +3124,9 @@ \subsection*{Armor (`{\tt [}')} protection. Armor class (AC) is measured as in AD\&D, with 10 being the equivalent of no armor, and lower numbers meaning better armor. Each suit of armor which exists in AD\&D gives the same protection in -{\it NetHack}. Here is an (incomplete) list of the armor classes provided by -various suits of armor: +\textit{NetHack}. + +Here is a list of the armor class values provided by suits of armor: \begin{center} \begin{tabular}{lllll} @@ -2395,11 +3143,19 @@ \subsection*{Armor (`{\tt [}')} \end{center} %.pg -\nd You can also wear other pieces of armor (for example, helmets, boots, -shields, cloaks) -to lower your armor class even further, but you can only wear one item -of each category (one suit of armor, one cloak, one helmet, one -shield, and so on) at a time. +\noindent You can also wear other pieces of armor (cloak over suit, shirt under +suit, helmet, gloves, boots, shield) to lower your armor class even +further. +%--too obvious to mention unless we include polymorph into ettin or maralith +% You can wear at most one item of each category (one suit of armor, one +% cloak, one helmet, one shield, and so on) at a time. +Most of these provide a one or two point improvement to AC (making the +overall value smaller and eventually negative) but can also be +enchanted. +Shirts are an exception; they don't provide any protection unless enchanted. +Some cloaks also don't improve AC when unenchanted but all cloaks offer +some protection against rust or corrosion to suits worn under them and +against some monster \textit{touch} attacks. %.pg If a piece of armor is enchanted, its armor protection will be better @@ -2416,12 +3172,26 @@ \subsection*{Armor (`{\tt [}')} damage can be repaired. Some types of armor may inhibit spell casting. %.pg -The commands to use armor are `{\tt W}' (wear) and `{\tt T}' (take off). -The `{\tt A}' command can also be used to take off armor as well as other +The \textit{nudist} +option can be set (prior to game start) to attempt to play the entire +game without wearing any armor (a self-imposed challenge which is +extremely difficult to accomplish). + +%.pg +Some interfaces support the \texttt{armorstatus} option. +When it is enabled, an extra status condition is displayed, summarizing +currently worn armor. + +%.pg +The commands to use armor are `\texttt{W}' (wear) and `\texttt{T}' (take off). +The `\texttt{A}' command can be used to take off armor as well as other worn items. +Also, `\texttt{P}' (put on) and `\texttt{R}' (remove) which are normally for +accessories can be used for armor, but pieces of armor won't be shown +as likely candidates in a prompt for choosing what to put on or remove. %.hn 2 -\subsection*{Food (`{\tt \%}')} +\subsection*{Food (`\texttt{\%}')} %.pg Food is necessary to survive. If you go too long without eating you @@ -2445,13 +3215,13 @@ \subsection*{Food (`{\tt \%}')} %.pg You can name one food item after something you like to eat with the -{\it fruit\/} option. +\textit{fruit} option. %.pg -The command to eat food is `{\tt e}'. +The command to eat food is `\texttt{e}'. %.hn 2 -\subsection*{Scrolls (`{\tt ?}')} +\subsection*{Scrolls (`\texttt{?}')} %.pg Scrolls are labeled with various titles, probably chosen by ancient wizards @@ -2461,31 +3231,41 @@ \subsection*{Scrolls (`{\tt ?}')} %.pg One of the most useful of these is the % -{\it scroll of identify}, which +\textit{scroll of identify}, which can be used to determine what another object is, whether it is cursed or -blessed, and how many uses it has left. Some objects of subtle -enchantment are difficult to identify without these. +blessed, and how many uses it has left. +Some objects of subtle enchantment are difficult to identify without these. + +%.pg +A scroll whose label is known can be read even when the hero is blind. +If a scroll has been discovered, it will be listed in inventory by type +rather than by label, but the label is known in that situation even though +it isn't shown. + +%.pg +Many scrolls produce a different effect from usual if they are blessed or +cursed, or read while the hero is confused. %.pg A mail daemon may run up and deliver mail to you as a % -{\it scroll of mail} (on versions compiled with this feature). -To use this feature on versions where {\it NetHack\/} +\textit{scroll of mail} (on versions compiled with this feature). +To use this feature on versions where \textit{NetHack} mail delivery is triggered by electronic mail appearing in your system mailbox, -you must let {\it NetHack\/} know where to look for new mail by setting the -``MAIL'' environment variable to the file name of your mailbox. -You may also want to set the ``MAILREADER'' environment variable to the -file name of your favorite reader, so {\it NetHack\/} can shell to it when you +you must let \textit{NetHack} know where to look for new mail by setting the +\texttt{MAIL} environment variable to the file name of your mailbox. +You may also want to set the \texttt{MAILREADER} environment variable to the +file name of your favorite reader, so \textit{NetHack} can shell to it when you read the scroll. -On versions of {\it NetHack\/} where mail is randomly +On versions of \textit{NetHack} where mail is randomly generated internal to the game, these environment variables are ignored. You can disable the mail daemon by turning off the -{\it mail\/} option. +\textit{mail} option. %.pg -The command to read a scroll is `{\tt r}'. +The command to read a scroll is `\texttt{r}'. %.hn 2 -\subsection*{Potions (`{\tt !}')} +\subsection*{Potions (`\texttt{!}')} %.pg Potions are distinguished by the color of the liquid inside the flask. @@ -2495,20 +3275,20 @@ \subsection*{Potions (`{\tt !}')} Clear potions are potions of water. Sometimes these are blessed or cursed, resulting in holy or unholy water. Holy water is the bane of the undead, so potions of holy water are good things to -throw (`{\tt t}') at them. It is also sometimes very useful to dip -(``{\tt \#dip}'') an object into a potion. +throw (`\texttt{t}') at them. It is also sometimes very useful to dip +(``\texttt{\#dip}'') an object into a potion. %.pg -The command to drink a potion is `{\tt q}' (quaff). +The command to drink a potion is `\texttt{q}' (quaff). %.hn 2 -\subsection*{Wands (`{\tt /}')} +\subsection*{Wands (`\texttt{/}')} %.pg Wands usually have multiple magical charges. Some types of wands require a direction in which to zap them. You can also -zap them at yourself (just give a `{\tt .}' or `{\tt s}' for the direction). +zap them at yourself (just give a `\texttt{.}' or `\texttt{s}' for the direction). Be warned, however, for this is often unwise. Other types of wands don't require a direction. The number of charges in a @@ -2533,15 +3313,15 @@ \subsection*{Wands (`{\tt /}')} When you have fully identified a particular wand, inventory display will include additional information in parentheses: the number of times it has been recharged followed by a colon and then by its current number of charges. -A current charge count of {\tt -1} is a special case indicating that the wand +A current charge count of \texttt{-1} is a special case indicating that the wand has been cancelled. %.pg -The command to use a wand is `{\tt z}' (zap). To break one, use the `{\tt a}' +The command to use a wand is `\texttt{z}' (zap). To break one, use the `\texttt{a}' (apply) command. %.hn 2 -\subsection*{Rings (`{\tt =}')} +\subsection*{Rings (`\texttt{=}')} %.pg Rings are very useful items, since they are relatively permanent @@ -2549,23 +3329,34 @@ \subsection*{Rings (`{\tt =}')} wands. %.pg -Putting on a ring activates its magic. You can wear only two -rings, one on each ring finger. +Putting on a ring activates its magic. +You can wear at most two rings at any time, one on the ring finger of +each hand. %.pg -Most rings also cause you to grow hungry more rapidly, the rate +Most worn rings also cause you to grow hungry more rapidly, the rate varying with the type of ring. %.pg -The commands to use rings are `{\tt P}' (put on) and `{\tt R}' (remove). +When wearing gloves, rings are worn underneath. +If the gloves are cursed, rings cannot be put on and any already being +worn cannot be removed. +When worn gloves aren't cursed, you don't have to manually take them +off before putting on or removing a ring and then re-wear them after. +That's done implicitly to avoid unnecessary tedium. + +%.pg +The commands to use rings are `\texttt{P}' (put on) and `\texttt{R}' (remove). +`\texttt{A}', `\texttt{W}', and `\texttt{T}' can also be used; see \textit{Amulets}. %.hn 2 -\subsection*{Spellbooks (`{\tt +}')} +\subsection*{Spellbooks (`\texttt{+}')} %.pg -Spellbooks are tomes of mighty magic. When studied with the `{\tt r}' (read) +Spellbooks are tomes of mighty magic. When studied with the `\texttt{r}' (read) command, they transfer to the reader the knowledge of a spell (and -therefore eventually become unreadable)---unless the attempt backfires. +therefore eventually become +unreadable)---unless the attempt backfires. Reading a cursed spellbook or one with mystic runes beyond your ken can be harmful to your health! @@ -2588,7 +3379,7 @@ \subsection*{Spellbooks (`{\tt +}')} %.pg Some spells require a direction in which to cast them, similar to wands. -To cast one at yourself, just give a `{\tt .}' or `{\tt s}' for the direction. +To cast one at yourself, just give a `\texttt{.}' or `\texttt{s}' for the direction. A few spells require you to pick a target location rather than just specify a particular direction. Other spells don't require any direction or target. @@ -2597,7 +3388,7 @@ \subsection*{Spellbooks (`{\tt +}')} Just as weapons are divided into groups in which a character can become proficient (to varying degrees), spells are similarly grouped. Successfully casting a spell exercises its skill group; using the -``{\tt \#enhance}'' command to advance a sufficiently exercised skill +``\texttt{\#enhance}'' command to advance a sufficiently exercised skill will affect all spells within the group. Advanced skill may increase the potency of spells, reduce their risk of failure during casting attempts, and improve the accuracy of the estimate for how much longer they will @@ -2610,14 +3401,14 @@ \subsection*{Spellbooks (`{\tt +}')} of armor may interfere with that. %.pg -The command to read a spellbook is the same as for scrolls, `{\tt r}' (read). -The `{\tt +}' command lists each spell you know along with its level, skill +The command to read a spellbook is the same as for scrolls, `\texttt{r}' (read). +The `\texttt{+}' command lists each spell you know along with its level, skill category, chance of failure when casting, and an estimate of how strongly it is remembered. -The `{\tt Z}' (cast) command casts a spell. +The `\texttt{Z}' (cast) command casts a spell. %.hn 2 -\subsection*{Tools (`{\tt (}')} +\subsection*{Tools (`\texttt{(}')} %.pg Tools are miscellaneous objects with various purposes. Some tools @@ -2626,30 +3417,73 @@ \subsection*{Tools (`{\tt (}')} be placed into or taken out of. %.pg -The command to use tools is `{\tt a}' (apply). +Some tools (such as a blindfold) can be \textit{worn} and can be put on and +removed like other accessories (rings, amulets); see \textit{Amulets}. +Other tools (such as pick-axe) can be wielded as weapons in addition to +being applied for their usual purpose, and in some cases (again, pick-axe) +become wielded as a weapon even when applied. + +%.pg +% Mentioned here because of the old method of attempting "Zen" conduct: +% restart until there's a blindfold in starting inventory and put it on +% first thing. +The \textit{blind} +option can be set (prior to game start) to attempt to play the entire +game without being able to see (a self-imposed challenge which is +very difficult to accomplish). + +%.pg +The command to use a tool is `\texttt{a}' (apply). %.hn 3 \subsection*{Containers} %.pg You may encounter bags, boxes, and chests in your travels. A tool of -this sort can be opened with the ``{\tt \#loot}'' extended command when +this sort can be opened with the ``\texttt{\#loot}'' extended command when you are standing on top of it (that is, on the same floor spot), -or with the `{\tt a}' (apply) command when you are carrying it. However, +or with the `\texttt{a}' (apply) command when you are carrying it. However, chests are often locked, and are in any case unwieldy objects. You must set one down before unlocking it by -using a key or lock-picking tool with the `{\tt a}' (apply) command, -by kicking it with the `{\tt \^{}D}' command, -or by using a weapon to force the lock with the ``{\tt \#force}'' +using a key or lock-picking tool with the `\texttt{a}' (apply) command, +by kicking it with the `\texttt{\textasciicircum D}' command, +or by using a weapon to force the lock with the ``\texttt{\#force}'' extended command. %.pg Some chests are trapped, causing nasty things to happen when you unlock or open them. You can check for and try to deactivate traps -with the ``{\tt \#untrap}'' extended command. +with the ``\texttt{\#untrap}'' extended command. + +%.pg +When the contents of a container are known, that container will be +described as something like ``a sack containing 3 items''. +In this example, the 3 refers to number of \textit{stacks} of compatible +items, not to the total number of individual items. +So a sack holding 2 sky blue potions, 7 arrows, and 350 gold pieces would be +described as having 3 items rather than 10 or 359. +And you would need to have 3 unused inventory slots available in order +to take everything out (for the case where the items you remove don't +combine into bigger stacks with things you're already carrying). + +%.pg +If a chest or large box is described as ``broken'', that means that it +can't be locked rather than that it no longer functions as a container. + +%.pg +The \textit{apply} and \textit{loot} commands allow you to take out and/or +put in an arbitrary number of items in a single operation. +If you want to take everything out of a container, you can use the +``\texttt{\#tip}'' command to pour the contents onto the floor. +This may be your only way to get things out if your hands are stuck +to a cursed two-handed weapon. +When your hands aren't stuck, you have the potential to pour the +contents into another container. +(As of this writing, the other container must be carried rather than on +the floor.) %.hn 2 -\subsection*{Amulets (`{\tt "}')} +\subsection*{Amulets (`\texttt{"}')} %.pg Amulets are very similar to rings, and often more powerful. Like @@ -2658,42 +3492,68 @@ \subsection*{Amulets (`{\tt "}')} %.pg Only one amulet may be worn at a time, around your neck. +Like wearing rings, wearing an amulet affects your metabolism, causing +you to grow hungry more rapidly. %.pg -The commands to use amulets are the same as for rings, `{\tt P}' (put on) -and `{\tt R}' (remove). +The commands to use amulets are the same as for rings, `\texttt{P}' (put on) +and `\texttt{R}' (remove). +`\texttt{A}' can be used to remove various worn items including amulets. +Also, '\texttt{W}' (wear) and `\texttt{T}' (take off) which are normally for +armor can be used for amulets and other accessories (rings and eyewear), +but accessories won't be shown as likely candidates in a prompt for +choosing what to wear or take off. %.hn 2 -\subsection*{Gems (`{\tt *}')} +\subsection*{Gems (`\texttt{*}')} %.pg -Some gems are valuable, and can be sold for a lot of gold. They are also -a far more efficient way of carrying your riches. Valuable gems increase -your score if you bring them with you when you exit. +Some gems are valuable, and can be sold for a lot of gold. +They are also a far more efficient way of carrying your riches. +Valuable gems increase your score if you bring them with you when you exit. %.pg Other small rocks are also categorized as gems, but they are much less -valuable. All rocks, however, can be used as projectile weapons (if you -have a sling). In the most desperate of cases, you can still throw them -by hand. +valuable. +All rocks, however, can be used as projectile weapons (if you have a sling). +In the most desperate of cases, you can still throw them by hand. %.hn 2 -\subsection*{Large rocks (`{\tt `}')} +\subsection*{Large rocks (`\texttt{`}')} %.pg -Statues and boulders are not particularly useful, and are generally -heavy. It is rumored that some statues are not what they seem. +Statues and boulders are not particularly useful, and are generally heavy. +It is rumored that some statues are not what they seem. %.pg -Very large humanoids (giants and their ilk) have been known to use boulders -as weapons. +Boulders occasionally block your path. +You can push one forward (by attempting to walk onto its spot) +when nothing blocks \textit{its} path, or you can +smash it into a pile of small rocks with breaking magic or a pick-axe. +It is possible to move onto a boulder's location if certain conditions +are met; ordinarily one of those conditions is that pushing it any +further be blocked. +Using the move-without-picking-up prefix (default key `\texttt{m}') +prior to the direction of movement will attempt to move to a boulder's +location without pushing it in addition to the prefix's usual action of +suppressing auto-pickup at the destination. + +%.pg +Very large humanoids (giants and their ilk) have been known to pick up +boulders and use them as missile weapons. + +%.pg +Unlike boulders, statues can't be pushed, but don't need to be because +they don't block movement. +%.\" 'rumor' above is about statue traps; this is a hint about statue contents +They can be smashed into rocks though. %.pg For some configurations of the program, statues are no longer shown -as `{\tt `}' +as `\texttt{`}' but by the letter representing the monster they depict instead. %.hn 2 -\subsection*{Gold (`{\tt \$}')} +\subsection*{Gold (`\texttt{\$}')} %.pg Gold adds to your score, and you can buy things in shops with it. @@ -2701,6 +3561,17 @@ \subsection*{Gold (`{\tt \$}')} of monsters in the dungeon that may be influenced by the amount of gold you are carrying (shopkeepers aside). +%.pg +Gold pieces are the only type of object where bless/curse state does not +apply. +They're always uncursed but never described as uncursed even if you turn +off the ``\textit{implicit\textunderscore uncursed}'' option. +You can set the ``\textit{goldX}'' +option if you prefer to have gold pieces be treated as bless/curse state +\textit{unknown} rather than as known to be uncursed. +Only matters when you're using an object selection prompt that can filter +by ``\texttt{BUCX}'' state. + %.hn 2 \subsection*{Persistence of Objects} @@ -2709,12 +3580,12 @@ \subsection*{Persistence of Objects} move to another location where you can't directly see that object any more, it will continue to be displayed on your map. That remains the case even if it is not actually there any -more---perhaps a monster has picked it up or it has rotted -away---until you can see or feel that location again. +more---perhaps a monster has picked it up or it has rotted away---until +you can see or feel that location again. One notable exception is that if the object gets covered by the ``remembered, unseen monster'' marker. When that marker is later removed -after you've verified that no monster is there, you will forget that +after you've verified that no monster is there, you will have forgotten that there was any object there regardless of whether the unseen monster actually took the object. If the object is still there, then once you see or feel that location @@ -2724,7 +3595,7 @@ \subsection*{Persistence of Objects} The situation is the same for a pile of objects, except that only the top item of the pile is displayed. The -{\it hilite\verb+_+pile\/} +\textit{hilite\textunderscore pile} option can be enabled in order to show an item differently when it is the top one of a pile. @@ -2732,10 +3603,10 @@ \subsection*{Persistence of Objects} \section{Conduct} %.pg -As if winning {\it NetHack\/} were not difficult enough, certain players +As if winning \textit{NetHack} were not difficult enough, certain players seek to challenge themselves by imposing restrictions on the way they play the game. The game automatically tracks some of -these challenges, which can be checked at any time with the {\tt \#conduct} +these challenges, which can be checked at any time with the \texttt{\#conduct} command or at the end of the game. When you perform an action which breaks a challenge, it will no longer be listed. This gives players extra ``bragging rights'' for winning the game with these @@ -2755,8 +3626,8 @@ \section{Conduct} %.pg A strict vegan diet is one which avoids any food derived from animals. The primary source of nutrition is fruits and vegetables. The -corpses and tins of blobs (`b'), jellies (`j'), and fungi (`F') are -also considered to be vegetable matter. Certain human +corpses and tins of blobs (`\texttt{b}'), jellies (`\texttt{j}'), and fungi +(`\texttt{F}') are also considered to be vegetable matter. Certain human food is prepared without animal products; namely, lembas wafers, cram rations, food rations (gunyoki), K-rations, and C-rations. Metal or another normally indigestible material eaten while polymorphed @@ -2767,7 +3638,7 @@ \section{Conduct} Vegetarians do not eat animals; however, they are less selective about eating animal byproducts than vegans. In addition to the vegan items listed above, they may eat any kind -of pudding (`P') other than the black puddings, +of pudding (`\texttt{P}') other than the black puddings, eggs and food made from eggs (fortune cookies and pancakes), food made with milk (cream pies and candy bars), and lumps of royal jelly. Monks are expected to observe a vegetarian diet. @@ -2798,8 +3669,8 @@ \section{Conduct} %.pg An atheist is one who rejects religion. This means that you cannot -{\tt \#pray}, {\tt \#offer} sacrifices to any god, -{\tt \#turn} undead, or {\tt \#chat} with a priest. +\texttt{\#pray}, \texttt{\#offer} sacrifices to any god, +\texttt{\#turn} undead, or \texttt{\#chat} with a priest. Particularly selective readers may argue that playing Monk or Priest characters should violate this conduct; that is a choice left to the player. Offering the Amulet of Yendor to your god is necessary to @@ -2808,6 +3679,15 @@ \section{Conduct} other religious figure; a true atheist would hear the words but attach no special meaning to them. +%.pg +A pauper starts the game with no possessions, no spells, and no weapon or +spell skills (and if playing as a knight, your pony will not have a saddle). +Can only be initiated by starting a new game with \texttt{OPTIONS=pauper} +set in your run-time configurtion file or \texttt{NETHACKOPTIONS} environment +variable. +Once the game is underway, you can acquire and use items, spells, and skills +in the usual way. + %.pg Most players fight with a wielded weapon (or tool intended to be wielded as a weapon). Another challenge is to win the game without @@ -2816,13 +3696,13 @@ \section{Conduct} or fight with your hands and feet. %.pg -In {\it NetHack}, a pacifist refuses to cause the death of any other monster +In \textit{NetHack}, a pacifist refuses to cause the death of any other monster (i.e. if you would get experience for the death). This is a particularly difficult challenge, although it is still possible to gain experience by other means. %.pg -An illiterate character cannot read or write. This includes reading +An illiterate character does not read or write. This includes reading a scroll, spellbook, fortune cookie message, or t-shirt; writing a scroll; or making an engraving of anything other than a single ``X'' (the traditional signature of an illiterate person). Reading an engraving, @@ -2832,6 +3712,33 @@ \section{Conduct} learned from your teachers prior to the start of the game and isn't counted. +%.pg +There is a side-branch to the main dungeon called ``Sokoban,'' briefly +described in the earlier section about \textit{Traps}. +As mentioned there, the goal is to push boulders into pits and/or holes +to plug those in order to both get the boulders out of your way and be +able to go past the traps. +There are some special ``rules'' that are active when in that branch +of the dungeon. +Some rules can't be bypassed, such as being unable to push a boulder +diagonally. +Other rules can, such as not smashing boulders with magic or tools, +but doing so causes you to receive a luck penalty. +No message about that is given at the time, but it is tracked as a conduct. +The \texttt{\#conduct} command and end of game disclosure will report whether +you have abided by the special rules of Sokoban, and if not, how many +times you violated them, providing you with a way to discover which +actions incur bad luck so that you can be better informed about whether +or not to avoid repeating those actions in the future. +(Note: the Sokoban conduct will only be displayed if you have +entered the Sokoban branch of the dungeon during the current game. +Once that has happened, it becomes part of disclosed conduct even if +you haven't done anything interesting there. +Ending the game with ``never broke the Sokoban rules'' conduct is most +meaningful if you also manage to perform +the ``obtained the Sokoban prize'' achievement +(see \textit{Achievements} below).) + %.pg There are several other challenges tracked by the game. It is possible to eliminate one or more species of monsters by genocide; playing without @@ -2849,23 +3756,148 @@ \section{Conduct} game offers you an opportunity to make a wish for an item, you may choose ``nothing'' if you want to decline. +%.hn 2 +\subsection*{Achievements} + +%.pg +End of game disclosure will also display various achievements +representing progress toward ultimate ascension, if any have been +attained. +They aren't directly related to \textit{conduct} but are grouped with +it because they fall into the same category of ``bragging rights'' +and to limit the number of questions during disclosure. +Listed here roughly in order of difficulty and not necessarily in the order +in which you might accomplish them. + +% [length stuff copied from paranoid_confirmation] +\newlength{\achwidth} +%.PS "Mines'\~End\~" +\settowidth{\achwidth}{\texttt{Mines'~End~}} +\addtolength{\achwidth}{\labelsep} +\begin{description}[leftmargin=\achwidth, topsep=1mm, itemsep=0mm, labelwidth=*, font=\ttfamily, align=right] +%.PL Shop +\item[] +Attained rank title \textit{Rank}. +\item[Shop] +Entered a shop. +\item[Temple] +Entered a temple. +\item[Mines] +Entered the Gnomish Mines. +\item[Town] +Entered Mine Town. +\item[Oracle] +Consulted the Oracle of Delphi. +\item[Novel] +Read a passage from a Discworld Novel. +\item[Sokoban] +Entered Sokoban. +\item["Big~Room"] +Entered the Big Room. +\item["Soko-Prize"] +Explored to the top of Sokoban and found a special item there. +\item[Mines'~End] +Explored to the bottom of the Gnomish Mines and found a special item there. +\item[Medusa] +Defeated Medusa. +\item[Tune] +Discovered the tune that can be used to open and close the drawbridge on +the Castle level. +\item[Bell] +Acquired the Bell of Opening. +\item[Gehennom] +Entered Gehennom. +\item[Candle] +Acquired the Candelabrum of Invocation. +\item[Book] +Acquired the Book of the Dead. +\item[Invocation] +Gained access to the bottommost level of Gehennom. +\item[Amulet] +Acquired the fabled Amulet of Yendor. +\item[Endgame] +Reached the Elemental Planes. +\item[Astral] +Reached the Astral Plane level. +\item[Blind] +Blind from birth. +\item[Deaf] +Deaf from birth. +\item[Nudist] +Never wore any armor. +\item[Pauper] +Started out with no possessions. +\item[Ascended] +Delivered the Amulet to its final destination. +\end{description} +%.PE +%.ED + +%.lp "Notes: " +\noindent +Notes: + +%.pg +Achievements are recorded and subsequently reported in the order in which +they happen during your current game rather than the order listed here. + +%.pg +There are nine \textit{Rank} titles for each role, bestowed at experience +levels 1, 3, 6, 10, 14, 18, 22, 26, and 30. +The one for experience level 1 is not recorded as an achievement. +Losing enough levels to revert to lower rank(s) does not discard the +corresponding achievement(s). + +%.pg +There's no guaranteed \textit{Novel} so the achievement to read one might +not always be attainable (except perhaps by wishing). +Similarly, the \textit{Big Room} level is not always present. +Unlike with the Novel, there's no way to wish for this opportunity. + +%.pg +The ``special items'' hidden in \textit{Mines'~End} and \textit{Sokoban} +are not unique but are considered to be prizes or rewards +for exploring those levels since doing so is not necessary to complete +the game. +Finding other instances of the same objects doesn't record the +corresponding achievement. + +%.pg +The \textit{Medusa} achievement is recorded if she dies for any reason, +even if you are not directly responsible, and only if she dies. + +%.pg +The 5-note \textit{tune} can be learned via trial and error with a musical +instrument played closely +enough---but not too close!---to +the Castle level's drawbridge or can be given to you via prayer boon. + +%.pg +\textit{Blind}, \textit{Deaf}, \textit{Nudist}, and \textit{Pauper} are also conducts, and they can only be +enabled by setting the correspondingly named option in \texttt{NETHACKOPTIONS} +or run-time configuration file prior to game start. +In the case of \textit{Blind} and \textit{Deaf}, the option also enforces the +conduct. +They aren't really significant accomplishments unless/until you make +substantial progress into the dungeon. + %.hn 1 \section{Options} %.pg -Due to variations in personal tastes and conceptions of how {\it NetHack\/} -should do things, there are options you can set to change how {\it NetHack\/} +Due to variations in personal tastes and conceptions of how \textit{NetHack} +should do things, there are options you can set to change how \textit{NetHack} behaves. %.hn 2 \subsection*{Setting the options} %.pg -Options may be set in a number of ways. Within the game, the `{\tt O}' +Options may be set in a number of ways. Within the game, the `\texttt{O}' command allows you to view all options and change most of them. You can also set options automatically by placing them in a configuration -file, or in the ``NETHACKOPTIONS'' environment variable. -Some versions of {\it NetHack\/} also have front-end programs that allow +file, or in the ``\texttt{NETHACKOPTIONS}'' environment variable. +Some versions of \textit{NetHack} also have front-end programs that allow you to set options before starting the game or a global configuration for system administrators. @@ -2877,54 +3909,64 @@ \subsection*{Using a configuration file} operating systems.\\ %.lp "" -On Unix, Linux and Mac OS X it is \mbox{``.nethackrc''} in the user's home -directory. The file may not exist, but it is a normal ASCII text file and +On UNIX, Linux and macOS it is \mbox{``.nethackrc''} in the user's home +directory. +The file may not exist, but it is a normal ASCII text file and can be created with any text editor.\\ %.lp "" -On Windows, it is \mbox{``.nethackrc''} in the folder -\mbox{{``\%USERPROFILE\%\textbackslash NetHack\textbackslash''}}. The -file may not exist, but it is a normal ASCII text file and can be created -with any text editor. -After runing {\it NetHack\/} for the first time, you should find a default +On Windows, the name is \mbox{``.nethackrc''} location in the folder +\mbox{{``\%USERPROFILE\%\textbackslash NetHack\textbackslash''}}. +The file may not exist, +but it is a normal ASCII text file and can be created with any +text editor. +After running \textit{NetHack} for the first time, you should find a default template for ths configuration file named \mbox{``.nethackrc.template''} in \mbox{{``\%USERPROFILE\%\textbackslash NetHack\textbackslash''}}. -If you had not created the configuration file, {\it NetHack\/} will create -the configuration file for you using the default template file. +If you have not created the configuration file, \textit{NetHack} will create +the configuration file for you using the default template file.\\ %.lp "" On MS-DOS it is \mbox{``defaults.nh''} in the same folder as -\mbox{{\it nethack.exe\/}}.\\ +\mbox{\textit{nethack.exe}}.\\ %.lp "" -Any line in the configuration file starting with `{\tt \#}' is treated as a comment. -Empty lines are ignored. Any line beginning with `{\tt [}' and ending in `{\tt ]}' is considered a section -marker. The text between the square brackets is the section name. -Lines after a section marker belong to that section, and are -ignored unless a CHOOSE -statement was used to select that section. -Section names are case insensitive. - -%.pg -You can use different configuration statements in the file, some +Any line in the configuration file starting with `\texttt{\#}' is treated +as a comment and ignored. +Empty lines are ignored. + +Any line beginning with `\texttt{[}' and ending in `\texttt{]}' +is a section marker (the closing `\texttt{]}' can be followed +by whitespace and then an arbitrary comment beginning with `\texttt{\#}'). +The text between the square brackets is the section name. +Section markers are only valid after a CHOOSE directive and their names +are case-insensitive. +Lines after a section marker belong to that section up until another +section starts or a marker without a name is encountered or the file ends. +Lines within sections are ignored unless a CHOOSE directive has selected +that section. + +%.pg +You can use different configuration directives in the file, some of which can be used multiple times. -In general, the statements are +In general, the directives are written in capital letters, followed by an equals sign, followed by -settings particular to that statement. +settings particular to that directive. %.pg -Here is a list of allowed statements: +Here is a list of allowed directives: %.lp -\blist{} -\item[\bb{OPTIONS}] +\begin{description} +\item[OPTIONS] There are two types of options, boolean and compound options. Boolean options toggle a setting on or off, while compound options take more diverse values. Prefix a boolean option with `no' or `!' to turn it off. For compound options, the option name and value are separated by a colon. Some options are persistent, and apply only to new games. -You can specify multiple OPTIONS statements, and multiple options -separated by commas in a single OPTIONS statement. +You can specify multiple OPTIONS directives, and multiple options +separated by commas in a single OPTIONS directive. (Comma separated options are processed from right to left.) %.lp "" @@ -2937,40 +3979,40 @@ \subsection*{Using a configuration file} %.ed %.lp -\item[\bb{HACKDIR}] -Default location of files {\it NetHack\/} needs. On Windows HACKDIR -defaults to the location of the {\it NetHack.exe\/} or {\it NetHackw.exe\/} file +\item[HACKDIR] +Default location of files \textit{NetHack} needs. On Windows HACKDIR +defaults to the location of the \textit{NetHack.exe} or \textit{NetHackw.exe} file so setting HACKDIR to override that is not usually necessary or recommended. %.lp -\item[\bb{LEVELDIR}] +\item[LEVELDIR] The location that in-progress level files are stored. Defaults to HACKDIR, must be writable. %.lp -\item[\bb{SAVEDIR}] +\item[SAVEDIR] The location where saved games are kept. Defaults to HACKDIR, must be writable. %.lp -\item[\bb{BONESDIR}] +\item[BONESDIR] The location that bones files are kept. Defaults to HACKDIR, must be writable. %.lp -\item[\bb{LOCKDIR}] +\item[LOCKDIR] The location that file synchronization locks are stored. Defaults to HACKDIR, must be writable. %.lp -\item[\bb{TROUBLEDIR}] +\item[TROUBLEDIR] The location that a record of game aborts and self-diagnosed game problems is kept. Defaults to HACKDIR, must be writable. % % config file entries beyond this point are shown alphabetically % %.lp -\item[\bb{AUTOCOMPLETE}] +\item[AUTOCOMPLETE] Enable or disable an extended command autocompletion. Autocompletion has no effect for the X11 windowport. You can specify multiple autocompletions. To enable autocompletion, list the extended command. Prefix the -command with ``{{\tt !}}'' to disable the autocompletion +command with ``\texttt{!}'' to disable the autocompletion for that command. %.lp "" @@ -2982,14 +4024,14 @@ \subsection*{Using a configuration file} %.ed %.lp -\item[\bb{AUTOPICKUP\_EXCEPTION}] -Set exceptions to the {{\it pickup\_types\/}} +\item[AUTOPICKUP\textunderscore EXCEPTION] +Set exceptions to the {\textit{pickup\textunderscore types}} option. See the ``Configuring Autopickup Exceptions'' section. %.lp -\item[\bb{BINDINGS}] -Change the key bindings of some special keys, menu accelerators, or -extended commands. You can specify multiple bindings. Format is key -followed by the command, separated by a colon. +\item[BINDINGS] +Change the key bindings of some special keys, menu accelerators, +extended commands, or mouse buttons. You can specify multiple bindings. +Format is key followed by the command, separated by a colon. See the ``Changing Key Bindings`` section for more information. %.lp "" @@ -3001,9 +4043,10 @@ \subsection*{Using a configuration file} %.ed %.lp -\item[\bb{CHOOSE}] +\item[CHOOSE] Chooses at random one of the comma-separated parameters as an active -section name. Lines in other sections are ignored. +section name. +Lines in other sections are ignored. %.lp "" Example: @@ -3015,34 +4058,41 @@ \subsection*{Using a configuration file} OPTIONS=role:arc,race:dwa,align:law,gender:fem [char B] OPTIONS=role:wiz,race:elf,align:cha,gender:mal + [] #end of CHOOSE + OPTIONS=!rest_on_space \end{verbatim} %.ed +%.lp "" +If \texttt{[]} is present, the preceding section is closed and no new +section begins; whatever follows will be common to all sections. +Otherwise the last section extends to the end of the options file. + %.lp -\item[\bb{MENUCOLOR}] +\item[MENUCOLOR] Highlight menu lines with different colors. See the ``Configuring Menu Colors`` section. %.lp -\item[\bb{MSGTYPE}] -Change the way messages are shown in the top status line. +\item[MSGTYPE] +Change the way messages are shown in the top line. See the ``Configuring Message Types`` section. %.lp -\item[\bb{ROGUESYMBOLS}] -Custom symbols for for the rogue level's symbol set. -See {\it SYMBOLS} below. +\item[ROGUESYMBOLS] +Custom symbols for the rogue level's symbol set. +See \textit{SYMBOLS} below. %.lp -\item[\bb{SOUND}] +\item[SOUND] Define a sound mapping. See the ``Configuring User Sounds'' section. %.lp -\item[\bb{SOUNDDIR}] +\item[SOUNDDIR] Define the directory that contains the sound files. See the ``Configuring User Sounds'' section. %.lp -\item[\bb{SYMBOLS}] +\item[SYMBOLS] Override one or more symbols in the symbol set used for all dungeon levels except for the special rogue level. -See the ``Modifying {\it NetHack\/} Symbols'' section. +See the ``Modifying \textit{NetHack} Symbols'' section. %.pg %.lp "" @@ -3050,16 +4100,17 @@ \subsection*{Using a configuration file} %.sd \begin{verbatim} # replace small punctuation (tick marks) with digits - SYMBOLS=S_boulder:0,S_golem:7 + SYMBOLS=S_golem:7 \end{verbatim} %.ed %.lp -\item[\bb{WIZKIT}] +\item[WIZKIT] Debug mode only: extra items to add to initial inventory. Value is the name of a text file containing a list of item names, one per line, up to a maximum of 128 lines. Each line is processed by the function that handles wishing. +Entries are added to the wish history; see the wizwish-command. %.lp "" Example: @@ -3068,7 +4119,7 @@ \subsection*{Using a configuration file} WIZKIT=~/wizkit.txt \end{verbatim} %.ed -\elist +\end{description} %.lp "" %.pg @@ -3086,7 +4137,8 @@ \subsection*{Using a configuration file} OPTIONS=lit_corridor # Show lit corridors differently OPTIONS=hilite_pet,hilite_pile # Replace small punctuation (tick marks) with digits - SYMBOLS=S_boulder:0,S_golem:7 + OPTIONS=boulder:0 + SYMBOLS=S_golem:7 # No startup splash screen. Windows GUI only. OPTIONS=!splash_screen @@ -3095,13 +4147,13 @@ \subsection*{Using a configuration file} %.BR 2 %.hn 2 -\subsection*{Using the NETHACKOPTIONS environment variable} +\subsection*{Using the \texttt{NETHACKOPTIONS} environment variable} %.pg The NETHACKOPTIONS variable is a comma-separated list of initial values for the various options. Some can only be turned on or off. You turn one of these on by adding the name of the option to the list, -and turn it off by typing a `{\tt !}' or ``{\tt no}'' before the name. +and turn it off by typing a `\texttt{!}' or ``\texttt{no}'' before the name. Others take a character string as a value. You can set string options by typing the option name, a colon or equals sign, and then the value of the string. @@ -3109,10 +4161,10 @@ \subsection*{Using the NETHACKOPTIONS environment variable} %.pg For example, to set up an environment variable so that -{\it color\/} is {\tt on}, -{\it legacy\/} is {\tt off}, -character {\it name\/} is set to ``{\tt Blue Meanie}'', -and named {\it fruit\/} is set to ``{\tt lime}'', +\textit{color} is \texttt{on}, +\textit{legacy} is \texttt{off}, +character \textit{name} is set to ``\texttt{Blue Meanie}'', +and named \textit{fruit} is set to ``\texttt{lime}'', you would enter the command %.SD i \begin{verbatim} @@ -3120,7 +4172,7 @@ \subsection*{Using the NETHACKOPTIONS environment variable} \end{verbatim} %.ED -\nd in {\it csh} +\noindent in \textit{csh} (note the need to escape the `!' since it's special to that shell), or the pair of commands %.SD i @@ -3130,23 +4182,23 @@ \subsection*{Using the NETHACKOPTIONS environment variable} \end{verbatim} %.ED -\nd in {\it sh}, {\it ksh}, or {\it bash}. +\noindent in \textit{sh}, \textit{ksh}, or \textit{bash}. %.pg The NETHACKOPTIONS value is effectively the same as a single OPTIONS -statement in a configuration file. +directive in a configuration file. The ``OPTIONS='' prefix is implied and comma separated options are processed from right to left. -Other types of configuration statements such as BIND or MSGTYPE are +Other types of configuration directives such as BIND or MSGTYPE are not allowed. %.pg Instead of a comma-separated list of options, NETHACKOPTIONS can be set to the full name of a configuration file you want to use. -If that full name doesn't start with a slash, precede it with `{\tt @}' +If that full name doesn't start with a slash, precede it with `\texttt{@}' (at-sign) to let NetHack know that the rest is intended as a file name. -If it does start with `{\tt /}', the at-sign is optional. +If it does start with `\texttt{/}', the at-sign is optional. %.hn 2 \subsection*{Customization options} @@ -3161,40 +4213,71 @@ \subsection*{Customization options} the game. Changing a persistent option in the configuration file applies only to new games. -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{acoustics}] +\item[accessiblemsg] +Add location or direction information to messages (default is off). +%.lp +\item[acoustics] Enable messages about what your character hears (default on). Note that this has nothing to do with your computer's audio capabilities. Persistent. %.lp -\item[\ib{align}] -Your starting alignment ({\tt align:lawful}, {\tt align:neutral}, -or {\tt align:chaotic}). You may specify just the first letter. -The default is to randomly pick an appropriate alignment. -If you prefix the value with `{\tt !}' or ``{\tt no}'', you will -exclude that alignment from being picked randomly. -Cannot be set with the `{\tt O}' command. Persistent. +\item[alignment] +Your starting alignment (\texttt{align:lawful}, \texttt{align:neutral}, +or \texttt{align:chaotic}). +You may specify just the first letter. +Many roles and the non-human races restrict which alignments are allowed. +See \textit{role} +for a description of how to use negation to exclude choices. +%.lp "" +\\ +If \texttt{align} is not specified, there is no default value; +player will be prompted unless role and/or race forces a choice for alignment. +Cannot be set with the `\texttt{O}' command. Persistent. %.lp -\item[\ib{autodescribe}] +\item[armorstatus] +Display an extra status condition which summarizes currently worn armor +(default off, not supported by all interfaces). +%.lp "" +\\ +For the usual case where more than one piece of armor is worn, a list of +letters is shown in the following order: +\\ +\texttt{G} - gloves;\\ +\texttt{C} - cloak;\\ +\texttt{A} - suit;\\ +\texttt{U} - shirt;\\ +\texttt{H} - helmet;\\ +\texttt{B} - boots;\\ +\texttt{S} - shield. +\item[autodescribe] Automatically describe the terrain under cursor when asked to get a location on the map (default true). -The {\it whatis\verb+_+coord\/} +The \textit{whatis\textunderscore coord} option controls whether the description includes map coordinates. %.lp -\item[\ib{autodig}] +\item[autodig] Automatically dig if you are wielding a digging tool and moving into a place that can be dug (default false). Persistent. %.lp -\item[\ib{autoopen}] -Walking into a door attempts to open it (default true). Persistent. +\item[autoopen] +Walking into a closed door attempts to open it (default true). +Persistent. %.lp -\item[\ib{autopickup}] -Automatically pick up things onto which you move (default on). Persistent. -See ``{\it pickup\verb+_+types\/}'' to refine the behavior. +\item[autopickup] +Automatically pick up things onto which you move (default off). +Persistent. +\\ +%.lp "" +See ``\textit{pickup\textunderscore types}'' and also +``\textit{autopickup\textunderscore exception}'' for ways to refine the behavior. +\\ +%.lp "" +Note: prior to version 5.0.0, the default for \textit{autopickup} was \textit{on}. %.lp -\item[\ib{autoquiver}] -This option controls what happens when you attempt the `f' (fire) +\item[autoquiver] +This option controls what happens when you attempt the `\texttt{f}' (fire) command when nothing is quivered or readied (default false). When true, the computer will fill your quiver or quiver sack or make ready some suitable weapon. @@ -3202,71 +4285,119 @@ \subsection*{Customization options} into account the blessed/cursed status, enchantment, damage, or quality of the weapon; you are free to manually fill your quiver or quiver sack or make ready -with the `Q' command instead. +with the `\texttt{Q}' command instead. If no weapon is found or the option is -false, the `t' (throw) command is executed instead. Persistent. +false, the `\texttt{t}' (throw) command is executed instead. Persistent. +%.lp +\item[autounlock] +%\hyphenation{apply\-key}%this needs to be tested... +Controls what action to take when attempting to walk into a locked door +or to loot a locked container. +Takes a plus-sign separated list of values: +% paranoid +% au => autounlock +\newlength{\auwidth} +%.PS Apply-Key +\settowidth{\auwidth}{\texttt{Apply-Key}} +\addtolength{\auwidth}{\labelsep} +\begin{description}[leftmargin=\auwidth, topsep=1mm, itemsep=0mm, labelwidth=*, font=\ttfamily, align=right] +%.PL Untrap +\item[Untrap] +prompt about whether to attempt to find a trap; +it might fail to find one even when present; if it does find one, it +will ask whether you want to try to disarm the trap; if you decline, +your character will forget that the door or box is trapped; +%.PL Apply-Key +\item[Apply-Key] +if carrying a key or other unlocking tool, prompt about using it; +%.PL Kick +\item[Kick] +kick the door (if you omit untrap or decline to attempt untrap and +you omit apply-key or you lack a key or you decline to use the key; +has no effect on containers); +%.PL Force +\item[Force] +try to force a container's lid with your currently +wielded weapon (if you omit untrap or decline to attempt untrap and +you omit apply-key or you lack a key or you decline to use the key; +has no effect on doors); +%.PL None +\item[None] +none of the above; can't be combined with the other choices. +%.PE +\end{description} +Omitting the value is treated as if \texttt{autounlock:apply-key}. +Preceding \texttt{autounlock} with `\texttt{!}' or ``\texttt{no}'' is treated as +\texttt{autounlock:none}. +\\ +%.lp "" +Applying a key might set off a trap if the door or container is trapped. +Successfully kicking a door will break it and wake up nearby monsters. +Successfully forcing a container open will break its lock and might also +destroy some of its contents or damage your weapon or both. +\\ +%.lp "" +The default is Apply-Key. +Persistent. %.lp -\item[\ib{blind}] +\item[blind] Start the character permanently blind (default false). Persistent. %.lp -\item[\ib{bones}] +\item[bones] Allow saving and loading bones files (default true). Persistent. %.lp -\item[\ib{boulder}] +\item[boulder] Set the character used to display boulders (default is the ``large rock'' -class symbol, `{\tt `}'). +class symbol, `\texttt{`}'). %.lp -\item[\ib{catname}] -Name your starting cat (for example, ``{\tt catname:Morris}''). -Cannot be set with the `{\tt O}' command. +\item[catname] +Name your starting cat (for example, ``\texttt{catname:Morris}''). +Cannot be set with the `\texttt{O}' command. %.lp character -\item[\ib{character}] -Pick your type of character (for example, ``{\tt character:Monk}''); -synonym for ``{\it role\/}''. See {\it role\/} for more details. +\item[character] +Synonym for ``\texttt{role}'' to pick the type of your character +(for example ``\texttt{character:Monk}''). See \textit{role} for more details. %.lp -\item[\ib{checkpoint}] +\item[checkpoint] Save game state after each level change, for possible recovery after program crash (default on). Persistent. %.lp -\item[\ib{checkspace}] -Check free disk space before writing files to disk (default on). -You may have to turn this off if you have more than 2 GB free space -on the partition used for your save and level files -(because too much space might overflow the calculation and end up -looking like insufficient space). -Only applies when MFLOPPY was defined during compilation. -%.lp -\item[\ib{clicklook}] -Allows looking at things on the screen by navigating the mouse -over them and clicking the right mouse button (default off). -%.lp -\item[\ib{cmdassist}] +\item[cmdassist] Have the game provide some additional command assistance for new players if it detects some anticipated mistakes (default on). %.lp -\item[\ib{confirm}] +\item[confirm] Have user confirm attacks on pets, shopkeepers, and other peaceable creatures (default on). Persistent. %.lp -%.lp -\item[\ib{dark\verb+_+room}] +\item[dark\textunderscore room] Show out-of-sight areas of lit rooms (default on). Persistent. -\item[\ib{disclose}] +%.lp +\item[deaf] +Start the character permanently deaf (default false). Persistent. +%.lp +\item[dropped\textunderscore nopick] +If this option is on, items you dropped will not be automatically picked up, +even if ``\textit{autopickup}'' is also on and they are in +``\textit{pickup\textunderscore types}'' or match a positive autopickup exception +(default on). Persistent. +%.lp +\item[disclose] Controls what information the program reveals when the game ends. Value is a space separated list of prompting/category pairs -(default is `{\tt ni na nv ng nc no}', -prompt with default response of `{\tt n}' for each candidate). +(default is `\texttt{ni na nv ng nc no}', +prompt with default response of `\texttt{n}' for each candidate). Persistent. The possibilities are: %.sd %.si -{\tt i} --- disclose your inventory;\\ -{\tt a} --- disclose your attributes;\\ -{\tt v} --- summarize monsters that have been vanquished;\\ -{\tt g} --- list monster species that have been genocided;\\ -{\tt c} --- display your conduct;\\ -{\tt o} --- display dungeon overview. +\texttt{i} --- disclose your inventory;\\ +\texttt{a} --- disclose your attributes;\\ +\texttt{v} --- summarize monsters that have been vanquished;\\ +\texttt{g} --- list monster species that have been genocided;\\ +\texttt{c} --- display your conduct; also achievements, if any;\\ +\texttt{o} --- display dungeon overview. %.ei %.ed @@ -3275,38 +4406,45 @@ \subsection*{Customization options} %.sd %.si -{\tt y} --- prompt you and default to yes on the prompt;\\ -{\tt n} --- prompt you and default to no on the prompt;\\ -{\tt +} --- disclose it without prompting;\\ -{\tt -} --- do not disclose it and do not prompt. +\texttt{y} --- prompt you and default to yes on the prompt;\\ +\texttt{n} --- prompt you and default to no on the prompt;\\ +\texttt{+} --- disclose it without prompting;\\ +\texttt{-} --- do not disclose it and do not prompt. %.ei %.ed The listing of vanquished monsters can be sorted, -so there are two additional choices for `{\tt v}': +so there are two additional choices for `\texttt{v}': +The listings of vanquished monsters and of genocided types can be sorted, +so there are two additional choices for `q' and `g': %.sd %.si -{\tt ?} --- prompt you and default to ask on the prompt;\\ +\texttt{?} --- prompt you and default to ask on the prompt;\\ {\tt\#} --- disclose it without prompting, ask for sort order. %.ei %.ed Asking refers to picking one of the orderings from a menu. -The `{\tt +}' disclose without prompting choice, -or being prompted and answering `{\tt y}' rather than `{\tt a}', -will default to showing monsters in the traditional order, -from high level to low level.\\ -.lp "" +The `\texttt{+}' disclose without prompting choice, +or being prompted and answering `\texttt{y}' rather than `\texttt{a}', +will default to showing monsters in the order specified by the +\textit{sortvanquished} option. +\\ +%.lp "" +Omitted categories are implicitly added with `\texttt{n}' prefix. +Specified categories with omitted prefix implicitly use `\texttt{+}' prefix. +Order of the disclosure categories does not matter, program display for +end-of-game disclosure follows a set sequence. %.lp "" -(for example, ``{\tt disclose:yi na +v -g o}'') +(for example, ``\texttt{disclose:yi na +v -g o}'') The example sets -{\tt inventory} to {\it prompt\/} and default to {\it yes\/}, -{\tt attributes} to {\it prompt\/} and default to {\it no\/}, -{\tt vanquished} to {\it disclose without prompting\/}, -{\tt genocided} to {\it not disclose\/} and {\it not prompt\/}, -{\tt conduct} to implicitly {\it prompt\/} and default to {\it no\/}, -{\tt overview} to {\it disclose without prompting\/}. +\texttt{inventory} to \textit{prompt} and default to \textit{yes}, +\texttt{attributes} to \textit{prompt} and default to \textit{no}, +\texttt{vanquished} to \textit{disclose without prompting}, +\texttt{genocided} to \textit{not disclose} and \textit{not prompt}, +\texttt{conduct} to implicitly \textit{prompt} and default to \textit{no}, +\texttt{overview} to \textit{disclose without prompting}. %.lp "" Note that the vanquished monsters list includes all monsters killed by @@ -3314,11 +4452,11 @@ \subsection*{Customization options} And the dungeon overview shows all levels you had visited but does not reveal things about them that you hadn't discovered. %.lp -\item[\ib{dogname}] -Name your starting dog (for example, ``{\tt dogname:Fang}''). -Cannot be set with the `{\tt O}' command. +\item[dogname] +Name your starting dog (for example, ``\texttt{dogname:Fang}''). +Cannot be set with the `\texttt{O}' command. %.lp -\item[\ib{extmenu}] +\item[extmenu] Changes the extended commands interface to pop-up a menu of available commands. It is keystroke compatible with the traditional interface except that it does not require that you hit Enter. @@ -3329,120 +4467,171 @@ \subsection*{Customization options} or just the subset of commands which have traditionally been considered extended ones (off). %.lp -\item[\ib{female}] -An obsolete synonym for ``{\tt gender:female}''. Cannot be set with the -`{\tt O}' command. +\item[female] +An obsolete synonym for ``\texttt{gender:female}''. Cannot be set with the +`\texttt{O}' command. %.lp -\item[\ib{fixinv}] +\item[fireassist] +This option controls what happens when you attempt the `\texttt{f}' (fire) +and don't have an appropriate launcher, such as a bow or a sling, wielded. +If on, you will automatically wield the launcher. Default is on. +%.lp +\item[fixinv] An object's inventory letter sticks to it when it's dropped (default on). If this is off, dropping an object shifts all the remaining inventory letters. Persistent. %.lp -\item[\ib{force\_invmenu}] +\item[force\textunderscore invmenu] Commands asking for an inventory item show a menu instead of a text query with possible menu letters. Default is off. %.lp -\item[\ib{fruit}] -Name a fruit after something you enjoy eating (for example, ``{\tt fruit:mango}'') -(default ``{\tt slime mold}''). Basically a nostalgic whimsy that -{\it NetHack\/} uses from time to time. You should set this to something you +\item[fruit] +Name a fruit after something you enjoy eating (for example, ``\texttt{fruit:mango}'') +(default ``\texttt{slime mold}''). Basically a nostalgic whimsy that +\textit{NetHack} uses from time to time. You should set this to something you find more appetizing than slime mold. Apples, oranges, pears, bananas, and -melons already exist in {\it NetHack\/}, so don't use those. -%.lp -\item[\ib{gender}] -Your starting gender ({\tt gender:male} or {\tt gender:female}). -You may specify just the first letter. Although you can -still denote your gender using the ``{\tt male}'' and ``{\tt female}'' -options, the ``{\tt gender}'' option will take precedence. -The default is to randomly pick an appropriate gender. -If you prefix the value with `{\tt !}' or ``{\tt no}'', you will -exclude that gender from being picked randomly. -Cannot be set with the `{\tt O}' command. Persistent. -%.lp -\item[\ib{goldX}] +melons already exist in \textit{NetHack}, so don't use those. +%.lp +\item[gender] +Your starting gender (\texttt{gender:male} or \texttt{gender:female}). +You may specify just the first letter. +Although you can +still denote your gender using either of the deprecated +``\textit{male}'' and ``\textit{female}'' +options, the ``\textit{gender}'' option will take precedence. +See \textit{role} +for a description of how to use negation to exclude choices. +%.lp "" +\\ +If \texttt{gender} is not specified, there is no default value; +player will be prompted unless role and/or race forces a choice for gender. +Cannot be set with the `\texttt{O}' command. Persistent. +%.lp +\item[goldX] When filtering objects based on bless/curse state (BUCX), whether to -treat gold pieces as {\tt X} (unknown bless/curse state, when `on') -or {\tt U} (known to be uncursed, when `off', the default). +treat gold pieces as \texttt{X} (unknown bless/curse state, when `on') +or \texttt{U} (known to be uncursed, when `off', the default). Gold is never blessed or cursed, but it is not described as ``uncursed'' -even when the {\it implicit\verb+_+uncursed\/} option is `off'. +even when the \textit{implicit\textunderscore uncursed} option is `off'. %.lp -\item[\ib{help}] +\item[help] If more information is available for an object looked at -with the `{\tt /}' command, ask if you want to see it (default on). +with the `\texttt{/}' command, ask if you want to see it (default on). Turning help off makes just looking at things faster, since you aren't -interrupted with the ``{\tt More info?}'' prompt, but it also means that you +interrupted with the ``\texttt{More info?}'' prompt, but it also means that you might miss some interesting and/or important information. Persistent. %.lp -\item[\ib{herecmd\verb+_+menu}] +\item[herecmd\textunderscore menu] When using a windowport that supports mouse and clicking on yourself or next to you, show a menu of possible actions for the location. -Same as ``{\tt \#herecmdmenu}'' and ``{\tt \#therecmdmenu}'' commands. +Same as ``\texttt{\#herecmdmenu}'' and ``\texttt{\#therecmdmenu}'' commands. %.lp -\item[\ib{hilite\verb+_+pet}] +\item[hilite\textunderscore pet] Visually distinguish pets from similar animals (default off). The behavior of this option depends on the type of windowing you use. In text windowing, text highlighting or inverse video is often used; with tiles, generally displays a heart symbol near pets. + %.lp "" -With the curses interface, the {\it petattr\/} +With the tty or curses interface, the \textit{petattr} option controls how to highlight pets and setting it will turn the -{\it hilite\verb+_+pet\/} option on or off as warranted. +\textit{hilite\textunderscore pet} option on or off as warranted. %.lp -\item[\ib{hilite\verb+_+pile}] +\item[hilite\textunderscore pile] Visually distinguish piles of objects from individual objects (default off). The behavior of this option depends on the type of windowing you use. In text windowing, text highlighting or inverse video is often used; with tiles, generally displays a small plus-symbol beside the object on the top of the pile. %.lp -\item[\ib{horsename}] -Name your starting horse (for example, ``{\tt horsename:Trigger}''). -Cannot be set with the `{\tt O}' command. +\item[hitpointbar] +Show a hit point bar graph behind your name and title in the status +display (default off). +\\ +%.lp +The ``curses'' interface supports it even if the status highlighting +feature has been disabled when building the program. +The ``tty'' and ``mswin'' (aka ``Windows GUI'') interfaces +support it only if status highlighting is left enabled when building. +You don't need to set up any highlighting rules in order to display +the bar. +If there is one for hitpoints in effect and it specifies color, that +color will be used for the bar. +However if it specifies video attributes, they will be ignored in +favor of \textit{inverse}. +For tty and curses, \textit{blink} will also be used if the current +hitpoint value is at or below the \textit{critical HP} threshold. +\\ %.lp -\item[\ib{hitpointbar}] -Show a hit point bar graph behind your name and title. -Only available for TTY and Windows GUI, and only when statushilites is on. +The ``Qt'' interface also supports hitpointbar, by drawing +a solid bar above the name and title with a hard-coded color scheme. +(As of this writing, having the bar enabled unintentionally inhibits +resizing the status panel. +To resize that, use the \texttt{\#optionsfull} command to toggle the +\textit{hitpointbar} option off, perform the resize while it's off, then +use the same command to toggle it back on.) %.lp -\item[\ib{ignintr}] +\item[horsename] +Name your starting horse (for example, ``\texttt{horsename:Trigger}''). +Cannot be set with the `\texttt{O}' command. +%.lp +\item[ignintr] Ignore interrupt signals, including breaks (default off). Persistent. %.lp -\item[\ib{implicit\verb+_+uncursed}] -Omit ``uncursed'' from inventory lists, if possible (default on). +\item[implicit\textunderscore uncursed] +Omit ``uncursed'' from object descriptions when it can be deduced from +other aspects of the description (default on). +Persistent. + +%.lp "" +If you use menu coloring, you may want to turn this off. %.lp -\item[\ib{legacy}] +\item[legacy] Display an introductory message when starting the game (default on). Persistent. %.lp -\item[\ib{lit\verb+_+corridor}] +\item[lit\textunderscore corridor] Show corridor squares seen by night vision or a light source held by your character as lit (default off). Persistent. %.lp -\item[\ib{lootabc}] +\item[lootabc] When using a menu to interact with a container, -use the old `{\tt a}', `{\tt b}', and `{\tt c}' keyboard shortcuts -rather than the mnemonics `{\tt o}', `{\tt i}', and `{\tt b}' (default off). +use the old `\texttt{a}', `\texttt{b}', and `\texttt{c}' keyboard shortcuts +rather than the mnemonics `\texttt{o}', `\texttt{i}', and `\texttt{b}' (default off). Persistent. %.lp -\item[\ib{mail}] +\item[mail] Enable mail delivery during the game (default on). Persistent. %.lp -\item[\ib{male}] -An obsolete synonym for ``{\tt gender:male}''. Cannot be set with the -`{\tt O}' command. +\item[male] +An obsolete synonym for ``\texttt{gender:male}''. Cannot be set with the +`\texttt{O}' command. +%.lp +\item[mention\textunderscore decor] +Give feedback when walking onto various dungeon features such as stairs, +fountains, or altars which are ordinarily only described when covered +by one or more objects (default off). Persistent. %.lp -\item[\ib{mention\verb+_+walls}] -Give feedback when walking against a wall (default off). +\item[mention\textunderscore map] +Give feedback when interesting map locations change (default off). %.lp -\item[\ib{menucolors}] +\item[mention\textunderscore walls] +Give feedback when walking against a wall (default off). Persistent. +%.lp +\item[menucolors] Enable coloring menu lines (default off). -See ``{\it Configuring Menu Colors\/}'' on how to configure the colors. -%.lp -\item[\ib{menustyle}] -Controls the interface used when you need to choose various objects (in -response to the Drop command, for instance). The value specified should -be the first letter of one of the following: traditional, combination, -full, or partial. -Traditional was the only interface available for +See ``\textit{Configuring Menu Colors}'' on how to configure the colors. +%.lp +\item[menustyle] +Controls the method used when you need to choose various objects (in +response to the \texttt{Drop} (aka \texttt{droptype}) command, for instance). +The value specified should be the first letter of one of the following: +traditional, combination, full, or partial. +Default is \texttt{full}. +Persistent. +\\ +%.lp "" +Traditional was the only method available for very early versions; it consists of a prompt for object class characters, followed by an object-by-object prompt for all items matching the selected object class(es). @@ -3452,292 +4641,428 @@ \subsection*{Customization options} Full displays a menu of object classes rather than a character prompt, and then a menu of matching objects for selection. +(Choosing its `A' (Autoselect-All) choice skips the second menu. +To avoid choosing that by accident, +set \textit{paranoid\textunderscore confirm:AutoAll} to require confirmation.) Partial skips the object class filtering and immediately displays a menu of all objects. -Persistent. -\item[\ib{menu\verb+_+deselect\verb+_+all}] -Menu character accelerator to deselect all items in a menu. +\item[menu\textunderscore deselect\textunderscore all] +Key to deselect all items in a menu. Implemented by the Amiga, Gem, X11 and tty ports. Default `-'. -\item[\ib{menu\verb+_+deselect\verb+_+page}] -Menu character accelerator to deselect all items on this page of a menu. +\item[menu\textunderscore deselect\textunderscore page] +Key to deselect all items on this page of a menu. Implemented by the Amiga, Gem and tty ports. -Default `\verb+\+'. -\item[\ib{menu\verb+_+first\verb+_+page}] -Menu character accelerator to jump to the first page in a menu. +Default `\textbackslash'. +\item[menu\textunderscore first\textunderscore page] +Key to jump to the first page in a menu. Implemented by the Amiga, Gem and tty ports. -Default `\verb+^+'. -\item[\ib{menu\verb+_+headings}] +Default `\textasciicircum'. +\item[menu\textunderscore headings] Controls how the headings in a menu are highlighted. -Values are ``{\tt none}'', ``{\tt bold}'', ``{\tt dim}'', -``{\tt underline}'', ``{\tt blink}'', or ``{\tt inverse}''. +Takes a text attribute, or text color and attribute separated by ampersand. +For allowed attributes and colors, see ``\textit{Configuring Menu Colors}``. Not all ports can actually display all types. -\item[\ib{menu\verb+_+invert\verb+_+all}] -Menu character accelerator to invert all items in a menu. +\item[menu\textunderscore invert\textunderscore all] +Key to invert all items in a menu. Implemented by the Amiga, Gem, X11 and tty ports. Default `@'. -\item[\ib{menu\verb+_+invert\verb+_+page}] -Menu character accelerator to invert all items on this page of a menu. +\item[menu\textunderscore invert\textunderscore page] +Key to invert all items on this page of a menu. Implemented by the Amiga, Gem and tty ports. -Default `\verb+~+'. -\item[\ib{menu\verb+_+last\verb+_+page}] -Menu character accelerator to jump to the last page in a menu. +Default `\textasciitilde'. +\item[menu\textunderscore last\textunderscore page] +Key to jump to the last page in a menu. Implemented by the Amiga, Gem and tty ports. -Default `\verb+|+'. -\item[\ib{menu\verb+_+next\verb+_+page}] -Menu character accelerator to goto the next menu page. +Default `|'. +\item[menu\textunderscore next\textunderscore page] +Key to go to the next menu page. Implemented by the Amiga, Gem and tty ports. -Default `\verb+>+'. -\item[\ib{menu\verb+_+objsyms}] -Show object symbols in menu headings in menus where -the object symbols act as menu accelerators (default off). -\item[\ib{menu\verb+_+overlay}] +Default `>'. +\item[menu\textunderscore objsyms] +% [originally menu_objsyms was a boolean] +% Show object symbols in menu headings in menus where +% the object symbols act as menu accelerators (default off). +Inventory and other object menus are normally separated by object class +(weapons, armor, and so forth), with a menu header line at the beginning +of each group. +You can have menus add the display symbol for the class of objects for +each header line. +You can also add the display symbol for the individual item in each menu +entry. +For a tiles map, that would be a small rendition of an object's tile. +For a text map, it is the same character as is used for the object's +class, which would be most useful when there are no headers separating +objects among classes. +% FIXME! -- three column table may be simpler than mashing first two together +% Possible values are +% .PS "5\ -\ One-or-other" +% .PL "0\ -\ None" +% no symbols for either header lines or menu entries; +% .PL "1\ -\ Headers" +% show symbols on header lines but not entries; +% .PL "2\ -\ Entries" +% show symbols on menu entry lines but not headers; +% .PL "3\ -\ Both" +% show symbols on headers and entries; +% .PL "4\ -\ Conditional" +% only show symbols for entries if there are no headers; +% .PL "5\ -\ One-or-other" +% show symbols on headers, or on entries if no headers. +% .PE + +Supported by tty and curses. +When setting the value, it can be specified by digit or keyword. +The default value is \texttt{Conditional} (4). +\item[menu\textunderscore overlay] Do not clear the screen before drawing menus, and align menus to the right edge of the screen. Only for the tty port. (default on) -\item[\ib{menu\verb+_+previous\verb+_+page}] -Menu character accelerator to goto the previous menu page. +\item[menu\textunderscore previous\textunderscore page] +Key to go to the previous menu page. Implemented by the Amiga, Gem and tty ports. -Default `\verb+<+'. -\item[\ib{menu\verb+_+search}] -Menu character accelerator to search for a menu item. -Implemented by the Amiga, Gem, X11 and tty ports. +Default `<'. +\item[menu\textunderscore search] +Key to search for some text and toggle selection state of matching menu items. Default `:'. -\item[\ib{menu\verb+_+select\verb+_+all}] -Menu character accelerator to select all items in a menu. +\item[menu\textunderscore select\textunderscore all] +Key to select all items in a menu. Implemented by the Amiga, Gem, X11 and tty ports. Default `.'. -\item[\ib{menu\verb+_+select\verb+_+page}] -Menu character accelerator to select all items on this page of a menu. +\item[menu\textunderscore select\textunderscore page] +Key to select all items on this page of a menu. Implemented by the Amiga, Gem and tty ports. Default `,'. + +%.lp +\item[menu\textunderscore shift\textunderscore left] +Key to scroll a menu---one which has been +scrolled right---back to the left. +Implemented for \textit{perm\textunderscore invent} only by curses and X11. +Default `\texttt{\textbraceleft}'. + +%.lp +\item[menu\textunderscore shift\textunderscore right] +Key to scroll a menu which has text beyond the +right edge to the right. +Implemented for \textit{perm\textunderscore invent} only by curses by X11. +Default `\texttt{\textbraceright}'. % %.lp -% \item[\ib{menu\verb+_+tab\verb+_+sep}] +% \item[menu\textunderscore tab\textunderscore sep] % Format menu entries using TAB to separate columns (default off). % Only applicable to some menus, and only useful to some interfaces. % Debug mode only. %.lp -\item[\ib{monpolycontrol}] +\item[mon\textunderscore movement] +Show a message when hero notices a monster movement (default is off). +%.lp +\item[monpolycontrol] Prompt for new form whenever any monster changes shape (default off). Debug mode only. %.lp -\item[\ib{mouse\verb+_+support}] +\item[montelecontrol] +Prompt for destination whenever any monster gets teleported (default off). +Debug mode only. +%.lp +\item[mouse\textunderscore support] Allow use of the mouse for input and travel. Valid settings are: %.sd %.si -{\tt 0} --- disabled\\ -{\tt 1} --- enabled and make OS adjustment to support mouse use\\ -{\tt 2} --- enabled like {\tt 1}, but does not make any OS adjustments\\ +\texttt{0} --- disabled\\ +\texttt{1} --- enabled and make OS adjustments to support mouse use\\ +\texttt{2} --- like \texttt{1}, but does not make any OS adjustments\\ %.ei %.ed -Omitting a value is the same as specifying {\tt 1} +Omitting a value is the same as specifying \texttt{1} and negating -{\it mouse\verb+_+support\/} -is the same as specifying {\tt 0}. +\textit{mouse\textunderscore support} +is the same as specifying \texttt{0}. %.lp -\item[\ib{msghistory}] +\item[msghistory] The number of top line messages to save (and be able to recall -with `{\tt \^{}P}') (default 20). -Cannot be set with the `{\tt O}' command. +with `\texttt{\textasciicircum P}') (default 20). +Cannot be set with the `\texttt{O}' command. %.lp -\item[\ib{msg\verb+_+window}] +\item[msg\textunderscore window] Allows you to change the way recalled messages are displayed. Currently it is only supported for tty (all four choices) and for curses -(`{\tt f}' and `{\tt r}' choices, default `{\tt r}'). +(`\texttt{f}' and `\texttt{r}' choices, default `\texttt{r}'). The possible values are: %.sd %.si -{\tt s} --- single message (default; only choice prior to 3.4.0);\\ -{\tt c} --- combination, two messages as {\it single\/}, then as {\it full\/};\\ -{\tt f} --- full window, oldest message first;\\ -{\tt r} --- full window reversed, newest message first. +\texttt{s} --- single message (default; only choice prior to 3.4.0);\\ +\texttt{c} --- combination, two messages as \textit{single}, then as \textit{full};\\ +\texttt{f} --- full window, oldest message first;\\ +\texttt{r} --- full window reversed, newest message first. %.ei %.ed For backward compatibility, no value needs to be specified (which -defaults to {\it full\/}), or it can be negated (which defaults -to {\it single\/}). +defaults to \textit{full}), or it can be negated (which defaults +to \textit{single}). %.lp -\item[\ib{name}] +\item[name] Set your character's name (defaults to your user name). You can also set your character's role by appending a dash and one or more letters of the role (that is, by suffixing one of -``{\tt -A -B -C -H -K -M -P -Ra -Ro -S -T -V -W}''). -If ``{\tt -@}'' is used for the role, then a random one will be +``\texttt{-A -B -C -H -K -M -P -Ra -Ro -S -T -V -W}''). +If ``\texttt{-@}'' is used for the role, then a random one will be automatically chosen. -Cannot be set with the `{\tt O}' command. %.lp -\item[\ib{news}] -Read the {\it NetHack\/} news file, if present (default on). +\\ +On some systems, the default is the player's user name; +on others, there is no default and the player will be prompted. +The former can made to behave like the latter by specifying a generic name +such as ``player''. +Cannot be set with the `\texttt{O}' command. +%.lp +\item[news] +Read the \textit{NetHack} news file, if present (default on). Since the news is shown at the beginning of the game, there's no point -in setting this with the `{\tt O}' command. +in setting this with the `\texttt{O}' command. %.lp -\item[\ib{nudist}] +\item[nudist] Start the character with no armor (default false). Persistent. %.lp -\item[\ib{null}] +\item[null] Send padding nulls to the terminal (default on). Persistent. %.lp -\item[\ib{number\verb+_+pad}] +\item[number\textunderscore pad] Use digit keys instead of letters to move (default 0 or off).\\ Valid settings are: %.sd %.si \newlength{\mwidth} -\settowidth{\mwidth}{\tt -0} -\newcommand{\numbox}[1]{\makebox[\mwidth][r]{{\tt #1}}} -\numbox{0} --- move by letters; `{\tt yuhjklbn}'\\ -\numbox{1} --- move by numbers; digit `{\tt 5}' acts as `{\tt G}' movement prefix\\ -\numbox{2} --- like {\tt 1} but `{\tt 5}' works as `{\tt g}' prefix instead of as `{\tt G}'\\ -\numbox{3} --- by numbers using phone key layout; {\tt 123} above, {\tt 789} below\\ -\numbox{4} --- combines {\tt 3} with {\tt 2}; phone layout plus MS-DOS compatibility\\ -\numbox{-1} --- by letters but use `{\tt z}' to go northwest, `{\tt y}' to zap wands +\settowidth{\mwidth}{\texttt{-0}} +\newcommand{\numbox}[1]{\makebox[\mwidth][r]{\texttt{#1}}} +\numbox{0} --- move by letters; `\texttt{yuhjklbn}'\\ +\numbox{1} --- move by numbers; digit `\texttt{5}' acts as `\texttt{G}' movement prefix\\ +\numbox{2} --- like \texttt{1} but `\texttt{5}' works as `\texttt{g}' prefix instead of as `\texttt{G}'\\ +\numbox{3} --- by numbers using phone key layout; \texttt{123} above, \texttt{789} below\\ +\numbox{4} --- combines \texttt{3} with \texttt{2}; phone layout plus MS-DOS compatibility\\ +\numbox{-1} --- by letters but use `\texttt{z}' to go northwest, `\texttt{y}' to zap wands %.ei %.ed -For backward compatibility, omitting a value is the same as specifying {\tt 1} +For backward compatibility, omitting a value is the same as specifying \texttt{1} and negating -{\it number\verb+_+pad\/} -is the same as specifying {\tt 0}. -(Settings {\tt 2} and {\tt 4} are for compatibility with MS-DOS or old PC Hack; -in addition to the different behavior for `{\tt 5}', `{\tt Alt-5}' acts as `{\tt G}' -and `{\tt Alt-0}' acts as `{\tt I}'. -Setting {\tt -1} is to accommodate some QWERTZ keyboards which have the -location of the `{\tt y}' and `{\tt z}' keys swapped.) +\textit{number\textunderscore pad} +is the same as specifying \texttt{0}. +(Settings \texttt{2} and \texttt{4} are for compatibility with MS-DOS or old PC Hack; +in addition to the different behavior for `\texttt{5}', `\texttt{Alt-5}' acts as `\texttt{G}' +and `\texttt{Alt-0}' acts as `\texttt{I}'. +Setting \texttt{-1} is to accommodate some QWERTZ keyboards which have the +location of the `\texttt{y}' and `\texttt{z}' keys swapped.) When moving by numbers, to enter a count prefix for those commands -which accept one (such as ``{\tt 12s}'' to search twelve times), precede it -with the letter `{\tt n}' (``{\tt n12s}''). +which accept one (such as ``\texttt{12s}'' to search twelve times), precede it +with the letter `\texttt{n}' (``\texttt{n12s}''). %.lp -\item[\ib{packorder}] +\item[packorder] Specify the order to list object types in (default -``\verb&")[%?+!=/(*`0_&''). The value of this option should be a string +``\texttt{")[\%?+!=/(*\textasciigrave 0\textunderscore}''). The value of this option should be a string containing the symbols for the various object types. Any omitted types are filled in at the end from the previous order. %.lp -\item[\ib{paranoid\verb+_+confirmation}] +\item[paranoid\textunderscore confirmation] A space separated list of specific situations where alternate -prompting is desired. The default is ``{\it paranoid\verb+_+confirmation:pray}''. +prompting is desired. +The default is ``\textit{paranoid\textunderscore confirmation:pray swim trap}''. %.sd %.si \newlength{\pcwidth} -\settowidth{\pcwidth}{\tt Were-change} +\settowidth{\pcwidth}{\texttt{Were-change}} \addtolength{\pcwidth}{\labelsep} -\blist{\leftmargin \pcwidth \topsep 1mm \itemsep 0mm} -\item[{\tt Confirm}] -for any prompts which are set to require ``yes'' -rather than `y', also require ``no'' to reject instead -of accepting any non-yes response as no; -\item[{\tt quit~~~}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm quitting +\begin{description}[leftmargin=\pcwidth, topsep=1mm, itemsep=0mm, labelwidth=*, font=\ttfamily, align=right] +\item[Confirm] +for any prompts which are set to require ``yes'' rather than `y', +also require ``no'' to reject instead of accepting any non-yes response +as no; changes pray and AutoAll to require ``yes'' or ``no'' too; +\item[quit] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm quitting the game or switching into non-scoring explore mode; -\item[{\tt die~~~~}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm dying (not +\item[die] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm dying (not useful in normal play; applies to explore mode); -\item[{\tt bones~~}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm saving +\item[bones] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm saving bones data when dying in debug mode -\item[{\tt attack~}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm attacking +\item[attack] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm attacking a peaceful monster; -\item[{\tt wand-break}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm breaking -a wand; -\item[{\tt eating}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm whether to +\item[wand-break] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm breaking +a wand with the \textit{apply} command; +\item[eating] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm whether to continue eating; -\item[{\tt Were-change}] -require ``{\tt yes}'' rather than `{\tt y}' to confirm changing form -due to lycanthropy -when hero has polymorph control; -\item[{\tt pray~~~}] -require `{\tt y}' to confirm an attempt to pray rather +\item[Were-change] +require ``\texttt{yes}'' rather than `\texttt{y}' to confirm changing form due +to lycanthropy when hero has polymorph control; +\item[pray] +require `\texttt{y}' to confirm an attempt to pray rather than immediately praying; on by default; -\item[{\tt Remove~}] require selection from inventory for `{\tt R}' -and `{\tt T}' -commands even when wearing just one applicable item. -\item[{\tt all~~~~}] +(to require ``yes'' rather than just `y', set Confirm too); +\item[trap] +require `\texttt{y}' to confirm an attempt to move into or onto a known trap, +unless doing so is considered to be harmless; +when enabled, this confirmation is also used for moving into visible +gas cloud regions; +(to require ``yes'' rather than just `y', set Confirm too); +confirmation can be skipped by using the `\texttt{m}' movement prefix; +\item[swim] +prevent walking into water or lava; on by default; (to deliberately step +onto/into such terrain when this is set, use the `\texttt{m}' +movement prefix when adjacent); +\item[AutoAll] +require confirmation when the `A' (Autoselect-All) choice is selected +in object class filtering menus for \textit{menustyle:Full}; +(to require ``yes'' rather than just `y', set Confirm too); +\item[Remove] +require selection from inventory for `\texttt{R}' and `\texttt{T}' +commands even when wearing just one applicable item; +\item[all] turn on all of the above. -\elist +\end{description} %.ei %.ed -By default, the pray choice is enabled, the others disabled. -To disable it without setting -any of the other choices, use ``{\it paranoid\verb+_+confirmation:none}''. To keep -it enabled while setting others, include it in the list, -such as ``{\it par\-a\-noid\verb+_+con\-fir\-ma\-tion:attack~pray~Remove}''. -%.lp -\item[\ib{perm\verb+_+invent}] -If true, always display your current inventory in a window. This only +By default, the pray, swim, and trap choices are enabled, the others disabled. +To disable them without setting +any of the other choices, use ``\textit{paranoid\textunderscore confirmation:none}''. +To keep them enabled while setting any of the others, you can +include them in the list, such as +``\textit{par\-a\-noid\textunderscore con\-fir\-ma\-tion:attack~pray~swim~Remove}'' +or you can precede the first entry in the list with a plus sign, +``\textit{paranoid\textunderscore confirmation:+attack~Remove}''. +To remove an entry that has been previously set without removing others, +precede the first entry in the list with a minus sign, +``\textit{paranoid\textunderscore confirmation:-swim}. +To both add some new entries and remove some old ones, you can use +multiple \textit{paranoid\textunderscore confirmation} option settings, or you can +use the `\texttt{+}' form and list entries to be added by their name +and entries to be removed by `\texttt{!}' and name. +The positive (no `!') and negative (with `!') entries +can be intermixed. +%.lp +\item[pauper] +Start the character with no possessions (default false). Persistent. +%.lp "" +\\ +Also start with no spells or skills, which are tied to starting equipment. +Does not inhibit acquiring and using items, spells, and skills once play +has started. +%.lp +\item[perm\textunderscore invent] +If true, always display your current inventory in a window (default is false). +%.lp "" +\\ +This only makes sense for windowing system interfaces that implement this feature. +For those that do, the +\texttt{perminv\textunderscore mode} +option can be used to refine what gets displayed +for \textit{perm\textunderscore invent}. +Setting that to a value other than \textit{none} +while \textit{perm\textunderscore invent} is false will change it to true. +%.lp +\item[perminv\textunderscore mode] +Augments the +\texttt{perm\textunderscore invent} +option. +Value is one of +%.PS "\f(CRin-use\fP" +\settowidth{\pcwidth}{\texttt{in-use}} %reuse the paranoid_confirm width +\addtolength{\pcwidth}{\labelsep} +\begin{description}[leftmargin=\pcwidth, topsep=1mm, itemsep=0mm, labelwidth=*, font=\mdseries, align=right] +%.PL +\item[\texttt{none}] +behave as if \textit{perm\textunderscore invent} is false; +\item[{all}] +show all inventory except for gold; +\item[{full}] +show full inventory including gold; +\item[{in-use}] +only show items which are in use (worn, wielded, lit lamp). +%.PE +\end{description} +Default is \textit{none} but if \textit{perm\textunderscore invent} gets set to true +while it is \textit{none} it will be changed to \textit{all}. +%.lp "" +\\ +Note: if gold has been equipped in quiver/ammo-pouch then it will be +included for \textit{all} despite that mode normally omitting gold. %.lp %.\" petattr is a wincap option but we'll document it here... -\item[\ib{petattr}] +\item[petattr] Specifies one or more text highlighting attributes to use when showing pets on the map. -Effectively a superset of the {\it hilite\verb+_+pet\/} boolean option. -Curses interface only; value is one or more of the following letters. - -%.sd -%.si -{\tt n} --- Normal text (no highlighting)\\ -{\tt i} --- Inverse video (default)\\ -{\tt b} --- Bold text\\ -{\tt u} --- Underlined text\\ -{\tt k} --- blinKing text\\ -{\tt d} --- Dim text\\ -{\tt t} --- iTalic text\\ -{\tt l} --- Left line indicator\\ -{\tt r} --- Right line indicator\\ -%.ei -%.ed - -Some of those choices might not work, particularly the final three, +Effectively a superset of the \textit{hilite\textunderscore pet} boolean option. +Curses or tty interface only; value is one of +none, bold, dim, underline, italic, blink, and inverse. +Some of those choices might not work, depending upon terminal hardware or terminal emulation software. -%.lp "" -Currently multiple highlight-style letters can be combined by simply -stringing them together (for example, ``bk''), but in the future -they might require being separated by plus signs (such as ``b\verb&+&k'', -which works already). -When using the `n' choice, it should be specified on its own, -not in combination with any of the other letters. - %.lp -\item[\ib{pettype}] +\item[pettype] Specify the type of your initial pet, if you are playing a character class that uses multiple types of pets; or choose to have no initial pet at all. -Possible values are ``{\tt cat}'', ``{\tt dog}'', ``{\tt horse}'' -and ``{\tt none}''. +Possible values are ``\texttt{cat}'', ``\texttt{dog}'', ``\texttt{horse}'' +and ``\texttt{none}''. If the choice is not allowed for the role you are currently playing, -it will be silently ignored. For example, ``{\tt horse}'' will only be +it will be silently ignored. For example, ``\texttt{horse}'' will only be honored when playing a knight. -Cannot be set with the `{\tt O}' command. +Cannot be set with the `\texttt{O}' command. %.lp -\item[\ib{pickup\verb+_+burden}] +\item[pickup\textunderscore burden] When you pick up an item that would exceed this encumbrance level (Unencumbered, Burdened, streSsed, straiNed, overTaxed, or overLoaded), you will be asked if you want to continue. (Default `S'). Persistent. %.lp -\item[\ib{pickup\verb+_+thrown}] -If this option is on and ``{\it autopickup\/}'' is also on, try to pick up +\item[pickup\textunderscore stolen] +If this option is on and ``\textit{autopickup}'' is also on, try to pick up +things that a monster stole from you, even if they aren't in +``\textit{pickup\textunderscore types}'' or +match an autopickup exception. +Default is on. +Persistent. +%.lp +\item[pickup\textunderscore thrown] +If this option is on and ``\textit{autopickup}'' is also on, try to pick up things that you threw, even if they aren't in -``{\it pickup\verb+_+types\/}'' or -match an autopickup exception. Default is on. Persistent. -%.lp -\item[\ib{pickup\verb+_+types}] -Specify the object types to be picked up when ``{\it autopickup\/}'' -is on. Default is all types. You can use -``{\it autopickup\verb+_+exception\/}'' -configuration file lines to further refine ``{\it autopickup\/}'' behavior. +``\textit{pickup\textunderscore types}'' or +match an autopickup exception. +Default is on. Persistent. %.lp -\item[\ib{pile\verb+_+limit}] +\item[pickup\textunderscore types] +Specify the object types to be picked up when ``\textit{autopickup}'' +is on. +Default is all types. +Persistent. +\\ +%.lp "" +The value is a list of object symbols, such as +\texttt{pickup\textunderscore types:\textdollar ?!\&} to pick up gold, scrolls, and potions. +You can use +``\textit{autopickup\textunderscore exception}'' +configuration file lines to further refine ``\textit{autopickup}'' behavior. +\\ +%.lp "" +There is no way to set \textit{pickup\textunderscore types} to ``\textit{none}''. +(Setting it to an empty value reverts to ``\textit{all}''.) +If you want to avoid automatically picking up any types of items but do +want to have \textit{autopickup} on in order to have +\textit{autopickup\textunderscore exceptions} control what you do and don't pick +up, you can set \textit{pickup\textunderscore types} to `\texttt{.}'. +That is the type symbol for \textit{venom} and you won't come across +any venom items so won't unintentionally pick such up. +%.lp +\item[pile\textunderscore limit] When walking across a pile of objects on the floor, threshold at which the message ``there are few/several/many objects here'' is given instead of showing a popup list of those objects. A value of 0 means ``no limit'' @@ -3745,8 +5070,8 @@ \subsection*{Customization options} the objects'' since the pile size will always be at least that big; default value is 5. Persistent. %.lp -\item[\ib{playmode}] -Values are {\it normal\/}, {\it explore\/}, or {\it debug\/}. +\item[playmode] +Values are \textit{normal}, \textit{explore}, or \textit{debug}. Allows selection of explore mode (also known as discovery mode) or debug mode (also known as wizard mode) instead of normal play. Debug mode might only be allowed for someone logged in under a particular @@ -3755,170 +5080,356 @@ \subsection*{Customization options} it when not allowed or not possible results in explore mode instead. Default is normal play. %.lp -\item[\ib{pushweapon}] -Using the `w' (wield) command when already wielding +\item[price\textunderscore quotes] +Whenever the game mentions the name of an object you haven't identified yet, +it also mentions the range of buy and sell prices you have seen for that +item (to help narrow down what it could be). +The price shown is the unit price for one item (even when you are looking at +a stack of multiple items). +Many players may want to turn this on while identifying objects, and then +turn it back off again for general play. +Default is off. +%.lp +\item[pushweapon] +Using the `\texttt{w}' (wield) command when already wielding something pushes the old item into your alternate weapon slot (default off). -Likewise for the `a' (apply) command if it causes the applied item to +Likewise for the `\texttt{a}' (apply) command if it causes the applied item to become wielded. Persistent. -%.Ip -\item[\ib{race}] -Selects your race (for example, ``{\tt race:human}''). Default is random. -If you prefix the value with `{\tt !}' or ``{\tt no}'', you will -exclude that race from being picked randomly. -Cannot be set with the `{\tt O}' command. Persistent. -%.lp -\item[\ib{rest\verb+_+on\verb+_+space}] -Make the space bar a synonym for the `{\tt .}' (\#wait) command (default off). +%.lp +\item[query\textunderscore menu] +Use a menu when asked specific yes/no queries, instead of a prompt. +%.lp +\item[quick\textunderscore farsight] +When set, usually prevents the ``you sense your surroundings'' message +where play pauses to allow you to browse the map whenever clairvoyance +randomly activates. +Some situations, such as being underwater or engulfed, ignore this option. +It does not affect the clairvoyance spell where pausing to examine revealed +objects or monsters is less intrusive. +Default is off. Persistent. +%.lp +\item[race] +Choices are \texttt{human}, \texttt{dwarf}, \texttt{elf}, \texttt{gnome}, and +\texttt{orc} but most roles restrict which of the non-human races are allowed. +See \textit{role} +for a description of how to use negation to exclude choices. +%.lp "" +\\ +If \texttt{race} is not specified, there is no default value; +player will be prompted unless role forces a choice for race. +Cannot be set with the `\texttt{O}' command. Persistent. +%.lp +\item[reroll] +Allows rerolling your character's starting inventory and attributes (default +false). Persistent. +%.lp "" +\\ +Note that rerolling your character is not a recommended way to play if aiming +merely to win (a lucky start has a much smaller influence on whether or not +you win the game than your actions later in the game). This option exists +partly as an acknowledgement that some players will insist on doing so anyway, +and partly because rerolling may be necessary for certain types of challenge +games. +%.lp +\item[rest\textunderscore on\textunderscore space] +Make the space bar a synonym for the `\texttt{.}' (\#wait) command (default off). Persistent. %.lp -\item[\ib{role}] -Pick your type of character (for example, ``{\tt role:Samurai}''); -synonym for ``{\it character\/}''. See ``{\it name\/}'' for an alternate method -of specifying your role. Normally only the first letter of the -value is examined; `r' is an exception with ``{\tt Rogue}'', {\tt Ranger}'', -and ``{\tt random}'' values. -If you prefix the value with `{\tt !}' or ``{\tt no}'', you will -exclude that role from being picked randomly. -Cannot be set with the `{\tt O}' command. Persistent. -%.lp -\item[\ib{roguesymset}] +\item[role] +Pick your type of character (for example, ``\texttt{role:Samurai}''); +synonym for ``\textit{character}''. +See ``\textit{name}'' for an alternate method of specifying your role. +%.\" Normally only the first letter of the +%.\" value is examined; `r' is an exception with ``\texttt{Rogue}'', +%.\" ``\texttt{Ranger}'', and ``\texttt{random}'' values. +%.lp "" +This option can also be used to limit selection when role is chosen +randomly. +Use a space-separated list of roles and either negate each one or negate +the option itself instead. +Negation is accomplished in the same manner as with \textit{boolean options}, +by prefixing the option or its value(s) with `\texttt{!}' or ``\texttt{no}''. +%.BR 0 +\\ +Examples: +\\ +\begin{verbatim} +OPTIONS=role:!arc !bar !kni +OPTIONS=!role:arc bar kni +\end{verbatim} +There can be multiple instances of the \textit{role} +option if they're all negations. +%.\" Only one positive value is allowed, and if present, it overrides any +%.\" negations. +%.lp "" +\\ +If \texttt{role} is not specified, there is no default value; +player will be prompted. +Cannot be set with the `\texttt{O}' command. Persistent. +%.lp +\item[roguesymset] This option may be used to select one of the named symbol sets found within -{\tt symbols} to alter the symbols displayed on the screen on the +\texttt{symbols} to alter the symbols displayed on the screen on the rogue level. %.lp -\item[\ib{rlecomp}] +\item[rlecomp] When writing out a save file, perform run length compression of the map. Not all ports support run length compression. It has no effect on reading an existing save file. %.lp -\item[\ib{runmode}] +\item[runmode] Controls the amount of screen updating for the map window when engaged -in multi-turn movement (running via {\tt shift}+direction -or {\tt control}+direction +in multi-turn movement (running via \texttt{shift}+direction +or \texttt{control}+direction and so forth, or via the travel command or mouse click). The possible values are: %.sd %.si -{\tt teleport} --- update the map after movement has finished;\\ -{\tt run} --- update the map after every seven or so steps;\\ -{\tt walk} --- update the map after each step;\\ -{\tt crawl} --- like {\it walk\/}, but pause briefly after each step. +\texttt{teleport} --- update the map after movement has finished;\\ +\texttt{run} --- update the map after every seven or so steps;\\ +\texttt{walk} --- update the map after each step;\\ +\texttt{crawl} --- like \textit{walk}, but pause briefly after each step. %.ei %.ed This option only affects the game's screen display, not the actual -results of moving. The default is {\it run\/}; versions prior to 3.4.1 -used {\it teleport\/} only. Whether or not the effect is noticeable will +results of moving. The default is \textit{run}; versions prior to 3.4.1 +used \textit{teleport} only. Whether or not the effect is noticeable will depend upon the window port used or on the type of terminal. Persistent. %.lp -\item[\ib{safe\verb+_+pet}] +\item[safe\textunderscore pet] Prevent you from (knowingly) attacking your pets (default on). Persistent. -%+.lp -\item[\ib{sanity\verb+_+check}] +%.lp +\item[safe\textunderscore wait] +Prevents you from waiting or searching when next to a hostile monster +(default on). Persistent. +%.lp +\item[sanity\textunderscore check] Evaluate monsters, objects, and map prior to each turn (default off). Debug mode only. %.lp -\item[\ib{scores}] +\item[scores] Control what parts of the score list you are shown at the end (for example, -``{\tt scores:5top scores/4around my score/own scores}''). Only the first -letter of each category (`{\tt t}', `{\tt a}' or `{\tt o}') is necessary. +``\texttt{scores:5top scores/4around my score/own scores}''). Only the first +letter of each category (`\texttt{t}', `\texttt{a}' or `\texttt{o}') is necessary. Persistent. %.lp -\item[\ib{showexp}] +\item[showdamage] +Whenever your character takes damage, show a message of the damage taken, +and the amount of hit points left. +%.lp +\item[showexp] Show your accumulated experience points on bottom line (default off). Persistent. %.lp -\item[\ib{showrace}] +\item[showrace] Display yourself as the glyph for your race, rather than the glyph for your role (default off). Note that this setting affects only the appearance of the display, not the way the game treats you. Persistent. %.lp -\item[\ib{showscore}] +\item[showscore] Show your approximate accumulated score on bottom line (default off). +By default, this feature is suppressed when building the program. +Persistent. +%.lp +\item[showvers] +Include the game's version number on the status lines (default off). +Potentially useful if you switch between different versions or variants, +or you are making screenshots or streaming video. +Using the +\textit{statuslines:3} +option is recommended so that there will be more room available for +status information, unless you're using NetHack's \textit{Qt} interface +or your terminal emulator window displays fewer than 25 lines. Persistent. +\\ +%.lp "" +The \textit{versinfo} +option provides limited control over what information +\textit{showvers} displays. %.lp -\item[\ib{silent}] +\item[silent] Suppress terminal beeps (default on). Persistent. %.lp -\item[\ib{sortloot}] +\item[sortdiscoveries] +Controls the sorting behavior for the output of the `\texttt{\textbackslash}' +and `\texttt{\`{}}' commands. +Persistent. +\\ +%.lp "" +The possible values are: +\\ +%.PS +\texttt{o} --- list object types by class, in discovery order within each class; +default; +\\ +\texttt{s} --- list object types by \textit{sortloot} +classification: by class, by sub-class within class for classes which +have substantial groupings (like helmets, boots, gloves, and so forth +for armor), with object types partly-discovered via assigned name coming +before fully identified types; +\\ +\texttt{c} --- list by class, alphabetically within each class;\\ +\texttt{a} --- list alphabetically across all classes.\\ +%.PE +Can be interactively set via the `\texttt{O}' command or via using +the `\texttt{m}' prefix before the `\texttt{\textbackslash}' +or `\texttt{\textasciigrave}' command. +%.lp +\item[sortloot] Controls the sorting behavior of pickup lists for inventory and \#loot commands and some others. Persistent. - +\\ The possible values are: +\\ %.sd %.si -{\tt full} --- always sort the lists;\\ -{\tt loot} --- only sort the lists that don't use inventory +\texttt{full} --- always sort the lists;\\ +\texttt{loot} --- only sort the lists that don't use inventory letters, like with the \#loot and pickup commands;\\ -{\tt none} --- show lists the traditional way without sorting. +\texttt{none} --- show lists the traditional way without sorting; default. %.ei %.ed %.lp -\item[\ib{sortpack}] +\item[sortpack] Sort the pack contents by type when displaying inventory (default on). Persistent. %.lp -\item[\ib{sparkle}] +\item[sortvanquished] +Controls the sorting behavior for the output of the \texttt{\#vanquished} command +and also for the \texttt{\#genocided} command. +Persistent. +\\ +%.lp "" +The possible values are: +\\ +%.PS +\texttt{t} --- +traditional: order by monster level; ties are broken by internal +monster index; +default; +\\ +\texttt{d} --- +order by monster difficulty rating; ties broken by internal index; +\\ +\texttt{a} --- +order alphabetically, first any unique monsters then all the others; +\\ +%note: 'A' and 'C' can be set in RC file or NETHACKOPTIONS but not by 'O' +% \texttt{A} --- +% order alphabetically, unique monsters intermixed with other monsters; +% \\ +% \texttt{C} --- +% order by monster class, by high to low level within each class; +% \\ +\texttt{c} --- +order by monster class, by low to high level within each class; +\\ +\texttt{n} --- +order by count, high to low; ties are broken by internal monster index; +\\ +\texttt{z} --- +order by count, low to high; ties broken by internal index. +\\ +%.PE +Can be interactively set via the `\texttt{m O}' command or via using +the `\texttt{m}' prefix before either the \texttt{\#vanquished} command +or the \texttt{\#genocided} command. +%.lp +\item[sounds] +Allow sounds to be emitted from an integrated sound library (default on). +%.lp +\item[sparkle] Display a sparkly effect when a monster (including yourself) is hit by an attack to which it is resistant (default on). Persistent. %.lp -\item[\ib{standout}] -Boldface monsters and ``{\tt --More--}'' (default off). Persistent. +\item[spot\textunderscore monsters] +Show a message when hero notices a monster (default is off). %.lp -\item[\ib{statushilites}] +\item[standout] +Boldface monsters and ``\texttt{--More--}'' (default off). Persistent. +%.lp +\item[statushilites] Controls how many turns status hilite behaviors highlight the field. If negated or set to zero, disables status hiliting. -See ``{\it Configuring Status Hilites\/}'' for further information. +See ``\textit{Configuring Status Hilites}'' for further information. %.lp -\item[\ib{status\verb+_+updates}] +\item[status\textunderscore updates] Allow updates to the status lines at the bottom of the screen (default true). %.lp -\item[\ib{suppress\verb+_+alert}] -This option may be set to a {\it NetHack\/} version level to suppress +\item[suppress\textunderscore alert] +This option may be set to a \textit{NetHack} version level to suppress alert notification messages about feature changes for that -and prior versions (for example, ``{\tt suppress\verb+_+alert:3.3.1}'') +and prior versions (for example, ``\texttt{suppress\textunderscore alert:3.3.1}'') %.lp -\item[\ib{symset}] +\item[symset] This option may be used to select one of the named symbol sets found within -{\tt symbols} to alter the symbols displayed on the screen. -Use ``{\tt symset:default}'' to explicitly select the default symbols. +\texttt{symbols} to alter the symbols displayed on the screen. +Use ``\texttt{symset:default}'' to explicitly select the default symbols. +%.lp +\item[terrainstatus] +Display an extra status condition describing the spot beneath the hero's +feet (default off, not supported by all interfaces). %.lp -\item[\ib{time}] +\item[time] Show the elapsed game time in turns on bottom line (default off). Persistent. %.lp -\item[\ib{timed\verb+_+delay}] +\item[timed\textunderscore delay] When pausing momentarily for display effect, such as with explosions and moving objects, use a timer rather than sending extra characters to the -screen. (Applies to ``tty'' interface only; ``X11'' interface always -uses a timer based delay. The default is on if configured into the +screen. (Applies to ``tty'' and ``curses'' interfaces only; ``X11'' interface always +uses a timer-based delay. The default is on if configured into the program.) Persistent. %.lp -\item[\ib{tombstone}] +\item[tips] +Show some helpful tips during gameplay (default on). Persistent. +%.lp +\item[tombstone] Draw a tombstone graphic upon your death (default on). Persistent. %.lp -\item[\ib{toptenwin}] -Put the ending display in a {\it NetHack\/} window instead of on stdout (default off). +\item[toptenwin] +Put the ending display in a \textit{NetHack} window instead of on stdout (default off). Setting this option makes the score list visible when a windowing version -of {\it NetHack\/} is started without a parent window, but it no longer leaves +of \textit{NetHack} is started without a parent window, but it no longer leaves the score list around after game end on a terminal or emulating window. %.lp -\item[\ib{travel}] -Allow the travel command (default on). Turning this option off will -prevent the game from attempting unintended moves if you make inadvertent -mouse clicks on the map window. Persistent. +\item[travel] +Allow the travel command via mouse click (default on). +Turning this option off will prevent the game from attempting unintended +moves if you make inadvertent mouse clicks on the map window. +Does not affect traveling via the `\texttt{\textunderscore}' (``\texttt{\#travel}'') +command. Persistent. % %.lp -% \item[ib{travel\verb+_+debug}] +% \item[ib{travel\textunderscore debug}] % Display intended path during each step of travel (default off). % Debug mode only. %.lp -\item[\ib{verbose}] +\item[tutorial] +Play a tutorial level at the start of the game. +Setting this option on or off in the config file will skip the query. +%.lp +\item[verbose] Provide more commentary during the game (default on). Persistent. %.lp -\item[\ib{whatis\verb+_+coord}] -When using the `{\tt /}' or `{\tt ;}' commands to look around on the map with -``{\tt autodescribe}'' +\item[versinfo] +Controls what the \textit{showvers} option displays on the status lines. +%.lp +\item[weaponstatus] +Display an extra status condition which describes currently wielded weapon +(default off, not supported by all interfaces). +%.lp "" +\\ +Some possible displayed values are: +\\ +\texttt{bare-hnds} - no weapon and no gloves;\\ +\texttt{empty-hnd} - no weapon but gloves are worn;\\ +\texttt{dual-weps} - wielding two weapons. +%.lp +\item[whatis\textunderscore coord] +When using the `\texttt{/}' or `\texttt{;}' commands to look around on the map with +``\texttt{autodescribe}'' on, display coordinates after the description. Also works in other situations where you are asked to pick a location.\\ @@ -3927,23 +5438,23 @@ \subsection*{Customization options} %.sd %.si -{\tt c} --- \verb#compass ('east' or '3s' or '2n,4w')#;\\ -{\tt f} --- \verb#full compass ('east' or '3south' or '2north,4west')#;\\ -{\tt m} --- \verb#map (map column x=0 is not used)#;\\ -{\tt s} --- \verb#screen [row,column] (row is offset to match tty usage)#;\\ -{\tt n} --- \verb#none (no coordinates shown) [default]#. +\texttt{c} --- \texttt{compass ('east' or '3s' or '2n,4w')};\\ +\texttt{f} --- \texttt{full compass ('east' or '3south' or '2north,4west')};\\ +\texttt{m} --- \texttt{map (map column x=0 is not used)};\\ +\texttt{s} --- \texttt{screen [row,column] (row is offset to match tty usage)};\\ +\texttt{n} --- \texttt{none (no coordinates shown) [default]}. %.ei %.ed %.lp "" The -{\it whatis\verb+_+coord\/} +\textit{whatis\textunderscore coord} option is also used with -the `{\tt /m}', `{\tt /M}', `{\tt /o}', and `{\tt /O}' sub-commands -of `{\tt /}', -where the `{\it none\/}' setting is overridden with `{\it map}'. +the `\texttt{/m}', `\texttt{/M}', `\texttt{/o}', and `\texttt{/O}' sub-commands +of `\texttt{/}', +where the `\textit{none}' setting is overridden with `\textit{map}'. %.lp -\item[\ib{whatis\verb+_+filter}] +\item[whatis\textunderscore filter] When getting a location on the map, and using the keys to cycle through next and previous targets, allows filtering the possible targets. (default none)\\ @@ -3952,35 +5463,36 @@ \subsection*{Customization options} %.sd %.si -{\tt n} --- \verb#no filtering#;\\ -{\tt v} --- \verb#in view only#;\\ -{\tt a} --- \verb#in same area (room, corridor, etc)#. +\texttt{n} --- \texttt{no filtering};\\ +\texttt{v} --- \texttt{in view only};\\ +\texttt{a} --- \texttt{in same area (room, corridor, etc)}. %.ei %.ed %.lp "" -The area-filter tries to be slightly predictive -- if you're standing -on a doorway, it will consider the area on the side of the door you -were last moving towards.\\ +The area-filter tries to be slightly +predictive---if +you're standing on a doorway, it will consider the area on the side of +the door you were last moving towards.\\ %.lp "" Filtering can also be changed when getting a location with the ``getpos.filter'' key. %.lp -\item[\ib{whatis\verb+_+menu}] +\item[whatis\textunderscore menu] When getting a location on the map, and using a key to cycle through next and previous targets, use a menu instead to pick a target. (default off) %.lp -\item[\ib{whatis\verb+_+moveskip}] +\item[whatis\textunderscore moveskip] When getting a location on the map, and using shifted movement keys or meta-digit keys to fast-move, instead of moving 8 units at a time, move by skipping the same glyphs. (default off) %.lp -\item[\ib{windowtype}] +\item[windowtype] When the program has been built to support multiple interfaces, -select whichone to use, such as ``{\tt tty}'' or ``{\tt X11}'' -(default depends on build-time settings; use ``{\tt \#version}'' to check). -Cannot be set with the `{\tt O}' command. +select whichone to use, such as ``\texttt{tty}'' or ``\texttt{X11}'' +(default depends on build-time settings; use ``\texttt{\#version}'' to check). +Cannot be set with the `\texttt{O}' command. %.lp "" When used, it should be the first option set since its value might @@ -3988,17 +5500,17 @@ \subsection*{Customization options} For multiple lines in a configuration file, that would be the first non-comment line. For a comma-separated list in NETHACKOPTIONS or an OPTIONS line in a -configuration file, that would be the {\it rightmost\/} option in the list. +configuration file, that would be the \textit{rightmost} option in the list. %.lp -\item[\ib{wizweight}] +\item[wizweight] Augment object descriptions with their objects' weight (default off). Debug mode only. %.lp -\item[\ib{zerocomp}] +\item[zerocomp] When writing out a save file, perform zero-comp compression of the contents. Not all ports support zero-comp compression. It has no effect on reading an existing save file. -\elist +\end{description} %.hn 2 \subsection*{Window Port Customization options} @@ -4016,144 +5528,194 @@ \subsection*{Window Port Customization options} option is supported by the window port that you are currently using by checking to see if it shows up in the Options list. Some options are dynamic and can be specified during the game -with the `{\tt O}' command. +with the `\texttt{O}' command. -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{align\verb+_+message}] +\item[align\textunderscore message] Where to align or place the message window (top, bottom, left, or right) %.lp -\item[\ib{align\verb+_+status}] +\item[align\textunderscore status] Where to align or place the status window (top, bottom, left, or right). %.lp -\item[\ib{ascii\verb+_+map}] -If {\it NetHack\/} can, it should display an ascii map. -%.lp -\item[\ib{color}] -If {\it NetHack\/} can, it should display color for different monsters, -objects, and dungeon features. - -%.lp -\item[\ib{eight\verb+_+bit\verb+_+tty}] -Pass eight-bit character values (for example, specified with the -{\it traps \/} option) straight through to your terminal (default off). -%.lp -\item[\ib{font\verb+_+map}] -If {\it NetHack\/} can, it should use a font by the chosen name for the +\item[ascii\textunderscore map] +%.hw DECgraphics IBMgraphics \% don't hyphenate these +\hyphenation{DECgraphics IBMgraphics} +If \textit{NetHack} can, it should display the map using simple +characters (letters and punctuation) rather than \textit{tiles} graphics. +In some cases, characters can be augmented with line-drawing symbols; +use the \texttt{symset} +option to select a symbol set such as \textit{DECgraphics} +or \textit{IBMgraphics} if your display supports them. +Setting \texttt{ascii\textunderscore map} to \textit{True} forces +\texttt{tiled\textunderscore map} to be \textit{False}. +%.lp +\item[color] +If \textit{NetHack} can, it should display color for different monsters, +objects, and dungeon features (default on). +%.lp +\item[eight\textunderscore bit\textunderscore tty] +If \textit{NetHack} can, it should pass eight-bit character values (for example, specified with the +\textit{traps } option) straight through to your terminal (default off). +%.lp +\item[font\textunderscore map] +If \textit{NetHack} can, it should use a font by the chosen name for the map window. %.lp -\item[\ib{font\verb+_+menu}] -If {\it NetHack\/} can, it should use a font by the chosen name for menu +\item[font\textunderscore menu] +If \textit{NetHack} can, it should use a font by the chosen name for menu windows. %.lp -\item[\ib{font\verb+_+message}] -If {\it NetHack\/} can, it should use a font by the chosen name for the message window. +\item[font\textunderscore message] +If \textit{NetHack} can, it should use a font by the chosen name for the message window. %.lp -\item[\ib{font\verb+_+status}] -If {\it NetHack\/} can, it should use a font by the chosen name for the status window. +\item[font\textunderscore status] +If \textit{NetHack} can, it should use a font by the chosen name for the status window. %.lp -\item[\ib{font\verb+_+text}] -If {\it NetHack\/} can, it should use a font by the chosen name for text windows. +\item[font\textunderscore text] +If \textit{NetHack} can, it should use a font by the chosen name for text windows. %.lp -\item[\ib{font\verb+_+size\verb+_+map}] -If {\it NetHack\/} can, it should use this size font for the map window. +\item[font\textunderscore size\textunderscore map] +If \textit{NetHack} can, it should use this size font for the map window. %.lp -\item[\ib{font\verb+_+size\verb+_+menu}] -If {\it NetHack\/} can, it should use this size font for menu windows. +\item[font\textunderscore size\textunderscore menu] +If \textit{NetHack} can, it should use this size font for menu windows. %.lp -\item[\ib{font\verb+_+size\verb+_+message}] -If {\it NetHack\/} can, it should use this size font for the message window. +\item[font\textunderscore size\textunderscore message] +If \textit{NetHack} can, it should use this size font for the message window. %.lp -\item[\ib{font\verb+_+size\verb+_+status}] -If {\it NetHack\/} can, it should use this size font for the status window. +\item[font\textunderscore size\textunderscore status] +If \textit{NetHack} can, it should use this size font for the status window. %.lp -\item[\ib{font\verb+_+size\verb+_+text}] -If {\it NetHack\/} can, it should use this size font for text windows. +\item[font\textunderscore size\textunderscore text] +If \textit{NetHack} can, it should use this size font for text windows. %.lp -\item[\ib{fullscreen}] -If {\it NetHack\/} can, it should try and display on the entire screen rather than in a window. +\item[fullscreen] +If \textit{NetHack} can, it should try to display on the entire screen rather than in a window. %.lp -\item[\ib{guicolor}] +\item[guicolor] Use color text and/or highlighting attributes when displaying some non-map data (such as menu selector letters). Curses interface only; default is on. %.lp -\item[\ib{large\verb+_+font}] -If {\it NetHack\/} can, it should use a large font. +\item[large\textunderscore font] +If \textit{NetHack} can, it should use a large font. %.lp -\item[\ib{map\verb+_+mode}] -If {\it NetHack\/} can, it should display the map in the manner specified. +\item[map\textunderscore mode] +If \textit{NetHack} can, it should display the map in the manner specified. %.lp -\item[\ib{player\verb+_+selection}] -If {\it NetHack\/} can, it should pop up dialog boxes or use prompts for character selection. +\item[player\textunderscore selection] +If \textit{NetHack} can, it should pop up dialog boxes or use prompts for character selection. %.lp -\item[\ib{popup\verb+_+dialog}] -If {\it NetHack\/} can, it should pop up dialog boxes for input. +\item[popup\textunderscore dialog] +If \textit{NetHack} can, it should pop up dialog boxes for input. %.lp -\item[\ib{preload\verb+_+tiles}] -If {\it NetHack\/} can, it should preload tiles into memory. +\item[preload\textunderscore tiles] +If \textit{NetHack} can, it should preload tiles into memory. For example, in the protected mode MS-DOS version, control whether tiles get pre-loaded into RAM at the start of the game. Doing so enhances performance of the tile graphics, but uses more memory. (default on). -Cannot be set with the `{\tt O}' command. +Cannot be set with the `\texttt{O}' command. %.lp -\item[\ib{scroll\verb+_+amount}] -If {\it NetHack\/} can, it should scroll the display by this number of cells -when the hero reaches the scroll\verb+_+margin. +\item[scroll\textunderscore amount] +If \textit{NetHack} can, it should scroll the display by this number of cells +when the hero reaches the scroll\textunderscore margin. %.lp -\item[\ib{scroll\verb+_+margin}] -If {\it NetHack\/} can, it should scroll the display when the hero or cursor +\item[scroll\textunderscore margin] +If \textit{NetHack} can, it should scroll the display when the hero or cursor is this number of cells away from the edge of the window. %.lp -\item[\ib{selectsaved}] -If {\it NetHack\/} can, it should display a menu of existing saved games for the player to +\item[selectsaved] +If \textit{NetHack} can, it should display a menu of existing saved games for the player to choose from at game startup, if it can. Not all ports support this option. %.lp -\item[\ib{softkeyboard}] -If {\it NetHack\/} can, it should display an onscreen keyboard. +\item[softkeyboard] +If \textit{NetHack} can, it should display an onscreen keyboard. Handhelds are most likely to support this option. %.lp -\item[\ib{splash\verb+_+screen}] -If {\it NetHack\/} can, it should display an opening splash screen when +\item[splash\textunderscore screen] +If \textit{NetHack} can, it should display an opening splash screen when it starts up (default yes). %.lp -\item[\ib{statuslines}] +\item[statuslines] Number of lines for traditional below-the-map status display. -Acceptable values are 2 and 3 (default is 2). -Curses and tty interfaces only. -%.lp -\item[\ib{term\verb+_+cols} {\normalfont and}] -%.lp -\item[\ib{term\verb+_+rows}] +Acceptable values are \texttt{2} and \texttt{3} (default is \texttt{2}). + +%.lp "" +When set to \texttt{3}, the \texttt{tty} interface moves some fields around and +mainly shows status conditions on their own line. +A display capable of showing at least 25 lines is recommended. +The value can be toggled back and forth during the game with the `\texttt{O}' +command. + +%.lp "" +The \texttt{curses} interface does likewise if the +\textit{align\textunderscore status} +option is set to \textit{top} or \textit{bottom} but ignores +\textit{statuslines} +when set to \textit{left} or \textit{right}. + +%.lp "" +The \texttt{Qt} interface already displays more than 3 lines for status +so uses the +\textit{statuslines} +value differently. +A value of \texttt{3} renders status in the \texttt{Qt} interface's +original format, with the status window spread out vertically. +A value of \texttt{2} makes status be slightly condensed, moving some +fields to different lines to eliminate one whole line, reducing the +height needed. +(If NetHack has been built using a version of \texttt{Qt} +older than \texttt{qt-5.9}, +\textit{statuslines} +can only be set in the run-time configuration file or via NETHACKOPTIONS, +not during play with the `\texttt{O}' command.) +%.lp +\item[term\textunderscore cols \textrm{and}] +%.lp +\item[term\textunderscore rows] Curses interface only. Number of columns and rows to use for the display. Curses will attempt to resize to the values specified but will settle for smaller sizes if they are too big. Default is the current window size. %.lp -\item[\ib{tiled\verb+_+map}] -If {\it NetHack\/} can, it should display a tiled map if it can. -%.lp -\item[\ib{tile\verb+_+file}] +\item[tile\textunderscore file] Specify the name of an alternative tile file to override the default. +\\ +%.lp "" +Note: the X11 interface uses X resources rather than NetHack's options +to select an alternate tile file. +See \texttt{NetHack.ad}, the sample X ``application defaults'' file. %.lp -\item[\ib{tile\verb+_+height}] +\item[tile\textunderscore height] Specify the preferred height of each tile in a tile capable port. %.lp -\item[\ib{tile\verb+_+width}] +\item[tile\textunderscore width] Specify the preferred width of each tile in a tile capable port %.lp -\item[\ib{use\verb+_+darkgray}] +\item[tiled\textunderscore map] +If \textit{NetHack} can, it should display the map using \textit{tiles} graphics +rather than simple characters (letters and punctuation, possibly +augmented by line-drawing symbols). +Setting \texttt{tiled\textunderscore map} to \textit{True} forces +\texttt{ascii\textunderscore map} to be \textit{False}. +%.lp +\item[use\textunderscore darkgray] Use bold black instead of blue for black glyphs (TTY only). %.lp -\item[\ib{use\verb+_+inverse}] -If {\it NetHack\/} can, it should display inverse when the game specifies it. +\item[use\textunderscore inverse] +If \textit{NetHack} can, it should display inverse when the game specifies it. %.lp -\item[\ib{vary\verb+_+msgcount}] -If {\it NetHack\/} can, it should display this number of messages at a time +\item[use\textunderscore menu\textunderscore glyphs] +If \textit{NetHack} can, it should display glyphs next to objects in the +inventory. +%.lp +\item[vary\textunderscore msgcount] +If \textit{NetHack} can, it should display this number of messages at a time in the message window. %.lp -\item[\ib{windowborders}] +\item[windowborders] Whether to draw boxes around the map, status area, message area, and persistent inventory window if enabled. Curses interface only. @@ -4161,46 +5723,84 @@ \subsection*{Window Port Customization options} %.sd %.si -{\tt 0} --- off, never show borders\\ -{\tt 1} --- on, always show borders\\ -{\tt 2} --- auto, on display is at least -(\verb&24+2&)x(\verb&80+2&)\ \ (default)\\ +\texttt{0} --- off, never show borders\\ +\texttt{1} --- on, always show borders\\ +\texttt{2} --- auto, on display is at least +$(24+2)\times(80+2)$ [default]\\ +\texttt{3} --- on, except forced off for perm\textunderscore invent\\ +\texttt{4} --- auto, except forced off for perm\textunderscore invent\\ %.ei %.ed -%.lp " +%.lp "" (The 26x82 size threshold for `2' refers to number of rows and columns of the display. -A width of at least 110 columns (\verb&80+2+26+2&) is needed for -{\it align_status\/} -set to {tt left} or {\tt right}.) -%.lp -\item[\ib{windowcolors}] -If {\it NetHack\/} can, it should display windows with the specified -foreground/background colors. Windows GUI only. The format is -\begin{verbatim} - OPTION=windowcolors:wintype foreground/background -\end{verbatim} +A width of at least 110 columns ($80+2+26+2$) is needed for +\textit{align\textunderscore status} +set to \texttt{left} or \texttt{right}.) +%.lp "" +The persistent inventory window, when enabled, can grow until it is +too big to fit on most displays, resulting in truncation of its contents. +If borders are forced on (1) or the display is big enough to show them (2), +setting the value to 3 or 4 instead will keep borders for the map, message, +and status windows but have room for two additional lines of inventory +plus widen each inventory line by two columns. +%.lp +\item[windowcolors] +If \textit{NetHack} can, it should display all windows of a particular style +with the specified foreground and background colors. +Windows GUI and curses windowport only. +The format is\\ +\texttt{~~~~OPTION=windowcolors:}\textit{style foreground}\texttt{/}\textit{background}\\ +where \textit{style} is one of \texttt{menu}, \texttt{message}, \texttt{status}, +or \texttt{text}, and +\textit{foreground} and \textit{background} are colors, either numeric (hash +sign followed by three pairs of hexadecimal digits, \textit{\#rrggbb}), +one of the named colors (\textit{black}, \textit{red}, \textit{green}, \textit{brown}, +\textit{blue}, \textit{magenta}, \textit{cyan}, \textit{orange}, +\textit{bright-green}, \textit{yellow}, \textit{bright-blue}, \textit{bright-magenta}, +\textit{bright-cyan}, \textit{white}, \textit{gray}, \textit{purple}, +\textit{silver}, \textit{maroon}, \textit{fuchsia}, \textit{lime}, \textit{olive}, +\textit{navy}, \textit{teal}, \textit{aqua}), +or (for Windows only) one of Windows UI colors (\textit{trueblack}, +\textit{activeborder}, \textit{activecaption}, \textit{appworkspace}, \textit{background}, +\textit{btnface}, \textit{btnshadow}, \textit{btntext}, \textit{captiontext}, +\textit{graytext}, \textit{greytext}, \textit{highlight}, +\textit{highlighttext}, \textit{inactiveborder}, \textit{inactivecaption}, \textit{menu}, +\textit{menutext}, \textit{scrollbar}, \textit{window}, \textit{windowframe}, +\textit{windowtext}). + +%.lp +\item[wraptext] +If \textit{NetHack} can, it should wrap long lines of text if they don't fit +in the visible area of the window. +\end{description} + +%.hn 2 +\subsection*{Crash Report Options} %.pg -where wintype is one of {\it menu}, {\it message}, {\it status}, or {\it text}, and -foreground and background are colors, either a hexadecimal {\it \#rrggbb}, -one of the named colors ({\it black}, {\it red}, {\it green}, {\it brown}, -{\it blue}, {\it magenta}, {\it cyan}, {\it orange}, -{\it brightgreen}, {\it yellow}, {\it brightblue}, {\it brightmagenta}, -{\it brightcyan}, {\it white}, {\it trueblack}, {\it gray}, {\it purple}, -{\it silver}, {\it maroon}, {\it fuchsia}, {\it lime}, {\it olive}, -{\it navy}, {\it teal}, {\it aqua}), or one of Windows UI colors ({\it activeborder}, -{\it activecaption}, {\it appworkspace}, {\it background}, {\it btnface}, {\it btnshadow}, -{\it btntext}, {\it captiontext}, {\it graytext}, {\it greytext}, {\it highlight}, -{\it highlighttext}, {\it inactiveborder}, {\it inactivecaption}, {\it menu}, -{\it menutext}, {\it scrollbar}, {\it window}, {\it windowframe}, {\it windowtext}). +Please note that NetHack does not send {\textbf any} information off your +computer unless you manually click submit on a form. +%.si +\begin{description} %.lp -\item[\ib{wraptext}] -If {\it NetHack\/} can, it should wrap long lines of text if they don't fit -in the visible area of the window. -\elist +\item[OPTION=crash\textunderscore email:\textit{email\textunderscore address}] +%.lp +\item[OPTION=crash\textunderscore name:\textit{your\textunderscore name}] +%.ei +\end{description} +These options are used only to save you some typing on the crash +report and \#bugreport forms. +%.si +\begin{description} +%.lp +\item[OPTION=crash\textunderscore urlmax:\textit{bytes}] +%.ei +\end{description} +This option is used to limit the length of the URLs generated and is only +needed if your browser cannot handle arbitrarily long URLs. %.hn 2 \subsection*{Platform-specific Customization options} @@ -4209,120 +5809,121 @@ \subsection*{Platform-specific Customization options} Here are explanations of options that are used by specific platforms or ports to customize and change the port behavior. -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{altkeyhandling}] -Select an alternate way to handle keystrokes ({\it Win32 tty\/ NetHack\/} only). -The name of the handling type is one of {\it default}, {\it ray}, {\it 340} +\item[altkeyhandling] +Select an alternate way to handle keystrokes (\textit{Win32 tty NetHack} only). +The name of the handling type is one of \textit{default}, \textit{ray}, \textit{340} +%.\" \item[altmeta] +%.\" On Amiga, this option controls whether typing ``Alt'' plus another key +%.\" functions as a meta-shift for that key (default on). %.lp -\item[\ib{altmeta}] -On Amiga, this option controls whether typing ``Alt'' plus another key -functions as a meta-shift for that key (default on). -%.lp -\item[\ib{altmeta}] -On other (non-Amiga) systems where this option is available, it can be -set to tell {\it NetHack\/} to convert a two character sequence beginning with +\item[altmeta] +%.\" On other (non-Amiga) systems where this option is available, it can be +On systems where this option is available, it can be +set to tell \textit{NetHack} to convert a two character sequence beginning with ESC into a meta-shifted version of the second character (default off). %.lp "" This conversion is only done for commands, not for other input prompts. Note that typing one or more digits as a count prefix prior to a -command---preceded by {\tt n} if the {\it number\verb+_+pad\/} -option is set---is also subject to this conversion, so attempting to -abort the count by typing ESC will leave {\it NetHack\/} waiting for another -character to complete the two character sequence. Type a second ESC to -finish cancelling such a count. At other prompts a single ESC suffices. -%.lp -\item[\ib{BIOS}] +command---preceded by \texttt{n} if the \textit{number\textunderscore pad} +option is set---is +also subject to this conversion, so attempting to +abort the count by typing ESC will leave \textit{NetHack} waiting for another +character to complete the two character sequence. +Type a second ESC to finish cancelling such a count. +At other prompts a single ESC suffices. +%.lp +\item[BIOS] Use BIOS calls to update the screen display quickly and to read the keyboard (allowing the use of arrow keys to move) on machines with an IBM PC -compatible BIOS ROM (default off, {\it OS/2, PC\/ {\rm and} ST NetHack\/} only). -%.lp -\item[\ib{flush}] -(default off, {\it Amiga NetHack \/} only). -%.lp -\item[\ib{Macgraphics}] -(default on, {\it Mac NetHack \/} only). -%.lp -\item[\ib{page\verb+_+wait}] -(default off, {\it Mac NetHack \/} only). +compatible BIOS ROM (default off, \textit{OS/2, PC {\rm and} ST NetHack} only). %.lp -\item[\ib{rawio}] +\item[rawio] Force raw (non-cbreak) mode for faster output and more -bulletproof input (MS-DOS sometimes treats `{\tt \^{}P}' as a printer toggle -without it) (default off, {\it OS/2, PC\/ {\rm and} ST NetHack\/} only). +bulletproof input (MS-DOS sometimes treats `\texttt{\textasciicircum P}' as a printer toggle +without it) (default off, \textit{OS/2, PC {\rm and} ST NetHack} only). Note: DEC Rainbows hang if this is turned on. -Cannot be set with the `{\tt O}' command. +Cannot be set with the `\texttt{O}' command. %.lp -\item[\ib{soundcard}] -(default off, {\it PC NetHack \/} only). -Cannot be set with the `{\tt O}' command. -%.lp -\item[\ib{subkeyvalue}] -({\it Win32 tty NetHack \/} only). +\item[subkeyvalue] +(\textit{Win32 tty NetHack } only). May be used to alter the value of keystrokes that the operating system -returns to {\it NetHack\/} to help compensate for international keyboard +returns to \textit{NetHack} to help compensate for international keyboard issues. OPTIONS=subkeyvalue:171/92 -will return 92 to {\it NetHack\/}, if 171 was originally going to be returned. -You can use multiple subkeyvalue statements in the configuration file +will return 92 to \textit{NetHack}, if 171 was originally going to be returned. +You can use multiple subkeyvalue assignments in the configuration file if needed. -Cannot be set with the `{\tt O}' command. -%.lp -\item[\ib{video}] -Set the video mode used ({\it PC\/ NetHack\/} only). -Values are {\it autodetect\/}, {\it default\/}, or {\it vga\/}. -Setting {\it vga\/} (or {\it autodetect\/} with vga hardware present) will -cause the game to display tiles. -Cannot be set with the `{\tt O}' command. -%.lp -\item[\ib{videocolors}] +Cannot be set with the `\texttt{O}' command. +%.lp +\item[video] +Set the video mode used (\textit{PC NetHack} only). +Values are \textit{autodetect}, \textit{default}, \textit{vga}, or \textit{vesa}. +Setting \textit{vesa} will cause the game to display tiles, using the full +capability of the VGA hardware. +Setting \textit{vga} will cause the game to display tiles, fixed at 640x480 +in 16 colors, a mode that is compatible with all VGA hardware. Third party +tilesets will probably not work. +Setting \textit{autodetect} attempts \textit{vesa}, then \textit{vga}, and +finally sets \textit{default} if neither of those modes works. +Cannot be set with the `\texttt{O}' command. +%.lp +\item[video\textunderscore height] +Set the VGA mode resolution height (MS-DOS only, with video:vesa) +%.lp +\item[video\textunderscore width] +Set the VGA mode resolution width (MS-DOS only, with video:vesa) +%.lp +\item[videocolors] \begin{sloppypar} -Set the color palette for PC systems using NO\verb+_+TERMS -(default 4-2-6-1-5-3-15-12-10-14-9-13-11, {\it PC\/ NetHack\/} only). +Set the color palette for PC systems using NO\textunderscore TERMS +(default 4-2-6-1-5-3-15-12-10-14-9-13-11, \textit{PC NetHack} only). The order of colors is red, green, brown, blue, magenta, cyan, bright.white, bright.red, bright.green, yellow, bright.blue, bright.magenta, and bright.cyan. -Cannot be set with the `{\tt O}' command. +Cannot be set with the `\texttt{O}' command. \end{sloppypar} %.lp -\item[\ib{videoshades}] +\item[videoshades] Set the intensity level of the three gray scales available -(default dark normal light, {\it PC\/ NetHack\/} only). +(default dark normal light, \textit{PC NetHack} only). If the game display is difficult to read, try adjusting these scales; -if this does not correct the problem, try {\tt !color}. -Cannot be set with the `{\tt O}' command. -\elist +if this does not correct the problem, try \texttt{!color}. +Cannot be set with the `\texttt{O}' command. +\end{description} -%.nh 2 +%.hn 2 \subsection*{Regular Expressions} %.pg Regular expressions are normally POSIX extended regular expressions. It is -possible to compile {\it NetHack\/} without regular expression support on +possible to compile \textit{NetHack} without regular expression support on a platform where there is no regular expression library. While this is not true of any modern -platform, if your {\it NetHack\/} was built this way, patterns are instead glob -patterns. This applies to Autopickup exceptions, Message types, Menu colors, +platform, if your \textit{NetHack} was built this way, patterns are instead glob +patterns; regardless, this document refers to both as ``regular expressions.'' +This applies to Autopickup exceptions, Message types, Menu colors, and User sounds. %.hn 2 \subsection*{Configuring Autopickup Exceptions} %.pg -You can further refine the behavior of the ``{\tt autopickup}'' option -beyond what is available through the ``{\tt pickup\verb+_+types}'' option. +You can further refine the behavior of the ``\texttt{autopickup}'' option +beyond what is available through the ``\texttt{pickup\textunderscore types}'' option. %.pg -By placing ``{\tt autopickup\verb+_+exception}'' lines in your configuration +By placing ``\texttt{autopickup\textunderscore exception}'' lines in your configuration file, you can define patterns to be checked when the game is about to autopickup something. -\blist{} +\begin{description} %.lp -\item[\ib{autopickup\verb+_+exception}] -Sets an exception to the ``{\it pickup\verb+_+types}'' option. -The {\it autopickup\verb+_+exception\/} option should be followed by a regular +\item[autopickup\textunderscore exception] +Sets an exception to the ``\textit{pickup\textunderscore types}'' option. +The \textit{autopickup\textunderscore exception} option should be followed by a regular expression to be used as a pattern to match against the singular form of the description of an object at your location. @@ -4331,21 +5932,21 @@ \subsection*{Configuring Autopickup Exceptions} %.sd %.si -{\tt <} --- always pickup an object that matches rest of pattern;\\ -{\tt >} --- never pickup an object that matches rest of pattern. +\texttt{<} --- always pickup an object that matches rest of pattern;\\ +\texttt{>} --- never pickup an object that matches rest of pattern. %.ei %.ed -The {\it autopickup\verb+_+exception\/} rules are processed in the order +The \textit{autopickup\textunderscore exception} rules are processed in the order in which they appear in your configuration file, thus allowing a later rule to override an earlier rule. %.lp "" -Exceptions can be set with the `{\tt O}' command, but because they are not +Exceptions can be set with the `\texttt{O}' command, but because they are not included in your configuration file, they won't be in effect if you save and then restore your game. -{\it autopickup\verb+_+exception\/} rules are not saved with the game. -\elist +\textit{autopickup\textunderscore exception} rules are not saved with the game. +\end{description} %.lp "Here are some examples:" Here are some examples: @@ -4368,192 +5969,175 @@ \subsection*{Changing Key Bindings} %.pg It is possible to change the default key bindings of some special commands, -menu accelerator keys, and extended commands, by using BIND stanzas in the +menu accelerator keys, extended commands, by using BIND stanzas in the configuration file. Format is key, followed by the command to bind to, -separated by a colon. The key can be a single character (``{\tt x}''), -a control key (``{\tt \^{}X}'', ``{\tt C-x}''), a meta key (``{\tt M-x}''), -or a three-digit decimal ASCII code. +separated by a colon. The key can be a single character (``\texttt{x}''), +a control key (``\texttt{\textasciicircum X}'', ``\texttt{C-x}''), a meta key (``\texttt{M-x}''), +a mouse button, or a three-digit decimal ASCII code. %.pg For example: \begin{verbatim} BIND=^X:getpos.autodescribe - BIND={:menu_first_page + BIND=\:menu_first_page BIND=v:loot \end{verbatim} -\blist{} +\begin{description}[font=\mdseries\ttfamily] %.lp "Extended command keys" -\item[\tb{Extended command keys}] +\item[Extended command keys] You can bind multiple keys to the same extended command. Unbind a key by -using ``{\tt nothing}'' as the extended command to bind to. You can also bind -the ``{\tt }'', ``{\tt }'', and ``{\tt }'' keys. +using ``\texttt{nothing}'' as the extended command to bind to. You can also bind +the ``\texttt{}'', ``\texttt{}'', and ``\texttt{}'' keys. %.lp "Menu accelerator keys" -\item[\tb{Menu accelerator keys}] +\item[Menu accelerator keys] The menu control or accelerator keys can also be rebound via OPTIONS lines in the configuration file. -You cannot bind object symbols into menu accelerators. +You cannot bind object symbols or selection letters into menu accelerators. +Some interfaces only support some of the menu accelerators. + +%.lp "Mouse buttons" +\item[Mouse buttons] +You can bind ``mouse1'' or ``mouse2'' to ``\texttt{nothing}'', +``\texttt{therecmdmenu}'', ``\texttt{clicklook}'', or ``\texttt{mouseaction}''. %.lp "Special command keys" -\item[\tb{Special command keys}] +\item[Special command keys] Below are the special commands you can rebind. Some of them can be bound to same keys with no problems, others are in the same ``context'', and if bound to same keys, only one of those commands will be available. Special command can only be bound to a single key. -\elist +\end{description} %.pg -\blist{\itemindent 10mm \labelwidth 15mm \rightmargin 15mm} +\begin{description}[itemindent=10mm, labelwidth=15mm, rightmargin=15mm] %.lp -\item[{\bb{count}}] +\item[count] Prefix key to start a count, to repeat a command this many times. -With {\it number\verb+_+pad\/} only. Default is~`{\tt n}'. -%.lp -\item[{\bb{doinv}}] -Show inventory. With {\it number\verb+_+pad\/} only. Default is~`{\tt 0}'. +With \textit{number\textunderscore pad} only. Default is~`\texttt{n}'. %.lp -\item[{\bb{fight}}] -Prefix key to force fight a direction. Default is~`{\tt F}'. +\item[getdir.help] +When asked for a direction, the key to show the help. Default is~`\texttt{?}'. %.lp -\item[{\bb{fight.numpad}}] -Prefix key to force fight a direction. With {\it number\verb+_+pad\/} only. -Default is~`{\tt -}'. +\item[getdir.mouse] +When asked for a direction, the key to initiate a simulated mouse click. +You will be asked to pick a location. +Use movement keystrokes to move the cursor around the map, then type +the getpos.pick.once key (default `\texttt{,}') +or the getpos.pick key (default `\texttt{.}') +to finish as if performing a left or right click. +Only useful when using the \texttt{\#therecmdmenu} command. +Default is~`\texttt{\textunderscore}'. %.lp -\item[{\bb{getdir.help}}] -When asked for a direction, the key to show the help. Default is~`{\tt ?}'. +\item[getdir.self] +When asked for a direction, the key to target yourself. Default is~`\texttt{.}'. %.lp -\item[{\bb{getdir.self}}] -When asked for a direction, the key to target yourself. Default is~`{\tt .}'. +\item[getdir.self2] +When asked for a direction, an alternate key to target yourself. +Default is~`\texttt{s}'. %.lp -\item[{\bb{getdir.self2}}] -When asked for a direction, the key to target yourself. Default is~`{\tt s}'. +\item[getpos.autodescribe] +When asked for a location, the key to toggle \textit{autodescribe}. +Default is~`\texttt{\#}'. %.lp -\item[{\bb{getpos.autodescribe}}] -When asked for a location, the key to toggle {\it autodescribe\/}. -Default is~`{\tt \#}'. -%.lp -\item[{\bb{getpos.all.next}}] +\item[getpos.all.next] When asked for a location, the key to go to next closest interesting thing. -Default is~`{\tt a}'. +Default is~`\texttt{a}'. %.lp -\item[{\bb{getpos.all.prev}}] +\item[getpos.all.prev] When asked for a location, the key to go to previous closest interesting thing. -Default is~`{\tt A}'. +Default is~`\texttt{A}'. %.lp -\item[{\bb{getpos.door.next}}] +\item[getpos.door.next] When asked for a location, the key to go to next closest door or doorway. -Default is~`{\tt d}'. +Default is~`\texttt{d}'. %.lp -\item[{\bb{getpos.door.prev}}] +\item[getpos.door.prev] When asked for a location, the key to go to previous closest door or doorway. -Default is~`{\tt D}'. +Default is~`\texttt{D}'. %.lp -\item[{\bb{getpos.help}}] -When asked for a location, the key to show help. Default is~`{\tt ?}'. +\item[getpos.help] +When asked for a location, the key to show help. Default is~`\texttt{?}'. %.lp -\item[{\bb{getpos.mon.next}}] +\item[getpos.mon.next] When asked for a location, the key to go to next closest monster. -Default is~`{\tt m}'. +Default is~`\texttt{m}'. %.lp -\item[{\bb{getpos.mon.prev}}] +\item[getpos.mon.prev] When asked for a location, the key to go to previous closest monster. -Default is~`{\tt M}'. +Default is~`\texttt{M}'. %.lp -\item[{\bb{getpos.obj.next}}] +\item[getpos.obj.next] When asked for a location, the key to go to next closest object. -Default is~`{\tt o}'. +Default is~`\texttt{o}'. %.lp -\item[{\bb{getpos.obj.prev}}] +\item[getpos.obj.prev] When asked for a location, the key to go to previous closest object. -Default is~`{\tt O}'. +Default is~`\texttt{O}'. %.lp -\item[{\bb{getpos.menu}}] +\item[getpos.menu] When asked for a location, and using one of the next or previous keys to -cycle through targets, toggle showing a menu instead. Default is~`{\tt !}'. +cycle through targets, toggle showing a menu instead. Default is~`\texttt{!}'. %.lp -\item[{\bb{getpos.moveskip}}] +\item[getpos.moveskip] When asked for a location, and using the shifted movement keys or meta-digit keys to fast-move around, move by skipping the same glyphs instead of by 8 units. -Default is~`{\tt *}'. +Default is~`\texttt{*}'. %.lp -\item[{\bb{getpos.filter}}] +\item[getpos.filter] When asked for a location, change the filtering mode when using one of the next or previous keys to cycle through targets. Toggles between no -filtering, in view only, and in the same area only. Default is~`{\tt "}'. +filtering, in view only, and in the same area only. Default is~`\texttt{"}'. %.lp -\item[{\bb{getpos.pick}}] +\item[getpos.pick] When asked for a location, the key to choose the location, and possibly -ask for more info. Default is~`{\tt .}'. +ask for more info. +When simulating a mouse click after being asked for a direction (see +getdir.mouse above), the key to use to respond as right click. +Default is~`\texttt{.}'. %.lp -\item[{\bb{getpos.pick.once}}] +\item[getpos.pick.once] When asked for a location, the key to choose the location, and skip -asking for more info. Default is~`{\tt ,}'. +asking for more info. +When simulating a mouse click after being asked for a direction, +the key to respond as left click. +Default is~`\texttt{,}'. %.lp -\item[{\bb{getpos.pick.quick}}] +\item[getpos.pick.quick] When asked for a location, the key to choose the location, skip asking -for more info, and exit the location asking loop. Default is~`{\tt ;}'. +for more info, and exit the location asking loop. Default is~`\texttt{;}'. %.lp -\item[{\bb{getpos.pick.verbose}}] +\item[getpos.pick.verbose] When asked for a location, the key to choose the location, and show more -info without asking. Default is~`{\tt :}'. +info without asking. Default is~`\texttt{:}'. %.lp -\item[{\bb{getpos.self}}] +\item[getpos.self] When asked for a location, the key to go to your location. -Default is~`{\tt @}'. +Default is~`\texttt{@}'. %.lp -\item[{\bb{getpos.unexplored.next}}] +\item[getpos.unexplored.next] When asked for a location, the key to go to next closest unexplored location. -Default is~`{\tt x}'. +Default is~`\texttt{x}'. %.lp -\item[{\bb{getpos.unexplored.prev}}] +\item[getpos.unexplored.prev] When asked for a location, the key to go to previous closest unexplored -location. Default is~`{\tt X}'. +location. Default is~`\texttt{X}'. %.lp -\item[{\bb{getpos.valid}}] +\item[getpos.valid] When asked for a location, the key to go to show valid target locations. -Default is~`{\tt \$}'. +Default is~`\texttt{\$}'. %.lp -\item[{\bb{getpos.valid.next}}] +\item[getpos.valid.next] When asked for a location, the key to go to next closest valid location. -Default is~`{\tt z}'. +Default is~`\texttt{z}'. %.lp -\item[{\bb{getpos.valid.prev}}] +\item[getpos.valid.prev] When asked for a location, the key to go to previous closest valid location. -Default is~`{\tt Z}'. -%.lp -\item[{\bb{nopickup}}] -Prefix key to move without picking up items. Default is~`{\tt m}'. -%.lp -\item[{\bb{redraw}}] -Key to redraw the screen. Default is~`{\tt \^{}R}'. -%.lp -\item[{\bb{redraw.numpad}}] -Key to redraw the screen. With {\it number\verb+_+pad\/} only. -Default is~`{\tt \^{}L}'. -%.lp -\item[{\bb{repeat}}] -Key to repeat previous command. Default is~`{\tt \^{}A}'. -%.lp -\item[{\bb{reqmenu}}] -Prefix key to request menu from some commands. Default is~`{\tt m}'. -%.lp -\item[{\bb{run}}] -Prefix key to run towards a direction. Default is~`{\tt G}'. -%.lp -\item[{\bb{run.nopickup}}] -Prefix key to run towards a direction without picking up items on the way. -Default is~`{\tt M}'. -%.lp -\item[{\bb{run.numpad}}] -Prefix key to run towards a direction. With {\it number\verb+_+pad\/} only. -Default is~`{\tt 5}'. -%.lp -\item[{\bb{rush}}] -Prefix key to rush towards a direction. Default is~`{\tt g}'. -\elist +Default is~`\texttt{Z}'. +\end{description} %.hn 2 @@ -4569,27 +6153,27 @@ \subsection*{Configuring Message Types} \begin{verbatim} MSGTYPE=type "pattern" \end{verbatim} -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{type}] +\item[type] how the message should be shown: %.sd %.si \\ -{\tt show} --- show message normally.\\ -{\tt hide} --- never show the message.\\ -{\tt stop} --- wait for user with more-prompt.\\ -{\tt norep} --- show the message once, but not again if no other message is +\texttt{show} --- show message normally.\\ +\texttt{hide} --- never show the message.\\ +\texttt{stop} --- wait for user with more-prompt.\\ +\texttt{norep} --- show the message once, but not again if no other message is shown in between. %.ei %.ed %.lp -\item[\ib{pattern}] +\item[pattern] the pattern to match. The pattern should be a regular expression. -\elist +\end{description} %.lp "" -Here's an example of message types using {\it NetHack's\/} internal +Here's an example of message types using \textit{NetHack's} internal pattern matching facility: \begin{verbatim} @@ -4599,7 +6183,7 @@ \subsection*{Configuring Message Types} specifies that whenever a message ``You feel hungry'' is shown, the user is prompted with more-prompt, and a message matching -``You displaced \verb+<+something\verb+>+'' is not shown at all. +``You displaced '' is not shown at all. %.lp The order of the defined MSGTYPE lines is important; the last matching @@ -4624,40 +6208,40 @@ \subsection*{Configuring Menu Colors} MENUCOLOR="pattern"=color&attribute \end{verbatim} -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{pattern}] +\item[pattern] the pattern to match; %.lp -\item[\ib{color}] +\item[color] the color to use for lines matching the pattern; %.lp -\item[\ib{attribute}] +\item[attribute] the attribute to use for lines matching the pattern. The attribute is optional, and if left out, you must also leave out the preceding ampersand. If no attribute is defined, no attribute is used. -\elist +\end{description} %.lp "" The pattern should be a regular expression. %.lp "" -Allowed colors are {\it black}, {\it red}, {\it green}, {\it brown}, -{\it blue}, {\it magenta}, {\it cyan}, {\it gray}, {\it orange}, -{\it light-green}, {\it yellow}, {\it light-blue}, {\it light-magenta}, -{\it light-cyan}, and {\it white}. -And {\it no-color}, the default foreground color, which isn't necessarily +Allowed colors are \textit{black}, \textit{red}, \textit{green}, \textit{brown}, +\textit{blue}, \textit{magenta}, \textit{cyan}, \textit{gray}, \textit{orange}, +\textit{light-green}, \textit{yellow}, \textit{light-blue}, \textit{light-magenta}, +\textit{light-cyan}, and \textit{white}. +And \textit{no-color}, the default foreground color, which isn't necessarily the same as any of the other colors. %.lp "" -Allowed attributes are {\it none}, {\it bold}, {\it dim}, {\it underline}, -{\it blink}, and {\it inverse}. -{\it Normal\/} is a synonym for {\it none}. +Allowed attributes are \textit{none}, \textit{bold}, \textit{dim}, \textit{italic}, +\textit{underline},\textit{blink}, and \textit{inverse}. +\textit{Normal} is a synonym for \textit{none}. Note that the platform used may interpret the attributes any way it wants. %.lp "" -Here's an example of menu colors using {\it NetHack's\/} internal +Here's an example of menu colors using \textit{NetHack's} internal pattern matching facility: \begin{verbatim} @@ -4677,7 +6261,7 @@ \subsection*{Configuring Menu Colors} %.pg Note that if you intend to have one or more color specifications match ``~uncursed~'', you will probably want to turn the -{\it implicit\verb+_+uncursed\/} +\textit{implicit\textunderscore uncursed} option off so that all items known to be uncursed are actually displayed with the ``uncursed'' description. @@ -4695,35 +6279,46 @@ \subsection*{Configuring User Sounds} The following configuration file entries are relevant to mapping user sounds to messages: -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{SOUNDDIR}] +\item[SOUNDDIR] The directory that houses the sound files to be played. %.lp -\item[\ib{SOUND}] +\item[SOUND] An entry that maps a sound file to a user-specified message pattern. Each SOUND entry is broken down into the following parts: %.sd %.si -{\tt MESG } --- message window mapping (the only one supported in 3.6);\\ -{\tt pattern } --- the pattern to match;\\ -{\tt sound file} --- the sound file to play;\\ -{\tt volume } --- the volume to be set while playing the sound file. +\texttt{MESG} --- message window mapping (the only one supported in 5.0.0);\\ +\texttt{msgtype} --- optional; message type to use, see ``Configuring User Sounds''\\ +\texttt{pattern} --- the pattern to match;\\ +\texttt{sound file} --- the sound file to play;\\ +\texttt{volume} --- the volume to be set while playing the sound file;\\ +\texttt{sound index} --- optional; the index corresponding to a sound file. %.ei %.ed -\elist +\end{description} %.lp "" The pattern should be a regular expression. +For example: + +\begin{verbatim} + SOUNDDIR=C:\nethack\sounds + SOUND=MESG "This door is locked" "lock.wav" 100 + SOUND=MESG hide "^You miss the " "swing.wav" 75 +\end{verbatim} +%.pg + %.lp %.hn 2 \subsection*{Configuring Status Hilites} %.pg -Your copy of {\it NetHack\/} may have been compiled with support -for {\it Status Hilites}. +Your copy of \textit{NetHack} may have been compiled with support +for \textit{Status Hilites}. If so, you can customize your game display by setting thresholds to change the color or appearance of fields in the status display. @@ -4738,8 +6333,8 @@ \subsection*{Configuring Status Hilites} \begin{verbatim} OPTION=hilite_status:hitpoints/<=30%/red/normal \end{verbatim} -(That example is actually specifying {\tt red\&normal} for {\tt <=30\%} -and {\tt no-color\&normal} for {\tt >30\%}.)\\ +(That example is actually specifying \texttt{red\& normal} for \texttt{<=30\%} +and \texttt{no-color\& normal} for \texttt{>30\%}.)\\ For another example, the following line in your configuration file will cause wisdom to be displayed red if it drops and green if it rises:\\ @@ -4749,10 +6344,10 @@ \subsection*{Configuring Status Hilites} Allowed colors are black, red, green, brown, blue, magenta, cyan, gray, orange, light-green, yellow, light-blue, light-magenta, light-cyan, and white. -And {\it no-color}, the default foreground color on the display, which +And \textit{no-color}, the default foreground color on the display, which is not necessarily the same as black or white or any of the other colors. -Allowed attributes are none, bold, dim, underline, blink, and inverse. +Allowed attributes are none, bold, dim, underline, italic, blink, and inverse. ``Normal'' is a synonym for ``none''; they should not be used in combination with any of the other attributes. @@ -4760,7 +6355,7 @@ \subsection*{Configuring Status Hilites} To specify multiple attributes, use `+' to combine those. %.lp "" -For example: {\tt magenta\&inverse+dim}. +For example: \texttt{magenta\& inverse+dim}. Note that the display may substitute or ignore particular attributes depending upon its capabilities, and in general may interpret the @@ -4770,7 +6365,7 @@ \subsection*{Configuring Status Hilites} On others, issuing an attribute request while another is already set up will replace the earlier attribute rather than combine with it. Since nethack issues attribute requests sequentially (at least with -the {\it tty} interface) rather than all at once, the only way a +the \textit{tty} interface) rather than all at once, the only way a situation like that can be controlled is to specify just one attribute. You can adjust the display of the following status fields: @@ -4799,46 +6394,51 @@ \subsection*{Configuring Status Hilites} %.lp "" Instead of a behavior, `condition' takes the following condition flags: -{\it stone}, {\it slime}, {\it strngl}, {\it foodpois}, {\it termill}, -{\it blind}, {\it deaf}, {\it stun}, {\it conf}, {\it hallu}, -{\it lev}, {\it fly}, and {\it ride}. -You can use `major\_troubles' as an alias -for stone through termill, `minor\_troubles' for blind through hallu, +\textit{stone}, \textit{slime}, \textit{strngl}, \textit{foodpois}, \textit{termill}, +\textit{blind}, \textit{deaf}, \textit{stun}, \textit{conf}, \textit{hallu}, +\textit{lev}, \textit{fly}, and \textit{ride}. +You can use `major\textunderscore troubles' as an alias +for stone through termill, `minor\textunderscore troubles' for blind through hallu, `movement' for lev, fly, and ride, and `all' for every condition. %.lp "" Allowed behaviors are ``always'', ``up'', ``down'', ``changed'', a percentage or absolute number threshold, or text to match against. +For the \textit{hitpoints} field, the additional behavior ``criticalhp'' +is available. +It overrides other behavior rules if +hit points are at or below the \textit{major problem} threshold +(which varies depending upon maximum hit points and experience level). -\blist{} +\begin{description}[font=\mdseries\ttfamily] %.lp "*" -\item[{\tt always}] will set the default attributes for that field. +\item[always] will set the default attributes for that field. %.lp "*" -\item[{\tt up}{\normalfont, }{\tt down}] set the field attributes +\item[up \textrm{\textmd{,}} down] set the field attributes for when the field value changes upwards or downwards. This attribute -times out after {\tt statushilites} turns. +times out after \texttt{statushilites} turns. %.lp "*" -\item[{\tt changed}] sets the field attribute for when the field value -changes. This attribute times out after {\tt statushilites} turns. +\item[changed] sets the field attribute for when the field value +changes. This attribute times out after \texttt{statushilites} turns. (If a field has both a ``changed'' rule and an ``up'' or ``down'' rule which matches a change in the field's value, the ``up'' or ``down'' one takes precedence.) %.lp "*" -\item[{\tt percentage}] sets the field attribute when the field value +\item[percentage] sets the field attribute when the field value matches the percentage. -It is specified as a number between 0 and 100, followed by `{\tt \%}' +It is specified as a number between 0 and 100, followed by `\texttt{\%}' (percent sign). -If the percentage is prefixed with `{\tt <=}' or `{\tt >=}', +If the percentage is prefixed with `\texttt{<=}' or `\texttt{>=}', it also matches when value is below or above the percentage. -Use prefix `{\tt <}' or `{\tt >}' to match when strictly below or above. -(The numeric limit is relaxed slightly for those: {\tt >-1\%} -and {\tt <101\%} are allowed.) +Use prefix `\texttt{<}' or `\texttt{>}' to match when strictly below or above. +(The numeric limit is relaxed slightly for those: \texttt{>-1\%} +and \texttt{<101\%} are allowed.) Only four fields support percentage rules. -Percentages for ``{\it hitpoints\/}'' and ``{\it power\/}'' are +Percentages for ``\textit{hitpoints}'' and ``\textit{power}'' are straightforward; they're based on the corresponding maximum field. -Percentage highlight rules are also allowed for ``{\it experience level\/}'' -and ``{\it experience points\/}'' (valid when the -{\it showexp\/} +Percentage highlight rules are also allowed for ``\textit{experience level}'' +and ``\textit{experience points}'' (valid when the +\textit{showexp} option is enabled). For those, the percentage is based on the progress from the start of the current experience level to the start of the next level. @@ -4846,34 +6446,41 @@ \subsection*{Configuring Status Hilites} having 30 points is 50\% and 35 points is 75\%. 100\% is unattainable for experience because you'll gain a level and the calculations will be reset for that new level, but a rule for -{\tt =100\%} is allowed and matches the special case of being +\texttt{=100\%} is allowed and matches the special case of being exactly 1 experience point short of the next level. % (If you manage to reach level 30, there is no next level and the % percentage will remain at 0\% no matter have many additional experience % points you earn.) %.lp "*" -\item[{\tt absolute}] value sets the attribute when the field value +\item[absolute] value sets the attribute when the field value matches that number. -The number must be 0 or higher, except for ``{\it armor-class\/} which -allows negative values, and may optionally be preceded by `{\tt =}'. -If the number is preceded by `{\tt <=}' or `{\tt >=}' instead, +The number must be 0 or higher, except for ``\textit{armor-class} which +allows negative values, and may optionally be preceded by `\texttt{=}'. +If the number is preceded by `\texttt{<=}' or `\texttt{>=}' instead, it also matches when value is below or above. -If the prefix is `{\tt <}' or `{\tt >}', only match when strictly +If the prefix is `\texttt{<}' or `\texttt{>}', only match when strictly above or below. %.lp "*" -\item[{\tt text}] match sets the attribute when the field value matches the text. -Text matches can only be used for ``{\it alignment\/}'', -``{\it carrying-capacity\/}'', ``{\it hunger\/}'', ``{\it dungeon-level\/}'', -and ``{\it title\/}''. +\item[criticalhp] only applies to the hitpoints field and only +when current hit points are below a threshold (which varies by maximum +hit points and experience level). +When the threshold is met, a criticalhp rule takes precedence over all +other hitpoints rules. +%.lp "*" +\item[text] match sets the attribute when the field value +matches the text. +Text matches can only be used for ``\textit{alignment}'', +``\textit{carrying-capacity}'', ``\textit{hunger}'', ``\textit{dungeon-level}'', +and ``\textit{title}''. For title, only the role's rank title is tested; the character's name is ignored. %.ei -\elist +\end{description} The in-game options menu can help you determine the correct syntax for a configuration file. -The whole feature can be disable by setting option {\it statushilites} to 0. +The whole feature can be disable by setting option \textit{statushilites} to 0. Example hilites: \begin{verbatim} @@ -4891,226 +6498,231 @@ \subsection*{Configuring Status Hilites} %.lp %.hn 2 -\subsection*{Modifying {\it NetHack\/} Symbols} +\subsection*{Modifying \textit{NetHack} Symbols} %.pg -{\it NetHack\/} can load entire symbol sets from the symbol file. +\textit{NetHack} can load entire symbol sets from the symbol file. %.pg The options that are used to select a particular symbol set from the symbol file are: -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{symset}] +\item[symset] Set the name of the symbol set that you want to load. -{\it symbols\/}. +\textit{symbols}. %.lp -\item[\ib{roguesymset}] +\item[roguesymset] Set the name of the symbol set that you want to load for display on the rogue level. -\elist - -You can also override one or more symbols using the {\it SYMBOLS\/} and -{\it ROGUESYMBOLS\/} configuration file options. -Symbols are specified as {\it name:value\/} pairs. -Note that {\it NetHack\/} escape-processes -the {\it value\/} string in conventional C fashion. -This means that `\verb+\+' is a prefix to take the following character +\end{description} + +You can also override one or more symbols using the \textit{SYMBOLS} and +\textit{ROGUESYMBOLS} configuration file options. +Symbols are specified as \textit{name:value} pairs. +Note that \textit{NetHack} escape-processes +the \textit{value} string in conventional C fashion. +This means that `\texttt{\textbackslash}' is a prefix to take the following character literally. -Thus `\verb+\+' needs to be represented as `\verb+\\+'. +Thus `\texttt{\textbackslash}' needs to be represented as `\texttt{\textbackslash\textbackslash}'. The special prefix -`\verb+\m+' switches on the meta bit in the symbol value, and the -`{\tt \^{}}' prefix causes the following character to be treated as a control +`\texttt{\textbackslash m}' switches on the meta bit in the symbol value, and the +`\texttt{\textasciicircum}' prefix causes the following character to be treated as a control character. -{ \small \begin{longtable}{lll} \caption[]{NetHack Symbols}\\ Default & Symbol Name & Description\\ \hline \hline \endhead -\verb@ @ & S\verb+_+air & (air)\\ -\_ & S\verb+_+altar & (altar)\\ -\verb@"@ & S\verb+_+amulet & (amulet)\\ -\verb@A@ & S\verb+_+angel & (angelic being)\\ -\verb@a@ & S\verb+_+ant & (ant or other insect)\\ -\verb@^@ & S\verb+_+anti\verb+_+magic\verb+_+trap & (anti-magic field)\\ -\verb@[@ & S\verb+_+armor & (suit or piece of armor)\\ -\verb@[@ & S\verb+_+armour & (suit or piece of armor)\\ -\verb@^@ & S\verb+_+arrow\verb+_+trap & (arrow trap)\\ -\verb@0@ & S\verb+_+ball & (iron ball)\\ -\# & S\verb+_+bars & (iron bars)\\ -\verb@B@ & S\verb+_+bat & (bat or bird)\\ -\verb@^@ & S\verb+_+bear\verb+_+trap & (bear trap)\\ -\verb@-@ & S\verb+_+blcorn & (bottom left corner)\\ -\verb@b@ & S\verb+_+blob & (blob)\\ -\verb@+@ & S\verb+_+book & (spellbook)\\ -\verb@)@ & S\verb+_+boomleft & (boomerang open left)\\ -\verb@(@ & S\verb+_+boomright & (boomerang open right)\\ -\verb@`@ & S\verb+_+boulder & (boulder)\\ -\verb@-@ & S\verb+_+brcorn & (bottom right corner)\\ -\verb@C@ & S\verb+_+centaur & (centaur)\\ -\verb@_@ & S\verb+_+chain & (iron chain)\\ -\# & S\verb+_+cloud & (cloud)\\ -\verb@c@ & S\verb+_+cockatrice & (cockatrice)\\ -\$ & S\verb+_+coin & (pile of coins)\\ -\# & S\verb+_+corr & (corridor)\\ -\verb@-@ & S\verb+_+crwall & (wall)\\ -\verb@-@ & S\verb+_+darkroom & (dark room)\\ -\verb@^@ & S\verb+_+dart\verb+_+trap & (dart trap)\\ -\verb@&@ & S\verb+_+demon & (major demon)\\ -\verb@*@ & S\verb+_+digbeam & (dig beam)\\ -\verb@>@ & S\verb+_+dnladder & (ladder down)\\ -\verb@>@ & S\verb+_+dnstair & (staircase down)\\ -\verb@d@ & S\verb+_+dog & (dog or other canine)\\ -\verb@D@ & S\verb+_+dragon & (dragon)\\ -\verb@;@ & S\verb+_+eel & (sea monster)\\ -\verb@E@ & S\verb+_+elemental & (elemental)\\ -\verb@/@ & S\verb+_+explode1 & (explosion top left)\\ -\verb@-@ & S\verb+_+explode2 & (explosion top center)\\ -\verb@\@ & S\verb+_+explode3 & (explosion top right)\\ -\verb@|@ & S\verb+_+explode4 & (explosion middle left)\\ -\verb@ @ & S\verb+_+explode5 & (explosion middle center)\\ -\verb@|@ & S\verb+_+explode6 & (explosion middle right)\\ -\verb@\@ & S\verb+_+explode7 & (explosion bottom left)\\ -\verb@-@ & S\verb+_+explode8 & (explosion bottom center)\\ -\verb@/@ & S\verb+_+explode9 & (explosion bottom right)\\ -\verb@e@ & S\verb+_+eye & (eye or sphere)\\ -\verb@^@ & S\verb+_+falling\verb+_+rock\verb+_+trap & (falling rock trap)\\ -\verb@f@ & S\verb+_+feline & (cat or other feline)\\ -\verb@^@ & S\verb+_+fire\verb+_+trap & (fire trap)\\ -\verb@!@ & S\verb+_+flashbeam & (flash beam)\\ -\% & S\verb+_+food & (piece of food)\\ -\{ & S\verb+_+fountain & (fountain)\\ -\verb@F@ & S\verb+_+fungus & (fungus or mold)\\ -\verb@*@ & S\verb+_+gem & (gem or rock)\\ -\verb@ @ & S\verb+_+ghost & (ghost)\\ -\verb@H@ & S\verb+_+giant & (giant humanoid)\\ -\verb@G@ & S\verb+_+gnome & (gnome)\\ -\verb@'@ & S\verb+_+golem & (golem)\\ -\verb@|@ & S\verb+_+grave & (grave)\\ -\verb@g@ & S\verb+_+gremlin & (gremlin)\\ -\verb@-@ & S\verb+_+hbeam & (wall)\\ -\# & S\verb+_+hcdbridge & (horizontal raised drawbridge)\\ -\verb@+@ & S\verb+_+hcdoor & (closed door)\\ -\verb@.@ & S\verb+_+hodbridge & (horizontal lowered drawbridge)\\ -\verb@|@ & S\verb+_+hodoor & (open door)\\ -\verb\^\ & S\verb+_+hole & (hole)\\ -\verb~@~ & S\verb+_+human & (human or elf)\\ -\verb@h@ & S\verb+_+humanoid & (humanoid)\\ -\verb@-@ & S\verb+_+hwall & (horizontal wall)\\ -\verb@.@ & S\verb+_+ice & (ice)\\ -\verb@i@ & S\verb+_+imp & (imp or minor demon)\\ -\verb@I@ & S\verb+_+invisible & (invisible monster)\\ -\verb@J@ & S\verb+_+jabberwock & (jabberwock)\\ -\verb@j@ & S\verb+_+jelly & (jelly)\\ -\verb@k@ & S\verb+_+kobold & (kobold)\\ -\verb@K@ & S\verb+_+kop & (Keystone Kop)\\ -\verb@^@ & S\verb+_+land\verb+_+mine & (land mine)\\ -\verb@}@ & S\verb+_+lava & (molten lava)\\ -\verb@l@ & S\verb+_+leprechaun & (leprechaun)\\ -\verb@^@ & S\verb+_+level\verb+_+teleporter & (level teleporter)\\ -\verb@L@ & S\verb+_+lich & (lich)\\ -\verb@y@ & S\verb+_+light & (light)\\ -\# & S\verb+_+litcorr & (lit corridor)\\ -\verb@:@ & S\verb+_+lizard & (lizard)\\ -\verb@\@ & S\verb+_+lslant & (wall)\\ -\verb@^@ & S\verb+_+magic\verb+_+portal & (magic portal)\\ -\verb@^@ & S\verb+_+magic\verb+_+trap & (magic trap)\\ -\verb@m@ & S\verb+_+mimic & (mimic)\\ -\verb@]@ & S\verb+_+mimic\verb+_+def & (mimic)\\ -\verb@M@ & S\verb+_+mummy & (mummy)\\ -\verb@N@ & S\verb+_+naga & (naga)\\ -\verb@.@ & S\verb+_+ndoor & (doorway)\\ -\verb@n@ & S\verb+_+nymph & (nymph)\\ -\verb@O@ & S\verb+_+ogre & (ogre)\\ -\verb@o@ & S\verb+_+orc & (orc)\\ -\verb@p@ & S\verb+_+piercer & (piercer)\\ -\verb@^@ & S\verb+_+pit & (pit)\\ -\# & S\verb+_+poisoncloud & (poison cloud)\\ -\verb@^@ & S\verb+_+polymorph\verb+_+trap & (polymorph trap)\\ -\verb@}@ & S\verb+_+pool & (water)\\ -\verb@!@ & S\verb+_+potion & (potion)\\ -\verb@P@ & S\verb+_+pudding & (pudding or ooze)\\ -\verb@q@ & S\verb+_+quadruped & (quadruped)\\ -\verb@Q@ & S\verb+_+quantmech & (quantum mechanic)\\ -\verb@=@ & S\verb+_+ring & (ring)\\ -\verb@`@ & S\verb+_+rock & (boulder or statue)\\ -\verb@r@ & S\verb+_+rodent & (rodent)\\ -\verb@^@ & S\verb+_+rolling\verb+_+boulder\verb+_+trap & (rolling boulder trap)\\ -\verb@.@ & S\verb+_+room & (floor of a room)\\ -\verb@/@ & S\verb+_+rslant & (wall)\\ -\verb@^@ & S\verb+_+rust\verb+_+trap & (rust trap)\\ -\verb@R@ & S\verb+_+rustmonst & (rust monster or disenchanter)\\ -\verb@?@ & S\verb+_+scroll & (scroll)\\ -\# & S\verb+_+sink & (sink)\\ -\verb@^@ & S\verb+_+sleeping\verb+_+gas\verb+_+trap & (sleeping gas trap)\\ -\verb@S@ & S\verb+_+snake & (snake)\\ -\verb@s@ & S\verb+_+spider & (arachnid or centipede)\\ -\verb@^@ & S\verb+_+spiked\verb+_+pit & (spiked pit)\\ -\verb@^@ & S\verb+_+squeaky\verb+_+board & (squeaky board)\\ -\verb@0@ & S\verb+_+ss1 & (magic shield 1 of 4)\\ -\# & S\verb+_+ss2 & (magic shield 2 of 4)\\ -\verb+@+ & S\verb+_+ss3 & (magic shield 3 of 4)\\ -\verb@*@ & S\verb+_+ss4 & (magic shield 4 of 4)\\ -\verb@^@ & S\verb+_+statue\verb+_+trap & (statue trap)\\ -\verb@ @ & S\verb+_+stone & (solid rock or unexplored terrain\\ - & & \,or dark part of a room)\\ -\verb@]@ & S\verb+_+strange\verb+_+obj & (strange object)\\ -\verb@-@ & S\verb+_+sw\verb+_+bc & (swallow bottom center)\\ -\verb@\@ & S\verb+_+sw\verb+_+bl & (swallow bottom left)\\ -\verb@/@ & S\verb+_+sw\verb+_+br & (swallow bottom right )\\ -\verb@|@ & S\verb+_+sw\verb+_+ml & (swallow middle left)\\ -\verb@|@ & S\verb+_+sw\verb+_+mr & (swallow middle right)\\ -\verb@-@ & S\verb+_+sw\verb+_+tc & (swallow top center)\\ -\verb@/@ & S\verb+_+sw\verb+_+tl & (swallow top left)\\ -\verb@\@ & S\verb+_+sw\verb+_+tr & (swallow top right)\\ -\verb@-@ & S\verb+_+tdwall & (wall)\\ -\verb@^@ & S\verb+_+teleportation\verb+_+trap & (teleportation trap)\\ -\verb@\@ & S\verb+_+throne & (opulent throne)\\ -\verb@-@ & S\verb+_+tlcorn & (top left corner)\\ -\verb@|@ & S\verb+_+tlwall & (wall)\\ -\verb@(@ & S\verb+_+tool & (useful item (pick-axe, key, lamp...))\\ -\verb@^@ & S\verb+_+trap\verb+_+door & (trap door)\\ -\verb@t@ & S\verb+_+trapper & (trapper or lurker above)\\ -\verb@-@ & S\verb+_+trcorn & (top right corner)\\ -\# & S\verb+_+tree & (tree)\\ -\verb@T@ & S\verb+_+troll & (troll)\\ -\verb@|@ & S\verb+_+trwall & (wall)\\ -\verb@-@ & S\verb+_+tuwall & (wall)\\ -\verb@U@ & S\verb+_+umber & (umber hulk)\\ -\verb@u@ & S\verb+_+unicorn & (unicorn or horse)\\ -\verb@<@ & S\verb+_+upladder & (ladder up)\\ -\verb@<@ & S\verb+_+upstair & (staircase up)\\ -\verb@V@ & S\verb+_+vampire & (vampire)\\ -\verb@|@ & S\verb+_+vbeam & (wall)\\ -\# & S\verb+_+vcdbridge & (vertical raised drawbridge)\\ -\verb@+@ & S\verb+_+vcdoor & (closed door)\\ -\verb@.@ & S\verb+_+venom & (splash of venom)\\ -\verb@^@ & S\verb+_+vibrating\verb+_+square & (vibrating square)\\ -\verb@.@ & S\verb+_+vodbridge & (vertical lowered drawbridge)\\ -\verb@-@ & S\verb+_+vodoor & (open door)\\ -\verb@v@ & S\verb+_+vortex & (vortex)\\ -\verb@|@ & S\verb+_+vwall & (vertical wall)\\ -\verb@/@ & S\verb+_+wand & (wand)\\ -\verb@}@ & S\verb+_+water & (water)\\ -\verb@)@ & S\verb+_+weapon & (weapon)\\ -\verb@"@ & S\verb+_+web & (web)\\ -\verb@w@ & S\verb+_+worm & (worm)\\ -\verb@~@ & S\verb+_+worm\verb+_+tail & (long worm tail)\\ -\verb@W@ & S\verb+_+wraith & (wraith)\\ -\verb@x@ & S\verb+_+xan & (xan or other extraordinary insect)\\ -\verb@X@ & S\verb+_+xorn & (xorn)\\ -\verb@Y@ & S\verb+_+yeti & (apelike creature)\\ -\verb@Z@ & S\verb+_+zombie & (zombie)\\ -\verb@z@ & S\verb+_+zruty & (zruty)\\ -\verb@ @ & S\verb+_+pet\verb+_+override & (any pet if ACCESSIBILITY=1 is set)\\ -\verb@ @ & S\verb+_+hero\verb+_+override & (hero if ACCESSIBILITY=1 is set) -\end{longtable}% -} +\space @ & S\textunderscore air & (air)\\ +\textunderscore & S\textunderscore altar & (altar)\\ +" & S\textunderscore amulet & (amulet)\\ +A & S\textunderscore angel & (angelic being)\\ +a & S\textunderscore ant & (ant or other insect)\\ +\textasciicircum & S\textunderscore anti\textunderscore magic\textunderscore trap & (anti-magic field)\\ +{[} & S\textunderscore armor & (suit or piece of armor)\\ +{[} & S\textunderscore armour & (suit or piece of armor)\\ +\textasciicircum & S\textunderscore arrow\textunderscore trap & (arrow trap)\\ +0 & S\textunderscore ball & (iron ball)\\ +\# & S\textunderscore bars & (iron bars)\\ +B & S\textunderscore bat & (bat or bird)\\ +\textasciicircum & S\textunderscore bear\textunderscore trap & (bear trap)\\ +- & S\textunderscore blcorn & (bottom left corner)\\ +b & S\textunderscore blob & (blob)\\ ++ & S\textunderscore book & (spellbook)\\ +) & S\textunderscore boomleft & (boomerang open left)\\ +( & S\textunderscore boomright & (boomerang open right)\\ +\textasciigrave & S\textunderscore boulder & (boulder)\\ +- & S\textunderscore brcorn & (bottom right corner)\\ +> & S\textunderscore brdnladder & (branch ladder down)\\ +> & S\textunderscore brdnstair & (branch staircase down)\\ +< & S\textunderscore brupladder & (branch ladder up)\\ +< & S\textunderscore brupstair & (branch staircase up)\\ +C & S\textunderscore centaur & (centaur)\\ +\textunderscore & S\textunderscore chain & (iron chain)\\ +\# & S\textunderscore cloud & (cloud)\\ +c & S\textunderscore cockatrice & (cockatrice)\\ +\textdollar & S\textunderscore coin & (pile of coins)\\ +\# & S\textunderscore corr & (corridor)\\ +- & S\textunderscore crwall & (wall)\\ +- & S\textunderscore darkroom & (dark room)\\ +\textasciicircum & S\textunderscore dart\textunderscore trap & (dart trap)\\ +\& & S\textunderscore demon & (major demon)\\ +* & S\textunderscore digbeam & (dig beam)\\ +> & S\textunderscore dnladder & (ladder down)\\ +> & S\textunderscore dnstair & (staircase down)\\ +d & S\textunderscore dog & (dog or other canine)\\ +D & S\textunderscore dragon & (dragon)\\ +; & S\textunderscore eel & (sea monster)\\ +E & S\textunderscore elemental & (elemental)\\ +\# & S\textunderscore engrcorr & (engraving in a corridor)\\ +\textasciigrave & S\textunderscore engroom & (engraving in a room)\\ +/ & S\textunderscore expl\textunderscore tl & (explosion top left)\\ +- & S\textunderscore expl\textunderscore tc & (explosion top center)\\ +\textbackslash & S\textunderscore expl\textunderscore tr & (explosion top right)\\ +| & S\textunderscore expl\textunderscore ml & (explosion middle left)\\ +~ & S\textunderscore expl\textunderscore mc & (explosion middle center)\\ +| & S\textunderscore expl\textunderscore mr & (explosion middle right)\\ +\textbackslash & S\textunderscore expl\textunderscore bl & (explosion bottom left)\\ +- & S\textunderscore expl\textunderscore bc & (explosion bottom center)\\ +/ & S\textunderscore expl\textunderscore br & (explosion bottom right)\\ +e & S\textunderscore eye & (eye or sphere)\\ +\textasciicircum & S\textunderscore falling\textunderscore rock\textunderscore trap & (falling rock trap)\\ +f & S\textunderscore feline & (cat or other feline)\\ +\textasciicircum & S\textunderscore fire\textunderscore trap & (fire trap)\\ +! & S\textunderscore flashbeam & (flash beam)\\ +\% & S\textunderscore food & (piece of food)\\ +\textbraceleft & S\textunderscore fountain & (fountain)\\ +F & S\textunderscore fungus & (fungus or mold)\\ +* & S\textunderscore gem & (gem or rock)\\ +~ & S\textunderscore ghost & (ghost)\\ +H & S\textunderscore giant & (giant humanoid)\\ +G & S\textunderscore gnome & (gnome)\\ +\textquotesingle & S\textunderscore golem & (golem)\\ +| & S\textunderscore grave & (grave)\\ +g & S\textunderscore gremlin & (gremlin)\\ +- & S\textunderscore hbeam & (wall)\\ +\# & S\textunderscore hcdbridge & (horizontal raised drawbridge)\\ ++ & S\textunderscore hcdoor & (closed door)\\ +. & S\textunderscore hodbridge & (horizontal lowered drawbridge)\\ +| & S\textunderscore hodoor & (open door)\\ +\textasciicircum & S\textunderscore hole & (hole)\\ +@ & S\textunderscore human & (human or elf)\\ +h & S\textunderscore humanoid & (humanoid)\\ +- & S\textunderscore hwall & (horizontal wall)\\ +. & S\textunderscore ice & (ice)\\ +i & S\textunderscore imp & (imp or minor demon)\\ +I & S\textunderscore invisible & (invisible monster)\\ +J & S\textunderscore jabberwock & (jabberwock)\\ +j & S\textunderscore jelly & (jelly)\\ +k & S\textunderscore kobold & (kobold)\\ +K & S\textunderscore kop & (Keystone Kop)\\ +\textasciicircum & S\textunderscore land\textunderscore mine & (land mine)\\ +\textbraceright & S\textunderscore lava & (molten lava)\\ +\textbraceright & S\textunderscore lavawall & (wall of lava)\\ +1 & S\textunderscore leprechaun & (leprechaun)\\ +\textasciicircum & S\textunderscore level\textunderscore teleporter & (level teleporter)\\ +L & S\textunderscore lich & (lich)\\ +y & S\textunderscore light & (light)\\ +\# & S\textunderscore litcorr & (lit corridor)\\ +: & S\textunderscore lizard & (lizard)\\ +\textbackslash & S\textunderscore lslant & (wall)\\ +\textasciicircum & S\textunderscore magic\textunderscore portal & (magic portal)\\ +\textasciicircum & S\textunderscore magic\textunderscore trap & (magic trap)\\ +m & S\textunderscore mimic & (mimic)\\ +{]} & S\textunderscore mimic\textunderscore def & (mimic)\\ +M & S\textunderscore mummy & (mummy)\\ +N & S\textunderscore naga & (naga)\\ +. & S\textunderscore ndoor & (doorway)\\ +n & S\textunderscore nymph & (nymph)\\ +O & S\textunderscore ogre & (ogre)\\ +o & S\textunderscore orc & (orc)\\ +p & S\textunderscore piercer & (piercer)\\ +\textasciicircum & S\textunderscore pit & (pit)\\ +\# & S\textunderscore poisoncloud & (poison cloud)\\ +\textasciicircum & S\textunderscore polymorph\textunderscore trap & (polymorph trap)\\ +\textbraceright & S\textunderscore pool & (water)\\ +! & S\textunderscore potion & (potion)\\ +P & S\textunderscore pudding & (pudding or ooze)\\ +q & S\textunderscore quadruped & (quadruped)\\ +Q & S\textunderscore quantmech & (quantum mechanic)\\ += & S\textunderscore ring & (ring)\\ +\textasciigrave & S\textunderscore rock & (boulder or statue)\\ +r & S\textunderscore rodent & (rodent)\\ +\textasciicircum & S\textunderscore rolling\textunderscore boulder\textunderscore trap & (rolling boulder trap)\\ +. & S\textunderscore room & (floor of a room)\\ +/ & S\textunderscore rslant & (wall)\\ +\textasciicircum & S\textunderscore rust\textunderscore trap & (rust trap)\\ +R & S\textunderscore rustmonst & (rust monster or disenchanter)\\ +? & S\textunderscore scroll & (scroll)\\ +\# & S\textunderscore sink & (sink)\\ +\textasciicircum & S\textunderscore sleeping\textunderscore gas\textunderscore trap & (sleeping gas trap)\\ +S & S\textunderscore snake & (snake)\\ +s & S\textunderscore spider & (arachnid or centipede)\\ +\textasciicircum & S\textunderscore spiked\textunderscore pit & (spiked pit)\\ +\textasciicircum & S\textunderscore squeaky\textunderscore board & (squeaky board)\\ +0 & S\textunderscore ss1 & (magic shield 1 of 4)\\ +\# & S\textunderscore ss2 & (magic shield 2 of 4)\\ +@ & S\textunderscore ss3 & (magic shield 3 of 4)\\ +* & S\textunderscore ss4 & (magic shield 4 of 4)\\ +\textasciicircum & S\textunderscore statue\textunderscore trap & (statue trap)\\ +~ & S\textunderscore stone & (solid rock)\\ +{]} & S\textunderscore strange\textunderscore obj & (strange object)\\ +- & S\textunderscore sw\textunderscore bc & (swallow bottom center)\\ +\textbackslash & S\textunderscore sw\textunderscore bl & (swallow bottom left)\\ +/ & S\textunderscore sw\textunderscore br & (swallow bottom right )\\ +| & S\textunderscore sw\textunderscore ml & (swallow middle left)\\ +| & S\textunderscore sw\textunderscore mr & (swallow middle right)\\ +- & S\textunderscore sw\textunderscore tc & (swallow top center)\\ +/ & S\textunderscore sw\textunderscore tl & (swallow top left)\\ +\textbackslash & S\textunderscore sw\textunderscore tr & (swallow top right)\\ +- & S\textunderscore tdwall & (wall)\\ +\textasciicircum & S\textunderscore teleportation\textunderscore trap & (teleportation trap)\\ +\textbackslash & S\textunderscore throne & (opulent throne)\\ +- & S\textunderscore tlcorn & (top left corner)\\ +| & S\textunderscore tlwall & (wall)\\ +( & S\textunderscore tool & (useful item (pick-axe, key, lamp...))\\ +\textasciicircum & S\textunderscore trap\textunderscore door & (trap door)\\ +t & S\textunderscore trapper & (trapper or lurker above)\\ +- & S\textunderscore trcorn & (top right corner)\\ +\# & S\textunderscore tree & (tree)\\ +T & S\textunderscore troll & (troll)\\ +| & S\textunderscore trwall & (wall)\\ +- & S\textunderscore tuwall & (wall)\\ +U & S\textunderscore umber & (umber hulk)\\ +~ & S\textunderscore unexplored & (unexplored terrain)\\ +u & S\textunderscore unicorn & (unicorn or horse)\\ +< & S\textunderscore upladder & (ladder up)\\ +< & S\textunderscore upstair & (staircase up)\\ +V & S\textunderscore vampire & (vampire)\\ +| & S\textunderscore vbeam & (wall)\\ +\# & S\textunderscore vcdbridge & (vertical raised drawbridge)\\ ++ & S\textunderscore vcdoor & (closed door)\\ +. & S\textunderscore venom & (splash of venom)\\ +\textasciicircum & S\textunderscore vibrating\textunderscore square & (vibrating square)\\ +. & S\textunderscore vodbridge & (vertical lowered drawbridge)\\ +- & S\textunderscore vodoor & (open door)\\ +v & S\textunderscore vortex & (vortex)\\ +| & S\textunderscore vwall & (vertical wall)\\ +/ & S\textunderscore wand & (wand)\\ +\textbraceright & S\textunderscore water & (water)\\ +\textbraceright & S\textunderscore weapon & (weapon)\\ +" & S\textunderscore web & (web)\\ +w & S\textunderscore worm & (worm)\\ +\textasciitilde & S\textunderscore worm\textunderscore tail & (long worm tail)\\ +W & S\textunderscore wraith & (wraith)\\ +x & S\textunderscore xan & (xan or other extraordinary insect)\\ +X & S\textunderscore xorn & (xorn)\\ +Y & S\textunderscore yeti & (apelike creature)\\ +Z & S\textunderscore zombie & (zombie)\\ +z & S\textunderscore zruty & (zruty)\\ +~ & S\textunderscore pet\textunderscore override & (any pet if ACCESSIBILITY=1 is set)\\ +~ @ & S\textunderscore hero\textunderscore override & (hero if ACCESSIBILITY=1 is set) +\end{longtable} \hyphenation{sysconf} %no syllable breaks => don't hyphenate file name %.lp @@ -5118,25 +6730,65 @@ \subsection*{Modifying {\it NetHack\/} Symbols} %.lp "*" Several symbols in this table appear to be blank. -They are the space character, except for S\verb+_+pet\verb+_+override -and S\verb+_+hero\verb+_+override which don't have any default value +They are the space character, except for S\textunderscore pet\textunderscore override +and S\textunderscore hero\textunderscore override which don't have any default value and can only be used if enabled in the ``sysconf'' file. %.lp "*" -S\verb+_+rock is misleadingly named; rocks and stones use S\verb+_+gem. +S\textunderscore rock is misleadingly named; rocks and stones use S\textunderscore gem. Statues and boulders are the rock being referred to, but since version 3.6.0, statues are displayed as the monster they depict. -So S\verb+_+rock is only used for boulders and not used at all if -overridden by the more specific S\verb+_+boulder. +So S\textunderscore rock is only used for boulders and not used at all if +overridden by the more specific S\textunderscore boulder. + +%.lp +%.hn 2 +\subsection*{Customizing Map Glyph Representations Using Unicode} + +%.pg +If your platform or terminal supports the display of UTF-8 character +sequences, you can customize your game display by assigning Unicode +codepoint values and red-green-blue colors to glyph +representations. The customizations can be specified for use with a symset that +has a UTF8 handler within the symbols file such as the enhanced1 set, or +individually within your own nethack.rc file. + +The format for defining a glyph representation is:\\ +\begin{verbatim} +OPTIONS=glyph:glyphid/U+nnnn/R-G-B +\end{verbatim} + +The window port that is active needs to provide support for displaying UTF-8 +character sequences and explicit 24-bit red-green-blue colors in order for the glyph +representation to be visible as specified. + +For example, the following line in your configuration file will cause +the glyph representation for glyphid G\textunderscore pool to use Unicode codepoint +U+224B and the color represented by R-G-B value 0-0-160:\\ +\begin{verbatim} +OPTIONS=glyph:G_pool/U+224B/0-0-160 +\end{verbatim} + +The list of acceptable glyphid's can be produced by +\begin{verbatim} + nethack --glyphids +\end{verbatim} +Individual NetHack glyphs can be specified using the G\textunderscore prefix, +or you can use an S\textunderscore symbol for a glyphid and store the custom +representation for all NetHack glyphs that would map to that +particular symbol. + +You will need to select a symset with a UTF8 handler to enable the +display of the customizations, such as the Enhanced symset. %.pg %.hn 2 -\subsection*{Configuring {\it NetHack\/} for Play by the Blind} +\subsection*{Configuring \textit{NetHack} for Play by the Blind} %.pg -{\it NetHack\/} can be set up to use only standard ASCII characters for making -maps of the dungeons. This makes the MS-DOS versions of {\it NetHack\/} -completely +\textit{NetHack} can be set up to use only standard ASCII characters for making +maps of the dungeons. This makes even the MS-DOS versions of \textit{NetHack} +(which use special line-drawing characters by default) completely accessible to the blind who use speech and/or Braille access technologies. Players will require a good working knowledge of their screen-reader's review features, and will have to know how to navigate horizontally and @@ -5151,190 +6803,225 @@ \subsection*{Configuring {\it NetHack\/} for Play by the Blind} These co-ordinates are often useful in giving players a better sense of the overall location of items on the screen. %.pg -{\it NetHack\/} can also be compiled with support for sending the game messages -to an external program, such as a text-to-speech synthesizer. If the -``{\tt \#version}'' extended command shows ``external program as a -message handler'', your {\it NetHack\/} -has been compiled with the capability. When compiling {\it NetHack\/} +\textit{NetHack} can also be compiled with support for sending the game +messages to an external program, such as a text-to-speech synthesizer. If +the ``\texttt{\#version}'' extended command shows ``external program as a +message handler'', your \textit{NetHack} +has been compiled with the capability. When compiling \textit{NetHack} from source -on Linux and other POSIX systems, define {\it MSGHANDLER\/} to enable it. +on Linux and other POSIX systems, define \texttt{MSGHANDLER} to enable it. To use -the capability, set the environment variable {\it NETHACK\_MSGHANDLER\/} to an -executable, which will be executed with the game message as the program's +the capability, set the environment variable \texttt{NETHACK\textunderscore MSGHANDLER} to +an executable, which will be executed with the game message as the program's only parameter. %.pg -While it is not difficult for experienced users to edit the {\it defaults.nh\/} -file to accomplish this, novices may find this task somewhat daunting. -Included within the symbol file of all official distributions of {\it NetHack\/} -is a symset called {\it NHAccess\/}. Selecting that symset in your -configuration file will cause the game to run in a manner accessible -to the blind. After you have gained some experience with the game -and with editing files, you may want to alter settings via {\it SYMBOLS=\/} -and {\it ROGUESYMBOLS=\/} -in your configuration file to better suit your preferences. -See the previous section for the special symbols S\verb+_+pet\verb+_+override -to force a consistent symbol for all pets and S\verb+_+hero\verb+_+override -to force a unique symbol for the player character if {\it accessibility\/} -is enabled in the {\it sysconf\/} file. -%.pg The most crucial settings to make the game more accessible are: %.pg -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{symset:NHAccess}] +\item[symset:plain] Load a symbol set appropriate for use by blind players. %.lp -\item[\ib{roguesymset:NHAccess}] -Load a symbol set for the rogue level that is appropriate for -use by blind players. -%.lp -\item[\ib{menustyle:traditional}] +\item[menustyle:traditional] This will assist in the interface to speech synthesizers. %.lp -\item[\ib{nomenu\verb+_+overlay}] +\item[nomenu\textunderscore overlay] Show menus on a cleared screen and aligned to the left edge. %.lp -\item[\ib{number\verb+_+pad}] +\item[number\textunderscore pad] A lot of speech access programs use the number-pad to review the screen. -If this is the case, disable the number\verb+_+pad option and use the +If this is the case, disable the number\textunderscore pad option and use the traditional Rogue-like commands. %.lp -\item[\ib{autodescribe}] +\item[paranoid\textunderscore confirmation:swim] +Prevent walking into water or lava. +%.lp +\item[accessiblemsg] +Adds direction or location information to messages. +%.lp +\item[spot\textunderscore monsters] +Shows a message when hero notices a monster; combine with accessiblemsg. +%.lp +\item[mon\textunderscore movement] +Shows a message when hero notices a monster movement; +combine with spot\textunderscore monsters and accessiblemsg. +%.lp +\item[autodescribe] Automatically describe the terrain under the cursor when targeting. %.lp -\item[\ib{mention\verb+_+walls}] +\item[mention\textunderscore map] +Give feedback messages when interesting map locations change. +%.lp +\item[mention\textunderscore walls] Give feedback messages when walking towards a wall or when travel command was interrupted. %.lp -\item[\ib{whatis\verb+_+coord:compass}] +\item[whatis\textunderscore coord:compass] When targeting with cursor, describe the cursor position with coordinates relative to your character. %.lp -\item[\ib{whatis\verb+_+filter:area}] +\item[whatis\textunderscore filter:area] When targeting with cursor, filter possible locations so only those in the same area (eg. same room, or same corridor) are considered. %.lp -\item[\ib{whatis\verb+_+moveskip}] +\item[whatis\textunderscore moveskip] When targeting with cursor and using fast-move, skip the same glyphs instead of moving 8 units at a time. %.lp -\item[\ib{nostatus\verb+_+updates}] +\item[nostatus\textunderscore updates] Prevent updates to the status lines at the bottom of the screen, if your screen-reader reads those lines. The same information can be -seen via the {\tt \#attributes} command. -\elist +seen via the \texttt{\#attributes} command. +%.lp +\item[showdamage] +Give a message of damage taken and how many hit points are left. +\end{description} %.hn2 \subsection*{Global Configuration for System Administrators} %.pg -If {\it NetHack\/} is compiled with the SYSCF option, a system administrator +If \textit{NetHack} is compiled with the SYSCF option, a system administrator should set up a global configuration; this is a file in the same format as the traditional per-user configuration file (see above). This file should be named sysconf and placed in the same directory as -the other {\it NetHack\/} support files. +the other \textit{NetHack} support files. The options recognized in this file are listed below. Any option not set uses a compiled-in default (which may not be appropriate for your system). %.pg -\blist{} +\begin{description}[font=\mdseries\itshape] %.lp -\item[\ib{WIZARDS}] +\item[WIZARDS] A space-separated list of user name who are allowed to play in debug mode (commonly referred to as wizard mode). A value of a single asterisk (*) allows anyone to start a game in debug mode. %.lp -\item[\ib{SHELLERS}] -A list of users who are allowed to use the shell escape command (`{\tt !}'). +\item[SHELLERS] +A list of users who are allowed to use the shell escape command (`\texttt{!}'). The syntax is the same as WIZARDS. %.lp -\item[\ib{EXPLORERS}] +\item[EXPLORERS] A list of users who are allowed to use the explore mode. The syntax is the same as WIZARDS. %.lp -\item[\ib{MAXPLAYERS}] +\item[MSGHANDLER] +A path and filename of executable. Whenever a message-window +message is shown, \textit{NetHack} runs this program. The program will get +the message as the only parameter. +%.lp +\item[MAXPLAYERS] Limit the maximum number of games that can be running at the same time. %.lp -\item[\ib{SUPPORT}] -A string explainign how to get local support (no default value). +\item[SUPPORT] +A string explaining how to get local support (no default value). %.lp -\item[\ib{RECOVER}] +\item[RECOVER] A string explaining how to recover a game on this system (no default value). %.lp -\item[\ib{SEDUCE}] -0 or 1 to disable or enable, respectively, the SEDUCE option (see the source) -for details on this function. +\item[SEDUCE] +0 or 1 to disable or enable, respectively, the SEDUCE option. +When disabled, incubi and succubi behave like nymphs. %.lp -\item[\ib{CHECK\verb+_+PLNAME}] +\item[CHECK\textunderscore PLNAME] Setting this to 1 will make the EXPLORERS, WIZARDS, and SHELLERS check for the player name instead of the user's login name. %.lp -\item[\ib{CHECK\verb+_+SAVE\verb+_+UID}] -0 or 1 to disable or enable, respectively, the UID checking for savefiles. -\elist +\item[CHECK\textunderscore SAVE\textunderscore UID] +0 or 1 to disable or enable, respectively, the UID +(used identification number) checking for save files (to verify that the +user who is restoring is the same one who saved). +\end{description} %.pg -The following options affect the score file: -\blist {} +The following four options affect the score file: +\begin{description}[font=\mdseries\itshape] %.pg %.lp -\item[\ib{PERSMAX}] -Maximum number of entries for one person +\item[PERSMAX] +Maximum number of entries for one person. %.lp -\item[\ib{ENTRYMAX}] -Maximum number of entries in the score file +\item[ENTRYMAX] +Maximum number of entries in the score file. %.lp -\item[\ib{POINTSMIN}] +\item[POINTSMIN] Minimum number of points to get an entry in the score file. %.lp -\item[\ib{PERS\verb+_+IS\verb+_+UID}] +\item[PERS\textunderscore IS\textunderscore UID] 0 or 1 to use user names or numeric userids, respectively, to identify -unique people for the score file +unique people for the score file. +%.lp +\item[HIDEUSAGE] +0 or 1 to control whether the help menu entry for command +line usage is shown or suppressed. %.lp -\item[\ib{ACCESSIBILITY}] +\item[MAX\textunderscore STATUENAME\textunderscore RANK] +Maximum number of score file entries to use for +random statue names (default is 10). +%.lp +\item[ACCESSIBILITY] 0 or 1 to disable or enable, respectively, the ability for players -to set S\verb+_+pet\verb+_+override and S\verb+_+hero\verb+_+override +to set S\textunderscore pet\textunderscore override and S\textunderscore hero\textunderscore override symbols in their configuration file. %.lp -\item[\ib{PORTABLE\verb+_+DEVICE\verb+_+PATHS}] +\item[PORTABLE\textunderscore DEVICE\textunderscore PATHS] 0 or 1 Windows OS only, the game will look for all of its external -files, and write to all of its output files in one place +files, and write to all of its output files in one place rather than at the standard locations. %.lp -\item[\ib{DUMPLOGFILE}] +\item[DUMPLOGFILE] A filename where the end-of-game dumplog is saved. -Not defining this will prevent dumplog from being created. Only available -if your game is compiled with DUMPLOG. Allows the following placeholders: -%.sd -%.si -{\tt \%\%} --- literal `{\tt \%}'\\ -{\tt \%v} --- version (eg. ``{\tt 3.6.3-0}'')\\ -{\tt \%u} --- game UID\\ -{\tt \%t} --- game start time, UNIX timestamp format\\ -{\tt \%T} --- current time, UNIX timestamp format\\ -{\tt \%d} --- game start time, YYYYMMDDhhmmss format\\ -{\tt \%D} --- current time, YYYYMMDDhhmmss format\\ -{\tt \%n} --- player name\\ -{\tt \%N} --- first character of player name -%.ei -%.ed -\elist +Not defining this will prevent dumplog from being created. +Only available if your game is compiled with DUMPLOG. +Allows the following placeholders: +% FIXME: this should be changed to a nested list or else be forcibly indented +\texttt{\%\%} --- literal `\texttt{\%}'\\ +\texttt{\%v} --- version (eg. ``\texttt{5.0.0-0}'')\\ +\texttt{\%u} --- game UID\\ +\texttt{\%t} --- game start time, UNIX timestamp format\\ +\texttt{\%T} --- current time, UNIX timestamp format\\ +\texttt{\%d} --- game start time, YYYYMMDDhhmmss format\\ +\texttt{\%D} --- current time, YYYYMMDDhhmmss format\\ +\texttt{\%n} --- player name\\ +\texttt{\%N} --- first character of player name +%.lp +\item[LIVELOG] +A bit-mask of types of events that should be written to +the \textit{livelog} file if one is present. +The sample \textit{sysconf} file accompanying the program contains a +comment which lists the meaning of the various bits used. +Intended for server systems supporting simultaneous play by multiple +players (to be clear, each one running a separate single player game), +for displaying their game progress to observers. +Only relevant if the program was built with LIVELOG enabled. +When available, it should be left commented out on single player +installations because over time the file could grow to be extremely +large unless it is actively maintained. +%.lp +\item[CRASHREPORTURL] +If set to +\url{https://www.nethack.org/links/cr-37BETA.html} +and support is compiled in, brings up a browser window populated with +the information needed to report a problem if the game panics or ends +up in an internally inconsistent state, or if the \#bugreport command is +invoked. +\end{description} %.hn 1 \section{Scoring} %.pg -{\it NetHack\/} maintains a list of the top scores or scorers on your machine, +\textit{NetHack} maintains a list of the top scores or scorers on your machine, depending on how it is set up. In the latter case, each account on the machine can post only one non-winning score on this list. If you score higher than someone else on this list, or better your previous score, you will be inserted in the proper place under your current name. How many scores are kept can also be set up when -{\it NetHack\/} is compiled. +\textit{NetHack} is compiled. %.pg Your score is chiefly based upon how much experience you gained, how @@ -5359,7 +7046,7 @@ \section{Scoring} \section{Explore mode} %.pg -{\it NetHack\/} is an intricate and difficult game. Novices might falter +\textit{NetHack} is an intricate and difficult game. Novices might falter in fear, aware of their ignorance of the means to survive. Well, fear not. Your dungeon comes equipped with an ``explore'' or ``discovery'' mode that enables you to keep old save files and cheat death, at the @@ -5367,10 +7054,10 @@ \section{Explore mode} %.pg There are two ways of enabling explore mode. One is to start the game -with the {\tt -X} +with the \texttt{-X} command-line switch or with the -{\it playmode:explore\/} -option. The other is to issue the `{\tt \#exploremode}' extended command while +\textit{playmode:explore} +option. The other is to issue the `\texttt{\#exploremode}' extended command while already playing the game. Starting a new game in explore mode provides your character with a wand of wishing in initial inventory; switching during play does not. The other benefits of explore mode are left for @@ -5389,16 +7076,16 @@ \subsection*{Debug mode} players who attempt debugging are expected to figure out how to use it themselves. It is initiated by starting the game with the -{\tt -D} +\texttt{-D} command-line switch or with the -{\it playmode:debug\/} +\textit{playmode:debug} option. %.pg For some systems, the player must be logged in under a particular user name to be allowed to use debug mode; for others, the hero must be given a particular character name (but may be any role; -there's no connection between ``wizard mode'' and the {\it Wizard\/} role). +there's no connection between ``wizard mode'' and the \textit{Wizard} role). Attempting to start a game in debug mode when not allowed or not available will result in falling back to explore mode instead. @@ -5406,178 +7093,248 @@ \subsection*{Debug mode} \section{Credits} %.pg The original % -{\it hack\/} game was modeled on the Berkeley +\textit{hack} game was modeled on the Berkeley %.ux UNIX -{\it rogue\/} game. Large portions of this paper were shamelessly +\textit{rogue} game. Large portions of this document were shamelessly cribbed from % -{\it A Guide to the Dungeons of Doom}, by Michael C. Toy +\textit{A Guide to the Dungeons of Doom}, by Michael C. Toy and Kenneth C. R. C. Arnold. Small portions were adapted from -{\it Further Exploration of the Dungeons of Doom}, by Ken Arromdee. +\textit{Further Exploration of the Dungeons of Doom}, by Ken Arromdee. %.pg -{\it NetHack\/} is the product of literally dozens of people's work. +\textit{NetHack} is the product of literally scores of people's work. Main events in the course of the game development are described below: %.pg \bigskip -\nd {\it Jay Fenlason\/} wrote the original {\it Hack\/} with help from {\it -Kenny Woodland}, {\it Mike Thome}, and {\it Jon Payne}. +\noindent \textit{Jay Fenlason} wrote the original \textit{Hack}, with help from {\it +Kenny Woodland}, \textit{Mike Thome}, and \textit{Jon Payne}. %.pg \medskip -\nd {\it Andries Brouwer\/} did a major re-write, transforming {\it Hack\/} -into a very different game, and published (at least) three versions (1.0.1, -1.0.2, and 1.0.3) for UNIX machines to the Usenet. +\noindent \textit{Andries Brouwer} did a major re-write while at +Stichting Mathematisch Centrum (now Centrum Wiskunde \& Informatica), +transforming Hack into a very different game. +He published the Hack source code for use on UNIX +systems by posting that to Usenet +newsgroup \textit{net.sources} (later renamed \textit{comp.sources}) +releasing version 1.0 in December of 1984, then versions 1.0.1, 1.0.2, +and finally 1.0.3 in July of 1985. +Usenet newsgroup \textit{net.games.hack} (later +renamed \textit{rec.games.hack}, eventually replaced +by \textit{rec.games.roguelike.nethack}) +was created for discussing it. %.pg \medskip -\nd {\it Don G. Kneller\/} ported {\it Hack\/} 1.0.3 to Microsoft C and MS-DOS, -producing {\it PC Hack\/} 1.01e, added support for DEC Rainbow graphics in +\noindent \textit{Don G. Kneller} ported \textit{Hack} 1.0.3 to Microsoft C and MS-DOS, +producing \textit{PC Hack} 1.01e, added support for DEC Rainbow graphics in version 1.03g, and went on to produce at least four more versions (3.0, 3.2, -3.51, and 3.6). +3.51, and 3.6; +note that these are old \textit{Hack} version numbers, not contemporary +\textit{NetHack} ones). %.pg \medskip -\nd {\it R. Black\/} ported {\it PC Hack\/} 3.51 to Lattice C and the Atari -520/1040ST, producing {\it ST Hack\/} 1.03. +\noindent \textit{R. Black} ported \textit{PC Hack} 3.51 to Lattice C and the Atari +520/1040ST, producing \textit{ST Hack} 1.03. %.pg \medskip -\nd {\it Mike Stephenson\/} merged these various versions back together, -incorporating many of the added features, and produced {\it NetHack\/} version -1.4. He then coordinated a cast of thousands in enhancing and debugging -{\it NetHack\/} 1.4 and released {\it NetHack\/} versions 2.2 and 2.3. +\noindent \textit{Mike Stephenson} merged these various versions back together, +incorporating many of the added features, and produced \textit{NetHack} version +1.4 in 1987. +He then coordinated a cast of thousands in enhancing and debugging +\textit{NetHack} 1.4 and released \textit{NetHack} versions 2.2 and 2.3. +Like Hack, they were released by posting their source code to Usenet where +they remained available in various archives accessible +via \textit{ftp} and \textit{uucp} after expiring from the newsgroup. %.pg \medskip -\nd Later, Mike coordinated a major rewrite of the game, heading a team which -included {\it Ken Arromdee}, {\it Jean-Christophe Collet}, {\it Steve Creps}, -{\it Eric Hendrickson}, {\it Izchak Miller}, {\it Eric S. Raymond}, {\it John -Rupley}, {\it Mike Threepoint}, and {\it Janet Walz}, to produce {\it -NetHack\/} 3.0c. +\noindent Later, Mike coordinated a major re-write of the game, heading a team which +included \textit{Ken Arromdee}, \textit{Jean-Christophe Collet}, \textit{Steve Creps}, +\textit{Eric Hendrickson}, \textit{Izchak Miller}, \textit{Eric S. Raymond}, \textit{John +Rupley}, \textit{Mike Threepoint}, and \textit{Janet Walz}, to produce +\textit{NetHack} 3.0c. %.pg \medskip -\nd {\it NetHack\/} 3.0 was ported to the Atari by {\it Eric R. Smith}, to OS/2 by -{\it Timo Hakulinen}, and to VMS by {\it David Gentzel}. The three of them -and {\it Kevin Darcy\/} later joined the main {\it NetHack Development Team} to produce +\noindent \textit{NetHack} 3.0 was ported to the Atari by \textit{Eric R. Smith}, to OS/2 by +\textit{Timo Hakulinen}, and to VMS by \textit{David Gentzel}. The three of them +and \textit{Kevin Darcy} later joined the main \textit{NetHack Development Team} to produce subsequent revisions of 3.0. %.pg \medskip -\nd {\it Olaf Seibert\/} ported {\it NetHack\/} 2.3 and 3.0 to the Amiga. {\it -Norm Meluch}, {\it Stephen Spackman\/} and {\it Pierre Martineau\/} designed -overlay code for {\it PC NetHack\/} 3.0. {\it Johnny Lee\/} ported {\it -NetHack\/} 3.0 to the Macintosh. Along with various other Dungeoneers, they +\noindent \textit{Olaf Seibert} ported \textit{NetHack} 2.3 and 3.0 to the Amiga. {\it +Norm Meluch}, \textit{Stephen Spackman} and \textit{Pierre Martineau} designed +overlay code for \textit{PC NetHack} 3.0. \textit{Johnny Lee} ported +\textit{NetHack} 3.0 to the Macintosh. Along with various other Dungeoneers, they continued to enhance the PC, Macintosh, and Amiga ports through the later revisions of 3.0. +%.pg +Version 3.0 went through ten relatively rapidly released ``patch-level'' +revisions. +Versions at the time were known as 3.0 for the base release and variously +as ``3.0a'' through ``3.0j'', +``3.0~patchlevel~1'' through ``3.0~patchlevel~10'', +or ``3.0pl1'' through ``3.0pl10'' +rather than 3.0.0 and 3.0.1 through 3.0.10; +the three component numbering scheme began to be used with 3.1.0. + %.pg \medskip -\nd Headed by {\it Mike Stephenson\/} and coordinated by {\it Izchak Miller\/} and -{\it Janet Walz}, the {\it NetHack Development Team} which now included {\it Ken Arromdee}, -{\it David Cohrs}, {\it Jean-Christophe Collet}, {\it Kevin Darcy}, -{\it Matt Day}, {\it Timo Hakulinen}, {\it Steve Linhart}, {\it Dean Luick}, -{\it Pat Rankin}, {\it Eric Raymond}, and {\it Eric Smith\/} undertook a radical -revision of 3.0. They re-structured the game's design, and re-wrote major -parts of the code. They added multiple dungeons, a new display, special +\noindent Headed by \textit{Mike Stephenson} and coordinated by \textit{Izchak Miller} +and \textit{Janet Walz}, the \textit{NetHack Development Team} which now included +\textit{Ken Arromdee}, +\textit{David Cohrs}, \textit{Jean-Christophe Collet}, \textit{Kevin Darcy}, +\textit{Matt Day}, \textit{Timo Hakulinen}, \textit{Steve Linhart}, \textit{Dean Luick}, +\textit{Pat Rankin}, \textit{Eric Raymond}, and \textit{Eric Smith} undertook a +radical revision of 3.0. +They re-structured the game's design, and re-wrote major +parts of the code. +They added multiple dungeons, a new display, special individual character quests, a new endgame and many other new features, and -produced {\it NetHack\/} 3.1. +produced \textit{NetHack} 3.1. +Version 3.1.0 was released in January of 1993. %.pg \medskip -\nd {\it Ken Lorber}, {\it Gregg Wonderly\/} and {\it Greg Olson}, with help -from {\it Richard Addison}, {\it Mike Passaretti}, and {\it Olaf Seibert}, -developed {\it NetHack\/} 3.1 for the Amiga. +\noindent \textit{Ken Lorber}, \textit{Gregg Wonderly} and \textit{Greg Olson}, with help +from \textit{Richard Addison}, \textit{Mike Passaretti}, and \textit{Olaf Seibert}, +developed \textit{NetHack} 3.1 for the Amiga. %.pg \medskip -\nd {\it Norm Meluch\/} and {\it Kevin Smolkowski}, with help from -{\it Carl Schelin}, {\it Stephen Spackman}, {\it Steve VanDevender}, -and {\it Paul Winner}, ported {\it NetHack\/} 3.1 to the PC. +\noindent \textit{Norm Meluch} and \textit{Kevin Smolkowski}, with help from +\textit{Carl Schelin}, \textit{Stephen Spackman}, \textit{Steve VanDevender}, +and \textit{Paul Winner}, ported \textit{NetHack} 3.1 to the PC. %.pg \medskip -\nd {\it Jon W\{tte} and {\it Hao-yang Wang}, -with help from {\it Ross Brown}, {\it Mike Engber}, {\it David Hairston}, -{\it Michael Hamel}, {\it Jonathan Handler}, {\it Johnny Lee}, -{\it Tim Lennan}, {\it Rob Menke}, and {\it Andy Swanson}, -developed {\it NetHack\/} 3.1 for the Macintosh, porting it for MPW. -Building on their development, {\it Bart House} added a Think C port. +\noindent \textit{Jon W\textbraceleft tte} and \textit{Hao-yang Wang}, +with help from \textit{Ross Brown}, \textit{Mike Engber}, \textit{David Hairston}, +\textit{Michael Hamel}, \textit{Jonathan Handler}, \textit{Johnny Lee}, +\textit{Tim Lennan}, \textit{Rob Menke}, and \textit{Andy Swanson}, +developed \textit{NetHack} 3.1 for the Macintosh, porting it for MPW. +Building on their development, \textit{Bart House} added a Think C port. %.pg \medskip -\nd {\it Timo Hakulinen\/} ported {\it NetHack\/} 3.1 to OS/2. -{\it Eric Smith\/} ported {\it NetHack\/} 3.1 to the Atari. -{\it Pat Rankin}, with help from {\it Joshua Delahunty}, -was responsible for the VMS version of {\it NetHack\/} 3.1. -{\it Michael Allison} ported {\it NetHack\/} 3.1 to Windows NT. +\noindent \textit{Timo Hakulinen} ported \textit{NetHack} 3.1 to OS/2. +\textit{Eric Smith} ported \textit{NetHack} 3.1 to the Atari. +\textit{Pat Rankin}, with help from \textit{Joshua Delahunty}, +was responsible for the VMS version of \textit{NetHack} 3.1. +\textit{Michael Allison} ported \textit{NetHack} 3.1 to Windows NT. %.pg \medskip -\nd {\it Dean Luick}, with help from {\it David Cohrs}, developed {\it NetHack\/} -3.1 for X11. -{\it Warwick Allison} wrote a tiled version of {\it NetHack\/} for the Atari; -he later contributed the tiles to the {\it NetHack Development Team} and tile support was -then added to other platforms. +\noindent \textit{Dean Luick}, with help from \textit{David Cohrs}, developed +\textit{NetHack} 3.1 for X11. +It drew the map as text rather than graphically but +included \texttt{nh10.bdf}, an optionally used custom X11 font which has +tiny images in place of letters and punctuation, a precursor of tiles. +Those images don't extend to individual monster and object types, just +replacements for monster and object classes (so one custom image for all +``\texttt{a}'' insects and another for all ``\texttt{[}'' armor and so +forth, not separate images for beetles and ants or for cloaks and boots). %.pg \medskip -\nd The 3.2 {\it NetHack Development Team}, comprised of {\it Michael Allison}, {\it Ken -Arromdee}, {\it David Cohrs}, {\it Jessie Collet}, {\it Steve Creps}, {\it -Kevin Darcy}, {\it Timo Hakulinen}, {\it Steve Linhart}, {\it Dean Luick}, -{\it Pat Rankin}, {\it Eric Smith}, {\it Mike Stephenson}, {\it Janet Walz}, -and {\it Paul Winner}, released version 3.2 in April of 1996. +\noindent \textit{Warwick Allison} wrote a graphically displayed version +of \textit{NetHack} +for the Atari where the tiny pictures were described as ``icons'' and +were distinct for specific types of monsters and objects rather than just +their classes. +He contributed them to the \textit{NetHack Development Team} which +rechristened them ``tiles'', original usage which has subsequently been +picked up by various other games. +\textit{NetHack's} tiles support was then implemented on other platforms +(initially MS-DOS but eventually Windows, Qt, and X11 too). %.pg \medskip -\nd Version 3.2 marked the tenth anniversary of the formation of the development -team. In a testament to their dedication to the game, all thirteen members -of the original {\it NetHack Development Team} remained on the team at the start of work on -that release. During the interval between the release of 3.1.3 and 3.2, -one of the founding members of the {\it NetHack Development Team}, {\it Dr. Izchak Miller}, -was diagnosed with cancer and passed away. That release of the game was +\noindent The 3.2 \textit{NetHack Development Team}, comprised of \textit{Michael Allison}, \textit{Ken +Arromdee}, \textit{David Cohrs}, \textit{Jessie Collet}, \textit{Steve Creps}, {\it +Kevin Darcy}, \textit{Timo Hakulinen}, \textit{Steve Linhart}, \textit{Dean Luick}, +\textit{Pat Rankin}, \textit{Eric Smith}, \textit{Mike Stephenson}, \textit{Janet Walz}, +and \textit{Paul Winner}, released version 3.2.0 in April of 1996. + +%.pg +\medskip +\noindent Version 3.2 marked the tenth anniversary of the formation of the +development team. +In a testament to their dedication to the game, all thirteen members +of the original \textit{NetHack Development Team} remained on the team at the +start of work on that release. +During the interval between the release of 3.1.3 and 3.2.0, +one of the founding members of the \textit{NetHack Development Team}, +\textit{Dr. Izchak Miller}, was diagnosed with cancer and passed away. +That release of the game was dedicated to him by the development and porting teams. +%.pg +Version 3.2 proved to be more stable than previous versions. +Many bugs were fixed, abuses eliminated, and game features tuned for +better game play. + %.pg \medskip -During the lifespan of {\it NetHack\/} 3.1 and 3.2, several enthusiasts +During the lifespan of \textit{NetHack} 3.1 and 3.2, several enthusiasts of the game added their own modifications to the game and made these ``variants'' publicly available: %.pg \medskip -{\it Tom Proudfoot} and {\it Yuval Oren} created {\it NetHack++}, -which was quickly renamed {\it NetHack$--$}. -Working independently, {\it Stephen White} wrote {\it NetHack Plus}. -{\it Tom Proudfoot} later merged {\it NetHack Plus} -and his own {\it NetHack$--$} to produce {\it SLASH}. -{\it Larry Stewart-Zerba} and {\it Warwick Allison} improved the spell +\textit{Tom Proudfoot} and \textit{Yuval Oren} created \textit{NetHack++}, +which was quickly renamed \textit{NetHack$--$} +when some people incorrectly assumed that it was a conversion of the +\textit{C} source code to \textit{C++}. +Working independently, \textit{Stephen White} wrote \textit{NetHack Plus}. +\textit{Tom Proudfoot} later merged \textit{NetHack Plus} +and his own \textit{NetHack$--$} to produce \textit{SLASH}. +\textit{Larry Stewart-Zerba} and \textit{Warwick Allison} improved the spell casting system with the Wizard Patch. -{\it Warwick Allison} also ported {\it NetHack\/} to use the Qt interface. +\textit{Warwick Allison} also ported \textit{NetHack} to use the Qt interface. %.pg \medskip -{\it Warren Cheung} combined {\it SLASH} with the Wizard Patch -to produce {\it Slash'EM\/}, and -with the help of {\it Kevin Hugo}, added more features. -Kevin later joined the -{\it NetHack Development Team} and incorporated the best of these ideas into {\it NetHack\/} 3.3. +\textit{Warren Cheung} combined \textit{SLASH} with the Wizard Patch +to produce \textit{Slash'EM}, and +with the help of \textit{Kevin Hugo}, added more features. +Kevin later joined the \textit{NetHack Development Team} and incorporated +the best of these ideas into \textit{NetHack} 3.3. %.pg \medskip The final update to 3.2 was the bug fix release 3.2.3, which was released simultaneously with 3.3.0 in December 1999 just in time for the Year 2000. +Because of the newer version, 3.2.3 was released as a source code patch only, +without any ready-to-play distribution for systems that usually had such. + +%.pg +(To anyone considering resurrecting an old version: all versions before +3.2.3 had a \textit{Y2K} bug. +The high scores file and the log file contained +dates which were formatted using a two-digit year, and 1999's year 99 was +followed by 2000's year 100. +That got written out successfully but it +unintentionally introduced an extra column in the file layout which prevented +score entries from being read back in correctly, interfering with insertion +of new high scores and with retrieval of old character names to use for +random ghost and statue names in the current game.) %.pg \medskip -The 3.3 {\it NetHack Development Team}, consisting of {\it Michael Allison}, {\it Ken Arromdee}, -{\it David Cohrs}, {\it Jessie Collet}, {\it Steve Creps}, {\it Kevin Darcy}, -{\it Timo Hakulinen}, {\it Kevin Hugo}, {\it Steve Linhart}, {\it Ken Lorber}, -{\it Dean Luick}, {\it Pat Rankin}, {\it Eric Smith}, {\it Mike Stephenson}, -{\it Janet Walz}, and {\it Paul Winner}, released 3.3.0 in +The 3.3 \textit{NetHack Development Team}, consisting of \textit{Michael Allison}, \textit{Ken Arromdee}, +\textit{David Cohrs}, \textit{Jessie Collet}, \textit{Steve Creps}, \textit{Kevin Darcy}, +\textit{Timo Hakulinen}, \textit{Kevin Hugo}, \textit{Steve Linhart}, \textit{Ken Lorber}, +\textit{Dean Luick}, \textit{Pat Rankin}, \textit{Eric Smith}, \textit{Mike Stephenson}, +\textit{Janet Walz}, and \textit{Paul Winner}, released 3.3.0 in December 1999 and 3.3.1 in August of 2000. %.pg @@ -5595,107 +7352,110 @@ \section{Credits} %.pg \medskip -The 3.4 {\it NetHack Development Team} initially consisted of -{\it Michael Allison}, {\it Ken Arromdee}, -{\it David Cohrs}, {\it Jessie Collet}, {\it Kevin Hugo}, {\it Ken Lorber}, -{\it Dean Luick}, {\it Pat Rankin}, {\it Mike Stephenson}, -{\it Janet Walz}, and {\it Paul Winner}, with {\it Warwick Allison} joining -just before the release of {\it NetHack\/} 3.4.0 in March 2002. +The 3.4 \textit{NetHack Development Team} initially consisted of +\textit{Michael Allison}, \textit{Ken Arromdee}, +\textit{David Cohrs}, \textit{Jessie Collet}, \textit{Kevin Hugo}, \textit{Ken Lorber}, +\textit{Dean Luick}, \textit{Pat Rankin}, \textit{Mike Stephenson}, +\textit{Janet Walz}, and \textit{Paul Winner}, with \textit{ Warwick Allison} joining +just before the release of \textit{NetHack} 3.4.0 in March 2002. %.pg \medskip As with version 3.3, various people contributed to the game as a whole as -well as supporting ports on the different platforms that {\it NetHack\/} +well as supporting ports on the different platforms that \textit{NetHack} runs on: %.pg \medskip -\nd{\it Pat Rankin} maintained 3.4 for VMS. +\noindent\textit{Pat Rankin} maintained 3.4 for VMS. %.pg \medskip -\nd {\it Michael Allison} maintained {\it NetHack\/} 3.4 for the MS-DOS +\noindent \textit{Michael Allison} maintained \textit{NetHack} 3.4 for the MS-DOS platform. -{\it Paul Winner} and {\it Yitzhak Sapir} provided encouragement. +\textit{Paul Winner} and \textit{Yitzhak Sapir} provided encouragement. %.pg \medskip -\nd {\it Dean Luick}, {\it Mark Modrall}, and {\it Kevin Hugo} maintained and +\noindent \textit{Dean Luick}, \textit{Mark Modrall}, and \textit{Kevin Hugo} maintained and enhanced the Macintosh port of 3.4. %.pg \medskip -\nd {\it Michael Allison}, {\it David Cohrs}, {\it Alex Kompel}, -{\it Dion Nicolaas}, and -{\it Yitzhak Sapir} maintained and enhanced 3.4 for the Microsoft Windows +\noindent \textit{Michael Allison}, \textit{David Cohrs}, \textit{Alex Kompel}, +\textit{Dion Nicolaas}, and +\textit{Yitzhak Sapir} maintained and enhanced 3.4 for the Microsoft Windows platform. -{\it Alex Kompel} contributed a new graphical interface for the Windows port. -{\it Alex Kompel} also contributed a Windows CE port for 3.4.1. +\textit{Alex Kompel} contributed a new graphical interface for the Windows port. +\textit{Alex Kompel} also contributed a Windows CE port for 3.4.1. %.pg \medskip -\nd {\it Ron Van Iwaarden} was the sole maintainer of {\it NetHack\/} for +\noindent \textit{Ron Van Iwaarden} was the sole maintainer of \textit{NetHack} for OS/2 the past several releases. Unfortunately Ron's last OS/2 machine stopped working in -early 2006. A great many thanks to Ron for keeping {\it NetHack\/} alive on +early 2006. A great many thanks to Ron for keeping \textit{NetHack} alive on OS/2 all these years. %.pg \medskip -\nd {\it Janne Salmij\"{a}rvi} and {\it Teemu Suikki} maintained -and enhanced the Amiga port of 3.4 after {\it Janne Salmij\"{a}rvi} resurrected +\noindent \textit{Janne Salmij\"{a}rvi} and \textit{Teemu Suikki} maintained +and enhanced the Amiga port of 3.4 after \textit{Janne Salmij\"{a}rvi} resurrected it for 3.3.1. %.pg \medskip -\nd {\it Christian ``Marvin'' Bressler} maintained 3.4 for the Atari after he +\noindent \textit{Christian ``Marvin'' Bressler} maintained 3.4 for the Atari after he resurrected it for 3.3.1. %.pg \medskip -The release of {\it NetHack\/} 3.4.3 in December 2003 marked the beginning of +The release of \textit{NetHack} 3.4.3 in December 2003 marked the beginning of a long release hiatus. 3.4.3 proved to be a remarkably stable version that provided continued enjoyment by the community for more than a decade. The -{\it NetHack Development Team} slowly and quietly continued to work on the game behind the scenes +\textit{NetHack Development Team} slowly and quietly continued to work on the game behind the scenes during the tenure of 3.4.3. It was during that same period that several new -variants emerged within the {\it NetHack\/} community. Notably sporkhack by -Derek S. Ray, {\it unnethack\/} by Patric Mueller, {\it nitrohack\/} and its +variants emerged within the \textit{NetHack} community. Notably sporkhack by +Derek S. Ray, \textit{unnethack} by Patric Mueller, \textit{nitrohack} and its successors originally by Daniel Thaler and then by Alex Smith, and -{\it Dynahack\/} by Tung Nguyen. Some of those variants continue to be +\textit{Dynahack} by Tung Nguyen. +Some of those variants continue to be developed, maintained, and enjoyed by the community to this day. %.pg \medskip In September 2014, an interim snapshot of the code under development was -released publicly by other parties. Since that code was a work-in-progress +released publicly by other parties. +Since that code was a work-in-progress and had not gone through the process of debugging it as a suitable release, it was decided that the version numbers present on that code snapshot would -be retired and never used in an official {\it NetHack\/} release. An -announcement was posted on the {\it NetHack Development Team}'s official {\it nethack.org\/} website +be retired and never used in an official \textit{NetHack} release. +An announcement was posted on the \textit{NetHack Development Team}'s official +\textit{nethack.org} website to that effect, stating that there would never be a 3.4.4, 3.5, or 3.5.0 official release version. %.pg \medskip -In January 2015, preparation began for the release of NetHack 3.6. +In January 2015, preparation began for the release of \textit{NetHack} 3.6. %.pg \medskip -At the beginning of development for what would eventually get released -as 3.6.0, the {\it NetHack Development Team} consisted of {\it Warwick Allison}, -{\it Michael Allison}, {\it Ken Arromdee}, -{\it David Cohrs}, {\it Jessie Collet}, -{\it Ken Lorber}, {\it Dean Luick}, {\it Pat Rankin}, -{\it Mike Stephenson}, {\it Janet Walz}, and {\it Paul Winner}. +At the beginning of development for what would eventually get released as +3.6.0, the \textit{NetHack Development Team} consisted of \textit{Warwick Allison}, +\textit{Michael Allison}, \textit{Ken Arromdee}, +\textit{David Cohrs}, \textit{Jessie Collet}, +\textit{Ken Lorber}, \textit{Dean Luick}, \textit{Pat Rankin}, +\textit{Mike Stephenson}, \textit{Janet Walz}, and \textit{Paul Winner}. In early 2015, ahead of the release of 3.6.0, new members -{\it Sean Hunt}, {\it Pasi Kallinen}, and {\it Derek S. Ray} -joined the {\it NetHack\/} development team. +\textit{Sean Hunt}, \textit{Pasi Kallinen}, and \textit{Derek S. Ray} +joined the \textit{NetHack Development Team}. %.pg \medskip Near the end of the development of 3.6.0, one of the significant inspirations for many of the humorous and fun features found in the game, -author Terry Pratchett, passed away. {\it NetHack\/} 3.6.0 introduced +author Terry Pratchett, passed away. \textit{NetHack} 3.6.0 introduced a tribute to him. %.pg @@ -5706,45 +7466,46 @@ \section{Credits} %.pg \medskip -The {\it NetHack Development Team}, as well as {\it Steve VanDevender} and -{\it Kevin Smolkowski}, ensured that {\it NetHack\/} 3.6 continued to -operate on various Unix flavors and maintained the X11 interface. +The \textit{NetHack Development Team}, as well as \textit{Steve VanDevender} and +\textit{Kevin Smolkowski}, ensured that \textit{NetHack} 3.6 continued to +operate on various UNIX flavors and maintained the X11 interface. %.pg \medskip -{\it Ken Lorber}, {\it Haoyang Wang}, {\it Pat Rankin}, and {\it Dean Luick} -maintained the port of {\it NetHack\/} 3.6 for Mac OSX. +\textit{Ken Lorber}, \textit{Haoyang Wang}, \textit{Pat Rankin}, and \textit{Dean Luick} +maintained the port of \textit{NetHack} 3.6 for MacOS. %.pg \medskip -{\it Michael Allison}, {\it David Cohrs}, {\it Bart House}, -{\it Pasi Kallinen}, {\it Alex Kompel}, {\it Dion Nicolaas}, -{\it Derek S. Ray} and {\it Yitzhak Sapir} -maintained the port of {\it NetHack\/} 3.6 for Microsoft Windows. +\textit{Michael Allison}, \textit{David Cohrs}, \textit{Bart House}, +\textit{Pasi Kallinen}, \textit{Alex Kompel}, \textit{Dion Nicolaas}, +\textit{Derek S. Ray} and \textit{Yitzhak Sapir} +maintained the port of \textit{NetHack} 3.6 for Microsoft Windows. %.pg \medskip -{\it Pat Rankin} attempted to keep the VMS port running for NetHack 3.6, -hindered by limited access. {\it Kevin Smolkowski} has updated and tested it +\textit{Pat Rankin} attempted to keep the VMS port running for \textit{NetHack} 3.6, +hindered by limited access. \textit{Kevin Smolkowski} has updated and tested it for the most recent version of OpenVMS (V8.4 as of this writing) on Alpha and Integrity (aka Itanium aka IA64) but not VAX. %.pg \medskip -{\it Ray Chason} resurrected the msdos port for 3.6 and contributed the +\textit{Ray Chason} resurrected the MS-DOS port for 3.6 and contributed the necessary updates to the community at large. %.pg \medskip In late April 2018, several hundred bug fixes for 3.6.0 and some new features -were assembled and released as NetHack 3.6.1. The {\it NetHack Development Team} at the +were assembled and released as \textit{NetHack} 3.6.1. +The \textit{NetHack Development Team} at the time of release of 3.6.1 consisted of -{\it Warwick Allison}, {\it Michael Allison}, {\it Ken Arromdee}, -{\it David Cohrs}, {\it Jessie Collet}, -{\it Pasi Kallinen}, {\it Ken Lorber}, {\it Dean Luick}, -{\it Patric Mueller}, {\it Pat Rankin}, {\it Derek S. Ray}, -{\it Alex Smith}, {\it Mike Stephenson}, {\it Janet Walz}, and -{\it Paul Winner}. +\textit{Warwick Allison}, \textit{Michael Allison}, \textit{Ken Arromdee}, +\textit{David Cohrs}, \textit{Jessie Collet}, +\textit{Pasi Kallinen}, \textit{Ken Lorber}, \textit{Dean Luick}, +\textit{Patric Mueller}, \textit{Pat Rankin}, \textit{Derek S. Ray}, +\textit{Alex Smith}, \textit{Mike Stephenson}, \textit{Janet Walz}, and +\textit{Paul Winner}. %.pg \medskip @@ -5753,110 +7514,200 @@ \section{Credits} %.pg \medskip -{\it Bart House}, who had contributed to the game as a porting team participant -for decades, joined the {\it NetHack Development Team} in late May 2019. +\textit{Bart House}, who had contributed to the game as a porting team participant +for decades, joined the \textit{NetHack Development Team} in late May 2019. %.pg \medskip -NetHack 3.6.3 was released on December 5, 2019 containing over 190 bug -fixes to NetHack 3.6.2. +\textit{NetHack} 3.6.3 was released on December 5, 2019 containing over 190 bug +fixes to \textit{NetHack} 3.6.2. %.pg \medskip -NetHack 3.6.4 was released on December 18, 2019 containing a security fix and +\textit{NetHack} 3.6.4 was released on December 18, 2019 containing a security fix and a few bug fixes. %.pg \medskip -NetHack 3.6.5 was released on January 27, 2020 containing some security fixes +\textit{NetHack} 3.6.5 was released on January 27, 2020 containing some security fixes and a small number of bug fixes. %.pg \medskip -NetHack 3.6.6 was released on March 8, 2020 containing a security fix and +\textit{NetHack} 3.6.6 was released on March 8, 2020 containing a security fix and some bug fixes. %.pg \medskip -NetHack 3.6.7 was released in February 2023 containing a security fix and +\textit{NetHack} 3.6.7 was released on February 16, 2023 containing a security fix and some bug fixes. %.pg \medskip -\nd The official {\it NetHack\/} web site is maintained by {\it Ken Lorber} at -{\catcode`\#=11 -\special{html:}} -https:{\tt /}{\tt /}www.nethack.org{\tt /}. -{\catcode`\#=11 -\special{html:}} +Development work for the major release to follow \textit{NetHack} 3.6 began in 2015 +around the same time as \textit{NetHack} 3.6.0 was being released. That development +work continued in parallel to each of the \textit{NetHack} 3.6 releases from 2015 +through 2023, and continued until the end of April 2026. For the first time, +that development was shared publicly on GitHub and SourceForge as it occurred. +It was done under the label NetHack-3.7 work-in-progress (WIP), although the +version number for the next release had not yet been solidified. + +%.pg +\medskip +Exposure of the development to the public brought many good things, and some +challenges. People were able to observe and criticize changes and new features +almost immediately, and they often did. The GitHub pull request system made +it straightforward for people to contribute directly to development. +Contributions resolved many, many bugs in the game and we thank all the +contributors. + +%.pg +\medskip +In early 2026, with the game development getting stable enough to consider +initiating an official release, the devteam reviewed the nature and number of +changes in the game. It was clear that there was sufficient depth and +breadth to warrant a major release and version 5.0 was decided on. +That's a new major release over 3.x, without opening up any ambiguity +or confusion with existing variants that there might have been had it +been released as version 4.0. + +%.pg +\medskip +\textit{NetHack} 5.0.0 was released on May 2, 2026. + +%.pg +\medskip +The source code for \textit{NetHack} 5.0.0 was modified and modernized to be +compliant with the C99 standard. The 5.0.0 release contained over 3100 fixes, +changes, and updated features. + +%.pg +\medskip +\textit{NetHack} 5.0 was the first version to replace the lex and yacc level +and dungeon compilers of past versions, with a new Lua interpreter-based +approach to provide those elements. Lua is also used for the quest texts +in \textit{NetHack} 5.0.0. The entire development team acknowledges the work +done by \textit{Pasi Kallinen} to make that happen. + +%.pg +\medskip +At the time of the \textit{NetHack} 5.0 release, the core +\textit{NetHack Development Team}, +active and erstwhile, included \textit{Warwick Allison}, \textit{Michael Allison}, +\textit{Ken Arromdee}, \textit{David Cohrs}, \textit{Jessie Collet}, \textit{Bart House}, +\textit{Kevin Hugo}, \textit{Pasi Kallinen}, \textit{Ken Lorber}, \textit{Dean Luick}, +\textit{Pat Rankin}, \textit{Derek S. Ray}, \textit{Alex Smith}, \textit{Patric Mueller}, +\textit{Mike Stephenson}, \textit{Janet Walz}, \textit{Paul Winner}. + +%.pg +\medskip +\textit{Ken Lorber}, \textit{Pat Rankin}, \textit{Patrick Mueller} and +\textit{Michael Allison} helped ensure that \textit{NetHack} 5.0 would run +on macOS. + +%.pg +\medskip +\textit{Ingo Paschke} somehow managed to revive a \textit{NetHack} 5.0 port for the Amiga, +using a cross-compiler on a modern platform to do so. His work was shared so +others can straightforwardly produce \textit{NetHack} 5.0 for the Amiga thanks to his +efforts. + +%.pg +\medskip +\textit{Ray Chason} contributed the majority of maintenance work for the +\textit{NetHack} 5.0 MS-DOS port, including porting the curses interface to it. +\textit{Michael Allison} ensured that \textit{NetHack} 5.0 core changes continued to +work with the msdos port and keep it alive. Cross-compiling the MS-DOS +port has helped make that possible and mostly painless. + +%.pg +\medskip +People that contributed to the Windows port of \textit{NetHack} 5.0 since the +development of \textit{NetHack} 5.0 began over eleven years ago, included +\textit{Michael Allison}, \textit{David Cohrs}, \textit{Bart House}, +\textit{Pasi Kallinen}, \textit{Alex Kompel}, \textit{Dion Nicolaas}, +\textit{Derek S. Ray} and \textit{Yitzhak Sapir}. + +%.pg +\medskip +With sadness, the devteam would like to acknowledge and remember the past +contributions from the late \textit{Ron Van Iwaarden}, who was the sole maintainer +of \textit{NetHack} for OS/2 for several past \textit{NetHack} releases. Ron will be missed. + +%.pg +\medskip +\noindent The official \textit{NetHack} web site is maintained by \textit{Ken Lorber} at +\url{https://www.nethack.org}. %.pg %.hn 2 \subsection*{Special Thanks} -\nd On behalf of the {\it NetHack\/} community, thank you very much once -again to {\it M. Drew Streib} and {\it Pasi Kallinen} for providing a -public NetHack server at nethack.alt.org. Thanks to {\it Keith Simpson} -and {\it Andy Thomson} for hardfought.org. Thanks to all those +\noindent On behalf of the \textit{NetHack} community, thank you very much once +again to \textit{M. Drew Streib} and \textit{Pasi Kallinen} for providing a +public \textit{NetHack} server at nethack.alt.org. Thanks to \textit{Keith Simpson} +and \textit{Andy Thomson} for hardfought.org. Thanks to all those unnamed dungeoneers who invest their time and effort into annual -{\it NetHack\/} tournaments such as {\it Junethack}, -{\it The November NetHack Tournament} and in days past, -{\it devnull.net\/} (gone for now, but not forgotten). +\textit{NetHack} tournaments such as \textit{Junethack}, +\textit{The November NetHack Tournament}, and in days past, +\textit{devnull.net} (gone for now, but not forgotten). \clearpage -%.hn -\section*{Dungeoneers} +%.hn 2 +\subsection*{Dungeoneers} %.pg -\nd From time to time, some depraved individual out there in netland sends a +\noindent From time to time, some depraved individual out there in netland sends a particularly intriguing modification to help out with the game. The -{\it NetHack Development Team} sometimes makes note of the names of the worst +\textit{NetHack Development Team} sometimes makes note of the names of the worst of these miscreants in this, the list of Dungeoneers: +\medskip %.sd \begin{center} \begin{tabular}{llll} %TABLE_START -Adam Aronow & J. Ali Harlow & Mikko Juola\\ -Alex Kompel & Janet Walz & Nathan Eady\\ -Alex Smith & Janne Salmij\"{a}rvi & Norm Meluch\\ -Andreas Dorn & Jean-Christophe Collet & Olaf Seibert\\ -Andy Church & Jeff Bailey & Pasi Kallinen\\ -Andy Swanson & Jochen Erwied & Pat Rankin\\ -Andy Thomson & John Kallen & Patric Mueller\\ -Ari Huttunen & John Rupley & Paul Winner\\ -Bart House & John S. Bien & Pierre Martineau\\ -Benson I. Margulies & Johnny Lee & Ralf Brown\\ -Bill Dyer & Jon W\{tte & Ray Chason\\ -Boudewijn Waijers & Jonathan Handler & Richard Addison\\ -Bruce Cox & Joshua Delahunty & Richard Beigel\\ -Bruce Holloway & Karl Garrison & Richard P. Hughey\\ -Bruce Mewborne & Keizo Yamamoto & Rob Menke\\ -Carl Schelin & Keith Simpson & Robin Bandy\\ -Chris Russo & Ken Arnold & Robin Johnson\\ -David Cohrs & Ken Arromdee & Roderick Schertler\\ -David Damerell & Ken Lorber & Roland McGrath\\ -David Gentzel & Ken Washikita & Ron Van Iwaarden\\ -David Hairston & Kevin Darcy & Ronnen Miller\\ -Dean Luick & Kevin Hugo & Ross Brown\\ -Del Lamb & Kevin Sitze & Sascha Wostmann\\ -Derek S. Ray & Kevin Smolkowski & Scott Bigham\\ -Deron Meranda & Kevin Sweet & Scott R. Turner\\ -Dion Nicolaas & Lars Huttar & Sean Hunt\\ -Dylan O'Donnell & Leon Arnott & Stephen Spackman\\ -Eric Backus & M. Drew Streib & Stefan Thielscher\\ -Eric Hendrickson & Malcolm Ryan & Stephen White\\ -Eric R. Smith & Mark Gooderum & Steve Creps\\ -Eric S. Raymond & Mark Modrall & Steve Linhart\\ -Erik Andersen & Marvin Bressler & Steve VanDevender\\ -Fredrik Ljungdahl & Matthew Day & Teemu Suikki\\ -Frederick Roeber & Merlyn LeRoy & Tim Lennan\\ -Gil Neiger & Michael Allison & Timo Hakulinen\\ -Greg Laskin & Michael Feir & Tom Almy\\ -Greg Olson & Michael Hamel & Tom West\\ -Gregg Wonderly & Michael Sokolov & Warren Cheung\\ -Hao-yang Wang & Mike Engber & Warwick Allison\\ -Helge Hafting & Mike Gallop & Yitzhak Sapir\\ -Irina Rempt-Drijfhout & Mike Passaretti\\ -Izchak Miller & Mike Stephenson +Adam Aronow & Irina Rempt-Drijfhout & Mike Gallop\\ +Alex Kompel & Izchak Miller & Mike Passaretti\\ +Alex Smith & J. Ali Harlow & Mike Stephenson\\ +Andreas Dorn & Janet Walz & Mikko Juola\\ +Andy Church & Janne Salmij\"{a}rvi & Nathan Eady\\ +Andy Swanson & Jean-Christophe Collet & Norm Meluch\\ +Andy Thomson & Jeff Bailey & Olaf Seibert\\ +Ari Huttunen & Jochen Erwied & Pasi Kallinen\\ +Bart House & John Kallen & Pat Rankin\\ +Benson I. Margulies & John Rupley & Patric Mueller\\ +Bill Dyer & John S. Bien & Paul Winner\\ +Boudewijn Waijers & Johnny Lee & Pierre Martineau\\ +Bruce Cox & Jon W\{tte & Ralf Brown\\ +Bruce Holloway & Jonathan Handler & Ray Chason\\ +Bruce Mewborne & Joshua Delahunty & Richard Addison\\ +Cameron Root & Karl Garrison & Richard Beigel\\ +Carl Schelin & Keizo Yamamoto & Richard P. Hughey\\ +Chris Russo & Keith Simpson & Rob Menke\\ +David Cohrs & Ken Arnold & Robin Bandy\\ +David Damerell & Ken Arromdee & Robin Johnson\\ +David Gentzel & Ken Lorber & Roderick Schertler\\ +David Hairston & Ken Washikita & Roland McGrath\\ +Dean Luick & Kestrel Gregorich-Trevor & Ron Van Iwaarden\\ +Del Lamb & Kevin Darcy & Ronnen Miller\\ +Derek S. Ray & Kevin Hugo & Ross Brown\\ +Deron Meranda & Kevin Sitze & Sascha Wostmann\\ +Dion Nicolaas & Kevin Smolkowski & Scott Bigham\\ +Dylan O'Donnell & Kevin Sweet & Scott R. Turner\\ +Eric Backus & Lars Huttar & Sean Hunt\\ +Eric Hendrickson & Leon Arnott & Stephen Spackman\\ +Eric R. Smith & M. Drew Streib & Stefan Thielscher\\ +Eric S. Raymond & Malcolm Ryan & Stephen White\\ +Erik Andersen & Mark Gooderum & Steve Creps\\ +Fredrik Ljungdahl & Mark Modrall & Steve Linhart\\ +Frederick Roeber & Marvin Bressler & Steve VanDevender\\ +G. Branden Robinson & Matthew Day & Teemu Suikki\\ +Gil Neiger & Merlyn LeRoy & Tim Lennan\\ +Greg Laskin & Michael Allison & Timo Hakulinen\\ +Greg Olson & Michael Feir & Tom Almy\\ +Gregg Wonderly & Michael Hamel & Tom West\\ +Hao-yang Wang & Michael Meyer & Warren Cheung\\ +Helge Hafting & Michael Sokolov & Warwick Allison\\ +Ingo Paschke & Mike Engber & Yitzhak Sapir %TABLE_END Do not delete this line. \end{tabular} \end{center} diff --git a/doc/Guidebook.txt b/doc/Guidebook.txt index d9c5287b7..1d85d895d 100644 --- a/doc/Guidebook.txt +++ b/doc/Guidebook.txt @@ -8,244 +8,234 @@ - A Guide to the Mazes of Menace - (Guidebook for NetHack) + A Guide to the Mazes of Menace + (Guidebook for NetHack) - Original version - Eric S. Raymond - (Edited and expanded for 3.6 by Mike Stephenson and others) + Original version - Eric S. Raymond + (Edited and expanded for NetHack 5.0.0 by Mike Stephenson and others) - February 3, 2023 + May 2, 2026 - 1. Introduction + 1. Introduction - Recently, you have begun to find yourself unfulfilled and - distant in your daily occupation. Strange dreams of prospecting, - stealing, crusading, and combat have haunted you in your sleep - for many months, but you aren't sure of the reason. You wonder - whether you have in fact been having those dreams all your life, - and somehow managed to forget about them until now. Some nights - you awaken suddenly and cry out, terrified at the vivid recollec- - tion of the strange and powerful creatures that seem to be lurk- - ing behind every corner of the dungeon in your dream. Could - these details haunting your dreams be real? As each night pass- - es, you feel the desire to enter the mysterious caverns near the - ruins grow stronger. Each morning, however, you quickly put the - idea out of your head as you recall the tales of those who en- - tered the caverns before you and did not return. Eventually you - can resist the yearning to seek out the fantastic place in your - dreams no longer. After all, when other adventurers came back - this way after spending time in the caverns, they usually seemed - better off than when they passed through the first time. And who - was to say that all of those who did not return had not just kept - going? + Recently, you have begun to find yourself unfulfilled and distant + in your daily occupation. Strange dreams of prospecting, stealing, + crusading, and combat have haunted you in your sleep for many months, + but you aren't sure of the reason. You wonder whether you have in + fact been having those dreams all your life, and somehow managed to + forget about them until now. Some nights you awaken suddenly and cry + out, terrified at the vivid recollection of the strange and powerful + creatures that seem to be lurking behind every corner of the dungeon + in your dream. Could these details haunting your dreams be real? As + each night passes, you feel the desire to enter the mysterious caverns + near the ruins grow stronger. Each morning, however, you quickly put + the idea out of your head as you recall the tales of those who entered + the caverns before you and did not return. Eventually you can resist + the yearning to seek out the fantastic place in your dreams no longer. + After all, when other adventurers came back this way after spending + time in the caverns, they usually seemed better off than when they + passed through the first time. And who was to say that all of those + who did not return had not just kept going? - Asking around, you hear about a bauble, called the Amulet of - Yendor by some, which, if you can find it, will bring you great - wealth. One legend you were told even mentioned that the one who - finds the amulet will be granted immortality by the gods. The - amulet is rumored to be somewhere beyond the Valley of Gehennom, - deep within the Mazes of Menace. Upon hearing the legends, you - immediately realize that there is some profound and undiscovered - reason that you are to descend into the caverns and seek out that - amulet of which they spoke. Even if the rumors of the amulet's - powers are untrue, you decide that you should at least be able to - sell the tales of your adventures to the local minstrels for a - tidy sum, especially if you encounter any of the terrifying and - magical creatures of your dreams along the way. You spend one - last night fortifying yourself at the local inn, becoming more - and more depressed as you watch the odds of your success being - posted on the inn's walls getting lower and lower. + Asking around, you hear about a bauble, called the Amulet of Yen- + dor by some, which, if you can find it, will bring you great wealth. + One legend you were told even mentioned that the one who finds the + amulet will be granted immortality by the gods. The amulet is rumored + to be somewhere beyond the Valley of Gehennom, deep within the Mazes + of Menace. Upon hearing the legends, you immediately realize that + there is some profound and undiscovered reason that you are to descend + into the caverns and seek out that amulet of which they spoke. Even + if the rumors of the amulet's powers are untrue, you decide that you + should at least be able to sell the tales of your adventures to the + local minstrels for a tidy sum, especially if you encounter any of the + terrifying and magical creatures of your dreams along the way. You + spend one last night fortifying yourself at the local inn, becoming + more and more depressed as you watch the odds of your success being + posted on the inn's walls getting lower and lower. + In the morning you awake, collect your belongings, and set off + for the dungeon. After several days of uneventful travel, you see the - NetHack Guidebook 1 + NetHack Guidebook 1 - NetHack Guidebook 2 + NetHack Guidebook 2 - In the morning you awake, collect your belongings, and set - off for the dungeon. After several days of uneventful travel, - you see the ancient ruins that mark the entrance to the Mazes of - Menace. It is late at night, so you make camp at the entrance - and spend the night sleeping under the open skies. In the morn- - ing, you gather your gear, eat what may be your last meal out- - side, and enter the dungeon... - 2. What is going on here? + ancient ruins that mark the entrance to the Mazes of Menace. It is + late at night, so you make camp at the entrance and spend the night + sleeping under the open skies. In the morning, you gather your gear, + eat what may be your last meal outside, and enter the dungeon.... - You have just begun a game of NetHack. Your goal is to grab - as much treasure as you can, retrieve the Amulet of Yendor, and - escape the Mazes of Menace alive. + 2. What is going on here? - Your abilities and strengths for dealing with the hazards of - adventure will vary with your background and training: + You have just begun a game of NetHack. Your goal is to grab as + much treasure as you can, retrieve the Amulet of Yendor, and escape + the Mazes of Menace alive. - Archeologists understand dungeons pretty well; this enables - them to move quickly and sneak up on the local nasties. They - start equipped with the tools for a proper scientific expedition. + Your abilities and strengths for dealing with the hazards of + adventure will vary with your background and training: - Barbarians are warriors out of the hinterland, hardened to - battle. They begin their quests with naught but uncommon - strength, a trusty hauberk, and a great two-handed sword. + Archeologists understand dungeons pretty well; this enables them + to move quickly and sneak up on the local nasties. They start + equipped with the tools for a proper scientific expedition, and are + able to read ancient languages. - Cavemen and Cavewomen start with exceptional strength but, - unfortunately, with neolithic weapons. + Barbarians are warriors out of the hinterland, hardened to bat- + tle. They begin their quests with naught but uncommon strength, a + trusty hauberk, and a great two-handed sword. - Healers are wise in medicine and apothecary. They know the - herbs and simples that can restore vitality, ease pain, anes- - thetize, and neutralize poisons; and with their instruments, they - can divine a being's state of health or sickness. Their medical - practice earns them quite reasonable amounts of money, with which - they enter the dungeon. + Cavemen and Cavewomen start with exceptional strength but, unfor- + tunately, with neolithic weapons. - Knights are distinguished from the common skirmisher by - their devotion to the ideals of chivalry and by the surpassing - excellence of their armor. + Healers are wise in medicine and apothecary. They know the herbs + and simples that can restore vitality, ease pain, anesthetize, and + neutralize poisons; and with their instruments, they can divine a + being's state of health or sickness. Their medical practice earns + them quite reasonable amounts of money, with which they enter the dun- + geon. - Monks are ascetics, who by rigorous practice of physical and - mental disciplines have become capable of fighting as effectively - without weapons as with. They wear no armor but make up for it - with increased mobility. + Knights are distinguished from the common skirmisher by their + devotion to the ideals of chivalry and by the surpassing excellence of + their armor. - Priests and Priestesses are clerics militant, crusaders ad- - vancing the cause of righteousness with arms, armor, and arts - thaumaturgic. Their ability to commune with deities via prayer - occasionally extricates them from peril, but can also put them in - it. + Monks are ascetics, who by rigorous practice of physical and men- + tal disciplines have become capable of fighting as effectively without + weapons as with. They wear no armor but make up for it with increased + mobility. - Rangers are most at home in the woods, and some say slightly - out of place in a dungeon. They are, however, experts in archery - as well as tracking and stealthy movement. + Priests and Priestesses are clerics militant, crusaders advancing + the cause of righteousness with arms, armor, and arts thaumaturgic. + Their ability to commune with deities via prayer occasionally extri- + cates them from peril, but can also put them in it. + Rangers are most at home in the woods, and some say slightly out + of place in a dungeon. They are, however, experts in archery as well + as tracking and stealthy movement. + Rogues are agile and stealthy thieves, with knowledge of locks, + traps, and poisons. Their advantage lies in surprise, which they + employ to great advantage. - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 3 + NetHack Guidebook 3 - Rogues are agile and stealthy thieves, with knowledge of - locks, traps, and poisons. Their advantage lies in surprise, - which they employ to great advantage. - Samurai are the elite warriors of feudal Nippon. They are - lightly armored and quick, and wear the dai-sho, two swords of - the deadliest keenness. + Samurai are the elite warriors of feudal Nippon. They are + lightly armored and quick, and wear the dai-sho, two swords of the + deadliest keenness. - Tourists start out with lots of gold (suitable for shopping - with), a credit card, lots of food, some maps, and an expensive - camera. Most monsters don't like being photographed. + Tourists start out with lots of gold (suitable for shopping + with), a credit card, lots of food, some maps, and an expensive cam- + era. Most monsters don't like being photographed. - Valkyries are hardy warrior women. Their upbringing in the - harsh Northlands makes them strong, inures them to extremes of - cold, and instills in them stealth and cunning. + Valkyries are hardy warrior women. Their upbringing in the harsh + Northlands makes them strong, inures them to extremes of cold, and + instills in them stealth and cunning. - Wizards start out with a knowledge of magic, a selection of - magical items, and a particular affinity for dweomercraft. Al- - though seemingly weak and easy to overcome at first sight, an ex- - perienced Wizard is a deadly foe. + Wizards start out with a knowledge of magic, a selection of magi- + cal items, and a particular affinity for dweomercraft. Although seem- + ingly weak and easy to overcome at first sight, an experienced Wizard + is a deadly foe. - You may also choose the race of your character (within lim- - its; most roles have restrictions on which races are eligible for - them): + You may also choose the race of your character (within limits; + most roles have restrictions on which races are eligible for them): - Dwarves are smaller than humans or elves, but are stocky and - solid individuals. Dwarves' most notable trait is their great - expertise in mining and metalwork. Dwarvish armor is said to be - second in quality not even to the mithril armor of the Elves. + Dwarves are smaller than humans or elves, but are stocky and + solid individuals. Dwarves' most notable trait is their great exper- + tise in mining and metalwork. Dwarvish armor is said to be second in + quality not even to the mithril armor of the Elves. - Elves are agile, quick, and perceptive; very little of what - goes on will escape an Elf. The quality of Elven craftsmanship - often gives them an advantage in arms and armor. + Elves are agile, quick, and perceptive; very little of what goes + on will escape an Elf. The quality of Elven craftsmanship often gives + them an advantage in arms and armor. - Gnomes are smaller than but generally similar to dwarves. - Gnomes are known to be expert miners, and it is known that a se- - cret underground mine complex built by this race exists within - the Mazes of Menace, filled with both riches and danger. + Gnomes are smaller than but generally similar to dwarves. Gnomes + are known to be expert miners, and it is known that a secret under- + ground mine complex built by this race exists within the Mazes of Men- + ace, filled with both riches and danger. - Humans are by far the most common race of the surface world, - and are thus the norm to which other races are often compared. - Although they have no special abilities, they can succeed in any - role. + Humans are by far the most common race of the surface world, and + are thus the norm to which other races are often compared. Although + they have no special abilities, they can succeed in any role. - Orcs are a cruel and barbaric race that hate every living - thing (including other orcs). Above all others, Orcs hate Elves - with a passion unequalled, and will go out of their way to kill - one at any opportunity. The armor and weapons fashioned by the - Orcs are typically of inferior quality. + Orcs are a cruel and barbaric race that hate every living thing + (including other orcs). Above all others, Orcs hate Elves with a pas- + sion unequalled, and will go out of their way to kill one at any + opportunity. The armor and weapons fashioned by the Orcs are typi- + cally of inferior quality. - 3. What do all those things on the screen mean? + 3. What do all those things on the screen mean? - On the screen is kept a map of where you have been and what - you have seen on the current dungeon level; as you explore more + On the screen is kept a map of where you have been and what you + have seen on the current dungeon level; as you explore more of the + level, it appears on the screen in front of you. + When NetHack's ancestor rogue first appeared, its screen orienta- + tion was almost unique among computer fantasy games. Since then, + screen orientation has become the norm rather than the exception; + NetHack continues this fine tradition. Unlike text adventure games - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 4 + NetHack Guidebook 4 - of the level, it appears on the screen in front of you. - When NetHack's ancestor rogue first appeared, its screen - orientation was almost unique among computer fantasy games. - Since then, screen orientation has become the norm rather than - the exception; NetHack continues this fine tradition. Unlike - text adventure games that accept commands in pseudo-English sen- - tences and explain the results in words, NetHack commands are all - one or two keystrokes and the results are displayed graphically - on the screen. A minimum screen size of 24 lines by 80 columns - is recommended; if the screen is larger, only a 21x80 section - will be used for the map. + that accept commands in pseudo-English sentences and explain the + results in words, NetHack commands are all one or two keystrokes and + the results are displayed graphically on the screen. A minimum screen + size of 24 lines by 80 columns is recommended; if the screen is + larger, only a 21x80 section will be used for the map. - NetHack can even be played by blind players, with the assis- - tance of Braille readers or speech synthesisers. Instructions - for configuring NetHack for the blind are included later in this - document. + NetHack can even be played by blind players, with the assistance + of Braille readers or speech synthesisers. Instructions for configur- + ing NetHack for the blind are included later in this document. - NetHack generates a new dungeon every time you play it; even - the authors still find it an entertaining and exciting game de- - spite having won several times. + NetHack generates a new dungeon every time you play it; even the + authors still find it an entertaining and exciting game despite having + won several times. - NetHack offers a variety of display options. The options - available to you will vary from port to port, depending on the - capabilities of your hardware and software, and whether various - compile-time options were enabled when your executable was creat- - ed. The three possible display options are: a monochrome charac- - ter interface, a color character interface, and a graphical in- - terface using small pictures called tiles. The two character in- - terfaces allow fonts with other characters to be substituted, but - the default assignments use standard ASCII characters to repre- - sent everything. There is no difference between the various dis- - play options with respect to game play. Because we cannot repro- - duce the tiles or colors in the Guidebook, and because it is com- - mon to all ports, we will use the default ASCII characters from - the monochrome character display when referring to things you - might see on the screen during your game. + NetHack offers a variety of display options. The options avail- + able to you will vary from port to port, depending on the capabilities + of your hardware and software, and whether various compile-time + options were enabled when your executable was created. The three pos- + sible display options are: a monochrome character interface, a color + character interface, and a graphical interface using small pictures + called tiles. The two character interfaces allow fonts with other + characters to be substituted, but the default assignments use standard + ASCII characters to represent everything. There is no difference + between the various display options with respect to game play. + Because we cannot reproduce the tiles or colors in the Guidebook, and + because it is common to all ports, we will use the default ASCII char- + acters from the monochrome character display when referring to things + you might see on the screen during your game. - In order to understand what is going on in NetHack, first - you must understand what NetHack is doing with the screen. The - NetHack screen replaces the "You see ..." descriptions of text - adventure games. Figure 1 is a sample of what a NetHack screen - might look like. The way the screen looks for you depends on - your platform. + In order to understand what is going on in NetHack, first you + must understand what NetHack is doing with the screen. The NetHack + screen replaces the "You see ..." descriptions of text adventure + games. Figure 1 is a sample of what a NetHack screen might look like. + The way the screen looks for you depends on your platform. @@ -258,5881 +248,7607 @@ - NetHack 3.6 February 3, 2023 - NetHack Guidebook 5 + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 5 + + + + +---------------------------------------------------------------+ + |The bat bites! | + | | + | ------ | + | |....| ---------- | + | |.<..|####...@...$.| | + | |....-# |...B....+ | + | |....| |.d......| | + | ------ -------|-- | + | | + | | + | | + |Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral | + |Dlvl:1 $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:752 Hungry Conf | + +---------------------------Figure-1----------------------------+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 6 + + + + +---------------------------------------------------------------+ + |Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 | + |Neutral $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 Hungry | + |Dlvl:1 T:752 Conf | + +---------------------------Figure-2----------------------------+ + + 3.1. The status lines (bottom) + + The bottom two (or three) lines of the screen contain several + cryptic pieces of information describing your current status. Figure + 1 shows the traditional two-line status area below the map. Figure 2 + shows just the status area, when the statuslines:3 option has been set + (not all interfaces support this option). If any status line becomes + wider than the screen, you might not see all of it due to truncation. + When the numbers grow bigger and multiple conditions are present, the + two-line format will run out of room on the second line, but sta- + tuslines:2 is the default because a basic 24-line terminal isn't tall + enough for the third line. + + Here are explanations of what the various status items mean: + + Title + Your character's name and professional ranking (based on role and + experience level, see below). + + Strength + A measure of your character's strength; one of your six basic + attributes. A human character's attributes can range from 3 to + 18 inclusive; non-humans may exceed these limits (occasionally + you may get super-strengths of the form 18/xx, and magic can also + cause attributes to exceed the normal limits). The higher your + strength, the stronger you are. Strength affects how success- + fully you perform physical tasks, how much damage you do in com- + bat, and how much loot you can carry. + + Dexterity + Dexterity affects your chances to hit in combat, to avoid traps, + and do other tasks requiring agility or manipulation of objects. + + Constitution + Constitution affects your ability to recover from injuries and + other strains on your stamina. When strength is low or modest, + constitution also affects how much you can carry. With suffi- + ciently high strength, the contribution to carrying capacity from + your constitution no longer matters. + + Intelligence + Intelligence affects your ability to cast spells and read spell- + books. + + Wisdom + Wisdom comes from your practical experience (especially when + dealing with magic). It affects your magical energy. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 7 + + + + Charisma + Charisma affects how certain creatures react toward you. In par- + ticular, it can affect the prices shopkeepers offer you. + + Alignment + Lawful, Neutral, or Chaotic. Often, Lawful is taken as good and + Chaotic as evil, but legal and ethical do not always coincide. + Your alignment influences how other monsters react toward you. + Monsters of a like alignment are more likely to be non-aggres- + sive, while those of an opposing alignment are more likely to be + seriously offended at your presence. + + Dungeon Level + How deep you are in the dungeon. You start at level one and the + number increases as you go deeper into the dungeon. Some levels + are special, and are identified by a name and not a number. The + Amulet of Yendor is reputed to be somewhere beneath the twentieth + level. + + Gold + The number of gold pieces you are openly carrying. Gold which + you have concealed in containers is not counted. + + Hit Points + Your current and maximum hit points. Hit points indicate how + much damage you can take before you die. The more you get hit in + a fight, the lower they get. You can regain hit points by rest- + ing, or by using certain magical items or spells. The number in + parentheses is the maximum number your hit points can reach. + + Power + Spell points. This tells you how much mystic energy (mana) you + have available for spell casting. Again, resting will regenerate + the amount available. + + Armor Class + A measure of how effectively your armor stops blows from + unfriendly creatures. The lower this number is, the more effec- + tive the armor; it is quite possible to have negative armor + class. See the Armor subsection of Objects for more information. + + Experience + Your current experience level. If the showexp option is set, it + will be followed by a slash and experience points. As you adven- + ture, you gain experience points. At certain experience point + totals, you gain an experience level. The more experienced you + are, the better you fight and withstand magical attacks. (By the + time your level reaches double digits, the usefulness of showing + the points with it has dropped significantly. You can use the + `O' command to turn showexp off to avoid using up the limited + status line space.) + + Time + The number of turns elapsed so far, displayed if you have the + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 8 + + + + time option set. + + Status + Hunger: your current hunger status. Values are Satiated, Not + Hungry (or Normal), Hungry, Weak, and Fainting. Not shown when + Normal. + + Encumbrance: an indication of how what you are carrying affects + your ability to move. Values are Unencumbered, Burdened, + Stressed, Strained, Overtaxed, and Overloaded. Not shown when + Unencumbered. + + Fatal conditions: Stone (aka Petrifying, turning to stone), Slime + (turning into green slime), Strngl (being strangled), FoodPois + (suffering from acute food poisoning), TermIll (suffering from a + terminal illness). + + Non-fatal conditions: Blind (can't see), Deaf (can't hear), Stun + (stunned), Conf (confused), Hallu (hallucinating). + + Movement modifiers: Lev (levitating), Fly (flying), Ride (rid- + ing). + + Other conditions and modifiers exist, but there isn't enough room + to display them with the other status fields. + + The #attributes command (default key ^X) will show all current status + information in unabbreviated format. It also shows other information + which might be included on the status lines if those had more room. + + 3.2. The message line (top) + + The top line of the screen is reserved for messages that describe + things that are impossible to represent visually. If you see a + "--More--" on the top line, this means that NetHack has another mes- + sage to display on the screen, but it wants to make certain that + you've read the one that is there first. To read the next message, + just press the space bar. + + To change how and what messages are shown on the message line, + see "Configuring Message Types" and the verbose option. + + 3.3. The map (rest of the screen) + + The rest of the screen is the map of the level as you have + explored it so far. Each symbol on the screen represents something. + You can set various graphics options to change some of the symbols the + game uses; otherwise, the game will use default symbols. Here is a + list of what the default symbols mean: + + - The horizontal or corner walls of a room, or an open east/west + door. + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 9 + + + + | The vertical walls of a room, or an open north/south door, or a + grave. + + . The floor of a room, or ice, or a doorless doorway, or the span + of an open drawbridge. + + # A corridor, or iron bars, or a tree, or the portcullis of a + closed drawbridge. + + Note: engravings in corridors also appear as # but are shown in a + different color from normal corridor locations. + + > Stairs down: a way to the next level. + + < Stairs up: a way to the previous level. + + + A closed door, or a spellbook containing a spell you may be able + to learn. + + @ Your character or a human or an elf. + + $ A pile of gold. + + ^ A trap (once you have detected it). + + ) A weapon. + + [ A suit or piece of armor. + + % Something edible (not necessarily healthy). + + ? A scroll. + + / A wand. + + = A ring. + + ! A potion. + + ( A useful item (pick-axe, key, lamp...). + + " An amulet or a spider web. + + * A gem or rock (possibly valuable, possibly worthless). + + ` A boulder or statue or an engraving on the floor of a room. + + Note: statues are displayed as if they were the monsters they + depict so won't appear as a grave accent (aka back-tick). + + 0 An iron ball. + + _ An altar, or an iron chain. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 10 + + + + { A fountain or a sink. + + } A pool of water or moat or a wall of water or a pool of lava or a + wall of lava. + + \ An opulent throne. + + a-z and + + A-HJ-Z and + + @&':; + Letters and certain other symbols represent the various inhabi- + tants of the Mazes of Menace. Watch out, they can be nasty and + vicious. Sometimes, however, they can be helpful. + + I Rather than a specific type of monster, this marks the last known + location of an invisible or otherwise unseen monster. Note that + the monster could have moved. The `s', `F', and `m' commands may + be useful here. + + 1-5 The digits 1 through 5 may be displayed, marking unseen monsters + sensed via the Warning attribute. Less dangerous monsters are + indicated by lower values, more dangerous by higher values. + + You need not memorize all these symbols; you can ask the game + what any symbol represents with the `/' command (see the next section + for more info). + + 4. Commands + + Commands can be initiated by typing one or two characters to + which the command is bound to, or typing the command name in the + extended commands entry. Some commands, like "search", do not require + that any more information be collected by NetHack. Other commands + might require additional information, for example a direction, or an + object to be used. For those commands that require additional infor- + mation, NetHack will present you with either a menu of choices or with + a command line prompt requesting information. Which you are presented + with will depend chiefly on how you have set the menustyle option. + + For example, a common question, in the form "What do you want to + use? [a-zA-Z ?*]", asks you to choose an object you are carrying. + Here, "a-zA-Z" are the inventory letters of your possible choices. + Typing `?' gives you an inventory list of these items, so you can see + what each letter refers to. In this example, there is also a `*' + indicating that you may choose an object not on the list, if you + wanted to use something unexpected. Typing a `*' lists your entire + inventory, so you can see the inventory letters of every object you're + carrying. Finally, if you change your mind and decide you don't want + to do this command after all, you can press the ESC key to abort the + command. + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 11 + + + + You can put a number before some commands to repeat them that + many times; for example, "10s" will search ten times. If you have the + number_pad option set, you must type `n' to prefix a count, so the + example above would be typed "n10s" instead. Commands for which + counts make no sense ignore them. In addition, movement commands can + be prefixed for greater control (see below). To cancel a count or a + prefix, press the ESC key. + + The list of commands is rather long, but it can be read at any + time during the game through the `?' command, which accesses a menu of + helpful texts. Here are the default key bindings for your reference: + + ? Help menu: display one of several help texts available. + + / The "whatis" command, to tell what a symbol represents. You may + choose to specify a location or type a symbol (or even a whole + word) to explain. Specifying a location is done by moving the + cursor to a particular spot on the map and then pressing one of + `.', `,', `;', or `:'. `.' will explain the symbol at the chosen + location, conditionally check for "More info?" depending upon + whether the help option is on, and then you will be asked to pick + another location; `,' will explain the symbol but skip any addi- + tional information, then let you pick another location; `;' will + skip additional info and also not bother asking you to choose + another location to examine; `:' will show additional info, if + any, without asking for confirmation. When picking a location, + pressing the ESC key will terminate this command, or pressing `?' + will give a brief reminder about how it works. + + If the autodescribe option is on, a short description of what you + see at each location is shown as you move the cursor. Typing `#' + while picking a location will toggle that option on or off. The + whatis_coord option controls whether the short description + includes map coordinates. + + Specifying a name rather than a location always gives any addi- + tional information available about that name. + + You may also request a description of nearby monsters, all mon- + sters currently displayed, nearby objects, or all objects. The + whatis_coord option controls which format of map coordinate is + included with their descriptions. + + & Tell what a command does. + + < Go up to the previous level (if you are on a staircase or lad- + der). + + > Go down to the next level (if you are on a staircase or ladder). + + [yuhjklbn] + Go one step in the direction indicated (see Figure 3). If you + sense or remember a monster there, you will fight the monster + instead. Only these one-step movement commands cause you to + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 12 + + + + fight monsters; the others (below) are "safe." +----------------------------------------------------------------+ - |The bat bites! | - | | - | ------ | - | |....| ---------- | - | |.<..|####...@...$.| | - | |....-# |...B....+ | - | |....| |.d......| | - | ------ -------|-- | - | | - | | - | | - |Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 Neutral | - |Dlvl:1 $:0 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:257 Weak | - +---------------------------Figure-1-----------------------------+ - - 3.1. The status lines (bottom) - - The bottom two lines of the screen contain several cryptic - pieces of information describing your current status. If either - status line becomes longer than the width of the screen, you - might not see all of it. Here are explanations of what the vari- - ous status items mean (though your configuration may not have all - the status items listed below): - - Rank - Your character's name and professional ranking (based on the - experience level, see below). + | y k u 7 8 9 | + | \ | / \ | / | + | h- . -l 4- . -6 | + | / | \ / | \ | + | b j n 1 2 3 | + | (number_pad off) (number_pad on) | + +---------------------------Figure-3-----------------------------+ + + [YUHJKLBN] + Go in that direction until you hit a wall or run into something. - Strength - A measure of your character's strength; one of your six ba- - sic attributes. A human character's attributes can range - from 3 to 18 inclusive; non-humans may exceed these limits - (occasionally you may get super-strengths of the form 18/xx, - and magic can also cause attributes to exceed the normal - limits). The higher your strength, the stronger you are. - Strength affects how successfully you perform physical - tasks, how much damage you do in combat, and how much loot - you can carry. + m[yuhjklbn] + Prefix: move without picking up objects or fighting (even if you + remember a monster there). - Dexterity - Dexterity affects your chances to hit in combat, to avoid - traps, and do other tasks requiring agility or manipulation - of objects. + A few non-movement commands use the `m' prefix to request operat- + ing via menu (to temporarily override the menustyle:traditional + option). Primarily useful for `,' (pickup) when there is only + one class of objects present (where there won't be any "what + kinds of objects?" prompt, so no opportunity to answer `m' at + that prompt). - Constitution - Constitution affects your ability to recover from injuries - and other strains on your stamina. When strength is low or - modest, constitution also affects how much you can carry. - With sufficiently high strength, the contribution to carry- - ing capacity from your constitution no longer matters. + The prefix will make "#travel" command show a menu of interesting + targets in sight. It can also be used with the `\' (known, show + a list of all discovered objects) and the ``' (knownclass, show a + list of discovered objects in a particular class) commands to + offer a menu of several sorting alternatives (which sets a new + value for the sortdiscoveries option); also for "#vanquished" and + "#genocided" commands to offer a sorting menu. - Intelligence - Intelligence affects your ability to cast spells and read + A few other commands (eat food, offer sacrifice, apply tinning- + kit, drink/quaff, dip, tip container) use the `m' prefix to skip + checking for applicable objects on the floor and go straight to + checking inventory, or (for "#loot" to remove a saddle), skip + containers and go straight to adjacent monsters. + In debug mode (aka "wizard mode"), the `m' prefix may also be + used with the "#teleport" and "#wizlevelport" commands. - NetHack 3.6 February 3, 2023 + F[yuhjklbn] + Prefix: fight a monster (even if you only guess one is there). + g[yuhjklbn] + Prefix: move until something interesting is found. + G[yuhjklbn] or +[yuhjklbn] + Prefix: similar to `g', but forking of corridors is not consid- + ered interesting. + Note: + means holding the or key + down like while typing and releasing , then releas- + ing . ^ is used as shorthand elsewhere in the - NetHack Guidebook 6 + NetHack 5.0.0 May 2, 2026 - spellbooks. - Wisdom - Wisdom comes from your practical experience (especially when - dealing with magic). It affects your magical energy. - Charisma - Charisma affects how certain creatures react toward you. In - particular, it can affect the prices shopkeepers offer you. + NetHack Guidebook 13 - Alignment - Lawful, Neutral, or Chaotic. Often, Lawful is taken as good - and Chaotic as evil, but legal and ethical do not always co- - incide. Your alignment influences how other monsters react - toward you. Monsters of a like alignment are more likely to - be non-aggressive, while those of an opposing alignment are - more likely to be seriously offended at your presence. - Dungeon Level - How deep you are in the dungeon. You start at level one and - the number increases as you go deeper into the dungeon. - Some levels are special, and are identified by a name and - not a number. The Amulet of Yendor is reputed to be some- - where beneath the twentieth level. - Gold - The number of gold pieces you are openly carrying. Gold - which you have concealed in containers is not counted. + Guidebook to mean the same thing. Control characters are case- + insensitive so ^x and ^X are the same. - Hit Points - Your current and maximum hit points. Hit points indicate - how much damage you can take before you die. The more you - get hit in a fight, the lower they get. You can regain hit - points by resting, or by using certain magical items or - spells. The number in parentheses is the maximum number - your hit points can reach. + M[yuhjklbn] + Old versions supported `M' as a movement prefix which combined + the effect of `m' with +. That is no longer + supported as a prefix but similar effect can be achieved by using + `m' and G in combination. m can also be used in com- + bination with g, +, or + +. - Power - Spell points. This tells you how much mystic energy (mana) - you have available for spell casting. Again, resting will - regenerate the amount available. + _ Travel to a map location via a shortest-path algorithm. - Armor Class - A measure of how effectively your armor stops blows from un- - friendly creatures. The lower this number is, the more ef- - fective the armor; it is quite possible to have negative ar- - mor class. + The shortest path is computed over map locations the hero knows + about (e.g. seen or previously traversed). If there is no known + path, a guess is made instead. Stops on most of the same condi- + tions as the `G' prefix, but without picking up objects, so + implicitly forces the `m' prefix. For ports with mouse support, + the command is also invoked when a mouse-click takes place on a + location other than the current position. - Experience - Your current experience level and experience points. As you - adventure, you gain experience points. At certain experi- - ence point totals, you gain an experience level. The more - experienced you are, the better you fight and withstand mag- - ical attacks. Many dungeons show only your experience level + . Wait or rest, do nothing for one turn. Precede with the `m' pre- + fix to wait for a turn even next to a hostile monster, if + safe_wait is on. + a Apply (use) a tool (pick-axe, key, lamp...). - NetHack 3.6 February 3, 2023 + If used on a wand, that wand will be broken, releasing its magic + in the process. Confirmation is required. + A Remove one or more worn items, such as armor. + Use `T' (take off) to take off only one piece of armor or `R' + (remove) to take off only one accessory. + ^A Repeat the previous command. + c Close a door. - NetHack Guidebook 7 + C Call (name) a monster, an individual object, or a type of object. + Same as extended command "#name". + ^C Panic button. Quit the game. - here. + d Drop something. - Time - The number of turns elapsed so far, displayed if you have - the time option set. + For example "d7a" means drop seven items of object a. - Status - Hunger: your current hunger status. Values are Satiated, - Not Hungry (or Normal), Hungry, Weak, and Fainting. Not - shown when Normal. + D Drop several things. - Encumbrance: an indication of how what you are carrying af- - fects your ability to move. Values are Unencumbered, Encum- - bered, Stressed, Strained, Overtaxed, and Overloaded. Not - shown when Unencumbered. + In answer to the question - Fatal conditions: Stone (aka Petrifying, turning to stone), - Slime (turning into green slime), Strngl (being strangled), - FoodPois (suffering from acute food poisoning), TermIll - (suffering from a terminal illness). - Non-fatal conditions: Blind (can't see), Deaf (can't hear), - Stun (stunned), Conf (confused), Hallu (hallucinating). - Movement modifiers: Lev (levitating), Fly (flying), Ride - (riding). - Other conditions and modifiers exist, but there isn't enough - room to display them with the other status fields. The `^X' - command shows all relevant status conditions. + NetHack 5.0.0 May 2, 2026 - 3.2. The message line (top) - The top line of the screen is reserved for messages that de- - scribe things that are impossible to represent visually. If you - see a "--More--" on the top line, this means that NetHack has an- - other message to display on the screen, but it wants to make cer- - tain that you've read the one that is there first. To read the - next message, just press the space bar. - To change how and what messages are shown on the message - line, see "Configuring Message Types" and the verbose option. - 3.3. The map (rest of the screen) - The rest of the screen is the map of the level as you have - explored it so far. Each symbol on the screen represents some- - thing. You can set various graphics options to change some of - the symbols the game uses; otherwise, the game will use default - symbols. Here is a list of what the default symbols mean: + NetHack Guidebook 14 - - and | - The walls of a room, or an open door. Or a grave (|). + "What kinds of things do you want to drop? [!%= BUCXPaium]" - NetHack 3.6 February 3, 2023 + you should type zero or more object symbols possibly followed by + `a' and/or `i' and/or `u' and/or `m'. In addition, one or more + of the blessed/uncursed/cursed groups may be typed. + DB - drop all objects known to be blessed. + DU - drop all objects known to be uncursed. + DC - drop all objects known to be cursed. + DX - drop all objects of unknown B/U/C status. + DP - drop objects picked up last. + Da - drop all objects, without asking for confirmation. + Di - examine your inventory before dropping anything. + Du - drop only unpaid objects (when in a shop). + Dm - use a menu to pick which object(s) to drop. + D%u - drop only unpaid food. + The last example shows a combination. There are four categories + of object filtering: class (`!' for potions, `?' for scrolls, and + so on), shop status (`u' for unpaid, in other words, owned by the + shop), bless/curse state (`B', `U', `C', and `X' as shown above), + and novelty (`P', recently picked up items; controlled by picking + up or dropping things rather than by any time factor). + If you specify more than one value in a category (such as "!?" + for potions and scrolls or "BU" for blessed and uncursed), an + inventory object will meet the criteria if it matches any of the + specified values (so "!?" means `!' or `?'). If you specify more + than one category, an inventory object must meet each of the cat- + egory criteria (so "%u" means class `%' and unpaid `u'). Lastly, + you may specify multiple values within multiple categories: + "!?BU" will select all potions and scrolls which are known to be + blessed or uncursed. (In versions prior to 3.6, filter combina- + tions behaved differently.) + ^D Kick something (usually a door). - NetHack Guidebook 8 + e Eat food. + Normally checks for edible item(s) on the floor, then if none are + found or none are chosen, checks for edible item(s) in inventory. + Precede `e' with the `m' prefix to bypass attempting to eat any- + thing off the floor. + If you attempt to eat while already satiated, you might choke to + death. If you risk it, you will be asked whether to "continue + eating?" if you survive the first bite. You can set the para- + noid_confirmation:eating option to require a response of yes + instead of just y. - . The floor of a room, ice, or a doorless doorway. + E Engrave a message on the floor. - # A corridor, or iron bars, or a tree, or possibly a kitchen - sink (if your dungeon has sinks), or a drawbridge. + E- - write in the dust with your fingers. - > Stairs down: a way to the next level. - < Stairs up: a way to the previous level. - + A closed door, or a spellbook containing a spell you may be - able to learn. + NetHack 5.0.0 May 2, 2026 - @ Your character or a human. - $ A pile of gold. - ^ A trap (once you have detected it). - ) A weapon. - [ A suit or piece of armor. + NetHack Guidebook 15 - % Something edible (not necessarily healthy). - ? A scroll. - / A wand. + Engraving the word "Elbereth" will cause most monsters to not + attack you hand-to-hand (but if you attack, you will rub it out); + this is often useful to give yourself a breather. - = A ring. + f Fire (shoot or throw) one of the objects placed in your quiver + (or quiver sack, or that you have at the ready). You may select + ammunition with a previous `Q' command, or let the computer pick + something appropriate if autoquiver is true. If your wielded + weapon has the throw-and-return property, your quiver is empty, + and autoquiver is false, you will throw that wielded weapon + instead of filling the quiver. This will also automatically use + a polearm if wielded. If fireassist is true, firing will auto- + matically try to wield a launcher (for example, a bow or a sling) + matching the ammo in the quiver; this might take multiple turns, + and get interrupted by a monster. Remember to swap back to your + main melee weapon afterwards. - ! A potion. + See also `t' (throw) for more general throwing and shooting. - ( A useful item (pick-axe, key, lamp...). + i List your inventory (everything you're carrying). - " An amulet or a spider web. + I List selected parts of your inventory, usually be specifying the + character for a particular set of objects, like `[' for armor or + `!' for potions. - * A gem or rock (possibly valuable, possibly worthless). + I* - list all gems in inventory; + Iu - list all unpaid items; + Ix - list all used up items that are on your shopping bill; + IB - list all items known to be blessed; + IU - list all items known to be uncursed; + IC - list all items known to be cursed; + IX - list all items whose bless/curse status is unknown; + IP - list items picked up last; + I$ - count your money. - ` A boulder or statue. + o Open a door. - 0 An iron ball. + O Set options. - _ An altar, or an iron chain. + A menu showing the current option values will be displayed. You + can change most values simply by selecting the menu entry for the + given option (ie, by typing its letter or clicking upon it, + depending on your user interface). For the non-boolean choices, + a further menu or prompt will appear once you've closed this + menu. The available options are listed later in this Guidebook. + Options are usually set before the game rather than with the `O' + command; see the section on options below. Precede `O' with the + `m' prefix to show advanced options. - { A fountain. + ^O Show overview. - } A pool of water or moat or a pool of lava. + Shortcut for "#overview": list interesting dungeon levels vis- + ited. - \ An opulent throne. - a-zA-Z and other symbols - Letters and certain other symbols represent the various in- - habitants of the Mazes of Menace. Watch out, they can be - nasty and vicious. Sometimes, however, they can be helpful. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 16 - NetHack Guidebook 9 + (Prior to 3.6.0, `^O' was a debug mode command which listed the + placement of all special levels. Use "#wizwhere" to run that + command.) - I This marks the last known location of an invisible or other- - wise unseen monster. Note that the monster could have - moved. The `F' and `m' commands may be useful here. + p Pay your shopping bill. - You need not memorize all these symbols; you can ask the - game what any symbol represents with the `/' command (see the - next section for more info). + P Put on an accessory (ring, amulet, or blindfold). - 4. Commands + This command may also be used to wear armor. The prompt for + which inventory item to use will only list accessories, but + choosing an unlisted item of armor will attempt to wear it. (See + the `W' command below. It lists armor as the inventory choices + but will accept an accessory and attempt to put that on.) - Commands can be initiated by typing one or two characters to - which the command is bound to, or typing the command name in the - extended commands entry. Some commands, like "search", do not - require that any more information be collected by NetHack. Other - commands might require additional information, for example a di- - rection, or an object to be used. For those commands that re- - quire additional information, NetHack will present you with ei- - ther a menu of choices or with a command line prompt requesting - information. Which you are presented with will depend chiefly on - how you have set the menustyle option. + ^P Repeat previous message. - For example, a common question, in the form "What do you - want to use? [a-zA-Z ?*]", asks you to choose an object you are - carrying. Here, "a-zA-Z" are the inventory letters of your pos- - sible choices. Typing `?' gives you an inventory list of these - items, so you can see what each letter refers to. In this exam- - ple, there is also a `*' indicating that you may choose an object - not on the list, if you wanted to use something unexpected. Typ- - ing a `*' lists your entire inventory, so you can see the inven- - tory letters of every object you're carrying. Finally, if you - change your mind and decide you don't want to do this command af- - ter all, you can press the ESC key to abort the command. + Subsequent `^P's repeat earlier messages. For some interfaces, + the behavior can be varied via the msg_window option. - You can put a number before some commands to repeat them - that many times; for example, "10s" will search ten times. If - you have the number_pad option set, you must type `n' to prefix a - count, so the example above would be typed "n10s" instead. Com- - mands for which counts make no sense ignore them. In addition, - movement commands can be prefixed for greater control (see be- - low). To cancel a count or a prefix, press the ESC key. + q Quaff (drink) something (potion, water, etc). - The list of commands is rather long, but it can be read at - any time during the game through the `?' command, which accesses - a menu of helpful texts. Here are the default key bindings for - your reference: + When there is a fountain or sink present, it asks whether to + drink from that. If that is declined, then it offers a chance to + choose a potion from inventory. Precede `q' with the `m' prefix + to skip asking about drinking from a fountain or sink. - ? Help menu: display one of several help texts available. + Q Select an object for your quiver, quiver sack, or just generally + at the ready (only one of these is available at a time). You can + then throw this (or one of these) using the `f' command. - / The "whatis" command, to tell what a symbol represents. You - may choose to specify a location or type a symbol (or even a - whole word) to explain. Specifying a location is done by - moving the cursor to a particular spot on the map and then - pressing one of `.', `,', `;', or `:'. `.' will explain the - symbol at the chosen location, conditionally check for "More + r Read a scroll or spellbook. + R Remove a worn accessory (ring, amulet, or blindfold). - NetHack 3.6 February 3, 2023 + If you're wearing more than one, you'll be prompted for which one + to remove. When you're only wearing one, then by default it will + be removed without asking, but you can set the paranoid_confirma- + tion:Remove option to require a prompt. + This command may also be used to take off armor. The prompt for + which inventory item to remove only lists worn accessories, but + an item of worn armor can be chosen. (See the `T' command below. + It lists armor as the inventory choices but will accept an acces- + sory and attempt to remove it.) + ^R Redraw the screen. + s Search for secret doors and traps around you. It usually takes + several tries to find something. Precede with the `m' prefix to + search for a turn even next to a hostile monster, if safe_wait is + on. + Can also be used to figure out whether there is still a monster + at an adjacent "remembered, unseen monster" marker. - NetHack Guidebook 10 + NetHack 5.0.0 May 2, 2026 - info?" depending upon whether the help option is on, and - then you will be asked to pick another location; `,' will - explain the symbol but skip any additional information, then - let you pick another location; `;' will skip additional info - and also not bother asking you to choose another location to - examine; `:' will show additional info, if any, without ask- - ing for confirmation. When picking a location, pressing the - ESC key will terminate this command, or pressing `?' will - give a brief reminder about how it works. - If the autodescribe option is on, a short description of - what you see at each location is shown as you move the cur- - sor. Typing `#' while picking a location will toggle that - option on or off. The whatis_coord option controls whether - the short description includes map coordinates. - Specifying a name rather than a location always gives any - additional information available about that name. - You may also request a description of nearby monsters, all - monsters currently displayed, nearby objects, or all ob- - jects. The whatis_coord option controls which format of map - coordinate is included with their descriptions. + NetHack Guidebook 17 - & Tell what a command does. - < Go up to the previous level (if you are on a staircase or - ladder). - > Go down to the next level (if you are on a staircase or lad- - der). + S Save the game (which suspends play and exits the program). The + saved game will be restored automatically the next time you play + using the same character name. - [yuhjklbn] - Go one step in the direction indicated (see Figure 2). If - you sense or remember a monster there, you will fight the - monster instead. Only these one-step movement commands - cause you to fight monsters; the others (below) are "safe." + In normal play, once a saved game is restored the file used to + hold the saved data is deleted. In explore mode, once restora- + tion is accomplished you are asked whether to keep or delete the + file. Keeping the file makes it feasible to play for a while + then quit without saving and later restore again. - y k u 7 8 9 - \ | / \ | / - h- . -l 4- . -6 - / | \ / | \ - b j n 1 2 3 - (if number_pad is set) + There is no "save current game state and keep playing" command, + not even in explore mode where saved game files can be kept and + re-used. - Figure 2 + t Throw an object or shoot a projectile. - [YUHJKLBN] - Go in that direction until you hit a wall or run into some- - thing. + There's no separate "shoot" command. If you throw an arrow while + wielding a bow, you are shooting that arrow and any weapon skill + bonus or penalty for bow applies. If you throw an arrow while + not wielding a bow, you are throwing it by hand and it will gen- + erally be less effective than when shot. - m[yuhjklbn] - Prefix: move without picking up objects or fighting (even - if you remember a monster there). + See also `f' (fire) for throwing or shooting an item pre-selected + via the `Q' (quiver) command, with some extra assistance. + T Take off armor. - NetHack 3.6 February 3, 2023 + If you're wearing more than one piece, you'll be prompted for + which one to take off. (Note that this treats a cloak covering a + suit and/or a shirt, or a suit covering a shirt, as if the under- + lying items weren't there.) When you're only wearing one, then + by default it will be taken off without asking, but you can set + the paranoid_confirmation:Remove option to require a prompt. + This command may also be used to remove accessories. The prompt + for which inventory item to take off only lists worn armor, but a + worn accessory can be chosen. (See the `R' command above. It + lists accessories as the inventory choices but will accept an + item of armor and attempt to take it off.) + ^T Teleport, if you have the ability. + v Display a list of significant events in the current game, also + shown by #chronicle. + `v' used to display the game's version number. Use `V' for that + now. - NetHack Guidebook 11 + V Display version number. + `V' used to display a summary of the game's history. Still + available via #history. - A few non-movement commands use the `m' prefix to request - operating via menu (to temporarily override the - menustyle:Traditional option). Primarily useful for `,' - (pickup) when there is only one class of objects present - (where there won't be any "what kinds of objects?" prompt, - so no opportunity to answer `m' at that prompt). - A few other commands (eat food, offer sacrifice, apply tin- - ning-kit) use the `m' prefix to skip checking for applicable - objects on the floor and go straight to checking inventory, - or (for "#loot" to remove a saddle), skip containers and go - straight to adjacent monsters. The prefix will make "#trav- - el" command show a menu of interesting targets in sight. In - debug mode (aka "wizard mode"), the `m' prefix may also be - used with the "#teleport" and "#wizlevelport" commands. - F[yuhjklbn] - Prefix: fight a monster (even if you only guess one is - there). + NetHack 5.0.0 May 2, 2026 - M[yuhjklbn] - Prefix: move far, no pickup. - g[yuhjklbn] - Prefix: move until something interesting is found. - G[yuhjklbn] or [yuhjklbn] - Prefix: same as `g', but forking of corridors is not con- - sidered interesting. - _ Travel to a map location via a shortest-path algorithm. - The shortest path is computed over map locations the hero - knows about (e.g. seen or previously traversed). If there - is no known path, a guess is made instead. Stops on most of - the same conditions as the `G' command, but without picking - up objects, similar to the `M' command. For ports with - mouse support, the command is also invoked when a mouse- - click takes place on a location other than the current posi- - tion. + NetHack Guidebook 18 - . Wait or rest, do nothing for one turn. - a Apply (use) a tool (pick-axe, key, lamp...). - If used on a wand, that wand will be broken, releasing its - magic in the process. Confirmation is required. + w Wield weapon. - A Remove one or more worn items, such as armor. + w- - wield nothing, use your bare (or gloved) hands. - Use `T' (take off) to take off only one piece of armor or - `R' (remove) to take off only one accessory. + Some characters can wield two weapons at once; use the `X' com- + mand (or the "#twoweapon" extended command) to do so. + W Wear armor. + This command may also be used to put on an accessory (ring, + amulet, or blindfold). The prompt for which inventory item to + use will only list armor, but choosing an unlisted accessory will + attempt to put it on. (See the `P' command above. It lists + accessories as the inventory choices but will accept an item of + armor and attempt to wear it.) + x Exchange your wielded weapon with the item in your alternate + weapon slot. - NetHack 3.6 February 3, 2023 + The latter is used as your secondary weapon when engaging in two- + weapon combat. Note that if one of these slots is empty, the + exchange still takes place. + X Toggle two-weapon combat, if your character can do it. Also + available via the "#twoweapon" extended command. + (In versions prior to 3.6 this keystroke ran the command to + switch from normal play to "explore mode", also known as "discov- + ery mode", which has now been moved to "#exploremode" and M-X.) + ^X Display basic information about your character. + Displays name, role, race, gender (unless role name makes that + redundant, such as Caveman or Priestess), and alignment, along + with your patron deity and his or her opposition. It also shows + most of the various items of information from the status line(s) + in a less terse form, including several additional things which + don't appear in the normal status display due to space considera- + tions. - NetHack Guidebook 12 + In normal play, that's all that `^X' displays. In explore mode, + the role and status feedback is augmented by the information pro- + vided by enlightenment magic. + z Zap a wand. + z. - to aim at yourself, use `.' for the direction. - ^A Redo the previous command. + Z Zap (cast) a spell. - c Close a door. + Z. - to cast at yourself, use `.' for the direction. - C Call (name) a monster, an individual object, or a type of - object. - Same as extended command "#name". - ^C Panic button. Quit the game. - d Drop something. - For example "d7a" means drop seven items of object a. + NetHack 5.0.0 May 2, 2026 - D Drop several things. - In answer to the question - "What kinds of things do you want to drop? [!%= BUCXaium]" - you should type zero or more object symbols possibly fol- - lowed by `a' and/or `i' and/or `u' and/or `m'. In addition, - one or more of the blessed/uncursed/cursed groups may be - typed. - DB - drop all objects known to be blessed. - DU - drop all objects known to be uncursed. - DC - drop all objects known to be cursed. - DX - drop all objects of unknown B/U/C status. - Da - drop all objects, without asking for confirmation. - Di - examine your inventory before dropping anything. - Du - drop only unpaid objects (when in a shop). - Dm - use a menu to pick which object(s) to drop. - D%u - drop only unpaid food. + NetHack Guidebook 19 - The last example shows a combination. There are three cate- - gories of object filtering: class (`!' for potions, `?' for - scrolls, and so on), shop status (`u' for unpaid, in other - words, owned by the shop), and bless/curse state (`B', `U', - `C', and `X' as shown above). If you specify more than one - value in a category (such as "!?" for potions and scrolls or - "BU" for blessed and uncursed), an inventory object will - meet the criteria if it matches any of the specified values - (so "!?" means `!' or `?'). If you specify more than one - category, an inventory object must meet each of the category - criteria (so "%u" means class `%' and unpaid `u'). Lastly, - you may specify multiple values within multiple categories: - "!?BU" will select all potions and scrolls which are known - to be blessed or uncursed. (In versions prior to 3.6, fil- - ter combinations behaved differently.) - ^D Kick something (usually a door). + ^Z Suspend the game (UNIX(R) versions with job control only). See + "#suspend" below for more details. + : Look at what is here. - NetHack 3.6 February 3, 2023 + ; Show what type of thing a visible symbol corresponds to. + , Pick up some things from the floor beneath you. + May be preceded by `m' to force a selection menu. + @ Toggle the autopickup option on and off. + ^ Ask for the type of an adjacent trap you found earlier. - NetHack Guidebook 13 + ) Tell what weapon you are wielding. + [ Tell what armor you are wearing. + = Tell what rings you are wearing. - e Eat food. + " Tell what amulet you are wearing. - Normally checks for edible item(s) on the floor, then if - none are found or none are chosen, checks for edible item(s) - in inventory. Precede `e' with the `m' prefix to bypass at- - tempting to eat anything off the floor. + ( Tell what tools you are using. - If you attempt to eat while already satiated, you might - choke to death. If you risk it, you will be asked whether - to "continue eating?" if you survive the first bite. You - can set the paranoid_confirmation:eating option to require a - response of yes instead of just y. + * Tell what equipment you are using. - E Engrave a message on the floor. + Combines the preceding five type-specific commands into one. - E- - write in the dust with your fingers. + $ Report the gold you're carrying, possibly shop credit and/or debt + too. - Engraving the word "Elbereth" will cause most monsters to - not attack you hand-to-hand (but if you attack, you will rub - it out); this is often useful to give yourself a breather. + + List the spells you know. - f Fire (shoot or throw) one of the objects placed in your - quiver (or quiver sack, or that you have at the ready). You - may select ammunition with a previous `Q' command, or let - the computer pick something appropriate if autoquiver is - true. + Using this command, you can also rearrange the order in which + your spells are listed, either by sorting the entire list or by + picking one spell from the menu then picking another to swap + places with it. Swapping pairs of spells changes their casting + letters, so the change lasts after the current `+' command fin- + ishes. Sorting the whole list is temporary. To make the most + recent sort order persist beyond the current `+' command, choose + the sort option again and then pick "reassign casting letters". + (Any spells learned after that will be added to the end of the + list rather than be inserted into the sorted ordering.) - See also `t' (throw) for more general throwing and shooting. + \ Show what types of objects have been discovered. - i List your inventory (everything you're carrying). + May be preceded by `m' to select preferred display order. - I List selected parts of your inventory, usually be specifying - the character for a particular set of objects, like `[' for - armor or `!' for potions. + ` Show discovered types for one class of objects. - I* - list all gems in inventory; - Iu - list all unpaid items; - Ix - list all used up items that are on your shopping bill; - IB - list all items known to be blessed; - IU - list all items known to be uncursed; - IC - list all items known to be cursed; - IX - list all items whose bless/curse status is unknown; - I$ - count your money. - o Open a door. + __________ + (R)UNIX is a registered trademark of The Open Group. - O Set options. - A menu showing the current option values will be displayed. - You can change most values simply by selecting the menu en- - try for the given option (ie, by typing its letter or click- - ing upon it, depending on your user interface). For the - non-boolean choices, a further menu or prompt will appear - once you've closed this menu. The available options are + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 20 - NetHack Guidebook 14 + May be preceded by `m' to select preferred display order. + | If persistent inventory display is supported and enabled (with + the perm_invent option), interact with it instead of with the + map. - listed later in this Guidebook. Options are usually set be- - fore the game rather than with the `O' command; see the sec- - tion on options below. + Allows scrolling with the menu_first_page, menu_previous_page, + menu_next_page, and menu_last_page keys (`^', `<', `>', `|' by + default). Some interfaces also support menu_shift_left and + menu_shift_right keys (`{' and `}' by default). Use the Return + (aka Enter) or Escape key to resume play. - ^O Show overview. + ! Escape to a shell. See "#shell" below for more details. - Shortcut for "#overview": list interesting dungeon levels - visited. + Del Show map without obstructions. You can view the explored portion + of the current level's map without monsters; without monsters and + objects; or without monsters, objects, and traps. - (Prior to 3.6.0, `^O' was a debug mode command which listed - the placement of all special levels. Use "#wizwhere" to run - that command.) + The key is also shown as on some keyboards or + on others. It is sometimes displayed as ^? even though + that is not an actual control character. - p Pay your shopping bill. + Many terminals have an option to swap the and + keys, so typing the key might not execute this + command. If that happens, you can use the extended command + "#terrain" instead. - P Put on an accessory (ring, amulet, or blindfold). + # Perform an extended command. - This command may also be used to wear armor. The prompt for - which inventory item to use will only list accessories, but - choosing an unlisted item of armor will attempt to wear it. - (See the `W' command below. It lists armor as the inventory - choices but will accept an accessory and attempt to put that - on.) - ^P Repeat previous message. - Subsequent `^P's repeat earlier messages. For some inter- - faces, the behavior can be varied via the msg_window option. + As you can see, the authors of NetHack used up all the letters, + so this is a way to introduce the less frequently used commands. What + extended commands are available depends on what features the game was + compiled with. - q Quaff (drink) something (potion, water, etc). + #adjust + Adjust inventory letters (most useful when the fixinv option is + "on"). Autocompletes. Default key is `M-a'. - Q Select an object for your quiver, quiver sack, or just gen- - erally at the ready (only one of these is available at a - time). You can then throw this (or one of these) using the - `f' command. + This command allows you to move an item from one particular + inventory slot to another so that it has a letter which is more + meaningful for you or that it will appear in a particular loca- + tion when inventory listings are displayed. You can move to a + currently empty slot, or if the destination is occupied--and + won't merge--the item there will swap slots with the one being + moved. "#adjust" can also be used to split a stack of objects; + when choosing the item to adjust, enter a count prior to its let- + ter. - (In versions prior to 3.3 this was the command to quit the - game, which has been moved to "#quit".) + Adjusting without a count used to collect all compatible stacks + when moving to the destination. That behavior has been changed; + to gather compatible stacks, "#adjust" a stack into its own + inventory slot. If it has a name assigned, other stacks with the - r Read a scroll or spellbook. - R Remove a worn accessory (ring, amulet, or blindfold). + NetHack 5.0.0 May 2, 2026 - If you're wearing more than one, you'll be prompted for - which one to remove. When you're only wearing one, then by - default it will be removed without asking, but you can set - the paranoid_confirmation option to require a prompt. - This command may also be used to take off armor. The prompt - for which inventory item to remove only lists worn acces- - sories, but an item of worn armor can be chosen. (See the - `T' command below. It lists armor as the inventory choices - but will accept an accessory and attempt to remove it.) - NetHack 3.6 February 3, 2023 + NetHack Guidebook 21 + same name or with no name will merge provided that all their + other attributes match. If it does not have a name, only other + stacks with no name are eligible. In either case, otherwise com- + patible stacks with a different name will not be merged. This + contrasts with using "#adjust" to move from one slot to a differ- + ent slot. In that situation, moving (no count given) a compati- + ble stack will merge if either stack has a name when the other + doesn't and give that name to the result, while splitting (count + given) will ignore the source stack's name when deciding whether + to merge with the destination stack. + #annotate + Allows you to specify one line of text to associate with the cur- + rent dungeon level. All levels with annotations are displayed by + the "#overview" command. Autocompletes. Default key is `M-A', + and also `^N' if number_pad is on. - NetHack Guidebook 15 + Preceding #annotate with the `m' prefix is the same as #overview + with the prefix. + #apply + Apply (use) a tool such as a pick-axe, a key, or a lamp. Default + key is `a'. + If the tool used acts on items on the floor, using the `m' prefix + skips those items. - ^R Redraw the screen. + If used on a wand, that wand will be broken, releasing its magic + in the process. Confirmation is required. - s Search for secret doors and traps around you. It usually - takes several tries to find something. + #attributes + Show your attributes. Default key is `^X'. - Can also be used to figure out whether there is still a mon- - ster at an adjacent "remembered, unseen monster" marker. + #autopickup + Toggle the autopickup option on/off. Default key is `@'. - S Save the game (which suspends play and exits the program). - The saved game will be restored automatically the next time - you play using the same character name. + #bugreport + Bring up a browser window to submit a report to the NetHack + Development Team. Can be disabled at the time the program is + built; when enabled, CRASHREPORTURL must be set in the system + configuration file. - In normal play, once a saved game is restored the file used - to hold the saved data is deleted. In explore mode, once - restoration is accomplished you are asked whether to keep or - delete the file. Keeping the file makes it feasible to play - for a while then quit without saving and later restore - again. + #call + Call (name) a monster, or an object in inventory, on the floor, + or in the discoveries list, or add an annotation for the current + level (same as "#annotate"). Default key is `C'. - There is no "save current game state and keep playing" com- - mand, not even in explore mode where saved game files can be - kept and re-used. + #cast + Cast a spell. Default key is `Z'. - t Throw an object or shoot a projectile. + #chat + Talk to someone. Default key is `M-c'. - There's no separate "shoot" command. If you throw an arrow - while wielding a bow, you are shooting that arrow and any - weapon skill bonus or penalty for bow applies. If you throw - an arrow while not wielding a bow, you are throwing it by - hand and it will generally be less effective than when shot. - See also `f' (fire) for throwing or shooting an item pre-se- - lected via the `Q' (quiver) command. - T Take off armor. - If you're wearing more than one piece, you'll be prompted - for which one to take off. (Note that this treats a cloak - covering a suit and/or a shirt, or a suit covering a shirt, - as if the underlying items weren't there.) When you're only - wearing one, then by default it will be taken off without - asking, but you can set the paranoid_confirmation option to - require a prompt. + NetHack 5.0.0 May 2, 2026 - This command may also be used to remove accessories. The - prompt for which inventory item to take off only lists worn - armor, but a worn accessory can be chosen. (See the `R' - command above. It lists accessories as the inventory choic- - es but will accept an item of armor and attempt to take it - off.) - ^T Teleport, if you have the ability. + NetHack Guidebook 22 - NetHack 3.6 February 3, 2023 + #chronicle + Show a list of important game events. Default key is `v'. + #close + Close a door. Default key is `c'. + #conduct + List voluntary challenges you have maintained. Autocompletes. + Default key is `M-C'. - NetHack Guidebook 16 + See the section below entitled "Conduct" for details. + #debugfuzzer + Start the fuzz tester. Debug mode only. + #dip + Dip an object into something. Autocompletes. Default key is `M- + d'. - v Display version number. + The `m' prefix skips dipping into a fountain or pool if there is + one at your location. - V Display the game history. + #down + Go down a staircase. Default key is `>'. - w Wield weapon. + #drop + Drop an item. Default key is `d'. - w- - wield nothing, use your bare (or gloved) hands. + #droptype + Drop specific item types. Default key is `D'. - Some characters can wield two weapons at once; use the `X' - command (or the "#twoweapon" extended command) to do so. + #eat + Eat something. Default key is `e'. The `m' prefix skips eating + items on the floor. - W Wear armor. + #engrave + Engrave writing on the floor. Default key is `E'. - This command may also be used to put on an accessory (ring, - amulet, or blindfold). The prompt for which inventory item - to use will only list armor, but choosing an unlisted acces- - sory will attempt to put it on. (See the `P' command above. - It lists accessories as the inventory choices but will ac- - cept an item of armor and attempt to wear it.) + #enhance + Advance or check weapon and spell skills. Autocompletes. + Default key is `M-e'. - x Exchange your wielded weapon with the item in your alternate - weapon slot. + #exploremode + Switch from normal play to non-scoring explore mode. Default key + is `M-X'. - The latter is used as your secondary weapon when engaging in - two-weapon combat. Note that if one of these slots is emp- - ty, the exchange still takes place. + Requires confirmation; default response is n (no). To really + switch to explore mode, respond with y. You can set the para- + noid_confirmation:quit option to require a response of yes + instead. - X Toggle two-weapon combat, if your character can do it. Also - available via the "#twoweapon" extended command. + #fight + Prefix key to force fight a direction, even if you see nothing to + fight there. Default key is `F', or `-' with number_pad - (In versions prior to 3.6 this was the command to switch - from normal play to "explore mode", also known as "discovery - mode", which has now been moved to "#exploremode".) - ^X Display basic information about your character. + NetHack 5.0.0 May 2, 2026 - Displays name, role, race, gender (unless role name makes - that redundant, such as Caveman or Priestess), and align- - ment, along with your patron deity and his or her opposi- - tion. It also shows most of the various items of informa- - tion from the status line(s) in a less terse form, including - several additional things which don't appear in the normal - status display due to space considerations. - In normal play, that's all that `^X' displays. In explore - mode, the role and status feedback is augmented by the in- - formation provided by enlightenment magic. - z Zap a wand. - z. - to aim at yourself, use `.' for the direction. - Z Zap (cast) a spell. + NetHack Guidebook 23 - NetHack 3.6 February 3, 2023 + #fire + Fire ammunition from quiver, possibly autowielding a launcher, or + hit with a wielded polearm. Default key is `f'. + #force + Force a lock. Autocompletes. Default key is `M-f'. + #genocided + List any monster types which have been genocided. In explore + mode and debug mode it also shows types which have become + extinct. + The display order is the same as is used by #vanquished. The `m' + prefix brings up a menu of available sorting orders, and doing + that for either #genocided or #vanquished changes the order for + both. + If the sorting order is "count high to low" or "count low to + high" (which are applicable for #vanquished), that will be + ignored for #genocided and alphabetical will be used instead. + The menu omits those two choices when used for #genocide. - NetHack Guidebook 17 + Autocompletes. Default key is `M-g'. + #glance + Show what type of thing a map symbol corresponds to. Default key + is `;'. + #help + Show the help menu. Default key is `?', and also `h' if num- + ber_pad is on. - Z. - to cast at yourself, use `.' for the direction. + #herecmdmenu + Show a menu of possible actions directed at your current loca- + tion. The menu is limited to a subset of the likeliest actions, + not an exhaustive set of all possibilities. Autocompletes. - ^Z Suspend the game (UNIX(R) versions with job control only). + If mouse support is enabled and the herecmd_menu option is On, + clicking on the hero (or steed when mounted) will execute this + command. - : Look at what is here. + #history + Show a summary of the game's development. - ; Show what type of thing a visible symbol corresponds to. + #inventory + Show your inventory. Default key is `i'. - , Pick up some things from the floor beneath you. + #inventtype + Inventory specific item types. Default key is `I'. - May be preceded by `m' to force a selection menu. + #invoke + Invoke an object's special powers. Autocompletes. Default key + is `M-i'. - @ Toggle the autopickup option on and off. - ^ Ask for the type of an adjacent trap you found earlier. - ) Tell what weapon you are wielding. + NetHack 5.0.0 May 2, 2026 - [ Tell what armor you are wearing. - = Tell what rings you are wearing. - " Tell what amulet you are wearing. - ( Tell what tools you are using. - * Tell what equipment you are using. + NetHack Guidebook 24 - Combines the preceding five type-specific commands into one. - $ Count your gold pieces. - + List the spells you know. + #jump + Jump to another location. Autocompletes. Default key is `M-j', + and also `j' if number_pad is on. - Using this command, you can also rearrange the order in - which your spells are listed, either by sorting the entire - list or by picking one spell from the menu then picking an- - other to swap places with it. Swapping pairs of spells - changes their casting letters, so the change lasts after the - current `+' command finishes. Sorting the whole list is - temporary. To make the most recent sort order persist be- - yond the current `+' command, choose the sort option again - and then pick "reassign casting letters". (Any spells - learned after that will be added to the end of the list - rather than be inserted into the sorted ordering.) + #kick + Kick something. Default key is `^D', and `k' if number_pad is + on. - \ Show what types of objects have been discovered. + #known + Show what object types have been discovered. Default key is `\'. - ` Show discovered types for one class of objects. + The `m' prefix allows assigning a new value to the sortdiscover- + ies option to control the order in which the discoveries are dis- + played. + #knownclass + Show discovered types for one class of objects. Default key is + ``'. + The `m' prefix operates the same as for "#known". - __________ - (R)UNIX is a registered trademark of The Open Group. + #levelchange + Change your experience level. Autocompletes. Debug mode only. + #lightsources + Show mobile light sources. Autocompletes. Debug mode only. - NetHack 3.6 February 3, 2023 + #look + Look at what is here, under you. Default key is `:'. + #lookaround + Describe what you can see, or remember, of your surroundings. + #loot + Loot a box or bag on the floor beneath you, or the saddle from a + steed standing next to you. Autocompletes. Precede with the `m' + prefix to skip containers at your location and go directly to + removing a saddle. Default key is `M-l', and also `l' if num- + ber_pad is on. + #monster + Use a monster's special ability (when polymorphed into monster + form). Autocompletes. Default key is `M-m'. + #name + Name a monster, an individual object, or a type of object. Same + as "#call". Autocompletes. Default keys are `N', `M-n', and `M- + N'. - NetHack Guidebook 18 + #offer + Offer a sacrifice to the gods. Autocompletes. Default key is + `M-o'. - ! Escape to a shell. - # Perform an extended command. + NetHack 5.0.0 May 2, 2026 - As you can see, the authors of NetHack used up all the let- - ters, so this is a way to introduce the less frequently used com- - mands. What extended commands are available depends on what fea- - tures the game was compiled with. - #adjust - Adjust inventory letters (most useful when the fixinv option - is "on"). Autocompletes. Default key is `M-a'. - This command allows you to move an item from one particular - inventory slot to another so that it has a letter which is - more meaningful for you or that it will appear in a particu- - lar location when inventory listings are displayed. You can - move to a currently empty slot, or if the destination is oc- - cupied -- and won't merge -- the item there will swap slots - with the one being moved. "#adjust" can also be used to - split a stack of objects; when choosing the item to adjust, - enter a count prior to its letter. + NetHack Guidebook 25 - Adjusting without a count used to collect all compatible - stacks when moving to the destination. That behavior has - been changed; to gather compatible stacks, "#adjust" a stack - into its own inventory slot. If it has a name assigned, - other stacks with the same name or with no name will merge - provided that all their other attributes match. If it does - not have a name, only other stacks with no name are eligi- - ble. In either case, otherwise compatible stacks with a - different name will not be merged. This contrasts with us- - ing "#adjust" to move from one slot to a different slot. In - that situation, moving (no count given) a compatible stack - will merge if either stack has a name when the other doesn't - and give that name to the result, while splitting (count - given) will ignore the source stack's name when deciding - whether to merge with the destination stack. - #annotate - Allows you to specify one line of text to associate with the - current dungeon level. All levels with annotations are dis- - played by the "#overview" command. Autocompletes. Default - key is `M-A', and also `^N' if number_pad is on. - #apply - Apply (use) a tool such as a pick-axe, a key, or a lamp. - Default key is `a'. + You'll need to find an altar to have any chance at success. + Corpses of recently killed monsters are the fodder of choice. - If the tool used acts on items on the floor, using the `m' - prefix skips those items. + The `m' prefix skips offering any items which are on the altar. + #open + Open a door. Default key is `o'. + #options + Show and change option settings. Default key is `O'. Precede + with the `m' prefix to show advanced options. - NetHack 3.6 February 3, 2023 + #optionsfull + Show advanced game option settings. No default key. Precede + with the `m' prefix to execute the simpler options command. + (Mainly useful if you use BINDING=O:optionsfull to switch `O' + from simple options back to traditional advanced options.) + #overview + Display information you've discovered about the dungeon. Any + visited level with an annotation is included, and many things + (altars, thrones, fountains, and so on; extra stairs leading to + another dungeon branch) trigger an automatic annotation. If dun- + geon overview is chosen during end-of-game disclosure, every vis- + ited level will be included regardless of annotations. + Precede #overview with the `m' prefix to display the dungeon + overview as a menu where you can select any visited level to add + or remove an annotation without needing to return to that level. + This will also force all visited levels to be displayed rather + than just the "interesting" subset. + Autocompletes. Default keys are `^O', and `M-O'. + #panic + Test the panic routine. Terminates the current game. Autocom- + pletes. Debug mode only. - NetHack Guidebook 19 + Asks for confirmation; default is n (no); continue playing. To + really panic, respond with y. You can set the paranoid_confirma- + tion:quit option to require a response of yes instead. + #pay + Pay your shopping bill. Default key is `p'. + #perminv + If persistent inventory display is supported and enabled (with + the perm_invent option), interact with it instead of with the + map. You'll be prompted for menu scrolling keystrokes such as + `>' and `<'. Press Return or Escape to resume normal play. + Default key is `|'. - If used on a wand, that wand will be broken, releasing its - magic in the process. Confirmation is required. + #pickup + Pick up things at the current location. Default key is `,'. The - #attributes - Show your attributes. Default key is `^X'. - #autopickup - Toggle the autopickup option on/off. Default key is `@'. + NetHack 5.0.0 May 2, 2026 - #call - Call (name) a monster, or an object in inventory, on the - floor, or in the discoveries list, or add an annotation for - the current level (same as "#annotate"). Default key is - `C'. - #cast - Cast a spell. Default key is `Z'. - #chat - Talk to someone. Default key is `M-c'. - #close - Close a door. Default key is `c'. - #conduct - List voluntary challenges you have maintained. Autocom- - pletes. Default key is `M-C'. + NetHack Guidebook 26 - See the section below entitled "Conduct" for details. - #dip - Dip an object into something. Autocompletes. Default key - is `M-d'. - #down - Go down a staircase. Default key is `>'. + `m' prefix forces use of a menu. - #drop - Drop an item. Default key is `d'. + #polyself + Polymorph self. Autocompletes. Debug mode only. - #droptype - Drop specific item types. Default key is `D'. + #pray + Pray to the gods for help. Autocompletes. Default key is `M-p'. - #eat - Eat something. Default key is `e'. The `m' prefix skips - eating items on the floor. + Praying too soon after receiving prior help is a bad idea. + (Hint: entering the dungeon alive is treated as having received + help. You probably shouldn't start off a new game by praying + right away.) Since using this command by accident can cause + trouble, there is an option to make you confirm your intent + before praying. It is enabled by default, and you can reset the + paranoid_confirmation option to disable it. - #engrave - Engrave writing on the floor. Default key is `E'. + #prevmsg + Show previously displayed game messages. Default key is `^P'. - #enhance - Advance or check weapon and spell skills. Autocompletes. - Default key is `M-e'. + #puton + Put on an accessory (ring, amulet, etc). Default key is `P'. + #quaff + Quaff (drink) something. Default key is `q'. + The `m' prefix skips drinking from a fountain or sink if there is + one at your location. - NetHack 3.6 February 3, 2023 + #quit + Quit the program without saving your game. Autocompletes. + Since using this command by accident would throw away the current + game, you are asked to confirm your intent before quitting. + Default response is n (no); continue playing. To really quit, + respond with y. You can set the paranoid_confirmation:quit + option to require a response of yes instead. + #quiver + Select ammunition for quiver. Default key is `Q'. + #read + Read a scroll, a spellbook, or something else. Default key is + `r'. + #redraw + Redraw the screen. Default key is `^R', and also `^L' if num- + ber_pad is on. - NetHack Guidebook 20 + #remove + Remove an accessory (ring, amulet, etc). Default key is `R'. + #repeat + Repeat the previous command. Default key is `^A'. - #exploremode - Enter the explore mode. - Requires confirmation; default response is n (no). To real- - ly switch to explore mode, respond with y. You can set the - paranoid_confirmation:quit option to require a response of - yes instead. + NetHack 5.0.0 May 2, 2026 - #fire - Fire ammunition from quiver. Default key is `f'. - #force - Force a lock. Autocompletes. Default key is `M-f'. - #glance - Show what type of thing a map symbol corresponds to. De- - fault key is `;'. - #help - Show the help menu. Default key is `?', and also `h' if - number_pad is on. - #herecmdmenu - Show a menu of possible actions in your current location. + NetHack Guidebook 27 - #history - Show long version and game history. Default key is `V'. - #inventory - Show your inventory. Default key is `i'. - #inventtype - Inventory specific item types. Default key is `I'. + #reqmenu + Prefix key to modify the behavior or request menu from some com- + mands. Prevents autopickup when used with movement commands. + Default key is `m'. - #invoke - Invoke an object's special powers. Autocompletes. Default - key is `M-i'. + #retravel + Travel to a previously selected travel destination. Default key + is `C-_'. See also #travel. - #jump - Jump to another location. Autocompletes. Default key is - `M-j', and also `j' if number_pad is on. + #ride + Ride (or stop riding) a saddled creature. Autocompletes. + Default key is `M-R'. - #kick - Kick something. Default key is `^D', and `k' if number_pad - is on. + #rub + Rub a lamp or a stone. Autocompletes. Default key is `M-r'. - #known - Show what object types have been discovered. Default key is - `\'. + #run + Prefix key to run towards a direction. Default key is `G' when + number_pad is off, `5' when number_pad is set to 1 or 3, other- + wise `M-5' when it is set to 2 or 4. - #knownclass - Show discovered types for one class of objects. Default key - is ``'. + #rush + Prefix key to rush towards a direction. Default is `g' when num- + ber_pad is off, `M-5' when number_pad is set to 1 or 3, otherwise + `5' when it is set to 2 or 4. + #save + Save the game and exit the program. Default key is `S'. + #saveoptions + Save configuration options to the config file. This will over- + write the file, removing all comments, so if you have manually + edited the config file, don't use this. - NetHack 3.6 February 3, 2023 + #search + Search for traps and secret doors around you. Default key is + `s'. + #seeall + Show all equipment in use. Default key is `*'. + Will display in-use items in a menu even when there is only one. + #seeamulet + Show the amulet currently worn. Default key is `"'. + Using the `m' prefix will force the display of a worn amulet in a + menu rather than with just a message. - NetHack Guidebook 21 + #seearmor + Show the armor currently worn. Default key is `['. + Will display worn armor in a menu even when there is only thing + worn. - #levelchange - Change your experience level. Autocompletes. Debug mode - only. + NetHack 5.0.0 May 2, 2026 - #lightsources - Show mobile light sources. Autocompletes. Debug mode only. - #look - Look at what is here, under you. Default key is `:'. - #loot - Loot a box or bag on the floor beneath you, or the saddle - from a steed standing next to you. Autocompletes. Precede - with the `m' prefix to skip containers at your location and - go directly to removing a saddle. Default key is `M-l', and - also `l' if number_pad is on. - #monster - Use a monster's special ability (when polymorphed into mon- - ster form). Autocompletes. Default key is `M-m'. - #name - Name a monster, an individual object, or a type of object. - Same as "#call". Autocompletes. Default keys are `N', `M- - n', and `M-N'. + NetHack Guidebook 28 - #offer - Offer a sacrifice to the gods. Autocompletes. Default key - is `M-o'. - You'll need to find an altar to have any chance at success. - Corpses of recently killed monsters are the fodder of - choice. - The `m' prefix skips offering any items which are on the al- - tar. + #seerings + Show the ring(s) currently worn. Default key is `='. - #open - Open a door. Default key is `o'. + Will display worn rings in a menu if there are two (or there is + just one and is a meat ring rather than a "real" ring). Use the + `m' prefix to force a menu for one ring. - #options - Show and change option settings. Default key is `O'. + #seetools + Show the tools currently in use. Default key is `('. - #overview - Display information you've discovered about the dungeon. - Any visited level (unless forgotten due to amnesia) with an - annotation is included, and many things (altars, thrones, - fountains, and so on; extra stairs leading to another dun- - geon branch) trigger an automatic annotation. If dungeon - overview is chosen during end-of-game disclosure, every vis- - ited level will be included regardless of annotations. Au- - tocompletes. Default keys are `^O', and `M-O'. + Will display the result in a message if there is one tool in use + (worn blindfold or towel or lenses, lit lamp(s) and/or candle(s), + leashes attached to pets). Will display a menu if there are more + than one or if the command is preceded by the `m' prefix. + #seeweapon + Show the weapon currently wielded. Default key is `)'. + If dual-wielding, a separate message about the secondary weapon + will be given. Using the `m' prefix will force a menu and it + will include primary weapon, alternate weapon even when not dual- + wielding, and also whatever is currently assigned to the quiver + slot. + #shell + Do a shell escape, switching from NetHack to a subprocess. Can + be disabled at the time the program is built. When enabled, + access for specific users can be controlled by the system config- + uration file. Use the shell command `exit' to return to the + game. Default key is `!'. - NetHack 3.6 February 3, 2023 + #showgold + Report the gold in your inventory, including gold you know about + in containers you're carrying. If you are inside a shop, report + any credit or debt you have in that shop. Default key is `$'. + #showspells + List and reorder known spells. Default key is `+'. + #showtrap + Describe an adjacent trap, possibly covered by objects or a mon- + ster. To be eligible, the trap must already be discovered. (The + "#terrain" command can display your map with all objects and mon- + sters temporarily removed, making it possible to see all discov- + ered traps.) Default key is `^'. + #sit + Sit down. Autocompletes. Default key is `M-s'. + #stats + Show memory usage statistics. Autocompletes. Debug mode only. - NetHack Guidebook 22 + #suspend + Suspend the game, switching from NetHack to the terminal it was + NetHack 5.0.0 May 2, 2026 - #panic - Test the panic routine. Terminates the current game. Auto- - completes. Debug mode only. - Asks for confirmation; default is n (no); continue playing. - To really panic, respond with y. You can set the para- - noid_confirmation:quit option to require a response of yes - instead. - #pay - Pay your shopping bill. Default key is `p'. - #pickup - Pick up things at the current location. Default key is `,'. - The `m' prefix forces use of a menu. - #polyself - Polymorph self. Autocompletes. Debug mode only. + NetHack Guidebook 29 - #pray - Pray to the gods for help. Autocompletes. Default key is - `M-p'. - Praying too soon after receiving prior help is a bad idea. - (Hint: entering the dungeon alive is treated as having re- - ceived help. You probably shouldn't start off a new game by - praying right away.) Since using this command by accident - can cause trouble, there is an option to make you confirm - your intent before praying. It is enabled by default, and - you can reset the paranoid_confirmation option to disable - it. - #prevmsg - Show previously displayed game messages. Default key is - `^P'. + started from without performing save-and-exit. Can be disabled + at the time the program is built. When enabled, mainly useful + for tty and curses interfaces on UNIX. Use the shell command + `fg' to return to the game. Default key is `^Z'. - #puton - Put on an accessory (ring, amulet, etc). Default key is - `P'. + #swap + Swap wielded and secondary weapons. Default key is `x'. - #quaff - Quaff (drink) something. Default key is `q'. + #takeoff + Take off one piece of armor. Default key is `T'. - #quit - Quit the program without saving your game. Autocompletes. - Default key is `M-q'. + #takeoffall + Remove all armor. Default key is `A'. - Since using this command by accident would throw away the - current game, you are asked to confirm your intent before - quitting. Default response is n (no); continue playing. To - really quit, respond with y. You can set the paranoid_con- - firmation:quit option to require a response of yes instead. + #teleport + Teleport around the level. Default key is `^T'. + #terrain + Show map without obstructions. In normal play you can view the + explored portion of the current level's map without monsters; + without monsters and objects; or without monsters, objects, and + traps. + If there are visible clouds of gas in view, they are treated like + traps when deciding whether to show them or the floor underneath + them. + In explore mode, you can choose to view the full map rather than + just its explored portion. In debug mode there are additional + choices. - NetHack 3.6 February 3, 2023 + Autocompletes. Default key is `' or `' (see Del + above). + #therecmdmenu + Show a menu of possible actions directed at a location next to + you. The menu is limited to a subset of the likeliest actions, + not an exhaustive set of all possibilities. Autocompletes. + #throw + Throw something. Default key is `t'. + #timeout + Look at the timeout queue. Autocompletes. Debug mode only. + #tip + Tip over a container (bag or box) to pour out its contents. When + there are containers on the floor, the game will prompt to pick + one of them or "tip something being carried". If the latter is + chosen, there will be another prompt for which item from inven- + tory to tip. - NetHack Guidebook 23 + The `m' prefix makes the command skip containers on the floor and + pick one from inventory, except for the special case of + NetHack 5.0.0 May 2, 2026 - #quiver - Select ammunition for quiver. Default key is `Q'. - #read - Read a scroll, a spellbook, or something else. Default key - is `r'. - #redraw - Redraw the screen. Default key is `^R', and also `^L' if - number_pad is on. - #remove - Remove an accessory (ring, amulet, etc). Default key is - `R'. - #ride - Ride (or stop riding) a saddled creature. Autocompletes. - Default key is `M-R'. + NetHack Guidebook 30 - #rub - Rub a lamp or a stone. Autocompletes. Default key is `M- - r'. - #save - Save the game and exit the program. Default key is `S'. - #search - Search for traps and secret doors around you. Default key - is `s'. + menustyle:traditional with two or more containers present; that + situation will start with the floor container menu. - #seeall - Show all equipment in use. Default key is `*'. + Autocompletes. Default key is `M-T'. - #seeamulet - Show the amulet currently worn. Default key is `"'. + #toggle + Toggle a boolean option on or off. Requires a parameter in + parenthesis, the name of the option to toggle. The option must + be settable in-game. - #seearmor - Show the armor currently worn. Default key is `['. + For example: - #seegold - Count your gold. Default key is `$'. + BIND=':toggle(price_quotes) + BIND=@:toggle(autopickup) - #seenv - Show seen vectors. Autocompletes. Debug mode only. + #travel + Travel to a specific location on the map. Default key is `_'. + Using the "request menu" prefix shows a menu of interesting tar- + gets in sight without asking to move the cursor. When picking a + target with cursor and the autodescribe option is on, the top + line will show "(no travel path)" if your character does not know + of a path to that location. See also #retravel. - #seerings - Show the ring(s) currently worn. Default key is `='. + #turn + Turn undead away. Autocompletes. Default key is `M-t'. - #seespells - List and reorder known spells. Default key is `+'. + #twoweapon + Toggle two-weapon combat on or off. Autocompletes. Default key + is `X', and also `M-2' if number_pad is off. - #seetools - Show the tools currently in use. Default key is `('. + Note that you must use suitable weapons for this type of combat, + or it will be automatically turned off. + #untrap + Untrap something (trap, door, or chest). Default key is `M-u', + and `u' if number_pad is on. + In some circumstances it can also be used to rescue trapped mon- + sters. - NetHack 3.6 February 3, 2023 + #up + Go up a staircase. Default key is `<'. + #vanquished + List vanquished monsters by type and count. + Note that the vanquished monsters list includes all monsters + killed by traps and each other as well as by you, and omits any + which got removed from the game without being killed (perhaps by + genocide, or by a mollified shopkeeper dismissing summoned Kops) + or were already corpses when placed on the map. + Using the "request menu" prefix prior to #vanquished brings up a + menu of sorting orders available (provided that the vanquished - NetHack Guidebook 24 + NetHack 5.0.0 May 2, 2026 - #seetrap - Show the type of an adjacent trap. Default key is `^'. - #seeweapon - Show the weapon currently wielded. Default key is `)'. - #shell - Do a shell escape. Default key is `!'. + NetHack Guidebook 31 - #sit - Sit down. Autocompletes. Default key is `M-s'. - #stats - Show memory usage statistics. Autocompletes. Debug mode - only. - #suspend - Suspend the game. Default key is `^Z'. + monsters list contains at least two types of monsters). Which- + ever ordering is picked gets assigned to the sortvanquished + option so is remembered for subsequent #vanquished requests. The + "#genocided" command shares this sorting order. - #swap - Swap wielded and secondary weapons. Default key is `x'. + During end-of-game disclosure, when asked whether to show van- + quished monsters answering `a' will let you choose from the sort + menu. - #takeoff - Take off one piece of armor. Default key is `T'. + Autocompletes. Default key is `M-V'. - #takeoffall - Remove all armor. Default key is `A'. + #version + Print compile time options for this version of NetHack. - #teleport - Teleport around the level. Default key is `^T'. + The second paragraph lists the user interface(s) that are + included. If there are more than one, you can use the windowtype + option in your run-time configuration file to select the one you + want. - #terrain - Show bare map without displaying monsters, objects, or - traps. Autocompletes. + Autocompletes. Default key is `M-v'. - #therecmdmenu - Show a menu of possible actions in a location next to you. + #versionshort + Show the program's version number, plus the date and time that + the running copy was built from sources (not the version's + release date). Default key is `V'. - #throw - Throw something. Default key is `t'. + #vision + Show vision array. Autocompletes. Debug mode only. - #timeout - Look at the timeout queue. Autocompletes. Debug mode only. + #wait + Rest one move while doing nothing. Default key is `.', and also + ` ' if rest_on_space is on. - #tip - Tip over a container (bag or box) to pour out its contents. - Autocompletes. Default key is `M-T'. The `m' prefix makes - the command use a menu. + #wear + Wear a piece of armor. Default key is `W'. - #travel - Travel to a specific location on the map. Default key is - `_'. Using the "request menu" prefix shows a menu of inter- - esting targets in sight without asking to move the cursor. - When picking a target with cursor and the autodescribe + #whatdoes + Tell what a key does. Default key is `&'. + #whatis + Show what type of thing a symbol corresponds to. Default key is + `/'. - NetHack 3.6 February 3, 2023 + #wield + Wield a weapon. Default key is `w'. + #wipe + Wipe off your face. Autocompletes. Default key is `M-w'. + #wizborn + Show monster birth, death, genocide, and extinct statistics. + Debug mode only. - NetHack Guidebook 25 + NetHack 5.0.0 May 2, 2026 - option is on, the top line will show "(no travel path)" if - your character does not know of a path to that location. - #turn - Turn undead away. Autocompletes. Default key is `M-t'. - #twoweapon - Toggle two-weapon combat on or off. Autocompletes. Default - key is `X', and also `M-2' if number_pad is off. - Note that you must use suitable weapons for this type of - combat, or it will be automatically turned off. + NetHack Guidebook 32 - #untrap - Untrap something (trap, door, or chest). Default key is `M- - u', and `u' if number_pad is on. - In some circumstances it can also be used to rescue trapped - monsters. - #up - Go up a staircase. Default key is `<'. + #wizbury + Bury objects under and around you. Autocompletes. Debug mode + only. - #vanquished - List vanquished monsters. Autocompletes. Debug mode only. + #wizcast + Cast any spell. Debug mode only. - #version - Print compile time options for this version of NetHack. Au- - tocompletes. Default key is `M-v'. + #wizdetect + Reveal hidden things (secret doors or traps or unseen monsters) + within a modest radius. No time elapses. Autocompletes. Debug + mode only. Default key is `^E'. - #versionshort - Show version string. Default key is `v'. + #wizgenesis + Create a monster. May be prefixed by a count to create more than + one. Autocompletes. Debug mode only. Default key is `^G'. - #vision - Show vision array. Autocompletes. Debug mode only. + #wizidentify + Identify all items in inventory. Autocompletes. Debug mode + only. Default key is `^I'. - #wait - Rest one move while doing nothing. Default key is `.', and - also ` ' if rest_on_space is on. + #wizintrinsic + Set one or more intrinsic attributes. Autocompletes. Debug mode + only. - #wear - Wear a piece of armor. Default key is `W'. + #wizkill + Remove monsters from play by just pointing at them. By default + the hero gets credit or blame for killing the targets. Precede + this command with the `m' prefix to override that. Autocom- + pletes. Debug mode only. - #whatdoes - Tell what a key does. Default key is `&'. + #wizlevelport + Teleport to another level. Autocompletes. Debug mode only. + Default key is `^V'. - #whatis - Show what type of thing a symbol corresponds to. Default - key is `/'. + #wizmap + Map the level. Autocompletes. Debug mode only. Default key is + `^F'. - #wield - Wield a weapon. Default key is `w'. + #wizrumorcheck + Verify rumor boundaries by displaying first and last true rumors + and first and last false rumors. + Also displays first, second, and last random engravings, epi- + taphs, and hallucinatory monsters. + Autocompletes. Debug mode only. + #wizseenv + Show map locations' seen vectors. Autocompletes. Debug mode + only. - NetHack 3.6 February 3, 2023 + #wizsmell + Smell monster. Autocompletes. Debug mode only. + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 26 - #wipe - Wipe off your face. Autocompletes. Default key is `M-w'. + NetHack Guidebook 33 - #wizbury - Bury objects under and around you. Autocompletes. Debug - mode only. - #wizdetect - Search for hidden things (secret doors or traps or unseen - monsters) within a modest radius. Autocompletes. Debug - mode only. Default key is `^E'. - #wizgenesis - Create a monster. May be prefixed by a count to create more - than one. Autocompletes. Debug mode only. Default key is - `^G'. + #wizwhere + Show locations of special levels. Autocompletes. Debug mode + only. - #wizidentify - Identify all items in inventory. Autocompletes. Debug mode - only. Default key is `^I'. + #wizwish + Wish for something. Autocompletes. Debug mode only. Default + key is `^W'. Precede this command with the `m' prefix to show a + wish history menu. - #wizintrinsic - Set one or more intrinsic attributes. Autocompletes. Debug - mode only. + #wmode + Show wall modes. Autocompletes. Debug mode only. - #wizlevelport - Teleport to another level. Autocompletes. Debug mode only. - Default key is `^V'. + #zap + Zap a wand. Default key is `z'. - #wizmap - Map the level. Autocompletes. Debug mode only. Default - key is `^F'. + #? + Help menu: get the list of available extended commands. - #wizrumorcheck - Verify rumor boundaries. Autocompletes. Debug mode only. - #wizsmell - Smell monster. Autocompletes. Debug mode only. - #wizwhere - Show locations of special levels. Autocompletes. Debug - mode only. + If your keyboard has a meta key (which, when pressed in combina- + tion with another key, modifies it by setting the "meta" [8th, or + "high"] bit), you can invoke many extended commands by meta-ing the + first letter of the command. - #wizwish - Wish for something. Autocompletes. Debug mode only. De- - fault key is `^W'. + On Windows and MS-DOS, the "Alt" key can be used in this fashion. + On other systems, if typing "Alt" plus another key transmits a two + character sequence consisting of an Escape followed by the other key, + you may set the altmeta option to have NetHack combine them into + meta+. (This combining action only takes place when NetHack is + expecting a command to execute, not when accepting input to name some- + thing or to make a wish.) - #wmode - Show wall modes. Autocompletes. Debug mode only. + Unlike control characters, where ^x and ^X denote the same thing, + meta characters are case-sensitive: M-x and M-X represent different + things. Some commands which can be run via a meta character require + that the letter be capitalized because the lower-case equivalent is + used for another command, so the three key combination + meta+Shift+ is needed. - #zap - Zap a wand. Default key is `z'. - NetHack 3.6 February 3, 2023 - NetHack Guidebook 27 - #? - Help menu: get the list of available extended commands. - If your keyboard has a meta key (which, when pressed in com- - bination with another key, modifies it by setting the "meta" - [8th, or "high"] bit), you can invoke many extended commands by - meta-ing the first letter of the command. - In NT, OS/2, PC and ST NetHack, the "Alt" key can be used in - this fashion; on the Amiga, set the altmeta option to get this - behavior. On other systems, if typing "Alt" plus another key - transmits a two character sequence consisting of an Escape fol- - lowed by the other key, you may set the altmeta option to have - NetHack combine them into meta+key. + NetHack 5.0.0 May 2, 2026 - M-? #? (not supported by all platforms) - M-2 #twoweapon (unless the number_pad option is enabled) - M-a #adjust - M-A #annotate - M-c #chat + NetHack Guidebook 34 - M-C #conduct - M-d #dip - M-e #enhance + M-? #? (not supported by all platforms) - M-f #force + M-2 #twoweapon (unless the number_pad option is enabled) - M-i #invoke + M-a #adjust - M-j #jump + M-A #annotate - M-l #loot + M-c #chat - M-m #monster + M-C #conduct - M-n #name + M-d #dip - M-o #offer + M-e #enhance - M-O #overview + M-f #force - M-p #pray + M-g #genocided - M-q #quit + M-i #invoke + M-j #jump + M-l #loot + M-m #monster - NetHack 3.6 February 3, 2023 + M-n #name + M-o #offer + M-O #overview + M-p #pray + M-r #rub - NetHack Guidebook 28 + M-R #ride + M-s #sit + M-t #turn - M-r #rub + M-T #tip - M-R #ride + M-u #untrap - M-s #sit + M-v #version - M-t #turn + M-V #vanquished - M-T #tip + M-w #wipe - M-u #untrap - M-v #version - M-w #wipe + NetHack 5.0.0 May 2, 2026 - If the number_pad option is on, some additional letter com- - mands are available: - h #help - j #jump + NetHack Guidebook 35 - k #kick - l #loot - N #name + M-X #exploremode - u #untrap - 5. Rooms and corridors - Rooms and corridors in the dungeon are either lit or dark. - Any lit areas within your line of sight will be displayed; dark - areas are only displayed if they are within one space of you. - Walls and corridors remain on the map as you explore them. + If the number_pad option is on, some additional letter commands + are available: - Secret corridors are hidden. You can find them with the `s' - (search) command. + h #help - 5.1. Doorways + j #jump - Doorways connect rooms and corridors. Some doorways have no - doors; you can walk right through. Others have doors in them, - which may be open, closed, or locked. To open a closed door, use - the `o' (open) command; to close it again, use the `c' (close) - command. + k #kick - You can get through a locked door by using a tool to pick - the lock with the `a' (apply) command, or by kicking it open with - the `^D' (kick) command. + l #loot + N #name - NetHack 3.6 February 3, 2023 + u #untrap - NetHack Guidebook 29 - Open doors cannot be entered diagonally; you must approach - them straight on, horizontally or vertically. Doorways without - doors are not restricted in this fashion. - Doors can be useful for shutting out monsters. Most mon- - sters cannot open doors, although a few don't need to (for exam- - ple, ghosts can walk through doors). - Secret doors are hidden. You can find them with the `s' - (search) command. Once found they are in all ways equivalent to - normal doors. - 5.2. Traps (`^') - There are traps throughout the dungeon to snare the unwary - delver. For example, you may suddenly fall into a pit and be - stuck for a few turns trying to climb out. Traps don't appear on - your map until you see one triggered by moving onto it, see some- - thing fall into it, or you discover it with the `s' (search) com- - mand. Monsters can fall prey to traps, too, which can be a very - useful defensive strategy. - There is a special pre-mapped branch of the dungeon based on - the classic computer game "Sokoban." The goal is to push the - boulders into the pits or holes. With careful foresight, it is - possible to complete all of the levels according to the tradi- - tional rules of Sokoban. Some allowances are permitted in case - the player gets stuck; however, they will lower your luck. - 5.3. Stairs and ladders (`<', `>') - In general, each level in the dungeon will have a staircase - going up (`<') to the previous level and another going down (`>') - to the next level. There are some exceptions though. For in- - stance, fairly early in the dungeon you will find a level with - two down staircases, one continuing into the dungeon and the oth- - er branching into an area known as the Gnomish Mines. Those - mines eventually hit a dead end, so after exploring them (if you - choose to do so), you'll need to climb back up to the main dun- - geon. - When you traverse a set of stairs, or trigger a trap which - sends you to another level, the level you're leaving will be de- - activated and stored in a file on disk. If you're moving to a - previously visited level, it will be loaded from its file on disk - and reactivated. If you're moving to a level which has not yet - been visited, it will be created (from scratch for most random - levels, from a template for some "special" levels, or loaded from - the remains of an earlier game for a "bones" level as briefly de- - scribed below). Monsters are only active on the current level; - those on other levels are essentially placed into stasis. - Ordinarily when you climb a set of stairs, you will arrive - on the corresponding staircase at your destination. However, - NetHack 3.6 February 3, 2023 - NetHack Guidebook 30 - pets (see below) and some other monsters will follow along if - they're close enough when you travel up or down stairs, and occa- - sionally one of these creatures will displace you during the - climb. When that occurs, the pet or other monster will arrive on - the staircase and you will end up nearby. - Ladders serve the same purpose as staircases, and the two - types of inter-level connections are nearly indistinguishable - during game play. - 5.4. Shops and shopping - Occasionally you will run across a room with a shopkeeper - near the door and many items lying on the floor. You can buy - items by picking them up and then using the `p' command. You can - inquire about the price of an item prior to picking it up by us- - ing the "#chat" command while standing on it. Using an item pri- - or to paying for it will incur a charge, and the shopkeeper won't - allow you to leave the shop until you have paid any debt you owe. - You can sell items to a shopkeeper by dropping them to the - floor while inside a shop. You will either be offered an amount - of gold and asked whether you're willing to sell, or you'll be - told that the shopkeeper isn't interested (generally, your item - needs to be compatible with the type of merchandise carried by - the shop). - If you drop something in a shop by accident, the shopkeeper - will usually claim ownership without offering any compensation. - You'll have to buy it back if you want to reclaim it. - Shopkeepers sometimes run out of money. When that happens, - you'll be offered credit instead of gold when you try to sell - something. Credit can be used to pay for purchases, but it is - only good in the shop where it was obtained; other shopkeepers - won't honor it. (If you happen to find a "credit card" in the - dungeon, don't bother trying to use it in shops; shopkeepers will - not accept it.) - The `$' command, which reports the amount of gold you are - carrying (in inventory, not inside bags or boxes), will also show - current shop debt or credit, if any. The "Iu" command lists un- - paid items (those which still belong to the shop) if you are car- - rying any. The "Ix" command shows an inventory-like display of - any unpaid items which have been used up, along with other shop - fees, if any. - 5.4.1. Shop idiosyncrasies - Several aspects of shop behavior might be unexpected. - * The price of a given item can vary due to a variety of factors. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 36 - NetHack Guidebook 31 + 5. Rooms and corridors + Rooms and corridors in the dungeon are either lit or dark. Any + lit areas within your line of sight will be displayed; dark areas are + only displayed if they are within one space of you. Walls and corri- + dors remain on the map as you explore them. + Secret corridors are hidden and appear to be solid rock. You can + find them with the `s' (search) command when adjacent to them. Multi- + ple search attempts may be needed. When searching is successful, + secret corridors become ordinary open corridor locations. Mapping + magic reveals secret corridors, so converts them into ordinary corri- + dors and shows them as such. - * A shopkeeper treats the spot immediately inside the door as if - it were outside the shop. + 5.1. Doorways - * While the shopkeeper watches you like a hawk, he will generally - ignore any other customers. + Doorways connect rooms and corridors. Some doorways have no + doors; you can walk right through. Others have doors in them, which + may be open, closed, or locked. To open a closed door, use the `o' + (open) command; to close it again, use the `c' (close) command. By + default the autoopen option is enabled, so simply attempting to walk + onto a closed door's location will attempt to open it without needing + `o'. Opening via autoopen will not work if you are confused or + stunned or suffer from the fumbling attribute. - * If a shop is "closed for inventory," it will not open of its - own accord. + Open doors cannot be entered diagonally; you must approach them + straight on, horizontally or vertically. Doorways without doors are + not restricted in this fashion except on one particular level + (described by "#overview" as "a primitive area"). - * Shops do not get restocked with new items, regardless of inven- - tory depletion. + Unlocking magic exists but usually won't be available early on. + You can get through a locked door without magic by first using an + unlocking tool with the `a' (apply) command, and then opening it. By + default the autounlock option is also enabled, so if you attempt to + open (via `o' or autoopen) a locked door while carrying an unlocking + tool, you'll be asked whether to use it on the door's lock. Alterna- + tively, you can break a closed door (whether locked or not) down by + kicking it via the `^D' (kick) command. Kicking down a door destroys + it and makes a lot of noise which might wake sleeping monsters. - 6. Monsters + Some closed doors are booby-trapped and will explode if an + attempt is made to open (when unlocked) or unlock (when locked) or + kick down. Like kicking, an explosion destroys the door and makes a + lot of noise. The "#untrap" command can be used to search a door for + traps but might take multiple attempts to find one. When one is + found, you'll be asked whether to try to disarm it. If you accede, + success will eliminate the trap but failure will set off the trap's + explosion. (If you decline, you effectively forget that a trap was + found there.) - Monsters you cannot see are not displayed on the screen. - Beware! You may suddenly come upon one in a dark place. Some - magic items can help you locate them before they locate you - (which some monsters can do very well). + Closed doors can be useful for shutting out monsters. Most mon- + sters cannot open closed doors, although a few don't need to (for + example, ghosts can walk through doors and fog clouds can flow under + them). Some monsters who can open doors can also use unlocking tools. - The commands `/' and `;' may be used to obtain information - about those monsters who are displayed on the screen. The com- - mand "#name" (by default bound to `C'), allows you to assign a - name to a monster, which may be useful to help distinguish one - from another when multiple monsters are present. Assigning a - name which is just a space will remove any prior name. - The extended command "#chat" can be used to interact with an - adjacent monster. There is no actual dialog (in other words, you - don't get to choose what you'll say), but chatting with some mon- - sters such as a shopkeeper or the Oracle of Delphi can produce - useful results. + NetHack 5.0.0 May 2, 2026 - 6.1. Fighting - If you see a monster and you wish to fight it, just attempt - to walk into it. Many monsters you find will mind their own - business unless you attack them. Some of them are very dangerous - when angered. Remember: discretion is the better part of valor. - In most circumstances, if you attempt to attack a peaceful - monster by moving into its location, you'll be asked to confirm - your intent. By default an answer of `y' acknowledges that in- - tent, which can be error prone if you're using `y' to move. You - can set the paranoid_confirmation option to require a response of - "yes" instead. - If you can't see a monster (if it is invisible, or if you - are blinded), the symbol `I' will be shown when you learn of its - presence. If you attempt to walk into it, you will try to fight - it just like a monster that you can see; of course, if the mon- - ster has moved, you will attack empty air. If you guess that the - monster has moved and you don't wish to fight, you can use the - `m' command to move without fighting; likewise, if you don't re- - member a monster but want to try fighting anyway, you can use the + NetHack Guidebook 37 - NetHack 3.6 February 3, 2023 + And some (giants) can smash doors. + Secret doors are hidden and appear to be ordinary wall (from + inside a room) or solid rock (from outside). You can find them with + the `s' (search) command but it might take multiple tries (possibly + many tries if your luck is poor). Once found they are in all ways + equivalent to normal doors. Mapping magic does not reveal secret + doors. + 5.2. Traps (`^') - NetHack Guidebook 32 + There are traps throughout the dungeon to snare the unwary + intruder. For example, you may suddenly fall into a pit and be stuck + for a few turns trying to climb out (see below). A trap usually won't + appear on your map until you trigger it by moving onto it, you see + someone else trigger it, or you discover it with the `s' (search) com- + mand (multiple attempts are often needed; if your luck is poor, many + attempts might be needed). Wands of secret door detection and spell + of detect unseen also reveal traps within a modest radius but only if + the trap is also within line-of-sight (whether you can see at the time + or not). There is also other magic which can reveal traps. + Monsters can fall prey to traps, too, which can potentially be + used as a defensive strategy. Unfortunately traps can be harmful to + your pet(s) as well. Monsters, including pets, usually will avoid + moving onto a trap which is shown on your map if they have encountered + that type of trap before. + Some traps such as pits, bear traps, and webs hold you in one + place. You can escape by simply trying to move to an adjacent spot + and repeat as needed; eventually you will get free. - `F' command. + Other traps can send you to different locations. Teleporters + send you elsewhere on the same dungeon level. Level teleporters send + you to a random dungeon level, the destination chosen from a few lev- + els lower all the way to the top. These traps choose a new destina- + tion each time they're activated. Trap doors and holes also send you + to another level, but one which is always below the current level. + Usually that will be the next level down but it can be farther. + Unlike (level) teleporters, the destination level of a particular trap + door or hole is persistent, so falling into one will bring you to the + same level each time--though not necessarily the same spot on the + level. Magic portals behave similarly, but with some additional vari- + ation. Some portals are two-way and their remote destination is + always the same: another portal which can take you back. Others are + one-way and send you to a specific destination level but not necessar- + ily to a specific location there. - 6.2. Your pet + There is a special multi-level branch of the dungeon with pre- + mapped levels based on the classic computer game "Sokoban." In that + game, you operate as a warehouse worker who pushes crates around + obstacles to position them at designated locations. In NetHack, the + goal is to push boulders into pits or holes until those traps have all + been nullified, giving access to whatever is beyond them. In the - You start the game with a little dog (`d'), kitten (`f'), or - pony (`u'), which follows you about the dungeon and fights mon- - sters with you. Like you, your pet needs food to survive. Dogs - and cats usually feed themselves on fresh carrion and other - meats; horses need vegetarian food which is harder to come by. - If you're worried about your pet or want to train it, you can - feed it, too, by throwing it food. A properly trained pet can be - very useful under certain circumstances. - Your pet also gains experience from killing monsters, and - can grow over time, gaining hit points and doing more damage. - Initially, your pet may even be better at killing things than - you, which makes pets useful for low-level characters. + NetHack 5.0.0 May 2, 2026 - Your pet will follow you up and down staircases if it is - next to you when you move. Otherwise your pet will be stranded - and may become wild. Similarly, when you trigger certain types - of traps which alter your location (for instance, a trap door - which drops you to a lower dungeon level), any adjacent pet will - accompany you and any non-adjacent pet will be left behind. Your - pet may trigger such traps itself; you will not be carried along - with it even if adjacent at the time. - 6.3. Steeds - Some types of creatures in the dungeon can actually be rid- - den if you have the right equipment and skill. Convincing a wild - beast to let you saddle it up is difficult to say the least. - Many a dungeoneer has had to resort to magic and wizardry in or- - der to forge the alliance. Once you do have the beast under your - control however, you can easily climb in and out of the saddle - with the "#ride" command. Lead the beast around the dungeon when - riding, in the same manner as you would move yourself. It is the - beast that you will see displayed on the map. - Riding skill is managed by the "#enhance" command. See the - section on Weapon proficiency for more information about that. - Use the `a' (apply) command and pick a saddle in your inven- - tory to attempt to put that saddle on an adjacent creature. If - successful, it will be transferred to that creature's inventory. + NetHack Guidebook 38 + - Use the "#loot" command while adjacent to a saddled creature - to try to remove the saddle from that creature. If successful, - it will be transferred to your inventory. - 6.4. Bones levels + Sokoban game, you can only move in the four cardinal compass direc- + tions, and a crate in its final destination blocks further access to + that spot. In the Sokoban levels of NetHack, you can move diagonally + (unless that would let you pass between two neighboring boulders) but + you can only push boulders in the four cardinal directions, and a + boulder which fills a pit or hole removes both the boulder and the + trap so opens up normal access to that spot. With careful foresight, + it is possible to complete all of the levels according to the tradi- + tional rules of Sokoban. (Hint: to solve Sokoban puzzles, you often + need to move things away from their eventual destinations in order to + open up more room to maneuver.) Since NetHack does not support an + undo capability, some allowances are permitted in case you get stuck. + For example, each level has at least one extra boulder. Also, it is + possible to drop everything in order to be able to squeeze into the + same location as a boulder (and then presumably move past it), or to + destroy a boulder with magic or tools, or to create new boulders with + a scroll of earth. However, doing such things will lower your luck + without any specific message given about that. See the Conduct sec- + tion for information about getting feedback for your actions in + Sokoban. - You may encounter the shades and corpses of other adventur- - ers (or even former incarnations of yourself!) and their personal + 5.3. Stairs and ladders (`<', `>') + In general, each level in the dungeon will have a staircase going + up (`<') to the previous level and another going down (`>') to the + next level. There are some exceptions though. For instance, fairly + early in the dungeon you will find a level with two down staircases, + one continuing into the dungeon and the other branching into an area + known as the Gnomish Mines. Those mines eventually hit a dead end, so + after exploring them (if you choose to do so), you'll need to climb + back up to the main dungeon. - NetHack 3.6 February 3, 2023 + When you traverse a set of stairs, or trigger a trap which sends + you to another level, the level you're leaving will be deactivated and + stored in a file on disk. If you're moving to a previously visited + level, it will be loaded from its file on disk and reactivated. If + you're moving to a level which has not yet been visited, it will be + created (from scratch for most random levels, from a template for some + "special" levels, or loaded from the remains of an earlier game for a + "bones" level as briefly described below). Monsters are only active + on the current level; those on other levels are essentially placed + into stasis. + Ordinarily when you climb a set of stairs, you will arrive on the + corresponding staircase at your destination. However, pets (see + below) and some other monsters will follow along if they're close + enough when you travel up or down stairs, and occasionally one of + these creatures will displace you during the climb. When that occurs, + the pet or other monster will arrive on the staircase and you will end + up nearby. + Ladders serve the same purpose as staircases, and the two types + of inter-level connections are nearly indistinguishable during game + play. + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 33 - effects. Ghosts are hard to kill, but easy to avoid, since - they're slow and do little damage. You can plunder the deceased - adventurer's possessions; however, they are likely to be cursed. - Beware of whatever killed the former player; it is probably still - lurking around, gloating over its last victory. - 6.5. Persistence of Monsters + NetHack Guidebook 39 - Monsters (a generic reference which also includes humans and - pets) are only shown while they can be seen or otherwise sensed. - Moving to a location where you can't see or sense a monster any - more will result in it disappearing from your map, similarly if - it is the one who moved rather than you. - However, if you encounter a monster which you can't see or - sense -- perhaps it is invisible and has just tapped you on the - noggin -- a special "remembered, unseen monster" marker will be - displayed at the location where you think it is. That will per- - sist until you have proven that there is no monster there, even - if the unseen monster moves to another location or you move to a - spot where the marker's location ordinarily wouldn't be seen any - more. - 7. Objects + 5.4. Shops and shopping - When you find something in the dungeon, it is common to want - to pick it up. In NetHack, this is accomplished automatically by - walking over the object (unless you turn off the autopickup op- - tion (see below), or move with the `m' prefix (see above)), or - manually by using the `,' command. + Occasionally you will run across a room with a shopkeeper near + the door and many items lying on the floor. You can buy items by + picking them up and then using the `p' command. You can inquire about + the price of an item prior to picking it up by using the "#chat" com- + mand while standing on it. Using an item prior to paying for it will + incur a charge, and the shopkeeper won't allow you to leave the shop + until you have paid any debt you owe. - If you're carrying too many items, NetHack will tell you so - and you won't be able to pick up anything more. Otherwise, it - will add the object(s) to your pack and tell you what you just - picked up. + You can sell items to a shopkeeper by dropping them to the floor + while inside a shop. You will either be offered an amount of gold and + asked whether you're willing to sell, or you'll be told that the shop- + keeper isn't interested (generally, your item needs to be compatible + with the type of merchandise carried by the shop). - As you add items to your inventory, you also add the weight - of that object to your load. The amount that you can carry de- - pends on your strength and your constitution. The stronger and - sturdier you are, the less the additional load will affect you. - There comes a point, though, when the weight of all of that stuff - you are carrying around with you through the dungeon will encum- - ber you. Your reactions will get slower and you'll burn calories - faster, requiring food more frequently to cope with it. Eventu- - ally, you'll be so overloaded that you'll either have to discard - some of what you're carrying or collapse under its weight. + If you drop something in a shop by accident, the shopkeeper will + usually claim ownership without offering any compensation. You'll + have to buy it back if you want to reclaim it. - NetHack will tell you how badly you have loaded yourself. - If you are encumbered, one of the conditions "Burdened", - "Stressed", "Strained", "Overtaxed" or "Overloaded" will be shown - on the bottom line status display. + Shopkeepers sometime run out of money. When that happens, you'll + be offered credit instead of gold when you try to sell something. + Credit can be used to pay for purchases, but it is only good in the + shop where it was obtained; other shopkeepers won't honor it. (If you + happen to find a "credit card" in the dungeon, don't bother trying to + use it in shops; shopkeepers will not accept it.) - When you pick up an object, it is assigned an inventory let- - ter. Many commands that operate on objects must ask you to find + The `$' command, which reports the amount of gold you are carry- + ing, will also show current shop debt or credit, if any. The "Iu" + command lists unpaid items (those which still belong to the shop) if + you are carrying any. The "Ix" command shows an inventory-like dis- + play of any unpaid items which have been used up, along with other + shop fees, if any. + 5.4.1. Shop idiosyncrasies - NetHack 3.6 February 3, 2023 + Several aspects of shop behavior might be unexpected. + * The price of a given item can vary due to a variety of factors. + * A shopkeeper treats the spot immediately inside the door as if it + were outside the shop. + * While the shopkeeper watches you like a hawk, he or she will gener- + ally ignore any other customers. + * If a shop is "closed for inventory," it will not open of its own + accord. - NetHack Guidebook 34 + * Shops do not get restocked with new items, regardless of inventory + depletion. - out which object you want to use. When NetHack asks you to - choose a particular object you are carrying, you are usually pre- - sented with a list of inventory letters to choose from (see Com- - mands, above). - Some objects, such as weapons, are easily differentiated. - Others, like scrolls and potions, are given descriptions which - vary according to type. During a game, any two objects with the - same description are the same type. However, the descriptions - will vary from game to game. - When you use one of these objects, if its effect is obvious, - NetHack will remember what it is for you. If its effect isn't - extremely obvious, you will be asked what you want to call this - type of object so you will recognize it later. You can also use - the "#name" command, for the same purpose at any time, to name - all objects of a particular type or just an individual object. - When you use "#name" on an object which has already been named, - specifying a space as the value will remove the prior name in- - stead of assigning a new one. + NetHack 5.0.0 May 2, 2026 - 7.1. Curses and Blessings - Any object that you find may be cursed, even if the object - is otherwise helpful. The most common effect of a curse is being - stuck with (and to) the item. Cursed weapons weld themselves to - your hand when wielded, so you cannot unwield them. Any cursed - item you wear is not removable by ordinary means. In addition, - cursed arms and armor usually, but not always, bear negative en- - chantments that make them less effective in combat. Other cursed - objects may act poorly or detrimentally in other ways. - Objects can also be blessed. Blessed items usually work - better or more beneficially than normal uncursed items. For ex- - ample, a blessed weapon will do more damage against demons. - Objects which are neither cursed nor blessed are referred to - as uncursed. They could just as easily have been described as - unblessed, but the uncursed designation is what you will see - within the game. A "glass half full versus glass half empty" - situation; make of that what you will. - There are magical means of bestowing or removing curses upon - objects, so even if you are stuck with one, you can still have - the curse lifted and the item removed. Priests and Priestesses - have an innate sensitivity to this property in any object, so - they can more easily avoid cursed objects than other character - roles. + NetHack Guidebook 40 - An item with unknown status will be reported in your inven- - tory with no prefix. An item which you know the state of will be - distinguished in your inventory by the presence of the word - "cursed", "uncursed" or "blessed" in the description of the item. - In some cases "uncursed" will be omitted as being redundant when - NetHack 3.6 February 3, 2023 + 5.5. Movement feedback + Moving around the map usually provides no feedback--other than + drawing the hero at the new location--unless you step on an object or + pile of objects, or on a trap, or attempt to move onto a spot where a + monster is located. There are several options which can be used to + augment the normal feedback. + The pile_limit option controls how many objects can be in a + pile--sharing the same map location--for the game to state "there are + objects here" instead of listing them. The default is 5. Setting it + to 1 would always give that message instead of listing any objects. + Setting it to 0 is a special case which will always list all objects + no matter how big a pile is. Note that the number refers to the count + of separate stacks of objects present rather than the sum of the quan- + tities of those stacks (so 7 arrows or 25 gold pieces will each count + as 1 rather than as 7 and 25, respectively, and total to 2 when both + are at the same location). + The "nopickup" command prefix (default `m') can be used before a + movement direction to step on objects without attempting auto-pickup + and without giving feedback about them. + The mention_walls option controls whether you get feedback if you + try to walk into a wall or solid stone or off the edge of the map. + Normally nothing happens (unless the hero is blind and no wall is + shown, then the wall that is being bumped into will be drawn on the + map). This option also gives feedback when rushing or running stops + for some non-obvious reason. - NetHack Guidebook 35 + The mention_decor option controls whether you get feedback when + walking on "furniture." Normally stepping onto stairs or a fountain + or an altar or various other things doesn't elicit anything unless it + is covered by one or more objects so is obscured on the map. Setting + this option to true will describe such things even when they aren't + obscured. Doorless doorways and open doors aren't considered worthy + of mention; closed doors (if you can move onto their spots) and broken + doors are. Assuming that you're able to do so, moving onto water or + lava or ice will give feedback if not yet on that type of terrain but + not repeat it (unless there has been some intervening message) when + moving from water to another water spot, or lava to lava, or ice to + ice. Moving off of any of those back onto "normal" terrain will give + one message too, unless there is feedback about one or more objects, + in which case the back on land circumstance is implied. + The confirm and safe_pet options control what happens when you + try to move onto a peaceful monster's spot or a tame one's spot. + The "nopickup" command prefix (default `m') is also the move- + without-attacking prefix and can be used to try to step onto a visible + monster's spot without the move being considered an attack (see the + Fighting subsection of Monsters below). The "fight" command prefix + (default `F'; also `-' if number_pad is on) can be used to force an + attack, when guessing where an unseen monster is or when deliberately - enough other information is displayed. The implicit_uncursed op- - tion can be used to control this; toggle it off to have "un- - cursed" be displayed even when that can be deduced from other at- - tributes. - 7.2. Weapons (`)') + NetHack 5.0.0 May 2, 2026 - Given a chance, most monsters in the Mazes of Menace will - gratuitously try to kill you. You need weapons for self-defense - (killing them first). Without a weapon, you do only 1-2 hit - points of damage (plus bonuses, if any). Monk characters are an - exception; they normally do more damage with bare (or gloved) - hands than they do with weapons. - There are wielded weapons, like maces and swords, and thrown - weapons, like arrows and spears. To hit monsters with a weapon, - you must wield it and attack them, or throw it at them. You can - simply elect to throw a spear. To shoot an arrow, you should - first wield a bow, then throw the arrow. Crossbows shoot cross- - bow bolts. Slings hurl rocks and (other) stones (like gems). - Enchanted weapons have a "plus" (or "to hit enhancement" - which can be either positive or negative) that adds to your - chance to hit and the damage you do to a monster. The only way - to determine a weapon's enchantment is to have it magically iden- - tified somehow. Most weapons are subject to some type of damage - like rust. Such "erosion" damage can be repaired. - The chance that an attack will successfully hit a monster, - and the amount of damage such a hit will do, depends upon many - factors. Among them are: type of weapon, quality of weapon (en- - chantment and/or erosion), experience level, strength, dexterity, - encumbrance, and proficiency (see below). The monster's armor - class -- a general defense rating, not necessarily due to wearing - of armor -- is a factor too; also, some monsters are particularly - vulnerable to certain types of weapons. - Many weapons can be wielded in one hand; some require both - hands. When wielding a two-handed weapon, you can not wear a - shield, and vice versa. When wielding a one-handed weapon, you - can have another weapon ready to use by setting things up with - the `x' command, which exchanges your primary (the one being - wielded) and alternate weapons. And if you have proficiency in - the "two weapon combat" skill, you may wield both weapons simul- - taneously as primary and secondary; use the `X' command to engage - or disengage that. Only some types of characters (barbarians, - for instance) have the necessary skill available. Even with that - skill, using two weapons at once incurs a penalty in the chance - to hit your target compared to using just one weapon at a time. + NetHack Guidebook 41 - There might be times when you'd rather not wield any weapon - at all. To accomplish that, wield `-', or else use the `A' com- - mand which allows you to unwield the current weapon in addition - to taking off other worn items. - NetHack 3.6 February 3, 2023 + attacking a peaceful or tame creature. + The run_mode option controls how frequently the map gets redrawn + when moving more than one step in a single command (so when rushing, + running, or traveling). + 5.6. Rogue level + One dungeon level (occurring in mid to late teens of the main + dungeon) is a tribute to the ancestor game hack's inspiration rogue. + It is usually displayed differently from other levels: possibly + in characters instead of tiles, or without line-drawing symbols if + already in characters; also, gold is shown as * rather than $ and + stairs are shown as % rather than < and >. There are some minor dif- + ferences in actual game play: doorways lack doors; a scroll, wand, or + spell of light used in a room lights up the whole room rather than + within a radius around your character. And monsters represented by + lower-case letters aren't randomly generated on the rogue level. - NetHack Guidebook 36 + The slight strangeness of this level is a feature, not a bug.... + 6. Monsters + Monsters you cannot see are not displayed on the screen. Beware! + You may suddenly come upon one in a dark place. Some magic items can + help you locate them before they locate you (which some monsters can + do very well). - Those of you in the audience who are AD&D players, be aware - that each weapon which existed in AD&D does roughly the same dam- - age to monsters in NetHack. Some of the more obscure weapons - (such as the aklys, lucern hammer, and bec-de-corbin) are defined - in an appendix to Unearthed Arcana, an AD&D supplement. + The commands `/' and `;' may be used to obtain information about + those monsters who are displayed on the screen. The command "#name" + (by default bound to `C'), allows you to assign a name to a monster, + which may be useful to help distinguish one from another when multiple + monsters are present. Assigning a name which is just a space will + remove any prior name. - The commands to use weapons are `w' (wield), `t' (throw), - `f' (fire, an alternate way of throwing), `Q' (quiver), `x' (ex- - change), `X' (twoweapon), and "#enhance" (see below). + The extended command "#chat" can be used to interact with an + adjacent monster. There is no actual dialog (in other words, you + don't get to choose what you'll say), but chatting with some monsters + such as a shopkeeper or the Oracle of Delphi can produce useful + results. - 7.2.1. Throwing and shooting + 6.1. Fighting - You can throw just about anything via the `t' command. It - will prompt for the item to throw; picking `?' will list things - in your inventory which are considered likely to be thrown, or - picking `*' will list your entire inventory. After you've chosen - what to throw, you will be prompted for a direction rather than - for a specific target. The distance something can be thrown de- - pends mainly on the type of object and your strength. Arrows can - be thrown by hand, but can be thrown much farther and will be - more likely to hit when thrown while you are wielding a bow. + If you see a monster and you wish to fight it, just attempt to + walk into it. Many monsters you find will mind their own business + unless you attack them. Some of them are very dangerous when angered. + Remember: discretion is the better part of valor. - You can simplify the throwing operation by using the `Q' - command to select your preferred "missile", then using the `f' - command to throw it. You'll be prompted for a direction as - above, but you don't have to specify which item to throw each - time you use `f'. There is also an option, autoquiver, which has - NetHack choose another item to automatically fill your quiver (or - quiver sack, or have at the ready) when the inventory slot used - for `Q' runs out. + In most circumstances, if you attempt to attack a peaceful mon- + ster by moving into its location, you'll be asked to confirm your + intent. By default an answer of `y' acknowledges that intent, which + can be error prone if you're using `y' to move. You can set the para- + noid_confirmation:attack option to require a response of "yes" - Some characters have the ability to fire a volley of multi- - ple items in a single turn. Knowing how to load several rounds - of ammunition at once -- or hold several missiles in your hand -- - and still hit a target is not an easy task. Rangers are among - those who are adept at this task, as are those with a high level - of proficiency in the relevant weapon skill (in bow skill if - you're wielding one to shoot arrows, in crossbow skill if you're - wielding one to shoot bolts, or in sling skill if you're wielding - one to shoot stones). The number of items that the character has - a chance to fire varies from turn to turn. You can explicitly - limit the number of shots by using a numeric prefix before the - `t' or `f' command. For example, "2f" (or "n2f" if using num- - ber_pad mode) would ensure that at most 2 arrows are shot even if - you could have fired 3. If you specify a larger number than - would have been shot ("4f" in this example), you'll just end up - shooting the same number (3, here) as if no limit had been speci- - fied. Once the volley is in motion, all of the items will travel - in the same direction; if the first ones kill a monster, the oth- - ers can still continue beyond that spot. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 42 + instead. + If you can't see a monster (if it is invisible, or if you are + blinded), the symbol `I' will be shown when you learn of its presence. + If you attempt to walk into it, you will try to fight it just like a + monster that you can see; of course, if the monster has moved, you + will attack empty air. If you guess that the monster has moved and + you don't wish to fight, you can use the `m' command to move without + fighting; likewise, if you don't remember a monster but want to try + fighting anyway, you can use the `F' command. - NetHack Guidebook 37 + 6.2. Your pet + You start the game with a little dog (`d'), kitten (`f'), or pony + (`u'), which follows you about the dungeon and fights monsters with + you. Like you, your pet needs food to survive. Dogs and cats usually + feed themselves on fresh carrion and other meats; horses need vegetar- + ian food which is harder to come by. If you're worried about your pet + or want to train it, you can feed it, too, by throwing it food. A + properly trained pet can be very useful under certain circumstances. + Your pet also gains experience from killing monsters, and can + grow over time, gaining hit points and doing more damage. Initially, + your pet may even be better at killing things than you, which makes + pets useful for low-level characters. - 7.2.2. Weapon proficiency + Your pet will follow you up and down staircases if it is next to + you when you move. Otherwise your pet will be stranded and may become + wild. Similarly, when you trigger certain types of traps which alter + your location (for instance, a trap door which drops you to a lower + dungeon level), any adjacent pet will accompany you and any non-adja- + cent pet will be left behind. Your pet may trigger such traps itself; + you will not be carried along with it even if adjacent at the time. - You will have varying degrees of skill in the weapons avail- - able. Weapon proficiency, or weapon skills, affect how well you - can use particular types of weapons, and you'll be able to im- - prove your skills as you progress through a game, depending on - your role, your experience level, and use of the weapons. + 6.3. Steeds - For the purposes of proficiency, weapons have been divided - up into various groups such as daggers, broadswords, and - polearms. Each role has a limit on what level of proficiency a - character can achieve for each group. For instance, wizards can - become highly skilled in daggers or staves but not in swords or - bows. + Some types of creatures in the dungeon can actually be ridden if + you have the right equipment and skill. Convincing a wild beast to + let you saddle it up is difficult to say the least. Many a dungeoneer + has had to resort to magic and wizardry in order to forge the + alliance. Once you do have the beast under your control however, you + can easily climb in and out of the saddle with the "#ride" command. + Lead the beast around the dungeon when riding, in the same manner as + you would move yourself. It is the beast that you will see displayed + on the map. - The "#enhance" extended command is used to review current - weapons proficiency (also spell proficiency) and to choose which - skill(s) to improve when you've used one or more skills enough to - become eligible to do so. The skill rankings are "none" (some- - times also referred to as "restricted", because you won't be able - to advance), "unskilled", "basic", "skilled", and "expert". Re- - stricted skills simply will not appear in the list shown by "#en- - hance". (Divine intervention might unrestrict a particular - skill, in which case it will start at unskilled and be limited to - basic.) Some characters can enhance their barehanded combat or - martial arts skill beyond expert to "master" or "grand master". + Riding skill is managed by the "#enhance" command. See the sec- + tion on Weapon proficiency for more information about that. - Use of a weapon in which you're restricted or unskilled will - incur a modest penalty in the chance to hit a monster and also in - the amount of damage done when you do hit; at basic level, there - is no penalty or bonus; at skilled level, you receive a modest - bonus in the chance to hit and amount of damage done; at expert - level, the bonus is higher. A successful hit has a chance to - boost your training towards the next skill level (unless you've - already reached the limit for this skill). Once such training - reaches the threshold for that next level, you'll be told that - you feel more confident in your skills. At that point you can - use "#enhance" to increase one or more skills. Such skills are - not increased automatically because there is a limit to your to- - tal overall skills, so you need to actively choose which skills - to enhance and which to ignore. + Use the `a' (apply) command and pick a saddle in your inventory + to attempt to put that saddle on an adjacent creature. If successful, + it will be transferred to that creature's inventory. - 7.2.3. Two-Weapon combat - Some characters can use two weapons at once. Setting things - up to do so can seem cumbersome but becomes second nature with - use. To wield two weapons, you need to use the "#twoweapon" com- - mand. But first you need to have a weapon in each hand. (Note - that your two weapons are not fully equal; the one in the hand - you normally wield with is considered primary and the other one - is considered secondary. The most noticeable difference is after - you stop -- or before you begin, for that matter -- wielding two - weapons at once. The primary is your wielded weapon and the sec- - ondary is just an item in your inventory that's been designated - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 38 + NetHack Guidebook 43 - as alternate weapon.) + Use the "#loot" command while adjacent to a saddled creature to + try to remove the saddle from that creature. If successful, it will + be transferred to your inventory. - If your primary weapon is wielded but your off hand is empty - or has the wrong weapon, use the sequence `x', `w', `x' to first - swap your primary into your off hand, wield whatever you want as - secondary weapon, then swap them both back into the intended - hands. If your secondary or alternate weapon is correct but your - primary one is not, simply use `w' to wield the primary. Lastly, - if neither hand holds the correct weapon, use `w', `x', `w' to - first wield the intended secondary, swap it to off hand, and then - wield the primary. + 6.4. Bones levels - The whole process can be simplified via use of the push- - weapon option. When it is enabled, then using `w' to wield some- - thing causes the currently wielded weapon to become your alter- - nate weapon. So the sequence `w', `w' can be used to first wield - the weapon you intend to be secondary, and then wield the one you - want as primary which will push the first into secondary posi- - tion. + You may encounter the shades and corpses of other adventurers (or + even former incarnations of yourself!) and their personal effects. + Ghosts are hard to kill, but easy to avoid, since they're slow and do + little damage. You can plunder the deceased adventurer's possessions; + however, they are likely to be cursed. Beware of whatever killed the + former player; it is probably still lurking around, gloating over its + last victory. - When in two-weapon combat mode, using the `X' command tog- - gles back to single-weapon mode. Throwing or dropping either of - the weapons or having one of them be stolen or destroyed will al- - so make you revert to single-weapon combat. + 6.5. Persistence of Monsters - 7.3. Armor (`[') + Monsters (a generic reference which also includes humans and + pets) are only shown while they can be seen or otherwise sensed. Mov- + ing to a location where you can't see or sense a monster any more will + result in it disappearing from your map, similarly if it is the one + who moved rather than you. - Lots of unfriendly things lurk about; you need armor to pro- - tect yourself from their blows. Some types of armor offer better - protection than others. Your armor class is a measure of this - protection. Armor class (AC) is measured as in AD&D, with 10 be- - ing the equivalent of no armor, and lower numbers meaning better - armor. Each suit of armor which exists in AD&D gives the same - protection in NetHack. Here is an (incomplete) list of the armor - classes provided by various suits of armor: - dragon scale mail 1 - plate mail 3 - crystal plate mail 3 - bronze plate mail 4 - splint mail 4 - banded mail 4 - dwarvish mithril-coat 4 - elven mithril-coat 5 - chain mail 5 - orcish chain mail 6 - scale mail 6 - dragon scales 7 - studded leather armor 7 - ring mail 7 - orcish ring mail 8 - leather armor 8 - leather jacket 9 - no armor 10 + However, if you encounter a monster which you can't see or + sense--perhaps it is invisible and has just tapped you on the noggin-- + a special "remembered, unseen monster" marker will be displayed at the + location where you think it is. That will persist until you have + proven that there is no monster there, even if the unseen monster + moves to another location or you move to a spot where the marker's + location ordinarily wouldn't be seen any more. + 7. Objects + When you find something in the dungeon, it is common to want to + pick it up. In NetHack, this is accomplished by using the `,' com- + mand. If autopickup option is on, you will automatically pick up the + object by walking over, unless you move with the `m' prefix. - NetHack 3.6 February 3, 2023 + If you're carrying too many items, NetHack will tell you so and + you won't be able to pick up anything more. Otherwise, it will add + the object(s) to your pack and tell you what you just picked up. + As you add items to your inventory, you also add the weight of + that object to your load. The amount that you can carry depends on + your strength and your constitution. The stronger and sturdier you + are, the less the additional load will affect you. There comes a + point, though, when the weight of all of that stuff you are carrying + around with you through the dungeon will encumber you. Your reactions + will get slower and you'll burn calories faster, requiring food more + frequently to cope with it. Eventually, you'll be so overloaded that + you'll either have to discard some of what you're carrying or collapse + under its weight. + NetHack will tell you how badly you have loaded yourself. If you + are encumbered, one of the conditions Burdened, Stressed, Strained, + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 39 - You can also wear other pieces of armor (for example hel- - mets, boots, shields, cloaks) to lower your armor class even fur- - ther, but you can only wear one item of each category (one suit - of armor, one cloak, one helmet, one shield, and so on) at a - time. - If a piece of armor is enchanted, its armor protection will - be better (or worse) than normal, and its "plus" (or minus) will - subtract from your armor class. For example, a +1 chain mail - would give you better protection than normal chain mail, lowering - your armor class one unit further to 4. When you put on a piece - of armor, you immediately find out the armor class and any - "plusses" it provides. Cursed pieces of armor usually have nega- - tive enchantments (minuses) in addition to being unremovable. + NetHack Guidebook 44 - Many types of armor are subject to some kind of damage like - rust. Such damage can be repaired. Some types of armor may in- - hibit spell casting. - The commands to use armor are `W' (wear) and `T' (take off). - The `A' command can also be used to take off armor as well as - other worn items. - 7.4. Food (`%') + Overtaxed, or Overloaded will be shown on the bottom line status dis- + play. - Food is necessary to survive. If you go too long without - eating you will faint, and eventually die of starvation. Some - types of food will spoil, and become unhealthy to eat, if not - protected. Food stored in ice boxes or tins ("cans") will usual- - ly stay fresh, but ice boxes are heavy, and tins take a while to - open. + When you pick up an object, it is assigned an inventory letter. + Many commands that operate on objects must ask you to find out which + object you want to use. When NetHack asks you to choose a particular + object you are carrying, you are usually presented with a list of + inventory letters to choose from (see Commands, above). - When you kill monsters, they usually leave corpses which are - also "food." Many, but not all, of these are edible; some also - give you special powers when you eat them. A good rule of thumb - is "you are what you eat." + Some objects, such as weapons, are easily differentiated. Oth- + ers, like scrolls and potions, are given descriptions which vary + according to type. During a game, any two objects with the same + description are the same type. However, the descriptions will vary + from game to game. - Some character roles and some monsters are vegetarian. Veg- - etarian monsters will typically never eat animal corpses, while - vegetarian players can, but with some rather unpleasant side-ef- - fects. + When you use one of these objects, if its effect is obvious, + NetHack will remember what it is for you. If its effect isn't + extremely obvious, you will be asked what you want to call this type + of object so you will recognize it later. You can also use the + "#name" command, for the same purpose at any time, to name all objects + of a particular type or just an individual object. When you use + "#name" on an object which has already been named, specifying a space + as the value will remove the prior name instead of assigning a new + one. - You can name one food item after something you like to eat - with the fruit option. + 7.1. Curses and Blessings - The command to eat food is `e'. + Any object that you find may be cursed, even if the object is + otherwise helpful. The most common effect of a curse is being stuck + with (and to) the item. Cursed weapons weld themselves to your hand + when wielded, so you cannot unwield them. Any cursed item you wear is + not removable by ordinary means. In addition, cursed arms and armor + usually, but not always, bear negative enchantments that make them + less effective in combat. Other cursed objects may act poorly or + detrimentally in other ways. - 7.5. Scrolls (`?') + Objects can also be blessed instead. Blessed items usually work + better or more beneficially than normal uncursed items. For example, + a blessed weapon will do slightly more damage against demons. - Scrolls are labeled with various titles, probably chosen by - ancient wizards for their amusement value (for example "READ ME," - or "THANX MAUD" backwards). Scrolls disappear after you read - them (except for blank ones, without magic spells on them). + Objects which are neither cursed nor blessed are referred to as + uncursed. They could just as easily have been described as unblessed, + but the uncursed designation is what you will see within the game. A + "glass half full versus glass half empty" situation; make of that what + you will. + There are magical means of bestowing or removing curses upon + objects, so even if you are stuck with one, you can still have the + curse lifted and the item removed. Priests and Priestesses have an + innate sensitivity to this property in any object, so they can more + easily avoid cursed objects than other character roles. Dropping + objects onto an altar will reveal their bless or curse state provided + that you can see them land. - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 40 + NetHack Guidebook 45 - One of the most useful of these is the scroll of identify, - which can be used to determine what another object is, whether it - is cursed or blessed, and how many uses it has left. Some ob- - jects of subtle enchantment are difficult to identify without - these. - A mail daemon may run up and deliver mail to you as a scroll - of mail (on versions compiled with this feature). To use this - feature on versions where NetHack mail delivery is triggered by - electronic mail appearing in your system mailbox, you must let - NetHack know where to look for new mail by setting the "MAIL" en- - vironment variable to the file name of your mailbox. You may al- - so want to set the "MAILREADER" environment variable to the file - name of your favorite reader, so NetHack can shell to it when you - read the scroll. On versions of NetHack where mail is randomly - generated internal to the game, these environment variables are - ignored. You can disable the mail daemon by turning off the mail - option. + An item with unknown status will be reported in your inventory + with no prefix. An item which you know the state of will be distin- + guished in your inventory by the presence of the word cursed, + uncursed, or blessed in the description of the item. In some cases + uncursed will be omitted as being redundant when enough other informa- + tion is displayed. The implicit_uncursed option can be used to con- + trol this; toggle it off to have uncursed be displayed even when that + can be deduced from other attributes. - The command to read a scroll is `r'. + Sometimes the bless or curse state of objects is referred to as + their "BUC" attribute, for Blessed, Uncursed, or Cursed state, or + "BUCX" for Blessed, Uncursed, Cursed, or unknown. (The term beatitude + is occasionally used as well.) - 7.6. Potions (`!') + 7.2. Artifacts - Potions are distinguished by the color of the liquid inside - the flask. They disappear after you quaff them. + Some objects have been imbued with special powers and are known + as Artifacts. They have specific types (such as long sword or orcish + dagger) and distinct names such as Giantslayer or Grimtooth. Artifact + weapons typically do more damage than their ordinary counterparts. + Some do extra damage against all monsters, others only against spe- + cific types of monsters so aren't better than regular weapons against + other types. Some confer defensive capabilities when wielded or have + other powers that aren't listed here. - Clear potions are potions of water. Sometimes these are - blessed or cursed, resulting in holy or unholy water. Holy water - is the bane of the undead, so potions of holy water are good - things to throw (`t') at them. It is also sometimes very useful - to dip ("#dip") an object into a potion. + You might find them simply lying on the floor, including but not + limited to inside shops, or be granted as a reward for "#offer" on an + altar to your patron deity. A few might be dropped by monsters, or + might be converted from an ordinary object of the same type via + assigning the right name. Or you might wish for them, if you happen + to be granted a wish, but such wishes can fail. - The command to drink a potion is `q' (quaff). + Some artifacts have a specific alignment, others don't. You + won't obtain aligned ones that have a different alignment from yours + via offering and might get a shock if you attempt to wish for any of + those or find one and attempt to use it. - 7.7. Wands (`/') + Each role has a distinct artifact that is contained in the Quest + dungeon branch. These are commonly known as quest artifacts. All are + aligned and most are non-weapons. They won't be found randomly. - Wands usually have multiple magical charges. Some types of - wands require a direction in which to zap them. You can also zap - them at yourself (just give a `.' or `s' for the direction). Be - warned, however, for this is often unwise. Other types of wands - don't require a direction. The number of charges in a wand is - random and decreases by one whenever you use it. + The `\' and ``a' commands will list artifacts that you have fully + identified (knowing the name and item type isn't sufficient). - When the number of charges left in a wand becomes zero, at- - tempts to use the wand will usually result in nothing happening. - Occasionally, however, it may be possible to squeeze the last few - mana points from an otherwise spent wand, destroying it in the - process. A wand may be recharged by using suitable magic, but - doing so runs the risk of causing it to explode. The chance for - such an explosion starts out very small and increases each time - the wand is recharged. + 7.3. Relics - In a truly desperate situation, when your back is up against - the wall, you might decide to go for broke and break your wand. + There are three unique items that are named and have limited spe- + cial powers but aren't classified as artifacts. Each is guarded by a + particular monster and you'll need to collect all three for use late + in the game. They are the Bell of Opening, the Book of the Dead, and + the Candelabrum of Invocation. Their corresponding descriptions when + not yet identified are silver bell, papyrus spellbook, and cande- + labrum. - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 41 + NetHack Guidebook 46 - This is not for the faint of heart. Doing so will almost cer- - tainly cause a catastrophic release of magical energies. - When you have fully identified a particular wand, inventory - display will include additional information in parentheses: the - number of times it has been recharged followed by a colon and - then by its current number of charges. A current charge count of - -1 is a special case indicating that the wand has been cancelled. + 7.4. Weapons (`)') - The command to use a wand is `z' (zap). To break one, use - the `a' (apply) command. + Given a chance, most monsters in the Mazes of Menace will gratu- + itously try to kill you. You need weapons for self-defense (killing + them first). Without a weapon, you do only 1-2 hit points of damage + (plus bonuses, if any). Monk characters are an exception; they nor- + mally do more damage with bare (or gloved) hands than they do with + weapons. - 7.8. Rings (`=') + There are wielded weapons, like maces and swords, and thrown + weapons, like arrows and spears. To hit monsters with a weapon, you + must wield it and attack them, or throw it at them. You can simply + elect to throw a spear. To shoot an arrow, you should first wield a + bow, then throw the arrow. Crossbows shoot crossbow bolts. Slings + hurl rocks and (other) stones (like gems). - Rings are very useful items, since they are relatively per- - manent magic, unlike the usually fleeting effects of potions, - scrolls, and wands. + Enchanted weapons have a "plus" (or "to hit enhancement" which + can be either positive or negative) that adds to your chance to hit + and the damage you do to a monster. The only way to determine a + weapon's enchantment is to have it magically identified somehow. Most + weapons are subject to some type of damage like rust. Such "erosion" + damage can be repaired. - Putting on a ring activates its magic. You can wear only - two rings, one on each ring finger. + The chance that an attack will successfully hit a monster, and + the amount of damage such a hit will do, depends upon many factors. + Among them are: type of weapon, quality of weapon (enchantment and/or + erosion), experience level, strength, dexterity, encumbrance, and pro- + ficiency (see below). The monster's armor class--a general defense + rating, not necessarily due to wearing of armor--is a factor too; + also, some monsters are particularly vulnerable to certain types of + weapons. - Most rings also cause you to grow hungry more rapidly, the - rate varying with the type of ring. + Many weapons can be wielded in one hand; some require both hands. + When wielding a two-handed weapon, you can not wear a shield, and vice + versa. When wielding a one-handed weapon, you can have another weapon + ready to use by setting things up with the `x' command, which + exchanges your primary (the one being wielded) and alternate weapons. + And if you have proficiency in the "two weapon combat" skill, you may + wield both weapons simultaneously as primary and secondary; use the + `X' command to engage or disengage that. Only some types of charac- + ters (barbarians, for instance) have the necessary skill available. + Even with that skill, using two weapons at once incurs a penalty in + the chance to hit your target compared to using just one weapon at a + time. - The commands to use rings are `P' (put on) and `R' (remove). + There might be times when you'd rather not wield any weapon at + all. To accomplish that, wield `-', or else use the `A' command which + allows you to unwield the current weapon in addition to taking off + other worn items. - 7.9. Spellbooks (`+') + Those of you in the audience who are AD&D players, be aware that + each weapon which existed in AD&D does roughly the same damage to mon- + sters in NetHack. Some of the more obscure weapons (such as the + aklys, lucern hammer, and bec-de-corbin) are defined in an appendix to - Spellbooks are tomes of mighty magic. When studied with the - `r' (read) command, they transfer to the reader the knowledge of - a spell (and therefore eventually become unreadable) -- unless - the attempt backfires. Reading a cursed spellbook or one with - mystic runes beyond your ken can be harmful to your health! - A spell (even when learned) can also backfire when you cast - it. If you attempt to cast a spell well above your experience - level, or if you have little skill with the appropriate spell - type, or cast it at a time when your luck is particularly bad, - you can end up wasting both the energy and the time required in - casting. + NetHack 5.0.0 May 2, 2026 - Casting a spell calls forth magical energies and focuses - them with your naked mind. Some of the magical energy released - comes from within you. Casting temporarily drains your magical - power, which will slowly be recovered, and causes you to need ad- - ditional food. Casting of spells also requires practice. With - practice, your skill in each category of spell casting will im- - prove. Over time, however, your memory of each spell will dim, - and you will need to relearn it. - Some spells require a direction in which to cast them, simi- - lar to wands. To cast one at yourself, just give a `.' or `s' - for the direction. A few spells require you to pick a target lo- - cation rather than just specify a particular direction. Other - NetHack 3.6 February 3, 2023 + NetHack Guidebook 47 + Unearthed Arcana, an AD&D supplement. - NetHack Guidebook 42 + Some interfaces support the weaponstatus option. When it is + enabled, an extra status condition is displayed, describing the cur- + rently wielded weapon. + The commands to use weapons are `w' (wield), `t' (throw), `f' + (fire), `Q' (quiver), `x' (exchange), `X' (twoweapon), and "#enhance" + (see below). + 7.4.1. Throwing and shooting - spells don't require any direction or target. + You can throw just about anything via the `t' command. It will + prompt for the item to throw; picking `?' will list things in your + inventory which are considered likely to be thrown, or picking `*' + will list your entire inventory. After you've chosen what to throw, + you will be prompted for a direction rather than for a specific tar- + get. The distance something can be thrown depends mainly on the type + of object and your strength. Arrows can be thrown by hand, but can be + thrown much farther and will be more likely to hit when thrown while + you are wielding a bow. - Just as weapons are divided into groups in which a character - can become proficient (to varying degrees), spells are similarly - grouped. Successfully casting a spell exercises its skill group; - using the "#enhance" command to advance a sufficiently exercised - skill will affect all spells within the group. Advanced skill - may increase the potency of spells, reduce their risk of failure - during casting attempts, and improve the accuracy of the estimate - for how much longer they will be retained in your memory. Skill - slots are shared with weapons skills. (See also the section on - "Weapon proficiency".) + Some weapons will return when thrown. A boomerang--provided it + fails to hit anything--is an obvious example. If an aklys (thonged + club) is thrown while it is wielded, it will return even when it hits + something. A sufficiently strong hero can throw the warhammer Mjoll- + nir; when thrown by a Valkyrie it will return too. However, aklyses + and Mjollnir occasionally fail to return. Returning thrown objects + occasionally fail to be caught, sometimes even hitting the thrower, + but when caught they become re-wielded. - Casting a spell also requires flexible movement, and wearing - various types of armor may interfere with that. + You can simplify the throwing operation by using the `Q' command + to select your preferred "missile", then using the `f' command to + throw it. You'll be prompted for a direction as above, but you don't + have to specify which item to throw each time you use `f'. There is + also an option, autoquiver, which has NetHack choose another item to + automatically fill your quiver (or quiver sack, or have at the ready) + when the inventory slot used for `Q' runs out. If your quiver is + empty, autoquiver is false, and you are wielding a weapon which + returns when thrown, you will throw that weapon instead of filling the + quiver. The fire command also has extra assistance, if fireassist is + on it will try to wield a launcher matching the ammo in the quiver. - The command to read a spellbook is the same as for scrolls, - `r' (read). The `+' command lists each spell you know along with - its level, skill category, chance of failure when casting, and an - estimate of how strongly it is remembered. The `Z' (cast) com- - mand casts a spell. + Some characters have the ability to throw or shoot a volley of + multiple items (from the same stack) in a single action. Knowing how + to load several rounds of ammunition at once--or hold several missiles + in your hand--and still hit a target is not an easy task. Rangers are + among those who are adept at this task, as are those with a high level + of proficiency in the relevant weapon skill (in bow skill if you're + wielding one to shoot arrows, in crossbow skill if you're wielding one + to shoot bolts, or in sling skill if you're wielding one to shoot + stones). The number of items that the character has a chance to fire + varies from turn to turn. You can explicitly limit the number of + shots by using a numeric prefix before the `t' or `f' command. For - 7.10. Tools (`(') - Tools are miscellaneous objects with various purposes. Some - tools have a limited number of uses, akin to wand charges. For - example, lamps burn out after a while. Other tools are contain- - ers, which objects can be placed into or taken out of. + NetHack 5.0.0 May 2, 2026 - The command to use a tool is `a' (apply). - 7.10.1. Containers - You may encounter bags, boxes, and chests in your travels. - A tool of this sort can be opened with the "#loot" extended com- - mand when you are standing on top of it (that is, on the same - floor spot), or with the `a' (apply) command when you are carry- - ing it. However, chests are often locked, and are in any case - unwieldy objects. You must set one down before unlocking it by - using a key or lock-picking tool with the `a' (apply) command, by - kicking it with the `^D' command, or by using a weapon to force - the lock with the "#force" extended command. - Some chests are trapped, causing nasty things to happen when - you unlock or open them. You can check for and try to deactivate - traps with the "#untrap" extended command. - 7.11. Amulets (`"') + NetHack Guidebook 48 - Amulets are very similar to rings, and often more powerful. - Like rings, amulets have various magical properties, some benefi- - cial, some harmful, which are activated by putting them on. + example, "2f" (or "n2f" if using number_pad mode) would ensure that at + most 2 arrows are shot even if you could have fired 3. If you specify + a larger number than would have been shot ("4f" in this example), + you'll just end up shooting the same number (3, here) as if no limit + had been specified. Once the volley is in motion, all of the items + will travel in the same direction; if the first ones kill a monster, + the others can still continue beyond that spot. + 7.4.2. Weapon proficiency - NetHack 3.6 February 3, 2023 + You will have varying degrees of skill in the weapons available. + Weapon proficiency, or weapon skills, affect how well you can use par- + ticular types of weapons, and you'll be able to improve your skills as + you progress through a game, depending on your role, your experience + level, and use of the weapons. + For the purposes of proficiency, weapons have been divided up + into various groups such as daggers, broadswords, and polearms. Each + role has a limit on what level of proficiency a character can achieve + for each group. For instance, wizards can become highly skilled in + daggers or staves but not in swords or bows. + The "#enhance" extended command is used to review current weapons + proficiency (also spell proficiency) and to choose which skill(s) to + improve when you've used one or more skills enough to become eligible + to do so. The skill rankings are "none" (sometimes also referred to + as "restricted", because you won't be able to advance), "unskilled", + "basic", "skilled", and "expert". Restricted skills simply will not + appear in the list shown by "#enhance". (Divine intervention might + unrestrict a particular skill, in which case it will start at + unskilled and be limited to basic.) Some characters can enhance their + barehanded combat or martial arts skill beyond expert to "master" or + "grand master". + Use of a weapon in which you're restricted or unskilled will + incur a modest penalty in the chance to hit a monster and also in the + amount of damage done when you do hit; at basic level, there is no + penalty or bonus; at skilled level, you receive a modest bonus in the + chance to hit and amount of damage done; at expert level, the bonus is + higher. A successful hit has a chance to boost your training towards + the next skill level (unless you've already reached the limit for this + skill). Once such training reaches the threshold for that next level, + you'll be told that you feel more confident in your skills. At that + point you can use "#enhance" to increase one or more skills. Such + skills are not increased automatically because there is a limit to + your total overall skills, so you need to actively choose which skills + to enhance and which to ignore. + + 7.4.3. Two-Weapon combat + + Some characters can use two weapons at once. Setting things up + to do so can seem cumbersome but becomes second nature with use. To + wield two weapons, you need to use the "#twoweapon" command. But + first you need to have a weapon in each hand. (Note that your two - NetHack Guidebook 43 + NetHack 5.0.0 May 2, 2026 - Only one amulet may be worn at a time, around your neck. - The commands to use amulets are the same as for rings, `P' - (put on) and `R' (remove). - 7.12. Gems (`*') + NetHack Guidebook 49 - Some gems are valuable, and can be sold for a lot of gold. - They are also a far more efficient way of carrying your riches. - Valuable gems increase your score if you bring them with you when - you exit. - Other small rocks are also categorized as gems, but they are - much less valuable. All rocks, however, can be used as projec- - tile weapons (if you have a sling). In the most desperate of - cases, you can still throw them by hand. - 7.13. Large rocks (``') + weapons are not fully equal; the one in the hand you normally wield + with is considered primary and the other one is considered secondary. + The most noticeable difference is after you stop--or before you begin, + for that matter--wielding two weapons at once. The primary is your + wielded weapon and the secondary is just an item in your inventory + that's been designated as alternate weapon.) - Statues and boulders are not particularly useful, and are - generally heavy. It is rumored that some statues are not what - they seem. + If your primary weapon is wielded but your off hand is empty or + has the wrong weapon, use the sequence `x', `w', `x' to first swap + your primary into your off hand, wield whatever you want as secondary + weapon, then swap them both back into the intended hands. If your + secondary or alternate weapon is correct but your primary one is not, + simply use `w' to wield the primary. Lastly, if neither hand holds + the correct weapon, use `w', `x', `w' to first wield the intended sec- + ondary, swap it to off hand, and then wield the primary. - Very large humanoids (giants and their ilk) have been known - to use boulders as weapons. + The whole process can be simplified via use of the pushweapon + option. When it is enabled, then using `w' to wield something causes + the currently wielded weapon to become your alternate weapon. So the + sequence `w', `w' can be used to first wield the weapon you intend to + be secondary, and then wield the one you want as primary which will + push the first into secondary position. - For some configurations of the program, statues are no - longer shown as ``' but by the letter representing the monster - they depict instead. + When in two-weapon combat mode, using the `X' command toggles + back to single-weapon mode. Throwing or dropping either of the weap- + ons or having one of them be stolen or destroyed will also make you + revert to single-weapon combat. - 7.14. Gold (`$') + 7.5. Armor (`[') - Gold adds to your score, and you can buy things in shops - with it. There are a number of monsters in the dungeon that may - be influenced by the amount of gold you are carrying (shopkeepers - aside). + Lots of unfriendly things lurk about; you need armor to protect + yourself from their blows. Some types of armor offer better protec- + tion than others. Your armor class is a measure of this protection. + Armor class (AC) is measured as in AD&D, with 10 being the equivalent + of no armor, and lower numbers meaning better armor. Each suit of + armor which exists in AD&D gives the same protection in NetHack. - 7.15. Persistence of Objects + Here is a list of the armor class values provided by suits of + armor: + Dragon scale mail 1 + Plate mail, Crystal plate mail 3 + Bronze plate mail, Splint mail, + Banded mail, Dwarvish mithril-coat 4 + Chain mail, Elven mithril-coat 5 + Scale mail, Orcish chain mail 6 + Ring mail, Studded leather armor, + Dragon scales 7 + Leather armor, Orcish ring mail 8 + Leather jacket 9 + none 10 - Normally, if you have seen an object at a particular map lo- - cation and move to another location where you can't directly see - that object any more, it will continue to be displayed on your - map. That remains the case even if it is not actually there any - more -- perhaps a monster has picked it up or it has rotted away - -- until you can see or feel that location again. One notable - exception is that if the object gets covered by the "remembered, - unseen monster" marker. When that marker is later removed after - you've verified that no monster is there, you will forget that - there was any object there regardless of whether the unseen mon- - ster actually took the object. If the object is still there, - then once you see or feel that location again you will re-discov- - er the object and resume remembering it. + You can also wear other pieces of armor (cloak over suit, shirt + under suit, helmet, gloves, boots, shield) to lower your armor class + even further. Most of these provide a one or two point improvement to + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 50 - NetHack Guidebook 44 + AC (making the overall value smaller and eventually negative) but can + also be enchanted. Shirts are an exception; they don't provide any + protection unless enchanted. Some cloaks also don't improve AC when + unenchanted but all cloaks offer some protection against rust or cor- + rosion to suits worn under them and against some monster touch + attacks. + If a piece of armor is enchanted, its armor protection will be + better (or worse) than normal, and its "plus" (or minus) will subtract + from your armor class. For example, a +1 chain mail would give you + better protection than normal chain mail, lowering your armor class + one unit further to 4. When you put on a piece of armor, you immedi- + ately find out the armor class and any "plusses" it provides. Cursed + pieces of armor usually have negative enchantments (minuses) in addi- + tion to being unremovable. - The situation is the same for a pile of objects, except that - only the top item of the pile is displayed. The hilite_pile op- - tion can be enabled in order to show an item differently when it - is the top one of a pile. + Many types of armor are subject to some kind of damage like rust. + Such damage can be repaired. Some types of armor may inhibit spell + casting. - 8. Conduct + The nudist option can be set (prior to game start) to attempt to + play the entire game without wearing any armor (a self-imposed chal- + lenge which is extremely difficult to accomplish). - As if winning NetHack were not difficult enough, certain - players seek to challenge themselves by imposing restrictions on - the way they play the game. The game automatically tracks some - of these challenges, which can be checked at any time with the - #conduct command or at the end of the game. When you perform an - action which breaks a challenge, it will no longer be listed. - This gives players extra "bragging rights" for winning the game - with these challenges. Note that it is perfectly acceptable to - win the game without resorting to these restrictions and that it - is unusual for players to adhere to challenges the first time - they win the game. + Some interfaces support the armorstatus option. When it is + enabled, an extra status condition is displayed, summarizing currently + worn armor. - Several of the challenges are related to eating behavior. - The most difficult of these is the foodless challenge. Although - creatures can survive long periods of time without food, there is - a physiological need for water; thus there is no restriction on - drinking beverages, even if they provide some minor food bene- - fits. Calling upon your god for help with starvation does not - violate any food challenges either. + The commands to use armor are `W' (wear) and `T' (take off). The + `A' command can be used to take off armor as well as other worn items. + Also, `P' (put on) and `R' (remove) which are normally for accessories + can be used for armor, but pieces of armor won't be shown as likely + candidates in a prompt for choosing what to put on or remove. - A strict vegan diet is one which avoids any food derived - from animals. The primary source of nutrition is fruits and veg- - etables. The corpses and tins of blobs (`b'), jellies (`j'), and - fungi (`F') are also considered to be vegetable matter. Certain - human food is prepared without animal products; namely, lembas - wafers, cram rations, food rations (gunyoki), K-rations, and C- - rations. Metal or another normally indigestible material eaten - while polymorphed into a creature that can digest it is also con- - sidered vegan food. Note however that eating such items still - counts against foodless conduct. + 7.6. Food (`%') - Vegetarians do not eat animals; however, they are less se- - lective about eating animal byproducts than vegans. In addition - to the vegan items listed above, they may eat any kind of pudding - (`P') other than the black puddings, eggs and food made from eggs - (fortune cookies and pancakes), food made with milk (cream pies - and candy bars), and lumps of royal jelly. Monks are expected to - observe a vegetarian diet. + Food is necessary to survive. If you go too long without eating + you will faint, and eventually die of starvation. Some types of food + will spoil, and become unhealthy to eat, if not protected. Food + stored in ice boxes or tins ("cans") will usually stay fresh, but ice + boxes are heavy, and tins take a while to open. - Eating any kind of meat violates the vegetarian, vegan, and - foodless conducts. This includes tripe rations, the corpses or - tins of any monsters not mentioned above, and the various other - chunks of meat found in the dungeon. Swallowing and digesting a - monster while polymorphed is treated as if you ate the creature's - corpse. Eating leather, dragon hide, or bone items while poly- - morphed into a creature that can digest it, or eating monster - brains while polymorphed into a mind flayer, is considered eating + When you kill monsters, they usually leave corpses which are also + "food." Many, but not all, of these are edible; some also give you + special powers when you eat them. A good rule of thumb is "you are + what you eat." + Some character roles and some monsters are vegetarian. Vegetar- + ian monsters will typically never eat animal corpses, while vegetarian + players can, but with some rather unpleasant side-effects. - NetHack 3.6 February 3, 2023 + You can name one food item after something you like to eat with + the fruit option. + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 45 - an animal, although wax is only an animal byproduct. + NetHack Guidebook 51 - Regardless of conduct, there will be some items which are - indigestible, and others which are hazardous to eat. Using a - swallow-and-digest attack against a monster is equivalent to eat- - ing the monster's corpse. Please note that the term "vegan" is - used here only in the context of diet. You are still free to - choose not to use or wear items derived from animals (e.g. - leather, dragon hide, bone, horns, coral), but the game will not - keep track of this for you. Also note that "milky" potions may - be a translucent white, but they do not contain milk, so they are - compatible with a vegan diet. Slime molds or player-defined - "fruits", although they could be anything from "cherries" to - "pork chops", are also assumed to be vegan. - An atheist is one who rejects religion. This means that you - cannot #pray, #offer sacrifices to any god, #turn undead, or - #chat with a priest. Particularly selective readers may argue - that playing Monk or Priest characters should violate this con- - duct; that is a choice left to the player. Offering the Amulet - of Yendor to your god is necessary to win the game and is not - counted against this conduct. You are also not penalized for be- - ing spoken to by an angry god, priest(ess), or other religious - figure; a true atheist would hear the words but attach no special - meaning to them. - Most players fight with a wielded weapon (or tool intended - to be wielded as a weapon). Another challenge is to win the game - without using such a wielded weapon. You are still permitted to - throw, fire, and kick weapons; use a wand, spell, or other type - of item; or fight with your hands and feet. + The command to eat food is `e'. - In NetHack, a pacifist refuses to cause the death of any - other monster (i.e. if you would get experience for the death). - This is a particularly difficult challenge, although it is still - possible to gain experience by other means. + 7.7. Scrolls (`?') - An illiterate character cannot read or write. This includes - reading a scroll, spellbook, fortune cookie message, or t-shirt; - writing a scroll; or making an engraving of anything other than a - single "X" (the traditional signature of an illiterate person). - Reading an engraving, or any item that is absolutely necessary to - win the game, is not counted against this conduct. The identity - of scrolls and spellbooks (and knowledge of spells) in your - starting inventory is assumed to be learned from your teachers - prior to the start of the game and isn't counted. + Scrolls are labeled with various titles, probably chosen by + ancient wizards for their amusement value (for example "READ ME," or + "THANX MAUD" backwards). Scrolls disappear after you read them + (except for blank ones, without magic spells on them). - There are several other challenges tracked by the game. It - is possible to eliminate one or more species of monsters by geno- - cide; playing without this feature is considered a challenge. - When the game offers you an opportunity to genocide monsters, you - may respond with the monster type "none" if you want to decline. - You can change the form of an item into another item of the same - type ("polypiling") or the form of your own body into another + One of the most useful of these is the scroll of identify, which + can be used to determine what another object is, whether it is cursed + or blessed, and how many uses it has left. Some objects of subtle + enchantment are difficult to identify without these. + A scroll whose label is known can be read even when the hero is + blind. If a scroll has been discovered, it will be listed in inven- + tory by type rather than by label, but the label is known in that sit- + uation even though it isn't shown. - NetHack 3.6 February 3, 2023 + Many scrolls produce a different effect from usual if they are + blessed or cursed, or read while the hero is confused. + A mail daemon may run up and deliver mail to you as a scroll of + mail (on versions compiled with this feature). To use this feature on + versions where NetHack mail delivery is triggered by electronic mail + appearing in your system mailbox, you must let NetHack know where to + look for new mail by setting the "MAIL" environment variable to the + file name of your mailbox. You may also want to set the "MAILREADER" + environment variable to the file name of your favorite reader, so + NetHack can shell to it when you read the scroll. On versions of + NetHack where mail is randomly generated internal to the game, these + environment variables are ignored. You can disable the mail daemon by + turning off the mail option. + The command to read a scroll is `r'. + 7.8. Potions (`!') + Potions are distinguished by the color of the liquid inside the + flask. They disappear after you quaff them. - NetHack Guidebook 46 + Clear potions are potions of water. Sometimes these are blessed + or cursed, resulting in holy or unholy water. Holy water is the bane + of the undead, so potions of holy water are good things to throw (`t') + at them. It is also sometimes very useful to dip ("#dip") an object + into a potion. + The command to drink a potion is `q' (quaff). + 7.9. Wands (`/') - creature ("polyself") by wand, spell, or potion of polymorph; - avoiding these effects are each considered challenges. Polymor- - phing monsters, including pets, does not break either of these - challenges. Finally, you may sometimes receive wishes; a game - without an attempt to wish for any items is a challenge, as is a - game without wishing for an artifact (even if the artifact imme- - diately disappears). When the game offers you an opportunity to - make a wish for an item, you may choose "nothing" if you want to - decline. + Wands usually have multiple magical charges. Some types of wands + require a direction in which to zap them. You can also zap them at + yourself (just give a `.' or `s' for the direction). Be warned, how- - 9. Options - Due to variations in personal tastes and conceptions of how - NetHack should do things, there are options you can set to change - how NetHack behaves. + NetHack 5.0.0 May 2, 2026 - 9.1. Setting the options - Options may be set in a number of ways. Within the game, - the `O' command allows you to view all options and change most of - them. You can also set options automatically by placing them in - a configuration file, or in the NETHACKOPTIONS environment vari- - able. Some versions of NetHack also have front-end programs that - allow you to set options before starting the game or a global - configuration for system administrators. - 9.2. Using a configuration file - The default name of the configuration file varies on differ- - ent operating systems. - On UNIX, Linux, and Mac OS X it is ".nethackrc" in the us- - er's home directory. The file may not exist, but it is a normal - ASCII text file and can be created with any text editor. + NetHack Guidebook 52 - On Windows, it is ".nethackrc" in the folder "\%USERPRO- - FILE%\NetHack\(rq. The file may not exist, but it is a normal - ASCII text file can can be created with any text editor. After - running NetHack for the first time, you should find a default - template for the configuration file named ".nethackrc.template" - in "\%USERPROFILE%\NetHack\(rq. If you had not created the con- - figuration file, NetHack will create the configuration file for - you using the default template file. - On MS-DOS, it is "defaults.nh" in the same folder as - nethack.exe. - Any line in the configuration file starting with `#' is - treated as a comment. Empty lines are ignored. + ever, for this is often unwise. Other types of wands don't require a + direction. The number of charges in a wand is random and decreases by + one whenever you use it. - Any line beginning with `[' and ending in `]' is considered - a section marker. The text between the square brackets is the - section name. Lines after a section marker belong to that sec- - tion, and are ignored unless a CHOOSE statement was used to + When the number of charges left in a wand becomes zero, attempts + to use the wand will usually result in nothing happening. Occasion- + ally, however, it may be possible to squeeze the last few mana points + from an otherwise spent wand, destroying it in the process. A wand + may be recharged by using suitable magic, but doing so runs the risk + of causing it to explode. The chance for such an explosion starts out + very small and increases each time the wand is recharged. + In a truly desperate situation, when your back is up against the + wall, you might decide to go for broke and break your wand. This is + not for the faint of heart. Doing so will almost certainly cause a + catastrophic release of magical energies. - NetHack 3.6 February 3, 2023 + When you have fully identified a particular wand, inventory dis- + play will include additional information in parentheses: the number of + times it has been recharged followed by a colon and then by its cur- + rent number of charges. A current charge count of -1 is a special + case indicating that the wand has been cancelled. + The command to use a wand is `z' (zap). To break one, use the + `a' (apply) command. + 7.10. Rings (`=') + Rings are very useful items, since they are relatively permanent + magic, unlike the usually fleeting effects of potions, scrolls, and + wands. + Putting on a ring activates its magic. You can wear at most two + rings at any time, one on the ring finger of each hand. - NetHack Guidebook 47 + Most worn rings also cause you to grow hungry more rapidly, the + rate varying with the type of ring. + When wearing gloves, rings are worn underneath. If the gloves + are cursed, rings cannot be put on and any already being worn cannot + be removed. When worn gloves aren't cursed, you don't have to manu- + ally take them off before putting on or removing a ring and then re- + wear them after. That's done implicitly to avoid unnecessary tedium. + The commands to use rings are `P' (put on) and `R' (remove). + `A', `W', and `T' can also be used; see Amulets. - select that section. Section names are case insensitive. + 7.11. Spellbooks (`+') - You can use different configuration statements in the file, - some of which can be used multiple times. In general, the state- - ments are written in capital letters, followed by an equals sign, - followed by settings particular to that statement. + Spellbooks are tomes of mighty magic. When studied with the `r' + (read) command, they transfer to the reader the knowledge of a spell + (and therefore eventually become unreadable)--unless the attempt back- + fires. Reading a cursed spellbook or one with mystic runes beyond + your ken can be harmful to your health! - Here is a list of allowed statements: - OPTIONS - There are two types of options, boolean and compound options. - Boolean options toggle a setting on or off, while compound op- - tions take more diverse values. Prefix a boolean option with - "no" or `!' to turn it off. For compound options, the option - name and value are separated by a colon. Some options are per- - sistent, and apply only to new games. You can specify multiple - OPTIONS statements, and multiple options separated by commas in - a single OPTIONS statement. (Comma separated options are pro- - cessed from right to left.) + NetHack 5.0.0 May 2, 2026 - Example: - OPTIONS=dogname:Fido - OPTIONS=!legacy,autopickup,pickup_types:$"=/!?+ - HACKDIR - Default location of files NetHack needs. On Windows HACKDIR - defaults to the location of the NetHack.exe or NetHackw.exe - file so setting HACKDIR to override that is not usually neces- - sary or recommended. - LEVELDIR - The location that in-progress level files are stored. Defaults - to HACKDIR, must be writable. - SAVEDIR - The location where saved games are kept. Defaults to HACKDIR, - must be writable. + NetHack Guidebook 53 - BONESDIR - The location that bones files are kept. Defaults to HACKDIR, - must be writable. - LOCKDIR - The location that file synchronization locks are stored. - Defaults to HACKDIR, must be writable. - TROUBLEDIR - The location that a record of game aborts and self-diagnosed - game problems is kept. Defaults to HACKDIR, must be writable. + A spell (even when learned) can also backfire when you cast it. + If you attempt to cast a spell well above your experience level, or if + you have little skill with the appropriate spell type, or cast it at a + time when your luck is particularly bad, you can end up wasting both + the energy and the time required in casting. - AUTOCOMPLETE - Enable or disable an extended command autocompletion. Autocom- - pletion has no effect for the X11 windowport. You can specify + Casting a spell calls forth magical energies and focuses them + with your naked mind. Some of the magical energy released comes from + within you. Casting temporarily drains your magical power, which will + slowly be recovered, and causes you to need additional food. Casting + of spells also requires practice. With practice, your skill in each + category of spell casting will improve. Over time, however, your mem- + ory of each spell will dim, and you will need to relearn it. + Some spells require a direction in which to cast them, similar to + wands. To cast one at yourself, just give a `.' or `s' for the direc- + tion. A few spells require you to pick a target location rather than + just specify a particular direction. Other spells don't require any + direction or target. - NetHack 3.6 February 3, 2023 + Just as weapons are divided into groups in which a character can + become proficient (to varying degrees), spells are similarly grouped. + Successfully casting a spell exercises its skill group; using the + "#enhance" command to advance a sufficiently exercised skill will + affect all spells within the group. Advanced skill may increase the + potency of spells, reduce their risk of failure during casting + attempts, and improve the accuracy of the estimate for how much longer + they will be retained in your memory. Skill slots are shared with + weapons skills. (See also the section on "Weapon proficiency".) + Casting a spell also requires flexible movement, and wearing var- + ious types of armor may interfere with that. + The command to read a spellbook is the same as for scrolls, `r' + (read). The `+' command lists each spell you know along with its + level, skill category, chance of failure when casting, and an estimate + of how strongly it is remembered. The `Z' (cast) command casts a + spell. + 7.12. Tools (`(') + Tools are miscellaneous objects with various purposes. Some + tools have a limited number of uses, akin to wand charges. For exam- + ple, lamps burn out after a while. Other tools are containers, which + objects can be placed into or taken out of. - NetHack Guidebook 48 + Some tools (such as a blindfold) can be worn and can be put on + and removed like other accessories (rings, amulets); see Amulets. + Other tools (such as pick-axe) can be wielded as weapons in addition + to being applied for their usual purpose, and in some cases (again, + pick-axe) become wielded as a weapon even when applied. + The blind option can be set (prior to game start) to attempt to + play the entire game without being able to see (a self-imposed chal- - multiple autocompletions. To enable autocompletion, list the - extended command. Prefix the command with "!" to disable the - autocompletion for that command. + NetHack 5.0.0 May 2, 2026 - Example: - AUTOCOMPLETE=zap,!annotate - AUTOPICKUP_EXCEPTION - Set exceptions to the pickup_types option. See the "Configur- - ing Autopickup Exceptions" section. - BINDINGS - Change the key bindings of some special keys, menu accelera- - tors, or extended commands. You can specify multiple bindings. - Format is key followed by the command, separated by a colon. - See the "Changing Key Bindings" section for more information. - Example: + NetHack Guidebook 54 - BIND=^X:getpos.autodescribe - CHOOSE - Chooses at random one of the comma-separated parameters as an - active section name. Lines in other sections are ignored. - Example: + lenge which is very difficult to accomplish). - OPTIONS=color - CHOOSE=char A,char B - [char A] - OPTIONS=role:arc,race:dwa,align:law,gender:fem - [char B] - OPTIONS=role:wiz,race:elf,align:cha,gender:mal + The command to use a tool is `a' (apply). - MENUCOLOR - Highlight menu lines with different colors. See the "Configur- - ing Menu Colors" section. + 7.12.1. Containers - MSGTYPE - Change the way messages are shown in the top status line. See - the "Configuring Message Types" section. + You may encounter bags, boxes, and chests in your travels. A + tool of this sort can be opened with the "#loot" extended command when + you are standing on top of it (that is, on the same floor spot), or + with the `a' (apply) command when you are carrying it. However, + chests are often locked, and are in any case unwieldy objects. You + must set one down before unlocking it by using a key or lock-picking + tool with the `a' (apply) command, by kicking it with the `^D' com- + mand, or by using a weapon to force the lock with the "#force" + extended command. - ROGUESYMBOLS - Custom symbols for for the rogue level's symbol set. See SYM- - BOLS below. + Some chests are trapped, causing nasty things to happen when you + unlock or open them. You can check for and try to deactivate traps + with the "#untrap" extended command. - SOUND - Define a sound mapping. See the "Configuring User Sounds" sec- - tion. + When the contents of a container are known, that container will + be described as something like "a sack containing 3 items". In this + example, the 3 refers to number of stacks of compatible items, not to + the total number of individual items. So a sack holding 2 sky blue + potions, 7 arrows, and 350 gold pieces would be described as having 3 + items rather than 10 or 359. And you would need to have 3 unused + inventory slots available in order to take everything out (for the + case where the items you remove don't combine into bigger stacks with + things you're already carrying). - SOUNDDIR - Define the directory that contains the sound files. See the - "Configuring User Sounds" section. + If a chest or large box is described as "broken", that means that + it can't be locked rather than that it no longer functions as a con- + tainer. + The apply and loot commands allow you to take out and/or put in + an arbitrary number of items in a single operation. If you want to + take everything out of a container, you can use the "#tip" command to + pour the contents onto the floor. This may be your only way to get + things out if your hands are stuck to a cursed two-handed weapon. + When your hands aren't stuck, you have the potential to pour the con- + tents into another container. (As of this writing, the other con- + tainer must be carried rather than on the floor.) - NetHack 3.6 February 3, 2023 + 7.13. Amulets (`"') + Amulets are very similar to rings, and often more powerful. Like + rings, amulets have various magical properties, some beneficial, some + harmful, which are activated by putting them on. + Only one amulet may be worn at a time, around your neck. Like + wearing rings, wearing an amulet affects your metabolism, causing you + to grow hungry more rapidly. - NetHack Guidebook 49 + NetHack 5.0.0 May 2, 2026 - SYMBOLS - Override one or more symbols in the symbol set used for all - dungeon levels except for the special rogue level. See the - "Modifying NetHack Symbols" section. - Example: - # replace small punctuation (tick marks) with digits - SYMBOLS=S_boulder:0,S_golem:7 - WIZKIT - Debug mode only: extra items to add to initial inventory. - Value is the name of a text file containing a list of item - names, one per line, up to a maximum of 128 lines. Each line - is processed by the function that handles wishing. + NetHack Guidebook 55 - Example: - WIZKIT=~/wizkit.txt + The commands to use amulets are the same as for rings, `P' (put + on) and `R' (remove). `A' can be used to remove various worn items + including amulets. Also, `W' (wear) and `T' (take off) which are nor- + mally for armor can be used for amulets and other accessories (rings + and eyewear), but accessories won't be shown as likely candidates in a + prompt for choosing what to wear or take off. + 7.14. Gems (`*') - Here is an example of configuration file contents: + Some gems are valuable, and can be sold for a lot of gold. They + are also a far more efficient way of carrying your riches. Valuable + gems increase your score if you bring them with you when you exit. - # Set your character's role, race, gender, and alignment. - OPTIONS=role:Valkyrie, race:Human, gender:female, align:lawful - # - # Turn on autopickup, set automatically picked up object types - OPTIONS=autopickup,pickup_types:$"=/!?+ - # - # Map customization - OPTIONS=color # Display things in color if possible - OPTIONS=lit_corridor # Show lit corridors differently - OPTIONS=hilite_pet,hilite_pile - # Replace small punctuation (tick marks) with digits - SYMBOLS=S_boulder:0,S_golem:7 - # - # No startup splash screen. Windows GUI only. - OPTIONS=!splash_screen + Other small rocks are also categorized as gems, but they are much + less valuable. All rocks, however, can be used as projectile weapons + (if you have a sling). In the most desperate of cases, you can still + throw them by hand. + 7.15. Large rocks (``') + Statues and boulders are not particularly useful, and are gener- + ally heavy. It is rumored that some statues are not what they seem. - 9.3. Using the NETHACKOPTIONS environment variable + Boulders occasionally block your path. You can push one forward + (by attempting to walk onto its spot) when nothing blocks its path, or + you can smash it into a pile of small rocks with breaking magic or a + pick-axe. It is possible to move onto a boulder's location if certain + conditions are met; ordinarily one of those conditions is that pushing + it any further be blocked. Using the move-without-picking-up prefix + (default key `m') prior to the direction of movement will attempt to + move to a boulder's location without pushing it in addition to the + prefix's usual action of suppressing auto-pickup at the destination. - The NETHACKOPTIONS variable is a comma-separated list of - initial values for the various options. Some can only be turned - on or off. You turn one of these on by adding the name of the - option to the list, and turn it off by typing a `!' or "no" be- - fore the name. Others take a character string as a value. You - can set string options by typing the option name, a colon or - equals sign, and then the value of the string. The value is ter- - minated by the next comma or the end of string. + Very large humanoids (giants and their ilk) have been known to + pick up boulders and use them as missile weapons. + Unlike boulders, statues can't be pushed, but don't need to be + because they don't block movement. They can be smashed into rocks + though. + For some configurations of the program, statues are no longer + shown as ``' but by the letter representing the monster they depict + instead. + 7.16. Gold (`$') - NetHack 3.6 February 3, 2023 + Gold adds to your score, and you can buy things in shops with it. + There are a number of monsters in the dungeon that may be influenced + by the amount of gold you are carrying (shopkeepers aside). + Gold pieces are the only type of object where bless/curse state + does not apply. They're always uncursed but never described as + uncursed even if you turn off the implicit_uncursed option. You can + set the goldX option if you prefer to have gold pieces be treated as + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 50 - For example, to set up an environment variable so that color - is on, legacy is off, character name is set to "Blue Meanie", and - named fruit is set to "lime", you would enter the command + NetHack Guidebook 56 - % setenv NETHACKOPTIONS "color,\!leg,name:Blue Meanie,fruit:lime" - in csh (note the need to escape the `!' since it's special to - that shell), or the pair of commands - $ NETHACKOPTIONS="color,!leg,name:Blue Meanie,fruit:lime" - $ export NETHACKOPTIONS + bless/curse state unknown rather than as known to be uncursed. Only + matters when you're using an object selection prompt that can filter + by "BUCX" state. - in sh, ksh, or bash. + 7.17. Persistence of Objects - The NETHACKOPTIONS value is effectively the same as a single - OPTIONS statement in a configuration file. The "OPTIONS=" prefix - is implied and comma separated options are processed from right - to left. Other types of configuration statements such as BIND or - MSGTYPE are not allowed. + Normally, if you have seen an object at a particular map location + and move to another location where you can't directly see that object + any more, it will continue to be displayed on your map. That remains + the case even if it is not actually there any more--perhaps a monster + has picked it up or it has rotted away--until you can see or feel that + location again. One notable exception is that if the object gets cov- + ered by the "remembered, unseen monster" marker. When that marker is + later removed after you've verified that no monster is there, you will + have forgotten that there was any object there regardless of whether + the unseen monster actually took the object. If the object is still + there, then once you see or feel that location again you will re-dis- + cover the object and resume remembering it. - Instead of a comma-separated list of options, NETHACKOPTIONS - can be set to the full name of a configuration file you want to - use. If that full name doesn't start with a slash, precede it - with `@' (at-sign) to let NetHack know that the rest is intended - as a file name. If it does start with `/', the at-sign is op- - tional. + The situation is the same for a pile of objects, except that only + the top item of the pile is displayed. The hilite_pile option can be + enabled in order to show an item differently when it is the top one of + a pile. - 9.4. Customization options + 8. Conduct - Here are explanations of what the various options do. Char- - acter strings that are too long may be truncated. Some of the - options listed may be inactive in your dungeon. + As if winning NetHack were not difficult enough, certain players + seek to challenge themselves by imposing restrictions on the way they + play the game. The game automatically tracks some of these chal- + lenges, which can be checked at any time with the #conduct command or + at the end of the game. When you perform an action which breaks a + challenge, it will no longer be listed. This gives players extra + "bragging rights" for winning the game with these challenges. Note + that it is perfectly acceptable to win the game without resorting to + these restrictions and that it is unusual for players to adhere to + challenges the first time they win the game. - Some options are persistent, and are saved and reloaded - along with the game. Changing a persistent option in the config- - uration file applies only to new games. + Several of the challenges are related to eating behavior. The + most difficult of these is the foodless challenge. Although creatures + can survive long periods of time without food, there is a physiologi- + cal need for water; thus there is no restriction on drinking bever- + ages, even if they provide some minor food benefits. Calling upon + your god for help with starvation does not violate any food challenges + either. - acoustics - Enable messages about what your character hears (default on). - Note that this has nothing to do with your computer's audio ca- - pabilities. Persistent. + A strict vegan diet is one which avoids any food derived from + animals. The primary source of nutrition is fruits and vegetables. + The corpses and tins of blobs (`b'), jellies (`j'), and fungi (`F') + are also considered to be vegetable matter. Certain human food is + prepared without animal products; namely, lembas wafers, cram rations, + food rations (gunyoki), K-rations, and C-rations. Metal or another + normally indigestible material eaten while polymorphed into a creature + that can digest it is also considered vegan food. Note however that + eating such items still counts against foodless conduct. - align - Your starting alignment (align:lawful, align:neutral, or - align:chaotic). You may specify just the first letter. The - default is to randomly pick an appropriate alignment. If you - prefix the value with `!' or "no", you will exclude that align- - ment from being picked randomly. Cannot be set with the `O' - command. Persistent. - autodescribe - Automatically describe the terrain under cursor when asked to - get a location on the map (default true). The whatis_coord op- - tion controls whether the description includes map coordinates. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 57 - NetHack Guidebook 51 + Vegetarians do not eat animals; however, they are less selective + about eating animal byproducts than vegans. In addition to the vegan + items listed above, they may eat any kind of pudding (`P') other than + the black puddings, eggs and food made from eggs (fortune cookies and + pancakes), food made with milk (cream pies and candy bars), and lumps + of royal jelly. Monks are expected to observe a vegetarian diet. + Eating any kind of meat violates the vegetarian, vegan, and food- + less conducts. This includes tripe rations, the corpses or tins of + any monsters not mentioned above, and the various other chunks of meat + found in the dungeon. Swallowing and digesting a monster while poly- + morphed is treated as if you ate the creature's corpse. Eating + leather, dragon hide, or bone items while polymorphed into a creature + that can digest it, or eating monster brains while polymorphed into a + mind flayer, is considered eating an animal, although wax is only an + animal byproduct. + + Regardless of conduct, there will be some items which are indi- + gestible, and others which are hazardous to eat. Using a swallow-and- + digest attack against a monster is equivalent to eating the monster's + corpse. Please note that the term "vegan" is used here only in the + context of diet. You are still free to choose not to use or wear + items derived from animals (e.g. leather, dragon hide, bone, horns, + coral), but the game will not keep track of this for you. Also note + that "milky" potions may be a translucent white, but they do not con- + tain milk, so they are compatible with a vegan diet. Slime molds or + player-defined "fruits", although they could be anything from "cher- + ries" to "pork chops", are also assumed to be vegan. - autodig - Automatically dig if you are wielding a digging tool and moving - into a place that can be dug (default false). Persistent. + An atheist is one who rejects religion. This means that you can- + not #pray, #offer sacrifices to any god, #turn undead, or #chat with a + priest. Particularly selective readers may argue that playing Monk or + Priest characters should violate this conduct; that is a choice left + to the player. Offering the Amulet of Yendor to your god is necessary + to win the game and is not counted against this conduct. You are also + not penalized for being spoken to by an angry god, priest(ess), or + other religious figure; a true atheist would hear the words but attach + no special meaning to them. - autoopen - Walking into a door attempts to open it (default true). Persis- - tent. + A pauper starts the game with no possessions, no spells, and no + weapon or spell skills (and if playing as a knight, your pony will not + have a saddle). Can only be initiated by starting a new game with + OPTIONS=pauper set in your run-time configurtion file or NETHACKOP- + TIONS environment variable. Once the game is underway, you can + acquire and use items, spells, and skills in the usual way. - autopickup - Automatically pick up things onto which you move (default on). - Persistent. See pickup_types to refine the behavior. + Most players fight with a wielded weapon (or tool intended to be + wielded as a weapon). Another challenge is to win the game without + using such a wielded weapon. You are still permitted to throw, fire, + and kick weapons; use a wand, spell, or other type of item; or fight + with your hands and feet. - autoquiver - This option controls what happens when you attempt the `f' - (fire) command when nothing is quivered or readied (default - false). When true, the computer will fill your quiver or - quiver sack or make ready some suitable weapon. Note that it - will not take into account the blessed/cursed status, enchant- - ment, damage, or quality of the weapon; you are free to manual- - ly fill your quiver or quiver sack or make ready with the `Q' - command instead. If no weapon is found or the option is false, - the `t' (throw) command is executed instead. Persistent. + In NetHack, a pacifist refuses to cause the death of any other + monster (i.e. if you would get experience for the death). This is a + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 58 + + + + particularly difficult challenge, although it is still possible to + gain experience by other means. + + An illiterate character does not read or write. This includes + reading a scroll, spellbook, fortune cookie message, or t-shirt; writ- + ing a scroll; or making an engraving of anything other than a single + "X" (the traditional signature of an illiterate person). Reading an + engraving, or any item that is absolutely necessary to win the game, + is not counted against this conduct. The identity of scrolls and + spellbooks (and knowledge of spells) in your starting inventory is + assumed to be learned from your teachers prior to the start of the + game and isn't counted. + + There is a side-branch to the main dungeon called "Sokoban," + briefly described in the earlier section about Traps. As mentioned + there, the goal is to push boulders into pits and/or holes to plug + those in order to both get the boulders out of the way and be able to + go past the traps. There are some special "rules" that are active + when in that branch of the dungeon. Some rules can't be bypassed, + such as being unable to push a boulder diagonally. Other rules can, + such as not smashing boulders with magic or tools, but doing so causes + you to receive a luck penalty. No message about that is given at the + time, but it is tracked as a conduct. The #conduct command and end of + game disclosure will report whether you have abided by the special + rules of Sokoban, and if not, how many times you violated them, pro- + viding you with a way to discover which actions incur bad luck so that + you can be better informed about whether or not to avoid repeating + those actions in the future. (Note: the Sokoban conduct will only be + displayed if you have entered the Sokoban branch of the dungeon during + the current game. Once that has happened, it becomes part of dis- + closed conduct even if you haven't done anything interesting there. + Ending the game with "never broke the Sokoban rules" conduct is most + meaningful if you also manage to perform the "obtained the Sokoban + prize" achievement (see Achievements below).) - blind - Start the character permanently blind (default false). Persis- - tent. + There are several other challenges tracked by the game. It is + possible to eliminate one or more species of monsters by genocide; + playing without this feature is considered a challenge. When the game + offers you an opportunity to genocide monsters, you may respond with + the monster type "none" if you want to decline. You can change the + form of an item into another item of the same type ("polypiling") or + the form of your own body into another creature ("polyself") by wand, + spell, or potion of polymorph; avoiding these effects are each consid- + ered challenges. Polymorphing monsters, including pets, does not + break either of these challenges. Finally, you may sometimes receive + wishes; a game without an attempt to wish for any items is a chal- + lenge, as is a game without wishing for an artifact (even if the arti- + fact immediately disappears). When the game offers you an opportunity + to make a wish for an item, you may choose "nothing" if you want to + decline. - bones - Allow saving and loading bones files (default true). Persis- - tent. - boulder - Set the character used to display boulders (default is the - "large rock" class symbol, ``'). - catname - Name your starting cat (for example "catname:Morris"). Cannot - be set with the `O' command. - character - Synonym for "role" to pick the type of your character (for ex- - ample "character:Monk"). See role for more details. - checkpoint - Save game state after each level change, for possible recovery - after program crash (default on). Persistent. - checkspace - Check free disk space before writing files to disk (default - on). You may have to turn this off if you have more than 2 GB - free space on the partition used for your save and level files - (because too much space might overflow the calculation and end - up looking like insufficient space). Only applies when MFLOPPY - was defined during compilation. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 59 - NetHack Guidebook 52 + 8.1. Achievements + End of game disclosure will also display various achievements + representing progress toward ultimate ascension, if any have been + attained. They aren't directly related to conduct but are grouped + with it because they fall into the same category of "bragging rights" + and to limit the number of questions during disclosure. Listed here + roughly in order of difficulty and not necessarily in the order in + which you might accomplish them. - clicklook - Allows looking at things on the screen by navigating the mouse - over them and clicking the right mouse button (default off). + Rank - Attained rank title Rank. + Shop - Entered a shop. + Temple - Entered a temple. + Mines - Entered the Gnomish Mines. + Town - Entered Mine Town. + Oracle - Consulted the Oracle of Delphi. + Novel - Read a passage from a Discworld Novel. + Sokoban - Entered Sokoban. + Big Room - Entered the Big Room. + Soko-Prize - Explored to the top of Sokoban and found a + special item there. + Mines' End - Explored to the bottom of the Gnomish Mines + and found a special item there. + Medusa - Defeated Medusa. + Tune - Discovered the tune that can be used to open + and close the drawbridge on the Castle level. + Bell - Acquired the Bell of Opening. + Gehennom - Entered Gehennom. + Candle - Acquired the Candelabrum of Invocation. + Book - Acquired the Book of the Dead. + Invocation - Gained access to the bottommost level of + Gehennom. + Amulet - Acquired the fabled Amulet of Yendor. + Endgame - Reached the Elemental Planes. + Astral - Reached the Astral Plane level. + Blind - Blind from birth. + Deaf - Deaf from birth. + Nudist - Never wore any armor. + Pauper - Started out with no possessions. + Ascended - Delivered the Amulet to its final destination. - cmdassist - Have the game provide some additional command assistance for - new players if it detects some anticipated mistakes (default - on). - confirm - Have user confirm attacks on pets, shopkeepers, and other - peaceable creatures (default on). Persistent. + Notes: - dark_room - Show out-of-sight areas of lit rooms (default on). Persistent. + Achievements are recorded and subsequently reported in the order + in which they happen during your current game rather than the order + listed here. - disclose - Controls what information the program reveals when the game - ends. Value is a space separated list of prompting/category - pairs (default is "ni na nv ng nc no", prompt with default re- - sponse of `n' for each candidate). Persistent. The possibili- - ties are: + There are nine titles for each role, bestowed at experi- + ence levels 1, 3, 6, 10, 14, 18, 22, 26, and 30. The one for experi- + ence level 1 is not recorded as an achievement. Losing enough levels + to revert to lower rank(s) does not discard the corresponding achieve- + ment(s). - i - disclose your inventory; - a - disclose your attributes; - v - summarize monsters that have been vanquished; - g - list monster species that have been genocided; - c - display your conduct; - o - display dungeon overview. - Each disclosure possibility can optionally be preceded by a - prefix which lets you refine how it behaves. Here are the - valid prefixes: - y - prompt you and default to yes on the prompt; - n - prompt you and default to no on the prompt; - + - disclose it without prompting; - - - do not disclose it and do not prompt. + NetHack 5.0.0 May 2, 2026 - The listing of vanquished monsters can be sorted, so there are - two additional choices for `v': - ? - prompt you and default to ask on the prompt; - # - disclose it without prompting, ask for sort order. - Asking refers to picking one of the orderings from a menu. The - `+' disclose without prompting choice, or being prompted and - answering `y' rather than `a', will default to showing monsters - in the traditional order, from high level to low level. - Omitted categories are implicitly added with `n' prefix. Spec- - ified categories with omitted prefix implicitly use `+' prefix. - Order of the disclosure categories does not matter, program - display for end-of-game disclosure follows a set sequence. + NetHack Guidebook 60 - NetHack 3.6 February 3, 2023 + There's no guaranteed Novel so the achievement to read one might + not always be attainable (except perhaps by wishing). Similarly, the + Big Room level is not always present. Unlike with the Novel, there's + no way to wish for this opportunity. + The "special items" hidden in Mines' End and Sokoban are not + unique but are considered to be prizes or rewards for exploring those + levels since doing so is not necessary to complete the game. Finding + other instances of the same objects doesn't record the corresponding + achievement. + The Medusa achievement is recorded if she dies for any reason, + even if you are not directly responsible, and only if she dies. - NetHack Guidebook 53 + The 5-note tune can be learned via trial and error with a musical + instrument played closely enough--but not too close!--to the Castle + level's drawbridge or can be given to you via prayer boon. + Blind, Deaf, Nudist, and Pauper are also conducts, and they can + only be enabled by setting the correspondingly named option in + NETHACKOPTIONS or run-time configuration file prior to game start. In + the case of Blind and Deaf, the option also enforces the conduct. + They aren't really significant accomplishments unless/until you make + substantial progress into the dungeon. + 9. Options - (for example "disclose:yi na +v -g o") The example sets inven- - tory to prompt and default to yes, attributes to prompt and de- - fault to no, vanquished to disclose without prompting, genocid- - ed to not disclose and not prompt, conduct to implicitly prompt - and default to no, and overview to disclose without prompting. + Due to variations in personal tastes and conceptions of how + NetHack should do things, there are options you can set to change how + NetHack behaves. - Note that the vanquished monsters list includes all monsters - killed by traps and each other as well as by you. And the dun- - geon overview shows all levels you had visited but does not re- - veal things about them that you hadn't discovered. + 9.1. Setting the options - dogname - Name your starting dog (for example "dogname:Fang"). Cannot be - set with the `O' command. + Options may be set in a number of ways. Within the game, the `O' + command allows you to view all options and change most of them. You + can also set options automatically by placing them in a configuration + file, or in the NETHACKOPTIONS environment variable. Some versions of + NetHack also have front-end programs that allow you to set options + before starting the game or a global configuration for system adminis- + trators. - extmenu - Changes the extended commands interface to pop-up a menu of - available commands. It is keystroke compatible with the tradi- - tional interface except that it does not require that you hit - Enter. It is implemented for the tty interface (default off). + 9.2. Using a configuration file - For the X11 interface, which always uses a menu for choosing an - extended command, it controls whether the menu shows all avail- - able commands (on) or just the subset of commands which have - traditionally been considered extended ones (off). + The default name of the configuration file varies on different + operating systems. - female - An obsolete synonym for "gender:female". Cannot be set with - the `O' command. + On UNIX, Linux, and macOS it is ".nethackrc" in the user's home + directory. The file may not exist, but it is a normal ASCII text file + and can be created with any text editor. - fixinv - An object's inventory letter sticks to it when it's dropped - (default on). If this is off, dropping an object shifts all - the remaining inventory letters. Persistent. + On Windows, the name is ".nethackrc" located in the folder + "%USERPROFILE%\NetHack\". The file may not exist, but it is a normal + ASCII text file can can be created with any text editor. After run- + ning NetHack for the first time, you should find a default template - force_invmenu - Commands asking for an inventory item show a menu instead of a - text query with possible menu letters. Default is off. - fruit - Name a fruit after something you enjoy eating (for example - "fruit:mango") (default "slime mold"). Basically a nostalgic - whimsy that NetHack uses from time to time. You should set - this to something you find more appetizing than slime mold. - Apples, oranges, pears, bananas, and melons already exist in - NetHack, so don't use those. + NetHack 5.0.0 May 2, 2026 - gender - Your starting gender (gender:male or gender:female). You may - specify just the first letter. Although you can still denote - your gender using the "male" and "female" options, the "gender" - option will take precedence. The default is to randomly pick - an appropriate gender. If you prefix the value with `!' or - "no", you will exclude that gender from being picked randomly. - NetHack 3.6 February 3, 2023 + NetHack Guidebook 61 - NetHack Guidebook 54 + for the configuration file named ".nethackrc.template" in + "%USERPROFILE%\NetHack\". If you have not created the configuration + file, NetHack will create one for you using the default template file. + On MS-DOS, it is "defaults.nh" in the same folder as nethack.exe. + Any line in the configuration file starting with `#' is treated + as a comment and ignored. Empty lines are ignored. - Cannot be set with the `O' command. Persistent. + Any line beginning with `[' and ending in `]' is a section marker + (the closing `]' can be followed by whitespace and then an arbitrary + comment beginning with `#'). The text between the square brackets is + the section name. Section markers are only valid after a CHOOSE + directive and their names are case-insensitive. Lines after a section + marker belong to that section up until another section starts or a + marker without a name is encountered or the file ends. Lines within + sections are ignored unless a CHOOSE directive has selected that sec- + tion. - goldX - When filtering objects based on bless/curse state (BUCX), - whether to treat gold pieces as X (unknown bless/curse state, - when "on") or U (known to be uncursed, when "off", the de- - fault). Gold is never blessed or cursed, but it is not de- - scribed as "uncursed" even when the implicit_uncursed option is - "off". + You can use different configuration directives in the file, some + of which can be used multiple times. In general, the directives are + written in capital letters, followed by an equals sign, followed by + settings particular to that directive. - help - If more information is available for an object looked at with - the `/' command, ask if you want to see it (default on). Turn- - ing help off makes just looking at things faster, since you - aren't interrupted with the "More info?" prompt, but it also - means that you might miss some interesting and/or important in- - formation. Persistent. + Here is a list of allowed directives: - herecmd_menu - When using a windowport that supports mouse and clicking on - yourself or next to you, show a menu of possible actions for - the location. Same as "#herecmdmenu" and "#therecmdmenu" com- - mands. + OPTIONS + There are two types of options, boolean and compound options. Bool- + ean options toggle a setting on or off, while compound options take + more diverse values. Prefix a boolean option with "no" or `!' to + turn it off. For compound options, the option name and value are + separated by a colon. Some options are persistent, and apply only + to new games. You can specify multiple OPTIONS directives, and mul- + tiple options separated by commas in a single OPTIONS directive. + (Comma separated options are processed from right to left.) - hilite_pet - Visually distinguish pets from similar animals (default off). - The behavior of this option depends on the type of windowing - you use. In text windowing, text highlighting or inverse video - is often used; with tiles, generally displays a heart symbol - near pets. + Example: - With the curses interface, the petattr option controls how to - highlight pets and setting it will turn the hilite_pet option - on or off as warranted. + OPTIONS=dogname:Fido + OPTIONS=!legacy,autopickup,pickup_types:$"=/!?+ - hilite_pile - Visually distinguish piles of objects from individual objects - (default off). The behavior of this option depends on the type - of windowing you use. In text windowing, text highlighting or - inverse video is often used; with tiles, generally displays a - small plus-symbol beside the object on the top of the pile. + HACKDIR + Default location of files NetHack needs. On Windows HACKDIR defaults + to the location of the NetHack.exe or NetHackw.exe file so setting + HACKDIR to override that is not usually necessary or recommended. - hitpointbar - Show a hit point bar graph behind your name and title. Only - available for TTY and Windows GUI, and only when statushilites - is on. + LEVELDIR + The location that in-progress level files are stored. Defaults to + HACKDIR, must be writable. - horsename - Name your starting horse (for example "horsename:Trigger"). - Cannot be set with the `O' command. + SAVEDIR + The location where saved games are kept. Defaults to HACKDIR, must + be writable. - ignintr - Ignore interrupt signals, including breaks (default off). Per- - sistent. - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 55 + NetHack Guidebook 62 - implicit_uncursed - Omit "uncursed" from inventory lists, if possible (default on). + BONESDIR + The location that bones files are kept. Defaults to HACKDIR, must be + writable. - legacy - Display an introductory message when starting the game (default - on). Persistent. + LOCKDIR + The location that file synchronization locks are stored. Defaults to + HACKDIR, must be writable. - lit_corridor - Show corridor squares seen by night vision or a light source - held by your character as lit (default off). Persistent. + TROUBLEDIR + The location that a record of game aborts and self-diagnosed game + problems is kept. Defaults to HACKDIR, must be writable. - lootabc - When using a menu to interact with a container, use the old - `a', `b', and `c' keyboard shortcuts rather than the mnemonics - `o', `i', and `b' (default off). Persistent. + AUTOCOMPLETE + Enable or disable an extended command autocompletion. Autocomple- + tion has no effect for the X11 windowport. You can specify multiple + autocompletions. To enable autocompletion, list the extended com- + mand. Prefix the command with "!" to disable the autocompletion for + that command. - mail - Enable mail delivery during the game (default on). Persistent. + Example: - male - An obsolete synonym for "gender:male". Cannot be set with the - `O' command. + AUTOCOMPLETE=zap,!annotate - mention_walls - Give feedback when walking against a wall (default off). + AUTOPICKUP_EXCEPTION + Set exceptions to the pickup_types option. See the "Configuring + Autopickup Exceptions" section. - menucolors - Enable coloring menu lines (default off). See "Configuring - Menu Colors" on how to configure the colors. + BINDINGS + Change the key bindings of some special keys, menu accelerators, + extended commands, or mouse buttons. You can specify multiple bind- + ings. Format is key followed by the command, separated by a colon. + See the "Changing Key Bindings" section for more information. - menustyle - Controls the interface used when you need to choose various ob- - jects (in response to the Drop command, for instance). The - value specified should be the first letter of one of the fol- - lowing: traditional, combination, full, or partial. Tradi- - tional was the only interface available for early versions; it - consists of a prompt for object class characters, followed by - an object-by-object prompt for all items matching the selected - object class(es). Combination starts with a prompt for object - class(es) of interest, but then displays a menu of matching ob- - jects rather than prompting one-by-one. Full displays a menu - of object classes rather than a character prompt, and then a - menu of matching objects for selection. Partial skips the ob- - ject class filtering and immediately displays a menu of all ob- - jects. Persistent. + Example: - menu_deselect_all - Menu character accelerator to deselect all items in a menu. - Implemented by the Amiga, Gem, X11 and tty ports. Default `-'. + BIND=^X:getpos.autodescribe - menu_deselect_page - Menu character accelerator to deselect all items on this page - of a menu. Implemented by the Amiga, Gem and tty ports. De- - fault `\'. + CHOOSE + Chooses at random one of the comma-separated parameters as an active + section name. Lines in other sections are ignored. + Example: - NetHack 3.6 February 3, 2023 + OPTIONS=color + CHOOSE=char A,char B + [char A] + OPTIONS=role:arc,race:dwa,align:law,gender:fem + [char B] + OPTIONS=role:wiz,race:elf,align:cha,gender:mal + [] #end of CHOOSE + OPTIONS=!rest_on_space + If [] is present, the preceding section is closed and no new section + begins; whatever follows will be common to all sections. Otherwise + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 56 - menu_first_page - Menu character accelerator to jump to the first page in a menu. - Implemented by the Amiga, Gem and tty ports. Default `^'. + NetHack Guidebook 63 - menu_headings - Controls how the headings in a menu are highlighted. Values - are "none", "bold", "dim", "underline", "blink", or "inverse". - Not all ports can actually display all types. - menu_invert_all - Menu character accelerator to invert all items in a menu. Im- - plemented by the Amiga, Gem, X11 and tty ports. Default `@'. - menu_invert_page - Menu character accelerator to invert all items on this page of - a menu. Implemented by the Amiga, Gem and tty ports. Default - `~'. + the last section extends to the end of the options file. - menu_last_page - Menu character accelerator to jump to the last page in a menu. - Implemented by the Amiga, Gem and tty ports. Default `|'. + MENUCOLOR + Highlight menu lines with different colors. See the "Configuring + Menu Colors" section. - menu_next_page - Menu character accelerator to goto the next menu page. Imple- - mented by the Amiga, Gem and tty ports. Default `>'. + MSGTYPE + Change the way messages are shown in the top line. See the "Config- + uring Message Types" section. - menu_objsyms - Show object symbols in menu headings in menus where the object - symbols act as menu accelerators (default off). + ROGUESYMBOLS + Custom symbols for the rogue level's symbol set. See SYMBOLS below. - menu_overlay - Do not clear the screen before drawing menus, and align menus - to the right edge of the screen. Only for the tty port. (de- - fault on) + SOUND + Define a sound mapping. See the "Configuring User Sounds" section. - menu_previous_page - Menu character accelerator to goto the previous menu page. Im- - plemented by the Amiga, Gem and tty ports. Default `<'. + SOUNDDIR + Define the directory that contains the sound files. See the "Con- + figuring User Sounds" section. - menu_search - Menu character accelerator to search for a menu item. Imple- - mented by the Amiga, Gem, X11 and tty ports. Default `:'. + SYMBOLS + Override one or more symbols in the symbol set used for all dungeon + levels except for the special rogue level. See the "Modifying + NetHack Symbols" section. - menu_select_all - Menu character accelerator to select all items in a menu. Im- - plemented by the Amiga, Gem, X11 and tty ports. Default `.'. + Example: - menu_select_page - Menu character accelerator to select all items on this page of - a menu. Implemented by the Amiga, Gem and tty ports. Default - `,'. + # replace small punctuation (tick marks) with digits + SYMBOLS=S_golem:7 - monpolycontrol - Prompt for new form whenever any monster changes shape (default + WIZKIT + Debug mode only: extra items to add to initial inventory. Value is + the name of a text file containing a list of item names, one per + line, up to a maximum of 128 lines. Each line is processed by the + function that handles wishing. Entries are added to the wish his- + tory; see the wizwish-command. + Example: - NetHack 3.6 February 3, 2023 + WIZKIT=~/wizkit.txt + Here is an example of configuration file contents: - NetHack Guidebook 57 - off). Debug mode only. - mouse_support - Allow use of the mouse for input and travel. Valid settings - are: - 0 - disabled - 1 - enabled and make OS adjustments to support mouse use - 2 - like 1 but does not make any OS adjustments - Omitting a value is the same as specifying 1 and negating - mouse_support is the same as specifying 0. - msghistory - The number of top line messages to keep (and be able to recall - with `^P') (default 20). Cannot be set with the `O' command. - msg_window - Allows you to change the way recalled messages are displayed. - Currently it is only supported for tty (all four choices) and - for curses (`f' and `r' choices, default `r'). The possible - values are: - s - single message (default; only choice prior to 3.4.0); - c - combination, two messages as "single", then as "full"; - f - full window, oldest message first; - r - full window reversed, newest message first. - For backward compatibility, no value needs to be specified - (which defaults to "full"), or it can be negated (which - defaults to "single"). + NetHack 5.0.0 May 2, 2026 - name - Set your character's name (defaults to your user name). You - can also set your character's role by appending a dash and one - or more letters of the role (that is, by suffixing one of -A -B - -C -H -K -M -P -Ra -Ro -S -T -V -W). If -@ is used for the - role, then a random one will be automatically chosen. Cannot - be set with the `O' command. - news - Read the NetHack news file, if present (default on). Since the - news is shown at the beginning of the game, there's no point in - setting this with the `O' command. - nudist - Start the character with no armor (default false). Persistent. - null - Send padding nulls to the terminal (default on). Persistent. - number_pad - Use digit keys instead of letters to move (default 0 or off). - Valid settings are: + NetHack Guidebook 64 - NetHack 3.6 February 3, 2023 + # Set your character's role, race, gender, and alignment. + OPTIONS=role:Valkyrie, race:Human, gender:female, align:lawful + # + # Turn on autopickup, set automatically picked up object types + OPTIONS=autopickup,pickup_types:$"=/!?+ + # + # Map customization + OPTIONS=color # Display things in color if possible + OPTIONS=lit_corridor # Show lit corridors differently + OPTIONS=hilite_pet,hilite_pile + # Replace small punctuation (tick marks) with digits + OPTIONS=boulder:0 + SYMBOLS=S_golem:7 + # + # No startup splash screen. Windows GUI only. + OPTIONS=!splash_screen + 9.3. Using the NETHACKOPTIONS environment variable - NetHack Guidebook 58 + The NETHACKOPTIONS variable is a comma-separated list of initial + values for the various options. Some can only be turned on or off. + You turn one of these on by adding the name of the option to the list, + and turn it off by typing a `!' or "no" before the name. Others take + a character string as a value. You can set string options by typing + the option name, a colon or equals sign, and then the value of the + string. The value is terminated by the next comma or the end of + string. + For example, to set up an environment variable so that color is + on, legacy is off, character name is set to "Blue Meanie", and named + fruit is set to "lime", you would enter the command + % setenv NETHACKOPTIONS "color,\!leg,name:Blue Meanie,fruit:lime" - 0 - move by letters; "yuhjklbn" - 1 - move by numbers; digit `5' acts as `G' movement prefix - 2 - like 1 but `5' works as `g' prefix instead of as `G' - 3 - by numbers using phone key layout; 123 above, 789 below - 4 - combines 3 with 2; phone layout plus MS-DOS compatibility - -1 - by letters but use `z' to go northwest, `y' to zap wands + in csh (note the need to escape the `!' since it's special to that + shell), or the pair of commands - For backward compatibility, omitting a value is the same as - specifying 1 and negating number_pad is the same as specifying - 0. (Settings 2 and 4 are for compatibility with MS-DOS or old - PC Hack; in addition to the different behavior for `5', `Alt-5' - acts as `G' and `Alt-0' acts as `I'. Setting -1 is to accommo- - date some QWERTZ keyboards which have the location of the `y' - and `z' keys swapped.) When moving by numbers, to enter a - count prefix for those commands which accept one (such as "12s" - to search twelve times), precede it with the letter `n' - ("n12s"). + $ NETHACKOPTIONS="color,!leg,name:Blue Meanie,fruit:lime" + $ export NETHACKOPTIONS - packorder - Specify the order to list object types in (default - "")[%?+!=/(*`0_"). The value of this option should be a string - containing the symbols for the various object types. Any omit- - ted types are filled in at the end from the previous order. + in sh, ksh, or bash. - paranoid_confirmation - A space separated list of specific situations where alternate - prompting is desired. The default is paranoid_confirma- - tion:pray. + The NETHACKOPTIONS value is effectively the same as a single + OPTIONS directive in a configuration file. The "OPTIONS=" prefix is + implied and comma separated options are processed from right to left. + Other types of configuration directives such as BIND or MSGTYPE are + not allowed. - Confirm - for any prompts which are set to require "yes" - rather than `y', also require "no" to reject in- - stead of accepting any non-yes response as no - quit - require "yes" rather than `y' to confirm quitting - the game or switching into non-scoring explore - mode; - die - require "yes" rather than `y' to confirm dying - (not useful in normal play; applies to explore - mode); - bones - require "yes" rather than `y' to confirm saving - bones data when dying in debug mode; - attack - require "yes" rather than `y' to confirm attack- - ing a peaceful monster; - wand-break - require "yes" rather than `y' to confirm breaking - a wand; - eating - require "yes" rather than `y' to confirm whether - to continue eating; - Were-change - require "yes" rather than `y' to confirm changing - form due to lycanthropy when hero has polymorph - control; - pray - require `y' to confirm an attempt to pray rather - than immediately praying; on by default; - Remove - require selection from inventory for `R' and `T' - commands even when wearing just one applicable - item. + Instead of a comma-separated list of options, NETHACKOPTIONS can + be set to the full name of a configuration file you want to use. If + that full name doesn't start with a slash, precede it with `@' (at- + sign) to let NetHack know that the rest is intended as a file name. - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 59 + NetHack Guidebook 65 - all - turn on all of the above. + If it does start with `/', the at-sign is optional. - By default, the pray choice is enabled, the others disabled. - To disable it without setting any of the other choices, use - "paranoid_confirmation:none". To keep it enabled while setting - any of the others, include it in the list, such as "para- - noid_confirmation:attack pray Remove". + 9.4. Customization options - perm_invent - If true, always display your current inventory in a window. - This only makes sense for windowing system interfaces that im- - plement this feature. + Here are explanations of what the various options do. Character + strings that are too long may be truncated. Some of the options + listed may be inactive in your dungeon. - petattr - Specifies one or more text highlighting attributes to use when - showing pets on the map. Effectively a superset of the - hilite_pet boolean option. Curses interface only; value is one - or more of the following letters. + Some options are persistent, and are saved and reloaded along + with the game. Changing a persistent option in the configuration file + applies only to new games. - n - Normal text (no highlighting) - i - Inverse video (default) - b - Bold text - u - Underlined text - k - blinKing text - d - Dim text - t - iTalic text - l - Left line indicator - r - Right line indicator + accessiblemsg + Add location or direction information to messages (default is off). - Some of those choices might not work, particularly the final - three, depending upon terminal hardware or terminal emulation - software. + acoustics + Enable messages about what your character hears (default on). Note + that this has nothing to do with your computer's audio capabilities. + Persistent. - Currently multiple highlight-style letters can be combined by - simply stringing them together (for example, "bk"), but in the - future they might require being separated by plus signs (such - as "b+k", which works already). When using the `n' choice, it - should be specified on its own, not in combination with any of - the other letters. + alignment + Your starting alignment (align:lawful, align:neutral, or + align:chaotic). You may specify just the first letter. Many roles + and the non-human races restrict which alignments are allowed. See + role for a description of how to use negation to exclude choices. - pettype - Specify the type of your initial pet, if you are playing a - character class that uses multiple types of pets; or choose to - have no initial pet at all. Possible values are "cat", "dog", - "horse", and "none". If the choice is not allowed for the role - you are currently playing, it will be silently ignored. For - example, "horse" will only be honored when playing a knight. - Cannot be set with the `O' command. + If align is not specified, there is no default value; player will be + prompted unless role and/or race forces a choice for alignment. + Cannot be set with the `O' command. Persistent. - pickup_burden - When you pick up an item that would exceed this encumbrance - level (Unencumbered, Burdened, streSsed, straiNed, overTaxed, - or overLoaded), you will be asked if you want to continue. - (Default `S'). Persistent. + armorstatus + Display an extra status condition which summarizes currently worn + armor (default off, not supported by all interfaces). + For the usual case where more than one piece of armor is worn, a + list of letters is shown in the following order: - NetHack 3.6 February 3, 2023 + G - gloves; + C - cloak; + A - suit; + U - shirt; + H - helmet; + B - boots; + S - shield. + autodescribe + Automatically describe the terrain under cursor when asked to get a + location on the map (default true). The whatis_coord option con- + trols whether the description includes map coordinates. + autodig + Automatically dig if you are wielding a digging tool and moving into + a place that can be dug (default false). Persistent. - NetHack Guidebook 60 + NetHack 5.0.0 May 2, 2026 - pickup_thrown - If this option is on and autopickup is also on, try to pick up - things that you threw, even if they aren't in pickup_types or - match an autopickup exception. Default is on. Persistent. - pickup_types - Specify the object types to be picked up when autopickup is on. - Default is all types. You can use autopickup_exception config- - uration file lines to further refine autopickup behavior. Per- - sistent. - pile_limit - When walking across a pile of objects on the floor, threshold - at which the message "there are few/several/many objects here" - is given instead of showing a popup list of those objects. A - value of 0 means "no limit" (always list the objects); a value - of 1 effectively means "never show the objects" since the pile - size will always be at least that big; default value is 5. - Persistent. + NetHack Guidebook 66 - playmode - Values are "normal", "explore", or "debug". Allows selection - of explore mode (also known as discovery mode) or debug mode - (also known as wizard mode) instead of normal play. Debug mode - might only be allowed for someone logged in under a particular - user name (on multi-user systems) or specifying a particular - character name (on single-user systems) or it might be disabled - entirely. Requesting it when not allowed or not possible re- - sults in explore mode instead. Default is normal play. - pushweapon - Using the `w' (wield) command when already wielding something - pushes the old item into your alternate weapon slot (default - off). Likewise for the `a' (apply) command if it causes the - applied item to become wielded. Persistent. - race - Selects your race (for example, "race:human"). Default is ran- - dom. If you prefix the value with `!' or "no", you will ex- - clude that race from being picked randomly. Cannot be set with - the `O' command. Persistent. + autoopen + Walking into a closed door attempts to open it (default true). Per- + sistent. - rest_on_space - Make the space bar a synonym for the `.' (#wait) command (de- - fault off). Persistent. + autopickup + Automatically pick up things onto which you move (default off). + Persistent. - role - Pick your type of character (for example "role:Samurai"); syn- - onym for "character". See "name" for an alternate method of - specifying your role. Normally only the first letter of the - value is examined; `r' is an exception with "Rogue", "Ranger", - and "random" values. If you prefix the value with `!' or "no", - you will exclude that role from being picked randomly. Cannot - be set with the `O' command. Persistent. + See pickup_types and also autopickup_exception for ways to refine + the behavior. + Note: prior to version 5.0.0, the default for autopickup was on. - NetHack 3.6 February 3, 2023 + autoquiver + This option controls what happens when you attempt the `f' (fire) + command when nothing is quivered or readied (default false). When + true, the computer will fill your quiver or quiver sack or make + ready some suitable weapon. Note that it will not take into account + the blessed/cursed status, enchantment, damage, or quality of the + weapon; you are free to manually fill your quiver or quiver sack or + make ready with the `Q' command instead. If no weapon is found or + the option is false, the `t' (throw) command is executed instead. + Persistent. + autounlock + Controls what action to take when attempting to walk into a locked + door or to loot a locked container. Takes a plus-sign separated + list of values: + Untrap - prompt about whether to attempt to find a trap; it might + fail to find one even when present; if it does find one, + it will ask whether you want to try to disarm the trap; + if you decline, your character will forget that the door + or box is trapped; + Apply-Key - if carrying a key or other unlocking tool, prompt about + using it; + Kick - kick the door (if you omit untrap or decline to attempt + untrap and you omit apply-key or you lack a key or you + decline to use the key; has no effect on containers); + Force - try to force a container's lid with your currently + wielded weapon (if you omit untrap or decline to attempt + untrap and you omit apply-key or you lack a key or you + decline to use the key; has no effect on doors); + None - none of the above; can't be combined with the other + choices. + Omitting the value is treated as if autounlock:apply-key. Preceding + autounlock with `!' or "no" is treated as autounlock:none. + Applying a key might set off a trap if the door or container is + trapped. Successfully kicking a door will break it and wake up + nearby monsters. Successfully forcing a container open will break + its lock and might also destroy some of its contents or damage your + weapon or both. - NetHack Guidebook 61 + NetHack 5.0.0 May 2, 2026 - roguesymset - This option may be used to select one of the named symbol sets - found within "symbols" to alter the symbols displayed on the - screen on the rogue level. - rlecomp - When writing out a save file, perform run length compression of - the map. Not all ports support run length compression. It has - no effect on reading an existing save file. - runmode - Controls the amount of screen updating for the map window when - engaged in multi-turn movement (running via shift+direction or - control+direction and so forth, or via the travel command or - mouse click). The possible values are: - teleport - update the map after movement has finished; - run - update the map after every seven or so steps; - walk - update the map after each step; - crawl - like walk, but pause briefly after each step. + NetHack Guidebook 67 - This option only affects the game's screen display, not the ac- - tual results of moving. The default is "run"; versions prior - to 3.4.1 used "teleport" only. Whether or not the effect is - noticeable will depend upon the window port used or on the type - of terminal. Persistent. - safe_pet - Prevent you from (knowingly) attacking your pets (default on). - Persistent. - sanity_check - Evaluate monsters, objects, and map prior to each turn (default - off). Debug mode only. + The default is Apply-Key. Persistent. - scores - Control what parts of the score list you are shown at the end - (for example "scores:5 top scores/4 around my score/own - scores"). Only the first letter of each category (`t', `a', or - `o') is necessary. Persistent. + blind + Start the character permanently blind (default false). Persistent. - showexp - Show your accumulated experience points on bottom line (default - off). Persistent. + bones + Allow saving and loading bones files (default true). Persistent. - showrace - Display yourself as the glyph for your race, rather than the - glyph for your role (default off). Note that this setting af- - fects only the appearance of the display, not the way the game - treats you. Persistent. + boulder + Set the character used to display boulders (default is the "large + rock" class symbol, ``'). - showscore - Show your approximate accumulated score on bottom line (default - off). Persistent. + catname + Name your starting cat (for example "catname:Morris"). Cannot be + set with the `O' command. + character + Synonym for "role" to pick the type of your character (for example + "character:Monk"). See role for more details. - NetHack 3.6 February 3, 2023 + checkpoint + Save game state after each level change, for possible recovery after + program crash (default on). Persistent. + cmdassist + Have the game provide some additional command assistance for new + players if it detects some anticipated mistakes (default on). + confirm + Have user confirm attacks on pets, shopkeepers, and other peaceable + creatures (default on). Persistent. + dark_room + Show out-of-sight areas of lit rooms (default on). Persistent. + deaf + Start the character permanently deaf (default false). Persistent. - NetHack Guidebook 62 + dropped_nopick + If this option is on, items you dropped will not be automatically + picked up, even if autopickup is also on and they are in + pickup_types or match a positive autopickup exception (default on). + Persistent. + disclose + Controls what information the program reveals when the game ends. + Value is a space separated list of prompting/category pairs (default + is "ni na nv ng nc no", prompt with default response of `n' for each + candidate). Persistent. The possibilities are: - silent - Suppress terminal beeps (default on). Persistent. - sortloot - Controls the sorting behavior of the pickup lists for inventory - and #loot commands and some others. Persistent. The possible - values are: - full - always sort the lists; - loot - only sort the lists that don't use inventory letters, - like with the #loot and pickup commands; - none - show lists the traditional way without sorting. - sortpack - Sort the pack contents by type when displaying inventory (de- - fault on). Persistent. - sparkle - Display a sparkly effect when a monster (including yourself) is - hit by an attack to which it is resistant (default on). Per- - sistent. - standout - Boldface monsters and "--More--" (default off). Persistent. + NetHack 5.0.0 May 2, 2026 - statushilites - Controls how many turns status hilite behaviors highlight the - field. If negated or set to zero, disables status hiliting. - See "Configuring Status Hilites" for further information. - status_updates - Allow updates to the status lines at the bottom of the screen - (default true). - suppress_alert - This option may be set to a NetHack version level to suppress - alert notification messages about feature changes for that and - prior versions (for example "suppress_alert:3.3.1"). - symset - This option may be used to select one of the named symbol sets - found within "symbols" to alter the symbols displayed on the - screen. Use "symset:default" to explicitly select the default - symbols. - time - Show the elapsed game time in turns on bottom line (default - off). Persistent. + NetHack Guidebook 68 - timed_delay - When pausing momentarily for display effect, such as with ex- - plosions and moving objects, use a timer rather than sending - extra characters to the screen. (Applies to "tty" interface - only; "X11" interface always uses a timer based delay. The - NetHack 3.6 February 3, 2023 + i - disclose your inventory; + a - disclose your attributes; + v - summarize monsters that have been vanquished; + g - list monster species that have been genocided; + c - display your conduct; also achievements, if any; + o - display dungeon overview. + Each disclosure possibility can optionally be preceded by a prefix + which lets you refine how it behaves. Here are the valid prefixes: + y - prompt you and default to yes on the prompt; + n - prompt you and default to no on the prompt; + + - disclose it without prompting; + - - do not disclose it and do not prompt. + The listings of vanquished monsters and of genocided types can be + sorted, so there are two additional choices for `v' and `g': + ? - prompt you and default to ask on the prompt; + # - disclose it without prompting, ask for sort order. - NetHack Guidebook 63 + Asking refers to picking one of the orderings from a menu. The `+' + disclose without prompting choice, or being prompted and answering + `y' rather than `a', will default to showing monsters in the order + specified by the sortvanquished option. + Omitted categories are implicitly added with `n' prefix. Specified + categories with omitted prefix implicitly use `+' prefix. Order of + the disclosure categories does not matter, program display for end- + of-game disclosure follows a set sequence. + (for example "disclose:yi na +v -g o") The example sets inventory to + prompt and default to yes, attributes to prompt and default to no, + vanquished to disclose without prompting, genocided to not disclose + and not prompt, conduct to implicitly prompt and default to no, and + overview to disclose without prompting. - default is on if configured into the program.) Persistent. + Note that the vanquished monsters list includes all monsters killed + by traps and each other as well as by you. And the dungeon overview + shows all levels you had visited but does not reveal things about + them that you hadn't discovered. - tombstone - Draw a tombstone graphic upon your death (default on). Persis- - tent. + dogname + Name your starting dog (for example "dogname:Fang"). Cannot be set + with the `O' command. - toptenwin - Put the ending display in a NetHack window instead of on stdout - (default off). Setting this option makes the score list visi- - ble when a windowing version of NetHack is started without a - parent window, but it no longer leaves the score list around - after game end on a terminal or emulating window. + extmenu + Changes the extended commands interface to pop-up a menu of avail- + able commands. It is keystroke compatible with the traditional + interface except that it does not require that you hit Enter. It is + implemented for the tty interface (default off). - travel - Allow the travel command (default on). Turning this option off - will prevent the game from attempting unintended moves if you - make inadvertent mouse clicks on the map window. Persistent. + For the X11 interface, which always uses a menu for choosing an + extended command, it controls whether the menu shows all available - verbose - Provide more commentary during the game (default on). Persis- - tent. - whatis_coord - When using the `/' or `;' commands to look around on the map - with autodescribe on, display coordinates after the descrip- - tion. Also works in other situations where you are asked to - pick a location. + NetHack 5.0.0 May 2, 2026 - The possible settings are: - c - compass ("east" or "3s" or "2n,4w"); - f - full compass ("east" or "3south" or "2north,4west"); - m - map (map column x=0 is not used); - s - screen [row,column] (row is offset to match tty usage); - n - none (no coordinates shown) [default]. - The whatis_coord option is also used with the "/m", "/M", "/o", - and "/O" sub-commands of `/', where the "none" setting is over- - ridden with "map". - whatis_filter - When getting a location on the map, and using the keys to cycle - through next and previous targets, allows filtering the possi- - ble targets. - n - no filtering [default] - v - in view only - a - in same area only + NetHack Guidebook 69 - The area-filter tries to be slightly predictive -- if you're - standing on a doorway, it will consider the area on the side of - the door you were last moving towards. + commands (on) or just the subset of commands which have tradition- + ally been considered extended ones (off). + female + An obsolete synonym for "gender:female". Cannot be set with the `O' + command. - NetHack 3.6 February 3, 2023 + fireassist + This option controls what happens when you attempt the `f' (fire) + and don't have an appropriate launcher, such as a bow or a sling, + wielded. If on, you will automatically wield the launcher. Default + is on. + fixinv + An object's inventory letter sticks to it when it's dropped (default + on). If this is off, dropping an object shifts all the remaining + inventory letters. Persistent. + force_invmenu + Commands asking for an inventory item show a menu instead of a text + query with possible menu letters. Default is off. + fruit + Name a fruit after something you enjoy eating (for example + "fruit:mango") (default "slime mold"). Basically a nostalgic whimsy + that NetHack uses from time to time. You should set this to some- + thing you find more appetizing than slime mold. Apples, oranges, + pears, bananas, and melons already exist in NetHack, so don't use + those. + gender + Your starting gender (gender:male or gender:female). You may spec- + ify just the first letter. Although you can still denote your gen- + der using either of the deprecated male and female options, if the + gender option is also present it will take precedence. See role for + a description of how to use negation to exclude choices. - NetHack Guidebook 64 + If gender is not specified, there is no default value; player will + be prompted unless role and/or race forces a choice for gender. + Cannot be set with the `O' command. Persistent. + goldX + When filtering objects based on bless/curse state (BUCX), whether to + treat gold pieces as X (unknown bless/curse state, when "on") or U + (known to be uncursed, when "off", the default). Gold is never + blessed or cursed, but it is not described as "uncursed" even when + the implicit_uncursed option is "off". + help + If more information is available for an object looked at with the + `/' command, ask if you want to see it (default on). Turning help + off makes just looking at things faster, since you aren't inter- + rupted with the "More info?" prompt, but it also means that you + might miss some interesting and/or important information. Persis- - Filtering can also be changed when getting a location with the - "getpos.filter" key. - whatis_menu - When getting a location on the map, and using a key to cycle - through next and previous targets, use a menu instead to pick a - target. (default off) + NetHack 5.0.0 May 2, 2026 - whatis_moveskip - When getting a location on the map, and using shifted movement - keys or meta-digit keys to fast-move, instead of moving 8 units - at a time, move by skipping the same glyphs. (default off) - windowtype - When the program has been built to support multiple interfaces, - select which one to use, such as "tty" or "X11" (default de- - pends on build-time settings; use "#version" to check). Cannot - be set with the `O' command. - When used, it should be the first option set since its value - might enable or disable the availability of various other op- - tions. For multiple lines in a configuration file, that would - be the first non-comment line. For a comma-separated list in - NETHACKOPTIONS or an OPTIONS line in a configuration file, that - would be the rightmost option in the list. - wizweight - Augment object descriptions with their objects' weight (default - off). Debug mode only. - zerocomp - When writing out a save file, perform zero-comp compression of - the contents. Not all ports support zero-comp compression. It - has no effect on reading an existing save file. + NetHack Guidebook 70 - 9.5. Window Port Customization options - Here are explanations of the various options that are used - to customize and change the characteristics of the windowtype - that you have chosen. Character strings that are too long may be - truncated. Not all window ports will adjust for all settings - listed here. You can safely add any of these options to your - configuration file, and if the window port is capable of adjust- - ing to suit your preferences, it will attempt to do so. If it - can't it will silently ignore it. You can find out if an option - is supported by the window port that you are currently using by - checking to see if it shows up in the Options list. Some options - are dynamic and can be specified during the game with the `O' - command. - align_message - Where to align or place the message window (top, bottom, left, - or right) + tent. + herecmd_menu + When using a windowport that supports mouse and clicking on yourself + or next to you, show a menu of possible actions for the location. + Same as "#herecmdmenu" and "#therecmdmenu" commands. + hilite_pet + Visually distinguish pets from similar animals (default off). The + behavior of this option depends on the type of windowing you use. + In text windowing, text highlighting or inverse video is often used; + with tiles, generally displays a heart symbol near pets. - NetHack 3.6 February 3, 2023 + With the tty or curses interface, the petattr option controls how to + highlight pets and setting it will turn the hilite_pet option on or + off as warranted. + hilite_pile + Visually distinguish piles of objects from individual objects + (default off). The behavior of this option depends on the type of + windowing you use. In text windowing, text highlighting or inverse + video is often used; with tiles, generally displays a small plus- + symbol beside the object on the top of the pile. + hitpointbar + Show a hit point bar graph behind your name and title in the status + display (default off). + The "curses" interface supports it even if the status highlighting + feature has been disabled when building the program. The "tty" and + "mswin" (aka "Windows GUI") interfaces support it only if status + highlighting is left enabled when building. You don't need to set + up any highlighting rules in order to display the bar. If there is + one for hitpoints in effect and it specifies color, that color will + be used for the bar. However if it specifies video attributes, they + will be ignored in favor of inverse. For tty and curses, blink will + also be used if the current hitpoint value is at or below the criti- + cal HP threshold. + The "Qt" interface also supports hitpointbar, by drawing a solid bar + above the name and title with a hard-coded color scheme. (As of + this writing, having the bar enabled unintentionally inhibits resiz- + ing the status panel. To resize that, use the #optionsfull command + to toggle the hitpointbar option off, perform the resize while it's + off, then use the same command to toggle it back on.) - NetHack Guidebook 65 + horsename + Name your starting horse (for example "horsename:Trigger"). Cannot + be set with the `O' command. + ignintr + Ignore interrupt signals, including breaks (default off). Persis- + tent. - align_status - Where to align or place the status window (top, bottom, left, - or right). - ascii_map - If NetHack can, it should display an ascii character map if it - can. + NetHack 5.0.0 May 2, 2026 - color - If NetHack can, it should display color if it can for different - monsters, objects, and dungeon features. - eight_bit_tty - If NetHack can, it should pass eight-bit character values (for - example, specified with the traps option) straight through to - your terminal (default off). - font_map - if NetHack can, it should use a font by the chosen name for the - map window. - font_menu - If NetHack can, it should use a font by the chosen name for - menu windows. - font_message - If NetHack can, it should use a font by the chosen name for the - message window. + NetHack Guidebook 71 - font_status - If NetHack can, it should use a font by the chosen name for the - status window. - font_text - If NetHack can, it should use a font by the chosen name for - text windows. - font_size_map - If NetHack can, it should use this size font for the map win- - dow. + implicit_uncursed + Omit "uncursed" from object descriptions when it can be deduced from + other aspects of the description (default on). Persistent. - font_size_menu - If NetHack can, it should use this size font for menu windows. + If you use menu coloring, you may want to turn this off. - font_size_message - If NetHack can, it should use this size font for the message - window. + legacy + Display an introductory message when starting the game (default on). + Persistent. - font_size_status - If NetHack can, it should use this size font for the status - window. + lit_corridor + Show corridor squares seen by night vision or a light source held by + your character as lit (default off). Persistent. - font_size_text - If NetHack can, it should use this size font for text windows. + lootabc + When using a menu to interact with a container, use the old `a', + `b', and `c' keyboard shortcuts rather than the mnemonics `o', `i', + and `b' (default off). Persistent. + mail + Enable mail delivery during the game (default on). Persistent. - NetHack 3.6 February 3, 2023 + male + An obsolete synonym for "gender:male". Cannot be set with the `O' + command. + mention_decor + Give feedback when walking onto various dungeon features such as + stairs, fountains, or altars which are ordinarily only described + when covered by one or more objects (default off). Cannot be set + with the `O' command. Persistent. + mention_map + Give feedback when interesting map locations change (default off). + mention_walls + Give feedback when walking against a wall (default off). Persis- + tent. + menucolors + Enable coloring menu lines (default off). See "Configuring Menu + Colors" on how to configure the colors. - NetHack Guidebook 66 + menustyle + Controls the method used when you need to choose various objects (in + response to the Drop (aka droptype) command, for instance). The + value specified should be the first letter of one of the following: + traditional, combination, full, or partial. Default is full. Per- + sistent. + Traditional was the only method available for very early versions; + it consists of a prompt for object class characters, followed by an + object-by-object prompt for all items matching the selected object + class(es). Combination starts with a prompt for object class(es) of - fullscreen - If NetHack can, it should try and display on the entire screen - rather than in a window. + NetHack 5.0.0 May 2, 2026 - guicolor - Use color text and/or highlighting attributes when displaying - some non-map data (such as menu selector letters). Curses in- - terface only; default is on. - large_font - If NetHack can, it should use a large font. - map_mode - If NetHack can, it should display the map in the manner speci- - fied. - player_selection - If NetHack can, it should pop up dialog boxes, or use prompts - for character selection. - popup_dialog - If NetHack can, it should pop up dialog boxes for input. + NetHack Guidebook 72 - preload_tiles - If NetHack can, it should preload tiles into memory. For exam- - ple, in the protected mode MS-DOS version, control whether - tiles get pre-loaded into RAM at the start of the game. Doing - so enhances performance of the tile graphics, but uses more - memory. (default on). Cannot be set with the `O' command. - scroll_amount - If NetHack can, it should scroll the display by this number of - cells when the hero reaches the scroll_margin. - scroll_margin - If NetHack can, it should scroll the display when the hero or - cursor is this number of cells away from the edge of the win- - dow. + interest, but then displays a menu of matching objects rather than + prompting one-by-one. Full displays a menu of object classes rather + than a character prompt, and then a menu of matching objects for + selection. (Choosing its `A' (Autoselect-All) choice skips the sec- + ond menu. To avoid choosing that by accident, set paranoid_con- + firm:AutoAll to require confirmation.) Partial skips the object + class filtering and immediately displays a menu of all objects. - selectsaved - If NetHack can, it should display a menu of existing saved - games for the player to choose from at game startup, if it can. - Not all ports support this option. + menu_deselect_all + Key to deselect all items in a menu. Default `-'. - softkeyboard - Display an onscreen keyboard. Handhelds are most likely to - support this option. + menu_deselect_page + Key to deselect all items on this page of a menu. Default `\'. - splash_screen - If NetHack can, it should display an opening splash screen when - it starts up (default yes). + menu_first_page + Key to jump to the first page in a menu. Default `^'. - statuslines - Number of lines for traditional below-the-map status display. + menu_headings + Controls how the headings in a menu are highlighted. Takes a text + attribute, or text color and attribute separated by ampersand. For + allowed attributes and colors, see "Configuring Menu Colors". Not + all ports can actually display all types. + menu_invert_all + Key to invert all items in a menu. Default `@'. - NetHack 3.6 February 3, 2023 + menu_invert_page + Key to invert all items on this page of a menu. Default `~'. + menu_last_page + Key to jump to the last page in a menu. Default `|'. + menu_next_page + Key to go to the next menu page. Default `>'. + menu_objsyms + Inventory and other object menus are normally separated by object + class (weapons, armor, and so forth), with a menu header line at the + beginning of each group. You can have menus add the display symbol + for the class of objects for each header line. You can also add the + display symbol for the individual item in each menu entry. For a + tiles map, that would be a small rendition of an object's tile. For + a text map, it is the same character as is used for the object's + class, which would be most useful when there are no headers separat- + ing objects among classes. Possible values are + 0 - None - no symbols for either header lines or menu + entries; + 1 - Headers - show symbols on header lines but not entries; + 2 - Entries - show symbols on menu entry lines but not headers; + 3 - Both - show symbols on headers and entries; + 4 - Conditional - only show symbols for entries if there are no + headers; + 5 - One-or-other - show symbols on headers, or on entries if no - NetHack Guidebook 67 + NetHack 5.0.0 May 2, 2026 - Acceptable values are 2 and 3 (default is 2). Curses and tty - interfaces only. - term_cols and - term_rows - Curses interface only. Number of columns and rows to use for - the display. Curses will attempt to resize to the values spec- - ified but will settle for smaller sizes if they are too big. - Default is the current window size. - tiled_map - If NetHack can, it should display a tiled map if it can. + NetHack Guidebook 73 - tile_file - Specify the name of an alternative tile file to override the - default. - tile_height - Specify the preferred height of each tile in a tile capable - port. - tile_width - Specify the preferred width of each tile in a tile capable port + headers. - use_darkgray - Use bold black instead of blue for black glyphs (TTY only). + Supported by tty and curses. When setting the value, it can be + specified by digit or keyword. The default value is Conditional + (4). - use_inverse - If NetHack can, it should display inverse when the game speci- - fies it. + menu_overlay + Do not clear the screen before drawing menus, and align menus to the + right edge of the screen. Only for the tty port. (default on) - vary_msgcount - If NetHack can, it should display this number of messages at a - time in the message window. + menu_previous_page + Key to go to the previous menu page. Default `<'. - windowborders - Whether to draw boxes around the map, status area, message - area, and persistent inventory window if enabled. Curses in- - terface only. Acceptable values are + menu_search + Key to search for some text and toggle selection state of matching + menu items. Default `:'. - 0 - off, never show borders - 1 - on, always show borders - 2 - auto, on if display is at least (24+2)x(80+2) (default) + menu_select_all + Key to select all items in a menu. Default `.'. - (The 26x82 size threshold for `2' refers to number of rows and - columns of the display. A width of at least 110 columns - (80+2+26+2) is needed for align_status set to left or right.) + menu_select_page + Key to select all items on this page of a menu. Default `,'. - windowcolors - If NetHack can, it should display windows with the specified - foreground/background colors. Windows GUI only. The format is + menu_shift_left + Key to scroll a menu--one which has been scrolled right--back to the + left. Implemented for perm_invent only by curses and X11. Default + `{'. + menu_shift_right + Key to scroll a menu which has text beyond the right edge to the + right. Implemented for perm_invent only by curses and X11. Default + `}'. + mon_movement + Show a message when hero notices a monster movement (default is + off). + monpolycontrol + Prompt for new form whenever any monster changes shape (default + off). Debug mode only. - NetHack 3.6 February 3, 2023 + montelecontrol + Prompt for destination whenever any monster gets teleported (default + off). Debug mode only. + mouse_support + Allow use of the mouse for input and travel. Valid settings are: + 0 - disabled + 1 - enabled and make OS adjustments to support mouse use + 2 - like 1 but does not make any OS adjustments + Omitting a value is the same as specifying 1 and negating mouse_sup- + port is the same as specifying 0. - NetHack Guidebook 68 + NetHack 5.0.0 May 2, 2026 - OPTION=windowcolors:wintype foreground/background - where wintype is one of "menu", "message", "status", or - "text", and foreground and background are colors, either a hexa- - decimal \'#rrggbb', one of the named colors (black, red, green, - brown, blue, magenta, cyan, orange, brightgreen, yellow, bright- - blue, brightmagenta, brightcyan, white, trueblack, gray, purple, - silver, maroon, fuchsia, lime, olive, navy, teal, aqua), or one - of Windows UI colors (activeborder, activecaption, appworkspace, - background, btnface, btnshadow, btntext, captiontext, graytext, - greytext, highlight, highlighttext, inactiveborder, inactivecap- - tion, menu, menutext, scrollbar, window, windowframe, window- - text). - wraptext - If NetHack can, it should wrap long lines of text if they don't - fit in the visible area of the window. + NetHack Guidebook 74 - 9.6. Platform-specific Customization options - Here are explanations of options that are used by specific - platforms or ports to customize and change the port behavior. - altkeyhandling - Select an alternate way to handle keystrokes (Win32 tty NetHack - only). The name of the handling type is one of "default", - "ray", "340". + msghistory + The number of top line messages to keep (and be able to recall with + `^P') (default 20). Cannot be set with the `O' command. - altmeta - On Amiga, this option controls whether typing "Alt" plus anoth- - er key functions as a meta-shift for that key (default on). + msg_window + Allows you to change the way recalled messages are displayed. Cur- + rently it is only supported for tty (all four choices) and for + curses (`f' and `r' choices, default `r'). The possible values are: - altmeta - On other (non-Amiga) systems where this option is available, it - can be set to tell NetHack to convert a two character sequence - beginning with ESC into a meta-shifted version of the second - character (default off). + s - single message (default; only choice prior to 3.4.0); + c - combination, two messages as "single", then as "full"; + f - full window, oldest message first; + r - full window reversed, newest message first. - This conversion is only done for commands, not for other input - prompts. Note that typing one or more digits as a count prefix - prior to a command -- preceded by n if the number_pad option is - set -- is also subject to this conversion, so attempting to - abort the count by typing ESC will leave NetHack waiting for - another character to complete the two character sequence. Type - a second ESC to finish cancelling such a count. At other - prompts a single ESC suffices. + For backward compatibility, no value needs to be specified (which + defaults to "full"), or it can be negated (which defaults to "sin- + gle"). - BIOS - Use BIOS calls to update the screen display quickly and to read - the keyboard (allowing the use of arrow keys to move) on ma- - chines with an IBM PC compatible BIOS ROM (default off, OS/2, - PC, and ST NetHack only). + name + Set your character's name (defaults to your user name). You can + also set your character's role by appending a dash and one or more + letters of the role (that is, by suffixing one of -A -B -C -H -K -M + -P -Ra -Ro -S -T -V -W). If -@ is used for the role, then a random + one will be automatically chosen. + On some systems, the default is the player's user name; on others, + there is no default and the player will be prompted. The former can + made to behave like the latter by specifying a generic name such as + ``player''. Cannot be set with the `O' command. + news + Read the NetHack news file, if present (default on). Since the news + is shown at the beginning of the game, there's no point in setting + this with the `O' command. + nudist + Start the character with no armor (default false). Persistent. - NetHack 3.6 February 3, 2023 + null + Send padding nulls to the terminal (default on). Persistent. + number_pad + Use digit keys instead of letters to move (default 0 or off). Valid + settings are: + 0 - move by letters; "yuhjklbn" + 1 - move by numbers; digit `5' acts as `G' movement prefix + 2 - like 1 but `5' works as `g' prefix instead of as `G' + 3 - by numbers using phone key layout; 123 above, 789 below + 4 - combines 3 with 2; phone layout plus MS-DOS compatibility + -1 - by letters but use `z' to go northwest, `y' to zap wands + For backward compatibility, omitting a value is the same as specify- + ing 1 and negating number_pad is the same as specifying 0. (Set- - NetHack Guidebook 69 + NetHack 5.0.0 May 2, 2026 - flush - (default off, Amiga NetHack only). - MACgraphics - (default on, Mac NetHack only). - page_wait - (default on, Mac NetHack only). + NetHack Guidebook 75 - rawio - Force raw (non-cbreak) mode for faster output and more bullet- - proof input (MS-DOS sometimes treats `^P' as a printer toggle - without it) (default off, OS/2, PC, and ST NetHack only). - Note: DEC Rainbows hang if this is turned on. Cannot be set - with the `O' command. - soundcard - (default on, PC NetHack only). Cannot be set with the `O' com- - mand. - subkeyvalue - (Win32 tty NetHack only). May be used to alter the value of - keystrokes that the operating system returns to NetHack to help - compensate for international keyboard issues. OPTIONS=subkey- - value:171/92 will return 92 to NetHack, if 171 was originally - going to be returned. You can use multiple subkeyvalue state- - ments in the configuration file if needed. Cannot be set with - the `O' command. + tings 2 and 4 are for compatibility with MS-DOS or old PC Hack; in + addition to the different behavior for `5', `Alt-5' acts as `G' and + `Alt-0' acts as `I'. Setting -1 is to accommodate some QWERTZ key- + boards which have the location of the `y' and `z' keys swapped.) + When moving by numbers, to enter a count prefix for those commands + which accept one (such as "12s" to search twelve times), precede it + with the letter `n' ("n12s"). - video - Set the video mode used (PC NetHack only). Values are "autode- - tect", "default", or "vga". Setting "vga" (or "autodetect" - with vga hardware present) will cause the game to display - tiles. Cannot be set with the `O' command. + packorder + Specify the order to list object types in (default + "")[%?+!=/(*`0_"). The value of this option should be a string con- + taining the symbols for the various object types. Any omitted types + are filled in at the end from the previous order. - videocolors - Set the color palette for PC systems using NO_TERMS (default - 4-2-6-1-5-3-15-12-10-14-9-13-11, (PC NetHack only). The order - of colors is red, green, brown, blue, magenta, cyan, - bright.white, bright.red, bright.green, yellow, bright.blue, - bright.magenta, and bright.cyan. Cannot be set with the `O' - command. + paranoid_confirmation + A space separated list of specific situations where alternate + prompting is desired. The default is "paranoid_confirmation:pray + swim trap". - videoshades - Set the intensity level of the three gray scales available (de- - fault dark normal light, PC NetHack only). If the game display - is difficult to read, try adjusting these scales; if this does - not correct the problem, try !color. Cannot be set with the - `O' command. + Confirm - for any prompts which are set to require "yes" rather + than `y', also require "no" to reject instead of + accepting any non-yes response as no; changes pray and + AutoAll to require "yes" or `no' too; + quit - require "yes" rather than `y' to confirm quitting the + game or switching into non-scoring explore mode; + die - require "yes" rather than `y' to confirm dying (not + useful in normal play; applies to explore mode); + bones - require "yes" rather than `y' to confirm saving bones + data when dying in debug mode; + attack - require "yes" rather than `y' to confirm attacking a + peaceful monster; + wand-break - require "yes" rather than `y' to confirm breaking a + wand with the apply command; + eating - require "yes" rather than `y' to confirm whether to + continue eating; + Were-change - require "yes" rather than `y' to confirm changing form + due to lycanthropy when hero has polymorph control; + pray - require `y' to confirm an attempt to pray rather than + immediately praying; on by default; (to require "yes" + rather than just `y', set Confirm too); + trap - require `y' to confirm an attempt to move into or onto + a known trap, unless doing so is considered to be + harmless; when enabled, this confirmation is also used + for moving into visible gas cloud regions; (to require + "yes" rather than just `y', set Confirm too); confir- + mation can be skipped by using the `m' movement pre- + fix; + swim - prevent walking into water or lava; on by default; (to + deliberately step onto/into such terrain when this is + set, use the `m' movement prefix when adjacent); + AutoAll - require confirmation when the `A' (Autoselect-All) + choice is selected in object class filtering menus for + menustyle:Full; (to require "yes" rather than just + `y', set Confirm too); - 9.7. Regular Expressions - Regular expressions are normally POSIX extended regular ex- - pressions. It is possible to compile NetHack without regular + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 76 - NetHack Guidebook 70 + Remove - require selection from inventory for `R' and `T' com- + mands even when wearing just one applicable item; + all - turn on all of the above. + By default, the pray, swim, and trap choices are enabled, the others + disabled. To disable them without setting any of the other choices, + use paranoid_confirmation:none. To keep them enabled while setting + any of the others, you can include them in the new list, such as + paranoid_confirmation:attack pray swim Remove or you can precede the + first entry in the list with a plus sign, paranoid_confirma- + tion:+attack Remove. To remove an entry that has been previously + set without removing others, precede the first entry in the list + with a minus sign, paranoid_confirmation:-swim. To both add some + new entries and remove some old ones, you can use multiple para- + noid_confirmation option settings, or you can use the `+' form and + list entries to be added by their name and entries to be removed by + `!' and name. The positive (no `!') and negative (with `!') entries + can be intermixed. - expression support on a platform where there is no regular ex- - pression library. While this is not true of any modern platform, - if your NetHack was built this way, patterns are instead glob - patterns. This applies to Autopickup exceptions, Message types, - Menu colors, and User sounds. + pauper + Start the character with no possessions (default false). Persis- + tent. - 9.8. Configuring Autopickup Exceptions + Also start with no spells or skills, which are tied to starting + equipment. Does not inhibit acquiring and using items, spells, and + skills once play has started. - You can further refine the behavior of the autopickup option - beyond what is available through the pickup_types option. + perm_invent + If true, always display your current inventory in a window (default + false). - By placing autopickup_exception lines in your configuration - file, you can define patterns to be checked when the game is - about to autopickup something. + This only makes sense for windowing system interfaces that implement + this feature. For those that do, the perminv_mode option can be + used to refine what gets displayed for perm_invent. Setting that to + a value other than none while perm_invent is false will change it to + true. - autopickup_exception - Sets an exception to the pickup_types option. The autopick- - up_exception option should be followed by a regular expression - to be used as a pattern to match against the singular form of - the description of an object at your location. + perminv_mode + Augments the perm_invent option. Value is one of - In addition, some characters are treated specially if they oc- - cur as the first character in the pattern, specifically: + none - behave as if perm_invent is false; + all - show all inventory except for gold; + full - show full inventory including gold; + in-use - only show items which are in use (worn, wielded, lit lamp). - < - always pickup an object that matches rest of pattern; - > - never pickup an object that matches rest of pattern. + Default is none but if perm_invent gets set to true while it is none + it will be changed to all. - The autopickup_exception rules are processed in the order in - which they appear in your configuration file, thus allowing a - later rule to override an earlier rule. + Note: if gold has been equipped in quiver/ammo-pouch then it will be + included for all despite that mode normally omitting gold. - Exceptions can be set with the `O' command, but because they - are not included in your configuration file, they won't be in - effect if you save and then restore your game. autopickup_ex- - ception rules and not saved with the game. + petattr + Specifies one or more text highlighting attributes to use when show- + ing pets on the map. Effectively a superset of the hilite_pet bool- - Here are some examples: - autopickup_exception="<*arrow" - autopickup_exception=">*corpse" - autopickup_exception=">* cursed*" + NetHack 5.0.0 May 2, 2026 - The first example above will result in autopickup of any - type of arrow. The second example results in the exclusion of - any corpse from autopickup. The last example results in the ex- - clusion of items known to be cursed from autopickup. - 9.9. Changing Key Bindings - It is possible to change the default key bindings of some - special commands, menu accelerator keys, and extended commands, - by using BIND stanzas in the configuration file. Format is key, - followed by the command to bind to, separated by a colon. The - key can be a single character ("x"), a control key ("^X", "C-x"), - NetHack 3.6 February 3, 2023 + NetHack Guidebook 77 + ean option. Curses or tty interface only; value is one of none, + bold, dim, underline, italic, blink, and inverse. Some of those + choices might not work, depending upon terminal hardware or terminal + emulation software. + pettype + Specify the type of your initial pet, if you are playing a character + class that uses multiple types of pets; or choose to have no initial + pet at all. Possible values are "cat", "dog", "horse", and "none". + If the choice is not allowed for the role you are currently playing, + it will be silently ignored. For example, "horse" will only be hon- + ored when playing a knight. Cannot be set with the `O' command. - NetHack Guidebook 71 + pickup_burden + When you pick up an item that would exceed this encumbrance level + (Unencumbered, Burdened, streSsed, straiNed, overTaxed, or over- + Loaded), you will be asked if you want to continue. (Default `S'). + Persistent. + pickup_stolen + If this option is on and autopickup is also on, try to pick up + things that a monster stole from you, even if they aren't in + pickup_types or match an autopickup exception. Default is on. Per- + sistent. + pickup_thrown + If this option is on and autopickup is also on, try to pick up + things that you threw, even if they aren't in pickup_types or match + an autopickup exception. Default is on. Persistent. - a meta key ("M-x"), or a three-digit decimal ASCII code. + pickup_types + Specify the object types to be picked up when autopickup is on. + Default is all types. Persistent. - For example: + The value is a list of object symbols, such as pickup_types:$?! to + pick up gold, scrolls, and potions. You can use autopickup_excep- + tion configuration file lines to further refine autopickup behavior. - BIND=^X:getpos.autodescribe - BIND={:menu_first_page - BIND=v:loot + There is no way to set pickup_types to "none". (Setting it to an + empty value reverts to "all".) If you want to avoid automatically + picking up any types of items but do want to have autopickup on in + order to have autopickup_exception settings control what you do and + don't pick up, you can set pickup_types to `.'. That is the type + symbol for venom and you won't come across any venom items so won't + unintentionally pick such up. - Extended command keys - You can bind multiple keys to the same extended command. Un- - bind a key by using "nothing" as the extended command to bind - to. You can also bind the "", "", and "" - keys. + pile_limit + When walking across a pile of objects on the floor, threshold at + which the message "there are few/several/many objects here" is given + instead of showing a popup list of those objects. A value of 0 + means "no limit" (always list the objects); a value of 1 effectively + means "never show the objects" since the pile size will always be at + least that big; default value is 5. Persistent. - Menu accelerator keys - The menu control or accelerator keys can also be rebound via - OPTIONS lines in the configuration file. You cannot bind ob- - ject symbols into menu accelerators. - Special command keys - Below are the special commands you can rebind. Some of them - can be bound to same keys with no problems, others are in the - same "context", and if bound to same keys, only one of those - commands will be available. Special command can only be bound - to a single key. - count - Prefix key to start a count, to repeat a command this many - times. With number_pad only. Default is `n'. + NetHack 5.0.0 May 2, 2026 - doinv - Show inventory. With number_pad only. Default is `0'. - fight - Prefix key to force fight a direction. Default is `F'. - fight.numpad - Prefix key to force fight a direction. With number_pad only. - Default is `-'. - getdir.help - When asked for a direction, the key to show the help. Default - is `?'. - getdir.self - When asked for a direction, the key to target yourself. De- - fault is `.'. + NetHack Guidebook 78 - getdir.self2 - When asked for a direction, the key to target yourself. De- - fault is `s'. - getpos.autodescribe - When asked for a location, the key to toggle autodescribe. + playmode + Values are "normal", "explore", or "debug". Allows selection of + explore mode (also known as discovery mode) or debug mode (also + known as wizard mode) instead of normal play. Debug mode might only + be allowed for someone logged in under a particular user name (on + multi-user systems) or specifying a particular character name (on + single-user systems) or it might be disabled entirely. Requesting + it when not allowed or not possible results in explore mode instead. + Default is normal play. - NetHack 3.6 February 3, 2023 + price_quotes + Whenever the game mentions the name of an object you haven't identi- + fied yet, it also mentions the range of buy and sell prices you have + seen for that item (to help narrow down what it could be). The + price shown is the unit price for one item (even when you are look- + ing at a stack of multiple items). Many players may want to turn + this on while identifying objects, and then turn it back off again + for general play. Default is off. + pushweapon + Using the `w' (wield) command when already wielding something pushes + the old item into your alternate weapon slot (default off). Like- + wise for the `a' (apply) command if it causes the applied item to + become wielded. Persistent. + query_menu + Use a menu when asked specific yes/no queries, instead of a prompt. + quick_farsight + When set, usually prevents the "you sense your surroundings" message + where play pauses to allow you to browse the map whenever clairvoy- + ance randomly activates. Some situations, such as being underwater + or engulfed, ignore this option. It does not affect the clairvoy- + ance spell where pausing to examine revealed objects or monsters is + less intrusive. Default is off. Persistent. + race + Selects your race (for example, race:human). Choices are human, + dwarf, elf, gnome, and orc but most roles restrict which of the non- + human races are allowed. See role for a description of how to use + negation to exclude choices. - NetHack Guidebook 72 + If race is not specified, there is no default value; player will be + prompted unless role forces a choice for race. Cannot be set with + the `O' command. Persistent. + reroll + Allows rerolling your character's starting inventory and attributes + (default false). Persistent. + Note that rerolling your character is not a recommended way to play + if aiming merely to win (a lucky start has a much smaller influence + on whether or not you win the game than your actions later in the + game). This option exists partly as an acknowledgement that some - Default is `#'. - getpos.all.next - When asked for a location, the key to go to next closest inter- - esting thing. Default is `a'. + NetHack 5.0.0 May 2, 2026 - getpos.all.prev - When asked for a location, the key to go to previous closest - interesting thing. Default is `A'. - getpos.door.next - When asked for a location, the key to go to next closest door - or doorway. Default is `d'. - getpos.door.prev - When asked for a location, the key to go to previous closest - door or doorway. Default is `D'. - getpos.help - When asked for a location, the key to show help. Default is - `?'. - getpos.mon.next - When asked for a location, the key to go to next closest mon- - ster. Default is `m'. + NetHack Guidebook 79 - getpos.mon.prev - When asked for a location, the key to go to previous closest - monster. Default is `M'. - getpos.obj.next - When asked for a location, the key to go to next closest ob- - ject. Default is `o'. - getpos.obj.prev - When asked for a location, the key to go to previous closest - object. Default is `O'. + players will insist on doing so anyway, and partly because rerolling + may be necessary for certain types of challenge games. - getpos.menu - When asked for a location, and using one of the next or previ- - ous keys to cycle through targets, toggle showing a menu in- - stead. Default is `!'. + rest_on_space + Make the space bar a synonym for the `.' (#wait) command (default + off). Persistent. - getpos.moveskip - When asked for a location, and using the shifted movement keys - or meta-digit keys to fast-move around, move by skipping the - same glyphs instead of by 8 units. Default is `*'. + role + Pick your type of character (for example, role:Samurai); synonym for + character. See name for an alternate method of specifying your + role. - getpos.filter - When asked for a location, change the filtering mode when using - one of the next or previous keys to cycle through targets. - Toggles between no filtering, in view only, and in the same - area only. Default is `"'. + This option can also be used to limit selection when role is chosen + randomly. Use a space-separated list of roles and either negate + each one or negate the option itself instead. Negation is accom- + plished in the same manner as with boolean options, by prefixing the + option or its value(s) with `!' or "no". + Examples: + OPTIONS=role:!arc !bar !kni + OPTIONS=!role:arc bar kni + There can be multiple instances of the role option if they're all + negations. - NetHack 3.6 February 3, 2023 + If role is not specified, there is no default value; player will be + prompted. Cannot be set with the `O' command. Persistent. + roguesymset + This option may be used to select one of the named symbol sets found + within "symbols" to alter the symbols displayed on the screen on the + rogue level. + rlecomp + When writing out a save file, perform run length compression of the + map. Not all ports support run length compression. It has no effect + on reading an existing save file. + runmode + Controls the amount of screen updating for the map window when + engaged in multi-turn movement (running via shift+direction or con- + trol+direction and so forth, or via the travel command or mouse + click). The possible values are: + teleport - update the map after movement has finished; + run - update the map after every seven or so steps; + walk - update the map after each step; + crawl - like walk, but pause briefly after each step. - NetHack Guidebook 73 + This option only affects the game's screen display, not the actual + results of moving. The default is "run"; versions prior to 3.4.1 + used "teleport" only. Whether or not the effect is noticeable will + depend upon the window port used or on the type of terminal. Per- + sistent. + NetHack 5.0.0 May 2, 2026 - getpos.pick - When asked for a location, the key to choose the location, and - possibly ask for more info. Default is `.'. - getpos.pick.once - When asked for a location, the key to choose the location, and - skip asking for more info. Default is `,'. - getpos.pick.quick - When asked for a location, the key to choose the location, skip - asking for more info, and exit the location asking loop. De- - fault is `;'. - getpos.pick.verbose - When asked for a location, the key to choose the location, and - show more info without asking. Default is `:'. - getpos.self - When asked for a location, the key to go to your location. De- - fault is `@'. + NetHack Guidebook 80 - getpos.unexplored.next - When asked for a location, the key to go to next closest unex- - plored location. Default is `x'. - getpos.unexplored.prev - When asked for a location, the key to go to previous closest - unexplored location. Default is `X'. - getpos.valid - When asked for a location, the key to go to show valid target - locations. Default is `$'. + safe_pet + Prevent you from (knowingly) attacking your pets (default on). Per- + sistent. - getpos.valid.next - When asked for a location, the key to go to next closest valid - location. Default is `z'. + safe_wait + Prevents you from waiting or searching when next to a hostile mon- + ster (default on). Persistent. - getpos.valid.prev - When asked for a location, the key to go to previous closest - valid location. Default is `Z'. + sanity_check + Evaluate monsters, objects, and map prior to each turn (default + off). Debug mode only. - nopickup - Prefix key to move without picking up items. Default is `m'. + scores + Control what parts of the score list you are shown at the end (for + example "scores:5 top scores/4 around my score/own scores"). Only + the first letter of each category (`t', `a', or `o') is necessary. + Persistent. - redraw - Key to redraw the screen. Default is `^R'. + showdamage + Whenever your character takes damage, show a message of the damage + taken, and the amount of hit points left. - redraw.numpad - Key to redraw the screen. With number_pad only. Default is - `^L'. + showexp + Show your accumulated experience points on bottom line (default + off). Persistent. - repeat - Key to repeat previous command. Default is `^A'. + showrace + Display yourself as the glyph for your race, rather than the glyph + for your role (default off). Note that this setting affects only + the appearance of the display, not the way the game treats you. + Persistent. + showscore + Show your approximate accumulated score on bottom line (default + off). By default, this feature is suppressed when building the pro- + gram. Persistent. + showvers + Include the game's version number on the status lines (default off). + Potentially useful if you switch between different versions or vari- + ants, or you are making screenshots or streaming video. Using the + statuslines:3 option is recommended so that there will be more room + available for status information, unless you're using NetHack's Qt + interface or your terminal emulator window displays fewer than 25 + lines. Persistent. - NetHack 3.6 February 3, 2023 + The versinfo option provides limited control over what information + showvers displays. + silent + Suppress terminal beeps (default on). Persistent. + sortdiscoveries + Controls the sorting behavior for the output of the `\' and ``' com- + NetHack 5.0.0 May 2, 2026 - NetHack Guidebook 74 - reqmenu - Prefix key to request menu from some commands. Default is `m'. - run - Prefix key to run towards a direction. Default is `G'. + NetHack Guidebook 81 - run.nopickup - Prefix key to run towards a direction without picking up items - on the way. Default is `M'. - run.numpad - Prefix key to run towards a direction. With number_pad only. - Default is `5'. - rush - Prefix key to rush towards a direction. Default is `g'. + mands. Persistent. - 9.10. Configuring Message Types + The possible values are: - You can change the way the messages are shown in the message - area, when the message matches a user-defined pattern. + o - list object types by class, in discovery order within each + class; default; + s - list object types by sortloot classification: by class, by sub- + class within class for classes which have substantial groupings + (like helmets, boots, gloves, and so forth for armor), with + object types partly-discovered via assigned name coming before + fully identified types; + c - list by class, alphabetically within each class; + a - list alphabetically across all classes. - In general, the configuration file entries to describe the - message types look like this: MSGTYPE=type "pattern" + Can be interactively set via the `O' command or via using the `m' + prefix before the `\' or ``' command. - type - how the message should be shown; - pattern - the pattern to match. + sortloot + Controls the sorting behavior of the pickup lists for inventory and + #loot commands and some others. Persistent. - The pattern should be a regular expression. + The possible values are: - Allowed types are: + full - always sort the lists; + loot - only sort the lists that don't use inventory letters, like + with the #loot and pickup commands; + none - show lists the traditional way without sorting; default. - show - show message normally; - hide - never show the message; - stop - wait for user with more-prompt; - norep - show the message once, but not again if no other mes- - sage is shown in between. + sortpack + Sort the pack contents by type when displaying inventory (default + on). Persistent. - Here's an example of message types using NetHack's internal - pattern matching facility: + sortvanquished + Controls the sorting behavior for the output of the #vanquished com- + mand and also for the #genocided command. Persistent. - MSGTYPE=stop "You feel hungry." - MSGTYPE=hide "You displaced *." + The possible values are: - specifies that whenever a message "You feel hungry" is shown, - the user is prompted with more-prompt, and a message matching - "You displaced ." is not shown at all. + t - traditional--order by monster level; ties are broken by internal + monster index; default; + d - order by monster difficulty rating; ties broken by internal + index; + a - order alphabetically, first any unique monsters then all the + others; + c - order by monster class, by low to high level within each class; + n - order by count, high to low; ties are broken by internal monster + index; + z - order by count, low to high; ties broken by internal index. - The order of the defined MSGTYPE lines is important; the last - matching rule is used. Put the general case first, exceptions - below them. + Can be interactively set via the `m O' command or via using the `m' + prefix before either the #vanquished command or the #genocided com- + mand. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 82 - NetHack Guidebook 75 + sounds + Allow sounds to be emitted from an integrated sound library (default + on). - 9.11. Configuring Menu Colors + sparkle + Display a sparkly effect when a monster (including yourself) is hit + by an attack to which it is resistant (default on). Persistent. - Some platforms allow you to define colors used in menu lines - when the line matches a user-defined pattern. At this time the - tty, curses, win32tty and win32gui interfaces support this. + spot_monsters + Show a message when hero notices a monster (default is off). - In general, the configuration file entries to describe the - menu color mappings look like this: + standout + Boldface monsters and "--More--" (default off). Persistent. - MENUCOLOR="pattern"=color&attribute + statushilites + Controls how many turns status hilite behaviors highlight the field. + If negated or set to zero, disables status hiliting. See "Configur- + ing Status Hilites" for further information. - pattern - the pattern to match; - color - the color to use for lines matching the pat- - tern; - attribute - the attribute to use for lines matching the - pattern. The attribute is optional, and if - left out, you must also leave out the preced- - ing ampersand. If no attribute is defined, - no attribute is used. + status_updates + Allow updates to the status lines at the bottom of the screen + (default true). - The pattern should be a regular expression. + suppress_alert + This option may be set to a NetHack version level to suppress alert + notification messages about feature changes for that and prior ver- + sions (for example "suppress_alert:3.3.1"). - Allowed colors are black, red, green, brown, blue, magenta, - cyan, gray, orange, light-green, yellow, light-blue, light-ma- - genta, light-cyan, and white. And no-color, the default fore- - ground color, which isn't necessarily the same as any of the - other colors. + symset + This option may be used to select one of the named symbol sets found + within "symbols" to alter the symbols displayed on the screen. Use + "symset:default" to explicitly select the default symbols. - Allowed attributes are none, bold, dim, underline, blink, and - inverse. "Normal" is a synonym for "none". Note that the - platform used may interpret the attributes any way it wants. + terrainstatus + Display an extra status condition describing the spot beneath the + hero's feet (default off, not supported by all interfaces). - Here's an example of menu colors using NetHack's internal pat- - tern matching facility: + time + Show the elapsed game time in turns on bottom line (default off). + Persistent. - MENUCOLOR="* blessed *"=green - MENUCOLOR="* cursed *"=red - MENUCOLOR="* cursed *(being worn)"=red&underline + timed_delay + When pausing momentarily for display effect, such as with explosions + and moving objects, use a timer rather than sending extra characters + to the screen. (Applies to "tty" and "curses" interfaces only; + "X11" interface always uses a timer-based delay. The default is on + if configured into the program.) Persistent. - specifies that any menu line with " blessed " contained in it - will be shown in green color, lines with " cursed " will be - shown in red, and lines with " cursed " followed by "(being - worn)" on the same line will be shown in red color and under- - lined. You can have multiple MENUCOLOR entries in your config- - uration file, and the last MENUCOLOR line that matches a menu - line will be used for the line. + tips + Show some helpful tips during gameplay (default on). Persistent. - Note that if you intend to have one or more color specifica- - tions match " uncursed ", you will probably want to turn the im- - plicit_uncursed option off so that all items known to be uncursed - are actually displayed with the "uncursed" description. + tombstone + Draw a tombstone graphic upon your death (default on). Persistent. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 83 - NetHack Guidebook 76 + toptenwin + Put the ending display in a NetHack window instead of on stdout + (default off). Setting this option makes the score list visible + when a windowing version of NetHack is started without a parent win- + dow, but it no longer leaves the score list around after game end on + a terminal or emulating window. + travel + Allow the travel command via mouse click (default on). Turning this + option off will prevent the game from attempting unintended moves if + you make inadvertent mouse clicks on the map window. Does not + affect traveling via the `_' ("#travel") command. Persistent. - 9.12. Configuring User Sounds + tutorial + Play a tutorial level at the start of the game. Setting this option + on or off in the config file will skip the query. - Some platforms allow you to define sound files to be played - when a message that matches a user-defined pattern is delivered - to the message window. At this time the Qt port and the win32tty - and win32gui ports support the use of user sounds. + verbose + Provide more commentary during the game (default on). Persistent. - The following configuration file entries are relevant to - mapping user sounds to messages: + versinfo + Controls what the showvers option displays on the status lines. - SOUNDDIR - The directory that houses the sound files to be played. + weaponstatus + Display an extra status condition which describes currently wielded + weapon (default off, not supported by all interfaces). - SOUND - An entry that maps a sound file to a user-specified message - pattern. Each SOUND entry is broken down into the following - parts: + Some possible displayed values are: + + bare-hnds - no weapon and no gloves; + empty-hnd - no weapon but gloves are worn; + dual-weps - wielding two weapons. + + whatis_coord + When using the `/' or `;' commands to look around on the map with + autodescribe on, display coordinates after the description. Also + works in other situations where you are asked to pick a location. + + The possible settings are: + + c - compass ("east" or "3s" or "2n,4w"); + f - full compass ("east" or "3south" or "2north,4west"); + m - map (map column x=0 is not used); + s - screen [row,column] (row is offset to match tty usage); + n - none (no coordinates shown) [default]. + + The whatis_coord option is also used with the "/m", "/M", "/o", and + "/O" sub-commands of `/', where the "none" setting is overridden + with "map". + + whatis_filter + When getting a location on the map, and using the keys to cycle + through next and previous targets, allows filtering the possible + targets. + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 84 + + + + n - no filtering [default] + v - in view only + a - in same area only + + The area-filter tries to be slightly predictive--if you're standing + on a doorway, it will consider the area on the side of the door you + were last moving towards. + + Filtering can also be changed when getting a location with the "get- + pos.filter" key. + + whatis_menu + When getting a location on the map, and using a key to cycle through + next and previous targets, use a menu instead to pick a target. + (default off) + + whatis_moveskip + When getting a location on the map, and using shifted movement keys + or meta-digit keys to fast-move, instead of moving 8 units at a + time, move by skipping the same glyphs. (default off) + + windowtype + When the program has been built to support multiple interfaces, + select which one to use, such as "tty" or "X11" (default depends on + build-time settings; use "#version" to check). Cannot be set with + the `O' command. + + When used, it should be the first option set since its value might + enable or disable the availability of various other options. For + multiple lines in a configuration file, that would be the first non- + comment line. For a comma-separated list in NETHACKOPTIONS or an + OPTIONS line in a configuration file, that would be the rightmost + option in the list. + + wizweight + Augment object descriptions with their objects' weight (default + off). Debug mode only. + + zerocomp + When writing out a save file, perform zero-comp compression of the + contents. Not all ports support zero-comp compression. It has no + effect on reading an existing save file. + + 9.5. Window Port Customization options + + Here are explanations of the various options that are used to + customize and change the characteristics of the windowtype that you + have chosen. Character strings that are too long may be truncated. + Not all window ports will adjust for all settings listed here. You + can safely add any of these options to your configuration file, and if + the window port is capable of adjusting to suit your preferences, it + will attempt to do so. If it can't it will silently ignore it. You + can find out if an option is supported by the window port that you are + currently using by checking to see if it shows up in the Options list. + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 85 + + + + Some options are dynamic and can be specified during the game with the + `O' command. + + align_message + Where to align or place the message window (top, bottom, left, or + right) + + align_status + Where to align or place the status window (top, bottom, left, or + right). + + ascii_map + If NetHack can, it should display the map using simple characters + (letters and punctuation) rather than tiles graphics. In some + cases, characters can be augmented with line-drawing symbols; use + the symset option to select a symbol set such as DECgraphics or + IBMgraphics if your display supports them. Setting ascii_map to + True forces tiled_map to be False. + + color + If NetHack can, it should display color if it can for different mon- + sters, objects, and dungeon features (default on). + + eight_bit_tty + If NetHack can, it should pass eight-bit character values (for exam- + ple, specified with the traps option) straight through to your ter- + minal (default off). + + font_map + if NetHack can, it should use a font by the chosen name for the map + window. + + font_menu + If NetHack can, it should use a font by the chosen name for menu + windows. + + font_message + If NetHack can, it should use a font by the chosen name for the mes- + sage window. + + font_status + If NetHack can, it should use a font by the chosen name for the sta- + tus window. + + font_text + If NetHack can, it should use a font by the chosen name for text + windows. + + font_size_map + If NetHack can, it should use this size font for the map window. + + font_size_menu + If NetHack can, it should use this size font for menu windows. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 86 + + + + font_size_message + If NetHack can, it should use this size font for the message window. + + font_size_status + If NetHack can, it should use this size font for the status window. + + font_size_text + If NetHack can, it should use this size font for text windows. + + fullscreen + If NetHack can, it should try to display on the entire screen rather + than in a window. + + guicolor + Use color text and/or highlighting attributes when displaying some + non-map data (such as menu selector letters). Curses interface + only; default is on. + + large_font + If NetHack can, it should use a large font. + + map_mode + If NetHack can, it should display the map in the manner specified. + + player_selection + If NetHack can, it should pop up dialog boxes, or use prompts for + character selection. + + popup_dialog + If NetHack can, it should pop up dialog boxes for input. + + preload_tiles + If NetHack can, it should preload tiles into memory. For example, + in the protected mode MS-DOS version, control whether tiles get pre- + loaded into RAM at the start of the game. Doing so enhances perfor- + mance of the tile graphics, but uses more memory. (default on). + Cannot be set with the `O' command. + + scroll_amount + If NetHack can, it should scroll the display by this number of cells + when the hero reaches the scroll_margin. + + scroll_margin + If NetHack can, it should scroll the display when the hero or cursor + is this number of cells away from the edge of the window. + + selectsaved + If NetHack can, it should display a menu of existing saved games for + the player to choose from at game startup, if it can. Not all ports + support this option. + + softkeyboard + Display an onscreen keyboard. Handhelds are most likely to support + this option. + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 87 + + + + splash_screen + If NetHack can, it should display an opening splash screen when it + starts up (default yes). + + statuslines + Number of lines for traditional below-the-map status display. + Acceptable values are 2 and 3 (default is 2). + + When set to 3, the tty interface moves some fields around and mainly + shows status conditions on their own line. A display capable of + showing at least 25 lines is recommended. The value can be toggled + back and forth during the game with the `O' command. + + The curses interface does likewise if the align_status option is set + to top or bottom but ignores statuslines when set to left or right. + + The Qt interface already displays more than 3 lines for status so + uses the statuslines value differently. A value of 3 renders status + in the Qt interface's original format, with the status window spread + out vertically. A value of 2 makes status be slightly condensed, + moving some fields to different lines to eliminate one whole line, + reducing the height needed. (If NetHack has been built using a ver- + sion of Qt older than qt-5.9, statuslines can only be set in the + run-time configuration file or via NETHACKOPTIONS, not during play + with the `O' command.) + + term_cols and + + term_rows + Curses interface only. Number of columns and rows to use for the + display. Curses will attempt to resize to the values specified but + will settle for smaller sizes if they are too big. Default is the + current window size. + + tile_file + Specify the name of an alternative tile file to override the + default. + + Note: the X11 interface uses X resources rather than NetHack's + options to select an alternate tile file. See NetHack.ad, the sam- + ple X "application defaults" file. + + tile_height + Specify the preferred height of each tile in a tile capable port. + + tile_width + Specify the preferred width of each tile in a tile capable port + + tiled_map + If NetHack can, it should display the map using tiles graphics + rather than simple characters (letters and punctuation, possibly + augmented by line-drawing symbols). Setting tiled_map to True + forces ascii_map to be False. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 88 + + + + use_darkgray + Use bold black instead of blue for black glyphs (TTY only). + + use_inverse + If NetHack can, it should display inverse when the game specifies + it. + + vary_msgcount + If NetHack can, it should display this number of messages at a time + in the message window. + + windowborders + Whether to draw boxes around the map, status area, message area, and + persistent inventory window if enabled. Curses interface only. + Acceptable values are + + 0 - off, never show borders + 1 - on, always show borders + 2 - auto, on if display is at least (24+2)x(80+2) [default] + 3 - on, except forced off for perm_invent + 4 - auto, except forced off for perm_invent + + (The 26x82 size threshold for `2' refers to number of rows and col- + umns of the display. A width of at least 110 columns (80+2+26+2) is + needed to show borders if align_status is set to left or right.) + + The persistent inventory window, when enabled, can grow until it is + too big to fit on most displays, resulting in truncation of its con- + tents. If borders are forced on (1) or the display is big enough to + show them (2), setting the value to 3 or 4 instead will keep borders + for the map, message, and status windows but have room for two addi- + tional lines of inventory plus widen each inventory line by two col- + umns. + + windowcolors + If NetHack can, it should display all windows of a particular style + with the specified foreground and background colors. Windows GUI + and curses windowport only. The format is + + OPTION=windowcolors:style foreground/background + + where style is one of "menu", "message", "status", or "text", and + foreground and background are colors, either numeric (hash sign fol- + lowed by three pairs of hexadecimal digits, #rrggbb), one of the + named colors (black, red, green, brown, blue, magenta, cyan, orange, + bright-green, yellow, bright-blue, bright-magenta, bright-cyan, + white, gray, purple, silver, maroon, fuchsia, lime, olive, navy, + teal, aqua), or (for Windows only) one of Windows UI colors (true- + black, activeborder, activecaption, appworkspace, background, btn- + face, btnshadow, btntext, captiontext, graytext, greytext, high- + light, highlighttext, inactiveborder, inactivecaption, menu, menu- + text, scrollbar, window, windowframe, windowtext). + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 89 + + + + wraptext + If NetHack can, it should wrap long lines of text if they don't fit + in the visible area of the window. + + 9.6. Crash Report Options + + Please note that NetHack does not send any information off your + computer unless you manually click submit on a form. + + OPTION=crash_email:email_address + + OPTION=crash_name:your_name + These options are used only to save you some typing on the + crash report and #bugreport forms. + + OPTION=crash_urlmax:bytes + This option is used to limit the length of the URLs generated + and is only needed if your browser cannot handle arbitrarily + long URLs. + + 9.7. Platform-specific Customization options + + Here are explanations of options that are used by specific plat- + forms or ports to customize and change the port behavior. + + altkeyhandling + Select an alternate way to handle keystrokes (Win32 tty NetHack + only). The name of the handling type is one of "default", "ray", + "340". + + altmeta + On systems where this option is available, it can be set to tell + NetHack to convert a two character sequence beginning with ESC into + a meta-shifted version of the second character (default off). + + This conversion is only done for commands, not for other input + prompts. Note that typing one or more digits as a count prefix + prior to a command--preceded by n if the number_pad option is set-- + is also subject to this conversion, so attempting to abort the count + by typing ESC will leave NetHack waiting for another character to + complete the two character sequence. Type a second ESC to finish + cancelling such a count. At other prompts a single ESC suffices. + + BIOS + Use BIOS calls to update the screen display quickly and to read the + keyboard (allowing the use of arrow keys to move) on machines with + an IBM PC compatible BIOS ROM (default off, OS/2, PC, and ST NetHack + only). + + rawio + Force raw (non-cbreak) mode for faster output and more bulletproof + input (MS-DOS sometimes treats `^P' as a printer toggle without it) + (default off, OS/2, PC, and ST NetHack only). Note: DEC Rainbows + hang if this is turned on. Cannot be set with the `O' command. + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 90 + + + + subkeyvalue + (Win32 tty NetHack only). May be used to alter the value of key- + strokes that the operating system returns to NetHack to help compen- + sate for international keyboard issues. OPTIONS=subkeyvalue:171/92 + will return 92 to NetHack, if 171 was originally going to be + returned. You can use multiple subkeyvalue assignments in the con- + figuration file if needed. Cannot be set with the `O' command. + + video + Set the video mode used (PC NetHack only). Values are "autodetect", + "default", "vga", or "vesa". Setting "vesa" will cause the game to + display tiles, using the full capability of the VGA hardware. Set- + ting "vga" will cause the game to display tiles, fixed at 640x480 in + 16 colors, a mode that is compatible with all VGA hardware. Third + party tilesets will probably not work. Setting "autodetect" + attempts "vesa", then "vga", and finally sets "default" if neither + of those modes works. Cannot be set with the `O' command. + + video_height + Set the VGA mode resolution height (MS-DOS only, with video:vesa) + + video_width + Set the VGA mode resolution width (MS-DOS only, with video:vesa) + + videocolors + Set the color palette for PC systems using NO_TERMS (default + 4-2-6-1-5-3-15-12-10-14-9-13-11, (PC NetHack only). The order of + colors is red, green, brown, blue, magenta, cyan, bright.white, + bright.red, bright.green, yellow, bright.blue, bright.magenta, and + bright.cyan. Cannot be set with the `O' command. + + videoshades + Set the intensity level of the three gray scales available (default + dark normal light, PC NetHack only). If the game display is diffi- + cult to read, try adjusting these scales; if this does not correct + the problem, try !color. Cannot be set with the `O' command. + + 9.8. Regular Expressions + + Regular expressions are normally POSIX extended regular expres- + sions. It is possible to compile NetHack without regular expression + support on a platform where there is no regular expression library. + While this is not true of any modern platform, if your NetHack was + built this way, patterns are instead glob patterns; regardless, this + document refers to both as `regular expressions.' This applies to + Autopickup exceptions, Message types, Menu colors, and User sounds. + + 9.9. Configuring Autopickup Exceptions + + You can further refine the behavior of the autopickup option + beyond what is available through the pickup_types option. + + By placing autopickup_exception lines in your configuration file, + you can define patterns to be checked when the game is about to + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 91 + + + + autopickup something. + + autopickup_exception + Sets an exception to the pickup_types option. The autopickup_excep- + tion option should be followed by a regular expression to be used as + a pattern to match against the singular form of the description of + an object at your location. + + In addition, some characters are treated specially if they occur as + the first character in the pattern, specifically: + + < - always pickup an object that matches rest of pattern; + > - never pickup an object that matches rest of pattern. + + The autopickup_exception rules are processed in the order in which + they appear in your configuration file, thus allowing a later rule + to override an earlier rule. + + Exceptions can be set with the `O' command, but because they are not + included in your configuration file, they won't be in effect if you + save and then restore your game. autopickup_exception rules and not + saved with the game. + + Here are some examples: + + autopickup_exception="<*arrow" + autopickup_exception=">*corpse" + autopickup_exception=">* cursed*" + + The first example above will result in autopickup of any type of + arrow. The second example results in the exclusion of any corpse from + autopickup. The last example results in the exclusion of items known + to be cursed from autopickup. + + 9.10. Changing Key Bindings + + It is possible to change the default key bindings of some special + commands, menu accelerator keys, and extended commands, by using BIND + stanzas in the configuration file. Format is key, followed by the + command to bind to, separated by a colon. The key can be a single + character ("x"), a control key ("^X", "C-x"), a meta key ("M-x"), a + mouse button, or a three-digit decimal ASCII code. + + For example: + + BIND=^X:getpos.autodescribe + BIND=\:menu_first_page + BIND=v:loot + + Extended command keys + You can bind multiple keys to the same extended command. Unbind a + key by using "nothing" as the extended command to bind to. You can + also bind the "", "", and "" keys. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 92 + + + + Menu accelerator keys + The menu control or accelerator keys can also be rebound via OPTIONS + lines in the configuration file. You cannot bind object symbols or + selection letters into menu accelerators. Some interfaces only sup- + port some of the menu accelerators. + + Mouse buttons + You can bind "mouse1" or "mouse2" to "nothing", "therecmdmenu", + "clicklook", or "mouseaction". + + Special command keys + Below are the special commands you can rebind. Some of them can be + bound to same keys with no problems, others are in the same "con- + text", and if bound to same keys, only one of those commands will be + available. Special command can only be bound to a single key. + + count + Prefix key to start a count, to repeat a command this many times. + With number_pad only. Default is `n'. + + getdir.help + When asked for a direction, the key to show the help. Default is + `?'. + + getdir.mouse + When asked for a direction, the key to initiate a simulated mouse + click. You will be asked to pick a location. Use movement key- + strokes to move the cursor around the map, then type the get- + pos.pick.once key (default `,') or the getpos.pick key (default `.') + to finish as if performing a left or right click. Only useful when + using the #therecmdmenu command. Default is `_'. + + getdir.self + When asked for a direction, the key to target yourself. Default is + `.'. + + getdir.self2 + When asked for a direction, an alternate key to target yourself. + Default is `s'. + + getpos.autodescribe + When asked for a location, the key to toggle autodescribe. Default + is `#'. + + getpos.all.next + When asked for a location, the key to go to next closest interesting + thing. Default is `a'. + + getpos.all.prev + When asked for a location, the key to go to previous closest inter- + esting thing. Default is `A'. + + getpos.door.next + When asked for a location, the key to go to next closest door or + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 93 + + + + doorway. Default is `d'. + + getpos.door.prev + When asked for a location, the key to go to previous closest door or + doorway. Default is `D'. + + getpos.help + When asked for a location, the key to show help. Default is `?'. + + getpos.mon.next + When asked for a location, the key to go to next closest monster. + Default is `m'. + + getpos.mon.prev + When asked for a location, the key to go to previous closest mon- + ster. Default is `M'. + + getpos.obj.next + When asked for a location, the key to go to next closest object. + Default is `o'. + + getpos.obj.prev + When asked for a location, the key to go to previous closest object. + Default is `O'. + + getpos.menu + When asked for a location, and using one of the next or previous + keys to cycle through targets, toggle showing a menu instead. + Default is `!'. + + getpos.moveskip + When asked for a location, and using the shifted movement keys or + meta-digit keys to fast-move around, move by skipping the same + glyphs instead of by 8 units. Default is `*'. + + getpos.filter + When asked for a location, change the filtering mode when using one + of the next or previous keys to cycle through targets. Toggles + between no filtering, in view only, and in the same area only. + Default is `"'. + + getpos.pick + When asked for a location, the key to choose the location, and pos- + sibly ask for more info. When simulating a mouse click after being + asked for a direction (see getdir.mouse above), the key to use to + respond as right click. Default is `.'. + + getpos.pick.once + When asked for a location, the key to choose the location, and skip + asking for more info. When simulating a mouse click after being + asked for a direction, the key to respond as left click. Default is + `,'. + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 94 + + + + getpos.pick.quick + When asked for a location, the key to choose the location, skip ask- + ing for more info, and exit the location asking loop. Default is + `;'. + + getpos.pick.verbose + When asked for a location, the key to choose the location, and show + more info without asking. Default is `:'. + + getpos.self + When asked for a location, the key to go to your location. Default + is `@'. + + getpos.unexplored.next + When asked for a location, the key to go to next closest unexplored + location. Default is `x'. + + getpos.unexplored.prev + When asked for a location, the key to go to previous closest unex- + plored location. Default is `X'. + + getpos.valid + When asked for a location, the key to go to show valid target loca- + tions. Default is `$'. + + getpos.valid.next + When asked for a location, the key to go to next closest valid loca- + tion. Default is `z'. + + getpos.valid.prev + When asked for a location, the key to go to previous closest valid + location. Default is `Z'. + + 9.11. Configuring Message Types + + You can change the way the messages are shown in the message + area, when the message matches a user-defined pattern. + + In general, the configuration file entries to describe the mes- + sage types look like this: MSGTYPE=type "pattern" + + type - how the message should be shown; + pattern - the pattern to match. + + The pattern should be a regular expression. + + Allowed types are: + + show - show message normally; + hide - never show the message; + stop - wait for user with more-prompt; + norep - show the message once, but not again if no other message is + shown in between. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 95 + + + + Here's an example of message types using NetHack's internal pattern + matching facility: + + MSGTYPE=stop "You feel hungry." + MSGTYPE=hide "You displaced *." + + specifies that whenever a message "You feel hungry" is shown, the + user is prompted with more-prompt, and a message matching "You dis- + placed ." is not shown at all. + + The order of the defined MSGTYPE lines is important; the last match- + ing rule is used. Put the general case first, exceptions below them. + + 9.12. Configuring Menu Colors + + Some platforms allow you to define colors used in menu lines when + the line matches a user-defined pattern. At this time the tty, + curses, win32tty and win32gui interfaces support this. + + In general, the configuration file entries to describe the menu + color mappings look like this: + + MENUCOLOR="pattern"=color&attribute + + pattern - the pattern to match; + color - the color to use for lines matching the pattern; + attribute - the attribute to use for lines matching the pat- + tern. The attribute is optional, and if left out, + you must also leave out the preceding ampersand. + If no attribute is defined, no attribute is used. + + The pattern should be a regular expression. + + Allowed colors are black, red, green, brown, blue, magenta, cyan, + gray, orange, light-green, yellow, light-blue, light-magenta, light- + cyan, and white. And no-color, the default foreground color, which + isn't necessarily the same as any of the other colors. + + Allowed attributes are none, bold, dim, italic, underline, blink, + and inverse. "Normal" is a synonym for "none". Note that the plat- + form used may interpret the attributes any way it wants. + + Here's an example of menu colors using NetHack's internal pattern + matching facility: + + MENUCOLOR="* blessed *"=green + MENUCOLOR="* cursed *"=red + MENUCOLOR="* cursed *(being worn)"=red&underline + + specifies that any menu line with " blessed " contained in it will + be shown in green color, lines with " cursed " will be shown in red, + and lines with " cursed " followed by "(being worn)" on the same + line will be shown in red color and underlined. You can have multi- + ple MENUCOLOR entries in your configuration file, and the last MENU- + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 96 + + + + COLOR line that matches a menu line will be used for the line. + + Note that if you intend to have one or more color specifications + match " uncursed ", you will probably want to turn the + implicit_uncursed option off so that all items known to be uncursed + are actually displayed with the "uncursed" description. + + 9.13. Configuring User Sounds + + Some platforms allow you to define sound files to be played when + a message that matches a user-defined pattern is delivered to the mes- + sage window. At this time the Qt port and the win32tty and win32gui + ports support the use of user sounds. + + The following configuration file entries are relevant to mapping + user sounds to messages: + + SOUNDDIR + The directory that houses the sound files to be played. + + SOUND + An entry that maps a sound file to a user-specified message pattern. + Each SOUND entry is broken down into the following parts: + + MESG - message window mapping (the only one supported in + 5.0.0); + msgtype - optional; message type to use, see "Configuring Mes- + sage Types" + pattern - the pattern to match; + sound file - the sound file to play; + volume - the volume to be set while playing the sound file; + sound index - optional; the index corresponding to a sound file. + + The pattern should be a regular expression. + + For example: + + SOUNDDIR=C:\nethack\sounds + SOUND=MESG "This door is locked" "lock.wav" 100 + SOUND=MESG hide "^You miss the " "swing.wav" 75 + + + + 9.14. Configuring Status Hilites + + Your copy of NetHack may have been compiled with support for + "Status Hilites". If so, you can customize your game display by set- + ting thresholds to change the color or appearance of fields in the + status display. + + The format for defining status colors is: + + OPTION=hilite_status:field-name/behavior/color&attributes + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 97 + + + + For example, the following line in your configuration file will + cause the hitpoints field to display in the color red if your hit- + points drop to or below a threshold of 30%: + + OPTION=hilite_status:hitpoints/<=30%/red/normal + + (That example is actually specifying red&normal for <=30% and no- + color&normal for >30%.) + + For another example, the following line in your configuration + file will cause wisdom to be displayed red if it drops and green if it + rises: + + OPTION=hilite_status:wisdom/down/red/up/green + + Allowed colors are black, red, green, brown, blue, magenta, cyan, + gray, orange, light-green, yellow, light-blue, light-magenta, light- + cyan, and white. And "no-color", the default foreground color on the + display, which is not necessarily the same as black or white or any of + the other colors. + + Allowed attributes are none, bold, dim, underline, italic, blink, + and inverse. "Normal" is a synonym for "none"; they should not be + used in combination with any of the other attributes. + + To specify both a color and an attribute, use `&' to combine + them. To specify multiple attributes, use `+' to combine those. For + example: "magenta&inverse+dim". + + Note that the display may substitute or ignore particular + attributes depending upon its capabilities, and in general may inter- + pret the attributes any way it wants. For example, on some display + systems a request for bold might yield blink or vice versa. On oth- + ers, issuing an attribute request while another is already set up will + replace the earlier attribute rather than combine with it. Since + NetHack issues attribute requests sequentially (at least with the tty + interface) rather than all at once, the only way a situation like that + can be controlled is to specify just one attribute. + + You can adjust the appearance of the following status fields: + title dungeon-level experience-level + strength gold experience + dexterity hitpoints HD + constitution hitpoints-max time + intelligence power hunger + wisdom power-max carrying-capacity + charisma armor-class condition + alignment score + + The pseudo-field "characteristics" can be used to set all six of + Str, Dex, Con, Int, Wis, and Cha at once. "HD" is "hit dice", an + approximation of experience level displayed when polymorphed. + "experience", "time", and "score" are conditionally displayed + depending upon your other option settings. + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 98 + + + + Instead of a behavior, "condition" takes the following condition + flags: stone, slime, strngl, foodpois, termill, blind, deaf, stun, + conf, hallu, lev, fly, and ride. You can use "major_troubles" as an + alias for stone through termill, "minor_troubles" for blind through + hallu, "movement" for lev, fly, and ride, and "all" for every condi- + tion. + + Allowed behaviors are "always", "up", "down", "changed", a percent- + age or absolute number threshold, or text to match against. For the + hitpoints field, the additional behavior "criticalhp" is available. + It overrides other behavior rules if hit points are at or below the + major problem threshold (which varies depending upon maximum hit + points and experience level). + + * "always" will set the default attributes for that field. + + * "up", "down" set the field attributes for when the field value + changes upwards or downwards. This attribute times out after + statushilites turns. + + * "changed" sets the field attribute for when the field value + changes. This attribute times out after statushilites turns. + (If a field has both a "changed" rule and an "up" or "down" + rule which matches a change in the field's value, the "up" or + "down" one takes precedence.) + + * percentage sets the field attribute when the field value + matches the percentage. It is specified as a number between 0 + and 100, followed by `%' (percent sign). If the percentage is + prefixed with `<=' or `>=', it also matches when value is below + or above the percentage. Use prefix `<' or `>' to match when + strictly below or above. (The numeric limit is relaxed + slightly for those: >-1% and <101% are allowed.) Only four + fields support percentage rules. Percentages for "hitpoints" + and "power" are straightforward; they're based on the corre- + sponding maximum field. Percentage highlight rules are also + allowed for "experience level" and "experience points" (valid + when the showexp option is enabled). For those, the percentage + is based on the progress from the start of the current experi- + ence level to the start of the next level. So if level 2 + starts at 20 points and level 3 starts at 40 points, having 30 + points is 50% and 35 points is 75%. 100% is unattainable for + experience because you'll gain a level and the calculations + will be reset for that new level, but a rule for =100% is + allowed and matches the special case of being exactly 1 experi- + ence point short of the next level. + + * absolute value sets the attribute when the field value matches + that number. The number must be 0 or higher, except for + "armor-class' which allows negative values, and may optionally + be preceded by `='. If the number is preceded by `<=' or `>=' + instead, it also matches when value is below or above. If the + prefix is `<' or `>', only match when strictly above or below. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 99 + + + + * criticalhp only applies to the hitpoints field and only when + current hit points are below a threshold (which varies by maxi- + mum hit points and experience level). When the threshold is + met, a criticalhp rule takes precedence over all other hit- + points rules. + + * text match sets the attribute when the field value matches the + text. Text matches can only be used for "alignment", "carry- + ing-capacity", "hunger", "dungeon-level", and "title". For + title, only the role's rank title is tested; the character's + name is ignored. + + The in-game options menu can help you determine the correct syn- + tax for a configuration file. + + The whole feature can be disabled by setting option statushilites + to 0. + + Example hilites: + + OPTION=hilite_status: gold/up/yellow/down/brown + OPTION=hilite_status: characteristics/up/green/down/red + OPTION=hilite_status: hitpoints/100%/gray&normal + OPTION=hilite_status: hitpoints/<100%/green&normal + OPTION=hilite_status: hitpoints/<66%/yellow&normal + OPTION=hilite_status: hitpoints/<50%/orange&normal + OPTION=hilite_status: hitpoints/<33%/red&bold + OPTION=hilite_status: hitpoints/<15%/red&inverse + OPTION=hilite_status: condition/major/orange&inverse + OPTION=hilite_status: condition/lev+fly/red&inverse + + + + 9.15. Modifying NetHack Symbols + + NetHack can load entire symbol sets from the symbol file. + + The options that are used to select a particular symbol set from + the symbol file are: + + symset + Set the name of the symbol set that you want to load. + + roguesymset + Set the name of the symbol set that you want to load for display on + the rogue level. + + You can also override one or more symbols using the SYMBOLS and + ROGUESYMBOLS configuration file options. Symbols are specified as + name:value pairs. Note that NetHack escape-processes the value string + in conventional C fashion. This means that \ is a prefix to take the + following character literally. Thus \ needs to be represented as \\. + The special prefix form \m switches on the meta bit in the symbol + value, and the ^ prefix causes the following character to be treated + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 100 + + + + as a control character. + + NetHack Symbols + Symbol Name Description + ----------------------------------------------------------------- + S_air (air) + _ S_altar (altar) + " S_amulet (amulet) + A S_angel (angelic being) + a S_ant (ant or other insect) + ^ S_anti_magic_trap (anti-magic field) + [ S_armor (suit or piece of armor) + [ S_armour (suit or piece of armor) + ^ S_arrow_trap (arrow trap) + 0 S_ball (iron ball) + # S_bars (iron bars) + B S_bat (bat or bird) + ^ S_bear_trap (bear trap) + - S_blcorn (bottom left corner) + b S_blob (blob) + + S_book (spellbook) + ) S_boomleft (boomerang open left) + ( S_boomright (boomerang open right) + ` S_boulder (boulder) + - S_brcorn (bottom right corner) + > S_brdnladder (branch ladder down) + > S_brdnstair (branch staircase down) + < S_brupladder (branch ladder up) + < S_brupstair (branch staircase up) + C S_centaur (centaur) + _ S_chain (iron chain) + # S_cloud (cloud) + c S_cockatrice (cockatrice) + $ S_coin (pile of coins) + # S_corr (corridor) + - S_crwall (wall) + # S_darkroom (dark room) + ^ S_dart_trap (dart trap) + & S_demon (major demon) + * S_digbeam (dig beam) + > S_dnladder (ladder down) + > S_dnstair (staircase down) + d S_dog (dog or other canine) + D S_dragon (dragon) + ; S_eel (sea monster) + E S_elemental (elemental) + # S_engrcorr (engraving in a corridor) + ` S_engroom (engraving in a room) + / S_expl_tl (explosion top left) + - S_expl_tc (explosion top center) + \ S_expl_tr (explosion top right) + | S_expl_ml (explosion middle left) + S_expl_mc (explosion middle center) + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 101 + + + + | S_expl_mr (explosion middle right) + \ S_expl_bl (explosion bottom left) + - S_expl_bc (explosion bottom center) + / S_expl_br (explosion bottom right) + e S_eye (eye or sphere) + ^ S_falling_rock_trap (falling rock trap) + f S_feline (cat or other feline) + ^ S_fire_trap (fire trap) + ! S_flashbeam (flash beam) + % S_food (piece of food) + { S_fountain (fountain) + F S_fungus (fungus or mold) + * S_gem (gem or rock) + S_ghost (ghost) + H S_giant (giant humanoid) + G S_gnome (gnome) + ' S_golem (golem) + | S_grave (grave) + g S_gremlin (gremlin) + - S_hbeam (horizontal beam [zap animation]) + # S_hcdbridge (horizontal raised drawbridge) + + S_hcdoor (closed door in horizontal wall) + . S_hodbridge (horizontal lowered drawbridge) + | S_hodoor (open door in horizontal wall) + ^ S_hole (hole) + @ S_human (human or elf) + h S_humanoid (humanoid) + - S_hwall (horizontal wall) + . S_ice (ice) + i S_imp (imp or minor demon) + I S_invisible (invisible monster) + J S_jabberwock (jabberwock) + j S_jelly (jelly) + k S_kobold (kobold) + K S_kop (Keystone Kop) + ^ S_land_mine (land mine) + } S_lava (molten lava) + } S_lavawall (wall of lava) + l S_leprechaun (leprechaun) + ^ S_level_teleporter (level teleporter) + L S_lich (lich) + y S_light (light) + # S_litcorr (lit corridor) + : S_lizard (lizard) + \ S_lslant (diagonal beam [zap animation]) + ^ S_magic_portal (magic portal) + ^ S_magic_trap (magic trap) + m S_mimic (mimic) + ] S_mimic_def (mimic) + M S_mummy (mummy) + N S_naga (naga) + . S_ndoor (doorway without door) + n S_nymph (nymph) + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 102 + + + + O S_ogre (ogre) + o S_orc (orc) + p S_piercer (piercer) + ^ S_pit (pit) + # S_poisoncloud (poison cloud) + ^ S_polymorph_trap (polymorph trap) + } S_pool (water) + ! S_potion (potion) + P S_pudding (pudding or ooze) + q S_quadruped (quadruped) + Q S_quantmech (quantum mechanic) + = S_ring (ring) + ` S_rock (boulder or statue) + r S_rodent (rodent) + ^ S_rolling_boulder_trap (rolling boulder trap) + . S_room (floor of a room) + / S_rslant (diagonal beam [zap animation]) + ^ S_rust_trap (rust trap) + R S_rustmonst (rust monster or disenchanter) + ? S_scroll (scroll) + # S_sink (sink) + ^ S_sleeping_gas_trap (sleeping gas trap) + S S_snake (snake) + s S_spider (arachnid or centipede) + ^ S_spiked_pit (spiked pit) + ^ S_squeaky_board (squeaky board) + 0 S_ss1 (magic shield 1 of 4) + # S_ss2 (magic shield 2 of 4) + @ S_ss3 (magic shield 3 of 4) + * S_ss4 (magic shield 4 of 4) + ^ S_statue_trap (statue trap) + S_stone (solid rock) + ] S_strange_obj (strange object) + - S_sw_bc (swallow bottom center) + \ S_sw_bl (swallow bottom left) + / S_sw_br (swallow bottom right) + | S_sw_ml (swallow middle left) + | S_sw_mr (swallow middle right) + - S_sw_tc (swallow top center) + / S_sw_tl (swallow top left) + \ S_sw_tr (swallow top right) + - S_tdwall (wall) + ^ S_teleportation_trap (teleportation trap) + \ S_throne (opulent throne) + - S_tlcorn (top left corner) + | S_tlwall (wall) + ( S_tool (useful item (pick-axe, key, lamp...)) + ^ S_trap_door (trap door) + t S_trapper (trapper or lurker above) + - S_trcorn (top right corner) + # S_tree (tree) + T S_troll (troll) + | S_trwall (wall) + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 103 + + + + - S_tuwall (wall) + U S_umber (umber hulk) + S_unexplored (unexplored terrain) + u S_unicorn (unicorn or horse) + < S_upladder (ladder up) + < S_upstair (staircase up) + V S_vampire (vampire) + | S_vbeam (vertical beam [zap animation]) + # S_vcdbridge (vertical raised drawbridge) + + S_vcdoor (closed door in vertical wall) + . S_venom (splash of venom) + ^ S_vibrating_square (vibrating square) + . S_vodbridge (vertical lowered drawbridge) + - S_vodoor (open door in vertical wall) + v S_vortex (vortex) + | S_vwall (vertical wall) + / S_wand (wand) + } S_water (water) + ) S_weapon (weapon) + " S_web (web) + w S_worm (worm) + ~ S_worm_tail (long worm tail) + W S_wraith (wraith) + x S_xan (xan or other extraordinary insect) + X S_xorn (xorn) + Y S_yeti (apelike creature) + Z S_zombie (zombie) + z S_zruty (zruty) + S_pet_override (any pet if ACCESSIBILITY=1 is set) + S_hero_override (hero if ACCESSIBILITY=1 is set) + + Notes: + + * Several symbols in this table appear to be blank. They are the + space character, except for S_pet_override and S_hero_override which + don't have any default value and can only be used if enabled in the + "sysconf" file. + + * S_rock is misleadingly named; rocks and stones use S_gem. Statues + and boulders are the rock being referred to, but since version + 3.6.0, statues are displayed as the monster they depict. So S_rock + is only used for boulders and not used at all if overridden by the + more specific S_boulder. + + 9.16. Customizing Map Glyph Representations Using Unicode + + If your platform or terminal supports the display of UTF-8 char- + acter sequences, you can customize your game display by assigning Uni- + code codepoint values and red-green-blue colors to glyph representa- + tions. The customizations can be specified for use with a symset that + has a UTF8 handler within the symbols file such as the enhanced1 set, + or individually within your nethack.rc file. + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 104 + + + + The format for defining a glyph representation is: + + OPTIONS=glyph:glyphid/U+nnnn/R-G-B + + The window port that is active needs to provide support for dis- + playing UTF-8 character sequences and explicit red-green-blue colors + in order for the glyph representation to be visible. For example, the + following line in your configuration file will cause the glyph repre- + sentation for glyphid G_pool to use Unicode codepoint U+224B and the + color represented by R-G-B value 0-0-160: + + OPTIONS=glyph:G_pool/U+224B/0-0-160 + + The list of acceptable glyphid's can be produced by nethack --dumpg- + lyphids. Individual NetHack glyphs can be specified using the G_ pre- + fix, or you can use an S_ symbol for a glyphid and store the custom + representation for all NetHack glyphs that would map to that particu- + lar symbol. + + You will need to select a symset with a UTF8 handler to enable + the display of the customizations, such as the Enhanced symset. + + 9.17. Configuring NetHack for Play by the Blind + + NetHack can be set up to use only standard ASCII characters for + making maps of the dungeons. This makes even the MS-DOS versions of + NetHack (which use special line-drawing characters by default) com- + pletely accessible to the blind who use speech and/or Braille access + technologies. Players will require a good working knowledge of their + screen-reader's review features, and will have to know how to navigate + horizontally and vertically character by character. They will also + find the search capabilities of their screen-readers to be quite valu- + able. Be certain to examine this Guidebook before playing so you have + an idea what the screen layout is like. You'll also need to be able to + locate the PC cursor. It is always where your character is located. + Merely searching for an @-sign will not always find your character + since there are other humanoids represented by the same sign. Your + screen-reader should also have a function which gives you the row and + column of your review cursor and the PC cursor. These co-ordinates + are often useful in giving players a better sense of the overall loca- + tion of items on the screen. + + NetHack can also be compiled with support for sending the game + messages to an external program, such as a text-to-speech synthesizer. + If the "#version" extended command shows "external program as a mes- + sage handler", your NetHack has been compiled with the capability. + When compiling NetHack from source on Linux and other POSIX systems, + define MSGHANDLER to enable it. To use the capability, set the envi- + ronment variable NETHACK_MSGHANDLER to an executable, which will be + executed with the game message as the program's only parameter. + + The most crucial settings to make the game more accessible are: + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 105 + + + + symset:plain + Load a symbol set appropriate for use by blind players. + + menustyle:traditional + This will assist in the interface to speech synthesizers. + + nomenu_overlay + Show menus on a cleared screen and aligned to the left edge. + + number_pad + A lot of speech access programs use the number-pad to review the + screen. If this is the case, disable the number_pad option and use + the traditional Rogue-like commands. + + paranoid_confirmation:swim + Prevent walking into water or lava. + + accessiblemsg + Adds direction or location information to messages. + + spot_monsters + Shows a message when hero notices a monster; combine with accessi- + blemsg. + + mon_movement + Shows a message when hero notices a monster movement; combine with + spot_monsters and accessiblemsg. + + autodescribe + Automatically describe the terrain under the cursor when targeting. + + mention_map + Give feedback messages when interesting map locations change. + + mention_walls + Give feedback messages when walking towards a wall or when travel + command was interrupted. + + whatis_coord:compass + When targeting with cursor, describe the cursor position with coor- + dinates relative to your character. + + whatis_filter:area + When targeting with cursor, filter possible locations so only those + in the same area (eg. same room, or same corridor) are considered. + + whatis_moveskip + When targeting with cursor and using fast-move, skip the same glyphs + instead of moving 8 units at a time. + + nostatus_updates + Prevent updates to the status lines at the bottom of the screen, if + your screen-reader reads those lines. The same information can be + seen via the "#attributes" command. + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 106 + + + + showdamage + Give a message of damage taken and how many hit points are left. + + 9.18. Global Configuration for System Administrators + + If NetHack is compiled with the SYSCF option, a system adminis- + trator should set up a global configuration; this is a file in the + same format as the traditional per-user configuration file (see + above). This file should be named sysconf and placed in the same + directory as the other NetHack support files. The options recognized + in this file are listed below. Any option not set uses a compiled-in + default (which may not be appropriate for your system). + + WIZARDS = A space-separated list of user names who are allowed to + play in debug mode (commonly referred to as wizard mode). A value + of a single asterisk (*) allows anyone to start a game in debug + mode. + + SHELLERS = A list of users who are allowed to use the shell escape + command (!). The syntax is the same as WIZARDS. + + EXPLORERS = A list of users who are allowed to use the explore mode. + The syntax is the same as WIZARDS. + + MSGHANDLER = A path and filename of executable. Whenever a message- + window message is shown, NetHack runs this program. The program + will get the message as the only parameter. + + MAXPLAYERS = Limit the maximum number of games that can be running + at the same time. + + SUPPORT = A string explaining how to get local support (no default + value). + + RECOVER = A string explaining how to recover a game on this system + (no default value). + + SEDUCE = 0 or 1 to disable or enable, respectively, the SEDUCE + option. When disabled, incubi and succubi behave like nymphs. + + CHECK_PLNAME = Setting this to 1 will make the EXPLORERS, WIZARDS, + and SHELLERS check for the player name instead of the user's login + name. + + CHECK_SAVE_UID = 0 or 1 to disable or enable, respectively, the UID + (used identification number) checking for save files (to verify that + the user who is restoring is the same one who saved). + + The following four options affect the score file: + + PERSMAX = Maximum number of entries for one person. + + ENTRYMAX = Maximum number of entries in the score file. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 107 + + + + POINTSMIN = Minimum number of points to get an entry in the score + file. + + PERS_IS_UID = 0 or 1 to use user names or numeric userids, respec- + tively, to identify unique people for the score file. + + HIDEUSAGE = 0 or 1 to control whether the help menu entry for com- + mand line usage is shown or suppressed. + + MAX_STATUENAME_RANK = Maximum number of score file entries to use + for random statue names (default is 10). + + ACCESSIBILITY = 0 or 1 to disable or enable, respectively, the abil- + ity for players to set S_pet_override and S_hero_override symbols in + their configuration file. + + PORTABLE_DEVICE_PATHS = 0 or 1 Windows OS only, the game will look + for all of its external files, and write to all of its output files + in one place rather than at the standard locations. + + DUMPLOGFILE = A filename where the end-of-game dumplog is saved. + Not defining this will prevent dumplog from being created. Only + available if your game is compiled with DUMPLOG. Allows the follow- + ing placeholders: + + %% - literal `%' + %v - version (eg. "5.0.0-0") + %u - game UID + %t - game start time, UNIX timestamp format + %T - current time, UNIX timestamp format + %d - game start time, YYYYMMDDhhmmss format + %D - current time, YYYYMMDDhhmmss format + %n - player name + %N - first character of player name + + LIVELOG = A bit-mask of types of events that should be written to + the livelog file if one is present. The sample sysconf file accom- + panying the program contains a comment which lists the meaning of + the various bits used. Intended for server systems supporting + simultaneous play by multiple players (to be clear, each one running + a separate single player game), for displaying their game progress + to observers. Only relevant if the program was built with LIVELOG + enabled. When available, it should be left commented out on single + player installations because over time the file could grow to be + extremely large unless it is actively maintained. + + CRASHREPORTURL = If set to + https://www.nethack.org/links/cr-37BETA.html and support is compiled + in, brings up a browser window pre-populated with the information + needed to report a problem if the game panics or ends up in an + internally inconsistent state, or if the #bugreport command is + invoked. + + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 108 + + + + 10. Scoring + + NetHack maintains a list of the top scores or scorers on your + machine, depending on how it is set up. In the latter case, each + account on the machine can post only one non-winning score on this + list. If you score higher than someone else on this list, or better + your previous score, you will be inserted in the proper place under + your current name. How many scores are kept can also be set up when + NetHack is compiled. + + Your score is chiefly based upon how much experience you gained, + how much loot you accumulated, how deep you explored, and how the game + ended. If you quit the game, you escape with all of your gold intact. + If, however, you get killed in the Mazes of Menace, the guild will + only hear about 90% of your gold when your corpse is discovered + (adventurers have been known to collect finder's fees). So, consider + whether you want to take one last hit at that monster and possibly + live, or quit and stop with whatever you have. If you quit, you keep + all your gold, but if you swing and live, you might find more. + + If you just want to see what the current top players/games list + is, you can type nethack -s all on most versions. + + 11. Explore mode + + NetHack is an intricate and difficult game. Novices might falter + in fear, aware of their ignorance of the means to survive. Well, fear + not. Your dungeon comes equipped with an "explore" or "discovery" + mode that enables you to keep old save files and cheat death, at the + paltry cost of not getting on the high score list. + + There are two ways of enabling explore mode. One is to start the + game with the -X command-line switch or with the playmode:explore + option. The other is to issue the "#exploremode" extended command + while already playing the game. Starting a new game in explore mode + provides your character with a wand of wishing in initial inventory; + switching during play does not. The other benefits of explore mode + are left for the trepid reader to discover. + + 11.1. Debug mode + + Debug mode, also known as wizard mode, is undocumented aside from + this brief description and the various "debug mode only" commands + listed among the command descriptions. It is intended for tracking + down problems within the program rather than to provide god-like pow- + ers to your character, and players who attempt debugging are expected + to figure out how to use it themselves. It is initiated by starting + the game with the -D command-line switch or with the playmode:debug + option. + + For some systems, the player must be logged in under a particular + user name to be allowed to use debug mode; for others, the hero must + be given a particular character name (but may be any role; there's no + connection between "wizard mode" and the Wizard role). Attempting to + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 109 + + + + start a game in debug mode when not allowed or not available will + result in falling back to explore mode instead. + + 12. Credits + + The original hack game was modeled on the Berkeley UNIX rogue + game. Large portions of this document were shamelessly cribbed from A + Guide to the Dungeons of Doom, by Michael C. Toy and Kenneth C. R. C. + Arnold. Small portions were adapted from Further Exploration of the + Dungeons of Doom, by Ken Arromdee. + + NetHack is the product of literally scores of people's work. + Main events in the course of the game development are described below: + + Jay Fenlason wrote the original Hack, with help from Kenny Wood- + land, Mike Thome, and Jon Payne. + + Andries Brouwer did a major re-write while at Stichting Mathema- + tisch Centrum (now Centrum Wiskunde & Informatica), transforming Hack + into a very different game. He published the Hack source code for use + on UNIX systems by posting that to Usenet newsgroup net.sources (later + renamed comp.sources) releasing version 1.0 in December of 1984, then + versions 1.0.1, 1.0.2, and finally 1.0.3 in July of 1985. Usenet + newsgroup net.games.hack (later renamed rec.games.hack, eventually + replaced by rec.games.roguelike.nethack) was created for discussing + it. + + Don G. Kneller ported Hack 1.0.3 to Microsoft C and MS-DOS, pro- + ducing PC HACK 1.01e, added support for DEC Rainbow graphics in ver- + sion 1.03g, and went on to produce at least four more versions (3.0, + 3.2, 3.51, and 3.6; note that these are old Hack version numbers, not + contemporary NetHack ones). + + R. Black ported PC HACK 3.51 to Lattice C and the Atari + 520/1040ST, producing ST Hack 1.03. + + Mike Stephenson merged these various versions back together, + incorporating many of the added features, and produced NetHack version + 1.4 in 1987. He then coordinated a cast of thousands in enhancing and + debugging NetHack 1.4 and released NetHack versions 2.2 and 2.3. Like + Hack, they were released by posting their source code to Usenet where + they remained available in various archives accessible via ftp and + uucp after expiring from the newsgroup. + + Later, Mike coordinated a major re-write of the game, heading a + team which included Ken Arromdee, Jean-Christophe Collet, Steve Creps, + Eric Hendrickson, Izchak Miller, Eric S. Raymond, John Rupley, Mike + Threepoint, and Janet Walz, to produce NetHack 3.0c. + + NetHack 3.0 was ported to the Atari by Eric R. Smith, to OS/2 by + Timo Hakulinen, and to VMS by David Gentzel. The three of them and + Kevin Darcy later joined the main NetHack Development Team to produce + subsequent revisions of 3.0. + + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 110 + + + + Olaf Seibert ported NetHack 2.3 and 3.0 to the Amiga. Norm + Meluch, Stephen Spackman and Pierre Martineau designed overlay code + for PC NetHack 3.0. Johnny Lee ported NetHack 3.0 to the Macintosh. + Along with various other Dungeoneers, they continued to enhance the + PC, Macintosh, and Amiga ports through the later revisions of 3.0. + + Version 3.0 went through ten relatively rapidly released "patch- + level" revisions. Versions at the time were known as 3.0 for the base + release and variously as "3.0a" through "3.0j", "3.0 patchlevel 1" + through "3.0 patchlevel 10", or "3.0pl1" through "3.0pl10" rather than + 3.0.0 and 3.0.1 through 3.0.10; the three component numbering scheme + began to be used with 3.1.0. + + Headed by Mike Stephenson and coordinated by Izchak Miller and + Janet Walz, the NetHack Development Team which now included Ken + Arromdee, David Cohrs, Jean-Christophe Collet, Kevin Darcy, Matt Day, + Timo Hakulinen, Steve Linhart, Dean Luick, Pat Rankin, Eric Raymond, + and Eric Smith undertook a radical revision of 3.0. They re-struc- + tured the game's design, and re-wrote major parts of the code. They + added multiple dungeons, a new display, special individual character + quests, a new endgame and many other new features, and produced + NetHack 3.1. Version 3.1.0 was released in January of 1993. + + Ken Lorber, Gregg Wonderly and Greg Olson, with help from Richard + Addison, Mike Passaretti, and Olaf Seibert, developed NetHack 3.1 for + the Amiga. + + Norm Meluch and Kevin Smolkowski, with help from Carl Schelin, + Stephen Spackman, Steve VanDevender, and Paul Winner, ported NetHack + 3.1 to the PC. + + Jon W{tte and Hao-yang Wang, with help from Ross Brown, Mike Eng- + ber, David Hairston, Michael Hamel, Jonathan Handler, Johnny Lee, Tim + Lennan, Rob Menke, and Andy Swanson, developed NetHack 3.1 for the + Macintosh, porting it for MPW. Building on their development, Bart + House added a Think C port. + + Timo Hakulinen ported NetHack 3.1 to OS/2. Eric Smith ported + NetHack 3.1 to the Atari. Pat Rankin, with help from Joshua + Delahunty, was responsible for the VMS version of NetHack 3.1. + Michael Allison ported NetHack 3.1 to Windows NT. + + Dean Luick, with help from David Cohrs, developed NetHack 3.1 for + X11. It drew the map as text rather than graphically but included + nh10.bdf, an optionally used custom X11 font which has tiny images in + place of letters and punctuation, a precursor of tiles. Those images + don't extend to individual monster and object types, just replacements + for monster and object classes (so one custom image for all "a" + insects and another for all "[" armor and so forth, not separate + images for beetles and ants or for cloaks and boots). + + Warwick Allison wrote a graphically displayed version of NetHack + for the Atari where the tiny pictures were described as "icons" and + were distinct for specific types of monsters and objects rather than + + + NetHack 5.0.0 May 2, 2026 + + + + + + NetHack Guidebook 111 + + + + just their classes. He contributed them to the NetHack Development + Team which rechristened them "tiles", original usage which has subse- + quently been picked up by various other games. NetHack's tiles sup- + port was then implemented on other platforms (initially MS-DOS but + eventually Windows, Qt, and X11 too). + + The 3.2 NetHack Development Team, comprised of Michael Allison, + Ken Arromdee, David Cohrs, Jessie Collet, Steve Creps, Kevin Darcy, + Timo Hakulinen, Steve Linhart, Dean Luick, Pat Rankin, Eric Smith, + Mike Stephenson, Janet Walz, and Paul Winner, released version 3.2.0 + in April of 1996. + + Version 3.2 marked the tenth anniversary of the formation of the + development team. In a testament to their dedication to the game, all + thirteen members of the original NetHack Development Team remained on + the team at the start of work on that release. During the interval + between the release of 3.1.3 and 3.2.0, one of the founding members of + the NetHack Development Team, Dr. Izchak Miller, was diagnosed with + cancer and passed away. That release of the game was dedicated to him + by the development and porting teams. + + Version 3.2 proved to be more stable than previous versions. + Many bugs were fixed, abuses eliminated, and game features tuned for + better game play. + + During the lifespan of NetHack 3.1 and 3.2, several enthusiasts + of the game added their own modifications to the game and made these + "variants" publicly available: + + Tom Proudfoot and Yuval Oren created NetHack++, which was quickly + renamed NetHack-- when some people incorrectly assumed that it was a + conversion of the C source code to C++. Working independently, + Stephen White wrote NetHack Plus. Tom Proudfoot later merged NetHack + Plus and his own NetHack-- to produce SLASH. Larry Stewart-Zerba and + Warwick Allison improved the spell casting system with the Wizard + Patch. Warwick Allison also ported NetHack to use the Qt interface. + + Warren Cheung combined SLASH with the Wizard Patch to produce + Slash'EM, and with the help of Kevin Hugo, added more features. Kevin + later joined the NetHack Development Team and incorporated the best of + these ideas into NetHack 3.3. + + The final update to 3.2 was the bug fix release 3.2.3, which was + released simultaneously with 3.3.0 in December 1999 just in time for + the Year 2000. Because of the newer version, 3.2.3 was released as a + source code patch only, without any ready-to-play distribution for + systems that usually had such. + + (To anyone considering resurrecting an old version: all versions + before 3.2.3 had a Y2K bug. The high scores file and the log file + contained dates which were formatted using a two-digit year, and + 1999's year 99 was followed by 2000's year 100. That got written out + successfully but it unintentionally introduced an extra column in the + file layout which prevented score entries from being read back in cor- + + + NetHack 5.0.0 May 2, 2026 - MESG - message window mapping (the only one supported in - 3.6); - pattern - the pattern to match; - sound file - the sound file to play; - volume - the volume to be set while playing the sound file. - The pattern should be a POSIX extended regular expression. - 9.13. Configuring Status Hilites - Your copy of NetHack may have been compiled with support for - "Status Hilites". If so, you can customize your game display by - setting thresholds to change the color or appearance of fields in - the status display. - The format for defining status colors is: + NetHack Guidebook 112 - OPTION=hilite_status:field-name/behavior/color&attributes - For example, the following line in your configuration file - will cause the hitpoints field to display in the color red if - your hitpoints drop to or below a threshold of 30%: - OPTION=hilite_status:hitpoints/<=30%/red/normal + rectly, interfering with insertion of new high scores and with + retrieval of old character names to use for random ghost and statue + names in the current game.) - (That example is actually specifying red&normal for <=30% and no- - color&normal for >30%.) + The 3.3 NetHack Development Team, consisting of Michael Allison, + Ken Arromdee, David Cohrs, Jessie Collet, Steve Creps, Kevin Darcy, + Timo Hakulinen, Kevin Hugo, Steve Linhart, Ken Lorber, Dean Luick, Pat + Rankin, Eric Smith, Mike Stephenson, Janet Walz, and Paul Winner, + released 3.3.0 in December 1999 and 3.3.1 in August of 2000. - For another example, the following line in your configura- - tion file will cause wisdom to be displayed red if it drops and - green if it rises: + Version 3.3 offered many firsts. It was the first version to sep- + arate race and profession. The Elf class was removed in preference to + an elf race, and the races of dwarves, gnomes, and orcs made their + first appearance in the game alongside the familiar human race. Monk + and Ranger roles joined Archeologists, Barbarians, Cavemen, Healers, + Knights, Priests, Rogues, Samurai, Tourists, Valkyries and of course, + Wizards. It was also the first version to allow you to ride a steed, + and was the first version to have a publicly available web-site list- + ing all the bugs that had been discovered. Despite that constantly + growing bug list, 3.3 proved stable enough to last for more than a + year and a half. - OPTION=hilite_status:wisdom/down/red/up/green + The 3.4 NetHack Development Team initially consisted of Michael + Allison, Ken Arromdee, David Cohrs, Jessie Collet, Kevin Hugo, Ken + Lorber, Dean Luick, Pat Rankin, Mike Stephenson, Janet Walz, and Paul + Winner, with Warwick Allison joining just before the release of + NetHack 3.4.0 in March 2002. - Allowed colors are black, red, green, brown, blue, magenta, - cyan, gray, orange, light-green, yellow, light-blue, light- + As with version 3.3, various people contributed to the game as a + whole as well as supporting ports on the different platforms that + NetHack runs on: + Pat Rankin maintained 3.4 for VMS. - NetHack 3.6 February 3, 2023 + Michael Allison maintained NetHack 3.4 for the MS-DOS platform. + Paul Winner and Yitzhak Sapir provided encouragement. + Dean Luick, Mark Modrall, and Kevin Hugo maintained and enhanced + the Macintosh port of 3.4. + Michael Allison, David Cohrs, Alex Kompel, Dion Nicolaas, and + Yitzhak Sapir maintained and enhanced 3.4 for the Microsoft Windows + platform. Alex Kompel contributed a new graphical interface for the + Windows port. Alex Kompel also contributed a Windows CE port for + 3.4.1. + Ron Van Iwaarden was the sole maintainer of NetHack for OS/2 the + past several releases. Unfortunately Ron's last OS/2 machine stopped + working in early 2006. A great many thanks to Ron for keeping NetHack + alive on OS/2 all these years. + Janne Salmijarvi and Teemu Suikki maintained and enhanced the + Amiga port of 3.4 after Janne Salmijarvi resurrected it for 3.3.1. - NetHack Guidebook 77 + NetHack 5.0.0 May 2, 2026 - magenta, light-cyan, and white. And "no-color", the default - foreground color on the display, which is not necessarily the - same as black or white or any of the other colors. - Allowed attributes are none, bold, dim, underline, blink, - and inverse. "Normal" is a synonym for "none"; they should not - be used in combination with any of the other attributes. - To specify both a color and an attribute, use `&' to combine - them. To specify multiple attributes, use `+' to combine those. - For example: "magenta&inverse+dim". - Note that the display may substitute or ignore particular - attributes depending upon its capabilities, and in general may - interpret the attributes any way it wants. For example, on some - display systems a request for bold might yield blink or vice ver- - sa. On others, issuing an attribute request while another is al- - ready set up will replace the earlier attribute rather than com- - bine with it. Since NetHack issues attribute requests sequen- - tially (at least with the tty interface) rather than all at once, - the only way a situation like that can be controlled is to speci- - fy just one attribute. - You can adjust the appearance of the following status - fields: - title dungeon-level experience-level - strength gold experience - dexterity hitpoints HD - constitution hitpoints-max time - intelligence power hunger - wisdom power-max carrying-capacity - charisma armor-class condition - alignment score + NetHack Guidebook 113 - The pseudo-field "characteristics" can be used to set all six - of Str, Dex, Con, Int, Wis, and Cha at once. "HD" is "hit - dice", an approximation of experience level displayed when - polymorphed. "experience", "time", and "score" are condition- - ally displayed depending upon your other option settings. - Instead of a behavior, "condition" takes the following condi- - tion flags: stone, slime, strngl, foodpois, termill, blind, - deaf, stun, conf, hallu, lev, fly, and ride. You can use "ma- - jor_troubles" as an alias for stone through termill, "mi- - nor_troubles" for blind through hallu, "movement" for lev, fly, - and ride, and "all" for every condition. - Allowed behaviors are "always", "up", "down", "changed", a per- - centage or absolute number threshold, or text to match against. + Christian "Marvin" Bressler maintained 3.4 for the Atari after he + resurrected it for 3.3.1. - * "always" will set the default attributes for that field. + The release of NetHack 3.4.3 in December 2003 marked the begin- + ning of a long release hiatus. 3.4.3 proved to be a remarkably stable + version that provided continued enjoyment by the community for more + than a decade. The NetHack Development Team slowly and quietly contin- + ued to work on the game behind the scenes during the tenure of 3.4.3. + It was during that same period that several new variants emerged + within the NetHack community. Notably sporkhack by Derek S. Ray, + unnethack by Patric Mueller, nitrohack and its successors originally + by Daniel Thaler and then by Alex Smith, and Dynahack by Tung Nguyen. + Some of those variants continue to be developed, maintained, and + enjoyed by the community to this day. - * "up", "down" set the field attributes for when the field - value changes upwards or downwards. This attribute times + In September 2014, an interim snapshot of the code under develop- + ment was released publicly by other parties. Since that code was a + work-in-progress and had not gone through the process of debugging it + as a suitable release, it was decided that the version numbers present + on that code snapshot would be retired and never used in an official + NetHack release. An announcement was posted on the NetHack Develop- + ment Team's official https://www.nethack.org website to that effect, + stating that there would never be a 3.4.4, 3.5, or 3.5.0 official + release version. + In January 2015, preparation began for the release of NetHack + 3.6. - NetHack 3.6 February 3, 2023 + At the beginning of development for what would eventually get + released as 3.6.0, the NetHack Development Team consisted of Warwick + Allison, Michael Allison, Ken Arromdee, David Cohrs, Jessie Collet, + Ken Lorber, Dean Luick, Pat Rankin, Mike Stephenson, Janet Walz, and + Paul Winner. In early 2015, ahead of the release of 3.6.0, new mem- + bers Sean Hunt, Pasi Kallinen, and Derek S. Ray joined the NetHack + Development Team. + Near the end of the development of 3.6.0, one of the significant + inspirations for many of the humorous and fun features found in the + game, author Terry Pratchett, passed away. NetHack 3.6.0 introduced a + tribute to him. + 3.6.0 was released in December 2015, and merged work done by the + development team since the release of 3.4.3 with some of the beloved + community patches. Many bugs were fixed and some code was restruc- + tured. + The NetHack Development Team, as well as Steve VanDevender and + Kevin Smolkowski, ensured that NetHack 3.6 continued to operate on + various UNIX flavors and maintained the X11 interface. + Ken Lorber, Haoyang Wang, Pat Rankin, and Dean Luick maintained + the port of NetHack 3.6 for MacOS. - NetHack Guidebook 78 - out after statushilites turns. + NetHack 5.0.0 May 2, 2026 - * "changed" sets the field attribute for when the field val- - ue changes. This attribute times out after statushilites - turns. (If a field has both a "changed" rule and an "up" - or "down" rule which matches a change in the field's val- - ue, the "up" or "down" one takes precedence.) - * percentage sets the field attribute when the field value - matches the percentage. It is specified as a number be- - tween 0 and 100, followed by `%' (percent sign). If the - percentage is prefixed with `<=' or `>=', it also matches - when value is below or above the percentage. Use prefix - `<' or `>' to match when strictly below or above. (The - numeric limit is relaxed slightly for those: >-1% and - <101% are allowed.) Only four fields support percentage - rules. Percentages for "hitpoints" and "power" are - straightforward; they're based on the corresponding maxi- - mum field. Percentage highlight rules are also allowed - for "experience level" and "experience points" (valid when - the showexp option is enabled). For those, the percentage - is based on the progress from the start of the current ex- - perience level to the start of the next level. So if lev- - el 2 starts at 20 points and level 3 starts at 40 points, - having 30 points is 50% and 35 points is 75%. 100% is - unattainable for experience because you'll gain a level - and the calculations will be reset for that new level, but - a rule for =100% is allowed and matches the special case - of being exactly 1 experience point short of the next lev- - el. - * absolute value sets the attribute when the field value - matches that number. The number must be 0 or higher, ex- - cept for "armor-class' which allows negative values, and - may optionally be preceded by `='. If the number is pre- - ceded by `<=' or `>=' instead, it also matches when value - is below or above. If the prefix is `<' or `>', only - match when strictly above or below. - * text match sets the attribute when the field value matches - the text. Text matches can only be used for "alignment", - "carrying-capacity", "hunger", "dungeon-level", and "ti- - tle". For title, only the role's rank title is tested; - the character's name is ignored. - The in-game options menu can help you determine the correct - syntax for a configuration file. + NetHack Guidebook 114 - The whole feature can be disabled by setting option sta- - tushilites to 0. - Example hilites: + Michael Allison, David Cohrs, Bart House, Pasi Kallinen, Alex + Kompel, Dion Nicolaas, Derek S. Ray and Yitzhak Sapir maintained the + port of NetHack 3.6 for Microsoft Windows. + Pat Rankin attempted to keep the VMS port running for NetHack + 3.6, hindered by limited access. Kevin Smolkowski has updated and + tested it for the most recent version of OpenVMS (V8.4 as of this + writing) on Alpha and Integrity (aka Itanium aka IA64) but not VAX. + Ray Chason resurrected the MS-DOS port for 3.6 and contributed + the necessary updates to the community at large. - NetHack 3.6 February 3, 2023 + In late April 2018, several hundred bug fixes for 3.6.0 and some + new features were assembled and released as NetHack 3.6.1. The + NetHack Development Team at the time of release of 3.6.1 consisted of + Warwick Allison, Michael Allison, Ken Arromdee, David Cohrs, Jessie + Collet, Pasi Kallinen, Ken Lorber, Dean Luick, Patric Mueller, Pat + Rankin, Derek S. Ray, Alex Smith, Mike Stephenson, Janet Walz, and + Paul Winner. + In early May 2019, another 320 bug fixes along with some enhance- + ments and the adopted curses window port, were released as 3.6.2. + Bart House, who had contributed to the game as a porting team + participant for decades, joined the NetHack Development Team in late + May 2019. + NetHack 3.6.3 was released on December 5, 2019 containing over + 190 bug fixes to NetHack 3.6.2. + NetHack 3.6.4 was released on December 18, 2019 containing a + security fix and a few bug fixes. - NetHack Guidebook 79 + NetHack 3.6.5 was released on January 27, 2020 containing some + security fixes and a small number of bug fixes. + NetHack 3.6.6 was released on March 8, 2020 containing a security + fix and some bug fixes. + NetHack 3.6.7 was released on February 16, 2023 containing a + security fix and some bug fixes. - OPTION=hilite_status: gold/up/yellow/down/brown - OPTION=hilite_status: characteristics/up/green/down/red - OPTION=hilite_status: hitpoints/100%/gray&normal - OPTION=hilite_status: hitpoints/<100%/green&normal - OPTION=hilite_status: hitpoints/<66%/yellow&normal - OPTION=hilite_status: hitpoints/<50%/orange&normal - OPTION=hilite_status: hitpoints/<33%/red&bold - OPTION=hilite_status: hitpoints/<15%/red&inverse - OPTION=hilite_status: condition/major/orange&inverse - OPTION=hilite_status: condition/lev+fly/red&inverse + Development work for the major release to follow NetHack 3.6 + began in 2015 around the same time as NetHack 3.6.0 was being + released. That development work continued in parallel to each of the + NetHack 3.6 releases from 2015 through 2023, and continued until the + end of April 2026. For the first time, that development was shared + publicly on GitHub and SourceForge as it occurred. It was done under + the label NetHack-3.7 work-in-progress (WIP), although the version + number for the next release had not yet been solidified. - 9.14. Modifying NetHack Symbols + Exposure of the development to the public brought many good + things, and some challenges. People were able to observe and criticize + changes and new features almost immediately, and they often did. The - NetHack can load entire symbol sets from the symbol file. - The options that are used to select a particular symbol set - from the symbol file are: - - symset - Set the name of the symbol set that you want to load. - - roguesymset - Set the name of the symbol set that you want to load for dis- - play on the rogue level. + NetHack 5.0.0 May 2, 2026 - You can also override one or more symbols using the SYMBOLS - and ROGUESYMBOLS configuration file options. Symbols are speci- - fied as name:value pairs. Note that NetHack escape-processes the - value string in conventional C fashion. This means that \ is a - prefix to take the following character literally. Thus \ needs - to be represented as \\. The special prefix form \m switches on - the meta bit in the symbol value, and the ^ prefix causes the - following character to be treated as a control character. - - NetHack Symbols - Symbol Name Description - ----------------------------------------------------------------- - S_air (air) - _ S_altar (altar) - " S_amulet (amulet) - A S_angel (angelic being) - a S_ant (ant or other insect) - ^ S_anti_magic_trap (anti-magic field) - [ S_armor (suit or piece of armor) - [ S_armour (suit or piece of armor) - ^ S_arrow_trap (arrow trap) - 0 S_ball (iron ball) - # S_bars (iron bars) - B S_bat (bat or bird) - ^ S_bear_trap (bear trap) - - S_blcorn (bottom left corner) - b S_blob (blob) - + S_book (spellbook) - - - - NetHack 3.6 February 3, 2023 - - - - - - NetHack Guidebook 80 - - - - ) S_boomleft (boomerang open left) - ( S_boomright (boomerang open right) - ` S_boulder (boulder) - - S_brcorn (bottom right corner) - C S_centaur (centaur) - _ S_chain (iron chain) - # S_cloud (cloud) - c S_cockatrice (cockatrice) - $ S_coin (pile of coins) - # S_corr (corridor) - - S_crwall (wall) - # S_darkroom (dark room) - ^ S_dart_trap (dart trap) - & S_demon (major demon) - * S_digbeam (dig beam) - > S_dnladder (ladder down) - > S_dnstair (staircase down) - d S_dog (dog or other canine) - D S_dragon (dragon) - ; S_eel (sea monster) - E S_elemental (elemental) - / S_explode1 (explosion top left) - - S_explode2 (explosion top center) - \ S_explode3 (explosion top right) - | S_explode4 (explosion middle left) - S_explode5 (explosion middle center) - | S_explode6 (explosion middle right) - \ S_explode7 (explosion bottom left) - - S_explode8 (explosion bottom center) - / S_explode9 (explosion bottom right) - e S_eye (eye or sphere) - ^ S_falling_rock_trap (falling rock trap) - f S_feline (cat or other feline) - ^ S_fire_trap (fire trap) - ! S_flashbeam (flash beam) - % S_food (piece of food) - { S_fountain (fountain) - F S_fungus (fungus or mold) - * S_gem (gem or rock) - S_ghost (ghost) - H S_giant (giant humanoid) - G S_gnome (gnome) - ' S_golem (golem) - | S_grave (grave) - g S_gremlin (gremlin) - - S_hbeam (horizontal beam [zap animation]) - # S_hcdbridge (horizontal raised drawbridge) - + S_hcdoor (closed door in horizontal wall) - . S_hodbridge (horizontal lowered drawbridge) - | S_hodoor (open door in horizontal wall) - ^ S_hole (hole) - @ S_human (human or elf) - h S_humanoid (humanoid) - - - - NetHack 3.6 February 3, 2023 - - - - - - NetHack Guidebook 81 - - - - - S_hwall (horizontal wall) - . S_ice (ice) - i S_imp (imp or minor demon) - I S_invisible (invisible monster) - J S_jabberwock (jabberwock) - j S_jelly (jelly) - k S_kobold (kobold) - K S_kop (Keystone Kop) - ^ S_land_mine (land mine) - } S_lava (molten lava) - l S_leprechaun (leprechaun) - ^ S_level_teleporter (level teleporter) - L S_lich (lich) - y S_light (light) - # S_litcorr (lit corridor) - : S_lizard (lizard) - \ S_lslant (diagonal beam [zap animation]) - ^ S_magic_portal (magic portal) - ^ S_magic_trap (magic trap) - m S_mimic (mimic) - ] S_mimic_def (mimic) - M S_mummy (mummy) - N S_naga (naga) - . S_ndoor (doorway without door) - n S_nymph (nymph) - O S_ogre (ogre) - o S_orc (orc) - p S_piercer (piercer) - ^ S_pit (pit) - # S_poisoncloud (poison cloud) - ^ S_polymorph_trap (polymorph trap) - } S_pool (water) - ! S_potion (potion) - P S_pudding (pudding or ooze) - q S_quadruped (quadruped) - Q S_quantmech (quantum mechanic) - = S_ring (ring) - ` S_rock (boulder or statue) - r S_rodent (rodent) - ^ S_rolling_boulder_trap (rolling boulder trap) - . S_room (floor of a room) - / S_rslant (diagonal beam [zap animation]) - ^ S_rust_trap (rust trap) - R S_rustmonst (rust monster or disenchanter) - ? S_scroll (scroll) - # S_sink (sink) - ^ S_sleeping_gas_trap (sleeping gas trap) - S S_snake (snake) - s S_spider (arachnid or centipede) - ^ S_spiked_pit (spiked pit) - ^ S_squeaky_board (squeaky board) - 0 S_ss1 (magic shield 1 of 4) - # S_ss2 (magic shield 2 of 4) - - - - NetHack 3.6 February 3, 2023 - - - - - - NetHack Guidebook 82 - - - - @ S_ss3 (magic shield 3 of 4) - * S_ss4 (magic shield 4 of 4) - ^ S_statue_trap (statue trap) - S_stone (solid rock or unexplored terrain - or dark part of a room) - ] S_strange_obj (strange object) - - S_sw_bc (swallow bottom center) - \ S_sw_bl (swallow bottom left) - / S_sw_br (swallow bottom right) - | S_sw_ml (swallow middle left) - | S_sw_mr (swallow middle right) - - S_sw_tc (swallow top center) - / S_sw_tl (swallow top left) - \ S_sw_tr (swallow top right) - - S_tdwall (wall) - ^ S_teleportation_trap (teleportation trap) - \ S_throne (opulent throne) - - S_tlcorn (top left corner) - | S_tlwall (wall) - ( S_tool (useful item (pick-axe, key, lamp...)) - ^ S_trap_door (trap door) - t S_trapper (trapper or lurker above) - - S_trcorn (top right corner) - # S_tree (tree) - T S_troll (troll) - | S_trwall (wall) - - S_tuwall (wall) - U S_umber (umber hulk) - u S_unicorn (unicorn or horse) - < S_upladder (ladder up) - < S_upstair (staircase up) - V S_vampire (vampire) - | S_vbeam (vertical beam [zap animation]) - # S_vcdbridge (vertical raised drawbridge) - + S_vcdoor (closed door in vertical wall) - . S_venom (splash of venom) - ^ S_vibrating_square (vibrating square) - . S_vodbridge (vertical lowered drawbridge) - - S_vodoor (open door in vertical wall) - v S_vortex (vortex) - | S_vwall (vertical wall) - / S_wand (wand) - } S_water (water) - ) S_weapon (weapon) - " S_web (web) - w S_worm (worm) - ~ S_worm_tail (long worm tail) - W S_wraith (wraith) - x S_xan (xan or other extraordinary insect) - X S_xorn (xorn) - Y S_yeti (apelike creature) - Z S_zombie (zombie) - z S_zruty (zruty) - - - - NetHack 3.6 February 3, 2023 - - - - - - NetHack Guidebook 83 - - - - S_pet_override (any pet if ACCESSIBILITY=1 is set) - S_hero_override (hero if ACCESSIBILITY=1 is set) - - Notes: - - * Several symbols in this table appear to be blank. They are the - space character, except for S_pet_override and S_hero_override - which don't have any default value and can only be used if en- - abled in the "sysconf" file. - * S_rock is misleadingly named; rocks and stones use S_gem. - Statues and boulders are the rock being referred to, but since - version 3.6.0, statues are displayed as the monster they de- - pict. So S_rock is only used for boulders and not used at all - if overridden by the more specific S_boulder. - 9.15. Configuring NetHack for Play by the Blind - NetHack can be set up to use only standard ASCII characters - for making maps of the dungeons. This makes the MS-DOS versions - of NetHack completely accessible to the blind who use speech - and/or Braille access technologies. Players will require a good - working knowledge of their screen-reader's review features, and - will have to know how to navigate horizontally and vertically - character by character. They will also find the search capabili- - ties of their screen-readers to be quite valuable. Be certain to - examine this Guidebook before playing so you have an idea what - the screen layout is like. You'll also need to be able to locate - the PC cursor. It is always where your character is located. - Merely searching for an @-sign will not always find your charac- - ter since there are other humanoids represented by the same sign. - Your screen-reader should also have a function which gives you - the row and column of your review cursor and the PC cursor. - These co-ordinates are often useful in giving players a better - sense of the overall location of items on the screen. - NetHack can also be compiled with support for sending the - game messages to an external program, such as a text-to-speech - synthesizer. If the "#version" extended command shows "external - program as a message handler", your NetHack has been compiled - with the capability. When compiling NetHack from source on Linux - and other POSIX systems, define MSGHANDLER to enable it. To use - the capability, set the environment variable NETHACK_MSGHANDLER - to an executable, which will be executed with the game message as - the program's only parameter. + NetHack Guidebook 115 - While it is not difficult for experienced users to edit the - defaults.nh file to accomplish this, novices may find this task - somewhat daunting. Included within the "symbols" file of all of- - ficial distributions of NetHack is a symset called NHAccess. Se- - lecting that symset in your configuration file will cause the - game to run in a manner accessible to the blind. After you have - gained some experience with the game and with editing files, you - may want to alter settings via SYMBOLS= and ROGUESYMBOLS= in your - NetHack 3.6 February 3, 2023 + GitHub pull request system made it straightforward for people to con- + tribute directly to development. Contributions resolved many, many + bugs in the game and we thank all the contributors. + In early 2026, with the game development getting stable enough to + consider initiating an official release, the devteam reviewed the + nature and number of changes in the game. It was clear that there was + sufficient depth and breadth to warrant a major release and version + 5.0 was decided on. That's a new major release over 3.x, without + opening up any ambiguity or confusion with existing variants that + there might have been had it been released as version 4.0. + NetHack 5.0.0 was released on May 2, 2026. + The source code for NetHack 5.0.0 was modified and modernized to + be compliant with the C99 standard. The 5.0.0 release contained over + 3100 fixes, changes, and updated features. + NetHack 5.0 was the first version to replace the lex and yacc + level and dungeon compilers of past versions, with a new Lua inter- + preter-based approach to provide those elements. Lua is also used for + the quest texts in NetHack 5.0.0. The entire development team acknowl- + edges the work done by Pasi Kallinen to make that happen. - NetHack Guidebook 84 + At the time of the NetHack 5.0 release, the core development + team, active and erstwhile, included Warwick Allison, Michael Allison, + Ken Arromdee, David Cohrs, Jessie Collet, Bart House, Kevin Hugo, Pasi + Kallinen, Ken Lorber, Dean Luick, Pat Rankin, Derek S. Ray, Alex + Smith, Patric Mueller, Mike Stephenson, Janet Walz, Paul Winner. + Ken Lorber, Pat Rankin, Patrick Mueller and Michael Allison + helped ensure that NetHack 5.0 would run on macOS. + Ingo Paschke somehow managed to revive a NetHack 5.0 port for the + Amiga, using a cross-compiler on a modern platform to do so. His work + was shared so others can straightforwardly produce NetHack 5.0 for the + Amiga thanks to his efforts. - configuration file to better suit your preferences. See the pre- - vious section for the special symbols S_pet_override to force a - consistent symbol for all pets and S_hero_override to force a - unique symbol for the player character if accessibility is en- - abled in the sysconf file. + Ray Chason contributed the majority of maintenance work for the + NetHack 5.0 MS-DOS port, including porting the curses interface to it. + Michael Allison ensured that NetHack 5.0 core changes continued to + work with the msdos port and keep it alive. Cross-compiling the MS- + DOS port has helped make that possible and mostly painless. - The most crucial settings to make the game more accessible - are: + People that contributed to the Windows port of NetHack 5.0 since + the development of NetHack 5.0 began over eleven years ago, included + Michael Allison, David Cohrs, Bart House, Pasi Kallinen, Alex Kompel, + Dion Nicolaas, Derek S. Ray and Yitzhak Sapir. - symset:NHAccess - Load a symbol set appropriate for use by blind players. + With sadness, the devteam would like to acknowledge and remember + the past contributions from the late Ron Van Iwaarden, who was the + sole maintainer of NetHack for OS/2 for several past NetHack releases. + Ron will be missed. - roguesymset:NHAccess - Load a symbol set for the rogue level that is appropriate for - use by blind players. - menustyle:traditional - This will assist in the interface to speech synthesizers. - nomenu_overlay - Show menus on a cleared screen and aligned to the left edge. + NetHack 5.0.0 May 2, 2026 - number_pad - A lot of speech access programs use the number-pad to review - the screen. If this is the case, disable the number_pad option - and use the traditional Rogue-like commands. - autodescribe - Automatically describe the terrain under the cursor when tar- - geting. - mention_walls - Give feedback messages when walking towards a wall or when - travel command was interrupted. - whatis_coord:compass - When targeting with cursor, describe the cursor position with - coordinates relative to your character. - whatis_filter:area - When targeting with cursor, filter possible locations so only - those in the same area (eg. same room, or same corridor) are - considered. + NetHack Guidebook 116 - whatis_moveskip - When targeting with cursor and using fast-move, skip the same - glyphs instead of moving 8 units at a time. - nostatus_updates - Prevent updates to the status lines at the bottom of the - screen, if your screen-reader reads those lines. The same in- - formation can be seen via the "#attributes" command. + The official NetHack web site is maintained by Ken Lorber at + https://www.nethack.org/. - NetHack 3.6 February 3, 2023 - NetHack Guidebook 85 - 9.16. Global Configuration for System Administrators - If NetHack is compiled with the SYSCF option, a system ad- - ministrator should set up a global configuration; this is a file - in the same format as the traditional per-user configuration file - (see above). This file should be named sysconf and placed in the - same directory as the other NetHack support files. The options - recognized in this file are listed below. Any option not set us- - es a compiled-in default (which may not be appropriate for your - system). - WIZARDS = A space-separated list of user names who are allowed - to play in debug mode (commonly referred to as wizard mode). A - value of a single asterisk (*) allows anyone to start a game in - debug mode. - SHELLERS = A list of users who are allowed to use the shell es- - cape command (!). The syntax is the same as WIZARDS. - EXPLORERS = A list of users who are allowed to use the explore - mode. The syntax is the same as WIZARDS. - MAXPLAYERS = Limit the maximum number of games that can be run- - ning at the same time. - SUPPORT = A string explaining how to get local support (no de- - fault value). - RECOVER = A string explaining how to recover a game on this - system (no default value). - SEDUCE = 0 or 1 to disable or enable, respectively, the SEDUCE - option. When disabled, incubi and succubi behave like nymphs. - CHECK_PLNAME = Setting this to 1 will make the EXPLORERS, WIZ- - ARDS, and SHELLERS check for the player name instead of the us- - er's login name. - CHECK_SAVE_UID = 0 or 1 to disable or enable, respectively, the - UID (used identification number) checking for save files (to - verify that the user who is restoring is the same one who - saved). - The following options affect the score file: - PERSMAX = Maximum number of entries for one person. - ENTRYMAX = Maximum number of entries in the score file. - POINTSMIN = Minimum number of points to get an entry in the - score file. - PERS_IS_UID = 0 or 1 to use user names or numeric userids, re- - spectively, to identify unique people for the score file. - NetHack 3.6 February 3, 2023 - NetHack Guidebook 86 - MAX_STATUENAME_RANK = Maximum number of score file entries to - use for random statue names (default is 10). - ACCESSIBILITY = 0 or 1 to disable or enable, respectively, the - ability for players to set S_pet_override and S_hero_override - symbols in their configuration file. - PORTABLE_DEVICE_PATHS = 0 or 1 Windows OS only, the game will - look for all of its external files, and write to all of its - output files in one place rather than at the standard loca- - tions. - DUMPLOGFILE = A filename where the end-of-game dumplog is - saved. Not defining this will prevent dumplog from being cre- - ated. Only available if your game is compiled with DUMPLOG. Al- - lows the following placeholders: - %% - literal `%' - %v - version (eg. "3.6.3-0") - %u - game UID - %t - game start time, UNIX timestamp format - %T - current time, UNIX timestamp format - %d - game start time, YYYYMMDDhhmmss format - %D - current time, YYYYMMDDhhmmss format - %n - player name - %N - first character of player name - 10. Scoring + 12.1. Special Thanks - NetHack maintains a list of the top scores or scorers on - your machine, depending on how it is set up. In the latter case, - each account on the machine can post only one non-winning score - on this list. If you score higher than someone else on this - list, or better your previous score, you will be inserted in the - proper place under your current name. How many scores are kept - can also be set up when NetHack is compiled. + On behalf of the NetHack community, thank you very much once + again to M. Drew Streib and Pasi Kallinen for providing a public + NetHack server at nethack.alt.org. Thanks to Keith Simpson and Andy + Thomson for hardfought.org. Thanks to all those unnamed dungeoneers + who invest their time and effort into annual NetHack tournaments such + as Junethack, The November NetHack Tournament, and in days past, + devnull.net (gone for now, but not forgotten). - Your score is chiefly based upon how much experience you - gained, how much loot you accumulated, how deep you explored, and - how the game ended. If you quit the game, you escape with all of - your gold intact. If, however, you get killed in the Mazes of - Menace, the guild will only hear about 90% of your gold when your - corpse is discovered (adventurers have been known to collect - finder's fees). So, consider whether you want to take one last - hit at that monster and possibly live, or quit and stop with - whatever you have. If you quit, you keep all your gold, but if - you swing and live, you might find more. - If you just want to see what the current top players/games - list is, you can type nethack -s all on most versions. + NetHack 5.0.0 May 2, 2026 - NetHack 3.6 February 3, 2023 + NetHack Guidebook 117 + 12.2. Dungeoneers - NetHack Guidebook 87 + From time to time, some depraved individual out there in netland + sends a particularly intriguing modification to help out with the + game. The NetHack Development Team sometimes makes note of the names + of the worst of these miscreants in this, the list of Dungeoneers: - 11. Explore mode - NetHack is an intricate and difficult game. Novices might - falter in fear, aware of their ignorance of the means to survive. - Well, fear not. Your dungeon comes equipped with an "explore" or - "discovery" mode that enables you to keep old save files and - cheat death, at the paltry cost of not getting on the high score - list. - There are two ways of enabling explore mode. One is to - start the game with the -X command-line switch or with the play- - mode:explore option. The other is to issue the "#exploremode" - extended command while already playing the game. Starting a new - game in explore mode provides your character with a wand of wish- - ing in initial inventory; switching during play does not. The - other benefits of explore mode are left for the trepid reader to - discover. - 11.1. Debug mode - Debug mode, also known as wizard mode, is undocumented aside - from this brief description and the various "debug mode only" - commands listed among the command descriptions. It is intended - for tracking down problems within the program rather than to pro- - vide god-like powers to your character, and players who attempt - debugging are expected to figure out how to use it themselves. - It is initiated by starting the game with the -D command-line - switch or with the playmode:debug option. - For some systems, the player must be logged in under a par- - ticular user name to be allowed to use debug mode; for others, - the hero must be given a particular character name (but may be - any role; there's no connection between "wizard mode" and the - Wizard role). Attempting to start a game in debug mode when not - allowed or not available will result in falling back to explore - mode instead. - 12. Credits - The original hack game was modeled on the Berkeley UNIX - rogue game. Large portions of this paper were shamelessly - cribbed from A Guide to the Dungeons of Doom, by Michael C. Toy - and Kenneth C. R. C. Arnold. Small portions were adapted from - Further Exploration of the Dungeons of Doom, by Ken Arromdee. - NetHack is the product of literally dozens of people's work. - Main events in the course of the game development are described - below: - Jay Fenlason wrote the original Hack, with help from Kenny - Woodland, Mike Thome and Jon Payne. - Andries Brouwer did a major re-write, transforming Hack into - a very different game, and published (at least) three versions - NetHack 3.6 February 3, 2023 - NetHack Guidebook 88 - (1.0.1, 1.0.2, and 1.0.3) for UNIX machines to the Usenet. - Don G. Kneller ported Hack 1.0.3 to Microsoft C and MS-DOS, - producing PC HACK 1.01e, added support for DEC Rainbow graphics - in version 1.03g, and went on to produce at least four more ver- - sions (3.0, 3.2, 3.51, and 3.6). - R. Black ported PC HACK 3.51 to Lattice C and the Atari - 520/1040ST, producing ST Hack 1.03. - Mike Stephenson merged these various versions back together, - incorporating many of the added features, and produced NetHack - 1.4. He then coordinated a cast of thousands in enhancing and - debugging NetHack 1.4 and released NetHack versions 2.2 and 2.3. - Later, Mike coordinated a major rewrite of the game, heading - a team which included Ken Arromdee, Jean-Christophe Collet, Steve - Creps, Eric Hendrickson, Izchak Miller, John Rupley, Mike Threep- - oint, and Janet Walz, to produce NetHack 3.0c. - NetHack 3.0 was ported to the Atari by Eric R. Smith, to - OS/2 by Timo Hakulinen, and to VMS by David Gentzel. The three - of them and Kevin Darcy later joined the main NetHack Development - Team to produce subsequent revisions of 3.0. - Olaf Seibert ported NetHack 2.3 and 3.0 to the Amiga. Norm - Meluch, Stephen Spackman and Pierre Martineau designed overlay - code for PC NetHack 3.0. Johnny Lee ported NetHack 3.0 to the - Macintosh. Along with various other Dungeoneers, they continued - to enhance the PC, Macintosh, and Amiga ports through the later - revisions of 3.0. - Headed by Mike Stephenson and coordinated by Izchak Miller - and Janet Walz, the NetHack Development Team which now included - Ken Arromdee, David Cohrs, Jean-Christophe Collet, Kevin Darcy, - Matt Day, Timo Hakulinen, Steve Linhart, Dean Luick, Pat Rankin, - Eric Raymond, and Eric Smith undertook a radical revision of 3.0. - They re-structured the game's design, and re-wrote major parts of - the code. They added multiple dungeons, a new display, special - individual character quests, a new endgame and many other new - features, and produced NetHack 3.1. - Ken Lorber, Gregg Wonderly and Greg Olson, with help from - Richard Addison, Mike Passaretti, and Olaf Seibert, developed - NetHack 3.1 for the Amiga. - Norm Meluch and Kevin Smolkowski, with help from Carl Sche- - lin, Stephen Spackman, Steve VanDevender, and Paul Winner, ported - NetHack 3.1 to the PC. - Jon W{tte and Hao-yang Wang, with help from Ross Brown, Mike - Engber, David Hairston, Michael Hamel, Jonathan Handler, Johnny - Lee, Tim Lennan, Rob Menke, and Andy Swanson, developed NetHack - 3.1 for the Macintosh, porting it for MPW. Building on their - NetHack 3.6 February 3, 2023 - NetHack Guidebook 89 + Adam Aronow Irina Rempt-Drijfhout Mike Gallop + Alex Kompel Izchak Miller Mike Passaretti + Alex Smith J. Ali Harlow Mike Stephenson + Andreas Dorn Janet Walz Mikko Juola + Andy Church Janne Salmijarvi Nathan Eady + Andy Swanson Jean-Christophe Collet Norm Meluch + Andy Thomson Jeff Bailey Olaf Seibert - development, Bart House added a Think C port. + NetHack 5.0.0 May 2, 2026 - Timo Hakulinen ported NetHack 3.1 to OS/2. Eric Smith port- - ed NetHack 3.1 to the Atari. Pat Rankin, with help from Joshua - Delahunty, was responsible for the VMS version of NetHack 3.1. - Michael Allison ported NetHack 3.1 to Windows NT. - Dean Luick, with help from David Cohrs, developed NetHack - 3.1 for X11. Warwick Allison wrote a tiled version of NetHack - for the Atari; he later contributed the tiles to the NetHack De- - velopment Team and tile support was then added to other plat- - forms. - The 3.2 NetHack Development Team, comprised of Michael Alli- - son, Ken Arromdee, David Cohrs, Jessie Collet, Steve Creps, Kevin - Darcy, Timo Hakulinen, Steve Linhart, Dean Luick, Pat Rankin, Er- - ic Smith, Mike Stephenson, Janet Walz, and Paul Winner, released - version 3.2 in April of 1996. - Version 3.2 marked the tenth anniversary of the formation of - the development team. In a testament to their dedication to the - game, all thirteen members of the original NetHack Development - Team remained on the team at the start of work on that release. - During the interval between the release of 3.1.3 and 3.2, one of - the founding members of the NetHack Development Team, Dr. Izchak - Miller, was diagnosed with cancer and passed away. That release - of the game was dedicated to him by the development and porting - teams. - During the lifespan of NetHack 3.1 and 3.2, several enthusi- - asts of the game added their own modifications to the game and - made these "variants" publicly available: + NetHack Guidebook 118 - Tom Proudfoot and Yuval Oren created NetHack++, which was - quickly renamed NetHack--. Working independently, Stephen White - wrote NetHack Plus. Tom Proudfoot later merged NetHack Plus and - his own NetHack-- to produce SLASH. Larry Stewart-Zerba and War- - wick Allison improved the spell casting system with the Wizard - Patch. Warwick Allison also ported NetHack to use the Qt inter- - face. - Warren Cheung combined SLASH with the Wizard Patch to pro- - duce Slash'EM, and with the help of Kevin Hugo, added more fea- - tures. Kevin later joined the NetHack Development Team and in- - corporated the best of these ideas in NetHack 3.3. - The final update to 3.2 was the bug fix release 3.2.3, which - was released simultaneously with 3.3.0 in December 1999 just in - time for the Year 2000. + Ari Huttunen Jochen Erwied Pasi Kallinen + Bart House John Kallen Pat Rankin + Benson I. Margulies John Rupley Patric Mueller + Bill Dyer John S. Bien Paul Winner + Boudewijn Waijers Johnny Lee Pierre Martineau + Bruce Cox Jon W{tte Ralf Brown + Bruce Holloway Jonathan Handler Ray Chason + Bruce Mewborne Joshua Delahunty Richard Addison + Cameron Root Karl Garrison Richard Beigel + Carl Schelin Keizo Yamamoto Richard P. Hughey + Chris Russo Keith Simpson Rob Menke + David Cohrs Ken Arnold Robin Bandy + David Damerell Ken Arromdee Robin Johnson + David Gentzel Ken Lorber Roderick Schertler + David Hairston Ken Washikita Roland McGrath + Dean Luick Kestrel Gregorich-Trevor Ron Van Iwaarden + Del Lamb Kevin Darcy Ronnen Miller + Derek S. Ray Kevin Hugo Ross Brown + Deron Meranda Kevin Sitze Sascha Wostmann + Dion Nicolaas Kevin Smolkowski Scott Bigham + Dylan O'Donnell Kevin Sweet Scott R. Turner + Eric Backus Lars Huttar Sean Hunt + Eric Hendrickson Leon Arnott Stephen Spackman + Eric R. Smith M. Drew Streib Stefan Thielscher + Eric S. Raymond Malcolm Ryan Stephen White + Erik Andersen Mark Gooderum Steve Creps + Fredrik Ljungdahl Mark Modrall Steve Linhart + Frederick Roeber Marvin Bressler Steve VanDevender + G. Branden Robinson Matthew Day Teemu Suikki + Gil Neiger Merlyn LeRoy Tim Lennan + Greg Laskin Michael Allison Timo Hakulinen + Greg Olson Michael Feir Tom Almy + Gregg Wonderly Michael Hamel Tom West + Hao-yang Wang Michael Meyer Warren Cheung + Helge Hafting Michael Sokolov Warwick Allison + Ingo Paschke Mike Engber Yitzhak Sapir - The 3.3 NetHack Development Team, consisting of Michael Al- - lison, Ken Arromdee, David Cohrs, Jessie Collet, Steve Creps, - Kevin Darcy, Timo Hakulinen, Kevin Hugo, Steve Linhart, Ken Lor- - ber, Dean Luick, Pat Rankin, Eric Smith, Mike Stephenson, Janet - NetHack 3.6 February 3, 2023 - NetHack Guidebook 90 - Walz, and Paul Winner, released 3.3.0 in December 1999 and 3.3.1 - in August of 2000. - Version 3.3 offered many firsts. It was the first version to - separate race and profession. The Elf class was removed in pref- - erence to an elf race, and the races of dwarves, gnomes, and orcs - made their first appearance in the game alongside the familiar - human race. Monk and Ranger roles joined Archeologists, Barbar- - ians, Cavemen, Healers, Knights, Priests, Rogues, Samurai, - Tourists, Valkyries and of course, Wizards. It was also the - first version to allow you to ride a steed, and was the first - version to have a publicly available web-site listing all the - bugs that had been discovered. Despite that constantly growing - bug list, 3.3 proved stable enough to last for more than a year - and a half. - The 3.4 NetHack Development Team initially consisted of - Michael Allison, Ken Arromdee, David Cohrs, Jessie Collet, Kevin - Hugo, Ken Lorber, Dean Luick, Pat Rankin, Mike Stephenson, Janet - Walz, and Paul Winner, with Warwick Allison joining just before - the release of NetHack 3.4.0 in March 2002. - As with version 3.3, various people contributed to the game - as a whole as well as supporting ports on the different platforms - that NetHack runs on: - Pat Rankin maintained 3.4 for VMS. - Michael Allison maintained NetHack 3.4 for the MS-DOS plat- - form. Paul Winner and Yitzhak Sapir provided encouragement. - Dean Luick, Mark Modrall, and Kevin Hugo maintained and en- - hanced the Macintosh port of 3.4. - Michael Allison, David Cohrs, Alex Kompel, Dion Nicolaas, - and Yitzhak Sapir maintained and enhanced 3.4 for the Microsoft - Windows platform. Alex Kompel contributed a new graphical inter- - face for the Windows port. Alex Kompel also contributed a Win- - dows CE port for 3.4.1. - Ron Van Iwaarden was the sole maintainer of NetHack for OS/2 - the past several releases. Unfortunately Ron's last OS/2 machine - stopped working in early 2006. A great many thanks to Ron for - keeping NetHack alive on OS/2 all these years. - Janne Salmijarvi and Teemu Suikki maintained and enhanced - the Amiga port of 3.4 after Janne Salmijarvi resurrected it for - 3.3.1. + NetHack 5.0.0 May 2, 2026 - Christian "Marvin" Bressler maintained 3.4 for the Atari af- - ter he resurrected it for 3.3.1. - The release of NetHack 3.4.3 in December 2003 marked the be- - ginning of a long release hiatus. 3.4.3 proved to be a remarkably - NetHack 3.6 February 3, 2023 + NetHack Guidebook 119 + Brand and product names are trademarks or registered trademarks + of their respective holders. - NetHack Guidebook 91 - stable version that provided continued enjoyment by the community - for more than a decade. The NetHack Development Team slowly and - quietly continued to work on the game behind the scenes during - the tenure of 3.4.3. It was during that same period that several - new variants emerged within the NetHack community. Notably - sporkhack by Derek S. Ray, unnethack by Patric Mueller, nitrohack - and its successors originally by Daniel Thaler and then by Alex - Smith, and Dynahack by Tung Nguyen. Some of those variants con- - tinue to be developed, maintained, and enjoyed by the community - to this day. - In September 2014, an interim snapshot of the code under de- - velopment was released publicly by other parties. Since that code - was a work-in-progress and had not gone through the process of - debugging it as a suitable release, it was decided that the ver- - sion numbers present on that code snapshot would be retired and - never used in an official NetHack release. An announcement was - posted on the NetHack Development Team's official nethack.org - website to that effect, stating that there would never be a - 3.4.4, 3.5, or 3.5.0 official release version. - In January 2015, preparation began for the release of - NetHack 3.6. - At the beginning of development for what would eventually - get released as 3.6.0, the NetHack Development Team consisted of - Warwick Allison, Michael Allison, Ken Arromdee, David Cohrs, - Jessie Collet, Ken Lorber, Dean Luick, Pat Rankin, Mike Stephen- - son, Janet Walz, and Paul Winner. In early 2015, ahead of the - release of 3.6.0, new members Sean Hunt, Pasi Kallinen, and Derek - S. Ray joined the NetHack Development Team. - Near the end of the development of 3.6.0, one of the signif- - icant inspirations for many of the humorous and fun features - found in the game, author Terry Pratchett, passed away. NetHack - 3.6.0 introduced a tribute to him. - 3.6.0 was released in December 2015, and merged work done by - the development team since the release of 3.4.3 with some of the - beloved community patches. Many bugs were fixed and some code was - restructured. - The NetHack Development Team, as well as Steve VanDevender - and Kevin Smolkowski, ensured that NetHack 3.6 continued to oper- - ate on various UNIX flavors and maintained the X11 interface. - Ken Lorber, Haoyang Wang, Pat Rankin, and Dean Luick main- - tained the port of NetHack 3.6 for Mac OSX. - Michael Allison, David Cohrs, Bart House, Pasi Kallinen, - Alex Kompel, Dion Nicolaas, Derek S. Ray and Yitzhak Sapir main- - tained the port of NetHack 3.6 for Microsoft Windows. - NetHack 3.6 February 3, 2023 - NetHack Guidebook 92 - Pat Rankin attempted to keep the VMS port running for - NetHack 3.6, hindered by limited access. Kevin Smolkowski has up- - dated and tested it for the most recent version of OpenVMS (V8.4 - as of this writing) on Alpha and Integrity (aka Itanium aka IA64) - but not VAX. - Ray Chason resurrected the msdos port for 3.6 and contrib- - uted the necessary updates to the community at large. - In late April 2018, several hundred bug fixes for 3.6.0 and - some new features were assembled and released as NetHack 3.6.1. - The NetHack Development Team at the time of release of 3.6.1 con- - sisted of Warwick Allison, Michael Allison, Ken Arromdee, David - Cohrs, Jessie Collet, Pasi Kallinen, Ken Lorber, Dean Luick, - Patric Mueller, Pat Rankin, Derek S. Ray, Alex Smith, Mike - Stephenson, Janet Walz, and Paul Winner. - In early May 2019, another 320 bug fixes along with some en- - hancements and the adopted curses window port, were released as - 3.6.2. - Bart House, who had contributed to the game as a porting - team participant for decades, joined the NetHack Development Team - in late May 2019. - NetHack 3.6.3 was released on December 5, 2019 containing - over 190 bug fixes to NetHack 3.6.2. - NetHack 3.6.4 was released on December 18, 2019 containing a - security fix and a few bug fixes. - NetHack 3.6.5 was released on January 27, 2020 containing - some security fixes and a small number of bug fixes. - NetHack 3.6.6 was released on March 8, 2020 containing a se- - curity fix and some bug fixes. - NetHack 3.6.7 was released in February 2023 containing a se- - curity fix and some bug fixes. - The official NetHack web site is maintained by Ken Lorber at - https://www.nethack.org/. - 12.1. SPECIAL THANKS - On behalf of the NetHack community, thank you very much once - again to M. Drew Streib and Pasi Kallinen for providing a public - NetHack server at nethack.alt.org. Thanks to Keith Simpson and - Andy Thomson for hardfought.org. Thanks to all those unnamed dun- - geoneers who invest their time and effort into annual NetHack - tournaments such as Junethack, The November NetHack Tournament - and in days past, devnull.net (gone for now, but not forgotten). - NetHack 3.6 February 3, 2023 - NetHack Guidebook 93 - - - - - - - - - - - - From time to time, some depraved individual out there in - netland sends a particularly intriguing modification to help out - with the game. The NetHack Development Team sometimes makes note - of the names of the worst of these miscreants in this, the list - of Dungeoneers: - Adam Aronow J. Ali Harlow Mikko Juola - Alex Kompel Janet Walz Nathan Eady - Alex Smith Janne Salmijarvi Norm Meluch - Andreas Dorn Jean-Christophe Collet Olaf Seibert - Andy Church Jeff Bailey Pasi Kallinen - Andy Swanson Jochen Erwied Pat Rankin - Andy Thomson John Kallen Patric Mueller - Ari Huttunen John Rupley Paul Winner - Bart House John S. Bien Pierre Martineau - Benson I. Margulies Johnny Lee Ralf Brown - Bill Dyer Jon W{tte Ray Chason - Boudewijn Waijers Jonathan Handler Richard Addison - Bruce Cox Joshua Delahunty Richard Beigel - Bruce Holloway Karl Garrison Richard P. Hughey - Bruce Mewborne Keizo Yamamoto Rob Menke - Carl Schelin Keith Simpson Robin Bandy - Chris Russo Ken Arnold Robin Johnson - David Cohrs Ken Arromdee Roderick Schertler - David Damerell Ken Lorber Roland McGrath - David Gentzel Ken Washikita Ron Van Iwaarden - David Hairston Kevin Darcy Ronnen Miller - Dean Luick Kevin Hugo Ross Brown - Del Lamb Kevin Sitze Sascha Wostmann - Derek S. Ray Kevin Smolkowski Scott Bigham - Deron Meranda Kevin Sweet Scott R. Turner - Dion Nicolaas Lars Huttar Sean Hunt - Dylan O'Donnell Leon Arnott Stephen Spackman - Eric Backus M. Drew Streib Stefan Thielscher - Eric Hendrickson Malcolm Ryan Stephen White - Eric R. Smith Mark Gooderum Steve Creps - Eric S. Raymond Mark Modrall Steve Linhart - Erik Andersen Marvin Bressler Steve VanDevender - Fredrik Ljungdahl Matthew Day Teemu Suikki - Frederick Roeber Merlyn LeRoy Tim Lennan - Gil Neiger Michael Allison Timo Hakulinen - Greg Laskin Michael Feir Tom Almy - Greg Olson Michael Hamel Tom West - Gregg Wonderly Michael Sokolov Warren Cheung - Hao-yang Wang Mike Engber Warwick Allison - Helge Hafting Mike Gallop Yitzhak Sapir - Irina Rempt-Drijfhout Mike Passaretti - Izchak Miller Mike Stephenson - Brand and product names are trademarks or registered trade- - marks of their respective holders. - NetHack 3.6 February 3, 2023 + NetHack 5.0.0 May 2, 2026 diff --git a/doc/config.nh b/doc/config.nh index 437158250..69c722135 100644 --- a/doc/config.nh +++ b/doc/config.nh @@ -1,7 +1,10 @@ -# NetHack 3.6 config.nh $NHDT-Date: 1524689547 2018/04/25 20:52:27 $ $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.1 $ +# NetHack 3.7 config.nh $NHDT-Date: 1745978702 2025/04/29 18:05:02 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.10 $ # Copyright (c) 2016 by Pasi Kallinen # NetHack may be freely redistributed. See license for details. -# Sample config file for NetHack 3.6 +# +# Sample run-time configuration file for NetHack 5.0.0 +# usually named ".nethackrc" (note leading dot; location +# depends upon the type of system nethack is running on). # # A '#' at the beginning of a line means the rest of the line is a comment. # @@ -9,9 +12,10 @@ # playing. # # Copy the contents of this file into -# * defaults.nh, same folder as nethack.exe or nethackW.exe (DOS, Windows) -# * ~/.nethackrc (Unix, linux, Mac OS X) +# * %USERPROFILE%\nethack\.nethackrc on Windows +# * ~/.nethackrc (Unix, linux, macOS) # * "NetHack Defaults" on pre-OSX Mac and BeOS +# * defaults.nh, same folder as nethack.exe on DOS # * NetHack.cnf on Amiga, Atari, OS/2, and VMS # # To change the configuration, comment out the unwanted lines, and @@ -122,7 +126,7 @@ # Objects will try to keep their inventory letters #OPTIONS=fixinv -# Try and display on the entire screen rather than in a window. +# Try to display on the entire screen rather than in a window. #OPTIONS=fullscreen # If more information is available for an object looked at with @@ -176,9 +180,17 @@ # Default is 'inverse' #OPTIONS=menu_headings:inverse -# Show object symbols in menus in the item class lines where that object symbol -# acts as an accelerator key to select items of that class. -#OPTIONS=menu_objsyms +# Control of displaying object symbols in menus for picking objects: +# show symbols in individual menu entries only if there are no class separators +#OPTIONS=menu_objsyms:4 +# show symbols on object class separator lines and also in individual entries +#OPTIONS=menu_objsyms:3 +# show symbols in individual entries but not on class separators +#OPTIONS=menu_objsyms:2 +# show object symbols on class separators but not in individual entries +#OPTIONS=menu_objsyms:1 +# don't show symbols on class separators or in individual menu entries +#OPTIONS=menu_objsyms:0 # Do not clear the screen before drawing menus, and align menus to right #OPTIONS=menu_overlay @@ -486,7 +498,7 @@ # Show all unholy water in red #MENUCOLOR=" unholy " = red # Show all cursed worn items in orange and underlined -#MENUCOLOR=" cursed .* (being worn)" = orange&underline +#MENUCOLOR=" cursed .* \(being worn\)" = orange&underline # Use the IBM character set rather than just plain ascii characters @@ -529,3 +541,12 @@ # Use highlighting in the status lines when it changes? #OPTIONS=hilite_status:hitpoints/30%/bright-magenta/normal +### Crash reports +# CRASHREPORTURL must be set in syscf to enable these options. +# These identify you in crash reports +#OPTIONS=crash_name:Your Name +#OPTIONS=crash_email:user@example.com +# This limits the size of the URL generated for a crash report. Only +# use this if your browser can't handle very long URLs. It should be as +# large as possible. +#OPTIONS=crash_maxurl:4000. diff --git a/doc/dgn_comp.6 b/doc/dgn_comp.6 deleted file mode 100644 index 7b311831c..000000000 --- a/doc/dgn_comp.6 +++ /dev/null @@ -1,419 +0,0 @@ -.TH DGN_COMP 6 "25 May 2015" NETHACK -.de ND -.ds Nd \\$3 -.. -.de NB -.ds Nb \\$2 -.. -.de NR -.ds Nr \\$2 -.. -.ND $NHDT-Date: 1524689548 2018/04/25 20:52:28 $ -.NB $NHDT-Branch: NetHack-3.6.0 $ -.NR $NHDT-Revision: 1.6 $ -.ds Na Kenneth Lorber - -.SH NAME -dgn_comp \- NetHack dungeon compiler -.SH SYNOPSIS -.B dgn_comp -[ -.I file -] -.PP -If no arguments are given, it reads standard input. -.SH DESCRIPTION -.PP -.I 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. -.PP -The purpose of this tool is to provide NetHack administrators and -implementors with a convenient way to create a custom dungeon for the -game, without having to recompile the entire world. -.SH GRAMMAR -.PP -DUNGEON: -.B name -.B bonesmarker -( -.B base -, -.B rand -) [ -.B %age -] -.PP -where -.B name -is the dungeon name, -.B bonesmarker -is a letter for marking bones files, ( -.B base -, -.B rand -) is the number of levels, and -.B %age -is its percentage chance of being generated (if absent, 100% chance). - -DESCRIPTION: -.B tag -.PP -where -.B tag -is currently one of -.BR HELLISH , -.BR MAZELIKE , -or -.BR ROGUELIKE . - -ALIGNMENT | LEVALIGN: [ -.B lawful -| -.B neutral -| -.B chaotic -| -.B unaligned -] -.PP -gives the alignment of the dungeon/level (default is unaligned). - -ENTRY: -.B level -.PP -the dungeon entry point. The dungeon connection attaches at this -level of the given dungeon. -If the value of -.B level -is negative, the entry level is calculated from the bottom of the -dungeon, with -1 being the last level. -If this line is not present in a dungeon description, the entry level -defaults to 1. - -PROTOFILE: -.B name -.PP -the prototypical name for dungeon level files in this dungeon. -For example, the PROTOFILE name for the dungeon -.I Vlad's Tower -is -.IR tower . - -LEVEL: -.B name -.B bonesmarker -@ ( -.B base -, -.B rand -) [ -.B %age -] -.PP -where -.B name -is the level name, -.B bonesmarker -is a letter for marking bones files, ( -.B base -, -.B rand -) is the location and -.B %age -is the generation percentage, as above. - -RNDLEVEL: -.B name -.B bonesmarker -@ ( -.B base -, -.B rand -) -[ -.B %age -] -.B rndlevs -.PP -where -.B name -is the level name, -.B bonesmarker -is a letter for marking bones files, ( -.B base -, -.B rand -) is the location, -.B %age -is the generation percentage, as above, and -.B rndlevs -is the number of similar levels available to choose from. - -CHAINLEVEL: -.B name -.B bonesmarker -.B prev_name -+ ( -.B base -, -.B rand -) [ -.B %age -] -.PP -where -.B name -is the level name, -.B bonesmarker -is a letter for marking bones files, -.B prev_name -is the name of a level defined previously, ( -.B base -, -.B rand -) is the -.I offset -from the level being chained from, and -.B %age -is the generation percentage. - -RNDCHAINLEVEL: -.B name -.B bonesmarker -.B prev_name -+ ( -.B base -, -.B rand -) [ -.B %age -] -.B rndlevs -.PP -where -.B name -is the level name, -.B bonesmarker -is a letter for marking bones files, -.B prev_name -is the name of a level defined previously, ( -.B base -, -.B rand -) is the -.I offset -from the level being chained from, -.B %age -is the generation percentage, and -.B rndlevs -is the number of similar levels available to choose from. - -LEVELDESC: -.B type -.PP -where -.B type -is the level type, (see DESCRIPTION, above). The -.B type -is used to override any pre-set value used to describe the entire dungeon, -for this level only. - -BRANCH: -.B name -@ ( -.B base -, -.B rand -) [ -.B stair -| -.B no_up -| -.B no_down -| -.B portal -] [ -.B up -| -.B down -] -.PP -where -.B name -is the name of the dungeon to branch to, and ( -.B base -, -.B rand -) is the location of the branch. -The last two optional arguments are -the branch type and branch direction. -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 -.B no_up -and -.B no_down -which specify which stair direction is missing. -The default branch type is -.BR stair . -The direction for a stair can be either up or down; direction is not -applicable to portals. The default direction is -.BR down . - -CHAINBRANCH: -.B name -.B prev_name -+ ( -.B base -, -.B rand -) [ -.B stair -| -.B no_up -| -.B no_down -| -.B portal -] [ -.B up -| -.B down -] -.PP -where -.B name -is the name of the dungeon to branch to, -.B prev_name -is the name of a previously defined -.B level -and ( -.B base -, -.B rand -) is the -.I offset -from the level being chained from. -The optional branch type and direction are the same as described above. -.SH GENERIC RULES -.PP -Each dungeon must have a unique -.B bonesmarker , -and each special level must have a -.B bonesmarker -unique within its dungeon (letters may be reused in different dungeons). -If the -.B bonesmarker -has the special value "none", no bones files will be created for that -level or dungeon. -.PP -The value -.B base -may be in the range of 1 to -.B MAXLEVEL -(as defined in -.I global.h -). -.PP -The value -.B rand -may be in the range of -1 to -.BR MAXLEVEL . -.PP -If -.B rand -is -1 it will be replaced with the value (num_dunlevs(dungeon) - base) -during the load process (ie. from here to the end of the dungeon). -.PP -If -.B rand -is 0 the level is located absolutely at -.BR base . -.PP -Branches don't have a probability. Dungeons do. If a dungeon fails -to be generated during load, all its levels and branches are skipped. -.PP -No level or branch may be chained from a level with a percentage 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 probability for the same reason. -.PP -As a general rule using the dungeon compiler: -.PP -If a dungeon has a -.B protofile -name associated with it -.RI ( eg. -.BR tower ) -that file will be used. -.PP -If a special level is present, it will override the above rule and -the appropriate file will be loaded. -.PP -If neither of the above are present, the standard generator will -take over and make a "normal" level. -.PP -A level alignment, if present, will override -the alignment of the dungeon that it exists within. -.SH EXAMPLE -.PP -Here is the current syntax of the dungeon compiler's "language": - -.LP -.nf -.ta +8n +8n +8n -# -# 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" -.fi -.PP -.I NOTES: -.br -Lines beginning with '#' are considered comments. -.br -A special level must be explicitly aligned. The alignment of the dungeon -it is in only applies to non-special levels within that dungeon. -.SH AUTHOR -.PP -M. Stephenson (from the level compiler by Jean-Christophe Collet). -.SH "SEE ALSO" -.PP -lev_comp(6), nethack(6) -.SH BUGS -.PP -Probably infinite. -.SH COPYRIGHT -This file is Copyright (C) \*(Na and was last modified \*(Nd (version -\*(Nb:\*(Nr). -NetHack may be freely redistributed. See license for details. diff --git a/doc/dgn_comp.txt b/doc/dgn_comp.txt deleted file mode 100644 index 8a5ef546d..000000000 --- a/doc/dgn_comp.txt +++ /dev/null @@ -1,202 +0,0 @@ -DGN_COMP(6) Games Manual 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 administrators 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 generated (if absent, 100% chance). - - DESCRIPTION: tag - - where tag is currently one of HELLISH, MAZELIKE, or ROGUELIKE. - - ALIGNMENT | LEVALIGN: [ lawful | neutral | chaotic | unaligned ] - - gives the alignment of the dungeon/level (default is unaligned). - - ENTRY: level - - the dungeon entry point. The dungeon connection attaches at this level - of the given dungeon. If the value of level is negative, the entry - level is calculated from the bottom of the dungeon, with -1 being the - last level. If this line is not present in a dungeon description, the - entry level defaults to 1. - - PROTOFILE: name - - the prototypical name for dungeon level files in this dungeon. 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 per- - centage, 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 percent- - age, 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 percentage. - - 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 percentage, 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 ] - - where name is the name of the dungeon to branch to, and ( base , rand ) - is the location of the branch. The last two optional arguments are the - branch type and branch direction. 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. - - CHAINBRANCH: name prev_name + ( base , rand ) [ stair | no_up | no_down - | portal ] [ up | down ] - - 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 and direc- - tion 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_dunlevs(dungeon) - - base) during the load process (ie. from here to the end of the dun- - geon). - - 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 percentage gener- - ation probability. This is to prevent non-resolution during the load. - In addition, no branch may be made from a dungeon with a percentage - generation probability 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 generator will take - over and make a "normal" level. - - A level alignment, if present, will override the alignment of the dun- - geon that it exists within. - -EXAMPLE - Here is the current syntax of the dungeon compiler's "language": - - - # - # 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 dun- - geon 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. - -COPYRIGHT - This file is Copyright (C) Kenneth Lorber and was last modified - 2018/04/25 (version NetHack-3.6.0:1.6). NetHack may be freely redis- - tributed. See license for details. - - - -NETHACK 25 May 2015 DGN_COMP(6) diff --git a/doc/dlb.6 b/doc/dlb.6 index 23e98c2f7..e314989d2 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -1,109 +1,165 @@ -.TH DLB 6 "25 May 2015" NETHACK -.de ND -.ds Nd \\$3 -.. +.\" $NHDT-Branch: master $:$NHDT-Revision: 1.14 $ $NHDT-Date: 1735103831 2024/12/25 00:17:11 $ +.\"DO NOT REMOVE NH_DATESUB .TH DLB 6 "Date(%-d %B %Y)" Project(uc) +.TH DLB 6 "25 December 2024" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2024 .de NB .ds Nb \\$2 .. .de NR .ds Nr \\$2 .. -.ND $NHDT-Date: 1524689548 2018/04/25 20:52:28 $ -.NB $NHDT-Branch: NetHack-3.6.0 $ -.NR $NHDT-Revision: 1.7 $ +.NB $NHDT-Branch: keni-gitset $ +.NR $NHDT-Revision: 1.13 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ +.\" groff and AT&T-descended troffs use different hyphenation patterns. +.\" Don't hyphenate the last word on a page or column, or +.\" before/after last/first 2 characters of a word. +.ie \n(.g .hy 12 +.el .hy 14 .ds Na Kenneth Lorber .SH NAME dlb \- NetHack data librarian .SH SYNOPSIS .B dlb -{ -.B xct -} -[ -.B vfIC -] -arguments... -[ -.B files... -] -.SH DESCRIPTION +.\" We'd use `RB` with 7 arguments, but Unix troff man(7) has a limit of +.\" 6 arguments to its macros. +{\c +.BR c | t | x\c +}\c +.RB [ v ]\c +.RB [ C +.IR directory ] +.RI [ file ] +\&.\|.\|. .PP +.B dlb +{\c +.BR c | t | x\c +}\c +.RB [ v ]\c +.B I +.I list-file +.PP +.B dlb +{\c +.BR c | t | x\c +}\c +.RB [ v ]\c +.RB [ f +.IR archive-file-name ] +.RI [ file ] +\&.\|.\|. +.SH DESCRIPTION .I Dlb -is a file archiving tool in the spirit (and tradition) of tar for -NetHack version 3.1 and higher. It is used to maintain the -archive files from which NetHack reads special level files and other -read-only information. Note that like tar the command and option -specifiers are specified as a continuous string and are followed -by any arguments required in the same order as the option specifiers. +is a file archiving tool in the spirit (and tradition) of +.IR tar (1) +for +.IR nethack (6) +version 3.1 and higher. +It is used to maintain the +archive files from which the game reads special level files and other +read-only information. +Note that like +.IR tar , +the letters specifying the operation and options +are expressed as a continuous string. +Unlike +.IR tar , +.I dlb +is configured with a default set of file names to process. +.ig .PP -^?ALLDOCS +\*^?ALLDOCS This facility is optional and may be excluded during NetHack configuration. -^: -^?DLB +\*^: +\*^?DLB This facility is optional but is included in this NetHack configuration. -^: +\*^: This facility is optional and was excluded from this NetHack configuration. -^. -^. -.SH COMMANDS -The -.B x -command causes -.I dlb -to extract the contents of the archive into the current directory. -.PP -The +\*^. +\*^. +.. +.SS Operations .B c -command causes +causes .I dlb to create a new archive from files in the current directory. .PP -The .B t -command lists the files in the archive. -.SH OPTIONS AND ARGUMENTS -.DT -.ta \w'f archive\ \ \ 'u -v verbose output -.br -.sp 1 -f archive specify the archive. Default if f not specified is -LIBFILE (usually the nhdat file in the playground). -.br -.sp 1 -I lfile specify the file containing the list of files to -put in to or extract from the archive if no files are listed -on the command line. Default for archive creation if no files -are listed is LIBLISTFILE. -.br -.sp 1 -C dir change directory. Changes directory before trying to -read any files (including the archive and the lfile). -.br +lists the files in the archive. +.PP +.B x +causes +.I dlb +to extract the contents of the archive into the current directory. +.SH OPTIONS +.TP 13n \" "I list-file" + 2n +.BI "C " dir +Change directory to +.I dir +before trying to +read any files. +.TP +.BI "f " archive +Read from or write to +.I archive +instead of LIBFILE +(usually the +.I nhdat +file in the playground). +.TP +.BI "I " list-file +Read from +.I list-file +the names of files to emplace within or extract from the archive. +The default for archive creation is LIBLISTFILE. +.TP +.B v +Operate verbosely. .SH EXAMPLES Create the default archive from the default file list: -.br - dlb c -.sp 1 -List the contents of the archive 'foo': -.br - dlb tf foo -.SH AUTHOR +.RS +.EX +dlb c +.EE +.RE .PP +List the contents of the archive +.IR foo : +.RS +.EX +dlb tf foo +.EE +.RE +.SH AUTHOR Kenneth Lorber .SH "SEE ALSO" -.PP -nethack(6), tar(1) +.IR nethack (6), +.IR tar (1) .SH BUGS -.PP -Not a good tar emulation; - does not mean stdin or stdout. +.IP \(bu 2n +Not a good +.I tar +emulation; +.B \- +does not mean stdin or stdout. +.IP \(bu Should include an optional compression facility. +.IP \(bu Not all read-only files for NetHack can be read out of an archive; -examining the source is the only way to know which files can be. +examining the source is the only way to know which files can be. .SH COPYRIGHT -This file is Copyright (C) \*(Na and was last modified \*(Nd (version -\*(Nb:\*(Nr). -NetHack may be freely redistributed. See license for details. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/dlb.txt b/doc/dlb.txt index 7fbd931f5..7c021e273 100644 --- a/doc/dlb.txt +++ b/doc/dlb.txt @@ -6,49 +6,47 @@ NAME dlb - NetHack data librarian SYNOPSIS - dlb { xct } [ vfIC ] arguments... [ files... ] + dlb {c|t|x}[v][C directory] [file] ... -DESCRIPTION - Dlb is a file archiving tool in the spirit (and tradition) of tar for - NetHack version 3.1 and higher. It is used to maintain the archive - files from which NetHack reads special level files and other read-only - information. Note that like tar the command and option specifiers are - specified as a continuous string and are followed by any arguments - required in the same order as the option specifiers. + dlb {c|t|x}[v]I list-file + + dlb {c|t|x}[v][f archive-file-name] [file] ... - ^?ALLDOCS This facility is optional and may be excluded during NetHack - configuration. ^: ^?DLB This facility is optional but is included in - this NetHack configuration. ^: This facility is optional and was - excluded from this NetHack configuration. ^. ^. +DESCRIPTION + Dlb is a file archiving tool in the spirit (and tradition) of tar(1) + for nethack(6) version 3.1 and higher. It is used to maintain the + archive files from which the game reads special level files and other + read-only information. Note that like tar, the letters specifying the + operation and options are expressed as a continuous string. Unlike + tar, dlb is configured with a default set of file names to process. -COMMANDS - The x command causes dlb to extract the contents of the archive into - the current directory. + Operations + c causes dlb to create a new archive from files in the current direc- + tory. - The c command causes dlb to create a new archive from files in the cur- - rent directory. + t lists the files in the archive. - The t command lists the files in the archive. + x causes dlb to extract the contents of the archive into the current + directory. -OPTIONS AND ARGUMENTS - v verbose output +OPTIONS + C dir Change directory to dir before trying to read any files. - f archive specify the archive. Default if f not specified is LIBFILE - (usually the nhdat file in the playground). + f archive Read from or write to archive instead of LIBFILE (usually + the nhdat file in the playground). - I lfile specify the file containing the list of files to put in to - or extract from the archive if no files are listed on the command line. - Default for archive creation if no files are listed is LIBLISTFILE. + I list-file Read from list-file the names of files to emplace within + or extract from the archive. The default for archive cre- + ation is LIBLISTFILE. - C dir change directory. Changes directory before trying to read - any files (including the archive and the lfile). + v Operate verbosely. EXAMPLES Create the default archive from the default file list: - dlb c + dlb c - List the contents of the archive 'foo': - dlb tf foo + List the contents of the archive foo: + dlb tf foo AUTHOR Kenneth Lorber @@ -57,16 +55,18 @@ SEE ALSO nethack(6), tar(1) BUGS - Not a good tar emulation; - does not mean stdin or stdout. Should - include an optional compression facility. Not all read-only files for - NetHack can be read out of an archive; examining the source is the only - way to know which files can be. + o Not a good tar emulation; - does not mean stdin or stdout. + + o Should include an optional compression facility. + + o Not all read-only files for NetHack can be read out of an archive; + examining the source is the only way to know which files can be. COPYRIGHT - This file is Copyright (C) Kenneth Lorber and was last modified - 2018/04/25 (version NetHack-3.6.0:1.7). NetHack may be freely redis- - tributed. See license for details. + This file is Copyright (C) Kenneth Lorber, 2024 for version keni-git- + set:1.13. NetHack may be freely redistributed. See license for de- + tails. -NETHACK 25 May 2015 DLB(6) +NETHACK 25 December 2024 DLB(6) diff --git a/doc/fixes10.0 b/doc/fixes1-0.txt similarity index 100% rename from doc/fixes10.0 rename to doc/fixes1-0.txt diff --git a/doc/fixes14.f b/doc/fixes1-4-f.txt similarity index 100% rename from doc/fixes14.f rename to doc/fixes1-4-f.txt diff --git a/doc/fixes22.0 b/doc/fixes2-2.txt similarity index 100% rename from doc/fixes22.0 rename to doc/fixes2-2.txt diff --git a/doc/fixes23.e b/doc/fixes2-3-e.txt similarity index 100% rename from doc/fixes23.e rename to doc/fixes2-3-e.txt diff --git a/doc/fixes30.pl01 b/doc/fixes3-0-pl01.txt similarity index 100% rename from doc/fixes30.pl01 rename to doc/fixes3-0-pl01.txt diff --git a/doc/fixes30.pl02 b/doc/fixes3-0-pl02.txt similarity index 100% rename from doc/fixes30.pl02 rename to doc/fixes3-0-pl02.txt diff --git a/doc/fixes30.pl03 b/doc/fixes3-0-pl03.txt similarity index 100% rename from doc/fixes30.pl03 rename to doc/fixes3-0-pl03.txt diff --git a/doc/fixes30.pl04 b/doc/fixes3-0-pl04.txt similarity index 100% rename from doc/fixes30.pl04 rename to doc/fixes3-0-pl04.txt diff --git a/doc/fixes30.pl05 b/doc/fixes3-0-pl05.txt similarity index 100% rename from doc/fixes30.pl05 rename to doc/fixes3-0-pl05.txt diff --git a/doc/fixes30.pl06 b/doc/fixes3-0-pl06.txt similarity index 100% rename from doc/fixes30.pl06 rename to doc/fixes3-0-pl06.txt diff --git a/doc/fixes30.pl07 b/doc/fixes3-0-pl07.txt similarity index 100% rename from doc/fixes30.pl07 rename to doc/fixes3-0-pl07.txt diff --git a/doc/fixes30.pl08 b/doc/fixes3-0-pl08.txt similarity index 100% rename from doc/fixes30.pl08 rename to doc/fixes3-0-pl08.txt diff --git a/doc/fixes30.pl09 b/doc/fixes3-0-pl09.txt similarity index 100% rename from doc/fixes30.pl09 rename to doc/fixes3-0-pl09.txt diff --git a/doc/fixes30.pl10 b/doc/fixes3-0-pl10.txt similarity index 100% rename from doc/fixes30.pl10 rename to doc/fixes3-0-pl10.txt diff --git a/doc/fixes30.0 b/doc/fixes3-0.txt similarity index 100% rename from doc/fixes30.0 rename to doc/fixes3-0.txt diff --git a/doc/fixes31.1 b/doc/fixes3-1-1.txt similarity index 100% rename from doc/fixes31.1 rename to doc/fixes3-1-1.txt diff --git a/doc/fixes31.2 b/doc/fixes3-1-2.txt similarity index 100% rename from doc/fixes31.2 rename to doc/fixes3-1-2.txt diff --git a/doc/fixes31.3 b/doc/fixes3-1-3.txt similarity index 100% rename from doc/fixes31.3 rename to doc/fixes3-1-3.txt diff --git a/doc/fixes32.0 b/doc/fixes3-2-0.txt similarity index 100% rename from doc/fixes32.0 rename to doc/fixes3-2-0.txt diff --git a/doc/fixes32.1 b/doc/fixes3-2-1.txt similarity index 100% rename from doc/fixes32.1 rename to doc/fixes3-2-1.txt diff --git a/doc/fixes32.2 b/doc/fixes3-2-2.txt similarity index 100% rename from doc/fixes32.2 rename to doc/fixes3-2-2.txt diff --git a/doc/fixes32.3 b/doc/fixes3-2-3.txt similarity index 100% rename from doc/fixes32.3 rename to doc/fixes3-2-3.txt diff --git a/doc/fixes33.0 b/doc/fixes3-3-0.txt similarity index 100% rename from doc/fixes33.0 rename to doc/fixes3-3-0.txt diff --git a/doc/fixes33.1 b/doc/fixes3-3-1.txt similarity index 100% rename from doc/fixes33.1 rename to doc/fixes3-3-1.txt diff --git a/doc/fixes34.0 b/doc/fixes3-4-0.txt similarity index 100% rename from doc/fixes34.0 rename to doc/fixes3-4-0.txt diff --git a/doc/fixes34.1 b/doc/fixes3-4-1.txt similarity index 100% rename from doc/fixes34.1 rename to doc/fixes3-4-1.txt diff --git a/doc/fixes34.2 b/doc/fixes3-4-2.txt similarity index 100% rename from doc/fixes34.2 rename to doc/fixes3-4-2.txt diff --git a/doc/fixes34.3 b/doc/fixes3-4-3.txt similarity index 100% rename from doc/fixes34.3 rename to doc/fixes3-4-3.txt diff --git a/doc/fixes35.0 b/doc/fixes3-5-0.txt similarity index 100% rename from doc/fixes35.0 rename to doc/fixes3-5-0.txt diff --git a/doc/fixes36.0 b/doc/fixes3-6-0.txt similarity index 100% rename from doc/fixes36.0 rename to doc/fixes3-6-0.txt diff --git a/doc/fixes36.1 b/doc/fixes3-6-1.txt similarity index 99% rename from doc/fixes36.1 rename to doc/fixes3-6-1.txt index 5fda55113..3b0b27ddb 100644 --- a/doc/fixes36.1 +++ b/doc/fixes3-6-1.txt @@ -853,7 +853,7 @@ X11: new NetHack*highlight_prompt resource to control whether the persistent configuration will be highlighted when it's expecting input X11: NetHack*extcmd_height_delta resource can be used to adjust initial size of the extended commands menu -X11: status display split into three columns to accomodate Stone/Deaf/Lev/&c; +X11: status display split into three columns to accommodate Stone/Deaf/Lev/&c; NetHack*status_condition.foreground, .background, and .showGrip resources replaced by status_condition[1-3].* X11: more terminal-like default resources diff --git a/doc/fixes36.2 b/doc/fixes3-6-2.txt similarity index 100% rename from doc/fixes36.2 rename to doc/fixes3-6-2.txt diff --git a/doc/fixes36.3 b/doc/fixes3-6-3.txt similarity index 100% rename from doc/fixes36.3 rename to doc/fixes3-6-3.txt diff --git a/doc/fixes36.4 b/doc/fixes3-6-4.txt similarity index 95% rename from doc/fixes36.4 rename to doc/fixes3-6-4.txt index a4b8991c4..912f80723 100644 --- a/doc/fixes36.4 +++ b/doc/fixes3-6-4.txt @@ -11,7 +11,7 @@ GDBPATH and GREPPATH from sysconf or -D... on compilation command line were at end of game when that was enabled fix the article used in the message when your steed encounters a polymorph trap allow teleporting onto the vibrating square -message "your knapsack can't accomodate any more items" when picking stuff up +message "your knapsack can't accommodate any more items" when picking stuff up or removing such from container was inaccurate if there was some gold pending; vary the message rather than add more convoluted pickup code dozen-ish assorted spelling/typo fixes in messages and source comments diff --git a/doc/fixes36.5 b/doc/fixes3-6-5.txt similarity index 100% rename from doc/fixes36.5 rename to doc/fixes3-6-5.txt diff --git a/doc/fixes36.6 b/doc/fixes3-6-6.txt similarity index 82% rename from doc/fixes36.6 rename to doc/fixes3-6-6.txt index aaa2b875f..21ccaaef7 100644 --- a/doc/fixes36.6 +++ b/doc/fixes3-6-6.txt @@ -1,4 +1,4 @@ -$NHDT-Branch: NetHack-3.6 $:$NHDT-Revision: 1.4 $ $NHDT-Date: 1587039894 2020/04/16 12:24:54 $ +$NHDT-Branch: NetHack-3.6-Mar2020 $:$NHDT-Revision: 1.2 $ $NHDT-Date: 1583606861 2020/03/07 18:47:41 $ fixes36.6 contains a terse summary of changes made to 3.6.5 in order to produce 3.6.6 as well as any post-release fixes in binaries. @@ -17,10 +17,9 @@ avoid "'s glorkum pass harmlessly through the shade" for weaponless mon Platform- and/or Interface-Specific Fixes or Features ----------------------------------------------------- -teach unix/Makefile.doc how to make Guidebook.dat, an unpaginated copy of - Guidebook.txt General New Features -------------------- none + diff --git a/doc/fixes3-6-7.txt b/doc/fixes3-6-7.txt new file mode 100644 index 000000000..6ac447eb6 --- /dev/null +++ b/doc/fixes3-6-7.txt @@ -0,0 +1,73 @@ +$NHDT-Branch: to500 $:$NHDT-Revision: 1.2 $ $NHDT-Date: 1777409988 2026/04/28 20:59:48 $ + +fixes36.7 contains a summary of changes made to 3.6.6 in order to +produce 3.6.7 as well as any post-release fixes in binaries. + + +General Fixes and Modified Features +----------------------------------- +during engraving, spaces were counted instead of non-space (cherry-pick of + 4e0a1e04 from NetHack WIP) +avoid potential buffer overflow in append_str() +resolve missing dependency in NetHack.sln +code in include/tradstdc.h was trying to suppress warn_unused result by + defining warn_unused_result to an empty string and that began causing + a build error within a system-supplied header file cdefs.h when using + ubuntu impish 21.10; disable that for any Linux unless GCC_URWARN is + defined to force it back into effect +update_inventory() after leash goes slack +player assigned name for monsters, specific objects, or object types could be + longer than what was intented to be allowed; for 'curses', much longer + +Platform- and/or Interface-Specific Fixes or Features +----------------------------------------------------- +windows: added winflexbison to travis-ci configuration to permit full build of + levcomp and dgncomp +windows: a bad chdir specified in win/win32/dgnstuff.mak caused full build to + abort +windows: the console.rc file had outdated information stating 3.6.3 when the + official 3.6.6 binary was built. +windows: switch from using keyhandling dll's to incorporating the three + variations (default, ray, 340) in sys/winnt/nttty.c +curses: cherry-picked selectsaved code from NetHack WIP for menu of save files +NetHackW: fix delay rendering of cursor when using farlook + + +General New Features +-------------------- +none + + +Fixes to 3.6.7 Post-release Problems and other Post-release changes +------------------------------------------------------------------- +extend the fix for build failure w/ newer C library headers to macOS (pr #988) +Windows: fix range error detected by address sanitizer in plselInitDialog() +Windows: nethackw.exe was vertically spacing out menu items based on + the height of the tileset in use, even though the tiles in the + menu were drawn at the default height of 16 anyway; get rid of + the extraneous vertical spacing between the menu rows +hilite_pile can remain on the map after eating food off the floor +vms: update winprocs.h to ensure that CLR_MAX is defined; necessary for + compiling vmsmail.c which uses winprocs.h but not hack.h +curses: when #quitting, just before the high scores are about to be shown + status_window was NULL and dereferenced, so add checks (issue #1090) +unix: update Makefile.dat so that if parallel make is used, it will build + the data files "engrave", "epitaph", and "bogusmon" sequentially; + 'makedefs -s' builds all three at once and doing parallel instances + of that can produce seemingly mysterious problems by stomping on + each other's results +fix the mingw32 build of NetHack 3.6.7 by updating sys/winnt/Makefile.gcc, + sys/winnt/winnt.c and sys/winnt/stubs.c +correct the Ixoth tile +makedefs can produce individual bogusmon, engrave and epitaph files +drinkfountain() fate 24 to curse objects could end up cursing objects + on the floor chain instead of the intended inventory object chain +proceed with showpaths option even if the sysconf file is missing +avoid memory leak in mk_artifact(); cherry-pick of 3cca4f27 from NetHack WIP +avoid using col in Guidebook build, since some distros no longer include + it, particularly some that use musl libc +back-port some nroff macro updates for Guidebook +prevent a crash when using 'O' to interactively set a text match highlight + for hunger +avoid a reported obuf reuse in use_misc() when using a bullwhip + diff --git a/doc/fixes36.7 b/doc/fixes36.7 deleted file mode 100644 index f5138bb74..000000000 --- a/doc/fixes36.7 +++ /dev/null @@ -1,45 +0,0 @@ -$NHDT-Branch: NetHack-3.6 $:$NHDT-Revision: 1.4 $ $NHDT-Date: 1587039894 2020/04/16 12:24:54 $ - -fixes36.7 contains a summary of changes made to 3.6.6 in order to -produce 3.6.7 as well as any post-release fixes in binaries. - - -General Fixes and Modified Features ------------------------------------ -during engraving, spaces were counted instead of non-space (cherry-pick of - 4e0a1e04 from NetHack-3.7) -avoid potential buffer overflow in append_str() -resolve missing dependency in NetHack.sln -code in include/tradstdc.h was trying to suppress warn_unused result by - defining warn_unused_result to an empty string and that began causing - a build error within a system-supplied header file cdefs.h when using - ubuntu impish 21.10; disable that for any Linux unless GCC_URWARN is - defined to force it back into effect -update_inventory() after leash goes slack -player assigned name for monsters, specific objects, or object types could be - longer than what was intented to be allowed; for 'curses', much longer - -Platform- and/or Interface-Specific Fixes or Features ------------------------------------------------------ -windows: added winflexbison to travis-ci configuration to permit full build of - levcomp and dgncomp -windows: a bad chdir specified in win/win32/dgnstuff.mak caused full build to - abort -windows: the console.rc file had outdated information stating 3.6.3 when the - official 3.6.6 binary was built. -windows: switch from using keyhandling dll's to incorporating the three - variations (default, ray, 340) in sys/winnt/nttty.c -curses: cherry-picked selectsaved code from 3.7 for menu of save files -NetHackW: fix delay rendering of cursor when using farlook - - -General New Features --------------------- -none - - -Fixes to 3.6.7 Post-release Problems and other Post-release changes -------------------------------------------------------------------- -none - - diff --git a/doc/fixes5-0-0.txt b/doc/fixes5-0-0.txt new file mode 100644 index 000000000..cba31fa8f --- /dev/null +++ b/doc/fixes5-0-0.txt @@ -0,0 +1,3268 @@ +NHDT-Branch: NetHack-5.0 $:$NHDT-Revision: 1.1649 $ $NHDT-Date: 1777000050 2026/04/23 19:07:30 $ + +General Fixes and Modified Features +----------------------------------- +hero polymorphed into a vampire can use #monster to shape-shift rather than + just do a one-shot polymorph into bat/cloud/wolf and shifted vampire + hero can use #monster again to take on another form (randomly chosen + among the shiftable shapes and true vampire form) +adjust bones filename buffer sizes to accommodate suffix +fix internal self-recover to work with recent fields added to checkpoint file +improvements to pronoun usage when hallucinating +function calls made from map_glyphinfo() based on dungeon level are now called + once per level +fast hero could have random clairvoyance happen more than once on same turn +using 'Q' on wielded weapon would offer to split stack; make using 'w' on a + quivered stack behave similarly +weight for giant spider was too low for creature of size 'large'; + weight for giant beetle was much too low for 'large' +leave some menu items out of "invert all" via '@' when their inclusion would + degrade the usefulness of that interface feature +change crysknife from mineral to bone and worm tooth from unspecified to bone +worn meat ring shouldn't cause increased hunger; neither should fake Amulet +worn +0 ring of protection should cause increased hunger if it is the only + source of extrinsic Protection +monster wielding Stormbringer or healer's Staff against another monster would + heal the hero instead of the wielding monster when draining life +change twoweapon feedback from "not a weapon" to "not a suitable weapon" +don't allow twoweapon combat if either weapon is a bow, crossbow, or sling + [later: or arrows, bolts, and missiles (darts, shuriken, boomerangs)] +drum of earthquake feedback reported various things (fountains, thrones, &c) + falling into a chasm but they remained intact because trap creation + had been changed to not clobber such things (so couldn't make pits) +make earthquake which hits a secret door or a secret corridor reveal it +wizard mode wishing for "Amulet of Yendor" had 50:50 chance for true Amulet + or a cheap plastic imitation; recognize "real Amulet of Yendor" and + "fake Amulet of Yendor" to precisely specify either of them but also + take away the 50% chance of yielding a fake one when neither real nor + fake is specified +unpaid globs showed weight info unconditionally outside of wizmode +walking out of tethered-to-buried-object trap condition was supposed to + reinstate punishment but wasn't finding the buried iron ball because + the trap condition was cleared first to indicate escape; result was + attached chain that got dragged around but had no ball attached +when poly'd into a giant and moving onto a boulder's spot, message given was + confused about whether autopickup would occur so could be misleading +random role selection wasn't honoring unwanted alignment(s) properly +if at the edge of the map window, trying to move farther fails but used a turn +hero can no longer wear blindfold/towel/lenses when poly'd into headless form +revamp achievement tracking for exploring Mine's End and Sokoban (by acquiring + luckstone and bag of holding or amulet of reflection, respectively) +throttle long worm growth rate and HP accumulation +poly'd hero was able to zap wands, apply tools, and #rub objects without + having any hands +spellcasting monster got an extra move after casting +allow defining #wizgenesis quantity in the prompt +digging through iron bars from an adjacent pit made a pit on top of the bars +give feedback if controlled level teleport attempt fails because hero is + already on the bottom level and player tries to go even deeper +unseen pet that drowned didn't give "you have a sad feeling" message +prevent ravens from blinding other ravens: /corvus oculum corvi non eruit/ +have ^X provide more information when held or swallowed +display wasn't updating immediately after toggling hilite_pet option +randomly choosing role could lead to crash via segfault +if eel bite attack caused hero to move (killed + rehumanized + crawled out + of water), its grab attack could succeed even if no longer adjacent +specifying a count when picking [part of] a stack of scrolls of scare monster + ignored that count and the whole stack was affected +wizmakemap didn't account for unique monsters and didn't correct monster + birth counts +generate objects (eg. statues) with genocided or extinct monster classes + in special levels, if requested +if the orc-town version of mine town has been loaded, creation of orc zombies + or orc mummies would name them as part of the town raiding orc clan +when punished, involuntarily teleporting and landing within chain range of + attached ball while encumbered worse than burdened could trigger + "remove_object: obj not on floor" panic on hero's next move +update persistent inventory when 'menu_headings' or 'sortloot' options change +update persistent inventory when putting on a helmet causes it to auto-curse +inventory cursing caused by "this water's no good" effect when drinking from + a fountain didn't update persistent inventory window +leashing or unleashing pets wasn't updating persistent inventory window +when the wetness of a towel in inventory changed, persistent inventory wasn't + updated to show that +using wizard mode identify to ID 'all' updated perm_invent window but IDing + specific items--even every one of them--did not +hold_another_object added item to inventory first, then maybe removed and + dropped it, resulting in spurious add and remove perm_invent updates +when hold_another_object fails while hero is swallowed, drop the item into + swallower's inventory instead of onto the floor +hold_another_object (for wishing, horn of plenty, theft while poly'd, other + non-pickup actions giving hero another inventory item) wasn't + reporting change in encumbrance; that would catch up on next turn but + could be off during additional move(s) for current turn +hold_another_object used hardcoded Stressed to limit carrying instead of + using the 'pickup_burden' option for that +transforming a potion by dipping a unicorn horn into it could result in the + potion being dropped due to 'pickup_burden' if encumbrance was already + over threshold before dipping but within it after removal from invent +fix priest created inside temple wall +fix vault guard occasionally encasing monsters in stone +tone down scare monster by excluding humans and uniques +lock the castle chest +revamp amnesia to forget skills instead of objects or maps +when Punished and carrying the iron ball and levitating, hurtling in the + opposite direction of a thrown object didn't bring along the chain +recognize "kirin" as alias for "ki-rin" when asked to create a monster +make unique swallowing monsters (Juiblex) resist magical digging from inside +correctly account for fuel remaining when lit candles are attached + to candelabrum (the previous code would make the game unwinnable if + there were 15 or fewer turns remaining) +praying on an unaligned altar outside of Gehennom behaved like an ordinary + prayer; make that always fail +tribute (Discworld snippets) typos, in book order rather than fix order: + Sourcery passage #4 "the moment the words were out of your mouth" -> + "the moment and the words out of your mouth" where "were" didn't + belong and awkward phrasing because of it caused "and" to be removed + (would be much clearer if optional comma after "moment" was included) + Moving Pictures passage #10 initial single quote should be double, + #12 "or" -> "of", #14 second instance of "megalomaniac" misspelled + Lords and Ladies passage #5, near end add missing opening double + quote, passage #6 first footnote, insert omitted "be", passage #7 + last paragraph, "to" -> "be" + Men at Arms passage #1, italicize /for/, passage #2, insert omitted + word "had": 'it was /fate/ that _had_ let Edward', #9, fix name typo + "Noddy" -> "Nobby" + Interesting Times passage #1, italicize several words + Feet of Clay passage #1, second "does not need" -> "doesn't even need" + Hogfather passage #7 missing initial double quote for "Oh, just ...", + also #7 insert missing "you" into "Why are you feeling [...]" + Soul Music passage #1, italicize /feel/, #8, "fossile" -> "fossil" + Jingo passage #2 "Vines" -> "Vimes", "profferred" -> "proffered", + missing opening single quote on second sentence of Lord Downey's + line, passage #11 both in footnote: "genious" -> "genius", + "was, oddly enough, was one [...]" -> "was, oddly enough, one [...]" + The Fifth Elephant #1, italicize /always/, #9, "dublet" -> "doublet", + #12, fix name typo, "Vines" -> "Vimes" + The Truth #1, italicize several words + Thief of Time #2, "gold starts" -> "gold stars" + A Hat Full of Sky passage #9 "though" -> "thought" + Death quotes #29, "metaphore" -> "metaphor" + various, including Death quotes: use two spaces to separate sentences +unicorn corpses and wraith corpses could be sacrificed even if "too old" +hero polymorphed into a hider and hiding was not unhidden when teleporting +impose tighter restraints on 'summon nasties', both for spellcasting monsters + and post-Wizard harassment +prevent swallowing monster ending up in a solid wall if it killed vault guard +fix attached ball getting deallocated if swallowed, going down into a pit, + and saving +level compiler creates correct novel with supplied name +for farlook, describe water in the castle moat and in Juiblex's swamp as moat + and as swamp, respectively, rather than just as "water" +make hezrous emit poison clouds when they move +make vrocks emit a poison cloud when they flee +stepping from one type of terrain to another was triggering an unnecessary + status update +make shriekers summon baby purple worms if purple worms would be too tough +make non-tame (baby) purple worms eat corpses off the ground +make baby purple worms attack shriekers +make hero polymorphed into baby purple worm warned against shriekers +confused scroll of light summons tame cancelled lights +potions of hallucination can give enlightenment +add a small chance of surviving food poisoning +deliberate level teleporter activation ignores magic resistance +auto-id scroll of remove curse when a known buc-state was changed +demon lords hate Demonbane +pets avoid eating shapeshifter corpses unless starving or nearly feral +blessed scroll of teleportation gives a single controlled teleport +allow opening a tin without interruption if slimed +tell player when wielding a different weapon toggles off dual-wielding +object taking erosion damage might give feedback message when out of view + or not give such when in view, depending on stale value of 'bhitpos' + [cited case assumed message came from drowned monster's dropped + inventory when out-of-view ice melted] +it's possible to wish for tins of the Riders in wizard mode; eating one is + fatal but if you're life-saved or decline to die, the game crashed +revival via undead turning of corpse carried by hero said "your corpse + comes alive" even when revived monster was undead +prevent searching or waiting next to a hostile monster if boolean option + safe_wait is on - override with 'm' +prevent searching or waiting if hero is slimed, stoning, strangled, + or deadly ill if safe_wait is on - override with 'm' +allow random mimics to show up mimicking more furniture than just stairs +scatter exploding bag of holding contents instead of outright deleting them +male hero poly'd into nymph chooses charm vs seduce message based on being + male rather than on all nymphs being female but charm message was + using hardcoded pronouns She,her for target monster--wrong for male + target and noticeable if " finishes taking off his suit" is given +hostile monsters with a ranged attack try to stay away from melee range +allow displacing peaceful creatures +unicorn horns don't restore attribute loss anymore +when a shop is changed from food to health food, change room type to match +wish parsing of things containing monster names would accept all supported + alternate spellings if they occurred at the end ("corpse of mumakil") + but only some when they occurred elsewhere ("gray-elf corpse" worked, + "mumakil corpse" yielded "does not exist") depending upon name length +couldn't wish for werecreature corpse or tin because monster name lookup + always matched the beast form which is flagged no-corpse; switch to + human form for "were" +wishing for werecreature figurine always made one that created the monster in + beast form if activated; allow "human were" to explicitly + specify werecreature's human form (for corpses and tins as well as + figurines); override the restriction against human figurines for that +wishing for "royal jelly" yielded "lump of royal jelly" as a special case, but + other 'of' items such as "clove of garlic", "sprig of wolfsbane", or + "piece of cloth" didn't allow using their post-of words as shorthand +monster or object detection found semi-dead vault guard at <0,0> while + traversing fmon list; monster detection gave misleading feedback + (blank map instead of 'strange feeling') if there were no other + monsters on level; likewise object detection and guard's minvent +squadprob[] in mkroom.c was defined with 5 elements but initialized only 4 + resulting in giant ants sometimes +allow nurses heal attack when wielding a non-weapon/weaptool +if riding or levitating, hero could apply bullwhip downward to pull up things + from underwater or lava; feedback implied the item was on the surface +some monster code was checking whether pets or engulfers were eating green + slime by checking for green slime corpse instead of glob +change light radius of stack of candles to square root +could get redundant "mon hits other-mon" messages when mon wields an artifact +failed untrap while mounted that moved hero onto the trap would leave steed + with stale coordinates, triggering warnings if 'sanity_check' is On +when digging a pit results in it being filled by adjacent pool or lava, any + objects at the spot weren't subjected to water or fire damage; + also, riding hero's steed wasn't subjected to immersion either +after "double trouble", cloned Wizard would wait until he had suffered some + damage or hero moved into direct view; keep STRAT_WAIT for original + Wizard but avoid that for clones +beyond turn 100000, prayer timeout is longer (scaling with game length) +falling while going down stairs and dropping items due to encumbrance or + punishment wasn't subjecting fragile ones to breakage +objects scattered by an explosion which land on water or lava weren't affected + by the water or lava +change mkclass() to usually honor (always honor for L class) the hell-only and + never-in-hell monster creation flags; no more achi-lich in the Castle + (nor master lich there unless demilich gets a potion of gain level) +thieving monster could be killed while hero was removing armor, triggering + warning "stealarm(): dead monster stealing" when taking-off finished +petrifying a long worm and then reanimating it handled tail incorrectly; + with sanity_check On, X coordinate of head segment was reported as 0 +attempting to read a novel while blind reported "you can't read the mystic + runes" like for a spellbook; use "you can't read the words" for novel +don't let life draining reduce a monster's max HP below its level + 1 +report " expires" rather than " dies" if polymorphed hero kills a + non-living monster (golem, vortex) with life drain (vampire bite) +allow hero in silver-hating form to ring the silver bell but only if on/over + the vibrating square +reading the Book of the Dead while blind is allowed; doing so gives + "you turn the pages of the Book of the Dead" and the type of item + becomes discovered, but the object wasn't being flagged as 'dknown' + so if not seen yet it remained "a spellbook" in hero's inventory +reading cursed Book of the Dead while blind gave feedback for sighted hero +reading non-cursed Book of the Dead after prepping with the other tools gave + a message referring to those as "artifacts" if either of them were + cursed; those unique items aren't artifacts so use "relics" instead +zapping a line of boulders with striking or force bolt was updating 'couldsee' + but deferring 'cansee', resulting in seeing the first boulder fracture + and only hearing that happen for the others despite coming into view +the default engraving, epitaph, and bogus monster inserted by 'makedefs -s' + (3.6.6 fix for empty source data file) lacked terminating newline, so + when the corresponding file wasn't actually empty its first line ended + up concatenated; default portion of the bad combined entry would be + decrypted properly but the portion from the file's first line wouldn't +if the Wizard of Yendor fled up the stairs on level 1, the game would behave + as if he was still in play, but he wouldn't be on migrating monsters + list so couldn't be brought back and wouldn't appear on Plane of Earth + (stale non-zero value for context.no_of_wizards) +if a mind flayer's psychic blast targeted a hidden monster, feedback named + the monster but it wasn't brought out of hiding +hero poly'd into a mind flayer who used #monster to emit a psychic blast was + able to harm mindless monsters with it +some hero attacks that should have gotten a skill bonus or penalty didn't +change internal name of " venom" to "splash of venom" +some operations that made sense to handle venom ('D', scroll of identify, no + doubt others) ignored it because venom is suppressed from packorder; + matters for wizard mode or for normal play that loads wizard bones +singularize "splashes" to "splash" instead of "splashe" +treat slinging gems and tossing or slinging stones at unicorns as attacks +give rot-away timer instead of revive timer to corpses of cancelled trolls +switch revive timer to rot-away timer if a troll corpse gets cancelled +uncancel an ice troll if its corpse is put into an ice box; give corpse a + revive timer if later taken out +splitting a stack of candy bars gave new wrapper text depending upon the + obj->o_id value assigned; keep existing text for both halves of stack + (side-effect: separate candy bars usually won't merge anymore) +describing tin variety (deep fried, pureed, &c) relied on the 'contents known' + flag but object identification wasn't setting obj->cknown for tins +wizard mode #wizintrinsic: setting Levitation wouldn't block Flying as + intended because the check for that was being made too soon +chatting to the quest leader in wizard mode with sufficient experience level + and insufficient piety, player is asked whether alignment should be + boosted; answering 'n' resulted in being prompted a second time +end of game inventory disclosure passed an inappropriate argument to the + inventory display routine; not noticeable for tty and curses, + noticeable but not harmful for X11, and slightly harmful for Qt +turning into slime rendered hero as slime one turn too soon +avoid potential infinite loop if hangup occurs at ring "right or left?" prompt +randomize the turns where accessories and extrinsics affect nutrition +handle being interrupted by approaching monsters more consistently +if hero attacked a peaceful monster, some other peaceful monsters with humanoid + shape (minotaur, zruty, perhaps others) that witnessed it but which + shouldn't be capable of normal speech expressed their surprise audibly +make gasp/exclamation message from peaceful monsters be more verbose to + indicate which monster is doing the gasping or exclaiming +when make was invoked with -j makedefs instances could end up running in + parallel and could trample on each other's temp files; default to + using mkstemp(); allow a port runtime library implementation that lacks + mkstemp() to define HAS_NO_MKSTEMP to revert to the old behavior; + provide a work-alike mkstemp() implementation for windows visual studio + in mdlib.c so there is no requirement to define HAS_NO_MKSTEMP there +make piranhas faster and give them extra bite attack +fire sources can ignite candles, lamps, and potions of oil +for multiple drop ('D') with menustyle traditional or combination, if the only + object class player picked was '$' then it operated on all classes +small monsters could seep through their shirt +don't snuff brass lantern when it's hit by water unless it is submerged +when reporting that hero can't repair a chest's broken lock with key/pick/card + just describe the base item without BUC, user assigned name, &c since + "You can't repair a chest's lock with an uncursed key." implicitly + suggests that you might be able to do so with a blessed or cursed one +pre-populate teleport destination prompt with travel destination +ghosts cannot be renamed +tossed upwards objects got two times half physical damage reduction +monster xorns could pass through iron bars but not eat them; monster rock + moles could no neither; now they can eat bars when adjacent and will + do so if the bars are blocking their path +hero poly'd into rust monster could implicitly eat bars when adjacent by + trying to move there, now when in rock mole form too; in xorn form + can explicitly eat them via 'e' after moving onto their spot +monster hiding under an egg that hatched was kept hidden +restful sleep regenerates hit points +restful sleep gives a warning message few turns before you fall asleep +attacking non-adjacent concealed mimic by applying a polearm would make the + hero be stuck to that mimic +hero could break a wand ("raising the wand high over your head, you break it + in two") even if hands were welded to a two-handed weapon or to a + one-handed weapon and also to a shield +if a monster threw a cockatrice egg at the hero but hit and petrified another + monster, the hero would get credit/blame for killing it +since ki-rin look quite a bit like unicorns, make them be more like one: + allow them to use their own horn to cure themselves; remove M1_ANIMAL, + change MS_NEIGH to MS_SPELL, add MR_POISON, use horse body parts; + they're still 'A' rather than 'u' and don't care about gems +wand/scroll of create monster or bag of tricks that makes a new monster which + can be seen or sensed becomes discovered, but was doing so even for a + concealed mimic seen as furniture or an object +'showscore' could be used to determine how much gold was inside a container + whose contents were unknown +wizard mode (only way to get timed flying): if levitation and flying time out + on same turn, player was told "You have stopped levitating and are + now flying."; status line wasn't updated to remove stale Fly condition +throwing or kicking a shop container (that's light enough to move) made the + hero pay for any gold inside, then didn't refund that amount if the + container landed inside the shop +try to fix message sequencing for tame golems that "roast/rot/rust in peace" +autodescribe when moving the cursor was erroneously honoring MSGTYPE=stop + and potentially delivering sounds +reduce the number of "seeXYZ" commands by renaming some: #seenv -> #wizseenv, + #seegold -> #showgold, #seespells -> #showspells, #seetrap -> #showtrap +when saving while punished or game ends while punished, handling for ball and + chain might access freed memory with unpredictable consequences +brown pudding monster hitting another monster with decay attack corroded armor + instead of rotting it + -> omitted 'n' prefix and M-digit for number_pad mode, + and ^A/re-do was suppressed due lack of obsolete '#define REDO' +add missing key binding support for rush.numpad; default is M-5 for numpad==1 + or plain 5 for numpad==2 where behavior of 5 and M-5 are swapped +allow monsters to use wand of undead turning to revive corpses on floor + in some situations +selling a container to a shop for gold leaves any contents that the shop + doesn't ordinarily buy and sell owned by the hero, but selling the + container for credit resulted in the shop taking possession of such + contents without giving any additional credit; mark out of place + contents 'no_charge' so that hero can reclaim them without buying +add some new demonic and angelic maledictions +when fire damage dried a wet towel, it would never reduce the wetness to 0 +when water damage wet a towel, the new wetness might randomly become less +make Death revive earlier, and all the Riders after 67 turns at latest +when protection from shape changers begins, force mimic out of concealment + even if hero can't see its location; for locations that can be seen, + don't make double-trouble Wizard concealed as another monster--or pet + temporarily mimicking something while eating mimic corpse--fall asleep +best possible armor class reduced from -127 to -99; worst from +127 to +99; + charged or enchanted individual items also capped at +/- 99 (affects + wizard mode wishing, negligible effect on normal play) +fix several inconsistencies for objects at hole locations +make repeat (^A) work when bound to some other keystroke +if a prefix key was bound to some character which ordinarily ran a regular + command and that command wasn't bound to another key, typing the + prefix followed by a non-movement key behaved strangely: instead + of reporting "invalid direction" it would run the other command + (actually depended upon relative order of prefix's new and old key) +reqmenu (the request-a-menu prefix supported by a handful of non-movement + commands) could be bound to some key other than 'm' but it only + worked if the new key was also a movement prefix +when telepathically sensed pet ate a mimic corpse and temporarily took on + a different shape, you were told that you sensed it changing into + something but the map continued to show its true shape (telepathy + overrides mimic hiding); give a different message in that case +when a pet ate a mimic corpse and tried to temporarily look like a sink it + ended up looking like a throne (terrain type SINK == symbol S_throne) +have dowhatdoes ('&') catch up with '?i' to describe ^A, ESC, and movement + prefix keystrokes correctly instead of reporting "no such command" +give barrow wights a cold touch +for configuration using external compression on save files that applied a name + suffix, 'selectsaved' (restore via menu) couldn't handle any which had + been manually uncompressed, mangling file name trying to remove suffix +an empty lamp hit by fire reported "the oil lamp catches fire" (but at least + didn't light) +spells that require a target spot rather than a direction (like skilled + fireball) would not let a blinded hero target his/her own spot, with + feedback stating hero failed to hold location sufficiently in mind; + when not blind, such spells left autodescribe feedback for target spot + in the message window while the spell was being performed +prevent wish request "death wand" from matching Death monster and producing a + random wand instead of a wand of death +grammar bit: "you hear a [AEF] note squeak in the distance" (should be "an") +during engraving, spaces were counted instead of non-spaces [later: affected + code is gone, removed when engraving was converted into an occupation] +when an explosion scatters objects, make any that fly over sinks stop there +output message when changing fastmove mode while cursor targeting +messages when Minetown watchmen become angry could report "you see an angry + guard approaching" even if he was invisible and hero can't see invis +when autopickup is on but disabled due to being inside a shop, have ^X say so +don't force fake player monks to always be male +it was theoretically possible to overflow an internal buffer containing + inventory letters by carrying more than 52 separate lit candles and + using the '(' or '*' commands +hero would be blinded and stunned by an Archon's radiance (gaze attack) even + if the Archon was blind, but monsters would not +applying a polearm to attempt to attack a hidden monster would report "wait! + there's a monster hidden there" and display the "remembered, unseen + monster" glyph but only use a turn if polearm wasn't already wielded +key parsing during options processing was inconsistent between OPTIONS=foo:k + BINDINGS=k:foo where k represents a key designation; the OPTIONS form + recognized backslash escape sequences but not M-x meta characters, + vice versa for BINDINGS (most noticeable for menu interaction keys + such as menu_next_page because those can be set via either directive) +when creating a rolling boulder trap, don't place boulder on a path that + starts on or passes over a pit/spiked pit, hole/trap door, + teleport trap/level teleporter/magic portal +remove superfluous "All" from "All foos are already nonexistent." when blessed + genocide tries to remove something which has already been genocided +"#dip into -" produced a scrambled message: + You mime dip intoing something. +similarly, "#rub the royal jelly on -" produced + You mime rub the royal jellying on something. +mounted hero falling out of saddle shouldn't hit ground and take damage when + levitating or flying (if done without steed's help) +avoid "obj not free" panic if monster kills itself by reading scroll of earth +attempting to throw a partial stack of gold at self was prevented but left + the partial stack in an extra $ inventory slot +quivering a partial stack of gold succeeded and put the partial stack in an + extra $ inventory slot +if player managed to get multiple $ items, all but the last could be moved to + normal letter slots via #adjust and then subsequent #adjust with a + count could split them into even more slots +when a monster on the far side of a closed door opens it, sometimes the hero + was told about the monster without it being displayed on the map +also show extended command name when showing what a key does in help +poly'd hero who exploded when attacking a monster didn't wake up other + monsters in the vicinity; when attacking thin air, hero's explosion + woke other monsters within different radius than same monster's would +troll corpse revival was inhibited by hero wielding Trollsbane; change that + to being killed by Trollsbane instead (wielded by hero or by monster) +statues representing petrified creatures on Medusa's level might be from + monsters who change form (golems) when hit with stoning damage +attempt to make corpse or statue of a named player character would yield that + of a random monster instead when 'record' was empty; could result in + statues of non-stonable creatures in cockatrice nests +homemade tin of very low nutrition corpse gave more nutrition than the corpse +magic mapping performed while engulfed or underwater would display whole map + but then not switch back to the engulfed or underwater restricted view +#overview used hardcoded bold and inverse for highlighting; switch to the + 'menu_headings' option value so player has some control +for menustyle:full, the 'A' menu choice to auto-select everything now only + does so if no other choices have been picked; when any have (object + class or BUCX state or both), it auto-selects every item that matches + those choices (so still skips the second menu) rather than every item +using travel to move one step diagonally where that step was blocked by being + too narrow to squeeze through stopped travel instead of considering + alternate routes to the destination +turn off input autocompletion for '#twoweapon' since simple 'X' invokes it; + likewise for #wizdetect (^E), #wizgenesis (^G), #wizidentify (^I), + #wizlevelport (^V), #wizmap (^F), and #wizwish (^W); probably ought + to do so for #overview (^O) too but that one still autocompletes +if a branch has only one level (Fort Ludios), prevent creation of any level + teleporters there (level definition doesn't have any but wizard mode + wishing could attempt to place one) +opening/unlocking magic zapped at monster holding the hero will release hold + (zap at engulfer already expels hero); zapping at self has same effect +when riding, allow scroll of remove curse read by hero to affect steed's saddle +the 'scores' option for final top ten display left default values in place if + only some of the three settings were set; 'scores:own' should have + produced '0 top/0 around/own' but ended up as '3 top/2 around/own' +allow 'scores:none' as shorthand for 'scores:0 t/0 a/!o' (player will be told + whether new score made the list but no scores will be shown) +contents of chests, large boxes, and ice boxes are now immune to water damage + unless the container is cursed, same as for oilskin sacks (previously, + chests+large boxes were always immune and ice boxes always vulnerable) +applying an empty brass lantern in an attempt to light it reported "your lamp + has run out of power"; change to "your lantern is out of power" +when swallowed or underwater, player could be told about events (such as a + shapechanger taking on a new form) that the hero sensed but which + were not shown on the screen; treat being swallowed or underwater as + situations which block telepathy, extended monster detection, warning +some rolling boulder trap feedback was inconsistent +change "killed by , while {paralyzed|frozen} by " into + "killed by , while {paralyzed|frozen}" if the killer caused + hero's helplessness +"It looks very angry" would be given if a hero wielding Excalibur or Demonbane + offended an unseen demon lord +Entering a special room, only wake up the monsters in that room instead of + doing a level-wide wake-up +any blessed key was behaving as if was the rogue's Master Key when unlocking + a trapped chest or box +when an unseen non-pet picks up or uses an item, hero loses known/dknown/ + bknown/cknown/lknown memory of that item (so becomes unidentified; in + particular, player won't be asked what to call unseen thrown potion) +when picking up a stackable item, it can be identified by comparing it to + another identical item that is already identified +wishing for a partly eaten wraith corpse yielded "partly eaten food (1) more + nutritious than untouched food (0)" +if PREFIXES_IN_USE was defined (and VAR_PLAYGROUND forces it to be) when + COMPRESS was also defined (external save and bones file compression + via fork()+exec()), the file name buffer in docompress_file() wasn't + big enough so could overflow and trigger a crash +suppress "This corpse takes {delicious|okay|terrible}" if preceded by + "You have a bad case of stomach acid" or "Ecch - that must have been + poisonous" +innocuous items like scrolls or eucalyptus leaves did harm when falling on + hero's head after being thrown upward +fighter types who start out knowing all non-magic armor should not know + cornuthaum and dunce cap +prediscovered weapons adjustments: only knights and samurai know polearms; + rangers know launchers (bows), ammo (arrows), and spears regardless + of their race/species; likewise, rogues know all daggers +if the move counter ever reaches 1000000000, end the game +knights get no metal armor penalty for clerical spells +change touch of death from instadeath to maxhp reduction and damage +report cause of death due to touch of death as "killed by the touch of death + inflicted by " instead of just "killed by a touch of death" +report cause of death due to wand/spell/breath as "killed by + zapped/cast/exhaled by " instead of just "killed by " +dying from being level-drained below level 1 killed hero without saying so + and jumped straight to "do you want your possessions identified?" +conflict will now consider your charisma and requires line of sight +boost hit points of some golems +make anti-magic fields always drain max energy +eating magical monsters such as wizards or shamans may give a mild buzz +make exploding spheres create an actual explosion +pets are more careful about attacking monsters at low health +allow killing your quest leader to open the quest +give King Arthur Excalibur +when moving the cursor to examine the map, have '^' move to next trap even if + that trap is displayed with some other symbol (web, vibrating square) +change valkyrie and warrior (valk quest) monsters from chaotic to lawful +change attendant (healer quest) monster from lawful to neutral +quit is not longer bound to M-q +change default value of autopickup to off and color to on +resurrected corpse of mon could end up with different gender from original mon +using a bullwhip to snatch a wielded cockatrice corpse from a monster when not + wearing gloves and without life-saving could trigger "obj_is_local" + panic during final cleanup +make fire-command autowield an appropriate launcher and add fireassist boolean + option to toggle the assistance off +Angels and priests were always described as "the {Angel,priest,high priest} of + " when first two should have been "{an Angel,a priest}..." +shopkeepers can remove pits and webs +perm_invent: when buying shop goods using itemized purchasing while persistent + inventory window was enabled, the prices of unpaid items went away as + soon as any item was bought (actual item-by-item purchase worked ok) +perm_invent: making an engraving which reduced known enchantment of a weapon + or known charge count of a marker didn't update persistent inventory +perm_invent: over-reading a spellbook so that in faded to blank didn't update + persistent inventory to show that if blank spellbook was already known +change getloc fastmove keys in number_pad mode from hardcoded HJKL to the + run/rush movement keys (meta+number) +allow using rush/run prefix key in getloc to fastmove the cursor +avoid "it" in messages "Wait! There's an it hiding under !" (hero + moving) and "It was hidden under !" (unseen monster moving) +don't extinguish burning objects when engulfed by a fire vortex +allow wishing for a novel via description "paperback book" (previously only + worked when specifying "paperback spellbook") +deal with gold leaving a shop via scatter() +defer encumbrance check during polymorph to new man; newman() -> redist_attr() + -> encumber_msg() could report change in encumbrance that immediately + became obsolete if polyman() subsequently restored old attributes +fix heap-use-after-free when attacking monster with potion +for "a" vs "an", add ukulele and uke as exceptions for "an u" +add new extended command #retravel +remove special doinv key, functionality was equal to BIND=0:inventory +some monsters should not have been scared of bugle playing +monsters that drowned would never leave a corpse (holdover from decades ago + when it wasn't possible to recover anything from a water location) +give alternate message if hero is blind when throne gives "your vision clears" +monster wearing an alchemy smock was only getting poison resistance from it, + not acid resistance; give both properties, just like for hero +in wizard mode, knowing teleport away spell resulted in ^T always attempting + the spell instead of teleporting on demand +describe a couple of isolated moat spots on Samurai quest home level as water + rather than as moat +crawling out of water to avoid drowning didn't work as intended when trying + to move diagonally through a tight squeeze +in wizard mode, polymorphing into hero's role monster in order to revert to + normal form would complain about missing light source if hero was + changing back from the form of a light-emitting monster [didn't affect + normal play because role monsters are invalid polymorph targets there] +revise a 3.6.1 fix: if a spellbook which is being read becomes cursed, always + stop reading: "The slams shut!" and set book->bknown +concealed mimic could trigger sanity check warning "mimic concealed as an + object despite Prot-from-shape-changers" if hidden as "strange object" +cancelled shape changer would become uncancelled if saved and restored (even + just leaving its level and then returning) +don't include time spent suspended in background (^Z) or in shell escape (!) + in the total elapsed time recorded to xlogfile +if a monster is starting to turn into green slime, eat the corpse, tin, or + egg of any creature that might polymorph into a fiery monster to cure + the slime, not just of one of a chameleon +yet another fix for display problems during restore: if game is saved while + hero is hallucinating but that's suppressed because of wielding + Grayswandir, hero is riding, and the steed is on or over an object, + restore will try to update hero's spot when making sure objects aren't + being obfuscated by hallucination, but when displaying the hero there + instead it would access steed pointer before that has been set up +resistances gained from worn or wielded items also protect hero's inventory +dwarvish cloaks somewhat protect hero's inventory from cold and fire +non-metallic gloves protect worn rings from shock +message "Oops! food rations out of your grasp!" occurred due to perm_invent + in mid-operation overwriting all of xname's/doname's obufs; fixed by + having hold_another_object() defer perm_invent update til done with + all its args (so fixed as a side-effect of "spurious add and remove + perm_invent updates" above, prior to being reported as #K3401) +similar "The ogre lord yanks Cleaver from your corpses!" due to caching the + result from makeplural(body_part(HAND)) then having a perm_invent + update clobber that; fixed by having inventory display release the + obuf used for each item so that the same one will be reused for the + next item, to avoid churning through the whole pool of obufs +gas clouds are a little random in how they spread out from a point +Izchak occasionally stocks wands/scrolls/spellbooks of light +data tracking for #overview was mis-using u.urooms[] and after being in a + situation where hero was in multiple rooms at once, visiting other + levels might flag unvisited rooms as having been visited +special damage attacks by the Riders and by fatal-illness inflictors such as + Demogorgon did no damage against other monsters, only against the hero +using obj->o_id to control 'random' behavior of a helm of opposite alignment + could potentially be controlled by player when wishing for such +obj->o_id might be set to invalid value 0 when a partly used up stack had a + dummy copy added to a shop's bill or when a bones file was loaded + (in theory that could happen on any system but in practice it could + only happen on a configuration that uses 16-bit ints) +if a Rider or displacer beast swapped places with a single-segment long worm + the segment co-located with the head wasn't moved with that head; + if sanity_checking was enabled a warning could be triggered: + mon (000000) at seg location is not worm (123abc) +blessed scroll of remove curse read while confused blesses or curses any + uncursed items in inventory, but if hero was dual-wielding and the + scroll cursed the secondary weapon, that would be dropped and further + object traversal would process items on the floor at hero's spot + instead of the rest of inventory +can now use m to try to move to an adjacent boulder's spot without + pushing it; hero poly'd into a giant or a tiny creature or carrying so + little as to be able to squeeze there will succeed, others will fail +breaching a shop wall, using locking magic to put a door there, then unlocking + that door yielded a situation where subsequent shop damage repair + produced invalid map data which resulted in an impossible() warning + about "wall_angle: unknown" during map display; similar for a vault + wall if it's the spot where the guard arrives to lead hero out +if vault guard arrives on a boulder in a breach in the vault wall when coming + to lead the hero out, smash that boulder into rocks so that the hero + won't try--and fail, because the guard will be in its way--to push it +when vault walls are repaired, destroy any rocks or boulders at their spots +melting ice timer could persist after the ice was gone from digging or from an + exploding land mine +using 'F'orcefight against iron bars while wielding something breakable could + yield erratic outcome because non-deterministic breaktest() was being + called twice and could yield results that conflicted +have applying a polearm give feedback similar to 'F' for melee weapon when + attacking a wall or boulder +if weight_cap() ever returned 0 (which probably can't happen), using #untrap + to pull a monster out of a pit would trigger a divide by 0 crash +avoid "you now detect it where the vampire bat was" when a vampire shifts from + a bat seen with infravision to an unseen fog cloud +if an artifact gets created as a random treasure drop and then deleted because + it is too big to include with a small corpse, explicitly uncreate it + instead of just discarding it so that it is eligible for use later +when creating random contents for a container, explicitly exclude artifacts + (already implicitly excluded because randomly generated artifacts are + all weapons and containers don't start with any weapons in them) +don't give lance or mattock as starting equipment when creating soldiers +fixup for the insect "legs" (some extraneous walls inside solid stone) on the + baalz level didn't work as intended if that level was flipped +handle flipped level when fixing up the baalz level "eyes" too +prevent normal monster activity from picking up the mines' luckstone or the + Sokoban amulet/bag before hero has done so; relying on scare monster + and/or engraved Elbereth wasn't sufficient to guard the Sokoban prize +proceed a little further into dochat() if hero is deaf +stacks of 1 to 49 gold pieces weighed 0 +the chance for #untrap to free a monster stuck in a web was very unlikely + unless hero was poly'd into spider form; make it less hard +if #untrap monst-from-web failure happened while hero was standing on a spot + where a new web couldn't be created (furniture, grave, magic portal), + the expected " remains entangled" feedback wasn't delivered +if hero is wearing an amulet of magical breathing and polymorphs into a fish + or sea monster, don't lose health for turns spent out of water +fix up some "the" handling for monsters whose type name is upper case to avoid + "Uruk-hai is healthy for a statue", "You can't polymorph into Oracle" +controlled polymorph would turn hero into new man or woman if player asked to + become a unique monster of the same race (so usually human) instead of + being told that polymorphing into the specified form wasn't allowed +assigning a fruit name that matches the name of an artifact which doesn't use + any "the" prefix could yield messages showing "the Artifact" when + dealing with the artifact rather than fruit: "You are blasted by _the_ + Excalibur's power!"; didn't impact basic inventory formatting +selection of random engravings, epitaphs, and hallucinatory monster names had + the same problem that rumor selection used to have: entries which + follow longer than average lines are most likely to be chosen and + ones which follow shorter than average lines are least likely; use + same workaround as for rumors: pad the shortest lines; result isn't + uniform distribution but is better (tradeoff vs size; see makedefs) +make selection of random rumors, engravings, epitaphs, and hallucinatory monst + names have uniform distribution by handling long lines specially +when filling a special room with monsters, if one that can come in groups got + picked the group could spill to outside of the room +extend 3.6.1 fix to explicitly use name of unseen shopkeeper instead of "It" + in various shop related messages (ones issued outside of shk.c) +fix some inconsistencies with applied bullwhip vs monster +polymorphing while wearing an amulet of strangulation from a form that wasn't + vulnerable to one that was gave wrong message ("still constricts") +for accessibility reasons, give a message when monster teleports and + when a monster is created during gameplay (for the cases that + did not have their own custom message) +if a gremlin stole intrinsic 'see invisible' the map wasn't updated properly +mark some messages as urgent ("You die*.", having equipment stolen, being + caught in a magical explosion) +if a leashed pet changed name (#name m) or an unnamed pet changed type + (polymorph or grow-up) and perm_invent was On, persistent inventory + display didn't get updated to show the leash's changed information +attack feedback when using a bullwhip said "swing"; change to "lash"; + use "lash" for hero hitting with wet towel too +attack feedback for monster using polearm when adjacent said "thrust"; change + to "bash" +apply runmode delay to multiturn actions, not just running +if a giant carrying a boulder was on ice that melted, it could be killed + twice, first by drowning, then by boulder filling the resulting pool + when it dropped inventory before being removed from the map +allow fire-command to automatically use a polearm, if wielding it +make '$' command also count gold carried inside containers +fleeing leprechauns bury their gold after teleporting +allow #tipping container contents directly into another container +when one leg is wounded, have ^X report which (already used plural if both) +wand of probing used on steed ('z >') didn't include wounded leg(s) feedback +getting wounded in one leg when the other was already wounded miraculously + healed old leg and kept longer of their recovery timeouts for new one +when parsing config file entry "BINDINGS=key1:cmd1,key2:cmd2,key3:cmd3" allow + keyN to be either a naked comma or backslash+comma instead requiring + that comma's numeric value be used to bind comma to a command +when two or more shops share a wall and hero uses Passes_walls to carry an + unpaid item from inside a shop into the shared wall, it could yield + impossible "unpaid_cost: object wasn't on any bill" when examining + inventory if the shop code picked wrong shopkeeper to determine cost +when two or more shops share a wall and hero uses Passes_walls to carry an + unpaid item through the shared wall into another shop, theft of that + unpaid item from the first shop wasn't noticed +redo the unpaid_cost fix to handle shop items inside hero-owned container +flyers shouldn't fall on arrival when going down holes or trap doors +change movement keys and some special keys into extended commands +"WHAMMM!!!" feedback when kicking a door suggests noise so if hero is deaf an + alternate message should be given +fix typo in message shown when hero sees a monster's wet towel become drier +for hero with slippery fingers, enlightenment reports "slippery fingers" or + "slippery gloves" but self-probing described it as "slippery hands" +when hitting with wet towel causes it to lose some wetness, defer "your towel + dries" until after the hit message +do some extra damage when hitting an iron golem with a wet towel +when already at level 30 and gaining another level--which doesn't increase + level further but does add more HP and Pw--throttle the increases +don't stop running when next to a peaceful, unless it blocks the way +mindless monsters shouldn't cringe stepping on squeaky boards +falling down a hole or trapdoor will cause damage proportional to fall height +stinking gas clouds block line-of-sight +covetous monsters will teleport to downstairs or upstairs to heal +have fake player monsters use verbalize instead of pline when reacting to chat +fix mention_walls distinguishing unseen walls from solid stone +don't push unknown boulders when moving +in flush_screen, reorder the code slightly to complete the bot() and timebot() + calls prior to the window port call to place the cursor on the hero +magic traps can toggle intrinsic invisibility +Death attacking a monster does drain life attack +add unique Rider revival messages +don't dereference NULL u.ustuck in dobuzz() when hero has been swallowed +monsters should growl even if you can't hear it +give a sound effect message when thrown item lands in water or lava +don't show rusting of items that land in water +the water used on the Plane of Water stops thrown or kicked items +looting will do #force if you could do it and the container is locked + and you didn't have a tool to unlock it +use silly names for rays (such as breath weapons) when hallucinating +zombies groan instead of being silent +martial arts users, sasquatches, and heroes wearing kicking boots can + no longer miss a monster completely with a clumsy kick +knights get no caitiff penalty against undead +candy bars are bright blue in text mode +towels weigh more than blindfolds +knight quest home level contains some saddled warhorses +allow creating unhidden traps in special levels +reading magic marker shows the specific red ink color +imps and other creatures cussing hero wake up nearby monsters +make ravens oviparous +thrown items can get stuck in webs +engraving with Fire Brand burns the text on the floor and does not + dull the artifact +make looting less tedious by getting rid of a y/n prompt making the command + go directly into the loot-in-out -menu +always give a message when monster changes form via polytrap if seen +illiterate hero receiving a spellbook from their deity gets the spell shoved + directly into their mind instead +adjust levels of sleep, confuse monster, and charm monster spells +replace monk starting sleep spell with confuse monster +chargeable rings have a chance of getting charged when hit with electricity +flint and hard gems break less often when thrown +hobbits getting a sling also get some ammo for it +elves and rangers get alignment penalty for cutting down trees +casting a forgotten spell uses some random amount of power +heroes starting with a spell have at least one level one spell, and + have just enough power to cast it +huge monsters and pit fiends get easily out of pits +give a message when a trapped monster frees itself from some trap +change kitchen sink glyph to a white { +killed wood golem has a chance to also drop small shields, clubs, + elven spears, and boomerangs +discovering an object on first turn with persistent inventory enabled might + not update inventory info for that item (autopickup a blank scroll + or spellbook and read it as first action; it becomes discovered but + will still be shown as if undiscovered until next inventory update) +most traps now require touching the floor to trigger +if a lit potion of oil on the floor was launched by an explosion and it hit + and killed the hero via missile damage rather than its own explosion, + it could trigger an "obj_is_local" panic when end of game cleanup + tried to extinguish it as a light source +place_object() validated coordinates after using them to index level.objects +killed rope golem may drop leashes, bullwhips, and grappling hooks +killed leather golem may drop leather cloaks, and saddles +using magic portals stuns hero for a few turns +using level teleporters confuses hero without teleport control for a few turns +clear obj->bypass for buried objects [a giant on ice triggers a fire trap, + inventory is subjected to burning and surviving objects have their + bypass bit set, giant is killed by fire trap and drops a boulder and + other inventory, ice is melted, boulder plugs resulting pool burying + rest of giant's dropped inventory, subsequent sanity checks report + that there are buried objects which are 'flagged bypass'] +give Sunsword as starting gear only to lawful Angels; since Demonbane has + become a mace and Angels only get swords, they won't start with it +for #knownclass with menustyle=Traditional, allow player to ask for `a even if + no artifacts have been discovered yet, same as `; + likewise for `u to ask to see unique items +reduce eucalyptus leaf nutrition to 1 +life-saving might increase max HP; if level drain triggers that, don't let max + HP go up because it confuses healing for monster wielding Stormbringer +HP recovery and/or max HP boost from eating royal jelly didn't perform a + status update to show the change +if poly'd hero is hiding under food and eats or #offers that food, stop hiding +hide-under monsters who can be turned to stone aren't able to hide under a + cockatrice corpse unless there is something else present but make sure + that the other items aren't all more cockatrice corpses +don't stop travel when going past a closed door (eg. when traveling along + a room wall) +some monster corpses can now convey temporary acid or stoning resistance +fix travel getting stuck oscillating between two locations +kicking a trapped chest and getting the exploding chest result destroyed items + at the hero's location rather than the chest's location; because of + that it left the exploded chest intact +it was possible to destroy a Rider corpse with an exploding chest +when teleporting, don't consider pits/spiked pits/trap doors/holes as unsafe + destination locations if hero is levitating or flying +try to avoid locations with engraved Elbereth or scare monster scroll when + creating new monsters or picking teleport destinations for monsters + who are susceptible to those +be more flexible when wishing checks for artifact name matches; now allows + "firebrand" or "fire-brand" to yield "Fire Brand" +exclude unique monsters from pacification when untrapped from web +ask to kick a door open, if it's locked and you don't have unlocking tool +give a message when stinking cloud is created on top of hero +when being life-saved prevents the hero from moving again during current turn, + avoid logfile annotation "while helpless" if hero dies a second time +if drinking from a fountain randomly gave the 'detect monsters' effect but + there were no monsters on the level then there was no feedback +object detection always showed a mimic imitating a statue as a tengu even if + it had information available about some other type of monster +avoid "the Lord Surtur's corpse glows iridescently" when shk_your() or the() + is applied to the corpse of unique monster with a personal name +restoring while attached ball or chain is on floor in a breach of a shop wall + could have it be moved out of wall gap as that gets repaired, then + might trigger an impossible about being positioned too far from hero +don't try to catch up for lost time for shop damage repair in restdamage() + called from getlev(); let normal shopkeeper movement take care of it +shop wall repair that was delayed because the hero or a monster was an + obstacle in the gap at repair time might not be displayed as wall + once the obstacle moved and the repair eventually took place +putting objects into a container with menustyle=traditional and then taking + them back out with #tip would result in complaints about obj bypass + bit being set if sanity_check was On +when drinking or dipping, allow the 'm' prefix to be used to skip asking + about fountains and pools +calling real or fake Amulet something could give away information about them +throwing gold while inside a purple worm would yield "The gold disappears + in the the purple worm's entrails." (note doubled "the") +inventory #adjust for !fixinv, after picking 'from' slot the prompt for 'to' + slot was supposed to include the next letter beyond those in use as + a candidate for destination but an off by 1 error only showed a-x + where x is last letter used (despite that, y could still be picked) +with two-weapon combat or Cleaver attacking multiple targets, hero kept going + with next attack after being paralyzed by passive counter-attack +trap detection could falsely find trapped secret doors; those can't be trapped + due to details of how they use overlaid fields in the rm structure +for force-fight against edge of level, report "you harmlessly attack unknown + obstacle" rather than "you have moved as far as possible" +using wizard mode ^V in endgame to return to previously visited Plane of Water + now gets the same air bubbles back instead of a replacement set; + likewise for clouds on Plane of Air +on tty at least, "version incompatibility for save/123xyzzy" was invisible: + a blank message of appropriate length followed by --More-- +fix a pair of off-by-one bugs when doling out initial characteristics points, + resulting in an unintentional bias toward Str and away from Cha; + negligible effect on individual games but had a minor cumulative + effect across a large set of games +using a marker to write "novel" or "paperback book" on a known blank spellbook + was producing a randomly chosen Pratchett novel; make it fail instead +when a monster killed a pudding and it left a glob, that glob might not be + displayed on the map (wasn't an issue for killed-by-hero case) +if player gave a subset count when removing an item from a container, then got + the pickup_burden prompt and declined to continue, the item remained + split rather be recombined, making it possible to create multiple + stacks of gold inside a container +two-handed weapon message stated "welds to monster's hand" instead of + "welds to monster's hands" +when formatting an object, avoid capitalization of "The" in " named + The " +be less specific when cause of death is "handling a " that + happened to be silver for current game; list it as "a silver ring" or + "a silver wand" rather than "ring of searching" or "wand of locking" +adjust the row placement of copyright and early startup messages so that + aren't partially overwritten by prompts that follow +ball and chain could be accessed after having been freed if bones were saved +early post-3.4.3 tried to fix the "naming artifacts trick" which could be used + to distinguish the type of some undiscovered items, but using a name + that only matched an artifact after capitalization was exploitable +the u.ustuck hierarchy is: swallowed by ustuck, hero poly'd into sticky form + is holding ustuck even if ustuck is sticky, ustuck is holding hero; + but some code assumed that the first two cases were reversed and + could make formerly sticky pold'd hero clear ustuck, leaving hero + swallowed by nothing (u.uswallow==1 with u.ustuck==NULL); that could + cause a crash if u.ustuck got dereferenced +when a vampire gains levels and grows into a vampire lord, change its cham + field (shapechanger base type) from vampire to vampire lord so that if + it revives in base form it won't revert to plain vampire +a migrating long worm that couldn't arrive could be placed at <0,0> while + setting up another migration attempt to the level, triggering + impossible "trying to place long worm tail at <0,0> mstate:8 on level" + (message is confused; it should say "long worm" without tail) +dropping things with 'D' wouldn't merge them with compatible items already at + that floor spot because use of obj->bypass made them seem incompatible +a hero on the quest home level who runs or travels past the quest leader and + gets tossed out of the quest for some reason would keep running on the + far side of the quest portal +allow rush/run over water if wearing discovered water walking boots +putting on water walking boots while underwater (maybe via magical breathing) + and rising to surface wasn't causing the boots to become discovered +flying pets wouldn't target underwater food but if they happened to fly over + such food they could and would eat it +praying on an altar with pet corpse or statue on it can revive the pet +applying a cursed oil lamp can make your hands slippery +valkyries start with a spear instead of a long sword +grid bugs don't have hands +if #wizmakemap was used to generate a replacement level while any shopkeeper, + temple priest, or vault guard from the level was off of it at the + time, the monster's eshk, epri, or egd data became invalid and would + cause trouble if the monster returned to its 'home' level +similarly, if #wizfliplevel was used to transpose an active level while a + vauld guard was maintaining a temporary corridor or while a monster + with eshk, epri, or egd data was off level, that data became invalid +blessed potion of polymorph will prompt user for monster to poly into +out of array bounds access attempt occurred when deciding whether to bounce + if wand or spell zap reached edge of map +if blind hero was challenged by a vault guard, it wasn't possible to see how + to start following that guard out of the vault +make taming via magic harp be consistent with scroll of taming and charm + spell: an angry shopkeeper becomes pacified (but never tamed) +wielding a bec de corbin makes ravens generate peaceful +moving with 'm' prefix allows hero to enter a known pit carefully +rangers always succeed in disarming bear traps, unless impaired +bigroom variant 2 may have ice floor in unlit areas +bigroom variant 3 may have some walls replaced with other terrain +bigroom variant 4 may have two large squares of terrain in the middle +bigroom variant 5 may have patches of ice or clouds +some large monsters can knock back smaller monsters with a hit +change Demonbane to a silver mace, make it the first sac gift for priests, + and give it an invoke ability to banish demons +wielding Giantslayer prevents knockback from larger monsters; likewise for + carried loadstone(s) +scared hostile monster which cannot move away will attack +prevent a fog cloud that has engulfed the hero from moving under closed doors +allow cutting a known spider web with wielded weapon by force-fighting the web +holes and trapdoors have a fixed exit level +recent changes to losedogs() could result in an infinite loop when migrating + monsters try to arrive as hero moves to a different level +when invisible without see invisible you could see your hands glowing red + after reading a scroll of confuse monster and delivering melee hits +greased saddle makes it impossible to mount the steed +if an item-using monster zaps a wand of digging downward on a level that + doesn't allow holes but does allow pits, create a pit and trigger it +no longer override the effect of a new moon by simply carrying a lizard corpse +make explosions burn monster's armor just like they do hero's armor +make healing and extra healing better by upping the average amount healed +lifesaving healing amount depends on the constitution +hitting a monster with a wielded potion hits you far less +pyrolisks get a mundane bite attack +chances of random item being an artifact depends on already existing artifacts +monsters can zap wands of teleportation at hero +piranhas devour corpses +turn on menucolors boolean automatically if any menucolors are defined +blind hero was notified when brass lantern burned out even though it isn't + warm enough to detect that by touch; manually switching the lantern + on or off can be determined that way so still gives on/off message +turn on statushilites automatically if any are defined +change poison instakill to damage with attribute and max hp loss +trappers and lurkers above enfold themselves around and crush their victims, + not swallow and digest +attempting to move up or down when poly'd into a holder and holding a monster + rejected the move; release the monster instead +throwing a non-weapon while engulfed by an ochre jelly reported that the item + vanished into the jelly's "currents" +if a pet gelatinous cube eats a container, treat it the same as when a hostile + one does: the container is destroyed but its contents are engulfed +when breaking a wand of sleep hits the hero with the explosion, don't describe + that as "the sleep ray hits you" +expose fuzz tester to wizard-mode as #debugfuzzer extended command +monsters which cannot move due to boulders or walls try to escape +intelligent monsters see and remember when others trigger traps +random figurines are of harder monsters by 5..10 difficulty points +statues for statue traps are of harder monsters too, but only by 3..6 +monsters can blind you with a camera +lit candles generated by wishing could have wrong light radius +better feedback from detect unseen +make public server admin messages use urgent_pline +cannot kick while squeezed on top of a boulder +room stocking would put multiple items on the same spot +splitting a stack of named, shop-owned objects while perm_invent is enabled + produced impossible "unpaid_cost: object wasn't on any bill." +more consistent feedback if a reviving corpse becomes an unseen monster +improve consistency between applying a key and explicitly opening a door: + if in a pit, you're told "you can't" and no time elapses; if there + isn't any door in the direction supplied, you're told "no door" and + time elapses if you discover the non-door's terrain type but doesn't + if you already knew the type there +if a bones file contained a doppelganger imitating a unique monster, a game + that loaded those bones would end up with that monster counted as + having already been created so it wouldn't be created when the time + for that arrived (the doppelganger would change its shape normally, + not be stuck in the unique monster's form) +if Vlad was lured to a level which allowed bones, he could be present in a + bones file for that level if he was in wolf/bat/cloud form at the + time hero died; getting those bones in another game would flag him + as extinct; if that occurred before entering his level he would not + be created there, leaving no way for hero to acquire the Candelabrum +when mounted hero got hit by an explosion, hero and steed shared resistances +removing an engraving from frost (ie, written with fingers on ice) reported + "you wipe out the message that was written in the _dust_" +orc hero starts with poison resistance but orc monsters lacked that +orc hero has maximum 18/50 strength but hero poly'd into an orc got 18/100 +hero with exceptional strength (18/01..18/100) retained that when polymorphed + into any monster lacking the strongmonst attribute +give hero poly'd into a giant 19 strength instead of 18/100 +wait for a response after displaying wishing help; affects X11 +guardian nagas' constriction attack could never hit because the two preceding + attacks must both hit and those were mutually exclusive: bite and spit +explicitly throwing 1 for non-gold stack of more than 1 and then canceling at + direction prompt left a pair of stacks of 1 and N-1 with same invlet +some attack damage which shouldn't affect shades operated as intended when + hero could see it happen but erroneously affected them when not seen +phrasing of the "you can't" message when attempting to name any monster + defined with a unique name or title sounded strange when rejecting + to remove the existing name without assigning a new one +some instances of using up or stealing shop-owned boulder didn't charge for it +when hero hears an unseen monster reading a scroll, only describe the monster + accurately if hero is not hallucinating and monster is same species + as hero's current form +don't allow monsters to disarm hero with bullwhip if hero is engulfed +teleporting an object out of a shop put it on the shop bill instead of dealing + with robbery +map browsing during gold detection didn't describe fake gold marking traps + when detection was via cursed scroll +if hero's action caused engulfer to expel swallowed hero, it might do so onto + a level teleporter and then have its memory accessed after being + freed when current level was saved in order to load destination level +throwing recoil while levitating could send hero out of shop while carrying + unpaid items, triggering sanity check warnings; once outside, taking + a step other than back into the shop was treated as a robbery +if punished and iron ball was cursed and wielded--so welded to hand--falling + when doors would drop it instead of keeping it welded +if player's run-time config file had OPTIONS=role:Val and the environment had + NETHACKOPTIONS='role:!Val' the hero would be a Val instead of !Val +sleeping or unconscious hero attacked by Medusa would meet her gaze +if a trap killed both the hero's steed and the hero an impossible "dmonsfree: + N+1 removed doesn't match N pending" warning could occur +prevent paralyzed hero from helping nymph or succubus remove worn armor +when identifying items via menu and more than one pass is needed (so when + identifying 3 items and player only picks 1, for instance), issue + --More-- because the next menu might cover up the ID message(s) +slightly more interesting Gehennom filler levels +don't reveal color of potions, gems, or spellbooks that haven't been seen up + close (seeing faraway monster operate on an object counts as up close) +fix freeing a worn object when forced to drop it by falling down stairs +allow setting per-level "temperature": hot, cold, or temperate, currently + only affects some messages +digging is noisy +polymorphing into fire elemental allows you eat flammable items +hitting sleeping monsters will cause them to wake up noisily +demon gating happens more in Gehennom and less outside it +intelligent peacefuls avoid digging shop or temple walls +fix bug making random subrooms never touching the right or bottom + wall of the parent room +if a grave is created with the corpse lying on top (bones), don't find a + corpse or release a zombie or mummy when digging it up +kicking a headstone might summon a ghoul +eating garlic makes nearby monsters flee +giants occasionally get a battle axe or a two-handed sword +give gremlin the property it stole, if possible +'F'orcefighting with a war hammer has a small chance of breaking iron bars +player assigned name for monsters, specific objects, or object types could be + longer than what was intended to be allowed; for 'curses', much longer +very rarely random items are generated eroded, erodeproof, or greased +Nazgul can see invisible +fix a case where punished iron ball yanked hero on top of a monster +slightly randomize amount of items and monsters in the mines +dying in a wall spot (temporary gap or via Passes_walls) shared by two shops + could result in "place_object: \"\" [0] off map <0,0>" warnings +a monster capable of using a polymorph trap to deliberately change form could + do so when trapped in an adjacent web or pit; if that happened, the + monster remained flagged as 'trapped' and wouldn't be able to move +give feedback when some types of damage are avoided due to MC (aka negation) +feedback if a named, shape-shifted vampire reverted to original shape rather + than dying when engulfed could say "Dracula turns into Dracula" +adjust archeologist and valkyrie starting intrinsics +spell of knock can knock back small monsters +protection from shape changers now prevents the Wizard from mimicking monsters +having worn levitation boots removed and destroyed (scroll, monster spell, + dragon breath) and floating down into lava can destroy them twice; + yielded "object lost" panic if program had been built with a debugging + malloc implementation which overwrites the contents of freed memory +ensure that all window interfaces respect flags.silent (suppress terminal beep) +falling into lava, being life-saved, and teleporting out could yield redundant + descriptions of what was present at hero's new location +if hero had passes-walls capability and was at the location of a closed door, + attempting to use 'o' on own spot reported "you don't find anything + here to loot"; change to open door for '.' (or '<'), only loot for '>' +items thrown by monster landing on an altar did not show BUC flash +a chameleon in giant form who gets trapped (bear trap?) while carrying + boulders and changes shape could be killed when dropping them; + shape-change traversal of its inventory would continue after it + dropped everything, possibly resulting in a crash +if hero is engulfed and polymorphs into a monster form which is too big to be + engulfed, make engulfer expel the poly'd hero +give feedback if monster holding onto the hero has to let go when hero polys + into a form which can't be held +prevent hug attacks and touch or engulf attacks for wrap, stick-to, and + digestion damage from succeeding against unsolid targets (ghosts, + vortices, a few others) or against worm tails +wand of speed gives temporary speed, potion gives intrinsic +some monsters (riders, shopkeepers, priests, quest leader) can break boulders +if hero owes shop for a boulder and shopkeeper breaks it, continue to bill hero + for the boulder rather than switching to the resulting rocks +corpse-eating monsters will go out of their way to eat corpses on the floor +warnings via impossible() would be unseen if message suppression via ESC at + --More-- prompt was in effect +wearing the Eyes of the Overworld overrides OPTIONS:blind; breaking the + always-blind conduct by doing that was intended but having permanent + blindness stay cured after removing them was not +change helm of brilliance from iron to crystal so that it no longer needs to + be a special case for metallic armor vs spell casting +fake player monsters in endgame had a 1 in 1000 chance to be given a stack + of 0 gold pieces, eventually triggering an impossible warning (cited + one was "Calculating weight of 0 gold pieces?") +avoid "wall_angle: unknown hwall mode 4" when using #terrain command to + display a spot remembered as a wall but actually a secret door that + has been transformed into an open door while not in sight +it was possible to produce a web at a water or lava location; it would not be + visible but could trap the hero, resulting in drowning or incineration +engraving in an open doorway was allowed, engraving in closed one (presumably + via Passes_walls) was not, but closing the door on an engraving was; + change to allow engraving at closed door location +engraving in a breach in a shop's or vault's wall or vault guard's temporary + corridor would leave the engraving intact after repair/cleanup +if a fire resistant non-fire immune monster wearing a thoroughly burnt wooden + shield got knocked into lava, burning the shield completely yielded + impossible warning "obfree: deleting worn obj" +hangup in wizard or explore mode would result in answering ESC to "Die?" + prompt if that was reached, and since default is 'no' the hero would + be life-saved and the game would try to keep going; if circumstances + resulted in repeat death then the program might get stuck in a loop + instead of exiting [no reports of such, but if it ever happened the + process was probably killed without anyone knowing why it happened] +with OPTIONS=blind (blind from birth), being inflicted with timed blinding + yielded "your vision seems to dim for a moment but is normal now" +avoid sanity_check warning if statue in water or lava gets polymorphed into a + boulder; break it into a stack of rocks if that would happen +werewolf or werejackal howling and purple worm burping wakes up monsters +don't exclude map column 1 from consideration when rloc() picks a random spot + for destination of a teleported monster +covetous monster attacking another monster to acquire special item would not + do so if positioned diagonally adjacent +skip sanity_check handling when current command is ^P, otherwise it might + re-trigger and show new sanity warning every time when set for + line-at-a-line feedback +applying a cream pie (always) or lump of royal jelly (sometimes) would use up + the object and then access its memory after that had been freed +keep track of hero's pending movement points across save and restore +give feedback if hero sees a monster become hidden under an object or water +hero might hear unseen monster read scroll of create monster or scroll of + teleportation; when it was create monster, player was given a chance + to call it something but not when it was teleportation, allowing the + player to deduce which type of scroll it actually was +wizard mode wish for terrain while on a fountain|sink spot made the counter + for number of fountains|sinks become one too big; would affect level + sound messages if all fountains|sinks were eventually destroyed +add a level arrival region to the Gnome King's Wine Cellar variation of the + Mines' End level so that hero can't end up in the treasure chamber +make potion of water become discovered if dipping a carried container into an + uncursed one reports that water gets inside or slides right off +a monster which was temporarily asleep wouldn't be affected by taming (either + food or magic), but one that was indefinitely asleep would be; when + tamable via food, it even caught and ate the food without waking up +in wizard mode, #terrain has offers to view all map locations as single- + letter codes corresponding to the levl[][].typ numbers and to view + a legend showing letter-to-type correspondence; adding new type + "lava wall" didn't update that legend and misdescribed all the types + which have higher values +restore the ability for trap creation via magic which creates pits to destroy + 'furniture' +allow #sit while flying over a squeaky board trap to trigger it +weight of statues of wraiths and of monsters which never leave a corpse was 0 +when a werecreature in human form attacked hero, it could transform to critter + despite hero having the Protection_from_shape_changers_attribute +status highlighting for hit points didn't work as intended for up or down HP + changes; 'up' rule was used for both, 'down' rule was ignored +unhide an unseen water monster using a polymorph trap on land +allow defining random-teleport or monster-generation exclusion zones in lua +if Magicbane cancelled a shapeshifter, forcing it to 'unshift', subsequent + messages continued to refer to the shifted form +a pet that was poison resistant but not stoning resistant would eat Medusa's + corpse and be turned to stone +ring of hunger prevents choking on your food +paranoid_confirm:pray can be changed to require yes/no response instead of y/n + by also setting paranoid_confirm:Confirm +wand of probing reveals map locations and traps in the ray path; also reveals + secret doors and secret corridors if the ray hits such +wand of probing zapped downward while hero is over water shows items under that +wand of probing reveals tin and egg contents +applying a wielded, lit potion of oil to unlight it while other unlit + potion(s) of oil were quivered would trigger panic + "addinv: null obj after quiver merge otyp=N" where N is POT_OIL +casting stone-to-flesh at self turned wielded or quivered rocks into unwielded, + unquivered meatballs, merging stacks if there were some in each slot +the throne room on the Samurai quest home level lacked a throne but gave + "You enter an opulent throne room!" message the first time it was + entered; vary the message rather than add a throne +coughing due to stinking cloud wakes up nearby monsters +stop occupation when timed levitation or choking issues a message +use #monster to make dragon steed breathe +steam vortices and fog clouds leave steam clouds behind +fog clouds maintain any clouds they are in, even poisonous ones +bone devils summon skeletons +adjust wand of make invisible and potion of invisibility effects +barbed devils have an attack that sticks you to them +balrogs prefer bullwhip if hero is wielding a weapon +ice devils have an additional attack, a slowing touch +buff scroll of confuse monster and blessed potion of monster detection +if a temple was entered while blind, #overview could show a line of just "." + when describing altars if no other interesting features on that level + were known +rolling boulders ignored walls and trees +shopkeepers consider the monster type when charging for tins, eggs and corpses +separate level flags premapped and sokoban +hero had worn amulet of magical breathing become unworn during theft by nymph, + dropped it to be able to crawl out of water, so it wasn't there when + game tried to transfer it to thief, triggering an "object lost" panic +digging down on a magical trap causes it to explode +thrown potion of sickness now bypasses target's innate magic resistance but + only affects current hit points, no longer also reducing maximum HP +lightning has a small chance of melting iron bars +make spell menu work with repeat +when attempting to look up a named fruit in data.base, try harder +set and check mon->mstate flags more consistently +fix sanity error when cloud was created over an engraving +docall naming of the monster that currently has the hero swallowed by + using their visible interior +give missiles thrown or shot by monsters the same chance to get used up upon + hitting as when thrown or shot by the hero +change menu_headings to also accept a color or color&attribute +issue feedback for encumbrance more consistently during pickup up +if hero destroys an altar by breaking a wand of digging or applying a drum of + earthquake, provoke divine wrath +if hero destroys a shop wall by breaking a wand of digging or applying a drum + of earthquake, have shopkeeper demand payment +mimics sometimes woke up and came out of hiding when they shouldn't have if + hero without protection from shape changers returned to a previously + visited level (though they would usually rehide so it wasn't obvious) +Wizards no longer have a bonus to writing unknown spellbooks, but now + learn what spellbooks look like as they gain skill in their + spell schools (allowing a guaranteed write with enough skill) +starting inventory: magic markers are more likely (guaranteed for + Wizards), but have fewer charges +early dungeon (pre-Sokoban) generates extra useful survivability items +potion of healing is much more common, and has a unique price +alchemy may affect only a portion of the dipped potions if a large + stack is dipped (especially if that stack is diluted) +monster kills can no longer deathdrop comestibles (other than the + monster's corpse) unless the monster collects food or + generates with food +about 10% of the heroes will now be left-handed; track the handedness of the + hero in the 'you' struct +if a monster fled from hero by intentionally jumping into a vault teleporter, + it would teleport randomly instead of into the vault, and if the + teleport trap's niche wasn't mapped yet, the trap would become mapped + but the spot would remain a secret corridor and not become accessible +boomerang travels in a clockwise arc when thrown by a left-handed hero and in + a counterclockwise arc when thrown by a right-handed hero +spellbooks weight 50 units but Book of the Dead only 20, and novels only 1; + the Book of the Dead has been changed to 50 and novels to 10 +save and restore hero tracks, increase track length +change vrock and hezrou from red to green, adjust vrock tile to have green +change wolf and werewolf to grey, warg to black +change [master] mind flayer, the Wizard, and the riders to bright magenta +change Nalzok and Minion of Huhetotl to bright red +walking into a shopkeeper tries to pay the bill +show billed items in a menu when paying with non-traditional menustyle +prioritize paying shopkeeper next to you even if multiple are detected +avoid impossible "trapped without a trap (fmon)" from 'sanity_check' when a + drum of earthquake made a pit at a monster's spot and pit creation + caused adjacent pool/moat/lava to flood that spot; if a non-floater, + non-flyer monster survived that, it got marked as trapped even though + flooding deleted the trap +demons cannot be frightened by showing them their reflection +HP regeneration formula has changed, primarily to be less fast in the endgame +riding negates stealth unless the steed is flying +previous hero rising as undead in bones retains intrinsics +level temperature affects monster generation +amulet of unchanging cannot be polymorphed +wishing for a "lit candle" provided one, but the feedback as it was added into + invent was "partly used candle (lit)" because of how 'lit' timer works +don't fall off steed because of Fumbling if saddle is cursed +cursed welded quarterstaff doesn't prevent spellcasting +wielded quarterstaff gives a small spellcasting bonus +if polymorphing a potion turned it into oil, dipping potions produced oil + randomly, or a horn of plenty produced a magic potion and converted + it into oil, the resulting potion of oil had its age (amount left) + set of the original potion's age (turn it was created) and could burn + for an arbitrarily long time if applied; conversely, polymorphing oil + into non-oil kept its relative age (no noticeable effect though) +an engulfer capable of passing through iron bars could do so even when hero + was engulfed +some uses of mons[obj->corpsenm] weren't excluding obj->corpsenm==NON_PM (-1) +if a covetous monster tried to teleport next to the hero but the level was + completely full, it would be booted off the level (set to migrate + back if the hero left and returned) instead of just staying put +if loadstone was unIDed but had been assigned a type name and you failed to + pick one up, the message referred to it as "gray stone" rather than + "stone called " +when a vision blocking gas cloud dissipated, the screen didn't necessarily + get updated to show newly visible locations in a timely fashion +if confused #loot while on a throne moved whole stack of quivered gold into + 'coffers' chest, the gold wasn't unworn from quiver slot, potentially + leading to crash when quiver was subsequently accessed +when filling quiver slot, don't bother asking "what do you want to ready?" if + invent is empty +no secret doors or corridors on the first two dungeon levels +the number of items destroyed by elemental effects is based on the damage +randomize the spellbook in the second level of vlad's tower +monsters weren't randomly generating if exactly one square was outside LOS, + and it contained a monster +when a spellbook was polymorphed into a novel and then incrementing spestudied + field turned it into a blank spellbook, the novel's title would stick: + "{spellbook of blank paper|plain spellbook} named " +walking on ice can make you slide in a random direction +if an adjacent statue was a in a pit, you could break it with a pick-axe even + though you're conceptually at the wrong elevation to reach it +using '#adjust c c' to collect all invent items compatible with the one in + slot c prefixed the inventory update message with "Merging:" rather + than "Collecting:" if there was at least one compatible stack; when + there weren't any compatible stacks and it was effectively a no-op, + the prefix used was "Collecting", lacking its intended colon +using '#adjust c d' or '#adjust d c' after splitting slot c via '#adjust Nc d' + for N less than c's stack size swapped c and d instead of re-merging + them even though merging was the intended behavior (the 3.6 change + that caused this was intended to avoid collecting other compatible + stacks while still merging the two specified ones) +ring of aggravate monster increases the level difficulty +if hero shattered an unseen monster's weapon, the [also unseen] weapon was + described in the feedback +don't self-genocide if a monk picks "master-lich" or "masterlich" as target + (was matching "Master" rank) +Sunsword can be invoked to create a blinding ray +Excalibur is much harder to get if hero is not a knight +pets considered any noise made by hero made as whistling +silent monsters in stinking clouds don't cough +unblind telepathy range depends on number of telepathy granting items worn +gold thrown or kicked at a sleeping monster with the 'greedy' attribute gets + caught instead of being treated as an attack but the catch message + neglected to report that target monster was awakened in the process +hero movement affects the water bubble movement direction +pets and peacefuls avoid a location hero just kicked +pets avoid a possible boulder pushing location in sokoban +shopkeepers bill you for using their bear trap or land mine +when engraving with a stack of eligible weapons, split one off the stack and + dull it rather than dull the whole stack +when engraving with a stack of cursed weapons, treat it differently if that + stack is welded to hero's hand: write in dust and leave whole stack + welded rather than split one off stack to engrave on floor +hero or monster didn't fall into pit if water at the location was boiled away +shopkeepers magnified the cost of shop items used up as a group; normally + using an item splits 1 from its stack, but applying a stack of N + candles to light them all charged N * N * single_candle_price +the tile for Ixoth (knight's quest nemesis) depicted a demon rather than a + dragon; change it to be a red dragon +untrapping containers or doors gives some experience +only honor DEBUGFILES (for activating debugpline() calls) when in wizard mode +if hero is on scroll of scare monster or Elbereth, werecreature switching from + human to beast form or general monster polymorphing into a susceptible + form will become scared right away instead on its next move +'altmeta' option didn't work as intended when 'number_pad' was On; typing + "n ESC c" wasn't treated as "n M-c" because reading + the 'n' changed program_state.input_state from commandInp to otherInp, + preventing special ESC handling; not an issue when number_pad was Off +a 3.6 fix to avoid a potential "object lost" panic when drinking potions had + unintended side-effect of making used up potions on shop's bill become + separate bill entries all with count 1 despite having come from same + unpaid stack; affected Ix inventory listing and itemized shop billing +buying shop items which include any unpaid ones inside containers would reveal + them even when the containers hadn't been opened (obj->cknown==0); + recent change to pay via menu made the problem become more visible; + shopping has been changed such that buying anything that is inside a + container requires that the whole container be bought as a unit +using #loot -> 'i'n to put multiple items into a shop-owned container would + ask whether to sell each item to the shop, and was prepared to accept + 'a' to sell the current one plus all the rest beyond it, or to accept + 'q' to not sell the current one or any beyond it, but the sell vs + don't-sell state was being reset for each item so 'a' and 'q' didn't + stick beyond the current one +join wall "spines" with walls of water and lava +some theft messages by nymphs force "she", others use default monster naming + which yields "it" when unseen; change the latter to "someone" which + still differs from "she" in a series of messages but isn't as jarring +if a nymph stole worn armor and got killed (perhaps by pet) before hero's next + turn, feedback would be "You finish taking off your suit." regardless + of the type of armor being taken off +when setting an option interactively [via O or 5.0's mO], if the particular + option uses a prompt to get a line of input (for compounds: 'fruit', + 'scores', most numeric ones), input was treated as a comma-separated + list of option[:value] rather than just the new value of that option +when there was a trap on a no-dig level, the floor beneath it was always + "too hard to dig into", making it impossible to remove the trap +the #terrain command didn't know how to cope with visible gas/cloud regions; + treat as traps as far as player choice of whether to show or hide; + if/when a spot contains both region and trap, show the trap +region expiration reported "the gas cloud around you dissipates" even when the + hero was swallowed +region expiration could report "the gas cloud around you dissipates" and also + "you see a gas cloud dissipate" for the same cloud spot +reduce shopkeeper's innate speed from 18 to 16 so that a hasted shopkeeper + doesn't always get 2 moves per turn +when a secret corridor was discovered by wand of secret door detection or by + wizard mode ^E and converted into a regular corridor, if there was a + formerly embedded object at the spot, presence of the object would be + forgotten unless within range of a light source +when poly'd into a giant, kicking a closed door always succeeds in breaking it +reduce crystal plate mail weight +interactively setting a status highlight for hunger with 'O' and choosing + 'text match' could crash while setting up the menu of hunger status + value strings; happened for curses or if the program was built to + use C++ regex processing but not for tty+posixregex +a pet with the hides-under attribute could "move reluctantly over" a cursed + object and then hide under it +prevent monster generation in the sokoban trap hallway +change MSGHANDLER from compile-time to sysconf option +allow changing extended command autocompletions via #optionsfull +if eating a tin's contents caused the hero to choke to death or turn to stone, + resulting bones would contain the tin still intact +when hero who is poly'd into metallivore form eats a tin, bypass "smells like + " feedback and the "Eat it?" prompt; just eat the contents + along with the tin without asking +digging in ice was handled inconsistently, particularly if done at the span + spot in front of closed drawbridge +angry god may remove an intrinsic +gelatinous cubes eat organic objects inside them +pets with reflection were unwilling to attack floating eyes +artifact gifts are rebalanced (easier to obtain; higher-value sacrifices are + needed for higher-value artifacts; lower-value artifacts are usually + gifted enchanted; unaligned artifacts are possible but rare even on + the first gift; artifacts you can't use well are less likely) +luck gains from sacrificing are limited by the value of the sacrifice +failed #untrap could move hero diagonally into or out of an open doorway +remember box is trapped after finding the trap +when you hear a monster incant a scroll, ensure that the 'I' invisible + monster indicator doesn't trump telepathy briefly +proceed with showpaths option even if the sysconf file is missing +angry shopkeeper was not charging for thrown items +avoid "You fall down a deep shaft!" if deliberately flying down +since introduction in 3.1.0, the definition for Mitre of Holiness has specified + that carrying it provides fire resistance, but that had never been + implemented; wearing it didn't confer fire resistance either--there is + no 'defends' capability for it since carrying should encompass that +if a tree and a boulder or statue were at the same location, applying an axe + would break the boulder or statue rather than chop the tree +avoid premapping outside Sokoban map to prevent showing stone glyphs +Grimtooth is permanently poisoned, protects from poison, and can fling poison +invoke cost for Grimtooth and Sunsword can be paid with magic power +cursed magic whistle can teleport you to your pet +Fire and Frost Brand can be invoked for expert level fireball or cone of cold +wielding Trollsbane grants hungerless regeneration +hitting with Ogresmasher gives a higher chance of knockback +Snickersnee can hit at a distance once per turn for free +the engraving pristine text field was not being appropriately populated during + level creation +worn alchemy smock reduces chances of dipped potions exploding +dwarves can sense buried items under their feet +monsters trapped in pits cannot kick +create familiar spell can create harder creatures +a vampire lord could choose to take on wolf form while flying over water or + lava, then revert to vampire lord form and teleport unnecessarily +a gas spore that was killed when an engulfer swallowed it produced an explosion + on the map rather than inside the engulfer +hallucination can display objects on the map that have a description (for + shuffling into play at game start) but no name; examining those might + trigger a crash +some food and paper items do no damage when bashing +improved messages for oilskin sacks protecting from water damage +some messages by amorous demons and mail daemon were delivered as verbal ones + even when the hero is deaf +travel couldn't find the vibrating square if it was covered by an object or + a monster; it isn't really a trap so treat it as special terrain +travel would stop one step in front of known vibrating square like other traps +fix bug which delayed burden changes due to monster actions (e.g. reverting to + natural form due to damage, changing carry capacity) for one turn +on arboreal levels (Ranger quest) where STONE terrain is treated as TREE, an + object at a tree location would be described as "embedded in stone" +an item at an ordinary tree location, whether the level is arboreal or not, + would be described as itself with no mention of the tree +some types of shopkeeper now start with a scroll of charging +objects are now accurately tracked as discovered even if not type-named nor + formally identified (fixing some bugs in scroll writing, and making + the discoveries list more accurate) +you cannot sacrifice objects/corpses while stunned or confused +'whatis' actions // and /? didn't work when the lootabc option was on, they + required /a and /c instead; add '/' and '?' as group accelerators so + that they work; /y and /n for them now only work when lootabc is off +writing on an unidentified scroll of blank paper identifies blank paper +dumplogs include spells and skills +praying will not restore monster-form HP while polymorphed, unless you + have unchanging +winter wolf cub was missing for monster to lycanthrope conversion +monster elves shooting arrows weren't getting intended small to-hit and damage + bonuses +luck has a reduced effect on to-hit chance +monsters use wand of teleportation to move hero away from item pile +lycanthrope instincts keep hero from changing shape while next to hostiles +scroll of enchant armor formula has changed (in particular, magical armor now + gains less enchantment when enchanted than nonmagical armor and + uncursed scrolls can sometimes enchant by more than one point) +dragonhide can rot +throwing ammo without a launcher produces a message +polymorphing into a large polyform unequips rather than destroying cloaks +clarify in the #quit message that it doesn't save the game +cursed potion of invisibility removes intrinsic invisibility +fix bug which caused engulf damage from air elementals and fog clouds to + ignore damage reduction from armor class +elementals do double damage on their home plane +water elementals move slightly more slowly +the "totally digested" instadeath timer is much faster +slow monster effects are more effective against faster enemies +light-spell is clerical, if playing a priest +boomerang can hit multiple monsters +the "bustling town" minetown has more peacefuls +healers may get tiny damage increase when attacking with knives +allow rogues to also backstab sleeping or paralyzed monsters +rogues cannot backstab monsters that have no backside +give experience if opening Schroedinger's Box causes death of the cat inside +priest donation amounts are explicitly stated, randomized slightly, based on + peak rather than current level, and allow for bulk donations (buying + larger amounts of clairvoyance/protection) if you have a lot of gold +amulet of magical breathing increases power regeneration +change some command keys, 'v' is now chronicle, 'V' is versionshort, + m-prefix 'V' is longer version, remove key binding of #history +one orc-town shaman has a higher level, affecting spellcasting +hero has a small chance of catching items thrown at them +wizard mode: history menu for #wizwish and WIZKIT +monster priests and wizards did not cast spells +prevent phaseable monsters hiding deep inside nondiggable walls +blessed potion of see invisible does not guarantee the intrinsic +prevent selecting all options in #optionsfull menu +shapeshifters change shape less +rolling boulder traps aren't removed when stepped on and move boulders + pushed onto them +when starting a new game as a monk, newsym(0,0) was being called (adjabil -> + postadjabil -> see_monsters when initializing See_invisible as hero + became level 1; seen 'monster' was the hero who hadn't been placed + on the map yet) +incorporate a fix to prevent segfault due to rolling boulder trap +wands of digging generate less often lategame + + +Fixes to 5.0.0-x General Problems Exposed Via git Repository +------------------------------------------------------------ +incrementing EDITLEVEL to invalidate incompatible save files was not working + as intended because VERSION_COMPATIBILITY was defined as 3.7.0-0 and up + rather than as 3.7.0-N for the current EDITLEVEL 'N'; undefine it +fix compile when DLB isn't defined +urealtime.realtime was being incorrectly calculated +revised "mysterious force" when climbing out of gehennom could generate + warnings about "rn2(0) attempted" or "rn2(-n) attempted" +after 'w' on split stack patch, wielding '-' would cause an object_lost panic +same patch allowed partial stack from getobj to replace cursed wielded weapon +autounlock of door or chest took no time; chest case depended on whether + anything got looted along with the unlocking +autounlock with artifact unlocking tool didn't do touch check on that tool +autounlock picked Rogue's artifact key over lock-pick or credit card (or + ordinary key depending upon invent order) even for non-rogues who + would be blasted when touching it +wielded aklys had its "(tethered weapon...)" description scrambled +randomized trap name could pick trap #0 which isn't a trap and yielded "water" +if running and Blind or Stunned or Fumbling or Dex < 10, encountering a closed + door orthogonally would keep reporting "ouch! you bump into a door" + repeatedly until eventually interrupted by approaching monster or + hunger or ^C +data.base lookup of an entry with any blank lines would falsely claim that + "'data' file in wrong format or corrupted" after some extra checks + were added while investigating tab handling anomalies +using nhl_error() to report a Lua processing problem would clobber the stack +level teleportation's "You materialize on a different level!" could be given + out of sequence with other arrival messages +more sequencing: if wielding Sting or similar and level teleporting to a + level with different warning effect, the start-glowing or stop-glowing + message came before the materialize message on the destination level +prevent "you materialize on a different level" after "a mysterious force + prevents you from descending" if you try to level teleport past the + stairs down from the quest home level before being granted access +creating Mine Town variant 1 (Orcish Town) sometimes complained about being + unable to place lregion type 1 and failed to have any staircase up +set g.context.botl for glove and wielding actions that could start or end + bare-handedness in support of condtests[bl_bareh] +reinstate ranked ordering of the status condition fields +grammar for messages about a monster removing items from a container was bad +some new status conditions didn't always update when they should +fix flipping non-existent stairs and ladders (github #311) +fix door created into random wall or position opening into solid wall +handle gone portal when going back in quest +'use_inverse' option was accidentally made Windows-only; change it back to + being more general; change its default to True +change inconsistent achievement spelling of "Mine Town" to "Minetown" +fix crash in water_damage_chain +teleport feedback "you materialize at another location" was given too soon +'mention_decore' was repeatedly reporting "you are back on bottom" when + moving around underwater +revised 'mention_decor' was describing furniture or ice right before look-here + described the same thing when stepping onto object(s) +poison gas clouds located over known but unlit pools were visible as known + clouds but steam clouds in that situation were not +after the wish parsing change, wishing for "" or for + "" worked as intended but wishing for "" + (where used the canonical spelling) triggered a crash +fix new "objects[0] class #1 not in order!" panic if plain 'char' is unsigned +only generate shop items on solid floor squares +avoid gcc 10 warning by removing duplicate definition of 'head_engr' +if a monster removed a corpse from an ice box, the corpse would never rot away +monster creation on quest levels could make genocided creatures +enabling wizard mode 'sanity_check' option would complain about invalid mhpmax + value for level N monsters created with a d8 value of 1 for all N d8's +disable that extra check because gremlim HP split after cloning triggers it +some versions of tiles processing (not X11's) complained about the rename of + "{acid,blinding} venom" to "splash of {acid,blinding} venom" +wizard mode #timeout changed to show timed Displacement in 'can be timed in + normal play' section instead of 'timed via #wizintrinsic only' section +the fix to make worm visibility checks work as intended forced the coordinates + of the extra tail segment co-located with the worm monster to match + the worm instead of leaving it off the map; place_worm_tail_randomly() + reverses the segments and can throw some away if there isn't room, + but throwing away the extra segment removed the worm from the map +using 'O' to try to change 'symset' was a no-op; 'roguesymset' worked +change default for lit attribute in special level des.terrain directives to + 'unchanged' instead of 'unlit' +replace worm tail placement code that reportedly led to a sanity_check warning + [no actual code problem found; might be compiler bug for 'xchar'] +learn scroll of teleportation after reading even when random destination is + right by starting spot +fix off-by-one bug in dimensions of theme rooms +fire/frost horn feedback when zapped by monster was inaccurate (falsely + claimed that it was "directed at self" when attacking hero) +tins of spinach and 'dead' eggs could cause out of array bounds access + attempting to index into mons[] by polyfodder() macro +options help ('? g') listed all boolean options, then repeated them among + the compound options; on macOS they showed a description of "(null)" + but for other sprintf implementations they might cause a crash +change name of #wizlevelflip to #wizfliplevel +dwarves could sometimes pass through walls without digging their way +fix genetic engineers dropping Schroedinger's cat box +the checks and handling for fountains, sinks, and drawbridges were being + missed during liquid_flow +monster movement flags unification allowed displacer beasts to displace Riders +a long worm with no visible segments (but one internal segment) might trigger + warning: tail 'segment' at <0,some_y>, worm at if teleported +adding displacer beast inadvertently introduced a regression in swapping with + pets, allowing them to be pulled into water by hero on/over water +splitting #if MAIL into #if MAIL_STRUCTURES and #if MAIL made it possible to + wish for and write scrolls of mail with MAIL disabled, but attempting + to read such a scroll issued impossible "What weird effect is this?" +remove M2_MALE flag that was unintentionally left on dwarf lord/lady/leader + entry and was preventing female incarnations +tilemap.c wasn't building if STATUES_LOOK_LIKE_MONSTERS wasn't defined; also, + to match the code that should be defined so change the preprocessor + test to 'ifndef STATUES_DONT_LOOK_LIKE_MONSTERS' +ensure that monster female name variation ends up as a female during ^G +arbitrate when there is a conflict between gender term (male or female) and + a gender-tied monster name (cavewoman) during ^G; gender term wins +wizard mode sanity check complained about Wizard's clone mimicking a monster +new ^G gender-naming handling code required a guard against null permonst + pointer which could occur under some circumstances +replace "aligned priest" entries in Pri-loca.lua, astral.lua, minetn-1.lua, + and sanctum.lua, with "aligned cleric" +attempting to swap places with a peaceful monster might cause it to flee +gender-specific monster names can be used in .lua files with the gender upheld +remove unused vision tables +changes accompanying sorting of discoveries resulted in omitting very last + item for '`'/#knownclass on a class where every item was discoverable + and had no extra labels (so potions and rings, possibly others, but + not scrolls or wands) and every item was actually discovered +change to can_reach_floor() resulted in hero being unable to reach the floor + when held by a lichen +panic if lua init fails +change wizard mode command #wizmgender to wizard mode option 'wizmgender' +engraving with non-blade dulled the weapon anyway (pr #464) +'sortdiscoveries:s' had a spurious generic header shown at the start of the + last class if there were any artifacts or unique items discovered +loss of saddle by opening magic left hero mounted on unsaddled steed +avoid segfault during error reporting for bad 'O' value(s) after theme rooms + have been initialized, leaving iflags.in_lua set +avoid complaints of "nothing to foo" for 'force_invmenu' if there are no + likely candidates to foo with but there are hidden acceptable choices +avoid "Not carrying anything. Never mind." for 'force_invmenu' +'altmeta' option could be toggled On but once On could not be toggled back Off +wearing a ring of protection and any amulet behaved as if wearing an amulet of + guarding when determining MC value +messaging for genetic engineer attacks had several problems +give genetic engineers teleport capability (as they had in slash'em); 'port + away after polymorphing someone so that they don't just repeat that +if an invisible hero managed to convert an unaligned altar to an aligned one + with color enabled, altar wasn't immediately redrawn with new color +repair some regressions to (a)pply introduced by "getobj refactor" patch +getobj too: allow attempting to (E)ngrave with any item in inventory +getobj refactor also allowed non-nameable items on floor to be assigned names +exploiting the bug to assign type name to glob on floor allowed wishing for + "N assigned-glob-name" to create a glob with quantity N instead of 1 +fix ^X feedback when held typo: "unseen createure" -> "unseen creature" +if a corpse was set to revive as a zombie and corpse was partly + eaten at revival time and monster is defined as providing more + nutrition that zombie, oeaten_stat() could give the warning + "partly eaten food more nutritious than untouched food" when used to + calculate zombie's hit points (depended upon how much had been eaten) +undead turning magic revived corpses flagged as no-revive if they were being + carried but not if they were zapped while on the floor +forgetting an item's known/dknown/bknown/&c settings when picked up by unseen + monster made it possible to trigger a latent shop bug with globs; + avoid clearing dknown flag for globs +fix globby_bill_fixup to use shopkeeper instead of Null for glob pricing +applying a book to check readability treated novels as if they were spellbooks +#version was leaving the 'in_lua' flag set and if subsequent 'O' issued an + error (example was an attempt to interactively set bouldersym to an + invalid value), the error reporting routine crashed via segfault +lighting for baalz level defaulted to random and could end up being lit +when using 'O' to set menu color patterns, the reminder message that the + boolean menucolors option needs to be set to True for them to work + was sometimes given even when already True +stair revamp unintentionally resulted in cursed potion of levitation no longer + causing hero to hit head on ceiling +enlightenment/disclosure when wielding two weapons with two-weap skill higher + than secondary weapon's skill had "with" duplicated in the feedback +corpse of monster with gender specific names (king vs queen and so forth) + was always described by the neutral name (ruler and such) +prevent obj_pmname() from calling mon_pmname(monst) when monst->data is null + to prevent a null pointer dereference +correct the pluralization of monarch to monarchs, rather than monarches +don't allow web spun by spider to interfere with solving Soloban +fix parsing of wish adjectives (return value broken by changes accompanying + figurine gender patch) +when picking up a thrown weapon while quiver is empty, don't put it into the + quiver slot if it needs to be wielded for throw-and-return action +using bhitpos in flooreffects to handle erosion damage broke its original use + of tracking wand zaps if a teleportation zap hit an object; subsequent + zap traversal was done from object's landing spot rather than from its + zap hit spot, resulting in scrambled wand targeting +restore previous behavior of the 'altmeta' option (only wait for a second + character when getting a command keystroke, not other key input) +baby gold dragons weren't able to grow into adult gold dragons +when hero is displaced, make monsters who try to stay out of direct line do so + with spot where they think the hero is rather than where he really is +if hero died while wearing gold dragon scales/mail and left bones, they would + still be emitting light without being worn when bones got loaded +if an invisible monster put on or took off armor while out of hero's sight + spurious message "Suddenly you cannot see it" would be given +an item thrown or dropped while swallowed was treated as being picked up by an + unseen monster so object fields {known, dknown, bknown} got cleared +segfault if gremlin fled weaponless hero wearing gold dragon scales/mail +'disambiguate WHACK' patch affected field layout of objects[] but EDITLEVEL + wasn't incremented, allowing incompatible save files to be restored +restore the boulder exception for piletops that had been unintentionally + removed during the expanded-glyphs changes +misaligned potion colors due to lack of reset_glyphmap() following obj shuffle; + this issue only impacted a new game +closed doors were described as "horizontal closed door" or "vertical closed + door" instead of just "closed door" +glob shrinkage while hero was away from glob's level wasn't handled properly +unpaid shop-owned glob that shrank to nothing had weight 0 which triggered + onbill warnings when 'sanity_check' was On; for 'Ix' and itemized + billing, the empty weight was shown to player if 'wizweight' was On +if 'showrace' was On and invisible hero couldn't see invisible so didn't see + self, the color of whatever could be seen underneath changed to white +in wizard mode, a poly'd priest/priestess attempting to polymorph into priest + or priestess in order to rehumanize became a new man or woman instead + because "priest" matched "aligned cleric" rather than the role monster +if a glob which has just shrunk away to nothing was wielded or quivered, + unwield it before destroying it +after changes to gender tracking for corpses and statues, when a unique + monster got turned into a statue if was erroneously flagged as female + rather than 'historic' +changing engraving to an occupation resulted in not dulling a weapon used to + engrave a single character +a change to wounded legs handling resulted in not recovering lost dexterity + or receiving the "leg(s) feel better" message if wound time expired + rather than having legs be explicitly healed +turning movement into commands broke the rest_on_space option; it also + interfered with using pick-axe plus autodig in downward direction +cursed scroll of light had special message when wielding Sunsword that didn't + work for wearing gold dragon scales/mail +giving a prefix keystroke other than 'm' prior to a command that doesn't use + prefixes was silently ignored instead of being rejected +prior revision broke all prefix usage +movement command revamp broke 'm>' and 'm<' on stairs to avoid auto-pickup at + the destination +when trapeffect_selector() returns 2 to caller mintrap(), meant to signify + that the monster was killed in the trap, ensure that mintrap() + returns that value too +have com_pager() check for failed nhl_init(); probably can't actually happen + because the program would never get that far if lua init was failing +rearranging first-kill and first-hit gamelog messages to get hit before kill + ordering resulted in "hit with a wielded weapon for first time" being + given twice if that hit was delivered via applied polearm or via a + joust hit +rearranging the feedback for first-kill and first-hit introduced a bug by + not verifying that the wielded item used to hit was a weapon, giving + erroneous event feedback and potentially giving it over and over for + other non-weapon hits for as long as never-hit conduct stayed unbroken +counting "just picked up" items when deciding what pseudo-classes should be + included for the 'I' command's object class prompt was operating on + an uninitialized variable +changes to stair internals resulted in summoned Kops blockading the stairs up + rather than intended stairs down +dumplog's list of "major events" showed all logged events, not just major ones +pickup via menu ignored player-specified count when picking up gold +changes in encumbrance sometimes went unreported, leaving stale status line + info until hero's next move +taking off yellow dragon scales/mail or having temporary stoning resistance + time out while wielding a cockatrice corpse without gloves left that + corpse safely wielded instead of petrifying the hero +special level loading wasn't honoring gender specified in lua code +add '#tip' for containers to context-sensitive invent handling +sequencing confusion: picking an item when viewing inventory and picking an + action to do with it caused the inventory command to use time, then + on next turn the action was performed without taking any time +program would access freed memory if charging caused a ring to explode +arriving on Valkyrie quest final level could produce impossible warning + "mkstairs: placing stairs up on molten lava at <68,13>" +if the repeat command was used after prefix+command, only the command part got + repeated +the change for repeat after prefix+command would result in a crash if repeat + was attempted after an unassigned key +items obtained via wishing while blind were erroneously being marked as 'seen + up close' so behaving differently from items picked up off the floor +corpses of neuter monsters had random chance to be flagged as female so would + only stack with others that made the same random choice +one-shot food testing ability conferred by blessed scroll of food detection + didn't warn about globs of green slime because the relevant code was + only executed for corpses, eggs, and tins, not for globs +worn ring of slow digestion blocks per-turn hunger but not the hunger caused + by wearing it; white dragon scales/mail was blocking per-turn hunger + and didn't cause any hunger itself; change to treat it like the ring +if the program was built with EXTRA_SANITY_CHECKS enabled, changing levels + while riding would give impossible warning "no monster to remove" +the change to protect Rider corpses from being destroyed by exploding chests + inadvertently prevented them from being used up when Riders revived +force-fight against furniture covered by an object described the attack as + missing an unknown obstacle +using #wizmakemap on Plane of Water added a new set of air bubbles each time + it was run and eventually replaced just about all the water; likewise + with clouds on Plane of Air +avoid new "where are we?" panic if player quits during character selection +add Untrap as a potential 'autounlock' action +if a zombie revived near the hero, a busy hero would keep doing whatever + action was in progress instead of stopping because the zombify didn't + walk across the threshold from no-threat to threat +revised monster teleportation message handling caused magic whistle to be + changed to not operate on pets that were already adjacent; change back +revised monster teleportation message handling could produce duplicate message + when shopkeeper who left shop got returned to it +revised magic whistle produced message sequencing issues when summoned pet + arrived on a trap, particularly if killed or sent away or shape changed +recent changes in removing a dead monster from the map didn't update screen + to show objects it dropped; they were present, just not displayed +further changes resulted in dead monsters' corpses be placed at <0,0>; + reverse the part(s) that cleared stale monst->mx,my +adding name/rename choice to #therecmdmenu caused it to crash when picking an + adjacent unnamed, untame monster +for menustyle:Full, fix the combination of 'A' auto-pick all plus 'P' just + picked up to limit what "all" means +for menustyle:Traditional, fix 'P' for just picked up items in inventory when + filtering what items to put into a container +restrict stunning effect to is_xport trap types +lua's garbage collection didn't like the way nethack was trying to use it and + issued a pair of warnings each time the relevant code got run +items flagged as just-picked-up were unflagged if you stepped on other items + without picking anything up +activating a magic portal still gave "you feel dizzy for a moment, but the + sensation passes" after portal traversal was changed to make the hero + be stunned for a few turns +after the fix for zombie reviving near hero (which now interrupts hero's + occupation), could get "revive panic" when eating a troll corpse if + it revived on the same turn that eating the corpse would finish +a wizard's starting equipment was supposed to include a random spellbook of + spell level 1 through 3 but it was being forced to be level 1 +earlier fix for prices of unpaid objects going away in persistent inventory + display when hero bought something during itemized billing didn't work + if paying for a used-up shop item--prices of any unpaid items vanished + when inventory got updated to reflect transfer of hero's gold to shk +save files created with SCORE_ON_BOTL disabled were erroneously being rejected + if the program was rebuilt with it enabled and vice versa +avoid "It suddenly appears!" if a monster with the STRAT_APPEARMSG attribute + is seen to teleport away then not seen at its destination +avoid boulder-on/in-water sanity_check warnings on the Plane of Water +when one monster swallowed/engulfed another and killed it, impossible + "placing over itself ..." could be given by place_monster() +if the game crashed or the process was killed, recovering a save file ended + up with incorrect stairway connections between levels +when using --nethackrc=file on the command line (currently only implemented + for ports that use unixmain.c), options parsing freed the string + containing 'file' before using it as the RC file name +using 'o'pen as a synonym for #loot of a container at the hero's location did + not work if the hero was in a pit +update '?' menu to reflect change to 'O' command +end of game with DUMPLOG could panic due to perm_invent handling, even when + the persistent inventory window wasn't in use +with color Off and the screen symbol for ice the same as for floor, the black + and white ice was supposed to be rendered in inverse video but that + got broken by the symbols and glyphs overhaul +command line processing interleaved with options file processing is complex: + a recent change to make 'color' show up for tty in the short options + menu resulted in 'nethack --windowtype:X11' running X11 with ascii map + ('NETHACKOPTIONS=windowtype:X11 nethack' continued to default to tiles) +when the Astral level got created, any fake player character monsters that + were seen or sensed when created were reported as " suddenly + appears!" rather than be treated as part of level's initial population +tipping contents of one container directly into another allowed transferring + wands of cancellation and bags of holding or tricks that were inside + a sack, box, or chest into a bag of holding without blowing it up +prevent random traps from being created inside the shops in the tourist quest +if hero's steed got hit by knockback effect, impossible "no monster to remove" + would occur (plus more warnings if 'sanity_check' was On) +the #saveoptions command included options changed via doset_simple() but not + ones changed via full doset() +fix 'nethack --scores' as alias for 'nethack -s' +adding command line 'nethack --usage' broke 'nethack -u name' (however, + 'nethack -uname' still worked for names other than "sage") +being hit by a big monster and getting knockback effect could send hero out + of a shop (or into its "free spot") while carrying unpaid goods; + robbery wasn't noticed until hero eventually moved to a different spot +hallucination of objects incorrectly included generic objects as candidates + for what objects looked like; if an object had its dknown flag set, + formatting a generic object in its place was unreliable (Null pointer + deference prior to static analyzer fix, odd fake name "generic" after) +some actions that ask the user to pick a location allow typing '$' to show + valid spots, accept typing a second '$' prior to moving the cursor to + toggle the highlights off; ^R already did that; moving the cursor too +change 'm' prefix for #tip from 'use menu to pick among floor containers' + (since that's already the default) to 'skip floor containers' so that + context-sensitive item-action Tip directly operates on the item +anti-magic field's reduction of hero's maximum energy could result in current + energy being one point higher than maximum +if hero was killed by a wand zapped by a monster, cause of death was reported + as "killed by a bolt of imagined by " +throttle the difficulty of the monsters in theme room "buried zombies" +buried troll whose auto-revive timer expired might trigger panic with + "revive default case 6" +throwing a helm of brilliance could yield "breaking odd object?" +sanity checking of engravings was stopping after first problem found +the fuzzer could get stuck in a loop if hero died in a way where life-saving + just resulted in a repeat death (cited case was burning up in lava, + where life-saving teleports you out of it; if the level is full, the + teleport will fail and you'll immediately burn up again) +fix unicorn horn's ability to repair blindness +quest nemesis and a few other special monsters are suppressed from bones; + their death feedback could be given when they were removed +running the tutorial until completion and returning to normal play but left + the 'no followers' flag set; adjacent pets wouldn't tag along when + hero moved to other levels +when a magic whistle moved a hidden pet it brought that out of hiding and + gave a message about "your appears" but the map was updated + while it was still hidden so nothing seemed to appear +entering the tutorial stashed hero's equipment for eventual return to normal + play but going down stairs to the second tutorial level returned it + too soon and allowed any items gathered on the first level to be kept +entering the tutorial disables the Save command; exiting it is supposed to + re-enable that but the change to fix the second level broke that +entering the tutorial and then returning to play made the tutorial branch be + eligible for a portal destination via wizard's Eye of the Aethiopica +'hard helmet' was based on being metallic so overlooked crystal helmet +don't blame/credit hero for stinking cloud if dying quest nemesis releases one +Lua selection operations 'subtract' and 'xor' didn't always work as intended +accept 'true' or 'false' as value for des.object field 'trapped' +special level loader didn't check for bad coordinates supplied by .lua + file thoroughly enough +hero might not be credited with "entered Mine Town" achievement for the town + variations which treat the whole level as the town if that level gets + entered via falling or level teleport +in the theme room "water-surrounded vault", guarantee an item which can + be used to escape from the room in one of the four chests +pets capable of using items would pick up and wear cursed armor +if something breakable was set up as alternate weapon and the second of two + bare-handed hits succeeded, it would be broken and trigger impossible + "objfree: deleting worn obj" +strength cap for hero poly'd into an orc captain was 18/50 even though it is + 10/100 for Uruk-Hai and monster Uruk-Hai can grow into orc captains +status_hilite rule for critical-hp takes precedence over up/down/changed HP +livelog/#chronicle of multiple high priests reported their deaths as + "killed high priest" and "killed high priest (2nd time)" instead of + "killed high priest of Foo" and "killed high priest of Bar" +using wizard mode #wizkill outside the endgame followed by m^V to enter the + endgame without any intervening moves would result in impossible + "dmonsfree: 0 removed doesn't match N pending on " +dwarf/elf/orc/gnome hero killed by zombie would rise as human zombie for bones +paranoid_confirm:Autoall for menustyle:full has the test handling backward and + was treating 'yes' as no and 'n' or ESC as 'y' +applying a wielded lump of royal jelly but not picking something to rub it on + while other lumps of jelly were quivered would trigger a panic, + "addinv: null obj after quiver merge" (like applying lit potion of oil) +ceiling hider could become hidden when there was no ceiling, triggering a + warning if sanity_check was On +hero could be forced onto a monster's location if a level was full and an + engulfer was occupying an adjacent but inaccessible spot, engulfed + hero, then expelled hero while now occupying hero's accessible spot, + triggering sanity_check warning "you over monster" +experimental #saveoptions wasn't saving the set of cond_xyz options correctly; + if player viewed the 'm O' submenu for status conditions, they would + get saved even if not changed; otherwise, ones that came in from the + old RC file wouldn't be included in the new one +knockback or recoil while levitating could hurtle the hero through a wall of + water to the spot beyond unless it happened on the Plane of Water +if recoil from throwing an item while levitating sent hero into a wall of + water, the thrown item got placed in that water rather than at its + intended destination +include '-' as suggested item in "what to dip?" prompt if dipping at pool or + fountain or sink with slippery hands +don't attempt a second hit for bare handed/martial arts if wearing a shield +when using 'm #overview' to annotate a level other than current the one, + include level number, and dungeon branch if not current one, in the + prompt instead of generic "this level" +when using 'm #overview' in the endgame, don't include non-endgame levels +when a tethered aklys gets caught in a web, make sure it doesn't return + and that the display of the tether gets cleaned up +add 'X' as a potential context-sensitive item-action for uwep and uswapwep +monsters weren't noticing hero's possession or lack of magic resistance when + hero getting zapped by a wand of striking was or wasn't resisted +discard monsters' observations about hero's resistances when saving bones +autopickup while levitating shares code with 'mention_decor'; after being told + about ice covered by an object, moving over some other object later + when mention_decor is Off could give "you are back on solid ground" + long after leaving the ice +duration of temporary stoning resistance would be extended while eating a + cockatrice corpse, as intended, but not while eating Medusa's corpse + so if it timed out during the meal, player got the message about hero + no longer being protected against stoning but was able to finish the + meal safely +farlook at something that was on top of an engraving or grave would report + the engraving text or headstone epitaph along with the 'something' +when carrying 52 items (excluding gold), hero couldn't pick up a thrown, + stolen, or dropped item which was split off from a still-carried stack +supply chests on early levels weighed the same as empty chests until something + was added or removed +stacked pair of potions of healing in supply chest weighed same as one potion; + drinking one of the two gave a healing message, then both had their + weight updated as their stack was split; if close to an encumbrance + threshold, new weight would trigger an encumbrance increase message, + immediately followed a decrease message when the potion got used up +bounds checking for object name formatting inadvertently introduced a change + that hid BUC prefix for charged rings +debug fuzzer was triggering out of bounds array access in loseexp() if + life-saving at level 1 used blessed restore ability to regain lost + levels and restored those all the way to level 30; introducing an + assert(u.ulevel < MAXULEV) changed bounds issue to assertion failure +strength less than 25 was unintentionally being capped at 18/07 +if an amulet of flying got stolen while hero was over lava without other + protection against lava, it would be destroyed even though it's not + flammable, then attempting to format it for messages would trigger an + impossible warning about "glorkum", then a crash occurred +poison gas breath from green dragon or iron golem that hit and was reflected + left target enveloped in a gas cloud (reflection now takes precedence; + somewhat odd though: gas that misses still leaves target enveloped) +Warning didn't show nearby monsters who were inside poison gas/steam/smoke + regions +map didn't show adjacent monsters if they were inside a gas region unless + they were seen via telepathy or extended monster detection, but they + were described as if visible in messages (combat, for instance) +OPTIONS=symset:blank and symset:plain didn't load the specified symbols if + used from the RC file or NETHACKOPTIONS +for OPTIONS=symset:blank, S_engroom (engraving on a room floor spot) and + S_engrcorr (engraving on a corridor spot) retained their default + symbols ('`' and '#', respectively) instead of switching to space +setting perm_invent in RC file before setting windowtype (whether later in + that file or via NETHACKOPTIONS) could result in it staying False + depending upon whether the default windowtype supported it +if hero was wielding potion(s) of unholy water and a magic trap gave its + remove curse effect, scroll of remove curse would become discovered +object discoveries during the tutorial carried over when normal play resumed; + counts of monsters created and vanquished carried over too +end-of-game attribute disclosure in wizard mode reported incorrect text for + for apron/alchemy smock's conferral of poison+acid resistances + (3.6.x was susceptible to this for T-shirt text but since T-shirts + don't confer any attributes, it wasn't noticeable) +if a tame or peaceful monster was trapped and blind hero hadn't seen the trap + yet, attempting to swap places would report "You stop. can't + move out of that trap." and if the 'tips' option was On, #untrap would + be suggested; but #untrap would fail due "you know of no traps there" +camera flash hitting a hidden mimic mentioned it as being a mimic but didn't + bring it out of hiding +when chain lightning hit a sleeping monster, the victim didn't wake up +on medusa-4, Medusa and the downstairs were located in different chambers +on medusa-3 and medusa-4, Perseus's statue was located in a different chamber + from Medusa +omit "a" from "drowned in a limitless water" when drowning on Plane of Water +restoring a save file could trigger impossible "rnd(0) attempted" if it tried + to make an unhidden mimic hide as an object; if the code was marked as + a released version, it would crash due to divide by 0 error instead +fix regression of a post-3.6 fix: if 2 Wizards of Yendor were in play and 1 + escaped the dungeon, bookkeeping for current number of Wizards stayed + at 2, interfering with future Wizard behavior +sometimes a repeat count from the preceding command carried over to most + recent one when using do-again (^A); if the most recent one was an + extended command, the spurious repeat was for '#' +if peaceful monsters react when seeing hero attack a peaceful monster, don't + have quest guardians run away; also, quest leader only becomes angry + if the monster being attacked is a quest guardian +farlook of water/lava location listed wall of lava before molten lava; because + of that, lava was omitted ("molten" suppressed to reduce vebosity, + resulting in "lava" which got skipped as substring of "wall of lava") +having #terrain display gas cloud regions as if they were traps didn't work + for monsters in such regions that are shown when adjacent to hero or + sensed via ESP +when a monster within a gas cloud was displayed on the map because the hero + was next to it, it remained displayed if hero moved away +eating a pyrolisk egg on the floor triggered an "object lost" panic +core object creation and the curses interface's window handling both became + confused by the 'pauper' option/conduct because they assumed that + invent being Null meant that the game hadn't started yet +wizards were discovering unread spellbooks whenever any skill was advanced; + do so only when a spell skill is advanced +if tips were enabled, the getpos/farlook tip clobbered the initial prompt (at + least for tty's one line message window), so reissue the prompt after + the tip has been displayed +a post-3.6 change to try to cope with invalid light source data when restoring + corrupted save file caused "panic: relink_light_sources" for valid + save file if saved while hero was poly'd into a light emitting monster +priestname() didn't handle "a" vs" "an" prefix correctly; normally priests are + named as "the priest of " but hearing an unseen priest read a + scroll doesn't force "the" and yielded "You hear an priest of + incant ." +non-fireproof water walking boots wouldn't be burnt up if fire resistant hero + walked on molten lava +1x1 poison gas clouds for green dragon and iron golem breath could be placed + at wall locations +if a pile of objects had plain arrow(s) on top, map location classification + got confused and reported 'unexplored area' +when the 'fireassist' option was on, 'f' would choose uquiver over wielded + throw-and-return uwep +knockback could move hero diagonally into or out of an open doorway +farlook of /e or /E stopped reporting engraving and headstone text after a fix + for the situation where // or ; reported such text when there was an + object or monster in the way +message was garbled when lightning or acid breath hit iron bars +shop bug: buying a container with unpaid items in it could produce impossible + "unpaid_cost: object not on any bill" warnings +when walking into/against a locked closed door, 'autounlock'==kick didn't + execute kick when player answered yes to "Door is locked. Kick it?" +having a 1% chance of creating rideable monsters with worn saddle gave knights + a 1% chance of creating an extra saddle for starting pony; it wasn't + tracked with other objects so produced a trivial memory leak +when attacking a displacer beast, using the 'F' forcefight prefix prevented it + from swapping places with the hero +successfully disarming a chest trap was clearing the chest's 'tknown' bit + instead of setting it; likewise when failing to disarm triggered and + used up the trap +when game ended with 'force_invmenu' On, final disclosure of inventory would + contain spurious menu entry "? - (list likely candidates)" +avoid reporting "a gold pieces appears next to you" for mimic +don't try to split a pudding that got jousted into a hole and is off the map +mounted hero was able to deliver joust hits when trapped +timer sanity check for melting ice gave false complaint about non-ice for + frozen moat under open drawbridge +mhitm_ad_phys() was not applying Half_physical_damage when hero was target +callers of thitu() were not applying Half_physical_damage either +throwing crystal plate mail or helm of brilliance up against the ceiling could + result in the item being cracked and then vanishing +yn_function (used all over the place) sometimes triggered an impossible() + during do-again (^A) processing [ongoing revisions; more are probably + needed; listed here in case ^A behavior changes] +uncursed genocide while hallucinating deliberately mis-reports hero's role as + target but was also inappropriately showing it to livelog/#chronicle +livelog/#chronicle for bribing a demon lord reported random monster and + currency if hero was hallucinating +naming a type of item, unnaming it (with name of ), naming it again + (new name or re-use of old one), then unnaming it again would issue + impossible: "named object not in disco" +throwing entire quiver and then picking the stack back up was not putting it + back into quiver +when reading a T-shirt or apron, add trailing period to the slogan unless + already present in the quoted text +when reading an engraving, suppress the addition of a trailing period if the + text already has one +cursed magic whistle could teleport hero on no-teleport levels +give a brief explanation when receiving a wish for acquiring the Amulet +teleportation traps no longer teleport you on levels made temporarily + no-teleport by the presence of a monster +an attempt to pick up an object from a monster's stomach would trigger + an impossible() in newsym() due to object having no ox,oy coordinates + set; set the coordinates to the monster's at the start of pick_obj() + + +Fixes to 5.0.0-x Platform and/or Interface Problems Exposed Via git Repository +------------------------------------------------------------------------------ +curses: 'msg_window' option wasn't functional for curses unless the binary + also included tty support +curses: line input that doesn't take place on the bottom line of the message + window uses a canned curses routine and doesn't support ESC to kill + partial input or to cancel; "Who are you?" prompt was willing to name + a character "^["; have the popup version of getlin() fake the usual + ESC handling, but player has to type for that to work +curses: menu headings didn't use default text color +curses: #perminv changes disabled menu_headings attribute for persistent + inventory window headings; reinstate that +curses: messages were tagged by turn in 3.6.x so that ^P can place a separator + between groups of messages; somehow the line of code that recorded + the turn vanished so ^P behaved as if every message came on its own + distinct turn, resulting in lots of "---" separators +curses: when entering a count while in a menu, cursor would jump to the spot + on screen where the hero was, even if menu covered that part of map; + post-3.6--started when curses was changed to use core's get_count() +curses: clipped map crashed due to uninitialized memory +curses: changes for tty's TTY_PERM_INVENT resulted in viewing inventory under + curses while carrying only gold to crash; didn't matter if perm_invent + was On or if TTY_PERM_INVENT was enabled +curses: for screen refresh, don't attempt to refresh windows that haven't been + set up yet or have already been shut down +curses: for raw_print() in #if PDCURSES config, don't attempt to write to + message window if it isn't set up yet or has already been shut down +curses: scrollbar 'framecolor' wasn't being initialized before use + causing an asan crash because the value is used to index an array +curses: typing ESC to cancel something issued a beep; if the terminal was set + to 'visible bell', the screen flashed; only beep when the ESC is part + of an escape sequence--other than M-c generating ESC c--and nethack + is expecting text rather than a command or direction +curses: with window borders on and align_status:left, restoring brought up a + screen where the message window's border wasn't shown; once it needed + to be scrolled to fit a new message, the border appeared +curses: after changing curses_mark_synch() to do something, making a menu + selection by entering a count that uses more than 1 digit caused the + menu to vanish +curses: setting up default roguesymset at startup clobbered primary symset if + config file picked Enhanced1 for primary (core bug exposed by curses) +Qt: at Xp levels above 20 with 'showexp' On, the combined status field + "Level:NN/nnnnnnnn" was too big and truncated by a char at each end +Qt: searching a text window for something that wasn't found and then searching + for some other target could crash +Qt: changes in glyph handling in the core introduced a bug in the "paper doll" + display for inventory subset +Qt: during role selection, icons for role and race showed giant ant tile after + the glyph overhaul changes +Qt: resolve a use-after-free error when saving message history +Qt: with a pick-one menu containing a pre-selected entry, clicking on that + worked to re-select it, as intended; clicking on any other entry + instead of typing the selector letter toggled off preselected entry + but failed to toggle on the explicitly selected one; clicking again + after nothing was pre-selected anymore refused to toggle anything on +Qt: don't show main window and tombstone window maximized by default +tty: redraw unexplored locations as S_unexplored rather than after + map has been partially overwritten by popup menu or text display +tty: previous change resulted in remnants of previous level being shown on + new level after level change when S_unexplored is +tty: for #wizidentify, using ^I as an unseen group accelerator to pick the + 'all' choice was incorrectly checking menuitem_invert_test() and + failing, so the 'all' choice wasn't being toggled on if user typed ^I +tty: changes to support utf8 resulted in lines of text windows being shown + starting at their second character +tty: changes to support TTY_PERM_INVENT resulted in blank inventory menu when + using the 'i' command while carrying only gold; didn't matter whether + or not TTY_PERM_INVENT was enabled during build +tty: for the !DEF_PAGER configuration, redraw screen properly if attempting + to display a file fails and tty_display_file()'s caller requests + feedback for that situation +tty: if a group accelerator matched a menu command ('^' in menu for '/') + it wouldn't work to select, just to manipulate the menu +tty: after resize changes which included screen erasure changes, ^C and yes|y + to "Really quit?" while a menu was open would lead to a panic +tty: make cursor visible again when using ! or ^Z to temporarily leave nethack +Unix: after lua changes to Makefiles, 'make spotless' for dat subdirectory + left some generated data files which should have been deleted +Unix: reject "--sX" on command line except if "X" is "cores" (so "--scores"); + single dash form still accepts "-sX" to lookup scores for "X" +Windows: new tile additions in win/share did not trigger the creation of a new + NetHackW.res file +Windows: nhl_loadlua() was missing the RDBMODE argument on the [dlb_]fopen(), + which is required on Windows to set binary mode; binary mode is + required in order to be able to reliably navigate through a file using + fseek(), ftell() and fread() +Windows: when VIRTUAL_TERMINAL_SEQUENCES was not defined, the preprocessing + would fail on consoletty.c +Windows: original fix for GLYPH_UNEXPLORED background tile merging resulted + in a new issue where the map wasn't being cleared on level changes +Windows: don't dupstr the return value of setlocale if it is NULL +Windows: nethackw.exe calculated vertical spacing for menu items based on + the height of the tileset in use, even though the tiles in the + menu were drawn at the default height of 16 anyway; get rid of + the extraneous vertical spacing between menu rows +X11: fix build failure if STATUS_HILITES is disabled +X11: was still initializing map to 'stone' instead of 'unexplored' after they + became separate glyphs +X11: for text map without color, add support for black&white ice; draw it in + inverse video to distinguish from ordinary floor +X11: if perm_invent is set in NETHACKOPTIONS or config file, start with the + persistent inventory window displayed +X11: use visctrl(response) when X11_yn_function() echoes prompt+response in + message window +X11: when trying to lookup scrollbars in order to handle scrolling via keys, + menu handling always ended up finding the top window +X11: enable horizontal scrollbar for persistent inventory window +X11: if a group accelerator matched a menu command ('^' in menu for '/') + it wouldn't work to select, just to manipulate the menu +X11: ascii_map could try to use a color value, with some added flag bits set, + as an index into the color_gcs[] and inv_color_gcs[] arrays leading + to a segfault; clear the flag bits before using the color as an index +X11+macOS: after the "bad Atom" fix (below), the persistent inventory window + crept downward every time it got updated + + +Platform- and/or Interface-Specific Fixes +----------------------------------------- +SYSCF: treat most sysconf directives that have invalid values as warnings + rather than errors; use a conservative default value and continue +curses: for vertical status, line up conditions in columns; usually two but + condense to three per line if the status window isn't tall enough + [at present, highlighting with inverse video includes trailing spaces + used to align entries in their columns--that's a feature...] +curses: indent items in perm_invent window by one space +curses: don't change the terminal's default colors +curses: remove unnecessary special handling for dark gray +curses: sometimes entering a count during menu selection caused the menu to + disappear (example was apply/loot in-out container menu with two or + more digits typed followed by non-digit); in-out menu was still active + but no longer displayed +curses: support backspace/delete when entering a count during menu selection +curses: was failing to honor menu_xxx option settings for menu interaction +curses: make extended command prompt behave more sensibly +curses: if a menu of objects contains at least one iron ball, and player is + not already in the midst of entering a count, recognize '0' as a + group accelerator rather than the start of a count +curses: obey timed_delay option +curses: support tty-style extended role/race/&c selection at start of new game +curses: implement mark_synch() and wait_synch() +curses: only convert arrow keys to hjkl or 4286 if nethack wants a direction +curses: conversion of arrows and other numpad-related function keys to digit + ignored phone-layout setting (inverted up/down) of the num_pad option +curses: ensure alt+'A' through alt+'Z' and alt+'a' through alt+'z' work + correctly with PDCURSES +curses: fix an off-by-one error when deciding whether a long line on the + bottom line of the message window can fit ">>" (curses' "--More--") +curses: selecting a partial stack, unselecting it, and then selecting it + normally did not reset the quantity to the whole stack +curses: if user's terminal was set to 'application keypad mode' (DEC VTxxx + nomenclature; set via 2 char "ESC =") and the terminfo or termcap + entry told the terminal to send 8-bit escape sequences (via 3 char + "ESC SPC G"), nethack wasn't recognizing number pad keys +curses: change petattr attributes, dropping support for curses-only ones +curses: swap the grey and no-color color initialization +curses+tty+Qt: allow changing default colors with the 'palette' config option + (only if compiled with CHANGE_COLOR) +curses: if messages have been issued during start-up (for instance, warnings + about issues in run-time config file), prompt user to press + so that they can be read before curses erases the screen +curses: when the map was narrower than the space set aside for it, wide popup + windows could write into the unused space and whatever was written + there would stick after the popup was removed +documentation: when building plain text Guidebook.txt from Guidebook.mn, avoid + attempting to use CR font; change doesn't affect building Guidebook.ps + which utilizes CR to get various instances of fixed-width text +documentation: improve Guidebook *roff formatting and prepare for use of + future release of groff 1.24.0 (pr #1280 by g-branden-robinson) +macOS: Xcode project was failing to build if the path to the NetHack source + tree contained a space; the issue was within some shell script code + contained within the project +MS-DOS: add -DSTATUES_LOOK_LIKE_MONSTERS to Makefile1.cross so the VESA mode + can display statue glyphs +MS-DOS: sample config file had same MENUCOLOR flaw as Windows (see below) +MS-DOS: implement inverse text attribute +Qt: quit if can't load tiles file instead of continuing and then segfaulting +Qt: [later] tiles load failure at startup now continues using an ascii map +Qt: use more columns for extended command selection dialog so that the number + of rows needed doesn't result in some commands being unaccessible +Qt: suppress wizard mode commands from '#' handling when not in wizard mode +Qt: organize extended command selection grid by columns instead of by rows + (first N entries down left column, next N entries down 2nd column, &c) +Qt: when selecting an extended command by typing its name, support + (aka ) in addition to to go back a character +Qt: switch to fixed-width font for menus +Qt: don't disable [cancel] button when viewing inventory or other pick-none + menus; ESC works to dismiss those and [cancel] should be the same +Qt: clicking on the window's Close button brought up a dialog offering + choices of "Save" and "Cancel"; picking Cancel sent nethack into an + infinite loop with complaints about Qt's event loop already being + active; change dialog: offer "Save and exit" or "Quit without saving" + with no opportunity to try to back out of the Close operation +Qt: add 3.6 status fields Stone, Slime, Strngl, Deaf, Lev, Fly, Ride +Qt: add Attributes, Overview, and Annotate to the "Info" pull down menu +Qt: rename menu entries game->Save to game->Save-and-exit and game->Quit + to game->Quit-without-saving +Qt: menu commands are now working; commands invoked via M-c were having that + keystroke changed to '?', bringing up nethack's help menu; now those + send #abc with just enough letters to disambiguate from other commands + ("Compilation" is one remaining problem; it yields "#version" which + brings up '#' menu subset with choices of "version" and "versionshort") +Qt: "paper doll" subset of persistent inventory has undergone several changes: + show previously missing quiver below weapon instead of duplicating + gloves there; show secondary weapon in shield slot and blank out + alternate weapon slot when two-weapon combat is active; show wielded + two-handed weapon in both the shield and primary weapon slots; show + first active light source in a previously unused slot on lower right; + show first leash-in-use in a previously unused slot on lower left +Qt: paper doll inventory view was inconsistently updated during Hallucination +Qt: when hero died, gold on tombstone only included gold in inventory, not + any additional gold inside carried containers; also, inventory gold + will be zero if bones get created for all 3.6.x and for 3.4.x+GOLDOBJ +Qt: tombstone showed newly constructed date instead of the value set up at + time of death; it only shows year but that could be wrong if player + stared at or ignored prior --More-- for long enough on 31 December +Qt: menu choices All, None, Invert were setting, unsetting, or toggling menu + entry checkboxes internally but didn't redraw the menu to show that +Qt: fix the F1/F2/Tab macro keys to not require that number_pad be On +Qt: unhighlight highlighted message (last one issued) after player has seen it +Qt: update message window's last message with player's response if it's a + prompt string for a single-character of input (ynaq or invent letter) +Qt: for line input, display the prompt+response in the message window +Qt: enable the popup_dialog WC option (result is a bit flakey but usable) +Qt: 3.6 catchup - show unexplored locations as unexplored rather than as stone +Qt: tried to honor 'showexp' but the value was unintentionally suppressed by + [lack of definition for] obsolete conditional EXP_ON_BOTL +Qt: implement --More-- prompt to support MSGTYPE=stop +Qt: for menu search, don't require clicking on the search target popup before + typing target string (was using typed letters to make menu selections + if player didn't click on the popup first) +Qt: rest ("Zz") button on the toolbar only worked when 'rest_on_space' was On + (core issue, not Qt's fault) +Qt: rename toolbar button "Get" and action menu choice "Get" to "Pick up" +Qt: status icons for alignment|hunger|encumbrance which started out centered + relative to the label text below them would shift to being left + justified when status got updated +Qt: handle '&' properly if it occurs as part of yn_function popup dialog +Qt: fix the display side of saved game selection; character names for + available save files are shown in a column of push buttons instead + of each button overwriting all the ones before it +Qt: don't clobber an existing save file after choosing "new game" in the + saved game selection widget +Qt: don't get stuck in a loop after choosing "play" while the character name + field is empty in the character selection widget +Qt: when a new message is issued, pan the message window to its left edge if + player panned it horizontally then didn't manually scroll it back +Qt: there was no way to enter extended command "#version" by typing; command + name matching was waiting to disambiguate it from "#versionshort" + and the only way to that was to type #version but + explicitly triggered rejection, cancelling '#' processing; #drop vs + "droptype, "known vs "knownclass, and #takeoff vs #takeoffall are in + similar ambiguous situation but usually invoked via keystroke +Qt: render all text windows in fixed-width font instead of just ones which + have one or more lines with four consecutive spaces; some data.base + entries do have those (usually final attribution) and some don't, + so display from one entry to another was inconsistent if default + proportional font was ever used +Qt: while a text window was shown (such as the "things that are here" popup + when stepping on items), typing commands had the input passed on to + the map and then executed; sometimes that caused the not-yet-dismissed + text window to hang +Qt: if player's run-time options specified a tiles file and it couldn't be + loaded, Qt was falling back to x11tiles just like when the default + can't be loaded; fallback to player's file plus explicit path instead +Qt: force the 'toptenwin' option On so that high scores display at end of game + is shown in a text window instead of being written to stdout where it + might not be seen (note: doesn't apply to 'nethack -s') +Qt: during role/race/&c selection, update role titles with their icons, and + also Valk eligibility, when gender is toggled +Qt: if a menu of objects contains at least one iron ball, and player is not + already in the midst of entering a count, recognize '0' as a group + accelerator rather than the start of a count +Qt: {maybe just Qt+macOS:} when viewing a text window ('V' to look at 'history' + for instance), clicking on [Search], entering a search target in the + resulting popup and clicking on [Okay] or typing , the text + window got pushed underneath the main window so seemed to go away +Qt: use idPressed signal instead of buttonPressed and mappedString instead + of mapped for recent Qt (pr #913 by chasonr) +Qt: make all NetHack menu and text windows modal +Qt: support Unicode supplementary characters (pr #1047 by chasonr) +Qt: qt_tilewidth and qt_tileheight are allocated with alloc() and need to be + freed with free(); don't use qt_tilewidth and qt_tileheight after + they have been freed; instead, retrieve the size from the glyphs + object (pr #1049 by chasonr) +Qt+macOS: fix control key (fixed all except for ^V); handle ^V as a shortcut +Qt+macOS: rename menu entry "nethack->Preferences..." for invoking nethack's + 'O' command to "Game->Run-time options" and entry "Game->Qt settings" + for making persistent Qt customizations to "nethack->Preferences..." +Qt+macOS: prevent game->Quit-without-saving from being hijacked for the nethack + menu by renaming it game->_Quit-without-saving (macOS only) +Qt+macOS: add a separate nethack->Quit menu entry with different functionality; + Command+Q invokes it +Qt+macOS: since menu entry help->"About Qt NetHack" gets hijacked and becomes + "nethack->About nethack", add a separate help->_About_Qt_NetHack_ + which stays where intended and brings up the same information +Qt+macOS: suppress unwanted "Search [______]" action from being inserted as the + first entry in the menubar's "Help" dropdown menu +sound: add a soundlib interface that consists of a specification + documented in doc/sound.txt; default 'nosound' soundlib implementation + of the specification in src/sounds.c +sound: added 'macsound' soundlib implementation for use on macOS; the + interface implementation resides in the objective C file + sound/macsound/macsound.m; built on top of the built-in AppKit + NSSound, #import , linked using -framework AppKit. +sound: added 'windsound' soundlib implementation for use on Windows; the + interface implementation resides in the file + sound/windsound/windsound.c; built on top of the win32 api, + header file mmsystem.h, linked with winmm. +sound: add 'qtsound' soundlib implementation for use on any platform + with Qt; the interface implementation resides win/Qt/qt_bind.cpp; + built on top of Qt. +tiles: add indicator of thonged portion to aklys tile +tty: role and race selection menus weren't filtering out potential choices + which got excluded by OPTIONS=align:!lawful or !neutral or !chaotic +tty: '$' can now select gold in a menu even when it isn't on current page +tty: if a menu used full screen and brought up another menu that wasn't full + screen, sometimes only a small border of background was drawn around + it with most of the map left blank until after the menu was dismissed +tty: have dismiss pick-none menus instead of acting like '>' (not + only wouldn't dismiss when not on last page, wouldn't dismiss at all) +tty: menu search via ':' would clobber part of the menu with a status line + refresh if the menu was tall enough to cover that +tty: add support for petattr +tty: if a ^C interrupt occurred while DECgraphics characters were being drawn + on the map, the "Really quit?" prompt would be illegible due to being + rendered with VT line drawing characters +tty: hide cursor unless waiting for user input; now extended to include tty + platforms that define NO_TERMS, rather than just on those using + termcap/terminfo, namely Windows console and msdos (text-mode + implemented; vga and vesa just have stubs currently) +tty+curses: if terminal goes away while in the wishing prompt, return to the + wish prompt when game is restored +Unix: when user name is used as default character name, keep hyphenated value + intact instead stripping off dash and whatever follows as if that + specified role/race/&c (worked once upon a time; broken since 3.3.0) +Unix: add "ec2-user" to the list of user names 'sysconf' classifies as generic +Unix: work-around a build issue in ubuntu 21.10 by using ifdef to skip the + define of warn_unused_result to empty string in tradstdc.h whenever + __linux__ is defined during build unless GCC_URWARN is also defined +Unix: re-do command line parsing +Unix: add ../include/nhlua.h to the alloc.o dependencies in Makefile.utl to + match Makefile.src +Unix: implement SELF_RECOVER compile-time option, on by default on linux +Unix: allow build to succeed with musl (instead of glibc), by specifying + musl=1 on the make command line +Unix: support tilde expansion for home directory path, "~/relative-path", in + command line --nethackrc=path and environment NETHACKOPTIONS=@path +user_sounds: move the message hook from inside individual window display ports + to the core where it allows MSGTYP_NOSHOW msgtyp's to still trigger + sounds to correct a reported github issue; also fixes a past reported + issue that the curses port on Windows not working with user_sounds +Windows: update for new status condition fields +Windows: include commented-out 'PORTABLE_DEVICE_PATHS' in sysconf.template +Windows: When there was no interesting background in get_bk_glyph() + in display.c, a default value of GLYPH_UNEXPLORED was returned to + the caller and then passed on to the interface; the graphical + Windows version, NetHackW.exe, was trying to use the tile mapped to + GLYPH_UNEXPLORED as a background tile to merge with the + foreground tile, so check for GLYPH_UNEXPLORED and bypass that +Windows: fix range error detected by address sanitizer in plselInitDialog() +Windows: the .nethackrc template contained a sample MENUCOLOR pattern for + "cursed .* (being worn)" which didn't work; parentheses need quotes +X11: substantial overhaul of status display, both 'fancy' and 'tty-style' +X11: extend fancy status one-turn inverse video status-change highlighting to + hunger, encumbrance, and conditions +X11: stop including unused column 0 in the map +X11: avoid 'bad Atom X Error' when perm_invent is enabled (seemingly window + manager dependent) +X11: toggling 'perm_invent' off via 'O' didn't dismiss persistent inventory + window +X11: with 'slow' resource set to False, the pop up yn_function didn't always + resize properly when re-used +X11: (possibly X11+macOS): if persistent inventory was displayed at time of + end-of-game prompting, prompting would stall until that window was + manually dismissed +X11: (possibly X11+macOS): try harder to resize the getlin() prompt, if needed, + when prompt text changes +X11: set all selectable menu lines to the same length, left justified +X11: initializing the get-extended-command widget modified memory beyond what + it dynamically allocated + + +General New Features +-------------------- +if a killer bee encounters a lump of royal jelly and there is no queen bee on + the level, the bee will eat the jelly and become a new queen +automatic annotation "gateway to Moloch's Sanctum" for vibrating square level + once that square's location becomes known (found or magic mapped); + goes away once sanctum temple is found (entered or high altar mapped) +savefile: add support to deconstruct internal data structures down into their + individual fields and save those fields instead of the entire struct +savefile: use little-endian format for fields where that makes a difference +replace build-time level compiler and dungeon compiler with run-time loading of + the dungeon and level descriptions and interpreting them via Lua +split off some of the functionality that was in makedefs (compiled-in options + build date/time, etc) so that it can be built by a cross-compiler + and accessed on the target platform +replace quest.txt and associated conversion to quest.dat via makedefs with + Lua quest texts loaded at runtime +callback lua functions from core at certain game actions +some altars are displayed in different colors (for tty and curses at least) +add 'quick_farsight' option to provide some control over random clairvoyance + where pausing to be able to browse temporarily visible aspects of the + revealed map can seem intrusive; doesn't affect clairvoyance spell +replace "money" in in-game texts with "gold" +when hallucinating, see hallucinated currencies instead of bits for an ale +when hallucinating, see hallucinated liquids when looking at water or lava + on the map +applying a spellbook hints about read charges left +wizard mode wishing for level topology can now create hidden doors (ask for + "secret door" when at a door or wall location), hidden corridor + spots ("secret corridor" at a corridor location), clouds, walls, + and (melting) ice +tiny chance for randomly created spellbooks to be Discworld novels instead + of having only one in the first book or scroll shop created (won't + occur in hero's initial inventory or NPC priest inventory or be + bestowed as a prayer boon or be found in statues) +'goldX', 'implicit_uncursed', and 'mention_walls' options changed to be + persistent across save/restore +wearing a wet towel confers "half damage from poison gas" attribute +for end of game disclosure and dumplog, show 'achievements' (previously only + available as an encoded value in xlogfile) along with 'conduct' +more grades of self-appearance than beautiful or handsome vs ugly +when 'color' if Off and 'use_inverse' is On, draw ice on the map in inverse + video if it uses the same character as room floor or as dark floor +new 'mention_decor' option; when On, describe dungeon features being stepped + on or floated/flown over even when they're not covered by objects +applying royal jelly on an egg kills, revives, or changes the egg +intelligent monsters pick up and rummage through containers +toggling 'travel' option Off now only inhibits travel by mouse click, not by + '_' command where choosing the destination provides a chance to cancel +different glyphs and symbols for stone and unexplored areas +new glyph GLYPH_NOTHING was added so !dark_room has something to be set to + now that stone could be mapped to an entirely different symbol +added several new status conditions all of which are opt-in except + the new cond_grab and cond_lava which are opt-out +tipping your cap might get a response +special levels can be flipped horizontally and/or vertically +new special level initialization routine, "swamp" +demon lords and princes suppress teleporting in Gehennom +for !fixinv option where inventory letters normally don't stick, try to put + a throw-and-return weapon back into the same inventory slot it gets + thrown from; only works if it does return and is successfully caught +wizard mode #wizborn command +include more skill information in ^X output when dual-wielding +include monk's to-hit penalty for worn suit in the status section of ^X output +item-using monsters will zap wand of undead turning at corpse-wielding hero + when the corpse is harmful +boiling a pool or fountain now creates a temporary cloud of steam +random themed rooms in the dungeons of doom +environment variables THEMERM and THEMERMFILL can be used in wizard mode to + provide some control over theme room generation +extended achievement and conduct fields for xlogfile +record amount of gold in hero's possession in xlogfile +new objects: amulets of flying and guarding, helm of caution, + gold dragon scale mail and set of gold dragon scales +new monsters: displacer beast ('f') and genetic engineer ('Q'), gold dragon + and baby gold dragon (both 'D') +make camera flash which reveals previously unseen map features or objects or + monsters record those on the hero's map; monsters revert to 'unseen' +boolean options can optionally have the form "name:value" with value taken + from among "true", "yes", "on", or 1 and "false", "no", "off", or 0 +record number of wishes and artifact wishes in xlogfile +give feedback for '#chat' directed at walls +add 'Sokoban' conduct, tracking the number of times the special Sokoban rules + which incur luck penalties have been violated; don't report it + unless/until Sokoban branch has been entered +reduce verbosity when a mind flayer attacks a headless monster; when a + tentacle-to-head attack hits but fails to accomplish anything skip + remaining attacks (mind flayer has 3, master mind flayer has 5) +add section marker [] support to run-time config file; CHOOSE section1,section2 + followed by [section1] ... [section2] ... forced all the rest of the + file to be part of the last section; that still works the same, but [] + can be used to terminate the last section and revert to common options + for the remainder of the file +render the color names in the corresponding color when using the pick-a-color + menu for adding status highlights or menu colors via 'O' +reading blessed scroll of teleportation confers one-shot teleport control +mild zombie apocalypse +list lamps and lanterns in charging prompt +let tourists read conical hats +when "?i" (show key bindings) displays commands and their keys, also show + commands without any key (so ones useable via '#', or possibly menu, + only; the majority are debugging commands) +assign default key binding for or to execute #terrain +assign M-X to #exploremode +make #herecmdmenu and #therecmdmenu autocomplete +add 'sortdiscoveries' option to control output of '\' and '`' commands +include an indication of monsters' health during farlook feedback (including + /M and autodescribe); also include it in death reason when killed by + a monster: "killed by {an uninjured newt,a heavily injured mumak}" +[later: suppress the indication of monsters' health] +add support for a single monster species to have distinct male, female, + and gender-neutral naming terms +add support for a single monster species to have distinct male and female + tiles +consolidate several monsters that differed only by their gender into their + single species +added wizmgender debugging command to display female monsters in red inverse; + helpful for debugging gender-related matters on tty; currently ignored + on other window ports [later: changed from command to boolean option] +record number of encountered bones levels in xlogfile +add bonesless to extended conducts field in xlogfile +show bones levels information in enlightenment at end of game or in explore + and wizmode +for #wizintrinsic, use any counts entered during menu selection +give feedback when boolean options are toggled interactively ('O' command) +'|' command (#perminv) for interacting with persistent inventory display + (curses and X11 only) +menu_shift_left, menu_shift_right menu command keys; default '{' and '}' + (curses for perm_invent only; implemented for X11 too but menus for + it lack horizontal scroll bars so the shifts don't work there) +using 'f' while quiver is empty and 'autoquiver' is Off when wielding a + thrown-and-return weapon will throw that weapon instead of filling + the quiver (inspired by xNetHack) +3.6's tribute: add one new passage to Sourcery, three to Small Gods, one to + Lords and Ladies, two to Soul Music, three to Interesting Times, four + to Maskerade, three to Hogfather, two to Jingo, four to The Last + Continent, four to Carpe Jugulum, three to The Fifth Elephant, five + to The Truth, six to Thief of Time, six to The Last Hero, four to + The Amazing Maurice, five to Night Watch, four to The Wee Free Men, + four to Monstrous Regiment, two to A Hat Full of Sky +monsters can see and remember hero resistances +monsters can gain resistances by eating corpses +menu for what-is command supports /^ and /" to view a list of nearby or whole + level visible and remembered traps +spiders will occasionally spin webs when moving around +drinking a burning potion of oil will cure being turned into slime +new bigroom variants, a boulder maze, hexagons, pillars +vomiting on an altar provokes the deities wrath +branch stairs have a different glyph, show up in yellow color in tty +duration of confusion when drinking booze depends upon hunger state +using 'D' allows dropping items picked up previously +bones piles can be ransacked by adjacent monsters +decaying globs of {ooze,pudding,slime} shrink over time based on their total + weight, eventually to nothing; for combined globs it can take a long + time, and while doing so they no longer give the tainted corpse food + poisoning effect when eaten +track peak maximum HP and peak maximum energy/power; no noticeable effect +give some dragon armor extra effects when worn +issue messages during last stage of food poisoning/terminal illness countdown + when hero's demise is imminent +drinking blessed potion of full healing heals wounded legs, either hero's or + steed's (when riding, wounded leg injury applies to steed, not hero) +drinking uncursed potion of full healing or blessed potion of extra healing + heal hero's wounded legs when not riding; no effect on steed if riding +cancellation explodes most magical traps +reading a blessed scroll of light has a chance to improve bless/curse state + of wielded Sunsword or worn gold dragon scales/mail similar to dipping + those into holy water; cursed scroll has chance to worsen the state +added a chronicle of major events, and optional live logging of those +paranoid_confirm:swim to prevent accidental dunking into dangerous liquids; + joins paranoid_confirm:pray as the default setting +paranoid_confirm:trap to confirm entering a known trap unless it is harmless; + like revised paranoid_confirm:pray, requires y/n response; add + paranoid_confirm:Confirm to require yes/no instead +extend 'paranoid_confirm:trap' to request confirmation when entering visible + gas cloud regions +paranoid_confirm:Autoall to confirm picking 'A' in menustyle:Full filter menu +looking at a monster will indicate whether it is asleep, and waking up a + monster yields a message +extend farlook's ", asleep" to ", can't move (paralyzed or sleeping + or busy)" for timed sleep and also ", meditating" for monster + that is waiting for hero to approach +add body part terminology for spiders; enhance it for cockatrices +context sensitive item usage menu from inventory, aka "item actions" +pets are more likely to follow you closely if you are carrying something they + really like to eat; behave as if you are carrying such whenever you + are standing on stairs so that pets will try harder to come to you +allow setting msgtype in SOUND line +display detected door traps and chest traps as trapped doors and trapped + chests rather than as fake bear traps +if built with DEBUG enabled and running in wizard mode, starting play with + DEBUGFILES=seethru in environment makes clouds on the Plane of Air, + water on Plane of Water, and fumaroles on Plane of Fire be transparent +add wizard mode #wizkill command to remove monster(s) from play +some quest nemeses release a cloud of poisonous gas when they die +taming magic acting on an already tame creature might make it become tamer +eliminate scimitar skill and have scimitars use saber skill +simplified configuration options menu +rudimentary key rebinding in game options +experimental #saveoptions command to allow saving configuration settings +mouse buttons can be bound to extended commands +hero poly'd into purple worm can gain intrinsics from digesting whole monster +add some tins of spinach to monk's quest (vegan => no Str from giant corpses) +very large humanoids can wear mummy wrappings +for ranger characters, shooting any type of arrow while wielding the Longbow + of Diana gets an extra +1 to multi-shot +change the #vanquished command from debug-only to general user command +add 'sortvanquished' option to be able to set the preferred sort order without + using 'm #vanquished' and to have it persist across save/restore +when sorting vanquished monsters by monster class, treat the Riders as a + separate class from major demons +add #genocided command +have 'I u' mention whether there are any unpaid items on the floor (unusual + but not impossible); it doesn't itemize them or show shop price +add items given a Japanese name when playing as a Samurai to discoveries list +make music improvisations more varied and interesting, as well as useful +give a helpful tip when first entering "farlook" mode +add a boolean option tips to disable all of the helpful tips +add a tutorial level +engravings appear on the map display; 'whatis' can list them ('/e', '/E') +option to create the character deaf +add conduct for petless +preceding #overview with the 'm' prefix brings up the overview display as a + menu allowing selection of any visited level to #annotate; it also + shows every level visited rather than just the "interesting" ones +include monster size in feedback for wand of probing and stethoscope +crystal armor is now subject to cracking damage rather than outright breakage +when a doppelganger takes on mplayer (fake hero) form, usually choose role + from the high scores file; name too if visible at the time +can now write unknown spellbook without need of Luck when spell is known; + if spell becomes known without having read its book (potential divine + gift), writing the book while the spell is still fresh will succeed +new status highlight rule type for hitpoints: "criticalhp" rule overrides + hit point rules if current HP is so low that prayer will consider it + to be major problem; applies to hitpointbar as well as HP status +high skill level in martial arts or bare-handed combat sometimes hits twice +answering '?' at the "genocide what?" prompt (for either monster class + or single species) runs the #genocided command to show what types of + monsters have already been genocided and then re-prompts +throwing the silver bell (or other invocation item, or the Amulet) to the + quest leader will identify it instead of being treated as an attack +applying gold pieces will flip one and report "heads" or "tails"; with a stack + of more than one, normally the flipped coin will rejoin the stack +during enlightenment and end-of-game disclosure, use contraction "n't" + for " not" +give feedback about the thaw status of ice terrain +allow #dip '-' in a fountain, pool, or sink to clean slippery fingers/gloves +allow #dip potions into a sink to get a hint about what they are, similar to + dropping rings into a sink; dipping other stuff causes water damage + so could be used to blank out scrolls and books +when restoring, show current level's player-applied annotation if there is one +have farlook of a grave report the engraving on the headstone if it's known +the '*' command (list inventory items in use) now shows items in a specific + order: amulet, ring on main hand (potentially affected by cursed + one-handed weapon), ring on off hand, blindfold, wielded weapon, + secondary or alternate weapon, quiver, suit, cloak, shield, helmet, + gloves, boots, shirt, lit lamps and candles, leashes attached to pets, + instead of by object class (sortpack) or inventory letter (!sortpack); + new perm_invent+perminv_mode==inuse does the same +allow the ')', '[', '(', '=', '"', and '*' commands to be preceded by the 'm' + prefix to force a menu where the player can pick an item and choose + a context-sensitive item action for it; some give a menu even without + the prefix and for those, same item selection and action can be used +hot ground (Gehennom / Plane of Fire) often destroys dropped potions +erinyes overhaul; they now attempt to punish heroes who have violated their + alignment and get stronger with greater alignment abuse +accessibility options to tell where on map a message happened (accessiblemsg), + to notify when a monster is spotted (spot_monsters), and when + a monster moved (mon_movement), when hero takes damage (showdamage), + when interesting map locations change (mention_map) +accessibility command #lookaround which will describe what hero can see +if hero is punished or tethered to a buried iron ball and has no inventory (or + only carries gold or embedded dragon scales or both), a nymph might + remove the chain when finding nothing else to steal +'showvers' option (and companion 'versinfo' option) to include program version + in the status display so that it will be visible for screenshots or + during streaming video +'query_menu' option to use a menu when asked certain yes/no questions +pyrolisk eggs explode when broken +pauper-option to start the character with no possessions +wand of secret door detection, spell of detect unseen, and wizard mode ^E now + flash the cursor at each location where detection finds something +'selectsaved' lists "name-role-race-gend-algn" instead of just "name" in the + menu of save files available to be restored +'selectsaved' prefixes "name-role-race-gend-algn" with "- " for normal play, + "X " for explore mode, or "D " for debug mode if any of the games + shown in its menu weren't saved during normal play; if they're all + normal play, the prefix is suppressed +tourists gain experience by "taking photos" of new creatures, and + going to new dungeon levels +healers gain experience by healing pets +blessed scroll of destroy armor asks which armor to destroy if wearing more + than one armor; otherwise it'll destroy a cursed armor, or erodes + random armor +archeologists' fedora is lucky +telepathic hero can discern which particular monster just read a scroll +add "make fetch-docs" to download pre-formatted documentation +monsters will use throw-and-return weapons such as an aklys +archeologists can identify scrolls by deciphering their labels +monster destroy armor -spell first erodes armor +iron footwear protects the wearer against certain floor-based traps +ring of stealth prevents hero from leaving tracks +the game now automatically tracks which sell prices and buy prices you have + seen for each type of item; these are visible in the discoveries list, + and can also be shown elsewhere using the new 'price_quotes' option +new shields: shield of shock resistance, shield of drain resistance +new wand: wand of stasis +early-game monsters always miss with their first use of an attack wand +new command #toggle which can be used to toggle a boolean option + + +Platform- and/or Interface-Specific New Features +------------------------------------------------ +user_sounds: provide an experimental mechanism for terminal-side sounds similar + to the method used for vt_tiledata; new option vt_sounddata that also + requires compile-time definition of TTY_SOUND_ESCCODES (also requires + terminal-side code external to NetHack to recognize the sequence and + act on it) +curses: implement 'selectsaved', restore via menu of saved games +curses: implement selecting menu items via mouse +curses: 'windowborders' can be set to 3 or 4 to suppress perm_invent borders + to provide slightly more room for actual inventory info +curses: if panictrace is triggered, reset the terminal before giving backtrace +curses: if a message is marked urgent, override message suppression initiated + by user having typed ESC at previous More>> prompt +curses: implement a dialog for the windowborders option +curses: implement the windowcolors option +Qt: the "paper doll" inventory subset can be controlled via the "Qt Settings" + dialog box ("Preferences..." on macOS) +Qt: draw a border around each tile in the paper doll inventory; when BUC is + known for a doll item, change the border's color and thicken it +Qt: letting the mouse hover over the paper doll shows a tool tip describing + the object--or lack of same--in the slot under the pointer +Qt: clicking on the paper doll runs the #seeall command (inventory of wielded + and worn items plus tools [lamps, leashes] actively in use; in other + words, same set of things whose tiles are used to populate the doll) +Qt: clicking on the status window runs the #attributes command (^X) +Qt: add a Search button to the toolbar +Qt: support the 'hitpointbar' option +Qt: add Filter, Layout, and Reset buttons to the extended command selector; + Filter is only useful in wizard mode, allowing changing the set of + extended commands between "all", "normal mode only", "extra wizard + mode only"; Layout redisplays the grid of command buttons, toggling + from down columns to across rows or vice versa; Reset puts both back + to their default settings and clears any pending typed input +Qt: [later] augment extended command selection dialog's Filter to add a + fourth subset, those commands which autocomplete when typed for tty, + typically commands with no keystroke or only meta character keystroke; + that makes Filter useful in normal mode (much shorter list of choices) +Qt: add '#' as "Extended-commands" to the 'game' dropdown menu +Qt: add tool tips to the extended command selector's buttons to show command + descriptions +Qt: add tool tips to the icons shown in the status window +Qt: to play user sounds with volume, replace QSound with QSoundEffect; also + restores user sound support for Qt6 +tiles: male and female variations in monsters.txt; tested only with tile2bmp + conversion utility so far; also supported by tilemap utility to + generate tile.c +tty: use bright colors directly on supporting terminals +tty: if a message is marked urgent, override message suppression initiated + by user having typed ESC at previous --More-- prompt +Unix: can define NOSUSPEND in config.h or src/Makefile's CFLAGS to prevent + unixconf.h from enabling SUSPEND without need to modify unixconf.h +Unix: support --nethackrc=filename on the command line; same effect as + NETHACKOPTIONS='@filename' but leaves NETHACKOPTIONS available for + specifying options; --no-nethackrc is same as --nethackrc=/dev/null +Windows: implement MSGHANDLER (pr #749 by argrath) +Windows: Add configuration to support Curses on WinGUI (pr #1028 by chasonr) +X11: implement 'selectsaved', restore via menu of saved games +X11: echo getline prompt and response (wishes, applying names) to message + window and dumplog message history +X11: fix map expose area, no longer leaving black bars on the map +tty and curses: support italic as text attribute +tty and curses: when hitpointbar is displayed, make it blink if current HP is + below the "critical HP" threshold (where prayer treats being injured + as major trouble) + + +NetHack Community Patches (or Variation) Included +------------------------------------------------- +hallucinatory trap names (pr #174 by copperwater) +autounlock feature originally from unnethack (pr #228 by copperwater) +replace "You feel cold" message for freezing unseen door (pr #265 by + copperwater) +applying a candelabrum with no candles gives a tip (pr #265 by copperwater) +candelabrum now reads "(n of 7 candles attached)" (pr #265 by copperwater) +show appropriate message on throne when crowned (pr #265 by copperwater) +choir chanting, bathing in darkness for death by Moloch (pr #265 by + copperwater) +remove "iron hook" unidentified description (pr #265 by copperwater) +suppress "Unknown command" messages in the dumplog. (pr #265 by copperwater) +give player message informing them they can use #enhance (pr #265 by + copperwater) +neutral sacrifices disappear in a cloud of smoke (pr #265 by copperwater) +call potion bottles by nonsensical names if hallucinating (pr #265 by + copperwater) +add a default message for chatting to gnomes (pr #265 by copperwater) +better reporting directions for impossible() (pr #265 by copperwater) +underwater fire scroll causes vaporization (pr #265 by copperwater) +default shk sell prompt to N (pr #265 by copperwater) +teach non-mindless monsters about the Castle trapdoors (pr #265 by copperwater) +always print a message when the hero teleports (pr #265 by copperwater) +always print a message when the hero level teleports (pr #265 by copperwater) +remove Sokoban luck penalties for actions you can't cheat with (pr #260 by + copperwater) +sounds for minotaurs (pr #298 by Kestrel Gregorich-Trevor) +correct the Guidebook descriptions for msdos video_width and video_height to + state that they work with video:vesa; the video:vga setting that was + described there forces the 640x480x16 mode where video_width and + video_height don't operate (pr #294 by chasonr) +redo rndmonst() to operate in a single pass (pr #286 by copperwater ) +fix the "stuck pets" issue (issue #329) +allow themed room subrooms to be filled (pr #347 by copperwater) +allow rereading spellbooks to refresh memory at any time (pr #261 by + copperwater) +allow themed rooms constrained by level difficulty (pr #344 by copperwater) +add a varied form of LIBNH nethack library contribution (pr #385, #403 + by apowers313) +add cross-compile to WASM (pr #385, #403, #412 by apowers313) +differentiating gendered monster tiles (pr #430 by Kestrel Gregorich-Trevor) +check bones data directly for deja vu messages (pr #374 by entrez) +unify code for extracting an object from a monster's inventory (pr #455 by + copperwater) +make engraving an occupation (pr #460 by copperwater) +fpostfx index out of bounds when eating standard eggs (pr#547 by janne-hmp) +"readable" Hawaiian shirt designs (pr#407 by entrez) +permit blind feeling for objects on trap door and fix up msgs when dropping + on trapdoor (pr#574 by entrez) +travel from 'interesting position' (pr #575 by entrez) +running on ice sent hero in weird directions (pr #588 by copperwater) +delete extra lines in Guidebook.mn (pr #590 by argrath) +supply missing changes on Guidebook.tex (pr #591 by argrath) +fix out-of-bounds access of xdir and ydir in farlook (pr #592 by copperwater) +variation of imp's period-speak (pr #602 by Vivit-R) +fix m-prefix movement into warning symbol (pr #573 by entrez) +pointer precedence fix incrementing flagcounter in do.c (pr #612 by argrath) +MAX_RADIUS defines the outer bound of the radius table, so leave it at 15 + to avoid out-of-bound access in view_from() and do_clear_area() + (pr #613 by argrath) +variable attknum was declared without initialization, and was used in + find_roll_to_hit() (pr #615 by argrath) +check for NULL lua_State before calling lua_close() (pr #616 by argrath) +use %lu, not %d, in format string in timer_sanity_check() (pr #617 by argrath) +bad cast making sp_lev chameleon light source (pr #625 by entrez) +add Ray Chason's adaptation of nethack's Qt5 interface to work with Qt6 (issue + #525 followup comment by chasonr) +mingw32 build updates to replace contents of sys/windows/GNUmakefile and new + sys/windows/GNUmakefile.depend (pr #661 by feiyunw) +mark various pointers to const char as const pointers (pr #624 by argrath) +function fill_special_room() in sp_lev.c was dereferencing a pointer + argument prior to a subsequent check for a NULL pointer that + resulted in an early function return (pr #669 by argrath) +function repairable_damage() in shk.c was dereferencing a pointer + argument prior to a subsequent check for a NULL pointer that + resulted in an early function return (pr #671 by argrath) +function savelev() in save.c was dereferencing a NHFILE pointer for + nhfp->mode prior to a subsequent check for nhfp being NULL + to trigger a call to panic() if it was; move the check for NULL + above that usage (pr #675 by argrath) +function tin_details() in eat.c was passing an obj pointer to + tin_variety() where it was dereferenced; move the tin_details() + NULL check above that tin_variety() call (pr #676 by argrath) +remove unnecessary null checks from christen_orc() (pr #681 by argrath) +mark high altars in altarmask (pr #748 by entrez) +split kicking empty space into separate function (pr #754 by argrath) +split adjusting attributes into separate function (pr #757 by argrath) +split getting damages with a kick into separate function (pr #758 by argrath) +split fixing curse trouble into separate function (pr #765 by argrath) +Handle -eaux plurals in makeplural/makesingular (pr #767 by entrez) +mdisplacem stoning and gloves had test backwards (pr #773 by entrez) +writing type-named scrolls (pr #551 by entrez) +more cases where newcham() gives messages (pr #775 by copperwater) +lua: instance cleanup should not be applied to classes (by ToxicFrog) +fix memory leaks related to selection_new() (pr #782 by argrath) +wished-for doors in wizmode always vertical (pr #788 by entrez) +vampire shapeshifting in a door (pr #794 by entrez) +split "act_on_act" into separate function (pr #777 by argrath) +unnecessary null-check on parsesymbols() (pr #793 by argrath) +split cleaning-up on gd_move() into separate function (pr #791 by argrath) +from xNetHack: better handling for monsters putting on equipment; fixes + issue #843: "Mon dies. Mon puts on . The seemingly dead Mon + rises as a vampire." +add Unicode support to DOS Curses port (pr #889 by chasonr) +add Unicode support to Win32 (pr #903 by chasonr) +add Unicode support to Qt (pr #910 by chasonr) +add Unicode, IBMgraphics and DECgraphics support to X11 (pr #923 by chasonr) +add some glue code for those that might wish to build with 3rd party fmod + sound library support (pr #962 by MrEveryDay98) +add new options 'nopick_dropped' and 'pickup_stolen' options to avoid + auto-pickup of items dropped by hero and to auto-pickup things + previously stolen from hero if moved upon while autopickup is On; both + bypass pickup_types and autopickup_exceptions (pr #1140 by entrez) +fix msg_window:combination and TTY getlin() ^P (pr #1155 by entrez) +remove a null sobj check from gold_detect that was situated after + dereferences had already been done (pr #1173 by argrath) and + adjust prototype in extern.h +check for valid indexes of def_monsyms[] and def_oc_syms[] in + choose_classes_menu() (pr #1179 by argrath) +split damage from acid potion into separate function (pr #1195 by argrath) +add swallow and explosion glyphs to glyph_to_cmap() (pr #1277 by ars3niy) +split "cannot_push" on moverock_done() into a separate function (pr #1282 + by argrath) +split making pits on do_earthquake() into a separate function and + eliminate some gotos on do_earthquake() (pr #1287 by argrath) +update the WASM cross-compile to work with the current + code (pr #1331 by guillaumebrunerie) +add silver maces (pr #1405 by disperse) +applied several source comment spelling or grammar fixes that were linked + to an old rec.games.roguelike.nethack post from May 2006 + by Arthur J. O'Dwyer +modernize code of LaTeX Guidebook (pr #1473 by Daniel Clow) +restore ability for a characteristic also resets exercise/abuse for that + characteristic (pr #1403 by greg-kennedy) +cross-compilation for the Amiga on Linux (pr #1494 by ingpaschke) + + +Code Cleanup and Reorganization +------------------------------- +new core file insight.c - move enlightenment and conduct from cmd.c to it, + also move vanquished, genocided, and extinct monsters from end.c, + and move one-line stethoscope/probing feedback from priest.c +move majority of global variables into instance_globals struct g +move zeroobj, zeromonst, zeroany into const_globals struct cg +remove STATIC_DCL, STATIC_OVL, STATIC_VAR, STATIC_PTR +old Qt moved from win/Qt to win/Qt3 and files renamed to use qt3_ prefix +more current Qt for Qt version 4 and 5 moved from win/Qt4 to win/Qt; qt4 + moniker changed to qt_ +window-port-interface: add_menu() modified to take a more general itemflags + parameter to support uses beyond just 'preselected' +window-port-interface: start_menu() modified to take a new mbehavior parameter +add some bounds checking to tabexpand (doesn't prevent the apparent compiler + optimization bug that put homebrew macOS executable into endless loop) +unified breamm and breamu +added some stair helper functions +unified the code for finding a queen bee +unified the code for multishot class bonus code +unified the code for obtaining the inventory letter value for sortloot +unified the code for (un)locking boxes in inventory +unified the code for finding room pos for some features +unified the code for revealing hiding monsters for mvm attacks +options overhaul: moved the option definitions into include/optlist.h; + combined the boolean and compound options into one allopt[] array; + each option has its own individual function for setting the option, + for retrieving the option value, and for processing the option + following its selection in the 'O' menu, added doc/options.txt file. +function reglyph_darkroom() relocated from options.c to display.c +resurrect 'makedefs -m' to be able to derive default mons[].difficulty values + suitable for assigning to new or changed monsters +convert obj->oextra->omid from pointer to scalar +get rid of unused obj->oextra->olong +relocated unmaintained code to outdated folder, specifically sys/amiga, + sys/atari, sys/be, sys/mac, sys/os2, sys/wince, win/Qt3, win/gem, + win/gnome, include/amiconf.h, include/beconf.h, include/def_os2.h, + include/os2conf.h, include/macconf.h, include/tosconf.h, + include/wceconf.h +removed SYSFLAGS conditional code +removed MFLOPPY conditional code +get rid of 3.6.1 workaround needed to retain compatibility with 3.6.0 bones + files after fix for 3.3.0 through 3.6.0 bug for invalid 'bonesid' + designation in bones of quest levels +add an additional note to mextra.h and obj.h comments that reminds people to + appropriately init new fields if they need to initialize to something + other than zero +rework stairs structure into a linked list +move 'restoring' to the program_state struct; add corresponding 'saving'; + both used to enforce no updating of status lines or of persistent + inventory when the relevant activity is in progress +unify special attack damages from separate you-hit-monster, monster-hits-you, + and monster-hits-monster into functions by damage type +unify trap effects for hero and monster stepping on the trap by trap type +replace the single permonst mname field with male, female, and gender-neutral + names pmnames[NUM_MGENDERS] fields +adjust window port interface to pass a pointer to a glyph_info struct which + contains the glyph itself, the ttychar, the color, the glyphflags, + and the symset index; this affects two window port calls that get + passed glyphs: print_glyph() and add_menu(). +switch from k&r C to C99 +remove the game-compile dependencies on any pre-generated header files +date.h dependency and inclusion is removed and comparable functionality is + produced at runtime; REPRODUCIBLE_BUILD capability will need to be + reviewed and adjusted +pm.h dependency and inclusion is removed and comparable functionality is + produced by moving the monster definitions from monst.c into new header + file called monsters.h, then taking advantage of the C preprocessor to + generate appropriate enum values during compile +onames.h dependency and inclusion is removed and comparable functionality is + produced by moving object definitions from objects.c into new header + file called objects.h, then taking advantage of the C preprocessor to + generate appropriate enum values during compile +artilist.h is used to generate appropriate artifact enum values by the C + preprocessor during compile +remove requirement of object probabilities adding to 1000 +delete obsolete variable 'g.monstermoves' (copperwater pull request #579) +expand glyphs to map wall styles that can vary between main, mines, gehennom, + knox and sokoban; tile interfaces were already doing that on the fly + by swapping several tiles in and out on those levels +expand glyphs to map altars that can vary between unaligned, chaotic, + neutral, lawful and other; tty was already doing that on the fly + per map cell via display code +explosion types are mapped and can vary between dark, noxious, muddy, wet, + magical, fiery and frosty; tile interfaces already had unique tiles + for each and tty was altering the color on the fly via per map cell + via display code +expand glyphs to uniquely represent things that are at the top of a pile of + objects (piletops); some window ports were already doing that on the + fly via a glyphmap flag, but NetHack itself had no awareness beyond + setting the glyphmap flag within the display code +expand glyphs to uniquely represent male and female variations of monsters, + pets, ridden monsters, detected monsters and the statues of monsters; + tile interfaces were already mapping them uniquely via a glyphmap flag + and mapping to separate tiles within the window port code, but NetHack + itself had very little awareness beyond setting the glyphmap flag + within the display code +added glyph_to_body_corpsenm(glyph) and glyph_to_statue_corpsenm(glyph) + macros to display.h for use by pager.c; the game core code is better + off using such display macros/functions for all glyph_to_* mappings + that are needed, rather than resorting to direct references of glyph + offsets that could change as the set of glyphs expands or gets adjusted +map_glyphinfo() now simply references an internal array that maps each unique + glyph to a color, a ttychar, or a tile, also to a set of glyphflags + that confirm some unique characteristics of that glyph; the glyph + mappings are set at game init/restore after config file processing, and + are reset upon level change, or when some game options are adjusted + in-game that could have an impact on the mappings, but they remain + stable between those events +added MG_MALE glyphflag to complement the MG_FEMALE glyphflag that was there +remove obsolete roles[].femalenum and rename roles[].malenum to roles[].mnum; + likewise for races[] +add git submodule support to the Makefiles by specifying git=1 or GIT=1 on the + make command +add TT_NONE==0, renumber other u.utraptype values so that TT_BEARTRAP isn't 0 +for Planes of Water and Air, save the air bubbles and clouds with the level + rather than as game state; affects wizard mode ^V and #wizmakemap +switch to a flags arg on newcham() in place of the pair of boolean args +replace some old 'time_t' hackery in system.h and hacklib.c with something + less obtrusive in unixconf.h +remove the per dungeon level door limit +remove various '#if LINT' hacks used to suppress warnings from pre-ANSI 'lint' +VMS: removed NO_VSNPRINTF conditional code +remove the window port get_menu_coloring() calls from all the existing window + ports, and implement the functionality on the core-side of the + interface prior to calling the window port's foo_add_menu() function +remove TEXTCOLOR build option +relocate general-purpose function choose_classes_menu(), from + options.c to windows.c +remove register from variable declarations +make glyph_to_cmap() a function instead of a macro diff --git a/doc/fixes5-0-1.txt b/doc/fixes5-0-1.txt new file mode 100644 index 000000000..09549b72e --- /dev/null +++ b/doc/fixes5-0-1.txt @@ -0,0 +1,81 @@ +NHDT-Branch: NetHack-5.0 $:$NHDT-Revision: 1.0 $ $NHDT-Date: 1778152494 2026/05/07 11:14:54 $ + +General Fixes and Modified Features +----------------------------------- +fix some cross-compile package filenames that still referenced 370 instead + of 500 +Use NHV macro (NHV=500) for filenames in Makefiles and/or hints files to make + it less likely to overlook or miss them next time +early startup options such as --showpaths could be run non-interactively, so + ensure that getret() doesn't prompt and wait for user input +fix issue where the new game startup message was stating 'Work-in-progress' + even when NH_DEVEL_STATUS was set to NH_STATUS_POSTRELEASE +if 'mention_decor' was set in config file or NETHACKOPTIONS, + starting the game told you that "you are standing on stairs which lead + out of the dungeon", even when the player entered the tutorial where that + wasn't true +doc: use full URL for nethack.org in Guidebook.mn +doc: fix a paste error in Guidebook.tex +doc: fix spelling correction in nethack.6 + +Platform- and/or Interface-Specific Fixes +----------------------------------------- +Amiga: fall back to text mode when tile mode is not viable +Amiga: Detect Workbench depth, display-database MaxDepth, and free chip RAM + if any signals AMIV can't run (e.g. A1000 with 4-colour WB) +Amiga: swap windowprocs to amii_procs before opening any screens +Amiga: disable SYSCF, drop sysconf from package; assure_syscf_file() was + killing the binary when run outside NetHack: was breaking normal + launches +Amiga: honor __stack under libnix; reference __stkinit so the linker pulls + swapstack.o from libnix.a; without it the program runs on the + inherited shell stack and crashes inside Lua / level-gen +Amiga: provide a real v4 UUID via get_nhuuid +Amiga: ship as a NetHack drawer with drawer icon and README +Amiga: ship Workbench icons for the binary and text files +Amiga: fix misleading fallback warning and stale comment +Amiga: stop rendering CLR_BLACK and CLR_WHITE as inverse video +Amiga: default number_pad:1 in shipped nethack.cnf +Amiga: promote AMIGA_INTUITION to supported so it shows up in version info +Amiga: wire altmeta option to sysflags.altmeta +libnh: update get_nhuuid() for libnhmain +libnh: sys/libnh/libnhmain.c: drop `static` on `whoami()` +libnh: rewrote sys/unix/hints/macOS.500: rewrote the libnh.a rule. The + `ar rcs libnh.a $(HOBJ) $(LIBNHSYSOBJ) liblua-$(LUA_VERSION).a` had + four problems: (a) ar archives liblua.a as a single opaque member + that macOS ld can't dereference, (b) date.o (DATE_O, kept separate + from HOBJ) was never archived, so `populate_nomakedefs` and + `nomakedefs` were missing, (c) hacklib.a was likewise omitted, and + (d) HOBJ already contains $(SYSOBJ) (with unixmain.o) and $(WINOBJ) + (the tty windowport), which duplicated symbols from libnhmain.o / + winshim.o. +libnh: sys/libnh/libnhmain.c: gate the emscripten-only code in get_nhuuid + with `#ifdef __EMSCRIPTEN__` instead of `#ifdef NHUUID` +libnh: sys/unix/hints/macOS.500 in the WANT_LIBNH block, add an explicit + `recover: lua_support` dependency (gated by MAKEFILE_TOP). When + $(GAME) is overridden to empty, the regular `recover: $(GAME)` chain + no longer triggers `lua_support`, so include/nhlua.h never gets + generated and recover.c's transitive #include of hack.h fails. +macOS: fix ncurses build with Homebrew +WASM: resolve some build failures in 'make CROSS_TO_WASM=1' +WASM: hints file cross-pre2.500 update to CFLAGS to include -DNHUUID + + + +General New Features +-------------------- + + +Platform- and/or Interface-Specific New Features +------------------------------------------------ + + +NetHack Community Patches (or Variation) Included +------------------------------------------------- + + +Code Cleanup and Reorganization +------------------------------- +add Contributing.md with some guidelines for making a pull request that + is in an acceptable format + diff --git a/doc/fixesX-X-X.txt b/doc/fixesX-X-X.txt new file mode 100644 index 000000000..462dd5f60 --- /dev/null +++ b/doc/fixesX-X-X.txt @@ -0,0 +1,28 @@ +$NHDT-Branch$:$NHDT-Revision$ $NHDT-Date$ + +General Fixes and Modified Features +----------------------------------- + + +Fixes to Post-X.X.X Problems that Were Exposed Via git Repository +------------------------------------------------------------------ + + +Platform- and/or Interface-Specific Fixes +----------------------------------------- + + +General New Features +-------------------- + + +Platform- and/or Interface-Specific New Features +------------------------------------------------ + + +NetHack Community Patches (or Variation) Included +------------------------------------------------- + + +Code Cleanup and Reorganization +------------------------------- diff --git a/doc/lev_comp.6 b/doc/lev_comp.6 deleted file mode 100644 index fdb1945a7..000000000 --- a/doc/lev_comp.6 +++ /dev/null @@ -1,588 +0,0 @@ -.TH LEV_COMP 6 "25 May 2015" NETHACK -.de ND -.ds Nd \\$3 -.. -.de NB -.ds Nb \\$2 -.. -.de NR -.ds Nr \\$2 -.. -.ND $NHDT-Date: 1524689549 2018/04/25 20:52:29 $ -.NB $NHDT-Branch: NetHack-3.6.0 $ -.NR $NHDT-Revision: 1.7 $ -.ds Na Kenneth Lorber -.SH NAME -lev_comp \- NetHack special levels compiler -.SH SYNOPSIS -.B lev_comp -[ -.B \-w -] -[ -.I files -] -.PP -If no arguments are given, it reads standard input. -.SH DESCRIPTION -.PP -.I Lev_comp -is a special level compiler for NetHack version 3.2 and higher. It -takes description files as arguments and produces level files that can -be loaded by NetHack at runtime. -.PP -The purpose of this tool is to provide NetHack administrators and -implementors with a convenient way for adding special levels to the -game, or modifying existing ones, without having to recompile the -entire world. -.PP -The -.B \-w -option causes -.I lev_comp -to perform extra checks on the level and display extra warnings, however -these warnings are sometimes superfluous, so they are not normally displayed. - -.SH GRAMMAR -.PP -.LP -.nf -.ta +8n +8n +8n +8n - -file : /* nothing */ - | levels - ; - -levels : level - | level levels - ; - -level : maze_level - | room_level - ; - -maze_level : maze_def flags lev_init messages regions - ; - -room_level : level_def flags lev_init messages rreg_init rooms corridors_def - ; - -level_def : LEVEL_ID ':' string - ; - -lev_init : /* nothing */ - | LEV_INIT_ID ':' CHAR ',' CHAR ',' BOOLEAN ',' BOOLEAN ',' light_state ',' walled - ; - -walled : BOOLEAN - | RANDOM_TYPE - ; - -flags : /* nothing */ - | FLAGS_ID ':' flag_list - ; - -flag_list : FLAG_TYPE ',' flag_list - | FLAG_TYPE - ; - -messages : /* nothing */ - | message messages - ; - -message : MESSAGE_ID ':' STRING - ; - -rreg_init : /* nothing */ - | rreg_init init_rreg - ; - -init_rreg : RANDOM_OBJECTS_ID ':' object_list - | RANDOM_MONSTERS_ID ':' monster_list - ; - -rooms : /* Nothing - dummy room for use with INIT_MAP */ - | roomlist - ; - -roomlist : aroom - | aroom roomlist - ; - -corridors_def : random_corridors - | corridors - ; - -random_corridors: RAND_CORRIDOR_ID - ; - -corridors : /* nothing */ - | corridors corridor - ; - -corridor : CORRIDOR_ID ':' corr_spec ',' corr_spec - | CORRIDOR_ID ':' corr_spec ',' INTEGER - ; - -corr_spec : '(' INTEGER ',' DIRECTION ',' door_pos ')' - ; - -aroom : room_def room_details - | subroom_def room_details - ; - -subroom_def : SUBROOM_ID ':' room_type ',' light_state ',' subroom_pos ',' room_size ',' string roomfill - ; - -room_def : ROOM_ID ':' room_type ',' light_state ',' room_pos ',' room_align ',' room_size roomfill - ; - -roomfill : /* nothing */ - | ',' BOOLEAN - ; - -room_pos : '(' INTEGER ',' INTEGER ')' - | RANDOM_TYPE - ; - -subroom_pos : '(' INTEGER ',' INTEGER ')' - | RANDOM_TYPE - ; - -room_align : '(' h_justif ',' v_justif ')' - | RANDOM_TYPE - ; - -room_size : '(' INTEGER ',' INTEGER ')' - | RANDOM_TYPE - ; - -room_details : /* nothing */ - | room_details room_detail - ; - -room_detail : room_name - | room_chance - | room_door - | monster_detail - | object_detail - | trap_detail - | altar_detail - | fountain_detail - | sink_detail - | pool_detail - | gold_detail - | engraving_detail - | stair_detail - ; - -room_name : NAME_ID ':' string - ; - -room_chance : CHANCE_ID ':' INTEGER - ; - -room_door : DOOR_ID ':' secret ',' door_state ',' door_wall ',' door_pos - ; - -secret : BOOLEAN - | RANDOM_TYPE - ; - -door_wall : DIRECTION - | RANDOM_TYPE - ; - -door_pos : INTEGER - | RANDOM_TYPE - ; - -maze_def : MAZE_ID ':' string ',' filling - ; - -filling : CHAR - | RANDOM_TYPE - ; - -regions : aregion - | aregion regions - ; - -aregion : map_definition reg_init map_details - ; - -map_definition : NOMAP_ID - | map_geometry MAP_ID - ; - -map_geometry : GEOMETRY_ID ':' h_justif ',' v_justif - ; - -h_justif : LEFT_OR_RIGHT - | CENTER - ; - -v_justif : TOP_OR_BOT - | CENTER - ; - -reg_init : /* nothing */ - | reg_init init_reg - ; - -init_reg : RANDOM_OBJECTS_ID ':' object_list - | RANDOM_PLACES_ID ':' place_list - | RANDOM_MONSTERS_ID ':' monster_list - ; - -object_list : object - | object ',' object_list - ; - -monster_list : monster - | monster ',' monster_list - ; - -place_list : place - | place ',' place_list - ; - -map_details : /* nothing */ - | map_details map_detail - ; - -map_detail : monster_detail - | object_detail - | door_detail - | trap_detail - | drawbridge_detail - | region_detail - | stair_region - | portal_region - | teleprt_region - | branch_region - | altar_detail - | fountain_detail - | mazewalk_detail - | wallify_detail - | ladder_detail - | stair_detail - | gold_detail - | engraving_detail - | diggable_detail - | passwall_detail - ; - -monster_detail : MONSTER_ID chance ':' monster_c ',' m_name ',' coordinate - monster_infos - ; - -monster_infos : /* nothing */ - | monster_infos monster_info - ; - -monster_info : ',' string - | ',' MON_ATTITUDE - | ',' MON_ALERTNESS - | ',' alignment - | ',' MON_APPEARANCE string - ; - -object_detail : OBJECT_ID object_desc - | COBJECT_ID object_desc - ; - -object_desc : chance ':' object_c ',' o_name ',' object_where object_infos - ; - -object_where : coordinate - | CONTAINED - ; - -object_infos : /* nothing */ - | ',' curse_state ',' monster_id ',' enchantment optional_name - | ',' curse_state ',' enchantment optional_name - | ',' monster_id ',' enchantment optional_name - ; - -curse_state : RANDOM_TYPE - | CURSE_TYPE - ; - -monster_id : STRING - ; - -enchantment : RANDOM_TYPE - | INTEGER - ; - -optional_name : /* nothing */ - | ',' NONE - | ',' STRING - ; - -door_detail : DOOR_ID ':' door_state ',' coordinate - ; - -trap_detail : TRAP_ID chance ':' trap_name ',' coordinate - ; - -drawbridge_detail: DRAWBRIDGE_ID ':' coordinate ',' DIRECTION ',' door_state - ; - -mazewalk_detail : MAZEWALK_ID ':' coordinate ',' DIRECTION - ; - -wallify_detail : WALLIFY_ID - ; - -ladder_detail : LADDER_ID ':' coordinate ',' UP_OR_DOWN - ; - -stair_detail : STAIR_ID ':' coordinate ',' UP_OR_DOWN - ; - -stair_region : STAIR_ID ':' lev_region ',' lev_region ',' UP_OR_DOWN - ; - -portal_region : PORTAL_ID ':' lev_region ',' lev_region ',' string - ; - -teleprt_region : TELEPRT_ID ':' lev_region ',' lev_region teleprt_detail - ; - -branch_region : BRANCH_ID ':' lev_region ',' lev_region - ; - -teleprt_detail : /* empty */ - | ',' UP_OR_DOWN - ; - -lev_region : region - | LEV '(' INTEGER ',' INTEGER ',' INTEGER ',' INTEGER ')' - ; - -fountain_detail : FOUNTAIN_ID ':' coordinate - ; - -sink_detail : SINK_ID ':' coordinate - ; - -pool_detail : POOL_ID ':' coordinate - ; - -diggable_detail : NON_DIGGABLE_ID ':' region - ; - -passwall_detail : NON_PASSWALL_ID ':' region - ; - -region_detail : REGION_ID ':' region ',' light_state ',' room_type prefilled - ; - -altar_detail : ALTAR_ID ':' coordinate ',' alignment ',' altar_type - ; - -gold_detail : GOLD_ID ':' amount ',' coordinate - ; - -engraving_detail: ENGRAVING_ID ':' coordinate ',' engraving_type ',' string - ; - -monster_c : monster - | RANDOM_TYPE - | m_register - ; - -object_c : object - | RANDOM_TYPE - | o_register - ; - -m_name : string - | RANDOM_TYPE - ; - -o_name : string - | RANDOM_TYPE - ; - -trap_name : string - | RANDOM_TYPE - ; - -room_type : string - | RANDOM_TYPE - ; - -prefilled : /* empty */ - | ',' FILLING - | ',' FILLING ',' BOOLEAN - ; - -coordinate : coord - | p_register - | RANDOM_TYPE - ; - -door_state : DOOR_STATE - | RANDOM_TYPE - ; - -light_state : LIGHT_STATE - | RANDOM_TYPE - ; - -alignment : ALIGNMENT - | a_register - | RANDOM_TYPE - ; - -altar_type : ALTAR_TYPE - | RANDOM_TYPE - ; - -p_register : P_REGISTER '[' INTEGER ']' - ; - -o_register : O_REGISTER '[' INTEGER ']' - ; - -m_register : M_REGISTER '[' INTEGER ']' - ; - -a_register : A_REGISTER '[' INTEGER ']' - ; - -place : coord - ; - -monster : CHAR - ; - -object : CHAR - ; - -string : STRING - ; - -amount : INTEGER - | RANDOM_TYPE - ; - -chance : /* empty */ - | PERCENT - ; - -engraving_type : ENGRAVING_TYPE - | RANDOM_TYPE - ; - -coord : '(' INTEGER ',' INTEGER ')' - ; - -region : '(' INTEGER ',' INTEGER ',' INTEGER ',' INTEGER ')' - ; -.fi -.PP -.I NOTE: -.br -Lines beginning with '#' are considered comments. -.PP -The contents of a "MAP" description of a maze is a rectangle showing the exact -level map that should be used for the given part of a maze. -Each character in the map corresponds to a location on the screen. -Different location types are denoted using different ASCII characters. -The following characters are recognized. -To give an idea of how these are used, see the EXAMPLE, below. -The maximum size of a map is normally 76 columns by 21 rows. -.LP -.nf -.ta +8n +8n +8n -\&'-' horizontal wall -\&'|' vertical wall -\&'+' a doorway (state is specified in a DOOR declaration) -\&'A' open air -\&'B' boundary room location (for bounding unwalled irregular regions) -\&'C' cloudy air -\&'I' ice -\&'S' a secret door -\&'H' a secret corridor -\&'{' a fountain -\&'\\' a throne -\&'K' a sink -\&'}' a part of a moat or other deep water -\&'P' a pool -\&'L' lava -\&'W' water (yes, different from a pool) -\&'T' a tree -\&'F' iron bars -\&'#' a corridor -\&'.' a normal room location (unlit unless lit in a REGION declaration) -\&' ' stone -.fi -.SH EXAMPLE -.PP -Here is an example of a description file (a very simple one): -.LP -.nf -.ta +8n +8n +8n -MAZE : "fortress", random -GEOMETRY : center , center -MAP -}}}}}}}}} -}}}|-|}}} -}}|-.-|}} -}|-...-|} -}|.....|} -}|-...-|} -}}|-.-|}} -}}}|-|}}} -}}}}}}}}} -ENDMAP -MONSTER: '@', "Wizard of Yendor", (4,4) -OBJECT: '"', "Amulet of Yendor", (4,4) -# a hell hound flanking the Wiz on a random side -RANDOM_PLACES: (4,3), (4,5), (3,4), (5,4) -MONSTER: 'd', "hell hound", place[0] -# a chest on another random side -OBJECT: '(', "chest", place[1] -# a sack on a random side, with a diamond and maybe a ruby in it -CONTAINER: '(', "sack", place[2] -OBJECT: '*', "diamond", contained -OBJECT[50%]: '*', "ruby", contained -# a random dragon somewhere -MONSTER: 'D', random, random -# 3 out of 4 chance for a random trap in the EAST end -TRAP[75%]: random, (6,4) -# an electric eel below the SOUTH end -MONSTER: ';', "electric eel", (4,8) -# make the walls non-diggable -NON_DIGGABLE: (0,0,8,8) -TELEPORT_REGION: levregion(0,0,79,20), (0,0,8,8) -.fi -.PP -This example will produce a file named "fortress" that can be integrated into -one of the numerous mazes of the game. -.PP -Note especially the final, TELEPORT_REGION specification. This says -that level teleports or other non-stairway arrivals on this level can -land anywhere on the level except the area of the map. This shows the -use of the ``levregion'' prefix allowed in certain region specifications. -Normally, regions apply only to the most recent MAP specification, but -when prefixed with ``levregion'', one can refer to any area of the -level, regardless of the placement of the current MAP in the level. -.SH AUTHOR -.PP -Jean-Christophe Collet, David Cohrs. -.SH "SEE ALSO" -.PP -dgn_comp(6), nethack(6) -.SH BUGS -.PP -Probably infinite. -Most importantly, still needs additional bounds checking. -.SH COPYRIGHT -This file is Copyright (C) \*(Na and was last modified \*(Nd (version -\*(Nb:\*(Nr). -NetHack may be freely redistributed. See license for details. diff --git a/doc/lev_comp.txt b/doc/lev_comp.txt deleted file mode 100644 index d6745409e..000000000 --- a/doc/lev_comp.txt +++ /dev/null @@ -1,563 +0,0 @@ -LEV_COMP(6) Games Manual LEV_COMP(6) - - - -NAME - lev_comp - NetHack special levels compiler - -SYNOPSIS - lev_comp [ -w ] [ files ] - - If no arguments are given, it reads standard input. - -DESCRIPTION - Lev_comp is a special level compiler for NetHack version 3.2 and - higher. It takes description files as arguments and produces level - files that can be loaded by NetHack at runtime. - - The purpose of this tool is to provide NetHack administrators and - implementors with a convenient way for adding special levels to the - game, or modifying existing ones, without having to recompile the - entire world. - - The -w option causes lev_comp to perform extra checks on the level and - display extra warnings, however these warnings are sometimes superflu- - ous, so they are not normally displayed. - - -GRAMMAR - file : /* nothing */ - | levels - ; - - levels : level - | level levels - ; - - level : maze_level - | room_level - ; - - maze_level : maze_def flags lev_init messages regions - ; - - room_level : level_def flags lev_init messages rreg_init rooms corridors_def - ; - - level_def : LEVEL_ID ':' string - ; - - lev_init : /* nothing */ - | LEV_INIT_ID ':' CHAR ',' CHAR ',' BOOLEAN ',' BOOLEAN ',' light_state ',' walled - ; - - walled : BOOLEAN - | RANDOM_TYPE - ; - - flags : /* nothing */ - | FLAGS_ID ':' flag_list - ; - - flag_list : FLAG_TYPE ',' flag_list - | FLAG_TYPE - ; - - messages : /* nothing */ - | message messages - ; - - message : MESSAGE_ID ':' STRING - ; - - rreg_init : /* nothing */ - | rreg_init init_rreg - ; - - init_rreg : RANDOM_OBJECTS_ID ':' object_list - | RANDOM_MONSTERS_ID ':' monster_list - ; - - rooms : /* Nothing - dummy room for use with INIT_MAP */ - | roomlist - ; - - roomlist : aroom - | aroom roomlist - ; - - corridors_def : random_corridors - | corridors - ; - - random_corridors: RAND_CORRIDOR_ID - ; - - corridors : /* nothing */ - | corridors corridor - ; - - corridor : CORRIDOR_ID ':' corr_spec ',' corr_spec - | CORRIDOR_ID ':' corr_spec ',' INTEGER - ; - - corr_spec : '(' INTEGER ',' DIRECTION ',' door_pos ')' - ; - - aroom : room_def room_details - | subroom_def room_details - ; - - subroom_def : SUBROOM_ID ':' room_type ',' light_state ',' subroom_pos ',' room_size ',' string roomfill - ; - - room_def : ROOM_ID ':' room_type ',' light_state ',' room_pos ',' room_align ',' room_size roomfill - ; - - roomfill : /* nothing */ - | ',' BOOLEAN - ; - - room_pos : '(' INTEGER ',' INTEGER ')' - | RANDOM_TYPE - ; - - subroom_pos : '(' INTEGER ',' INTEGER ')' - | RANDOM_TYPE - ; - - room_align : '(' h_justif ',' v_justif ')' - | RANDOM_TYPE - ; - - room_size : '(' INTEGER ',' INTEGER ')' - | RANDOM_TYPE - ; - - room_details : /* nothing */ - | room_details room_detail - ; - - room_detail : room_name - | room_chance - | room_door - | monster_detail - | object_detail - | trap_detail - | altar_detail - | fountain_detail - | sink_detail - | pool_detail - | gold_detail - | engraving_detail - | stair_detail - ; - - room_name : NAME_ID ':' string - ; - - room_chance : CHANCE_ID ':' INTEGER - ; - - room_door : DOOR_ID ':' secret ',' door_state ',' door_wall ',' door_pos - ; - - secret : BOOLEAN - | RANDOM_TYPE - ; - - door_wall : DIRECTION - | RANDOM_TYPE - ; - - door_pos : INTEGER - | RANDOM_TYPE - ; - - maze_def : MAZE_ID ':' string ',' filling - ; - - filling : CHAR - | RANDOM_TYPE - ; - - regions : aregion - | aregion regions - ; - - aregion : map_definition reg_init map_details - ; - - map_definition : NOMAP_ID - | map_geometry MAP_ID - ; - - map_geometry : GEOMETRY_ID ':' h_justif ',' v_justif - ; - - h_justif : LEFT_OR_RIGHT - | CENTER - ; - - v_justif : TOP_OR_BOT - | CENTER - ; - - reg_init : /* nothing */ - | reg_init init_reg - ; - - init_reg : RANDOM_OBJECTS_ID ':' object_list - | RANDOM_PLACES_ID ':' place_list - | RANDOM_MONSTERS_ID ':' monster_list - ; - - object_list : object - | object ',' object_list - ; - - monster_list : monster - | monster ',' monster_list - ; - - place_list : place - | place ',' place_list - ; - - map_details : /* nothing */ - | map_details map_detail - ; - - map_detail : monster_detail - | object_detail - | door_detail - | trap_detail - | drawbridge_detail - | region_detail - | stair_region - | portal_region - | teleprt_region - | branch_region - | altar_detail - | fountain_detail - | mazewalk_detail - | wallify_detail - | ladder_detail - | stair_detail - | gold_detail - | engraving_detail - | diggable_detail - | passwall_detail - ; - - monster_detail : MONSTER_ID chance ':' monster_c ',' m_name ',' coordinate - monster_infos - ; - - monster_infos : /* nothing */ - | monster_infos monster_info - ; - - monster_info : ',' string - | ',' MON_ATTITUDE - | ',' MON_ALERTNESS - | ',' alignment - | ',' MON_APPEARANCE string - ; - - object_detail : OBJECT_ID object_desc - | COBJECT_ID object_desc - ; - - object_desc : chance ':' object_c ',' o_name ',' object_where object_infos - ; - - object_where : coordinate - | CONTAINED - ; - - object_infos : /* nothing */ - | ',' curse_state ',' monster_id ',' enchantment optional_name - | ',' curse_state ',' enchantment optional_name - | ',' monster_id ',' enchantment optional_name - ; - - curse_state : RANDOM_TYPE - | CURSE_TYPE - ; - - monster_id : STRING - ; - - enchantment : RANDOM_TYPE - | INTEGER - ; - - optional_name : /* nothing */ - | ',' NONE - | ',' STRING - ; - - door_detail : DOOR_ID ':' door_state ',' coordinate - ; - - trap_detail : TRAP_ID chance ':' trap_name ',' coordinate - ; - - drawbridge_detail: DRAWBRIDGE_ID ':' coordinate ',' DIRECTION ',' door_state - ; - - mazewalk_detail : MAZEWALK_ID ':' coordinate ',' DIRECTION - ; - - wallify_detail : WALLIFY_ID - ; - - ladder_detail : LADDER_ID ':' coordinate ',' UP_OR_DOWN - ; - - stair_detail : STAIR_ID ':' coordinate ',' UP_OR_DOWN - ; - - stair_region : STAIR_ID ':' lev_region ',' lev_region ',' UP_OR_DOWN - ; - - portal_region : PORTAL_ID ':' lev_region ',' lev_region ',' string - ; - - teleprt_region : TELEPRT_ID ':' lev_region ',' lev_region teleprt_detail - ; - - branch_region : BRANCH_ID ':' lev_region ',' lev_region - ; - - teleprt_detail : /* empty */ - | ',' UP_OR_DOWN - ; - - lev_region : region - | LEV '(' INTEGER ',' INTEGER ',' INTEGER ',' INTEGER ')' - ; - - fountain_detail : FOUNTAIN_ID ':' coordinate - ; - - sink_detail : SINK_ID ':' coordinate - ; - - pool_detail : POOL_ID ':' coordinate - ; - - diggable_detail : NON_DIGGABLE_ID ':' region - ; - - passwall_detail : NON_PASSWALL_ID ':' region - ; - - region_detail : REGION_ID ':' region ',' light_state ',' room_type prefilled - ; - - altar_detail : ALTAR_ID ':' coordinate ',' alignment ',' altar_type - ; - - gold_detail : GOLD_ID ':' amount ',' coordinate - ; - - engraving_detail: ENGRAVING_ID ':' coordinate ',' engraving_type ',' string - ; - - monster_c : monster - | RANDOM_TYPE - | m_register - ; - - object_c : object - | RANDOM_TYPE - | o_register - ; - - m_name : string - | RANDOM_TYPE - ; - - o_name : string - | RANDOM_TYPE - ; - - trap_name : string - | RANDOM_TYPE - ; - - room_type : string - | RANDOM_TYPE - ; - - prefilled : /* empty */ - | ',' FILLING - | ',' FILLING ',' BOOLEAN - ; - - coordinate : coord - | p_register - | RANDOM_TYPE - ; - - door_state : DOOR_STATE - | RANDOM_TYPE - ; - - light_state : LIGHT_STATE - | RANDOM_TYPE - ; - - alignment : ALIGNMENT - | a_register - | RANDOM_TYPE - ; - - altar_type : ALTAR_TYPE - | RANDOM_TYPE - ; - - p_register : P_REGISTER '[' INTEGER ']' - ; - - o_register : O_REGISTER '[' INTEGER ']' - ; - - m_register : M_REGISTER '[' INTEGER ']' - ; - - a_register : A_REGISTER '[' INTEGER ']' - ; - - place : coord - ; - - monster : CHAR - ; - - object : CHAR - ; - - string : STRING - ; - - amount : INTEGER - | RANDOM_TYPE - ; - - chance : /* empty */ - | PERCENT - ; - - engraving_type : ENGRAVING_TYPE - | RANDOM_TYPE - ; - - coord : '(' INTEGER ',' INTEGER ')' - ; - - region : '(' INTEGER ',' INTEGER ',' INTEGER ',' INTEGER ')' - ; - - NOTE: - Lines beginning with '#' are considered comments. - - The contents of a "MAP" description of a maze is a rectangle showing - the exact level map that should be used for the given part of a maze. - Each character in the map corresponds to a location on the screen. - Different location types are denoted using different ASCII characters. - The following characters are recognized. To give an idea of how these - are used, see the EXAMPLE, below. The maximum size of a map is nor- - mally 76 columns by 21 rows. - - '-' horizontal wall - '|' vertical wall - '+' a doorway (state is specified in a DOOR declaration) - 'A' open air - 'B' boundary room location (for bounding unwalled irregular regions) - 'C' cloudy air - 'I' ice - 'S' a secret door - 'H' a secret corridor - '{' a fountain - '\' a throne - 'K' a sink - '}' a part of a moat or other deep water - 'P' a pool - 'L' lava - 'W' water (yes, different from a pool) - 'T' a tree - 'F' iron bars - '#' a corridor - '.' a normal room location (unlit unless lit in a REGION declaration) - ' ' stone - -EXAMPLE - Here is an example of a description file (a very simple one): - - MAZE : "fortress", random - GEOMETRY : center , center - MAP - }}}}}}}}} - }}}|-|}}} - }}|-.-|}} - }|-...-|} - }|.....|} - }|-...-|} - }}|-.-|}} - }}}|-|}}} - }}}}}}}}} - ENDMAP - MONSTER: '@', "Wizard of Yendor", (4,4) - OBJECT: '"', "Amulet of Yendor", (4,4) - # a hell hound flanking the Wiz on a random side - RANDOM_PLACES: (4,3), (4,5), (3,4), (5,4) - MONSTER: 'd', "hell hound", place[0] - # a chest on another random side - OBJECT: '(', "chest", place[1] - # a sack on a random side, with a diamond and maybe a ruby in it - CONTAINER: '(', "sack", place[2] - OBJECT: '*', "diamond", contained - OBJECT[50%]: '*', "ruby", contained - # a random dragon somewhere - MONSTER: 'D', random, random - # 3 out of 4 chance for a random trap in the EAST end - TRAP[75%]: random, (6,4) - # an electric eel below the SOUTH end - MONSTER: ';', "electric eel", (4,8) - # make the walls non-diggable - NON_DIGGABLE: (0,0,8,8) - TELEPORT_REGION: levregion(0,0,79,20), (0,0,8,8) - - This example will produce a file named "fortress" that can be inte- - grated into one of the numerous mazes of the game. - - Note especially the final, TELEPORT_REGION specification. This says - that level teleports or other non-stairway arrivals on this level can - land anywhere on the level except the area of the map. This shows the - use of the ``levregion'' prefix allowed in certain region specifica- - tions. Normally, regions apply only to the most recent MAP specifica- - tion, but when prefixed with ``levregion'', one can refer to any area - of the level, regardless of the placement of the current MAP in the - level. - -AUTHOR - Jean-Christophe Collet, David Cohrs. - -SEE ALSO - dgn_comp(6), nethack(6) - -BUGS - Probably infinite. Most importantly, still needs additional bounds - checking. - -COPYRIGHT - This file is Copyright (C) Kenneth Lorber and was last modified - 2018/04/25 (version NetHack-3.6.0:1.7). NetHack may be freely redis- - tributed. See license for details. - - - -NETHACK 25 May 2015 LEV_COMP(6) diff --git a/doc/lua.adoc b/doc/lua.adoc new file mode 100644 index 000000000..456503569 --- /dev/null +++ b/doc/lua.adoc @@ -0,0 +1,1614 @@ += NetHack lua +:toc: right + + +== Core functions + +Functions exposed from the NetHack core. They are all in the `nh` table. + +All core functions involving xy coordinates interpret these as relative to the +last defined map or room. + + +=== abscoord + +Convert a room- or map-relative coordinate to absolute. +Can accept one table with x and y keys (and in that case, returns similar), +or two integer values (and returns two integer values) +des, nh, and obj routines all treat inputs as relative coordinates, but this is +here in case an absolute one is needed for some reason (debugging?). + +Example: + + local ax, ay = nh.abscoord(x, y); + local coord = nh.abscoord({ x = 10, y = 15 }); + + +=== an + +Returns a string with "a " or "an " prepended to it. + +Example: + + local str = nh.an("unicorn"); + + +=== callback + +Add or remove a lua function to callback list. +First argument is the callback list, second is the name of the lua function to be called. +Two arguments adds the callback, if optional 3rd argument is true, removes the callback. +Cannot add the same function to the same callback list does nothing. + +|=== +| cmd_before | called before an extended command is executed. The command name is given as a parameter. If this function returns false, the command will not execute. +| level_enter | called when hero enters the level for the first time. +| level_leave | called when hero leaves the level. +| end_turn | called after player input is handled. May not be exact turn, if eg. hero is running or otherwise occupied. +|=== + +Example: + + nh.callback("level_enter", "tutorial_enter"); + nh.callback("level_enter", "tutorial_enter", true); + + +=== debug_flags + +Set debugging flags. + +|=== +| mongen | boolean | Do monsters generate +| hunger | boolean | Does hero's hunger-state increase +| overwrite_stairs | boolean | Allow special-file commands overwrite the stairs +| prevent_pline | boolean | Prevent messages going out to the UI +|=== + +Example: + + nh.debug_flags({ mongen = false, hunger = false }); + + +=== dnum_name + +Returns the full dungeon name (as defined in dungeon.lua) for the dungeon +number given as parameter. + +Example: + + local dungeon_name = nh.dnum_name(u.dnum); + + +=== doturn + +Execute gameloop once, or until multi-turn action is done if +optional boolean parameter is true. + +Example: + + nh.doturn(); + + +=== dump_fmtstr + +Returns a string replacing special format chars with game data. +Only available if NetHack was compiled with DUMPLOG. + +|=== +| %% | literal '%' +| %t | game start, timestamp +| %T | current time, timestamp +| %d | game start, YYYYMMDDhhmmss +| %D | current time, YYYYMMDDhhmmss +| %v | game version, eg. '5.0.0-0' +| %u | UID +| %n | player name +| %N | first character of player name +|=== + +Example: + + local filename = nh.dump_fmtstr("/tmp/nethack.%n.%d.log"); + + +=== eckey + +Return the key bound to an extended command, or the full extended +command name, if it is not bound to any key. + +Example: + + local k = nh.eckey("help"); + + +=== flip_level + +Flip the level horizontally or vertically. + +Example: + + nh.flip_level(1); + + +=== getlin + +Asks the player for a text to enter, and returns the entered string. + +Example: + + local str = nh.getlin("What do you want to call this?"); + + +=== getmap + +Get information about the map location. +Returns a table with the following elements: + +[%header] +|=== +| field name | type | description +| glyph | integer | +| typ | integer | terrain type +| typ_name | text | name of terrain type +| mapchr | text | <<_map_characters,map character>> +| seenv | integer | seen vector +| horizontal | boolean | +| lit | boolean | +| waslit | boolean | +| roomno | integer | room number +| edge | boolean | +| candig | boolean | +| has_trap | boolean | +| flags | table | See below +|=== + +[%header] +|=== +| field name | type | description +| nodoor | boolean | door +| broken | boolean | door +| isopen | boolean | door +| closed | boolean | door +| locked | boolean | door +| trapped | boolean | door +| shrine | boolean | altar +| looted | boolean | throne, tree, fountain +| swarm | boolean | tree +| warned | boolean | fountain +| pudding | boolean | sink +| dishwasher | boolean | sink +| ring | boolean | sink +|=== + +Example: + + local x = 20; + local y = 10; + local loc = nh.getmap(x,y); + nh.pline("Map location at (" .. x .. "," .. y .. ) is " .. (loc.lit and "lit" or "unlit") ); + local loc2 = nh.getmap({ x = 18, y = 16 }); + + +=== get_config + +Get current value of a boolean or a compound configuration option. + +Example: + + local wt = nh.get_config("windowtype"); + + +=== gettrap + +Get trap info at x,y +Returns a table with the following elements: + +[%header] +|=== +| field name | type | description +| tx, ty | integer | trap coordinates +| ttyp | integer | trap type +| ttyp_name | text | name of trap type +| tseen | boolean | trap seen by you? +| madeby_u | boolean | trap made by you? +| once | boolean | trap is deleted once triggered +| tnote | integer | note of a squeaky board trap +| launchx, launchy, launch2x, launch2y | integer | coordinates of a boulder for a rolling boulder trap +| conjoined | integer | encoded directions for a [spiked] pit. +|=== + +Example: + + local t1 = nh.gettrap(x, y); + local t2 = nh.gettrap({ x = 10, y = 15 }); + + +=== has_timer_at + +Does location at x,y have a timer? + +Example: + + local has_melttimer = nh.has_timer_at(x,y, "melt-ice"); + + +=== deltrap + +Delete a trap at x,y + +Example: + + nh.deltrap(x, y); + nh.deltrap({ x = 10, y = 10 }); + + +=== impossible + +Issue an impossible, signaling a possible error in the code. + +Example: + + nh.impossible("Something errory happened!"); + + +=== ing_suffix + +Construct a gerund (a verb formed by appending "ing" to a noun). + +Example: + + local str = nh.ing_suffix("foo"); + + +=== int_to_objname + +Convert integer value to object name and class. +Returns two strings, the object base name and the class character. +The returned strings may be empty if an error occurred. + +Example: + + local oname, oclass = nh.int_to_objname(45); + + +=== int_to_pmname + +Convert integer value to monster type name. + +Example: + + local pmname = nh.int_to_pmname(12); + + +=== is_genocided + +Is specific monster type genocided? Returns a boolean value. + +Example: + + local x = nh.is_genocided("vampire"); + + +=== level_difficulty + +Returns an integer value describing the level difficulty. +Normally this is the level's physical depth from the surface. + +Example: + + local diff = nh.level_difficulty(); + + +=== makeplural + +Pluralize the given string. + +Example: + + local str = nh.makeplural("zorkmid"); + + +=== makesingular + +Make the given string singular. + +Example: + + local str = nh.makesingular("zorkmids"); + + +=== menu + +Show a menu to the player. + +Synopsis: + + s = nh.menu(prompt, default, pickx, { option1, option2, ... } ); + +* prompt is a string. +* default is the default returned value, if player cancelled the menu. +* pickx is how many entries user is allowed to choose, one of "none", "one" or "any". + +Options is a table with either { "key" = "text" }, or { { key : "a", text: "text of option a"} }. + +Example: + + local selected = nh.menu("prompt", default, pickX, { "a" = "option a", "b" = "option b" }); + local selected = nh.menu("prompt", default, pickX, { {key:"a", text:"option a"}, {key:"b", text:"option b"} } ); + + +=== parse_config + +Parse string as if it was read from a config file. +Always call parse_config_errors afterwards to check for any parsing errors. + +Example: + + nh.parse_config("OPTIONS=color"); + + +=== parse_config_errors + +Returns any errors found when parsing a config file string with parse_config. + +Example: + + nh.parse_config("OPTIONS=color\nOPTIONS=!color"); + local errors = nh.parse_config_errors(); + nh.pline("Line: " .. errors[1].line .. ", " .. errors[1].error); + + +=== peek_timer_at + +When does timer at location at x,y trigger? +See <<_timer_types>>. + +Example: + + local melttime = nh.peek_timer_at(x,y, "melt-ice"); + local melttime = nh.peek_timer_at({x=5,y=6}, "melt-ice"); + + +=== pline + +Show the text in the message area. +Second parameter is an optional boolean; if true, force a `--more--` prompt. + +Example: + + nh.pline("Message text to show."); + nh.pline("Waiting for user.", true); + + +=== pushkey + +Push a key into the command queue. + +Example: + + nh.pushkey("i"); + + +=== random + +Generate a random number. + +Example: + + nh.random(10); -- returns a number between 0 and 9, inclusive. + nh.random(1,5); -- same as 1 + nh.random(5); + + +=== rn2 + +Generate a random number. + +Example: + + nh.rn2(10); -- returns a number between 0 and 9, inclusive. + + +=== s_suffix + +Return a string converted to possessive. + +Example: + + local str = nh.s_suffix("foo"); + + +=== stairways + +Returns an array of stairway data. Each entry is a hash with the following keys: + +|=== +| x, y | location of the stairs on the map +| up | boolean, is it up stairs? +| ladder | boolean, is it a ladder? +| dnum | dungeon number where the stairs lead to +| dlevel | dungeon level where the stairs lead to +|=== + +Example: + + local stairs = nh.stairways(); + for k, v in pairs(stairs) do + nh.pline("stair[" .. k .. "]:(" .. v.x .. "," .. v.y .. ")," .. tostring(v.up)); + end + + +=== start_timer_at + +Start a timer at location x,y, with trigger time of `when` - relative to current turn. +See <<_timer_types>>. + +Example: + + nh.start_timer_at(x,y, "melt-ice", when); + nh.start_timer_at({x=7,y=8}, "melt-ice", when); + + +=== stop_timer_at + +Stop a timer at location x,y. +See <<_timer_types>>. + +Example: + + nh.stop_timer_at(x,y, "melt-ice"); + nh.stop_timer_at({x=5,y=6}, "melt-ice"); + + +=== text + +Show long texts in a menu window. Wordwraps automatically. + +Example: + + nh.text("long long long string\nwith newlines too."); + + +=== variable + +Set or get a global variable. These are persistent, saved and restored along with the game. +Supports only strings, booleans, numbers, or tables. + +Example: + + nh.variable("test", 10); + local ten = nh.variable("test"); + nh.variable("tbl", { a = 1, b = "foo" }); + local tbl = nh.variable("tbl"); + + +=== verbalize + +Show the text in the message area as if someone said it, obeying eg. hero's deafness. + +Example: + + nh.verbalize("Message to say."); + + +== Special level functions + +Functions for creating special levels. They are in the `des` table. + +All special level functions involving xy coordinates interpret these as relative +to the last defined map or room. + + +=== altar + +Create an altar of certain type and alignment. + +* align is one of "noalign", "law", "neutral", "chaos", "coaligned", "noncoaligned", or "random", + defaulting to "random". +* type is one of "altar", "shrine", or "sanctum", defaulting to "altar". + +Example: + + des.altar({ x=6, y=12 }); + des.altar({ coord = {5, 10}, align = "noalign", type = "altar" }); + + +=== corridor + +Create a random corridor from one room to another. + +* srcwall and destwall are one of "all", "random", "north", "west", "east", or "south", defaulting to "all". + +Example: + + des.corridor({ srcroom=1, srcdoor=2, srcwall="north", destroom=2, destdoor=1, destwall="west" }); + + +=== door + +Create a door at a coordinate on the map, or in a room's wall. +When adding a door to a <<_room>>, it must be added after the subrooms in the room. + +* state is one of "random", "open", "closed", "locked", "nodoor", "broken", or "secret", defaulting to "random". + +Example: + + des.door({ x = 1, y = 1, state = "nodoor" }); + des.door({ coord = {1, 1}, state = "nodoor" }); + des.door({ wall = "north", pos = 3, state = "secret" }); + des.door("nodoor", 1, 2); + + +=== drawbridge + +Create a drawbridge. Location is where the open drawbridge would be, +and there should be a wall when moving one step towards the diven direction; +this is where the portcullis will be placed. + +* dir is one of "north", "south", "west", "east", or "random". +* state is one of "open", "closed", or "random". + +Example: + + des.drawbridge({ dir="east", state="closed", x=05,y=08 }); + des.drawbridge({ dir="east", state="closed", coord={05,08} }); + + +=== engraving + +Create an engraving. + +* type is one of "dust", "engrave", "burn", "mark", or "blood". +* optional boolean `degrade` defaults to true; engraving can degrade or be wiped out. +* optional boolean `guardobjects` defaults to false (unless making a level and the text is "Elbereth"); are items on the engraving protected from monsters. + +Example: + + des.engraving({ x = 1, y = 1, type = "burn", text = "Foo" }); + des.engraving({ coord = {1, 1}, type = "burn", text = "Foo" }); + des.engraving({x,y}, "engrave", "Foo"); + + +=== exclusion + +Exclude an area of the map from being randomly chosen target when +falling or teleporting into the level, or creating a monster. +Multiple exclusions per level are allowed. + +* type is one of "teleport", "teleport-up", "teleport-down", or "monster-generation". + +Example: + + des.exclusion({ type = "teleport", region = { 0,0, 10,5 } }); + + +=== feature + +Create a feature, and set flags for it. +Valid features are a fountain, a sink, a pool, a throne, or a tree. +Throne has `looted` flag, tree has `looted` and `swarm`, fountain has `looted` and `warned`, +sink has `pudding`, `dishwasher`, and `ring`. +If passed with no coordinates, it will be placed in a random normal-floor spot +in the enclosing room or region if one exists, or a random normal-floor spot +anywhere on the level if one does not exist. + +Example: + + des.feature("fountain", 2, 3); + des.feature("fountain", {4, 5}); + des.feature({ type = "fountain", x = 12, y = 6 }); + des.feature({ type = "fountain", coord = {4, 6} }); + des.feature({ type = "throne", coord = {4, 6}, looted = true }); + des.feature({ type = "tree", coord = {4, 6}, looted = true, swarm = false }); + + +=== finalize_level + +Only used for testing purposes. See also <<_reset_level>>. + +Example: + + des.finalize_level(); + + +=== gas_cloud + +Create a gas cloud. +The `damage` and `ttl` fields are optional. +Defaults to non-poisonous and infinite lifetime. + +Example: + + des.gas_cloud({ x = XX, y = YY }); + des.gas_cloud({ coord = { XX, YY } }); + des.gas_cloud({ selection = SEL }); + des.gas_cloud({ selection = SEL, damage = 5 }); + des.gas_cloud({ selection = SEL, damage = 5, ttl = 200 }); + + +=== gold + +Create a pile of gold. + +Example: + + des.gold(500, 3,5); + des.gold(500, {5, 6}); + des.gold({ amount = 500, x = 2, y = 5 }); + des.gold({ amount = 500, coord = {2, 5} }); + des.gold(); + + +=== grave + +Create a grave. A missing text results in a random epitaph being used. + +Example: + + des.grave(40,11, "Text"); + des.grave({ x = 10, y = 20, text = "Epitaph text" }); + des.grave({ coord = {10, 20}, text = "Epitaph text" }); + des.grave({ text = "Epitaph text" }); + des.grave(); + + +=== ladder + +Create a ladder. + +Example: + + des.ladder("down"); + des.ladder("up", 6,10); + des.ladder("up", {6,10}); + des.ladder({ x=11, y=05, dir="down" }); + des.ladder({ coord={11, 05}, dir="down" }); + + +=== level_flags + +Set flags for this level. + +|=== +| noteleport | Prevents teleporting +| hardfloor | Prevents digging down +| nommap | Prevents magic mapping +| shortsighted | Prevents monsters from seeing the hero from far away +| arboreal | Notionally an outdoor map; replaces solid stone with trees +| mazelevel | +| shroud | Unseen locations on the level will not be remembered by the hero, instead of rendering as out-of-sight map, trap, and object glyphs like they normally do. +| graveyard | Treats the level as a graveyard level (causes graveyard sounds and undead have a reduced chance of leaving corpses). +| icedpools | Ice generated with the level will be treated as frozen pools instead of frozen moats. +| corrmaze | +| premapped | Map, including traps and boulders, is revealed on entrance. +| sokoban | Level has special Sokoban rules +| solidify | Areas outside the specified level map are made undiggable and unphaseable. +| inaccessibles | If inaccessible areas are generated, generate ways for them to connect to the "accessible" area. +| noflip | Prevent flipping the level. +| noflipx | Prevent flipping the level horizontally. +| noflipy | Prevent flipping the level vertically. +| hot | Level is hot. Dungeon flag "hellish" automatically sets this. +| cold | Level is cold. +| temperate | Level is neither hot nor cold. +| nomongen | Prevents random monster generation. +| nodeathdrops | Prevents killed monsters from dropping corpses or random death drops. +| fumaroles | Lava emits poison gas clouds at random. +| stormy | Clouds create lightning bolts at random. +|=== + +Example: + + des.level_flags("noteleport", "mazelevel"); + + +=== level_init + +Initialize the map with a random generator of a certain type. + +Example: + + des.level_init({ style = "solidfill", fg = " " }); + des.level_init({ style = "mines", fg = ".", bg = "}", smoothed=true, joined=true, lit=0 }) + des.level_init({ style = "maze", corrwid = 3, wallthick = 1, deadends = false }); + + +=== levregion + +Create a region where a stair, a branch stair, or a portal is created, +or a region which limits teleportation. + +* type is one of "stair-down", "stair-up", "portal", "branch", "teleport", "teleport-up", or "teleport-down". +* name is used for portals as the target level name. + +Example: + + des.levregion({ region = { x1,y1, x2,y2 }, exclude = { x1,y1, x2,y2 }, type = "portal", name="air" }); + + +=== map + +Construct a piece of the level from text map. Takes one parameter, either a text string +describing the map, or a table with multiple parameters. Returns a <<_selection>> where +the map locations were put down on. If a contents-function is used, the commands following +the map are not relative to it. + +[options="header"] +|=== +| parameter | description +| x, y | Coordinates on the level. +| coord | Coordinates in table format. +| halign | Horizontal alignment on a rough 3x3 grid. +| valign | Vertical alignment on a rough 3x3 grid. +| map | Multi-line string describing the map. See <<_map_characters>> +| lit | Boolean. Are the map grids lit? Default is false. +| contents | A function called with one parameter, a table with "width" and "height", the map width and height. All coordinates in the function will be relative to the map. +|=== + +Example: + + des.map({ x = 10, y = 10, map = [[...]] }); + des.map({ coord = {10, 10}, map = [[...]] }); + des.map({ halign = "center", valign = "center", map = [[...]] }); + des.map([[...]]); + des.map({ halign = "center", valign = "center", map = [[ + .... + .... + ....]], contents = function(map) + des.terrain(0,0, "L"); + des.terrain(map.width-1, map.height-1, "T"); + end }); + local sel = des.map([[LLL]]); + + +=== mazewalk + +Create a maze. + +* dir is one of "north", "south", "east", "west", or "random", and tells which direction the maze creation starts. Default is "random". +* stocked tells whether the maze is stocked with default monsters and objects. +* typ is the map terrain used for the walkable parts of the maze. + +Example: + + des.mazewalk({ x = NN, y = NN, typ = ".", dir = "north", stocked = 0 }); + des.mazewalk({ coord = {NN, NN}, typ = ".", dir = "north" }); + des.mazewalk(x,y,dir); + + +=== message + +Message shown to the player when entering the level for the first time. + +Example: + + des.message("Foo"); + + +=== mineralize + +Place random gems, gold, and kelp on the level. + +Example: + + des.mineralize({ gem_prob = 10, gold_prob = 20, kelp_moat = 30, kelp_pool = 40 }); + + +=== monster + +Create a monster. + +The hash parameter accepts the following keys: + +[options="header"] +|=== +| parameter | type | description +| id | string | specific monster type, eg. "wood nymph" +| class | string | monster class, eg "D" +| x, y | integers | +| coord | table of two integer | +| peaceful | boolean | +| asleep | boolean | +| name | string | name of the monster +| female | boolean | +| invisible | boolean | +| cancelled | boolean | +| revived | boolean | +| avenge | boolean | +| fleeing | 0 - 127 | +| blinded | 0 - 127 | +| paralyzed | 0 - 127 | +| stunned | boolean | +| confused | boolean | +| waiting | boolean | monster will wait until hero gets next to it +| m_lev_adj | integer | monster's level adjustment +| tail | boolean | generate worm without a tail? +| group | boolean | generate a group of monsters? +| adjacentok | boolean | is adjacent location ok, if given one is not suitable? +| ignorewater | boolean | ignore water when choosing location for the monster +| countbirth | boolean | do we count this monster as generated +| appear_as | string | monster can appear as object, monster, or terrain. Add "obj:", "mon:", or "ter:" prefix to the value. +| inventory | function | objects generated in the function are given to the monster (any random inventory it gets is discarded unless keep_default_invent is true) +| keep_default_invent | boolean | if inventory is specified and this is true, those items are in addition to random inventory for this species; if inventory is not specified and this is false, monster gets no starting inventory +|=== + +Example: + + des.monster(); + des.monster("wood nymph"); + des.monster("D"); + des.monster("giant eel",11,06); + des.monster("hill giant", {08,06}); + des.monster({ id = "giant mimic", appear_as = "obj:boulder" }); + des.monster({ class = "H", peaceful = 0 }); + + +=== non_diggable + +Set walls in an area of the map as non-diggable. See also: <<_wall_property>>. + +Example: + + des.non_diggable(selection); + des.non_diggable(); + + +=== non_passwall + +Set walls in an area of the map as non-passwall, so they can't be phased through. See also: <<_wall_property>>. + +Example: + + des.non_passwall(selection); + des.non_passwall(); + + +=== object + +Create an object and place it somewhere on the map. Returns the object as an <> class. +The table parameter accepts the following: + +[options="header"] +|=== +| key | type | description +| id | string | Specific object type name +| class | string | Single character, object class +| spe | int | obj-struct spe-field value. See table below. Also accepts "random". +| buc | string | one of "random", "blessed", "uncursed", "cursed", + "not-cursed", "not-uncursed", "not-blessed". + Default is "random" +| name | string | Object name +| quantity | int | Number of items in this stack. Also accepts "random". +| buried | boolean | Is the object buried? +| lit | boolean | Is the object lit? +| eroded | int | Object erosion +| locked | boolean | Is the object locked? +| trapped | boolean | Is the object trapped? +| trap_known | boolean | If container is trapped, is it obvious? +| recharged | boolean | Is the object recharged? +| greased | boolean | Is the object greased? +| broken | boolean | Is the object broken? +| achievement | boolean | Is there an achievement attached to the object? +| x, y | int | Coordinates on the level; defaults to a random location. +| coord | table | x,y coordinates in table format; defaults to a random location. +| montype | string | Monster id or class +| historic | boolean | Is statue historic? +| male | boolean | Is statue male? +| female | boolean | Is statue female? +| laid_by_you | boolean | Is an egg laid by you? +| contents | function | Container contents. The container object is given as a parameter. See <> class. +|=== + +Example: + + des.object(); + des.object("/"); + des.object("sack"); + des.object("scimitar", 6, 7); + des.object("scimitar", {6, 7}); + des.object({ class = "%" }); + des.object({ id = "boulder", x = 03, y = 12}); + des.object({ id = "chest", coord = {03, 12}, locked = true, contents = function(obj) des.object("rock"); end }); + local o = des.object(); + + +=== random_corridors + +Create random corridors between rooms. + +Example: + + des.random_corridors(); + + +=== region + +Create a room region, which can be irregular; use the boundary <<_map_characters,map character>> to restrict the floodfilled area. + +If using the first form with a selection and "lit", the lit area will extend +outward 1 space from the selection to attempt to accommodate adjacent walls, +regardless of whether they are actually walls or not. If using "unlit", this +will not happen. + +Example: + + des.region(selection, lit); + des.region({ x1=NN, y1=NN, x2=NN, y2=NN, lit=BOOL, type=ROOMTYPE, joined=BOOL, irregular=BOOL, filled=NN [ , contents = FUNCTION ] }); + des.region({ region={x1,y1, x2,y2}, type="ordinary" }); + + +=== replace_terrain + +Replaces matching terrain on the area, selection, or whole map. +The mapfragment case is similar to the selection <<_match>>, but the replacement is done immediately when matched. + +Example: + + des.replace_terrain({ x1=NN,y1=NN, x2=NN,y2=NN, fromterrain=MAPCHAR, toterrain=MAPCHAR, lit=N, chance=NN }); + des.replace_terrain({ region={x1,y1, x2,y2}, fromterrain=MAPCHAR, toterrain=MAPCHAR, lit=N, chance=NN }); + des.replace_terrain({ selection=selection.area(2,5, 40,10), fromterrain=MAPCHAR, toterrain=MAPCHAR }); + des.replace_terrain({ selection=SEL, mapfragment=[[...]], toterrain=MAPCHAR }); + des.replace_terrain({ mapfragment=[[...]], toterrain=MAPCHAR }); + des.replace_terrain({ fromterrain=MAPCHAR, toterrain=MAPCHAR }); + + +=== reset_level + +Only used for testing purposes. See also <<_finalize_level>>. + +Example: + + des.reset_level(); + + +=== room + +Create a room of certain type and size. Takes one parameter, a table with the following +fields: + +[options="header"] +|=== +| parameter | description +| type | The room type. Default is "ordinary" +| chance | Percentage chance this room is of type, otherwise it will be created as ordinary room. Default is 100. +| x,y | Room coordinates. +| coord | Room coordinates, in table format. +| w, h | Width and height. Both default to -1 (random). If one is set, then both must be set. +| xalign | Horizontal alignment on a rough 3x3 grid. Default is "random". +| yalign | Vertical alignment on a rough 3x3 grid. Default is "random". +| lit | Is the room lit or unlit? Defaults to -1 (random). +| filled | Is the room filled as per the room type. Defaults to 1 (filled). +| joined | Is the room joined to the rest of the level with corridors? Default is true. +| contents | A function called with one parameter, a table with room data. See <<_room_contents>>. +|=== + + +==== room contents + +The room contents function is called when the room is created. +All coordinates in the function will be relative to the room. +The function get passed one parameter, a table with room data: + +[options="header"] +|=== +| parameter | description +| width | room width, excluding the walls. +| height | room height, excluding the walls. +| region | table with 4 elements, the room region coordinates: x1, y1, x2, y2. +| lit | is the room lit or unlit? +| irregular | is the room irregular? +| needjoining | does the room need joining with corridors? +| type | the room type. +|=== + + +Example: + + des.room({ type="ordinary", lit=1, x=3,y=3, xalign="center",yalign="center", w=11,h=9 }); + des.room({ lit=1, coord={3,3}, xalign="center",yalign="center", w=11,h=9 }); + des.room({ type="ordinary", contents=function(room) + des.terrain(0,0, "L"); + des.terrain(room.width, room.height, "T"); + end }); + + +=== stair + +Create stairs. + +Example: + + des.stair("up"); + des.stair({ dir = "down" }); + des.stair({ dir = "down", x = 4, y = 7 }); + des.stair({ dir = "down", coord = {5,12} }); + des.stair("down", 4, 7); + des.stair("down", {4, 7}); + + +=== teleport_region + +Example: + + des.teleport_region({ region = { x1,y1, x2,y2} }); + des.teleport_region({ region = { x1,y1, x2,y2}, region_islev = 1, exclude = { x1,y1, x2,y2}, exclude_islev = 1, dir = "up" }); + + +=== terrain + +Example: + + des.terrain({ x=5, y=6, typ="L", lit=1 }); + des.terrain({ coord={10, 11}, typ="T", lit=0 }); + des.terrain({ selection=selection.rect(15,5, 20,7), typ="F", lit=0 }); + des.terrain(selection.area(25, 3, 30,6), "C"); + des.terrain({20,11}, "."); + des.terrain(21,12, "."); + + +=== trap + +Create a trap. The `launchfrom` is relative to the rolling boulder trap coord, +but `teledest` is absolute. + +Example: + + des.trap({ type = "hole", x = 1, y = 1 }); + des.trap({ type = "hole", coord = {2, 2} }); + des.trap({ type = "web", coord = {2, 2}, spider_on_web = false, seen = true }); + des.trap({ type = "falling rock", victim = false }); + des.trap({ type = "rolling boulder", coord = {7, 5}, launchfrom = {-2, -2} }); + des.trap({ type = "teleport", coord = {7, 5}, teledest = {2, 2} }); + des.trap("hole", 3, 4); + des.trap("level teleport", {5, 8}); + des.trap("rust") + des.trap(); + + +=== wall_property + +Set walls in an area nondiggable or non-passwall. See also: <<_non_diggable>> and <<_non_passwall>>. + +Example: + + des.wall_property({ x1=0, y1=0, x2=78, y2=20, property="nondiggable" }); + des.wall_property({ region = {1,0, 78,20}, property="nonpasswall" }); + + +=== wallify + +Example: + + des.wallify({ x1=NN,y1=NN, x2=NN,y2=NN }); + des.wallify(); + + +== Selection + +Selection object can be used to "select" areas of the map with graphic primitives. + + +=== new + +Create a new selection. + +Example: + + local sel = selection.new(); + + +=== Logical and + +Choose locations that are selected in both selections. + +Example: + + local sel = selection.area(4,5, 40,10) & selection.rect(7,8, 60,14); + + +=== Logical or + +Choose locations that are selected in either or both selections. The +addition operator also does this. + +Example: + + local sel = selection.area(4,5, 40,10) | selection.rect(7,8, 60,14); + local sel = selection.area(4,5, 40,10) + selection.rect(7,8, 60,14); + + +=== Logical xor + +Choose locations in either selection, but not both. + +Example: + + local sel = selection.area(4,5, 40,10) ~ selection.rect(7,8, 60,14); + + +=== Logical difference + +Choose locations in the first selection but not in the second selection. + +Example: + + local sel = selection.area(10,10, 20,20) - selection.area(14,14, 17,17); + + +=== area + +Alias for <<_fillrect>>. + + +=== bounds + +Get the bounding box for the selection. Returns a table with lx, ly, hx, hy integer fields. + +Example: + + local rect = sel:bounds(); + local s = string.format("(%i,%i)-(%i,%i)", rect.lx, rect.ly, rect.hx, rect.hy)); + + +=== circle + +Example: + + local s = selection.circle(x,y, radius); + local s = selection.circle(x, y, radius, filled); + local s = selection.circle(sel, x, y, radius); + local s = selection.circle(sel, x, y, radius, filled); + + +=== clone + +Clone a selection. + +Example: + + local sel2 = selection.clone(sel); + + +=== describe_size + +Return a text describing the size of the selection. + +Example: + + local sel = selection.fillrect(1,1, 3,3); + local txt = sel:describe_size(); + + +=== ellipse + +Example: + + local s = selection.ellipse(x, y, radius1, radius2); + local s = selection.ellipse(x, y, radius1, radius2, filled); + local s = selection.ellipse(sel, x, y, radius1, radius2); + local s = selection.ellipse(sel, x, y, radius1, radius2, filled); + + +=== fillrect + +Example: + + local s = selection.fillrect(sel, x1,y1, x2,y2); + local s = selection.fillrect(x1,y1, x2,y2); + s:fillrect(x1,y1, x2,y2); + selection.area(x1,y1, x2,y2); + + +=== filter_mapchar + +Filter points in selection by choosing those that match the map character, +and optionally the light state of the map location. + +`lit` can be 1 or 0 (which matches the lit or unlit locations), +or -1, in which case it will choose either all lit or all unlit map locations. + +Example: + + local s = selection.filter_mapchar(sel, mapchar); + local s = selection.filter_mapchar(sel, mapchar, lit); + + +=== floodfill + +Select locations by starting floodfill at (x,y), +matching the same map terrain in cardinal directions. +If the optional third parameter is true, also checks diagonals. + +Example: + + local s = selection.floodfill(sel, x, y); + local s = selection.floodfill(x,y); + local s = selection.floodfill(x,y, true); + + +=== get + +Get the selection value at (x,y). + +Example: + + local value = selection.get(sel, x, y); + local value = selection.get(sel, { x = 10, y = 14 }); + + +=== gradient + +Create a "gradient" of selected positions, radiating outward from a center point +or line. +x and y are required; x2 and y2 are not required. If they are provided and are +different from x and y, the center of the gradient will be a line; otherwise it +will be a point source at (x,y). +type is either "radial" or "square"; defaults to "radial" if not provided. +mindist is not required and is 0 by default. Points within (mindist) tiles of +the center will always be added to the selection. +maxdist is required. Points more than (maxdist) tiles from the center will never +be added to the selection. +For any given point between mindist and maxdist, there is a random chance it +will be added to the selection; this chance starts at 100% at mindist and +decreases linearly to 0% at maxdist. + +Example: + + local s = selection.gradient({ type = "radial", x = 3, y = 5, x2 = 10, y2 = 12, mindist = 4, maxdist = 10 }); + + +=== grow + +Add locations to the selection by choosing unselected locations +to the given direction from selected locations. +If no direction is given, picks all directions. + +Example: + + local s = selection.grow(sel); + local s = selection.grow(sel, "north"); + + +=== iterate + +Iterate through the selection, calling a function for each set point. + +Example: + + sel:iterate(function(x,y) ... end); + + +=== line + +Draw a line from (x1,y1) to (x2,y2). + +Example: + + local s = selection.line(sel, x1,y1, x2,y2); + local s = selection.line(x1,y1, x2,y2); + s:line(x1,y1, x2,y2); + + +=== match + +Every location on the map, centered on the map fragment and matching it, +are added to the selection. The map fragment must have odd width and height, +and the center must not be the "transparent" map character. + +Example: + + local s = selection.match([[ + ... + .L. + ...]]); + + +=== negate + +Negate the selection. Alias for "unary minus" and "bitwise not". + +Example: + + local s = selection.negate(sel); + local s = selection.negate(); + + +=== numpoints + +Return the number of points in the selection. + +Example: + + local n = sel:numpoints(); + + +=== percentage + +Each selected location has a percentage chance of being selected in the new selection. + +Example: + + local s = selection.percentage(sel, 50); + + +=== randline + +Example: + + local s = selection.randline(sel, x1,y1, x2,y2, roughness); + local s = selection.randline(x1,y1, x2,y2, roughness); + + +=== rect + +Draw a rectangle. + +Example: + + local s = selection.rect(sel, x1,y1, x2,y2); + + +=== rndcoord + +Choose one of the selected locations, and return a table with x and y keys. +If the optional second argument is 1, removes the location from the selection. +If there are no coordinates in the selection, returns -1, -1. + +Example: + + local coord = selection.rndcoord(sel); + local coord = selection.rndcoord(sel, 1); + + +=== room + +Create a selection of locations inside the (current) room. +Does not include the edges of the room, such as its walls. +Does not do any check on terrain type, so if there are non-ROOM locations inside the room, they remain part of the selection. + +Example: + + des.room({ type = "ordinary", contents = function(rm) + local sel = selection.room(); + des.terrain(sel, "I"); + end + }); + + +=== set + +Set the value for location (x,y) in the selection. + +Example: + + selection.set(sel, x, y); + selection.set(sel, x, y, value); + local sel = selection.set(); + local sel = sel:set(); + local sel = selection.set(sel); + + +== Obj + +Handling objects via obj-class. + + +=== new + +Create a new object, either via wishing routine, or specifying object name and class. +Unlike des.object, does not place the object anywhere. + +Example: + + local o = obj.new("rock"); + local o = obj.new({ id = "invisibility", class = "!" }); + + +=== isnull + +Is the object a "null" object? Meaning, the object variable exists in lua, but NetHack +core has freed it. + +Example: + + local badobj = o:isnull(); + + +=== at + +Get the topmost object on the map at x,y. + +Example: + + local o = obj.at(x, y); + + +=== next + +Get the next object in the object chain. +When called without an object, returns the first object in the object chain. +When called with an object, an optional boolean parameter can be given. When +it is true, and the object is on the map, the next object at the same location +is returned. Otherwise the normal object chain is followed. + +Example: + + local first = obj.next(); + local second = first:next(); + local o_at_xy = obj.at(x, y); + local next_at_xy = o_at_xy:next(true); + + +=== totable + +Create a lua table representation of the object, unpacking all the object fields. + +Example: + + local o = obj.new("rock"); + local otbl = o:totable(); + + +=== class + +Get a lua table of object class data. + +Example: + + local odata1 = obj.class(obj.new("rock")); + + +=== placeobj + +Place object on the map at x,y. + +Example: + + local o = obj.new("rock"); + o:placeobj(u.ux, u.uy); + + +=== container + +Get the container object is in. + +Example: + + local box = o:container(); + + +=== contents + +Get the contents of an object. + +Example: + + local o = obj.new("large chest"); + local cobj = o:contents(); + + +=== addcontent + +Put object inside another object. + +Example: + + local box = obj.new("large chest"); + box.addcontent(obj.new("rock")); + + +=== has_timer + +Does object have an attached timer of certain type? +See <<_timer_types>>. + +Example: + + local hastimer = o:has_timer("rot-organic"); + + +=== peek_timer + +Peek at an object timer. Returns the turn when timer triggers. +Returns 0 if no such timer attached to the object. +See <<_timer_types>>. + +Example: + + local when = o:peek_timer("hatch-egg"); + + +=== stop_timer + +Stop object timer(s). Return the turn when timer would have triggered. +Returns 0 if no such timer was attached to the object. +Without a timer type parameters, stops all timers for the object, +and returns nothing. See <<_timer_types>>. + +Example: + + o:stop_timer(); + local when = o:stop_timer("rot-organic"); + + +=== start_timer + +Start an object timer. See <<_timer_types>>. + +Example: + + o:start_timer("hatch-egg", 10); + + +=== bury + +Bury an object. Returns true if object is gone (merged with ground), false otherwise. +Without parameters, buries the object at the location it is. + +Example: + + local ogone = o:bury(); + local ogone = o:bury(5, 5); + + +== Map characters + +[%header, cols="10%,90%"] +|=== +| Character | Dungeon feature +| `" "` | solid stone wall +| `"#"` | corridor +| `"."` | room floor +| `"-"` | horizontal wall +| `"\|"` | vertical wall +| `"+"` | door +| `"A"` | air +| `"B"` | crosswall / boundary symbol hack +| `"C"` | cloud +| `"S"` | secret door +| `"H"` | secret corridor +| `"{"` | fountain +| `"\"` | throne +| `"K"` | sink +| `"}"` | moat +| `"P"` | pool of water +| `"L"` | lava pool +| `"Z"` | wall of lava +| `"I"` | ice +| `"W"` | water +| `"T"` | tree +| `"F"` | iron bars +| `"x"` | "transparent" - used for <<_map>> parts. +| `"w"` | "any wall" - see <<_match>> +|=== + + +== Constants + +These constants are in the `nhc` table. + +|=== +| COLNO | Number of map columns +| ROWNO | Number of map rows +| NUMMONS | Number of different monster types +| LOW_PM | First monster type id. See <<_int_to_pmname>>. +| HIGH_PM | Last monster type id. See <<_int_to_pmname>>. +| FIRST_OBJECT | First object type id. See <<_int_to_objname>>. +| LAST_OBJECT | Number of object type ids. See <<_int_to_objname>>. +| DLB | 1 or 0, depending if NetHack is compiled with DLB +|=== + + +== Timer types + +[%header, cols="20%,10%,70%"] +|=== +| Name | Type | Description +| rot-organic | obj | non-corpse object rotting away +| rot-corpse | obj | corpse object rotting away +| revive-mon | obj | monster corpse revival +| zombify-mon | obj | monster corpse rising as a zombie +| burn-obj | obj | light-source object is lit +| hatch-egg | obj | egg hatching +| fig-transform | obj | cursed figurine automatical transform +| shrink-glob | obj | glob object shrinking away +| melt-ice | map | ice at map location melts +|=== diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 79179969f..af3919c39 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -1,275 +1,280 @@ -.TH MAKEDEFS 6 "25 May 2015" NETHACK -.de ND -.ds Nd \\$3 -.. +.\"DO NOT REMOVE NH_DATESUB .TH MAKEDEFS 6 "Date(%-d %B %Y)" Project(uc) +.TH MAKEDEFS 6 "26 April 2026" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2024 .de NB .ds Nb \\$2 .. .de NR .ds Nr \\$2 .. -.ND $NHDT-Date: 1524689549 2018/04/25 20:52:29 $ -.NB $NHDT-Branch: NetHack-3.6.0 $ -.NR $NHDT-Revision: 1.10 $ +.NB $NHDT-Branch: NetHack-5 $ +.NR $NHDT-Revision: 1.22 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ +.\" groff and AT&T-descended troffs use different hyphenation patterns. +.\" Don't hyphenate the last word on a page or column, or +.\" before/after last/first 2 characters of a word. +.ie \n(.g .hy 12 +.el .hy 14 .ds Na Kenneth Lorber .SH NAME makedefs \- NetHack miscellaneous build-time functions .SH SYNOPSIS .B makedefs -{ -.B -o -| -.B -d -| -.B -e -| -.B -m -| -.B -v -| -.B -p -| -.B -q -| -.B -r -| -.B -h -| -.B -z +{\c +.BR \-o |\c +.BR \-d |\c +.BR \-e |\c +.BR \-m |\c +.BR \-v |\c +.BR \-p |\c +.BR \-q |\c +.BR \-r |\c +.B \-h\c } .P -.B makedefs --input +.B makedefs \-\-input .I file -.B --output +.B \-\-output .I file -.BI -- command +.BI \-\- command .SH DESCRIPTION -.PP .B Makedefs is a build-time tool used for a variety of -.BR NetHack (6) -source file creation and modification tasks. For historical reasons, +.IR nethack (6) +source file creation and modification tasks. +For historical reasons, .B makedefs -takes two types of command lines. When invoked with a short option, the -files operated on are determined when +takes two types of command lines. +When invoked with a short option, +the files operated on are determined when .B makedefs -is compiled. When invoked with a long option, the -.B --input -and -.B --output +is compiled. +When invoked with a long option, +the +.B \-\-input +and +.B \-\-output options are used to specify the files for the -.BI -- command. +.BI \-\- command. Each command is only available in one of the two formats. .SH SHORT COMMANDS Upper and lower case are both accepted for the short commands. .TP -.B -o +.B \-o Generate -.I onames.h. -.br +.IR onames.h . .TP -.B -d +.B \-d Generate -.I data.base. -.br +.IR data.base . .TP -.B -e +.B \-e Generate -.I dungeon.pdf. +.IR dungeon.pdf . The input file .I dungeon.def is passed through the same logic as that used by the -.B --grep +.B \-\-grep command; see the .B MDGREP FUNCTIONS section below for details. -.br -.TP -.B -m -Generate -.I monster.c. -.br .TP -.B -v +.B \-m Generate .I date.h and .I options -file. It will read +file. +It will read .IR dat/gitinfo.txt , only if it is present, to obtain .B githash= and .B gitbranch= - info and include related preprocessor #defines in +info and include related preprocessor #defines in .I date.h file. -.br -.TP -.B -p -Generate -.I pm.h -.br .TP -.B -q +.B \-p Generate -.IR quest.dat . -.br +.IR pm.h . .TP -.B -r +.B \-q Generate the .I rumors file. -.br .TP -.B -s +.B \-s Generate the -.I bogusmon -, -.I engrave +.IR bogusmon , +.IR engrave , and -.IR epitaph files. -.br +.I epitaph +files. .TP -.B -h +.B \-1 Generate the -.B oracles +.I epitaph file. -.br .TP -.B -z -Generate -.I vis_tab.c -and -.IR vis_tab.h . +.B \-2 +Generate the +.I engrave +file. +.TP +.B \-3 +Generate the +.I bogusmon +file. +.TP +.B \-h +Generate the +.I oracles +file. .SH LONG COMMANDS .TP -.B --debug +.B \-\-debug Show debugging output. -.br .TP -.B --make \fR[\fIcommand\fR] -Execute a short command. Command is given without preceding dash. -.br +.B \-\-make \fR[\fIcommand\fR] +Execute a short command. +.I Command +is given without preceding dash. .TP -.BI --input " file" +.BI \-\-input " file" Specify the input .I file -for the command (if needed). If the file is - standard -input is read. -.br +for the command (if needed). +If +.I file +is \*(lq\-\*(rq, +.B makedefs +reads the standard input stream. .TP -.BI --output " file" +.BI \-\-output " file" Specify the output .I file -for the command (if needed). If the file is - standard -output is written. -.br +for the command (if needed). +If +.I file +is \*(lq\-\*(rq, +.B makedefs +writes to the standard input stream. .TP -.B --svs \fR[\fIdelimiter\fR] +.B \-\-svs \fR[\fIdelimiter\fR] Generate a version string to standard output without a trailing newline. If specified, the delimiter is used between each part of the version string. -.br .TP -.B --grep +.B \-\-grep Filter the input .I file to the output .IR file . See the .B MDGREP FUNCTIONS section below for information on controlling the filtering operation. -.br .TP -.B --grep-showvars +.B \-\-grep\-showvars Show the name and value for each variable known to the grep option. -.br .TP -.B --grep-trace +.B \-\-grep\-trace Turn on debug tracing for the grep function ( -.B --grep +.B \-\-grep must be specified as well). -.br .TP -.BI --grep-define " symbol" +.BI \-\-grep\-defined " symbol" +Exit shell true (0) if +.I symbol +is known and defined, otherwise exit shell false (1). +.TP +.BI \-\-grep\-define " symbol" Force the value of .I symbol -to be "defined." +to be \*(lqdefined.\*(rq .I Symbol must already be known to .BR makedefs . -.br .TP -.BI --grep-undef " symbol" +.BI \-\-grep\-undef " symbol" Force the definition of .I symbol -to be "undefined." +to be \*(lqundefined.\*(rq .I Symbol must already be known to .BR makedefs . .SH MDGREP FUNCTIONS The -.B --grep +.B \-\-grep command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input and on information gleaned from the -.BR NetHack (6) -configuration. This allows certain changes such as embedding platform-specific +.I nethack +configuration. +This allows certain changes such as embedding platform-specific documentation into the master documentation files. .P Rules: -.RS -.IP - 4 +.IP \(bu The default conditional state is printing enabled. -.IP - 4 +.IP \(bu Any line .I NOT -starting with a caret (^) is either suppressed or passed through unchanged +starting with a caret (\*^) is either suppressed or passed through unchanged depending on the current conditional state. -.IP - 4 +.IP \(bu Any line starting with a caret is a control line; as in C, zero or more spaces may be embedded in the line almost anywhere (except immediately after the caret); however the caret must be in column 1. -.IP - 4 +.IP \(bu Conditionals may be nested. -.IP - 4 +.IP \(bu .I Makedefs will exit with an error code if any errors are detected; processing will continue (if it can) to allow as many errors as possible to be detected. -.IP - 4 -Unknown identifiers are treated as both TRUE and as an error. Note that -.BR --undef " or " #undef +.IP \(bu +Unknown identifiers are treated as both TRUE and as an error. +Note that +.BR \-\-undef " or " #undef in the -.BR NetHack (6) +.I nethack configuration are different from unknown. -.RE .P Control lines: -.RS -.IP ^^ 4 +.TP +.B +\*^\*^ a line starting with a (single) literal caret -.IP ^# +.TP +.B \*^# a comment -.IP ^?\fIID +.TP +.B \*^?\fIID if the .I ID is defined set the conditional state to TRUE -.IP ^!\fIID +.TP +.B \*^!\fIID if the .I ID is not defined set the conditional state to TRUE -.IP ^: +.TP +.B \*^: else; invert the conditional state -.IP ^. +.TP +.B \*^. end the most recent conditional -.RE .\".SH EXAMPLES .SH AUTHOR The NetHack Development Team -.SH "SEE ALSO" -.PP -.BR dgn_comp (6) .SH COPYRIGHT -This file is Copyright (C) \*(Na and was last modified \*(Nd (version -\*(Nb:\*(Nr). -NetHack may be freely redistributed. See license for details. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/makedefs.txt b/doc/makedefs.txt index 97a1f0ac7..7bae10fa1 100644 --- a/doc/makedefs.txt +++ b/doc/makedefs.txt @@ -6,12 +6,12 @@ NAME makedefs - NetHack miscellaneous build-time functions SYNOPSIS - makedefs { -o | -d | -e | -m | -v | -p | -q | -r | -h | -z } + makedefs {-o|-d|-e|-m|-v|-p|-q|-r|-h} makedefs --input file --output file --command DESCRIPTION - Makedefs is a build-time tool used for a variety of NetHack(6) source + Makedefs is a build-time tool used for a variety of nethack(6) source file creation and modification tasks. For historical reasons, makedefs takes two types of command lines. When invoked with a short option, the files operated on are determined when makedefs is compiled. When @@ -30,57 +30,61 @@ SHORT COMMANDS through the same logic as that used by the --grep command; see the MDGREP FUNCTIONS section below for details. - -m Generate monster.c. + -m Generate date.h and options file. It will read dat/gitinfo.txt, + only if it is present, to obtain githash= and gitbranch= info + and include related preprocessor #defines in date.h file. - -v Generate date.h and options file. It will read dat/gitinfo.txt, - only if it is present, to obtain githash= and gitbranch= - info and include related preprocessor #defines in date.h file. + -p Generate pm.h. - -p Generate pm.h + -q Generate the rumors file. - -q Generate quest.dat. + -s Generate the bogusmon, engrave, and epitaph files. - -r Generate the rumors file. + -1 Generate the epitaph file. - -s Generate the bogusmon , engrave and epitaphfiles. + -2 Generate the engrave file. - -h Generate the oracles file. + -3 Generate the bogusmon file. - -z Generate vis_tab.c and vis_tab.h. + -h Generate the oracles file. LONG COMMANDS --debug Show debugging output. --make [command] - Execute a short command. Command is given without preceding + Execute a short command. Command is given without preceding dash. --input file - Specify the input file for the command (if needed). If the file - is - standard input is read. + Specify the input file for the command (if needed). If file is + "-", makedefs reads the standard input stream. --output file - Specify the output file for the command (if needed). If the - file is - standard output is written. + Specify the output file for the command (if needed). If file is + "-", makedefs writes to the standard input stream. --svs [delimiter] - Generate a version string to standard output without a trailing - newline. If specified, the delimiter is used between each part + Generate a version string to standard output without a trailing + newline. If specified, the delimiter is used between each part of the version string. - --grep Filter the input file to the output file. See the MDGREP FUNC- + --grep Filter the input file to the output file. See the MDGREP FUNC- TIONS section below for information on controlling the filtering operation. --grep-showvars - Show the name and value for each variable known to the grep + Show the name and value for each variable known to the grep option. --grep-trace - Turn on debug tracing for the grep function ( --grep must be + Turn on debug tracing for the grep function ( --grep must be specified as well). + --grep-defined symbol + Exit shell true (0) if symbol is known and defined, otherwise + exit shell false (1). + --grep-define symbol Force the value of symbol to be "defined." Symbol must already be known to makedefs. @@ -92,60 +96,55 @@ LONG COMMANDS MDGREP FUNCTIONS The --grep command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input - and on information gleaned from the NetHack(6) configuration. This - allows certain changes such as embedding platform-specific documenta- - tion into the master documentation files. + and on information gleaned from the nethack configuration. This allows + certain changes such as embedding platform-specific documentation into + the master documentation files. Rules: - - The default conditional state is printing enabled. + o The default conditional state is printing enabled. - - Any line NOT starting with a caret (^) is either suppressed - or passed through unchanged depending on the current condi- - tional state. + o Any line NOT starting with a caret (^) is either suppressed or + passed through unchanged depending on the current conditional + state. - - Any line starting with a caret is a control line; as in C, - zero or more spaces may be embedded in the line almost any- - where (except immediately after the caret); however the - caret must be in column 1. + o Any line starting with a caret is a control line; as in C, zero + or more spaces may be embedded in the line almost anywhere + (except immediately after the caret); however the caret must be + in column 1. - - Conditionals may be nested. + o Conditionals may be nested. - - Makedefs will exit with an error code if any errors are - detected; processing will continue (if it can) to allow as - many errors as possible to be detected. + o Makedefs will exit with an error code if any errors are + detected; processing will continue (if it can) to allow as many + errors as possible to be detected. - - Unknown identifiers are treated as both TRUE and as an - error. Note that --undef or #undef in the NetHack(6) con- - figuration are different from unknown. + o Unknown identifiers are treated as both TRUE and as an error. + Note that --undef or #undef in the nethack configuration are + different from unknown. Control lines: - ^^ a line starting with a (single) literal caret + ^^ a line starting with a (single) literal caret - ^# a comment + ^# a comment - ^?ID - if the ID is defined set the conditional state to TRUE + ^?ID if the ID is defined set the conditional state to TRUE - ^!ID - if the ID is not defined set the conditional state to TRUE + ^!ID if the ID is not defined set the conditional state to TRUE - ^: else; invert the conditional state + ^: else; invert the conditional state - ^. end the most recent conditional + ^. end the most recent conditional AUTHOR The NetHack Development Team -SEE ALSO - dgn_comp(6) - COPYRIGHT - This file is Copyright (C) Kenneth Lorber and was last modified - 2018/04/25 (version NetHack-3.6.0:1.10). NetHack may be freely redis- - tributed. See license for details. + This file is Copyright (C) Kenneth Lorber, 2024 for version + NetHack-5:1.22. NetHack may be freely redistributed. See license for + details. -NETHACK 25 May 2015 MAKEDEFS(6) +NETHACK 26 April 2026 MAKEDEFS(6) diff --git a/doc/mn.7 b/doc/mn.7 index 1d40edc2c..827ed82a8 100644 --- a/doc/mn.7 +++ b/doc/mn.7 @@ -136,7 +136,7 @@ b num \- i used to embolden italics _bi \*Z mac \- \- print \*x in emboldened font 2, \*y after, \*z before bm num 1i,1i+1v \- height of bottom margin -_bt mac \- \- print pottom title +_bt mac \- \- print bottom title bt num .5i+1v \- bottom of footer to bottom of page _cf \*Z mac \- \- print contents of header line (double quotes around \*x, \*y before, \*z after) diff --git a/doc/mn.txt b/doc/mn.txt index 502a0f3bb..7623777fd 100644 --- a/doc/mn.txt +++ b/doc/mn.txt @@ -17,8 +17,8 @@ DESCRIPTION All -mn macros, diversions, string registers, and number registers are defined below. Many nroff and troff requests are unsafe in conjunction - with this package. However, the requests below may be used with - impunity: + with this package. However, the requests below may be used with im- + punity: .bp begin new page .br break output line @@ -29,8 +29,8 @@ DESCRIPTION Font and point size changes with \f and \s are also allowed; for exam- ple, ``\f2word\fR'' will italicize word. Output of the tbl(1), eqn(1), - and refer(1) preprocessors for equations, tables, and references is - acceptable as input. + and refer(1) preprocessors for equations, tables, and references is ac- + ceptable as input. FILES /usr/lib/tmac/tmac.n @@ -47,12 +47,12 @@ WARNINGS This package is not now intended for uses other than with the news doc- umentation. - Bug reports are always welcome; please send them to the author. - (Include a sample of the input; this helps track down the bug.) + Bug reports are always welcome; please send them to the author. (In- + clude a sample of the input; this helps track down the bug.) AUTHOR - Matt Bishop (mab@riacs.arpa, ihnp4!ames!riacs!mab, dec- - vax!decwrl!riacs!mab) + Matt Bishop (mab@riacs.arpa, ihnp4!ames!riacs!mab, decvax!decwrl!ri- + acs!mab) Updated for versions 1.4-1.6 by The NetHack Development Team REQUESTS @@ -75,14 +75,14 @@ b num - i used to embolden italics .bi x y z mac - - print x in emboldened font 2, y after, z before bm num 1i,1i+1v - height of bottom margin -.bt mac - - print pottom title +.bt mac - - print bottom title bt num .5i+1v - bottom of footer to bottom of page .cf x y z mac - - print contents of header line (double quotes around x, y before, z after) cm num 0 - 0 if no cut marks, nonzero if cut marks .cn x y z mac - - print computer/site name; same as .i .dd div - i text of display -dg str *,- - footnote mark +dg str *,<*> - footnote mark dw str current - name of current day of week dy str current - full date .ed mac - b end display diff --git a/doc/mnh.7 b/doc/mnh.7 index daed16283..802c806ec 100644 --- a/doc/mnh.7 +++ b/doc/mnh.7 @@ -1,5 +1,16 @@ +.\"DO NOT REMOVE NH_DATESUB .TH MAKEDEFS 6 "Date(%-d %B %Y)" Project(uc) .\" $NHDT-Branch: NetHack-3.6.2 $:$NHDT-Revision: 1.0 $ $NHDT-Date: 1541298620 2018/11/04 02:30:20 $ -.TH MNH 7 NETHACK +.TH MNH 7 "4 November 2018" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2018 +.de NB +.ds Nb \\$2 +.. +.de NR +.ds Nr \\$2 +.. +.NB $NHDT-Branch: NetHack-3.6.2 $ +.NR $NHDT-Revision: 1.0 $ .SH NAME mnh \- additional text formatting macros for the NetHack Guidebook .SH SYNOPSIS @@ -9,14 +20,14 @@ mnh \- additional text formatting macros for the NetHack Guidebook .\".B "troff \-mn" .\"[ options ] file ... .SH DESCRIPTION -.PP This package of .IR nroff (1) and .IR troff (1) macro definitions extends .IR tmac.n (7) -for the NetHack Guidebook. This document should be +for the NetHack Guidebook. +This document should be read as an addendum to the documentation for .IR tmac.n . .PP @@ -27,11 +38,10 @@ and number registers are defined below. .SH FILES doc/tmac.nh .SH "SEE ALSO" -mn(7) +.IR mn (7) .SH AUTHOR Pat Rankin .SH REQUESTS -.PP In the .I Note column, @@ -76,6 +86,7 @@ and the second for Macro What Initial Note \0 Explanation Name It Is Value .sp .3 +nH num 0 \- avoid processing multiple times _BR mac \- \- hard line break with vertical padding inserted bR num \- i _CC \*Y mac \- \- aligned one char key \*x with \fIshort\fP definition \*y @@ -92,4 +103,5 @@ PX num \- i PY num \- i _SD \*X mac \- \- .sd with options c-center i-indent n-no indent SF num \- i +UR mac \- \- URL passthrough for HTML generator _UX mac \- \- .ux with updated trademark owner diff --git a/doc/mnh.txt b/doc/mnh.txt index b7e966065..729409a99 100644 --- a/doc/mnh.txt +++ b/doc/mnh.txt @@ -36,6 +36,7 @@ REQUESTS Macro What Initial Note Explanation Name It Is Value +nH num 0 - avoid processing multiple times .BR mac - - hard line break with vertical padding inserted bR num - i .CC x y mac - - aligned one char key x with short definition y @@ -52,8 +53,9 @@ PX num - i PY num - i .SD x mac - - .sd with options c-center i-indent n-no indent SF num - i +UR mac - - URL passthrough for HTML generator .UX mac - - .ux with updated trademark owner - NETHACK MNH(7) +NETHACK 4 November 2018 MNH(7) diff --git a/doc/nethack.6 b/doc/nethack.6 index dda4c89f4..d6c922e00 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -1,91 +1,142 @@ -.TH NETHACK 6 "2 February 2018" NETHACK -.de ND -.ds Nd \\$3 -.. +.\"DO NOT REMOVE NH_DATESUB .TH NETHACK 6 "Date(%-d %B %Y)" Project(uc) +.TH NETHACK 6 "26 April 2026" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2024 .de NB .ds Nb \\$2 .. .de NR .ds Nr \\$2 .. -.ND $NHDT-Date: 1568509458 2019/09/15 01:04:18 $ -.NB $NHDT-Branch: NetHack-3.6 $ -.NR $NHDT-Revision: 1.16 $ +.NB $NHDT-Branch: NetHack-5 $ +.NR $NHDT-Revision: 1.31 $ +.\" groff and AT&T-descended troffs use different hyphenation patterns. +.\" Don't hyphenate the last word on a page or column, or +.\" before/after last/first 2 characters of a word. +.ie \n(.g .hy 12 +.el .hy 14 .ds Na Robert Patrick Rankin +.\" DWB, Solaris 10, and Plan 9 troffs don't support `\(ti`, `\(oq`, or +.\" `\(cq`. Assume the best, then detect these older troffs and fall +.\" back as needed. +.\" +.\" Put NO SPACE between special character and comment escape sequences. +.ds ~ \(ti\" The name "ti" is taken by *roff's `ti` request. +.ds oq \(oq +.ds cq \(cq +.if !\n(.g \{\ +. ds ~ ~ +. ds oq ` +. ds cq ' +.\} +.\" Define string to exercise groff's hyphenless break point feature. +.ie \n(.g .ds : \: +.el .ds : \" empty +.\" Define string to exercise groff's adjustable, unbreakable space. +.ie \n(.g .ds _ \~ +.el .ds _ \ \" backslash, space +.\" Define local versions of groff's "an-ext.tmac" macros if needed. +.ds %% \" empty +.if \n(.g .ig %% +.\" Add supplementary paragraph tag on its own line after TP. +.de TQ +. br +. ns +. \" Do not quote the argument to `TP`; the user might specify +. \" their own quotes for multi-word tags or to exercise AT&T troff +. \" quoting rules. +. TP \\$1\" +.. +.%% .SH NAME nethack \- Exploring The Mazes of Menace .SH SYNOPSIS +.HP +.nr sA \n(.j \" Save the adjustment mode. .na -.hy 0 .B nethack -[ -.B \-d -.I directory -] -[ -.B \-n -] -[ -.B \-p -.I profession -] -[ -.B \-r -.I race -] -[ -.B \-[DX] -] -[ -.B \-u -.I playername -] -[ -.B \-dec -] -[ -.B \-ibm -] -[ -.BR \-\-showpaths -] -[ -.BR \-\-version [ :paste ] +.RI [ role-option ] +.RB [ \-d | \-\-directory\*_\c +.IR directory ] +.RB [ \-w | \-\-windowtype\*_\c +.IR interface ] +\%[\c +.BI \-\-nethackrc: rc-file\c +|\c +.B \-\-no\-nethackrc\c ] +.RB [ \-n ] +.RB [ \-dec | \-ibm ] +.RB [ \-u\*_\c +.IR player-name ] +.RB [ \-X | \-D ] +.RB [ \-p\*_\c +.IR profession ] +.RB [ \-r\*_\c +.IR race ] +.RB [ \-@ ] +.PP +.I role-option +can be any of the following. .PP +.RS +.nf +.BR \-A | \-Arc +.BR \-B | \-Bar +.BR \-C | \-Cav +.BR \-H | \-Hea +.BR \-K | \-Kni +.BR \-M | \-Mon +.BR \-P | \-Pri +.BR \-R | \-Rog +.B \-Ran +.BR \-S | \-Sam +.BR \-T | \-Tou +.BR \-V | \-Val +.BR \-W | \-Wiz +.fi +.RE +.HP .B nethack -[ -.B \-d -.I directory -] -.B \-s -[ -.B \-v -] -[ -.B \-p -.I profession -] -[ -.B \-r -.I race -] -[ -.I playernames -] -.ad -.hy 14 +.RB { \-s | \-\-scores } +.RB [ \-d | \-\-directory\*_\c +.IR directory ] +.RB [ \-v ] +.RB [ \-p\*_\c +.IR profession ] +.RB [ \-r\*_\c +.IR race ] +.RI [ player-name\*_\c +\&.\|.\|.] +.PP +.B nethack +.RB { \-\-usage | \-\-help } +.PP +.B nethack +.B \-\-showpaths +.PP +.B nethack +.BR \-\-version [ :copy | :dump\c +.RB | :show ] +.ad \n(sA \" Restore the adjustment mode. .\" Make sure path is not hyphenated below .hw nethackdir .SH DESCRIPTION -.PP .I NetHack -is a display oriented Dungeons & Dragons(tm) - like game. -The standard tty display and command structure resemble rogue. +is a fantasy-themed game of survival, +exploration, +and combat +set in the Mazes of Menace, +an elaborate underground complex. .PP -Other, more graphical display options exist for most platforms. +Traditionally, +the game's interface uses a Unix terminal connection, +depicting the interface on a grid of character cells +and responding to keyboard-entered commands. +Other interface options exist for most platforms. .PP -To get started you really only need to know two commands. The command +To get started you really only need to know two commands. +The command .B ? will give you a list of the available commands (as well as other information) and the command @@ -95,9 +146,11 @@ will identify the things you see on the screen. To win the game (as opposed to merely playing to beat other people's high scores) you must locate the Amulet of Yendor which is somewhere below the 20th level of the dungeon and get it out. -Few people achieve this; most never do. Those who have go down -in history as heroes among heroes - and then they find ways of making the -game even harder. See the +Few people achieve this; most never do. +Those who have done so go down +in history as heroes among heroes \(em and then they find ways of making the +game even harder. +See the .I Guidebook section on Conduct if this game has gotten too easy for you. .PP @@ -118,7 +171,7 @@ The ? command provides a description of these options and syntax. .B \-dec and .B \-ibm -command line options are equivalent to the +command line options are mutually exclusive and are equivalent to the .B decgraphics and .B ibmgraphics @@ -126,20 +179,29 @@ run-time options described there, and are provided purely for convenience on systems supporting multiple types of terminals.) .PP -Because the option list can be very long (particularly when specifying -graphics characters), options may also be included in a configuration -file. +Because the option list can be very long, +options may also be included in a configuration file. The default is located in your home directory and -named .nethackrc on Unix systems. On other systems, the default may be -different, usually NetHack.cnf. On DOS or Windows, the name is -defaults.nh, while on the Macintosh or BeOS, it is NetHack Defaults. -The configuration file's location may be specified by setting NETHACKOPTIONS -to a string consisting of an @ character followed by the filename. +named .nethackrc on UNIX systems (including descendants such as +linux, NetBSD, and macOS). +On Windows, the name is also .nethackrc but the location can vary +(see +.B \-\-showpaths +below). +On other systems, the default may be different, possibly NetHack.cnf. +On MS-DOS, the name is defaults.nh in NetHack's directory (folder), +while +.\" on the Macintosh or BeOS, it is \*(lqNetHack Defaults\*(rq, and +on VMS|OpenVMS it is nethack.ini in your home directory. +The default configuration file may be overridden via the +.BI \-\-nethackrc: rc-file +command line option or by setting NETHACKOPTIONS in your environment +to a string consisting of an @ character followed by the path and filename. .PP The .B \-u -.I playername -option supplies the answer to the question "Who are you?". +.I player-name +option supplies the answer to the question \*(lqWho are you?\*(rq. It overrides any name from the options or configuration file, USER, LOGNAME, or getlogin(), which will otherwise be tried in order. If none of these provides a useful name, the player will be asked for one. @@ -148,100 +210,207 @@ so you can have several saved games under different names. Conversely, you must use the appropriate player name to restore a saved game. .PP A -.I playername +.I player-name suffix can be used to specify the profession, race, alignment and/or gender -of the character. The full syntax of the playername that includes a -suffix is "name-ppp-rrr-aaa-ggg". "ppp" are at least the first three letters -of the profession (this can also be specified using a separate +of the character. +The full syntax of a +.I player-name +including a suffix is \*(lqname\-ppp\-rrr\-aaa\-ggg\*(rq. +\*(lqppp\*(rq are at least the first three letters +of the profession (this can also be specified using a separate .B \-p .I profession -option). "rrr" are at least the first three letters of the character's -race (this can also be specified using a separate +option). +\*(lqrrr\*(rq are at least the first three letters of the character's +race (this can also be specified using a separate .B \-r .I race -option). "aaa" are at least the first three letters of the character's -alignment, and "ggg" are at least the first three letters of the -character's gender. Any of the parts of the suffix may be left out. +option). +\*(lqaaa\*(rq are at least the first three letters of the character's +alignment, and \*(lqggg\*(rq are at least the first three letters of the +character's gender. +Any of the parts of the suffix may be left out. .PP .B \-p .I profession can be used to determine the character profession, also known as the role. You can specify either the male or female name for the character role, or the first three characters of the role as an abbreviation. -.B "\-p \@" -has been retained to explicitly request that a random role be chosen. -It may need to be quoted with a backslash (\\@) if @ -is the "kill" character (see "stty") for the terminal, in order -to prevent the current input line from being cleared. +.\" .B "\-p @" +.\" has been retained to explicitly request that a random role be chosen. .PP Likewise, .B \-r .I race can be used to explicitly request that a race be chosen. .PP -Leaving out any of these characteristics will result in you being prompted -during the game startup for the information. -.PP -.PP -The -.B \-s -option alone will print out the list of your scores on the current version. -An immediately following -.B \-v -reports on all versions present in the score file. +.\" Note: 'BR -A | -Arc' produces "-A|-Arc" (no spaces); +.\" '-A | -Arc' newline '|' newline '-B | -Bar' produces "-A|-Arc | -B|-Bar" The -.B \-s -may also be followed by arguments -.B \-p -and -.B \-r -to print the scores of particular roles and races only. -It may also be followed by one or more player names to print the scores of the -players mentioned, by 'all' to print out all scores, or by a number to print -that many top scores. +.BR \-A | \-Arc +| +.BR \-B | \-Bar +| +.BR \-C | \-Cav +| +.BR \-H | \-Hea +| +.BR \-K | \-Kni +| +.BR \-M | \-Mon +| +.BR \-P | \-Pri +| +.BR \-R | \-Rog +| +.B \-Ran +| +.BR \-S | \-Sam +| +.BR \-T | \-Tou +| +.BR \-V | \-Val +| +.BR \-W | \-Wiz +options for role selection are maintained for compatibility with older +versions of the program. +They are mutually exclusive and the single-letter form must be uppercase. +.I Ranger +has no single-letter choice because +.B \-R +is already used for the +.I Rogue +role. +.PP +.B \-@ +tells NetHack to choose any omitted characteristics (profession/role, race, +gender, alignment) randomly without prompting. +Otherwise, leaving out any of these characteristics will result in you +being prompted during game startup for the information. .PP The .B \-n option suppresses printing of any news from the game administrator. .PP The -.B \-D -or .B \-X -option will start the game in a special non-scoring discovery mode. +option will start the game in a special non-scoring discovery mode +(also known as explore mode). .B \-D -will, if the player is the game administrator, start in debugging (wizard) -mode instead. +will start the game in debug mode (also known as wizard mode) after +changing the character name to \*(lqwizard\*(rq, +if the player is allowed. +Otherwise it will switch to +.BR \-X . +Control of who is allowed to use debug mode is done via the +.\" The `lq` and `rq` strings are not reliable in macro calls, because +.\" some nroffs interpolate `"` for them, messing up macro argument +.\" delimitation. Use an (initially) uglier method than `RI`. +.\".RI "\*(lq" WIZARDS= "\*(rq line in NetHack's " sysconf " file." +\*(lq\c +.I WIZARDS=\c +\*(rq +line in +NetHack's +.I sysconf +file. .PP The -.B \-d +.BR \-d " or " \-\-directory option, which must be the first argument if it appears, supplies a directory which is to serve as the playground. It overrides the value from NETHACKDIR, HACKDIR, or the directory specified by the game administrator during compilation -(usually /usr/games/lib/nethackdir). +(usually +.IR /usr/\*:games/\*:lib/\*:nethackdir ). This option is usually only useful to the game administrator. The playground must contain several auxiliary files such as help files, the list of top scorers, and a subdirectory .I save where games are saved. .PP -.B \-\-showpaths -can be used to cause NetHack to show where it is expecting -to find various configuration files. -.PP -.B \-\-version -can be used to cause NetHack to show the version information it -was compiled with, then exit. That will include the -.I git -commit hash if the information was available when the game was compiled. -On some platforms, such as windows and macosx, a variation -.B \-\-version:paste +The +.BR \-w " or " \-\-windowtype +.I +interface +option can be used to specify which interface to use if the program +has been built with support for more than one. +Specifying a value on the command line overrides any value +specified in the run-time configuration file. +NetHack's #version command shows available interfaces. +.PP +The +.BI \-\-nethackrc: rc-file +option will use +.I rc-file +instead of the default run-time configuration file +.RI "(typically " \*~/.nethackrc ) +and the +.B \-\-no\-nethackrc +option can be used to skip any run-time configuration file. +.PP +Some options provide feedback and then exit rather than play the game: +.PP +The +.BR \-s " or " \-\-scores +option alone will print out the list of your scores on the current version. +An immediately following +.B \-v +reports on all versions present in the score file. +.RB \*(oq \-s | \-s\*_\-v \*(cq +may also be followed by arguments +.B \-p +.I profession +and +.B \-r +.I race +to print the scores of particular roles and races only. +Either can be specified multiple times to include more than one role +or more than one race. +When both are specified, score entries which match either the role or the +race (or both) are printed rather than just entries which match both. +.RB \*(oq \-s | \-s\*_\-v \*(cq +may be followed by one or more player names to print the scores of the +players mentioned, by 'all' to print out all scores, or by a number to print +that many top scores. +Combining names with role or race or both will report entries which match +any of those rather than just the ones which match all. +.PP +.\" avoid hyphenating "version" in this paragraph (and beyond; don't care) +.hw version +.BR \-\-version " or " \-\-version:show +can be used to cause NetHack to show the version number, the date and +time that the program was built from its source code, and possibly +some auxiliary information about that source code, then exit. +The optional auxiliary information is \fIgit\fP +commit hash (reflecting the source code's most recent modification when +extracted from the \fIgit\fP version control system, if that is in use) +if available when the program was built. +On some platforms such as Windows and macOS, a variation, +.BR \-\-version:copy , can be used to cause NetHack to show the version information, then exit, -while also leaving a copy of the version information in the paste buffer +while also leaving a copy of that information in the paste buffer or clipboard for potential insertion into things like bug reports. -.SH AUTHORS +On any platform, +.B \-\-version:dump +can be used to show most of the data used when checking whether a save +file or bones file is compatible with the program. +The program will display a line containing five numbers expressed in +hexadecimal, then exit. +.PP +.B \-\-showpaths +can be used to cause NetHack to show where it is expecting +to find various files. +Among other things it shows the path to and name for the player's +run-time configuration file, a text file which can be edited to +customize aspects of how the game operates. .PP +.BR \-\-usage " or " \-\-help +will display information similar to this manual page, then exit. +Use +.RB \*(oq "nethack \-\-usage | more" \*(cq +to read it a page at a time. +.SH AUTHORS Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote the original hack, very much like rogue (but full of bugs). .PP @@ -255,151 +424,244 @@ A number of these miscreants are immortalized in the historical roll of dishonor and various other places. .PP The resulting mess is now called NetHack, to denote its -development by the Usenet. Andries Brouwer has made this request for the +development by the Usenet. +Andries Brouwer has made this request for the distinction, as he may eventually release a new version of his own. .SH FILES -.PP Run-time configuration options were discussed above and use a platform -specific name for a file in a platform specific location. For Unix, the -name is '.nethackrc' in the user's home directory. - -.br +specific name for a file in a platform specific location. +For Unix, the +name is +.I .nethackrc +in the user's home directory. +.PP All other files are in the playground directory, -normally /usr/games/lib/nethackdir. -If DLB was defined during the compile, the data files and special levels -will be inside a larger file, normally nhdat, instead of being separate -files. - -.br -.DT -.ta \w'cmdhelp, opthelp, wizhelp\ \ \ 'u -nethack The program itself. -.br -data, oracles, rumors Data files used by NetHack. -.br -quest.dat, bogusmon More data files. -.br -engrave, epitaph, tribute Still more data files. -.br -symbols Data file holding sets of specifications -.br - for how to display monsters, objects, and -.br - map features. -.br -options Data file containing a description of the - build-time option settings. -.br -help, hh Help data files. -.br -cmdhelp, opthelp, wizhelp More help data files. -.br -*.lev Predefined special levels. -.br -dungeon Control file for special levels. -.br -history A short history of NetHack. -.br -license Rules governing redistribution. -.br -record The list of top scorers. -.br -logfile An extended list of games played -.br - (optional). -.br -xlogfile A more detailed version of 'logfile' -.br - (also optional). -.br -paniclog Record of exceptional conditions -.br - discovered during program execution. -.br -xlock.nn Description of dungeon level 'nn' of -.br - active game 'x' if there's a limit on the -.br - number of simultaneously active games. -.br -UUcccccc.nn Alternate form for dungeon level 'nn' -.br - of active game by user 'UU' playing -.br - character named 'cccccc' when there's no -.br - limit on number of active games. -.br -perm Lock file for xlock.0 or UUcccccc.0. -.br -bonesDD.nn Descriptions of the ghost and belongings -.br - of a deceased adventurer who met his -.br - or her demise on level 'nn'. -.br -.\"following line should contain - -.br -save/ A subdirectory containing saved games. -.br -.\"following line should contain - -.br -sysconf System-wide options. Required if -.br - program is built with 'SYSCF' option -.br - enabled, ignored if not. -.br - -The location of 'sysconf' is specified at build time and can't be changed -except by updating source file "config.h" and rebuilding the program. -.br - -In a perfect world, 'paniclog' would remain empty. +normally +.IR /usr/\*:games/\*:lib/\*:nethackdir . +If DLB was defined during the compile, +the data files and special levels will be inside a larger file, +normally +.IR nhdat , +instead of being separate files. +.TP +.I nethack +The program itself. +.TP +.I Guidebook +.TQ +.I Guidebook.txt +NetHack's user manual. +.TP +.I data +.TQ +.I oracles +.TQ +.I rumors +Data files used by NetHack. +.TP +.I bogusmon +Another data file. +.TP +.I engrave +.TQ +.I epitaph +.TQ +.I tribute +Still more data files. +.TP +.I symbols +Data file holding sets of specifications +for how to display monsters, objects, and +map features. +.TP +.I options +Data file containing a description of the +build-time option settings. +.TP +.I help +.TQ +.I hh +.TQ +.I cmdhelp +Help data files. +.RI ( cmdhelp +is obsolete.) +.TP +.I opthelp +.TQ +.I optmenu +.TQ +.I wizhelp +More help data files. +.TP +.I keyhelp +.TQ +.I usagehlp +Even more help data files. +.TP +.RI * .lua +Predefined special levels, dungeon control +for special levels, quest texts. +.TP +.I history +A short history of NetHack. +.TP +.I license +Rules governing redistribution. +.TP +.I record +The list of top scorers. +.TP +.I logfile +An extended list of games played +(optional). +.TP +.I xlogfile +A more detailed version of +.I logfile +(also optional). +.TP +.I paniclog +Record of exceptional conditions +discovered during program execution. +.TP +.RI x lock. nn +Description of dungeon level +.I nn +of active game +.I x +if there's a limit on the +number of simultaneously active games. +.TP +.RI UUcccccc . nn +Alternate form for dungeon level +.I nn +of active game by user +.I UU +playing character named +.I cccccc +when there's no +limit on number of active games. +.TP +.I perm +Lock file for +.RI x lock.0 +or +.RI UUcccccc .0 . +.TP +.IR bonD0. nn +Descriptions of the ghost and belongings +of a deceased adventurer who met his or +her demise on level +.IR nn . +A subsequent +character might encounter this old level. +.TP +.I save/ +Subdirectory containing saved games. +.TP +.I sysconf +System-wide options. +Required if +program is built with 'SYSCF' option +enabled, ignored if not. +.PP +The location of +.I sysconf +is specified at build time and can't be changed +except by updating source file +.\" We do the following in an ugly and non-idiomatic way to work around +.\" a DWB 3.3 nroff bug. +.\" troff: if-else overflow.; doc/nethack.6:623 +.\" stack: }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S RI +.\" Even at that, DWB insists on setting the period in roman. +"\c +.I config.h\c +" +and rebuilding the program. +.PP +NetHack's Guidebook might not be present if whoever packaged or installed +the program distribution neglected to include it. +.PP +In a perfect world, +.I paniclog +would remain empty. .SH ENVIRONMENT -.DT -.ta \w'NETHACKDIR or HACKDIR\ \ \ 'u -USER or LOGNAME Your login name. -.br -HOME Your home directory. -.br -SHELL Your shell. -.br -TERM The type of your terminal. -.br -HACKPAGER or PAGER Replacement for default pager. -.br -MAIL Mailbox file. -.br -MAILREADER Replacement for default reader -.br - (probably /bin/mail or /usr/ucb/mail). -.br -NETHACKDIR or HACKDIR Playground. -.br -NETHACKOPTIONS String predefining several NetHack -.br - options. -.br - -If the same option is specified in both NETHACKOPTIONS and .nethackrc, -the value assigned in NETHACKOPTIONS takes precedence. -.br - -SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode. -.br -DEBUGFILES can be used if the program was built with 'DEBUG' enabled. -.SH "SEE ALSO" +In some cases, +.I NetHack +attempts to access multiple environment variables in sequence +(via +.IR getenv (3) +or similar) +to determine information. +.TP 16n \" "NETHACKOPTIONS" + 2n +.I USER +.TQ +.I +LOGNAME +Your login name. +.TP +.I HOME +Your home directory. +.TP +.I SHELL +Your login shell +(not necessarily the one running when you started +.IR NetHack ). +.TP +.I TERM +Your terminal type. +.TP +.I HACKPAGER +.TQ +.I PAGER +Replacement for default pager. +.TP +.I MAIL +Mailbox file. +.TP +.I MAILREADER +Replacement for default reader +(probably +.I /bin/\*:mail +or +.IR /usr/\*:ucb/\*:mail ). +.TP +.I NETHACKDIR +.TQ +.I HACKDIR +Playground. +.TP +.I NETHACKOPTIONS +Predefined +.I NetHack +options. .PP -dgn_comp(6), lev_comp(6), recover(6) -.SH BUGS +If the same option is specified in both +.I \%NETHACKOPTIONS +and +.IR \%.nethackrc , +the value assigned in +.I \%NETHACKOPTIONS +takes precedence. .PP +.I SHOPTYPE +and +.I \%SPLEVTYPE +can be used in debugging (wizard) mode. +.I \%DEBUGFILES +can be used if the program was built with 'DEBUG' enabled. +.SH "SEE ALSO" +.IR recover (6) +.SH BUGS Probably infinite. .SH COPYRIGHT -This file is Copyright (C) \*(Na and was last modified \*(Nd (version -\*(Nb:\*(Nr). -NetHack may be freely redistributed. See license for details. -.PP -Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/nethack.txt b/doc/nethack.txt index 95a220b4a..c3e19b0e2 100644 --- a/doc/nethack.txt +++ b/doc/nethack.txt @@ -6,18 +6,44 @@ NAME nethack - Exploring The Mazes of Menace SYNOPSIS - nethack [ -d directory ] [ -n ] [ -p profession ] [ -r race ] [ -[DX] ] - [ -u playername ] [ -dec ] [ -ibm ] [ --showpaths ] [ --version[:paste] - ] + nethack [role-option] [-d|--directory directory] [-w|--window- + type interface] [--nethackrc:rc-file|--no-nethackrc] [-n] + [-dec|-ibm] [-u player-name] [-X|-D] [-p profession] [-r race] + [-@] - nethack [ -d directory ] -s [ -v ] [ -p profession ] [ -r race ] [ - playernames ] + role-option can be any of the following. + + -A|-Arc + -B|-Bar + -C|-Cav + -H|-Hea + -K|-Kni + -M|-Mon + -P|-Pri + -R|-Rog + -Ran + -S|-Sam + -T|-Tou + -V|-Val + -W|-Wiz + + nethack {-s|--scores} [-d|--directory directory] [-v] [-p profession] + [-r race] [player-name ...] + + nethack {--usage|--help} + + nethack --showpaths + + nethack --version[:copy|:dump|:show] DESCRIPTION - NetHack is a display oriented Dungeons & Dragons(tm) - like game. The - standard tty display and command structure resemble rogue. + NetHack is a fantasy-themed game of survival, exploration, and combat + set in the Mazes of Menace, an elaborate underground complex. - Other, more graphical display options exist for most platforms. + Traditionally, the game's interface uses a Unix terminal connection, + depicting the interface on a grid of character cells and responding to + keyboard-entered commands. Other interface options exist for most + platforms. To get started you really only need to know two commands. The command ? will give you a list of the available commands (as well as other @@ -27,37 +53,39 @@ DESCRIPTION To win the game (as opposed to merely playing to beat other people's high scores) you must locate the Amulet of Yendor which is somewhere below the 20th level of the dungeon and get it out. Few people achieve - this; most never do. Those who have go down in history as heroes among - heroes - and then they find ways of making the game even harder. See - the Guidebook section on Conduct if this game has gotten too easy for - you. + this; most never do. Those who have done so go down in history as + heroes among heroes -- and then they find ways of making the game even + harder. See the Guidebook section on Conduct if this game has gotten + too easy for you. When the game ends, whether by your dying, quitting, or escaping from the caves, NetHack will give you (a fragment of) the list of top scor- ers. The scoring is based on many aspects of your behavior, but a rough estimate is obtained by taking the amount of gold you've found in the cave plus four times your (real) experience. Precious stones may - be worth a lot of gold when brought to the exit. There is a 10% - penalty for getting yourself killed. + be worth a lot of gold when brought to the exit. There is a 10% pen- + alty for getting yourself killed. The environment variable NETHACKOPTIONS can be used to initialize many run-time options. The ? command provides a description of these - options and syntax. (The -dec and -ibm command line options are equiv- - alent to the decgraphics and ibmgraphics run-time options described - there, and are provided purely for convenience on systems supporting - multiple types of terminals.) - - Because the option list can be very long (particularly when specifying - graphics characters), options may also be included in a configuration - file. The default is located in your home directory and named - .nethackrc on Unix systems. On other systems, the default may be dif- - ferent, usually NetHack.cnf. On DOS or Windows, the name is - defaults.nh, while on the Macintosh or BeOS, it is NetHack Defaults. - The configuration file's location may be specified by setting NETHACK- - OPTIONS to a string consisting of an @ character followed by the file- - name. - - The -u playername option supplies the answer to the question "Who are + options and syntax. (The -dec and -ibm command line options are mutu- + ally exclusive and are equivalent to the decgraphics and ibmgraphics + run-time options described there, and are provided purely for conve- + nience on systems supporting multiple types of terminals.) + + Because the option list can be very long, options may also be included + in a configuration file. The default is located in your home directory + and named .nethackrc on UNIX systems (including descendants such as + linux, NetBSD, and macOS). On Windows, the name is also .nethackrc but + the location can vary (see --showpaths below). On other systems, the + default may be different, possibly NetHack.cnf. On MS-DOS, the name is + defaults.nh in NetHack's directory (folder), while on VMS|OpenVMS it is + nethack.ini in your home directory. The default configuration file may + be overridden via the --nethackrc:rc-file command line option or by + setting NETHACKOPTIONS in your environment to a string consisting of an + @ character followed by the path and filename. + + The -u player-name option supplies the answer to the question "Who are you?". It overrides any name from the options or configuration file, USER, LOGNAME, or getlogin(), which will otherwise be tried in order. If none of these provides a useful name, the player will be asked for @@ -66,9 +94,9 @@ DESCRIPTION versely, you must use the appropriate player name to restore a saved game. - A playername suffix can be used to specify the profession, race, align- - ment and/or gender of the character. The full syntax of the playername - that includes a suffix is "name-ppp-rrr-aaa-ggg". "ppp" are at least + A player-name suffix can be used to specify the profession, race, + alignment and/or gender of the character. The full syntax of a player- + name including a suffix is "name-ppp-rrr-aaa-ggg". "ppp" are at least the first three letters of the profession (this can also be specified using a separate -p profession option). "rrr" are at least the first three letters of the character's race (this can also be specified using @@ -80,156 +108,255 @@ DESCRIPTION -p profession can be used to determine the character profession, also known as the role. You can specify either the male or female name for the character role, or the first three characters of the role as an - abbreviation. -p @ has been retained to explicitly request that a ran- - dom role be chosen. It may need to be quoted with a backslash (\@) if - @ is the "kill" character (see "stty") for the terminal, in order to - prevent the current input line from being cleared. + abbreviation. Likewise, -r race can be used to explicitly request that a race be cho- sen. - Leaving out any of these characteristics will result in you being - prompted during the game startup for the information. + The -A|-Arc | -B|-Bar | -C|-Cav | -H|-Hea | -K|-Kni | -M|-Mon | -P|-Pri + | -R|-Rog | -Ran | -S|-Sam | -T|-Tou | -V|-Val | -W|-Wiz options for + role selection are maintained for compatibility with older versions of + the program. They are mutually exclusive and the single-letter form + must be uppercase. Ranger has no single-letter choice because -R is + already used for the Rogue role. - The -s option alone will print out the list of your scores on the cur- - rent version. An immediately following -v reports on all versions - present in the score file. The -s may also be followed by arguments -p - and -r to print the scores of particular roles and races only. It may - also be followed by one or more player names to print the scores of the - players mentioned, by 'all' to print out all scores, or by a number to - print that many top scores. + -@ tells NetHack to choose any omitted characteristics (profes- + sion/role, race, gender, alignment) randomly without prompting. Other- + wise, leaving out any of these characteristics will result in you being + prompted during game startup for the information. The -n option suppresses printing of any news from the game administra- tor. - The -D or -X option will start the game in a special non-scoring dis- - covery mode. -D will, if the player is the game administrator, start - in debugging (wizard) mode instead. - - The -d option, which must be the first argument if it appears, supplies - a directory which is to serve as the playground. It overrides the - value from NETHACKDIR, HACKDIR, or the directory specified by the game - administrator during compilation (usually /usr/games/lib/nethackdir). - This option is usually only useful to the game administrator. The - playground must contain several auxiliary files such as help files, the - list of top scorers, and a subdirectory save where games are saved. + The -X option will start the game in a special non-scoring discovery + mode (also known as explore mode). -D will start the game in debug + mode (also known as wizard mode) after changing the character name to + "wizard", if the player is allowed. Otherwise it will switch to -X. + Control of who is allowed to use debug mode is done via the "WIZARDS=" + line in NetHack's sysconf file. + + The -d or --directory option, which must be the first argument if it + appears, supplies a directory which is to serve as the playground. It + overrides the value from NETHACKDIR, HACKDIR, or the directory speci- + fied by the game administrator during compilation (usually /usr/games/ + lib/nethackdir). This option is usually only useful to the game admin- + istrator. The playground must contain several auxiliary files such as + help files, the list of top scorers, and a subdirectory save where + games are saved. + + The -w or --windowtype interface option can be used to specify which + interface to use if the program has been built with support for more + than one. Specifying a value on the command line overrides any value + specified in the run-time configuration file. NetHack's #version com- + mand shows available interfaces. + + The --nethackrc:rc-file option will use rc-file instead of the default + run-time configuration file (typically ~/.nethackrc) and the + --no-nethackrc option can be used to skip any run-time configuration + file. + + Some options provide feedback and then exit rather than play the game: + + The -s or --scores option alone will print out the list of your scores + on the current version. An immediately following -v reports on all + versions present in the score file. '-s|-s -v' may also be followed by + arguments -p profession and -r race to print the scores of particular + roles and races only. Either can be specified multiple times to + include more than one role or more than one race. When both are speci- + fied, score entries which match either the role or the race (or both) + are printed rather than just entries which match both. '-s|-s -v' may + be followed by one or more player names to print the scores of the + players mentioned, by 'all' to print out all scores, or by a number to + print that many top scores. Combining names with role or race or both + will report entries which match any of those rather than just the ones + which match all. + + --version or --version:show can be used to cause NetHack to show the + version number, the date and time that the program was built from its + source code, and possibly some auxiliary information about that source + code, then exit. The optional auxiliary information is git commit hash + (reflecting the source code's most recent modification when extracted + from the git version control system, if that is in use) if available + when the program was built. On some platforms such as Windows and + macOS, a variation, --version:copy, can be used to cause NetHack to + show the version information, then exit, while also leaving a copy of + that information in the paste buffer or clipboard for potential inser- + tion into things like bug reports. On any platform, --version:dump can + be used to show most of the data used when checking whether a save file + or bones file is compatible with the program. The program will display + a line containing five numbers expressed in hexadecimal, then exit. --showpaths can be used to cause NetHack to show where it is expecting - to find various configuration files. + to find various files. Among other things it shows the path to and + name for the player's run-time configuration file, a text file which + can be edited to customize aspects of how the game operates. - --version can be used to cause NetHack to show the version information - it was compiled with, then exit. That will include the git commit hash - if the information was available when the game was compiled. On some - platforms, such as windows and macosx, a variation --version:paste can - be used to cause NetHack to show the version information, then exit, - while also leaving a copy of the version information in the paste buf- - fer or clipboard for potential insertion into things like bug reports. + --usage or --help will display information similar to this manual page, + then exit. Use 'nethack --usage | more' to read it a page at a time. AUTHORS - Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote the + Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote the original hack, very much like rogue (but full of bugs). - Andries Brouwer continuously deformed their sources into an entirely + Andries Brouwer continuously deformed their sources into an entirely different game. Mike Stephenson has continued the perversion of sources, adding various - warped character classes and sadistic traps with the help of many - strange people who reside in that place between the worlds, the Usenet - Zone. A number of these miscreants are immortalized in the historical + warped character classes and sadistic traps with the help of many + strange people who reside in that place between the worlds, the Usenet + Zone. A number of these miscreants are immortalized in the historical roll of dishonor and various other places. - The resulting mess is now called NetHack, to denote its development by + The resulting mess is now called NetHack, to denote its development by the Usenet. Andries Brouwer has made this request for the distinction, as he may eventually release a new version of his own. FILES - Run-time configuration options were discussed above and use a platform - specific name for a file in a platform specific location. For Unix, - the name is '.nethackrc' in the user's home directory. - - All other files are in the playground directory, normally - /usr/games/lib/nethackdir. If DLB was defined during the compile, the - data files and special levels will be inside a larger file, normally - nhdat, instead of being separate files. - - nethack The program itself. - data, oracles, rumors Data files used by NetHack. - quest.dat, bogusmon More data files. - engrave, epitaph, tribute Still more data files. - symbols Data file holding sets of specifications - for how to display monsters, objects, and - map features. - options Data file containing a description of the - build-time option settings. - help, hh Help data files. - cmdhelp, opthelp, wizhelp More help data files. - *.lev Predefined special levels. - dungeon Control file for special levels. - history A short history of NetHack. - license Rules governing redistribution. - record The list of top scorers. - logfile An extended list of games played - (optional). - xlogfile A more detailed version of 'logfile' - (also optional). - paniclog Record of exceptional conditions - discovered during program execution. - xlock.nn Description of dungeon level 'nn' of - active game 'x' if there's a limit on the - number of simultaneously active games. - UUcccccc.nn Alternate form for dungeon level 'nn' - of active game by user 'UU' playing - character named 'cccccc' when there's no - limit on number of active games. - perm Lock file for xlock.0 or UUcccccc.0. - bonesDD.nn Descriptions of the ghost and belongings - of a deceased adventurer who met his - or her demise on level 'nn'. - - save/ A subdirectory containing saved games. - - sysconf System-wide options. Required if - program is built with 'SYSCF' option - enabled, ignored if not. - - The location of 'sysconf' is specified at build time and can't be - changed except by updating source file "config.h" and rebuilding the - program. - - In a perfect world, 'paniclog' would remain empty. + Run-time configuration options were discussed above and use a platform + specific name for a file in a platform specific location. For Unix, + the name is .nethackrc in the user's home directory. + + All other files are in the playground directory, normally /usr/games/ + lib/nethackdir. If DLB was defined during the compile, the data files + and special levels will be inside a larger file, normally nhdat, + instead of being separate files. + + nethack + The program itself. + + Guidebook + Guidebook.txt + NetHack's user manual. + + data + oracles + rumors Data files used by NetHack. + + bogusmon + Another data file. + + engrave + epitaph + tribute + Still more data files. + + symbols + Data file holding sets of specifications for how to display mon- + sters, objects, and map features. + + options + Data file containing a description of the build-time option set- + tings. + + help + hh + cmdhelp + Help data files. (cmdhelp is obsolete.) + + opthelp + optmenu + wizhelp + More help data files. + + keyhelp + usagehlp + Even more help data files. + + *.lua Predefined special levels, dungeon control for special levels, + quest texts. + + history + A short history of NetHack. + + license + Rules governing redistribution. + + record The list of top scorers. + + logfile + An extended list of games played (optional). + + xlogfile + A more detailed version of logfile (also optional). + + paniclog + Record of exceptional conditions discovered during program exe- + cution. + + xlock.nn + Description of dungeon level nn of active game x if there's a + limit on the number of simultaneously active games. + + UUcccccc.nn + Alternate form for dungeon level nn of active game by user UU + playing character named cccccc when there's no limit on number + of active games. + + perm Lock file for xlock.0 or UUcccccc.0. + + bonD0.nn + Descriptions of the ghost and belongings of a deceased adven- + turer who met his or her demise on level nn. A subsequent char- + acter might encounter this old level. + + save/ Subdirectory containing saved games. + + sysconf + System-wide options. Required if program is built with 'SYSCF' + option enabled, ignored if not. + + The location of sysconf is specified at build time and can't be changed + except by updating source file "config.h" and rebuilding the program. + + NetHack's Guidebook might not be present if whoever packaged or + installed the program distribution neglected to include it. + + In a perfect world, paniclog would remain empty. ENVIRONMENT - USER or LOGNAME Your login name. - HOME Your home directory. - SHELL Your shell. - TERM The type of your terminal. - HACKPAGER or PAGER Replacement for default pager. - MAIL Mailbox file. - MAILREADER Replacement for default reader - (probably /bin/mail or /usr/ucb/mail). - NETHACKDIR or HACKDIR Playground. - NETHACKOPTIONS String predefining several NetHack - options. - - If the same option is specified in both NETHACKOPTIONS and .nethackrc, + In some cases, NetHack attempts to access multiple environment vari- + ables in sequence (via getenv(3) or similar) to determine information. + + USER + LOGNAME Your login name. + + HOME Your home directory. + + SHELL Your login shell (not necessarily the one running when + you started NetHack). + + TERM Your terminal type. + + HACKPAGER + PAGER Replacement for default pager. + + MAIL Mailbox file. + + MAILREADER Replacement for default reader (probably /bin/mail or + /usr/ucb/mail). + + NETHACKDIR + HACKDIR Playground. + + NETHACKOPTIONS Predefined NetHack options. + + If the same option is specified in both NETHACKOPTIONS and .nethackrc, the value assigned in NETHACKOPTIONS takes precedence. - SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode. + SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode. DEBUGFILES can be used if the program was built with 'DEBUG' enabled. SEE ALSO - dgn_comp(6), lev_comp(6), recover(6) + recover(6) BUGS Probably infinite. COPYRIGHT - This file is Copyright (C) Robert Patrick Rankin and was last modified - 2019/09/15 (version NetHack-3.6:1.16). NetHack may be freely redis- - tributed. See license for details. - - Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc. + This file is Copyright (C) Robert Patrick Rankin, 2024 for version + NetHack-5:1.31. NetHack may be freely redistributed. See license for + details. -NETHACK 2 February 2018 NETHACK(6) +NETHACK 26 April 2026 NETHACK(6) diff --git a/doc/options.txt b/doc/options.txt new file mode 100644 index 000000000..54c654161 --- /dev/null +++ b/doc/options.txt @@ -0,0 +1,113 @@ +The definition for each OPTIONS= option resides in include/optlist.h as of +February 2020 in the WIP branch. + +Boolean and compound options are combined into a single allopt[] array. + +To add an entirely new option macro type: + + The current list of option macros: + NHOPTB (for boolean options) + NHOPTC (for complex options that take values beyond off/on) + NHOPTP (for handling a suite that all begin with a common prefix) + NHOPTO (for other options not easily handled as one of the above) + + 1. You need to add three different expansions of your macro, one for + the NHOPT_PROTO phase where function prototypes are generated, + one for the NHOPT_ENUM phase where enums are generated, and + NHOPT_PARSE phase. + + 2. If you are adding a new macro type to the current NHOPTB, + NHOPTC, NHOPTP, NHOPTO macros, don't forget to add the #undef near + the bottom of optlist.h, so that the macro is available for re-use + during the next usage phase. + + To add an option: + + 1. Add an entry to include/optlist.h, using the NHOPTB macro for a + boolean on/off option, or NHOPTC macro for a complex option, + or NHOPTP macro if it handles an entire prefix, or NHOPTO macro for + other types. + + The list of options is always kept in optlist.h in alphabetical order. + + When the list of options is processed during the compile of options.c, + the following will be automatically generated and included in + options.c: + + i) an optfn_xxxx function prototype (xxxx is the option name). + ii) an opt_xxxx enum value for referencing that option index by + name throughout options.c (xxxx is the option name). + iii) an initialization of an element in the allopt[] array, at + index opt_xxxx from step ii (xxxx is the option name). + + 2. If you are adding a boolean option, link it to a global variable + (e.g. in flags or iflags) and update optfn_boolean in options.c if + necessary. + + 3. If you are not adding a boolean option, create the optfn_xxxx() + function in options.c. Failure to do that will result in a link error + of "undefined function optfn_xxxx." The functions are in options.c in + alphabetical sequence by function name. + + The skeletal template for an optn_xxxx() function is: + + int + optfn_xxxx(optidx, req, negated, opts, op) + int optidx /* the index of this option opt_xxxx */ + int req; /* the request ID from core functions */ + boolean negated; /* will be true if opt was negated */ + char *opts; /* points to the complete opt string */ + char *op; /* points to value portion of opt string */ + { + if (req == do_init) { + return optn_ok; + } + if (req == do_set) { + /* do option set processing for the option */ + /* if successful, return optn_ok; */ + /* if unsuccessful, return optn_err; */ + } + if (req == get_val) { + /* return the current val of option in supplied opts buf */ + if (!opts) + return optn_err; + Sprintf(opts, "%s", fakefunction_to_get_xxxx_value_goes_here); + return optn_ok; + } + if (req == do_handler) { + + /* this is optional. If the option needs its own + special handling after the doset menu, do it here + or call a function to do it. The naming convention + for such a function in options.c has been + handler_xxxx(), but the function does not need to + reside in options.c */ + + return optn_ok; + } + return optn_ok; + } + + 4. NOTE: If you add (or delete) an option, please update the short + options help (option_help()), the long options help (dat/opthelp) + and also the Guidebooks. + +Here's some information about the req ID's passed to optfn_xxxx() functions. +Each optfn_xxxx() function can be called with a req id of: do_init, do_set, +do_handler or get_val. + +req do_init is called from options_init, and if initialization or memory +allocation or other initialization for that particular option is needed, +it can be done in response to the init req + +req do_set is called from parseoptions() for each option it encounters +and the optfn_xxxx() function is expected to react and set the option +based on the string values that parseoptions() passes to it. + +req get_val is passed a buffer from its caller that the optfn_xxxx() is +expected to fill with the current value of the option. + +req do_handler is called during doset() operations processing in response +to player selections, most likely from the 'O' option-setting menu. The +do_handler req is only called for options that were marked as supporting +do_handler in the option definition in include/optlist.h diff --git a/doc/recover.6 b/doc/recover.6 index 1209d31d3..a1c8ad68b 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -1,90 +1,110 @@ -.TH RECOVER 6 "14 December 2015" NETHACK -.de ND -.ds Nd \\$3 -.. +.\"DO NOT REMOVE NH_DATESUB .TH RECOVER 6 "Date(%-d %B %Y)" Project(uc) +.TH RECOVER 6 "26 April 2026" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2024 .de NB .ds Nb \\$2 .. .de NR .ds Nr \\$2 .. -.ND $NHDT-Date: 1524689550 2018/04/25 20:52:30 $ -.NB $NHDT-Branch: NetHack-3.6.0 $ -.NR $NHDT-Revision: 1.9 $ +.NB $NHDT-Branch: NetHack-5 $ +.NR $NHDT-Revision: 1.12 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ +.\" groff and AT&T-descended troffs use different hyphenation patterns. +.\" Don't hyphenate the last word on a page or column, or +.\" before/after last/first 2 characters of a word. +.ie \n(.g .hy 12 +.el .hy 14 .ds Na Kenneth Lorber .SH NAME recover \- recover a NetHack game interrupted by disaster .SH SYNOPSIS .B recover -[ -.B \-d -.I directory -] -.I "base1 base2" ... +.RB [ \-d +.IR playground-directory ] +.I base +\&.\|.\|. .SH DESCRIPTION -.PP -Occasionally, a NetHack game will be interrupted by disaster -when the game or the system crashes. -Prior to NetHack v3.1, these games were lost because various information +Occasionally, a NetHack game is interrupted by disaster +when the program or the system crashes. +Prior to NetHack v3.1, these games were lost because information like the player's inventory was kept only in memory. Now, all pertinent information can be written out to disk, so such games can be recovered at the point of the last level change. .PP -The -.I base -options tell +.I Base +operands tell .I recover which files to process. -Each base option specifies recovery of a separate game. +Each +.I base +specifies recovery of a separate game. .PP The .B \-d option, which must be the first argument if it appears, -supplies a directory which is the NetHack playground. -It overrides the value from NETHACKDIR, HACKDIR, or the directory +supplies the directory housing the NetHack playground. +It overrides the value of the environment variables +.I NETHACKDIR +and +.IR HACKDIR , +and the directory specified by the game administrator during compilation -(usually /usr/games/lib/nethackdir). +(usually +.IR /usr/games/lib/nethackdir ). +.ig .PP -^?ALLDOCS +\*^?ALLDOCS For recovery to be possible, -.I nethack +.IR nethack (6) must have been compiled with the INSURANCE option, and the run-time option .I checkpoint must also have been on. -^: -^?INSURANCE +\*^: +\*^?INSURANCE For recovery to be possible, .I nethack must have been compiled with the INSURANCE option (this configuration was), and the run-time option .I checkpoint must also have been on. -^: +\*^: This configuration of .I nethack was created without support for recovery. -^. -^. -NetHack normally writes out files for levels as the player leaves them, +\*^. +\*^. +.. +.IR nethack (6) +normally writes out files for levels as the player leaves them, so they will be ready for return visits. -When checkpointing, NetHack also writes out the level entered and +When checkpointing, it also writes out the level entered and the current game state on every level change. -This naturally slows level changes down somewhat. +This procedure slows level changes. .PP -The level file names are of the form base.nn, where nn is an internal -bookkeeping number for the level. -The file base.0 is used for game identity, locking, and, when checkpointing, +The level file names are of the form +.IR base. nn, where +.I nn +is an internal bookkeeping number for the level. +The file +.I base.0 +is used for game identity, locking, and, when checkpointing, for the game state. Various OSes use different strategies for constructing the base name. -Microcomputers use the character name, possibly truncated and modified +Single-user systems use the character name, +possibly truncated and modified to be a legal filename on that system. Multi-user systems use the (modified) character name prefixed by a user number to avoid conflicts, -or "xlock" if the number of concurrent players is being limited. +or +.I xlock +if the number of concurrent players is being limited. It may be necessary to look in the playground to find the correct base name of the interrupted game. .I recover -will transform these level files into a save file of the same name as +transforms these level files into a save file of the same name that .I nethack would have used. .PP @@ -99,13 +119,16 @@ through setuid or setgid is tantamount to leaving the playground world-writable, with respect to both cheating and messing up other players. For a single-user system, this of course does not change anything, -so some of the microcomputer ports install +so some of these ports install .I recover by default. .PP For a multi-user system, -the game administrator may want to arrange for all .0 files in the -playground to be fed to recover when the host machine boots, +the game administrator may want to arrange for all +.I .0 +files in the playground to be fed to +.I recover +when the host machine boots, and handle game crashes individually. If the user population is sufficiently trustworthy, .I recover @@ -116,12 +139,11 @@ In either case, .I recover is easily compiled from the distribution utility directory. .SH NOTES -.PP Like .I nethack itself, .I recover -will overwrite existing savefiles of the same name. +will overwrite existing save files of the same name. Savefiles created by .I recover are uncompressed; @@ -130,18 +152,24 @@ but even a compression-using .I nethack will find them in the uncompressed form. .SH "SEE ALSO" -nethack(6) +.IR nethack (6) .SH BUGS -.PP .I recover makes no attempt to find out if a base name specifies a game in progress. If multiple machines share a playground, this would be impossible to determine. .PP .I recover -should be taught to use the nethack playground locking mechanism to -avoid conflicts. +should be taught to use the +.I nethack +playground locking mechanism to avoid conflicts. .SH COPYRIGHT -This file is Copyright (C) \*(Na and was last modified \*(Nd (version -\*(Nb:\*(Nr). -NetHack may be freely redistributed. See license for details. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/recover.txt b/doc/recover.txt index c2d4af038..2631dda0e 100644 --- a/doc/recover.txt +++ b/doc/recover.txt @@ -6,66 +6,59 @@ NAME recover - recover a NetHack game interrupted by disaster SYNOPSIS - recover [ -d directory ] base1 base2 ... + recover [-d playground-directory] base ... DESCRIPTION - Occasionally, a NetHack game will be interrupted by disaster when the - game or the system crashes. Prior to NetHack v3.1, these games were - lost because various information like the player's inventory was kept - only in memory. Now, all pertinent information can be written out to - disk, so such games can be recovered at the point of the last level - change. + Occasionally, a NetHack game is interrupted by disaster when the pro- + gram or the system crashes. Prior to NetHack v3.1, these games were + lost because information like the player's inventory was kept only in + memory. Now, all pertinent information can be written out to disk, so + such games can be recovered at the point of the last level change. - The base options tell recover which files to process. Each base option - specifies recovery of a separate game. + Base operands tell recover which files to process. Each base specifies + recovery of a separate game. The -d option, which must be the first argument if it appears, supplies - a directory which is the NetHack playground. It overrides the value - from NETHACKDIR, HACKDIR, or the directory specified by the game admin- - istrator during compilation (usually /usr/games/lib/nethackdir). - - ^?ALLDOCS For recovery to be possible, nethack must have been compiled - with the INSURANCE option, and the run-time option checkpoint must also - have been on. ^: ^?INSURANCE For recovery to be possible, nethack must - have been compiled with the INSURANCE option (this configuration was), - and the run-time option checkpoint must also have been on. ^: This - configuration of nethack was created without support for recovery. ^. - ^. NetHack normally writes out files for levels as the player leaves - them, so they will be ready for return visits. When checkpointing, - NetHack also writes out the level entered and the current game state on - every level change. This naturally slows level changes down somewhat. - - The level file names are of the form base.nn, where nn is an internal - bookkeeping number for the level. The file base.0 is used for game - identity, locking, and, when checkpointing, for the game state. Vari- - ous OSes use different strategies for constructing the base name. - Microcomputers use the character name, possibly truncated and modified - to be a legal filename on that system. Multi-user systems use the + the directory housing the NetHack playground. It overrides the value + of the environment variables NETHACKDIR and HACKDIR, and the directory + specified by the game administrator during compilation (usually + /usr/games/lib/nethackdir). nethack(6) normally writes out files for + levels as the player leaves them, so they will be ready for return vis- + its. When checkpointing, it also writes out the level entered and the + current game state on every level change. This procedure slows level + changes. + + The level file names are of the form base.nn,where nn is an internal + bookkeeping number for the level. The file base.0 is used for game + identity, locking, and, when checkpointing, for the game state. Vari- + ous OSes use different strategies for constructing the base name. Sin- + gle-user systems use the character name, possibly truncated and modi- + fied to be a legal filename on that system. Multi-user systems use the (modified) character name prefixed by a user number to avoid conflicts, - or "xlock" if the number of concurrent players is being limited. It - may be necessary to look in the playground to find the correct base - name of the interrupted game. recover will transform these level files - into a save file of the same name as nethack would have used. + or xlock if the number of concurrent players is being limited. It may + be necessary to look in the playground to find the correct base name of + the interrupted game. recover transforms these level files into a save + file of the same name that nethack would have used. Since recover must be able to read and delete files from the playground and create files in the save directory, it has interesting interactions - with game security. Giving ordinary players access to recover through - setuid or setgid is tantamount to leaving the playground world- - writable, with respect to both cheating and messing up other players. - For a single-user system, this of course does not change anything, so - some of the microcomputer ports install recover by default. + with game security. Giving ordinary players access to recover through + setuid or setgid is tantamount to leaving the playground world- + writable, with respect to both cheating and messing up other players. + For a single-user system, this of course does not change anything, so + some of these ports install recover by default. For a multi-user system, the game administrator may want to arrange for - all .0 files in the playground to be fed to recover when the host + all .0 files in the playground to be fed to recover when the host machine boots, and handle game crashes individually. If the user popu- - lation is sufficiently trustworthy, recover can be installed with the - same permissions the nethack executable has. In either case, recover + lation is sufficiently trustworthy, recover can be installed with the + same permissions the nethack executable has. In either case, recover is easily compiled from the distribution utility directory. NOTES - Like nethack itself, recover will overwrite existing savefiles of the - same name. Savefiles created by recover are uncompressed; they may be - compressed afterwards if desired, but even a compression-using nethack + Like nethack itself, recover will overwrite existing save files of the + same name. Savefiles created by recover are uncompressed; they may be + compressed afterwards if desired, but even a compression-using nethack will find them in the uncompressed form. SEE ALSO @@ -73,17 +66,17 @@ SEE ALSO BUGS recover makes no attempt to find out if a base name specifies a game in - progress. If multiple machines share a playground, this would be + progress. If multiple machines share a playground, this would be impossible to determine. - recover should be taught to use the nethack playground locking mecha- + recover should be taught to use the nethack playground locking mecha- nism to avoid conflicts. COPYRIGHT - This file is Copyright (C) Kenneth Lorber and was last modified - 2018/04/25 (version NetHack-3.6.0:1.9). NetHack may be freely redis- - tributed. See license for details. + This file is Copyright (C) Kenneth Lorber, 2024 for version + NetHack-5:1.12. NetHack may be freely redistributed. See license for + details. -NETHACK 14 December 2015 RECOVER(6) +NETHACK 26 April 2026 RECOVER(6) diff --git a/doc/sound.txt b/doc/sound.txt new file mode 100644 index 000000000..608237c68 --- /dev/null +++ b/doc/sound.txt @@ -0,0 +1,625 @@ +NetHack 5.0 sound.txt $NHDT-Date: 1693253363 2023/08/28 20:09:23 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.7 $ + +Introduction + +This file documents the support for various sound library integration +interface, or just soundlib for short. + +The soundlib support is through a standard interface, separating the +main NetHack code from soundlib-specific code. The implementation +supports multiple soundlib systems in the same binary. Even if you only +wish to support one soundlib, you will need to follow the instructions +to end up with a compiled binary + +Copyright 2023, Michael Allison, with acknowledgement and thanks to +David Cohrs for window.txt that provided the inspiration for the layout +of this document. + +NetHack may be freely redistributed. See license for details. + +Contents: + I. Sound trigger types and terminology + II. Interface Specification + III. Global variables + IV. Other related routines + V. Game Startup and Soundlib Activation Sequencing + VI. Conventions + VII. Implementation and Multiple Soundlib Support + +I. Sound Trigger Types and Terminology + +There are 4 distinct types of sound sound_triggers used by NetHack. + + SOUND_TRIGGER_USERSOUNDS User-specified sounds that play based + on config file entries that identify a + regular expression to match against + message window text, and identify an + external sound file to load in response. + The sound interface function pointer + used to invoke it: + + void (*sound_play_usersound)(char *filename, + int32_t volume, int32_t idx); + + SOUND_TRIGGER_HEROMUSIC Invoked by the core when the in-game hero, + or perhaps another creature, is playing + a tune on an instrument. The sound interface + function pointer used to invoke it: + + void (*sound_hero_playnotes) + (int32_t instrument, const char *str, + int32_t volume); + + SOUND_TRIGGER_ACHIEVEMENTS Invoked by the core when an in-game + achievement is reached. The soundlib routines + could play appropriate theme or some fanfare + in response. + There needs to be a way to map each + achievement to a specific external + sound file or resource. The sound + interface function pointer used to + invoke it: + + void (*sound_achievement)(schar, schar, + int32_t); + + SOUND_TRIGGER_SOUNDEFFECTS Invoked by the core when something + sound-producing happens in the game. The + soundlib routines could play an appropriate + sound effect in response. They can be + public-domain or suitably licensed stock + sounds included with the + gamesource. The soundeffect must be made + available during the build process, or + (not-yet-implemented) a way to tie a + particular sound effect to a player-specified + sound samples within the player's config + file. The sound interface function + pointer used to invoke it: + + void (*sound_soundeffect)(char *desc, + int32_t seid, int32_t volume); + + SOUND_TRIGGER_AMBIENCE Invoked by the core in response to something + atmosphere or mood-producing or flavorful. + Unlike the other interface functions, this + one gets called to notify the sound interface + at the outset (ambience_begin), at the + termination (ambience_end), and + periodically in-between as needed + (ambience_update), likely with a different + hero proximity value. + + SOUND_TRIGGER_VERBAL Invoked by the core when someone (or something) + is speaking. + + +The types of sound sound_triggers supported by a particular soundlib +implementation are specified in that library's soundlib file, which is usually +found in sound//.c (.m in the case of macound), in +the sound_triggers field of the sound_procs struct: + + struct sound_procs { + const char *soundname; + enum soundlib_ids soundlib_id; + unsigned long sound_triggers; + void (*sound_init_nhsound)(void); + void (*sound_exit_nhsound)(const char *reason); + void (*sound_achievement)(schar arg1, schar arg2, int32_t avals); + void (*sound_soundeffect)(char *desc, int32_t, int32_t volume); + void (*sound_hero_playnotes)(int32_t instrument, const char *notestr, + int32_t volume); + void (*sound_play_usersound)(char *filename, int32_t volume, + int32_t usidx); + void (*sound_ambience)(int32_t ambienceid, int32_t ambience_action, + int32_t hero_proximity); + void (*sound_verbal)(char *text, int32_t gender, int32_t tone, + int32_t vol, int32_t moreinfo); + }; + +A sound library integration support file can implement one, two, three, four, +five, or six of the sound trigger types. The more types of sound_triggers the +soundlib implements, the more full-featured the sound experience will be +during the game. + +The values can be or'd together in the sound_triggers field initialization. + SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_HEROMUSIC + | SOUND_TRIGGER_ACHIEVEMENTS | SOUND_TRIGGER_SOUNDEFFECTS + | SOUND_TRIGGER_AMBIENCE | SOUND_TRIGGER_VERBAL + + +II. Interface Specification + +A. Integration routines: + +All functions below are void unless otherwise noted. + +sound_init_nhsound(void); + + -- NetHack will call this function when it is ready to enable sound + library support. It will do that during start-up, and it might do + it if the player has chosen to switch soundlib options. + +sound_exit_nhsound(const char *reason); + + -- NetHack will call this function when it wants to turn off the + sound library support and make it inactive. It will do that + when the game is ending, whether because the game is over or + because the player has chosen to save the game. The function + might also get called if the player has chosen to switch soundlib + options. + +sound_achievement(schar arg1, schar arg2, int32_t avals); + + -- NetHack will call this function when it wants to invoke a sound + based on an achievement, or an event that has occurred in the + game. + -- arg1 will contain the achievement value used internal to the + game, and if it is non-zero then arg2 should be ignored. + -- avals may contain more specific information about the achievement + or event that has just occurred. + For internal achievements (non-zero arg1), it will be zero if + this is the first occurrence of that achievement, or it will be + non-zero if this is a repeat occurrence. + -- arg2 is only used when arg1 iz zero. arg2 contains event + identifiers for various events that occur during the game. The + identifiers are from the 'enum achievements_arg2' list in + include/sndprocs.h. It is recommended that you look them up + there as new ones get added periodically as the game development + continues. The identifiers all begin with 'sa2_'. + For arg2 events, avals may contain additional integer information + specific to that particular event. For other events, it may be + meaningless. Those relationships will also be documented in + include/sndprocs.h as they develop. + +sound_soundeffect(char *desc, int32_t seid, int32_t volume); + + -- NetHack will call this function when it wants to invoke a particular + sound effect during the course of a game. The calls are typically + hard-coded into the NetHack sources at various appropriate points, + and the calls typically use the Soundeffects(desc, seid, volume) + macro to do so. They benefit of using the macro is that it does some + suitable validation checks before actually invoking the soundlib + function. + -- desc may hold a text description of the sound effect. Often this + field is not set, so the soundlib routine needs to be aware of + that and not depend on it holding a description. + -- The soundeffects identifiers (seid) are from the + 'enum sound_effect_entries' list in include/sndprocs.h. + It is recommended that you look them up there as new ones get + added periodically as game development continues. The identifiers + all begin with 'se_'. + +sound_hero_playnotes(int32_t instrument, const char *notestr, int32_t volume); + + -- NetHack will call this function when it wants a sequence of notes + (A,B,C,D,E,F,G) played, because the hero in the game, or a + creature in the game, is playing an instrument. + -- instrument specifies the instrument to use. The instrument + identifiers are from the 'enum instruments' list in + include/sndprocs.h. It is recommended that you look them up + there as new ones get added periodically as game development + continues. The identifiers all begin with 'ins_'. + Side note: the underlying values associated with those enums + match the instrument values in some MIDI specifications. If + they match the values for instruments in the underlying sound + library or platform API, they may be able to be passed through. + -- The sequence of notes is in notestr. At this time, NetHack may + be capping the number of notes at 5, but it is not + recommended that the soundlib integration support functions + rely on that note count cap as a hard rule. + -- A soundlib integration support file that has SOUND_TRIGGER_HEROMUSIC + support is expected to play the sound at the volume specified + by the volume argument (1 - 100, representing percentage of + possible volume levels), if the underlying sound library supports + volume adjustments. If it doesn't, the volume argument would + just have to be ignored. + +sound_play_usersound(char *filename, int32_t volume, int32_t usidx); + + -- NetHack will call this function when it wants a particular + external sound file played, based on a regular expression match + that the player has defined in their config file. + -- A soundlib integration support file that has SOUND_TRIGGER_USERSOUNDS + support is expected to play the sound file specified by the filename + argument. + -- A soundlib integration support file that has SOUND_TRIGGER_USERSOUNDS + support is expected to play the sound at the volume specified + by the volume argument (1 - 100, representing percentage of + possible volume levels), if the underlying sound library supports + volume adjustments. If it doesn't, the volume argument would + just have to be ignored. + +sound_ambience(int32_t ambienceid, int32_t ambience_action, + int32_t hero_proximity); + -- NetHack will call this function when it wants a particular + ambience related sound played in order to provide atmosphere + or flavor. + -- The ambienceid is used to identify the particular ambience sound + being sought. The abienceid identifiers are from the + 'enum ambiences' list in include/sndprocs.h. It is recommended + that you look them up there as new ones get added periodically + as game development continues. The identifiers all begin + with 'amb_'. + -- ambience_action. A soundlib integration support file that has + SOUND_TRIGGER_AMBIENCE support is expected to commence playing the + sound when it receives an ambience_action of ambience_begin. It + will receive an ambience_action of ambience_end when it should cease + playing the sound. It may receive an ambience_action of + ambience_update periodically, anytime the ambience is underway, + and it should respond accordingly: perhaps by adjusting the nature + of the sound being heard, or possibly by just adjusting the volume. + -- hero_proximity could be zero, in which case the ambience being + triggered is not impacted by the hero's distance from anything. + If the distance of the hero from the source of the ambience does + matter, then a distance value will be in hero_proximity. + +sound_verbal(char *text, int32_t gender, int32_t tone, int32_t vol, + int32_t moreinfo); + -- NetHack will call this function when it wants to pass text of + spoken language by a character or creature within the game. + -- text is a transcript of what has been spoken. + -- gender indicates MALE or FEMALE or NEUTRAL (either MALE + or FEMALE) voice. + -- tone indicates the tone of the voice. + -- vol is the volume (1% - 100%) for the sound. + -- moreinfo is used to provide additional information to the soundlib. + -- there may be some accessibility uses for this function. + + +III. Global variables + +The following global variables are defined in decl.c and are related to +the soundlib support in some way. They are just being documented here, +Some of them are expected to be used by the soundlib support file, +particularly where the core options interface is responsible for +setting the values. + +[TO BE DONE] + +soundprocs +gc.chosen_soundlib +ga.active_soundlib +a usersound mappings reference + +iflags.sounds is the master on/off switch to control whether any audio +is produced by the soundlib interface + +iflags.voice is the master on/off switch for voices produced by +the soundlib interface. + +IV. Other related routines + +These are not part of the interface, but mentioned here for your information. + +assign_soundlib(soundlib_identifier) + + -- Places a value into gc.chosen_soundlib as a "hint" that the + particular soundlib support is compiled in and thus available. + +activate_chosen_soundlib(void) + + -- If a soundlib is already active, indicated by ga.active_soundlib + holding the identifier of one of the added soundlib integrations, + then the sound_exit_nhsound() is called to turn it off or + deactivate it. + -- The soundlib identified in gc.chosen_soundlib is activated by + updating ga.active_soundlib, copying the chosen interface's + sound_proc structure into soundprocs, and calling the + soundlib interface's sound_init_nhsound() function. + +V. Game Start-up and Soundlib Activation Sequencing + +The following is the general order of calls that lead to soundlib +activation. + + 1. assign_soundlib(soundlib_identifier) + + The platform-specific main, or in the case of at least one + sound library that is integrated with the full visual/window + support (Qt) - the win_init_nhwindows() routine, drops + a hint about a supported soundlib by calling assign_soundlib. + + [The window interface has already been enabled by this point, + meaning that its win_init_nhwindows() has already been called. + That's important because for at least one of the soundlibs (Qt), + it is the window interface becoming active, and thus initializing + the underlying framework that includes both display and sound, + that has caused assign_soundlib() to be called again to indicate + that its soundlib interface routines are now the preferred soundlib + routines to use. That will have superseded the gc.chosen_soundlib + value that the platform's main() may have placed there earlier + via its own call to assign_soundlib()] + + 2. init_sound_disp_gamewindows() + -> activate_chosen_soundlib() is called prior to + displaying the game windows. + +VI. Conventions + +[to be done] + +The windsound soundlib is contained in sound/windsound, the macsound +soundlib is contained in sound/macsound. The files in these directories +contain _only_ soundlib code, and may be replaced completely by other +soundlib support. + + +VII. Implementation and Multiple Soundlib Support + + +Multiple soundlib routines are supported in the same binary. +When writing a new set of sound library integration routines +use the following guidelines: + +1) Pick a unique name to identify your soundlib. The default + built-in soundlib uses "nosound". Your name pick should make it + obvious which 3rd party sound library you are writing your + interface glue-code for. +2) When declaring your soundlib interface functions, precede the + function names with your unique prefix. For example, + + void myprefix_init_nhsound() + { + /* code for initializing the underlying sound library */ + } + + When/if calling one your own soundlib functions from within your + soundlib code (one calling another), we suggest calling the + prefixed version to avoid unnecessary overhead of using the + soundprocs function pointer. + + We also suggest declaring all functions (not just the interface + functions) with the prefix, or declare them static, to avoid + unexpected overlaps with other soundlibs. The same applies to + file-scope data variables. + +3) Declare a structure, "struct sound_procs myprefix_procs", (with your + prefix instead of "myprefix") and fill in names of all of your + interface functions. All functions specified as part of the interface + must be present, even if they have empty function bodies. + + struct sound_procs myprefix_procs = { + SOUNDID(myprefix), + SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_HEROMUSIC + | SOUND_TRIGGER_ACHIEVEMENTS |SOUND_TRIGGER_SOUNDEFFECTS + | SOUND_TRIGGER_AMBIENCE | SOUND_TRIGGER_VERBAL, + myprefix_init_nhsound, + myprefix_exit_nhsound, + myprefix_achievement, + myprefix_soundeffect, + myprefix_hero_playnotes, + myprefix_play_usersound, + myprefix_ambience, + myprefix_verbal), + }; + + The first entry in this structure should be the SOUNDID(myprefix) + where myprefix should be the name of your soundlib port. + After that, the next entry is the sound_triggers mask that identifies + what sound_triggers your soundlib will actually react to and + support. Don't include the sound_triggers values for functions that are + empty, so that the NetHack core code won't bother trying to call + them. The other entries are the function addresses. + + Assuming that you followed the convention in (2), you can safely copy + the structure definition from the sample skeleton located below in + this document and just change the prefix from "sample" to your prefix. + +4) Add a new section to the 'enum soundlib_ids' in include/sndprocs.h, + just above the entry for 'soundlib_notused'. There are some + placeholders for some soundlib possibilities in there already. You + can skip this step if your prefix matches one of those, as long as + it is unused and you aren't colliding with work already done. Check + for a subdirectory in sounds as a reliable indicator of whether it + is already being used. + + Enclose your new section in #ifdef preprocessor directive prefixed + with "SND_LIB_" (without the quotes) and the uppercase variation of + your soundlib name. + + #ifdef SND_LIB_MYPREFIX + soundlib_myprefix, + #endif + + Again, place that in the enum above the entry for 'soundlib_notused'. + +5) Edit mdlib.c and add an entry for your soundlib to the + soundlib_information soundlib_opts[] array + right above the final "{ 0, 0, 0, FALSE }," entry. + + #ifdef SND_LIB_MYPREFIX + { soundlib_myprefix, "soundlib_myprefix", + "", FALSE }, + #endif + + +6) Edit include/sndprocs.h and add yours to the multiline #if defined + used to #define SND_LIB_INTEGRATED when none of the active soundlibs + and placeholders are defined. + #if defined(SND_LIB_QTSOUND) || defined(SND_LIB_PORTAUDIO) \ + || defined(SND_LIB_OPENAL) || defined(SND_LIB_SDL_MIXER) \ + || defined(SND_LIB_MINIAUDIO) || defined(SND_LIB_FMOD) \ + || defined(SND_LIB_SOUND_ESCCODES) || defined(SND_LIB_VISSOUND) \ + || defined(SND_LIB_WINDSOUND) || defined(SND_LIB_MACSOUND) \ + || defined(SND_LIB_MYPREFIX) + + #define SND_LIB_INTEGRATED + [...] + +7) Edit sounds.c and add the extern entry for your soundlib's sound_procs + struct, enclosed with an #ifdef SND_LIB_MYPREFIX block. + + #ifdef SND_LIB_MYPREFIX + extern struct sound_procs myprefix_procs; + #endif + + +8) Also while editing sounds.c, add a reference for your myprefix_procs + as the last entry in the soundlib_choices[] array initializations, + enclosed with and #ifdef SND_LIB_MYPREFIX block. + + #ifdef SND_LIB_MYPREFIX + { &myprefix_procs }, + #endif + +9) If the soundlib you are using work across multiple (more than one) + platform, several files related to building for the various + systems and/or build tools will likely require updates in order + for them to be able to compile for, and link with, your soundlib + interface support and the underlying sound library it is meant to + use. This part often isn't particularly fun. The build tools are + all quite different, and many developers only understand the build + system for one platform/system better than others. It typically + comes down to experience and familiarity. + + Don't be afraid to get assistance with unfamiliar ones. + + Generally speaking, build tools need to know about: + - changes that are needed to include C preprocessor defines + for enabling the inclusion of your soundlib support on the + compiler command line for all NetHack files + ( -DSND_LIB_MYPREFIX ). + - changes that are needed to include header files supplied + by the underlying sound library, so they can be found + via include path updates on the compiler command line + ( -I../lib/myprefix/inc). + - changes that are needed to link in the sound library + itself during the linking stage of the build + ( -L ../lib/myprefix/lib/myprefix.lib ). + + Here are some known examples of what might have to change + at the time of this writing: + + sys/unix/hints/* + These hints files might require updates to + include your new soundlib addition. You can + look at what was done for macsound support + in sys/unix/hints/macOS.500 for inspiration. + + sys/unix/NetHack.xcodeproj/project.pbxproj + + Will require updates in order to build with + Xcode on macOS. + + sys/windows/Makefile.nmake + + Will require updates in order to build on + Windows with Visual studio nmake at the command + line. + + sys/windows/GNUmakefile + sys/windows/GNUmakefile.depend + + Will require updates in order to build on + Windows with mingw32 or MSYS2 using GNU make at + the command line. + + sys/windows/vs/NetHackW/NetHackW.vcxproj + + Will need an + entry added in order to build under visual + studio, and additional updates to link in the + underlying sound library, if it requires one. + +10) Look at your soundlib support file in sound/myprefix/myprefix.c + and make sure that all of the calls match the requirements laid out in + Section VI and VII. + +What follows is a sample soundlib interface that can be used as a +starting template. + +-- snip 8< -- +/* sample.c */ +/* NetHack may be freely redistributed. See license for details. */ + +#include "hack.h" + +/* + * Sample sound interface for NetHack + * + * Replace 'sample' with your soundlib name in this template file. + * Should be placed in ../sound/sample/. + */ + +static void sample_init_nhsound(void); +static void sample_exit_nhsound(const char *); +static void sample_achievement(schar, schar, int32_t); +static void sample_soundeffect(char *, int32_t, int32_t); +static void sample_hero_playnotes(int32_t, const char *, int32_t); +static void sample_play_usersound(char *, int32_t, int32_t); +static void sample_ambience(int32_t ambienceid, int32_t ambience_action, + int32_t hero_proximity); +static void (*sound_verbal)(char *text, int32_t gender, int32_t tone, + int32_t vol, int32_t moreinfo); + +struct sound_procs sample_procs = { + SOUNDID(sample), + SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_HEROMUSIC + | SOUND_TRIGGER_ACHIEVEMENTS |SOUND_TRIGGER_SOUNDEFFECTS + | SOUND_TRIGGER_AMBIENCE + sample_init_nhsound, + sample_exit_nhsound, + sample_achievement, + sample_soundeffect, + sample_hero_playnotes, + sample_play_usersound, + sample_ambience, + sample_verbal +}; + +static void +sample_init_nhsound(void) +{ + /* Initialize external sound library */ +} + +static void +sample_exit_nhsound(const char *reason) +{ + /* Close / Terminate external sound library */ + +} + +/* fulfill SOUND_TRIGGER_ACHIEVEMENTS */ +static void +sample_achievement(schar ach1, schar ach2, int32_t avals) +{ + + +} + +/* fulfill SOUND_TRIGGER_SOUNDEFFECTS */ +static void +sample_soundeffect(char *desc, int32_t seid, int volume) +{ + +} + +/* fulfill SOUND_TRIGGER_HEROMUSIC */ +static void sample_hero_playnotes(int32_t instrument, const char *str, int32_t volume) +{ + +} + +/* fulfill SOUND_TRIGGER_USERSOUNDS */ +static void +sample_play_usersound(char *filename, int volume, int usidx) +{ + +} + +static void +sample_ambience(int32_t ambienceid, int32_t ambience_action, + int32_t hero_proximity) +{ +} + +static void +sample_verbal(char *text, int32_t gender, int32_t tone, + int32_t vol, int32_t moreinfo) +{ +} + +/* end of sample.c */ +-- >8 -- diff --git a/doc/tmac.n b/doc/tmac.n index 270a78a06..4effecdc6 100644 --- a/doc/tmac.n +++ b/doc/tmac.n @@ -1,4 +1,4 @@ -\" @(#)$Id: tmac.n,v 1.4 2002/01/19 13:41:15 michael.allison Exp $ +.\" @(#)$Id: tmac.n,v 1.4 1989/03/15 Matt Bishop .\" The News macro package .\" .\" This is the macro package that is used to format news documents. It @@ -761,4 +761,3 @@ .\" couple of miscellaneous requests .bd S 3 3 \" embolden special font chars if B .hy 2 \" don't hyphenate last lines - diff --git a/doc/tmac.nh b/doc/tmac.nh index 5a1bd0a60..a109c66af 100644 --- a/doc/tmac.nh +++ b/doc/tmac.nh @@ -1,4 +1,4 @@ -.\" NetHack 3.6 tmac.nh $NHDT-Date: $ $NHDT-Branch: $:$NHDT-Revision: $ +.\" NetHack 5.0 tmac.nh $NHDT-Date: $ $NHDT-Branch: $:$NHDT-Revision: $ . .\" Miscellaneous tmac.n-style macros specifically for nethack's Guidebook. .\" @@ -8,6 +8,10 @@ .\" cluttered as their number increased. It now uses the '.so' directive .\" to include this file. (tmac.n is passed to 'roff on the command line.) . +.\" Protect against being sourced twice. +.nr nH +1 +.if \n(nH>1 .nx +. .\" labeled paragraph start .\" .PS word .\" set the width for the label column @@ -25,7 +29,7 @@ .\" labeled paragraph label (and first line) .de PL .br -\\h'|-\\n(PYu'\\$1\\h'|-\\n(PXu'\ -\ \\c \" back up, output the label, then +\\h'|-\\n(PYu'\\$1\\h'|-\\n(PXu'\ -\ \\c\" back up, output the label, then . \" skip to width-of(" - ") before the . \" normal indentation, output the " - " . \" then attach the next line (the @@ -85,7 +89,8 @@ . if \\n(id=0 \{\ . di \" end diversion . fi \" resume filling -. in -\\n(piu \" dedent +. ie \\n(.i<\\n(pi .in 0 +. el .in -\\n(piu \" dedent . ev \" pop environment . ne \\n(dnu \" be sure you have room . nf \" don't reprocess display @@ -118,7 +123,7 @@ .\" $1 - repeat count for amount of padding (optional; default is 1) .de BR .ie \\.$==0 .nr bR 1v -.el .nr bR (\\$1-0)v +.el .nr bR 0\\$1v \0 .sp \\n(bR .br @@ -129,4 +134,9 @@ \\$1\\$2 .. . +.\" groff and AT&T-descended troffs use different hyphenation patterns. +.\" Don't hyphenate the last word on a page or column, or +.\" before/after last/first 2 characters of a word. +.ie \n(.g .hy 12 +.el .hy 14 .\"tmac.nh/" diff --git a/doc/window.doc b/doc/window.txt similarity index 77% rename from doc/window.doc rename to doc/window.txt index 3758bf55b..ae69d4f00 100644 --- a/doc/window.doc +++ b/doc/window.txt @@ -1,4 +1,4 @@ -NetHack 3.6 window.doc $NHDT-Date: 1433901374 2015/06/10 01:56:14 $ $NHDT-Branch: master $:$NHDT-Revision: 1.42 $ +NetHack 5.0 window.txt $NHDT-Date: 1666390558 2022/10/21 22:15:58 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.70 $ Introduction @@ -18,11 +18,10 @@ Contents: III. Global variables IV. WINCAP preferences support V. New or respecified common, high level routines - VI. Helper routines - VII. Game startup - VIII. Conventions - IX. Implementation and Multi-window support - X. WINCHAIN + VI. Game startup + VII. Conventions + VIII. Implementation and Multi-window support + IX. WINCHAIN I. Window Types and Terminology @@ -37,7 +36,7 @@ The tty window-port also uses NHW_BASE (the base display) internally. (The genl_status_* routines use NHW_STATUS for backward compatibility when displaying status information on the bottom lines. New code - should not use NHW_STATUS. NHW_STATUS will be phased out over time.) + should not use NHW_STATUS. NHW_STATUS will be phased out over time.) NHW_MENU windows can be used for either menu or text display. Their basic feature is that for the tty-port, if the window is small enough, @@ -57,6 +56,19 @@ page using the DEF_PAGER, if DEF_PAGER is defined. There exists an assumption that the font for text windows is monospaced. The help files are all formatted accordingly. +NHW_MAP is a persistent window which uses tty-style character cell +column and row as x,y coordinates (even for tiled map). The y or row +coordinate runs from 0 through ROWNO-1 inclusive, with 0 at the top +and +(ROWNO-1) at the bottom. The x or column coordinate runs from +_1_ through COLNO-1, left to right. Column 0 is used by the core +for internal bookkeeping and not drawn on the screen. Most levels +leave some rows and/or columns unused but the core still passes data +(typically 'unexplored' or 'solid stone') for them and those should +be rendered to the screen. The exception is map column 0. The map +window does not need to include room for that; if it does, that column +should be drawn as for text map or the tile specified for +GLYPH_NOTHING for tiled map. + "window" is always of type winid. This is currently implemented as an integer, but doesn't necessarily have to be done that way. There are a few fixed window names that are known throughout the code: @@ -69,7 +81,7 @@ Other windows are created and destroyed as needed. (The genl_status_* routines use WIN_STATUS for backward compatibility when displaying status information on the bottom lines. New code - should not use WIN_STATUS, or assume its presence. NHW_STATUS will + should not use WIN_STATUS, or assume its presence. NHW_STATUS will be phased out over time.) "Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS @@ -102,7 +114,7 @@ curs(window, x, y) behavior when curs() is called outside the window's limits is unspecified. The mac port wraps to 0, with the status window being 2 lines high and 80 columns wide. - -- Still used by curs_on_u(), obsolete status updates, + -- Still used by curs_on_u(), obsolete status updates, screen locating (identify, teleport). -- NHW_MESSAGE, NHW_MENU and NHW_TEXT windows do not currently support curs in the tty window-port. @@ -112,10 +124,13 @@ putstr(window, attr, str) Multiple putstr()s are output on separate lines. Attributes can be one of ATR_NONE (or 0) - ATR_ULINE ATR_BOLD + ATR_DIM + ATR_ITALIC + ATR_ULINE ATR_BLINK ATR_INVERSE + If a window-port does not support all of these, it may map unsupported attributes to a supported one (e.g. map them all to ATR_INVERSE). putstr() may compress spaces out of @@ -128,28 +143,31 @@ putstr(window, attr, str) by calling more() or displaying both on the same line. putmixed(window, attr, str) -- Print str on the window with the given attribute. In - addition to printable ASCII characters (040-0126), + addition to printable ASCII characters (040-0126), sequences of encoded glyph values are supported. The glyph encoding sequence is \GXXXXNNNN, where: XXXX is a hexadecimal value. The value must match - the randomly generated value for the current - game in progress in order to be decoded. - The value for the game in progress is stored in - context.rndencode. This field minimizes - unintentional decoding of player-supplied strings + the randomly generated value for the current + game in progress in order to be decoded. + The value for the game in progress is stored in + context.rndencode. This field minimizes + unintentional decoding of player-supplied strings such as pet names, etc. NNNN is a hexadecimal value representing the glyph. If a window port does not yet support special handling of - the glyph value, it can use genl_putmixed (mapglyph.c) + the glyph value, it can use genl_putmixed (windows.c) which converts the encoded glyph into a character symbol. - Multiple putmixed()s are output on separate lines. Attributes - can be one of + Multiple putmixed()s are output on separate lines. + Attributes can be one of ATR_NONE (or 0) - ATR_ULINE ATR_BOLD + ATR_DIM + ATR_ITALIC + ATR_ULINE ATR_BLINK ATR_INVERSE + If a window-port does not support all of these, it may map unsupported attributes to a supported one (e.g. map them all to ATR_INVERSE). putmixed() may compress spaces out of @@ -192,18 +210,32 @@ int nh_poskey(int *x, int *y, int *mod) B. High-level routines: -print_glyph(window, x, y, glyph, bkglyph) - -- Print the glyph at (x,y) on the given window. Glyphs are - integers at the interface, mapped to whatever the window- +print_glyph(window, x, y, glyphinfo, bkglyphinfo) + -- Print a glyph found within the glyphinfo at (x,y) on the + given window. The glyphs within the glyph_info struct are + integers and can be mapped to whatever the window- port wants (symbol, font, color, attributes, ...there's a 1-1 map between glyphs and distinct things on the map). - -- bkglyph is a background glyph for potential use by some - graphical or tiled environments to allow the depiction - to fall against a background consistent with the grid - around x,y. If bkglyph is NO_GLYPH, then the parameter - should be ignored (do nothing with it). - -char yn_function(const char *ques, const char *choices, char default) + -- bkglyphinfo contains a background glyph for potential use + by some graphical or tiled environments to allow the + depiction to fall against a background consistent with the + grid around x,y. If bkglyphinfo->glyph is NO_GLYPH, then + the parameter should be ignored (do nothing with it). + -- glyph_info struct fields: + int glyph; /* the display entity */ + int color; /* color for window ports not using a tile */ + int ttychar; /* the character mapping for the original tty + * interface. Most or all window ports wanted + * and used this for various things so it is + * provided in 5.0+ */ + short int symidx; /* offset into syms array */ + unsigned glyphflags; /* more detail about the entity */ + + +char win_yn_function(const char *ques, const char *choices, char default) + -- Not to be confused with the core yn_function() + added in 3.4.2 and no yn_function() macro is defined + for this. -- Print a prompt made up of ques, choices and default. Read a single character response that is contained in choices or default. If choices is NULL, all possible @@ -248,17 +280,23 @@ player_selection() display_file(str, boolean complain) -- Display the file named str. Complain about missing files iff complain is TRUE. -update_inventory() - -- Indicate to the window port that the inventory has been - changed. - -- Merely calls display_inventory() for window-ports that - leave the window up, otherwise empty. +update_inventory(arg) + -- For an argument of 0: + -- Indicate to the window port that the inventory has + been changed. + -- Merely calls repopulate_perminvent() for window-ports + that leave the window up, otherwise empty. + -- or for a non-zero argument: + -- Prompts the user for a menu scrolling action and + executes that. + -- May repeat until user finishes (typically by using + or but interface may use other means). doprev_message() -- Display previous messages. Used by the ^P command. -- On the tty-port this scrolls WIN_MESSAGE back one line. update_positionbar(char *features) - -- Optional, POSITIONBAR must be defined. Provide some + -- Optional, POSITIONBAR must be defined. Provide some additional information for use in a horizontal position bar (most useful on clipped displays). Features is a series of char pairs. The first char @@ -303,14 +341,16 @@ display_nhwindow(window, boolean blocking) destroy_nhwindow(window) -- Destroy will dismiss the window if the window has not already been dismissed. -start_menu(window) +start_menu(window, unsigned long mbehavior) -- Start using window as a menu. You must call start_menu() before add_menu(). After calling start_menu() you may not putstr() to the window. Only windows of type NHW_MENU may be used for menus. -add_menu(windid window, int glyph, const anything identifier, - char accelerator, char groupacc, - int attr, char *str, boolean preselected) + -- mbehavior allows flags to be passed to alter the appearance + and/or behavior of the menu. +add_menu(windid window, glyphinfo, const anything identifier, char accelerator, + char groupacc, int attr, int clr, char *str, + unsigned itemflags) -- Add a text line str to the given menu window. If identifier is 0, then the line cannot be selected (e.g. a title). Otherwise, identifier is the value returned if the line is @@ -320,10 +360,11 @@ add_menu(windid window, int glyph, const anything identifier, accelerator. It is up to the window-port to make the accelerator visible to the user (e.g. put "a - " in front of str). The value attr is the same as in putstr(). - Glyph is an optional glyph to accompany the line. If - window port cannot or does not want to display it, this - is OK. If there is no glyph applicable, then this - value will be NO_GLYPH. + -- glyphinfo (glyph_info type) may optionally contain a glyph + to accompany the line. If a window port cannot + or does not want to display it, this is OK. If there is no + glyph provided, then the value of glyphinfo->glyph will + be NO_GLYPH. -- All accelerators should be in the range [A-Za-z], but there are a few exceptions such as the tty player selection code which uses '*'. @@ -337,8 +378,21 @@ add_menu(windid window, int glyph, const anything identifier, the menu command (or their user defined aliases), it loses. The menu commands and aliases take care not to interfere with the default object class symbols. - -- If you want this choice to be preselected when the - menu is displayed, set preselected to TRUE. + -- attr attributes can be one of + ATR_NONE (or 0) + ATR_BOLD + ATR_DIM + ATR_ITALIC + ATR_ULINE + ATR_BLINK + ATR_INVERSE + + If a window-port does not support all of these, it may map + unsupported attributes to a supported one (e.g. map them + all to ATR_INVERSE). + -- clr is color and is one of the NetHack CLR_ defines. + -- str is a pointer to the menu item text. + -- itemflags on this item (such as MENU_ITEMFLAGS_SELECTED etc.). end_menu(window, prompt) -- Stop adding entries to the menu and flushes the window @@ -387,56 +441,74 @@ char message_menu(char let, int how, const char *mesg) D. Status Display Routines status_init() -- core calls this to notify the window port that a status - display is required. The window port should perform + display is required. The window port should perform the necessary initialization in here, allocate memory, etc. -status_enablefield(int fldindex, char fldname, char fieldfmt, boolean enable) +status_enablefield(int fldindex, char fldname, char fieldfmt, boolean enable) -- notifies the window port which fields it is authorized to display. -- This may be called at any time, and is used - to disable as well as enable fields, depending on the + to disable as well as enable fields, depending on the value of the final argument (TRUE = enable). -- fldindex could be one of the following from botl.h: - BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH, - BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX, - BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX, - BL_LEVELDESC, BL_EXP, BL_CONDITION + BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH, + BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX, + BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX, + BL_LEVELDESC, BL_EXP, BL_CONDITION, BL_VERS -- There are MAXBLSTATS status fields (from botl.h) -status_update(int fldindex, genericptr_t ptr, int chg, int percentage, int color, long *colormasks) +status_update(int fldindex, genericptr_t ptr, int chg, int percentage, \ + int color, long *colormasks) -- update the value of a status field. -- the fldindex identifies which field is changing and is an integer index value from botl.h -- fldindex could be any one of the following from botl.h: - BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH, - BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX, - BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX, - BL_LEVELDESC, BL_EXP, BL_CONDITION + BL_TITLE, BL_STR, BL_DX, BL_CO, BL_IN, BL_WI, BL_CH, + BL_ALIGN, BL_SCORE, BL_CAP, BL_GOLD, BL_ENE, BL_ENEMAX, + BL_XP, BL_AC, BL_HD, BL_TIME, BL_HUNGER, BL_HP, BL_HPMAX, + BL_LEVELDESC, BL_EXP, BL_CONDITION, BL_VERS -- fldindex could also be BL_FLUSH (-1), which is not really - a field index, but is a special trigger to tell the + a field index, but is a special trigger to tell the windowport that it should output all changes received to this point. It marks the end of a bot() cycle. -- fldindex could also be BL_RESET (-2), which is not really - a field index, but is a special advisory to to tell the + a field index, but is a special advisory to tell the windowport that it should redisplay all its status fields, even if no changes have been presented to it. -- ptr is usually a "char *", unless fldindex is BL_CONDITION. If fldindex is BL_CONDITION, then ptr is a long value with any or none of the following bits set (from botl.h): - BL_MASK_STONE 0x00000001L - BL_MASK_SLIME 0x00000002L - BL_MASK_STRNGL 0x00000004L - BL_MASK_FOODPOIS 0x00000008L - BL_MASK_TERMILL 0x00000010L - BL_MASK_BLIND 0x00000020L - BL_MASK_DEAF 0x00000040L - BL_MASK_STUN 0x00000080L - BL_MASK_CONF 0x00000100L - BL_MASK_HALLU 0x00000200L - BL_MASK_LEV 0x00000400L - BL_MASK_FLY 0x00000800L - BL_MASK_RIDE 0x00001000L + BL_MASK_BAREH 0x00000001L + BL_MASK_BLIND 0x00000002L + BL_MASK_BUSY 0x00000004L + BL_MASK_CONF 0x00000008L + BL_MASK_DEAF 0x00000010L + BL_MASK_ELF_IRON 0x00000020L + BL_MASK_FLY 0x00000040L + BL_MASK_FOODPOIS 0x00000080L + BL_MASK_GLOWHANDS 0x00000100L + BL_MASK_GRAB 0x00000200L + BL_MASK_HALLU 0x00000400L + BL_MASK_HELD 0x00000800L + BL_MASK_ICY 0x00001000L + BL_MASK_INLAVA 0x00002000L + BL_MASK_LEV 0x00004000L + BL_MASK_PARLYZ 0x00008000L + BL_MASK_RIDE 0x00010000L + BL_MASK_SLEEPING 0x00020000L + BL_MASK_SLIME 0x00040000L + BL_MASK_SLIPPERY 0x00080000L + BL_MASK_STONE 0x00100000L + BL_MASK_STRNGL 0x00200000L + BL_MASK_STUN 0x00400000L + BL_MASK_SUBMERGED 0x00800000L + BL_MASK_TERMILL 0x01000000L + BL_MASK_TETHERED 0x02000000L + BL_MASK_TRAPPED 0x04000000L + BL_MASK_UNCONSC 0x08000000L + BL_MASK_WOUNDEDL 0x10000000L + BL_MASK_HOLDING 0x20000000L -- The value passed for BL_GOLD includes a leading - symbol for GOLD "$:nnn". If the window port needs to use - the textual gold amount without the leading "$:" the port + symbol for GOLD "$:nnn". If the window port needs to use + the textual gold amount without the leading "$:" the port will have to add 2 to the passed "ptr" for the BL_GOLD case. -- color is an unsigned int. int & 0x00FF = color CLR_* @@ -445,13 +517,12 @@ status_update(int fldindex, genericptr_t ptr, int chg, int percentage, int color This contains the color and attribute that the field should be displayed in. - This is relevant for everything except BL_CONDITION fldindex. - If fldindex is BL_CONDITION, this parameter should be ignored, - as condition hilighting is done via the next colormasks - parameter instead. + This is relevant for everything except BL_CONDITION. + If fldindex is BL_CONDITION, this parameter should be + ignored, as condition hilighting is done via the next + colormasks parameter instead. -- colormasks - pointer to cond_hilites[] array of colormasks. - Only relevant for BL_CONDITION fldindex. The window port should ignore this parameter for other fldindex values. @@ -513,17 +584,24 @@ status_update(int fldindex, genericptr_t ptr, int chg, int percentage, int color +------+----------------------+--------------------+ | 15 | CLR_WHITE | | +------+----------------------+--------------------+ - | 16 | HL_ATTCLR_DIM | | CLR_MAX + | 16 | HL_ATTCLR_UNDEF | | CLR_MAX + +------+----------------------+--------------------+ + | 17 | HL_ATTCLR_NONE | | CLR_MAX + 1 + +------+----------------------+--------------------+ + | 18 | HL_ATTCLR_BOLD | | CLR_MAX + 2 + +------+----------------------+--------------------+ + | 19 | HL_ATTCLR_DIM | | CLR_MAX + 3 +------+----------------------+--------------------+ - | 17 | HL_ATTCLR_BLINK | | + | 20 | HL_ATTCLR_ITALIC | | CLR_MAX + 4 +------+----------------------+--------------------+ - | 18 | HL_ATTCLR_ULINE | | + | 21 | HL_ATTCLR_ULINE | | CLR_MAX + 5 +------+----------------------+--------------------+ - | 19 | HL_ATTCLR_INVERSE | 00010110 | + | 22 | HL_ATTCLR_BLINK | | CLR_MAX + 6 +------+----------------------+--------------------+ - | 20 | HL_ATTCLR_BOLD | | + | 23 | HL_ATTCLR_INVERSE | | CLR_MAX + 7 +------+----------------------+--------------------+ - | 21 | beyond array boundary | BL_ATTCLR_MAX + | 24 | beyond array boundary| | BL_ATTCLR_MAX + The window port can AND (&) the bits passed in the ptr argument to status_update() with any non-zero @@ -545,6 +623,8 @@ E. Misc. Routines make_sound(???) -- To be determined later. THIS IS CURRENTLY UN-IMPLEMENTED. nhbell() -- Beep at user. [This will exist at least until sounds are redone, since sounds aren't attributable to windows anyway.] + Implementation should respect the flags.silent setting just + like the tty window-port does in tty_nhbell(). mark_synch() -- Don't go beyond this point in I/O on any channel until all channels are caught up to here. Can be an empty call for the moment @@ -569,14 +649,6 @@ can_suspend() -- Tell the core if the window system will allow the game to be suspended now. If unconditionally yes or no, use genl_can_suspend_yes() or genl_can_suspend_no(). -start_screen() -- Only used on Unix tty ports, but must be declared for - completeness. Sets up the tty to work in full-screen - graphics mode. Look at win/tty/termcap.c for an - example. If your window-port does not need this function - just declare an empty function. -end_screen() -- Only used on Unix tty ports, but must be declared for - completeness. The complement of start_screen(). - outrip(winid, int, time_t) -- The tombstone code. If you want the traditional code use genl_outrip for the value and check the #if in rip.c. @@ -587,36 +659,39 @@ preference_update(preference) port of that change. If your window-port is capable of dynamically adjusting to the change then it should do so. Your window-port will only be notified of a particular - change if it indicated that it wants to be by setting the + change if it indicated that it wants to be by setting the corresponding bit in the wincap mask. -getmsghistory(init) +getmsghistory(init) -- This is used to preserve message history between games by - obtaining the messages from the window port so that the core - can put them into the savefile. + obtaining the messages from the window port so that the + core can put them into the savefile. The routine is called repeatedly from the core save routine, - and the window port routine is expected to successively return - each message that it wants the game to store in the savefile, - starting with the oldest message first, finishing + and the window port routine is expected to successively + return each message that it wants the game to store in the + savefile, starting with the oldest message first, finishing with the most recent. If init is TRUE, start over again from most recent message. -putmsghistory(msg) +putmsghistory(const char *msg, boolean restoring) -- This is the counterpart to getmsghistory() for restores used to reload the port's message recall buffer. - The routine is called repeatedly from the core restore + The routine is called repeatedly from the core restore routine, starting with the oldest message first, and - finishing with the most recent one that it read from the savefile. - The window port routine is expected to load the message - recall buffers in such a way that the ordering remains correct. - The window port routine should make no assumptions about how - many messages are forthcoming, nor should it assume that - another message will follow this one, so it must be careful - to keep all pointers/indexes intact at the end of each call. + finishing with the most recent one that it read from the + savefile. The window port routine is expected to load the + message recall buffers in such a way that the ordering + remains correct. The window port routine should make no + assumptions about how many messages are forthcoming, nor + should it assume that another message will follow this one, + so it must be careful to keep all pointers/indexes intact + at the end of each call. If the window port receives more messages that can fit in its buffers, it is expected to scroll away the oldest from its buffers, much like it would with new messages being produced. + At the end of restoring messages, this will be called + one more time with msg NULL. III. Global variables @@ -631,8 +706,9 @@ winid WIN_MESSAGE, WIN_MAP, WIN_INVEN There is also a window called WIN_STATUS that is used only for backward compatibility in the genl_status_* set of generic status display functions. -char *AE, *AS; Checked in options.c to see if we should load and - switch to DECGraphics symset. It is #ifdefed VMS and UNIX. +char *AE, *AS; Checked in options.c to see if we should load and + switch to DECGraphics symset. It is #ifdefed VMS + and UNIX. int LI, CO; Set in sys/unix/ioctl.c. The following appears to be Unix specific. Other ports using the tty @@ -641,83 +717,83 @@ window-port should also declare this variable in one of your sys/*.c files. short ospeed; Set and declared in sys/unix/unixtty.c (don't know about other sys files). -The following global variable is defined in options.c. It equates a +The following global variable is defined in options.c. It equates a list of wincap option names with their associated bit-mask [see section IV WINCAP preferences support]. The array is zero-terminated. struct wc_Opt wc_options[]; One entry for each available WINCAP option. Each entry has a wc_name field and a wc_bit - field. + field. IV. WINCAP preferences support Starting with NetHack 3.4.0, the window interface was enhanced to provide -a common way of setting window port user preferences from the config file, +a common way of setting window port user preferences from the config file, and from the command line for some settings. The wincap preference settings all have their underlying values stored in iflags fields. The names of the wincap related fields are all pre- -fixed with wc_ or wc2_ to make it easy to identify them. Your window +fixed with wc_ or wc2_ to make it easy to identify them. Your window port can access the fields directly. Your window port identifies what options it will react to and support -by setting bits in the window_procs wincap mask and/or wincap2 mask. +by setting bits in the window_procs wincap mask and/or wincap2 mask. Your window port can also fill in the color-availability table for -the window port, has_color[CLR_MAX] to flag the colors it supports +the window port, has_color[CLR_MAX] to flag the colors it supports 1 it does, or 0 it doesn't. [CLR_MAX is 16 as of 3.6.3.] -See section IX for details of where the wincap masks reside. +See section IX for details of where the wincap masks reside. -Two things control whether any preference setting appears in the +Two things control whether any preference setting appears in the 'O' command options menu during the game: - 1. The option must be marked as being supported by having its + 1. The option must be marked as being supported by having its bit set in the window_procs wincap or wincap2 mask. - 2. The option must have its optflag field set to SET_IN_GAME in order - to be able to set the option, or marked DISP_IN_GAME if you just - want to reveal what the option is set to. + 2. The option must have its optflag field set to set_in_game in order + to be able to set the option, or marked set_gameview if you just + want to reveal what the option is set to. Both conditions must be true to be able to see or set the option from -within NetHack. +within NetHack. -The default values for the optflag field for all the options are -hard-coded into the option in options.c. The default value for -the wc_ options can be altered by calling +The default values for the optflag field for all the options are +hard-coded into the option in options.c. The default value for +the wc_ options can be altered by calling set_wc_option_mod_status(optmask, status) -The default value for the wc2_ options can be altered by calling +The default value for the wc2_ options can be altered by calling set_wc2_option_mod_status(optmask, status) -In each case, set the option modification status to one of SET_IN_FILE, -DISP_IN_GAME, or SET_IN_GAME. - -The setting of any wincap or wincap2 option is handled by the NetHack -core option processing code. You do not have to provide a parser in -your window port, nor should you set the values for the -iflags.wc_* and iflags.wc2_* fields directly within the port code. -The port code should honor whatever values were put there by the core -when processing options, either in the config file, or by the 'O' command. - -You may be wondering what values your window port will find in the -iflags.wc_* and iflags.wc2_* fields for options that the user has not +In each case, set the option modification status to one of set_in_config, +set_gameview, or set_in_game. + +The setting of any wincap or wincap2 option is handled by the NetHack +core option processing code. You do not have to provide a parser in +your window port, nor should you set the values for the +iflags.wc_* and iflags.wc2_* fields directly within the port code. +The port code should honor whatever values were put there by the core +when processing options, either in the config file, or by the 'O' command. + +You may be wondering what values your window port will find in the +iflags.wc_* and iflags.wc2_* fields for options that the user has not specified in his/her config file. Put another way, how does your port code tell if an option has not been set? The next paragraph explains that. -If the core does not set an option, it will still be initialized -to its default value. Those default values for the +If the core does not set an option, it will still be initialized +to its default value. Those default values for the iflags.wc_* and iflags.wc_* fields are: - o All boolean fields are initialized to the starting - value specified for that option in the boolopt array in - options.c. The window-port should respect that setting - unless it has a very good reason for not doing so. + o All boolean fields are initialized to the starting + value specified for that option in the boolopt array in + options.c. The window-port should respect that setting + unless it has a very good reason for not doing so. o All int fields are initialized to zero. Zero is not a valid setting for any of the int options, so if your port code encounters a zero there, it can assume that the preference option was not specified. In that case, the window-port code - should use a default setting that the port is comfortable with. + should use a default setting that the port is comfortable with. It should write the default setting back into the iflags.wc_* field. That is the only time that your window-port could should update those fields. o All "char *" fields will be null pointers. Be sure to check for - that in your window-port code before using such a pointer, or + that in your window-port code before using such a pointer, or you'll end up triggering a nasty fault. Here are the wincap and wincap2 preference settings that your port can choose @@ -745,6 +821,7 @@ to support: | font_size_text | WC_FONTSIZ_TEXT | wc_fontsiz_text |int | | hilite_pet | WC_HILITE_PET | wc_hilite_pet |boolean | | map_mode | WC_MAP_MODE | wc_map_mode |int | + | perm_invent | WC_PERM_INVENT | wc_perm_invent |boolean | | player_selection | WC_PLAYER_SELECTION| wc_player_selection|int | | popup_dialog | WC_POPUP_DIALOG | wc_popup_dialog |boolean | | preload_tiles | WC_PRELOAD_TILES | wc_preload_tiles |boolean | @@ -774,13 +851,20 @@ to support: | player option | bit in wincap mask | for value | type | |--------------------+--------------------+--------------------+--------+ | fullscreen | WC2_FULLSCREEN | wc2_fullscreen |boolean | - | softkeyboard | WC2_SOFTKEYBOARD | wc2_softkeyboard |boolean | - | wraptext | WC2_WRAPTEXT | wc2_wraptext |boolean | - | selectsaved | WC2_SELECTSAVED | wc2_selectsaved |boolean | + | guicolor | WC2_GUICOLOR | wc2_guicolor |boolean | + | hilite_status | WC2_HILITE_STATUS | wc2_hilite_status |strings | | hitpointbar | WC2_HITPOINTBAR | wc2_hitpointbar |boolean | - | term_cols | WC2_TERM_COLS | wc2_term_cols |int | - | term_rows | WC2_TERM_ROWS | wc2_term_rows |int | + | menu_shift_left | WC2_MENU_SHIFT | n/a |char | + | menu_shift_right | WC2_MENU_SHIFT | n/a |char | + | petattr | WC2_PETATTR | wc2_petattr |int | + | selectsaved | WC2_SELECTSAVED | wc2_selectsaved |boolean | + | softkeyboard | WC2_SOFTKEYBOARD | wc2_softkeyboard |boolean | + | statuslines | WC2_STATUSLINES | wc2_statuslines |int | + | term_cols | WC2_TERM_SIZE | wc2_term_cols |int | + | term_rows | WC2_TERM_SIZE | wc2_term_rows |int | + | use_darkgray | WC2_DARKGRAY | wc2_darkgray |boolean | | windowborders | WC2_WINDOWBORDERS | wc2_windowborders |int | + | wraptext | WC2_WRAPTEXT | wc2_wraptext |boolean | +--------------------+--------------------+--------------------+--------+ more wincap2 for STATUS_HILITES support and control @@ -797,6 +881,13 @@ to support: | fields should be redone | | +----------------------------------+---------------------------+ + additional wincap2 flag bits for supported putstr() attributes + +----------------------------------+---------------------------+ + | avoid putting message into | WC2_SUPPRESS_HIST | + | recall history | | + | draw extra attention to message | WC2_URGENT_MESG | + +----------------------------------+---------------------------+ + align_message -- where to place message window (top, bottom, left, right) align_status -- where to place status display (top, bottom, left, right). ascii_map -- port should display an ascii map if it can. @@ -807,7 +898,7 @@ font_menu -- port should use a font by this name for menu windows. font_message -- port should use a font by this name for message window. font_size_map -- port should use this size font for the map window. font_size_menu -- port should use this size font for menu windows. -font_size_message +font_size_message -- port should use this size font for the message window. font_size_status-- port should use this size font for the status display. font_size_text -- port should use this size font for text windows. @@ -828,14 +919,14 @@ selectsaved -- if port can display a menu of the user's saved games do so. softkeyboard -- handhelds should display an on-screen keyboard if possible. splash_screen -- port should/should not display an opening splashscreen. term_cols -- Terminal should size itself to specified width, if possible. -term_rows -- Terminal should size itself to specified height, if possible. +term_rows -- Terminal should size to specified height, if possible. tiled_map -- port should display a tiled map if it can. -tile_width -- port should display tiles with this width or round to closest - if it can. -tile_height -- port should display tiles with this height or round to closest - if it can. -tile_file -- open this alternative tile file. The file name is likely to be - window-port or platform specific. +tile_width -- port should display tiles with this width or round to + closest if it can. +tile_height -- port should display tiles with this height or round to + closest if it can. +tile_file -- open this alternative tile file. The file name is likely to + be window-port or platform specific. use_inverse -- port should display inverse when NetHack asks for it. vary_msgcount -- port should display this number of messages at a time in the message window. @@ -845,36 +936,36 @@ windowcolors -- port should use these colors for window foreground/background colors. Syntax: menu fore/back message fore/back status fore/back text fore/back -wraptext -- port should wrap long lines of text if they don't fit in +wraptext -- port should wrap long lines of text if they don't fit in the visible area of the window mouse_support -- port should enable mouse support if possible Whenever one of these settings is adjusted, the port is notified of a change to the setting by calling the port's preference_update() routine. The port is only notified if it has indicated that it supports that option by setting -the option's bit in the port's wincap mask. The port can choose to adjust +the option's bit in the port's wincap mask. The port can choose to adjust for the change to an option that it receives notification about, or ignore it. The former approach is recommended. If you don't want to deal with a -user-initiated setting change, then the port should call -set_wc_option_mod_status(mask, SET_IN_FILE) to make the option invisible to +user-initiated setting change, then the port should call +set_wc_option_mod_status(mask, set_in_config) to make the option invisible to the user. Functions available for the window port to call: set_wc_option_mod_status(optmask, status) - -- Adjust the optflag field for a set of wincap options to - specify whether the port wants the option to appear + -- Adjust the optflag field for a set of wincap options to + specify whether the port wants the option to appear in the 'O' command options menu, The second parameter, - "status" can be set to SET_IN_FILE, DISP_IN_GAME, - or SET_IN_GAME (SET_IN_FILE implies that the option + "status" can be set to set_in_config, set_gameview, + or set_in_game (set_in_config implies that the option is completely hidden during the game). set_wc2_option_mod_status(optmask, status) - -- Adjust the optflag field for a set of wincap2 options to - specify whether the port wants the option to appear + -- Adjust the optflag field for a set of wincap2 options to + specify whether the port wants the option to appear in the 'O' command options menu, The second parameter, - "status" can be set to SET_IN_FILE, DISP_IN_GAME, - or SET_IN_GAME (SET_IN_FILE implies that the option + "status" can be set to set_in_config, set_gameview, + or set_in_game (set_in_config implies that the option is completely hidden during the game). set_option_mod_status(optnam, status) @@ -882,7 +973,7 @@ set_option_mod_status(optnam, status) that is not part of the wincap suite. A port might use this to override the default initialization setting for status specified in options.c. Note that you have to - specify the option by name and that you can only set + specify the option by name and that you can only set one option per call unlike set_wc_option_mod_status(). @@ -892,7 +983,7 @@ To add a new wincap option, please follow all these steps: 1. Add the option to the wincap preference settings table above. Since wincap is full, your option will likely target wincap2 field. 2. Add the description to the paragraph below the chart. - 3. Add the WC_ or WC2_ to the bit list in include/winprocs.h + 3. Add the WC_ or WC2_ to the bit list in include/winprocs.h (in wincap2 if there is no room in wincap). 4. Add the wc_ or wc2_ field(s) to the iflags structure in flag.h. 5. Add the name and value to wc_options[] or wc2_options[] in options.c @@ -910,6 +1001,10 @@ char display_inventory(lets, want_reply) -- Calls a start_menu()/add_menu()/select_menu() sequence. It returns the item selected, or '\0' if none is selected. Returns '\033' if the menu was canceled. +void repopulate_perminvent(void) + -- a minimal alternative to display_inventory() that + focuses only on repopulating the permanent inventory + window. raw_printf(str, ...) -- Like raw_print(), but accepts arguments like printf(). This routine processes the arguments and then calls raw_print(). @@ -924,33 +1019,7 @@ pline(str, ...) by Norep() and pline(). If the window system is not active (!iflags.window_inited) pline() uses raw_print(). -VI. Helper Routines - -These are not part of the interface. They may be called by your -window port routines to perform the desired task, instead of duplicating -the necessary code in each window port. - -int mapglyph(int glyph, int *ochar, int *ocolor, unsigned *special, - int x, int y, unsigned mgflags) - -- Maps glyph at x,y to NetHack ascii character and color. - The return value is an index into the showsyms[] array, in - case a port wants to index into its own alternative - set of display symbols (such as a unicode set) instead of - the default set. - - If the glyph represents something special such as a pet, - that information is returned as set bits in "special.": - MG_CORPSE 0x01 - MG_INVIS 0x02 - MG_DETECT 0x04 - MG_PET 0x08 - MG_RIDDEN 0x10 - MG_STATUE 0x20 - MG_OBJPILE 0x40 - Usually called from the window port's print_glyph() - routine. - -VII. Game startup +VI. Game startup The following is the general order in which calls from main() should be made, as they relate to the window system. The actual code may differ, but the @@ -962,11 +1031,11 @@ initoptions() /* read the resource file */ init_nhwindows() /* initialize the window system */ process_options(argc, argv) /* process command line options or equiv */ if(save file is present) { - display_gamewindows() /* create & display the game windows */ + init_sound_disp_gamewindows() /* init sound, create & display */ dorestore() /* restore old game; pline()s are OK */ } else { player_selection() /* select a player type using a window */ - display_gamewindows() /* create & display the game windows */ + init_sound_disp_gamewindows() /* init sound, create & display */ } pline("Hello, welcome..."); @@ -981,27 +1050,31 @@ ini_routines have side effects that need to be undone, the old ini_routine (if any) will be called with an argument of WININIT_UNDO before the new ini_routine (if any) is called (with WININIT). -Display_gamewindows() is a common routine that displays the two standard -game windows (WIN_MESSAGE, WIN_MAP), and the status display. It is normally -called just before the "Hello, welcome" message. +Init_sound_and_display_gamewindows() is a common routine that initializes +the soundlib, then displays the standard game windows (WIN_MESSAGE, WIN_MAP, +etc.), and the status display. It is normally called just before the +"Hello, welcome" message. Process_options() is currently still unique to each port. There may be need in the future to make it possible to replace this on a per window-port basis. -VIII. Conventions +VII. Conventions init_nhwindows() is expected to display a gee-whiz banner window, including -the Copyright message. It is recommended that the COPYRIGHT_BANNER_A, -COPYRIGHT_BANNER_B, COPYRIGHT_BANNER_C, and COPYRIGHT_BANNER_D macros from -patchlevel.h and date.h be used for constructing the Copyright message. -COPYRIGHT_BANNER_A is a quoted string that has the NetHack copyright declaration, +the Copyright message. It is recommended that the COPYRIGHT_BANNER_A macro +from patchlevel.h, COPYRIGHT_BANNER_B from patchlevel.h, +nomakedefs.copyright_banner_c internal global variable, and +COPYRIGHT_BANNER_D macros from patchlevel.h be used for constructing the +Copyright message. +COPYRIGHT_BANNER_A is a quoted string that has NetHack copyright declaration, COPYRIGHT_BANNER_B is a quoted string that states who the copyright belongs to, -COPYRIGHT_BANNER_C is a quoted string generated by makedefs that includes version -and build information. and COPYRIGHT_BANNER_D simply says "See License for details." -Be sure to #include "patchlevel.h" and date.h to define these macros. Using the -macros will prevent having to update the Copyright information in each window-port -prior to each release. +nomakedefs.copyright_banner_c is a quoted string produced at runtime that +includes version and build information, and +COPYRIGHT_BANNER_D simply says "See License for details." +Be sure to #include "patchlevel.h" and date.h to define these macros. Using +the macros will prevent having to update the Copyright information in each +window-port prior to each release. Ports (MSDOS, TOS, MAC, etc) _may_ use window-port specific routines in their port specific files, _AT_THEIR_OWN_RISK_. Since "port" and @@ -1015,7 +1088,7 @@ in win/X11. The files in these directories contain _only_ window port code, and may be replaced completely by other window ports. -IX. Implementation and Multi-window support +VIII. Implementation and Multi-window support NetHack 3.2 and higher support multiple window systems in the same binary. When writing a new window-port, you need to follow the following guidelines: @@ -1108,7 +1181,7 @@ printing any message, because raw_print() cannot function without first setting the window-port. -X. WINCHAIN +IX. WINCHAIN WINCHAIN is an optional facility that allows the SYSCF_FILE to specify a series of processors that will see each call from the core to the window