Source Code 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1994 March / Source_Code_CD-ROM_Walnut_Creek_March_1994.iso / compsrcs / games / volume16 / nethck31 / part53 < prev next >

Wrap

Text File | 1993-02-03 | 58.0 KB | 1,422 lines

Path: uunet!news.tek.com!master!saab!billr From: billr@saab.CNA.TEK.COM (Bill Randle) Newsgroups: comp.sources.games Subject: v16i061: nethack31 - display oriented dungeons & dragons (Ver. 3.1), Part53/108 Message-ID: <4364@master.CNA.TEK.COM> Date: 1 Feb 93 19:43:17 GMT Sender: news@master.CNA.TEK.COM Lines: 1410 Approved: billr@saab.CNA.TEK.COM Xref: uunet comp.sources.games:1611 Submitted-by: izchak@linc.cis.upenn.edu (Izchak Miller) Posting-number: Volume 16, Issue 61 Archive-name: nethack31/Part53 Supersedes: nethack3p9: Volume 10, Issue 46-102 Environment: Amiga, Atari, Mac, MS-DOS, OS2, Unix, VMS, X11 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 53 (of 108)." # Contents: doc/Guidebook.te2 doc/window.doc # Wrapped by billr@saab on Wed Jan 27 16:09:07 1993 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'doc/Guidebook.te2' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/Guidebook.te2'\" else echo shar: Extracting \"'doc/Guidebook.te2'\" $34659 characters$ sed "s/^X//" >'doc/Guidebook.te2' <<'END_OF_FILE' X%.hn 1 X\section{Objects} X X%.pg XWhen you find something in the dungeon, it is common to want to pick Xit up. In {\it NetHack}, this is accomplished automatically by walking over Xthe object (unless you turn off the {\it pickup\/} Xoption (see below), or move with the `{\tt m}' prefix (see above)), or Xmanually by using the `{\tt ,}' command. If you're carrying too many Xthings, {\it NetHack\/} will tell you so and won't pick up anything more. XOtherwise, it will add the object(s) to your pack and tell you what you Xjust picked up. X X%.pg XWhen you pick up an object, it is assigned an inventory letter. Many Xcommands that operate on objects must ask you to find out which object Xyou want to use. When {\it NetHack\/} asks you to choose a particular object Xyou are carrying, you are usually presented with a list of inventory Xletters to choose from (see Commands, above). X X%.pg XSome objects, such as weapons, are easily differentiated. Others, like Xscrolls and potions, are given descriptions which vary according to Xtype. During a game, any two objects with the same description are Xthe same type. However, the descriptions will vary from game to game. X X%.pg XWhen you use one of these objects, if its effect is obvious, {\it NetHack\/} Xwill remember what it is for you. If its effect isn't extremely Xobvious, you will be asked what you want to call this type of object Xso you will recognize it later. You can also use the ``{\tt \#name}'' Xcommand for the same purpose at any time, to name all objects of a Xparticular type or just an individual object. X X%.hn 2 X\subsection*{Curses and blessings} X X%.pg XAny object that you find may be cursed, even if the object is Xotherwise helpful. The most common effect of a curse is being stuck Xwith (and to) the item. Cursed weapons weld themselves to your hand Xwhen wielded, so you cannot unwield them. Any cursed item you wear Xis not removable by ordinary means. In addition, cursed arms and armor Xusually, but not always, bear negative enchantments that make them Xless effective in combat. Other cursed objects may act poorly or Xdetrimentally in other ways. X X%.pg XObjects can also become blessed. Blessed items usually work better or Xmore beneficially than normal uncursed items. For example, a blessed Xweapon will do more damage against demons. X X%.pg XThere are magical means of bestowing or removing curses upon objects, Xso even if you are stuck with one, you can still have the curse Xlifted and the item removed. Priests and Priestesses have an innate Xsensitivity to curses and blessings, so they can more easily avoid Xcursed objects than other character classes. X X%.pg XAn item with unknown curse status, and an item which you know to be uncursed, Xwill be distinguished in your inventory by the presence of the word X``uncursed'' in the description of the latter. The exception is if this Xdescription isn't needed; you can look at the inventory description and know Xthat you have discovered whether it's cursed. This applies to items which Xhave ``plusses,'' and items with charges. X X%.hn 2 X\subsection*{Weapons (`{\tt )}')} X X%.pg XGiven a chance, most monsters in the Mazes of Menace will Xgratuitously kill you. You need weapons for self-defense (killing Xthem first). Without a weapon, you do only 1--2 hit points of damage X(plus bonuses, if any). X X%.pg XThere are wielded weapons, like maces and swords, and thrown weapons, Xlike arrows. To hit monsters with a weapon, you must wield it and Xattack them, or throw it at them. To shoot an arrow out of a bow, you Xmust first wield the bow, then throw the arrow. Crossbows shoot Xcrossbow bolts. Slings hurl rocks and (other) gems. You can wield Xonly one weapon at a time, but you can change weapons unless you're Xwielding a cursed one. X X%.pg XEnchanted weapons have a ``plus'' (which can also be a minus) Xthat adds to your chance Xto hit and the damage you do to a monster. The only way to find out Xif a weapon is enchanted is to have it magically identified somehow. X X%.pg XThose of you in the audience who are AD\&D players, be aware that each Xweapon which exists in AD\&D does the same damage to monsters in X{\it NetHack}. Some of the more obscure weapons (such as the % X{\it aklys}, {\it lucern hammer}, and {\it bec-de-corbin\/}) are defined Xin an appendix to {\it Unearthed Arcana}, an AD\&D supplement. X X%.pg XThe commands to use weapons are `{\tt w}' (wield) and `{\tt t}' (throw). X X%.hn 2 X\subsection*{Armor (`{\tt [}')} X X%.pg XLots of unfriendly things lurk about; you need armor to protect Xyourself from their blows. Some types of armor offer better Xprotection than others. Your armor class is a measure of this Xprotection. Armor class (AC) is measured as in AD\&D, with 10 being Xthe equivalent of no armor, and lower numbers meaning better armor. XEach suit of armor which exists in AD\&D gives the same protection in X{\it NetHack}. Here is an (incomplete) list of the armor classes provided by Xvarious suits of armor: X X\begin{center} X\begin{tabular}{lllll} Xdragon scale mail & 1 & \makebox[20mm]{} & chain mail & 5\\ Xplate mail & 3 & & scale mail & 6\\ Xbronze plate mail & 4 & & ring mail & 7\\ Xsplint mail & 4 & & studded leather armor & 7\\ Xbanded mail & 4 & & leather armor & 8\\ Xelven mithril-coat & 5 & & no armor & 10 X\end{tabular} X\end{center} X X%.pg X\nd You can also wear other pieces of armor (ex.\ helmets, boots, Xshields, cloaks) Xto lower your armor class even further, but you can only wear one item Xof each category (one suit of armor, one cloak, one helmet, one Xshield, and so on). X X%.pg XIf a piece of armor is enchanted, its armor protection will be better X(or worse) than normal, and its ``plus'' (or minus) will subtract from Xyour armor class. For example, a +1 chain mail would give you Xbetter protection than normal chain mail, lowering your armor class one Xunit further to 4. When you put on a piece of armor, you immediately Xfind out the armor class and any ``plusses'' it provides. Cursed Xpieces of armor usually have negative enchantments (minuses) in Xaddition to being unremovable. X X%.pg XThe commands to use armor are `{\tt W}' (wear) and `{\tt T}' (take off). X X%.hn 2 X\subsection*{Food (`{\tt \%}')} X X%.pg XFood is necessary to survive. If you go too long without eating you Xwill faint, and eventually die of starvation. Unprotected food does Xnot stay fresh indefinitely; after a while it will spoil, and be Xunhealthy to eat. Food stored in ice boxes or tins (``cans'' to you XAmericans) will usually stay fresh, but ice boxes are heavy, and tins Xtake a while to open. X X%.pg XWhen you kill monsters, they usually leave corpses which are also X``food.'' Many, but not all, of these are edible; some also give you Xspecial powers when you eat them. A good rule of thumb is ``you are Xwhat you eat.'' X%.pg XYou can name one food item after something you like to eat with the X{\it fruit\/} option, if your dungeon has it. X X%.pg XThe command to eat food is `{\tt e}'. X X%.hn 2 X\subsection*{Scrolls (`{\tt ?}')} X X%.pg XScrolls are labeled with various titles, probably chosen by ancient wizards Xfor their amusement value (ex.\ ``READ ME,'' or ``HOLY BIBLE'' backwards). XScrolls disappear after you read them (except for blank ones, without Xmagic spells on them). X X%.pg XOne of the most useful of these is the % X{\it scroll of identify}, which Xcan be used to determine what another object is, whether it is cursed or Xblessed, and how many uses it has left. Some objects of subtle Xenchantment are difficult to identify without these. X X%.pg XIf you receive mail while you are playing (on Xversions compiled with this feature), a mail daemon may run up and Xdeliver it to you as a % X{\it scroll of mail}. To use this feature, Xyou must let {\it NetHack\/} know where to look for new mail by setting the X``MAIL'' environment variable to the file name of your mailbox. You Xmay also want to set the ``MAILREADER'' environment variable to the Xfile name of your favorite reader, so {\it NetHack\/} can shell to it when you Xread the scroll. X X%.pg XThe command to read a scroll is `{\tt r}'. X X%.hn 2 X\subsection*{Potions (`{\tt !}')} X X%.pg XPotions are distinguished by the color of the liquid inside the flask. XThey disappear after you quaff them. X X%.pg XClear potions are potions of water. Sometimes these are Xblessed or cursed, resulting in holy or unholy water. Holy water is Xthe bane of the undead, so potions of holy water are good thing to Xthrow (`{\tt t}') at them. It also is very useful when you dip X(``{\tt \#dip}'') other Xobjects in it. X X%.pg XThe command to drink a potion is `{\tt q}' (quaff). X X%.hn 2 X\subsection*{Wands (`{\tt /}')} X X%.pg XMagic wands have multiple magical charges. Some wands are Xdirectional---you must give a direction to zap them in. You can also Xzap them at yourself (just give a `{\tt .}' or `{\tt s}' for the direction), Xbut it is often unwise. Other wands are nondirectional---they don't ask Xfor directions. The number of charges in a wand is random, and Xdecreases by one whenever you use it. X X%.pg XThe command to use a wand is `{\tt z}' (zap). X X%.hn 2 X\subsection*{Rings (`{\tt =}')} X X%.pg XRings are very useful items, since they are relatively permanent Xmagic, unlike the usually fleeting effects of potions, scrolls, and Xwands. XPutting on a ring activates its magic. You can wear only two Xrings, one on each ring finger. XMost rings also cause you to grow hungry more rapidly, the rate Xvarying with the type of ring. X X%.pg XThe commands to use rings are `{\tt P}' (put on) and `{\tt R}' (remove). X X%.hn 2 X\subsection*{Spell books (`{\tt +}')} X X%.pg XSpell books are tomes of mighty magic. When studied with the `{\tt r}' (read) Xcommand, they bestow the knowledge of a spell---unless the attempt Xbackfires. XReading a cursed spell book, or one with mystic runes beyond Xyour ken can be harmful to your health! X X%.pg XA spell can also backfire when you cast it. If you attempt to cast a Xspell well above your experience level, or cast it at a time when your Xluck is particularly bad, you can end up wasting both the energy and Xthe time required in casting. X X%.pg XCasting a spell calls forth magical energies and focuses them with Xyour naked mind. Releasing the magical energy releases some of your Xmemory of the spell with it. Each time you cast a spell, your Xfamiliarity with it will dwindle, until you eventually forget the Xdetails completely and must relearn it. X X%.pg XThe command to read a spell book is the same as for scrolls, `{\tt r}' X(read). The `{\tt +}' command lists your current spells and the number of Xspell points they require. The `{\tt Z}' (cast) command casts a spell. X X%.hn 2 X\subsection*{Tools (`{\tt (}')} X X%.pg XTools are miscellaneous objects with various purposes. Some tools, Xlike wands, have a limited number of uses. For example, lamps burn Xout after a while. Other tools are containers, which objects can Xbe placed into or taken out of. X X%.pg XThe command to use tools is `{\tt a}' (apply). X X%.hn 3 X\subsection*{Chests and boxes} X X%.pg XYou may encounter chests or boxes in your travels. These can be Xopened with the ``{\tt \#loot}'' extended command when they are on the floor, Xor with the `{\tt a}' (apply) command when you are carrying one. However, Xchests are often locked, and require you to either use a key to unlock Xit, a tool to pick the lock, or to break it open with brute force. XChests are unwieldy objects, and must be set down to be unlocked (by Xkicking them, using a key or lock picking tool with the `{\tt a}' (apply) Xcommand, or by using a weapon to force the lock with the ``{\tt \#force}'' Xextended command). X X%.pg XSome chests are trapped, causing nasty things to happen when you Xunlock or open them. You can check for and try to deactivate traps Xwith the ``{\tt \#untrap}'' extended command. X X%.hn 2 X\subsection*{Amulets (`{\tt "}')} X X%.pg XAmulets are very similar to rings, and often more powerful. Like Xrings, amulets have various magical properties, some beneficial, Xsome harmful, which are activated by putting them on. X X%.pg XThe commands to use amulets are the same as for rings, `{\tt P}' (put on) Xand `{\tt R}' (remove). X X%.hn 2 X\subsection*{Gems (`{\tt *}')} X X%.pg XSome gems are valuable, and can be sold for a lot of gold pieces. XValuable gems increase your score if you bring them with you when you Xexit. Other small rocks are also categorized as gems, but they are Xmuch less valuable. X X%.hn 2 X\subsection*{Large rocks (`{\tt `}')} X%.pg XStatues and boulders are not particularly useful, and are generally Xheavy. It is rumored that some statues are not what they seem. X X%.hn 2 X\subsection*{Gold (`{\tt \$}')} X X%.pg XGold adds to your score, and you can buy things in shops with it. XYour version of {\it NetHack\/} may display how much gold you have on the Xstatus line. If not, the `{\tt \$}' command will count it. X X%.hn 1 X\section{Options} X X%.pg XDue to variations in personal tastes and conceptions of how {\it NetHack\/} Xshould do things, there are options you can set to change how {\it NetHack\/} Xbehaves. X X%.hn 2 X\subsection*{Setting the options} X X%.pg XOptions may be set in a number of ways. Within the game, the `{\tt O}' Xcommand allows you to view all options and change most of them. XYou can also set options automatically by placing them in the X``NETHACKOPTIONS'' environment variable or a configuration file. XSome versions of {\it NetHack\/} also have front-end programs that allow Xyou to set options before starting the game. X X%.hn 2 X\subsection*{Using the NETHACKOPTIONS environment variable} X X%.pg XThe NETHACKOPTIONS variable is a comma-separated list of initial Xvalues for the various options. Some can only be turned on or off. XYou turn one of these on by adding the name of the option to the list, Xand turn it off by typing a `{\tt !}' or ``{\tt no}'' before the name. XOthers take a Xcharacter string as a value. You can set string options by typing Xthe option name, a colon, and then the value of the string. The value Xis terminated by the next comma or the end of string. X X%.pg XFor example, to set up an environment variable so that {\it female\/} Xis on, {\it pickup\/} is off, the {\it name\/} is set to ``Blue Meanie'', and Xthe {\it fruit\/} is set to ``papaya'', you would enter the command X%.sd X\begin{verbatim} X setenv NETHACKOPTIONS "female,!pickup,name:Blue Meanie,fruit:papaya" X\end{verbatim} X%.ed X X\nd in {\it csh}, or X%.sd X\begin{verbatim} X NETHACKOPTIONS="female,!pickup,name:Blue Meanie,fruit:papaya" X export NETHACKOPTIONS X\end{verbatim} X%.ed X X\nd in {\it sh\/} or {\it ksh}. X X%.hn 2 X\subsection*{Using a configuration file} X X%.pg XAny line in the configuration file starting with ``{\tt OPTIONS=}'' may be Xfilled out with options in the same syntax as in NETHACKOPTIONS. XAny line starting with ``{\tt GRAPHICS=}'', ``{\tt MONSTERS=}'', or X``{\tt OBJECTS=}'' Xis taken as defining the {\it graphics\/}, {\it monsters\/}, or X{\it objects\/} options in a different syntax, Xa sequence of decimal numbers giving the character position Xin the current font to be used in displaying each entry. XSuch a sequence can be continued to multiple lines by putting a X`{\tt \verb+\+}' at the end of each line to be continued. XAny line starting with `{\tt \#}' is treated as a comment. X X%.pg XThe default name of the configuration file varies on different Xoperating systems, but NETHACKOPTIONS can also be set to Xthe full name of a file you want to use (possibly preceded by an `{\tt @}'). X X%.hn 2 X\subsection*{Customization options} X X%.pg XHere are explanations of the various options do. Character strings Xlonger than fifty characters are truncated. Some of the options Xlisted may be inactive in your dungeon. X X\blist{} X%.lp X\item[\ib{BIOS}] XUse BIOS calls to update the screen display quickly and to read the keyboard X(allowing the use of arrow keys to move) on machines with an IBM PC Xcompatible BIOS ROM (default off, {\it OS/2, PC\/ {\rm and} ST NetHack\/} only). X%.lp X\item[\ib{catname}] XName your starting cat (ex.\ ``{\tt catname:Morris}''). XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{checkpoint}] XSave game state after each level change, for possible recovery after Xprogram crash (default on). X%.lp X\item[\ib{color}] XUse color for different monsters, objects, and dungeon features X(default on for microcomputers). X%.lp X\item[\ib{confirm}] XHave user confirm attacks on pets, shopkeepers, and other Xpeaceable creatures (default on). X%.lp X\item[\ib{DECgraphics}] XUse a predefined selection of characters from the DEC VT-xxx/DEC Rainbow/ XANSI line-drawing character set to display the dungeon instead of having Xto define a full graphics set yourself (default off). XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{disclose}] XOffer to identify your inventory and intrinsics when the Xgame ends (default on). X%.lp X\item[\ib{dogname}] XName your starting dog (ex.\ ``{\tt dogname:Fang}''). XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{female}] XSet your sex (default off). Cannot be set with the `{\tt O}' command. X%.lp X\item[\ib{fixinv}] XAn object's inventory letter sticks to it when it's dropped (default on). XIf this is off, dropping an object shifts all the remaining inventory letters. X%.lp X\item[\ib{fruit}] XName a fruit after something you enjoy eating (ex.\ ``{\tt fruit:mango}'') X(default ``{\tt slime mold}''). Basically a nostalgic whimsy that X{\it NetHack\/} uses from time to time. You should set this to something you Xfind more appetizing than slime mold. Apples, oranges, pears, bananas, and Xmelons already exist in {\it NetHack}, so don't use those. X%.lp X\item[\ib{graphics}] XSet the graphics symbols for screen displays (default X``\verb& |--------||.-|++.##<>& X\verb&<>\^"_\\#{}.}..## #}|-\\/*!)(0#@*/-\\||\\-//-\\| |\\-/&''). XIf specified, the {\it graphics\/} Xoption should come last, followed by a string of 1--69 Xcharacters to be used instead of the default map-drawing characters. XThe dungeon map will use the characters you specify instead of the Xdefault symbols. XRemember that you may need to escape some of these characters Xif, for example, you use {\it csh}. X XThe {\it DECgraphics\/} and {\it IBMgraphics\/} Xoptions use predefined selections of graphics symbols, so you need not Xgo to the trouble of setting up a full graphics string for these common Xcases. These two options also set up proper handling of graphics Xcharacters for such terminals, so you should specify them as appropriate Xeven if you override the selections with your own graphics string. X XNote that this option string is now escape-processed in conventional C Xfashion. This means that `\verb+\+' is a prefix to take the following Xcharacter literally, and not as a special prefix. Your graphics Xstrings for {\it NetHack\/} 2.2 and older versions may contain a `\verb+\+'; Xit must be doubled for the same effect now. The special escape form X`\verb+\m+' switches on the meta bit in the following character, and the X`{\tt \^{}}' prefix causes the following character to be treated as a control Xcharacter (so any `{\tt \^{}}' in your old graphics strings should be changed Xto `\verb+\^+' now). Also note that there are more symbols in a different Xorder than used for {\it NetHack\/} 3.0. X XThe order of the symbols is: solid rock, vertical wall, horizontal Xwall, upper left corner, upper right corner, lower left corner, lower Xright corner, cross wall, upward T wall, downward T wall, leftward T Xwall, rightward T wall, no door, vertical open door, horizontal open Xdoor, vertical closed door, horizontal closed door, floor of a room, Xdark corridor, lit corridor, stairs up, stairs down, ladder up, ladder Xdown, trap, web, altar, throne, kitchen sink, fountain, pool or moat, Xice, lava, vertical lowered drawbridge, horizontal lowered drawbridge, Xvertical raised drawbridge, horizontal raised drawbridge, air, cloud, Xunder water, vertical beam, horizontal beam, left slant, right slant, Xdigging beam, camera flash beam, left boomerang, right boomerang, four Xglyphs giving the sequence for magic resistance displays; the eight Xsurrounding glyphs for swallowed display; nine glyphs for explosions. XAn explosion consists of three rows (top, middle, and bottom) of three Xcharacters. The explosion is centered in the center of this $3 \times 3$ Xarray. X XYou might want to use `{\tt +}' for the corners and T walls for a more Xaesthetic, boxier display. Note that in the next release, new symbols Xmay be added, or the present ones rearranged. X XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{help}] XIf more information is available for an object looked at Xwith the `{\tt /}' command, ask if you want to see it (default on). XTurning help off makes just looking at things faster, since you aren't Xinterrupted with the ``{\tt More info?}'' prompt, but it also means that you Xmight miss some interesting and/or important information. X%.lp X\item[\ib{hilite\_pet}] XHighlight pets when color is turned off (default off). X%.lp X\item[\ib{IBMgraphics}] XUse a predefined selection of IBM extended ASCII characters to display the Xdungeon instead of having to define a full graphics set yourself (default off). XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{ignintr}] XIgnore interrupt signals, including breaks (default off). X%.lp X\item[\ib{legacy}] XDisplay an introductory message when starting the game (default on). X%.lp X\item[\ib{lit\_corridor}] XShow corridor squares seen by night vision or a light source held by your Xcharacter as lit (default off). X%.lp X\item[\ib{male}] XSet your sex (default on, most hackers are male). XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{monsters}] XSet the characters used to display monster classes (default X``\verb+abcdefghijklmnopqrstuv+ X\verb+wxyzABCDEFGHIJKLMNOPQRSTUVWXYZ@ \\&;:~]+''). XThis string is subjected to the same processing as the {\it graphics\/} option. XThe order of the symbols is Xant or other insect, blob, cockatrice, Xdog or other canine, eye or sphere, feline, Xgremlin, humanoid, imp or minor demon, Xjelly, kobold, leprechaun, Xmimic, nymph, orc, Xpiercer, quadruped, rodent, Xspider, trapper or lurker above, unicorn, Xvortex, worm, xan or other mythical/fantastic insect, Xlight, zruty, Xangelic being, bat, centaur, Xdragon, elemental, fungus or mold, Xgnome, giant humanoid, invisible stalker, Xjabberwock, Keystone Kop, lich, Xmummy, naga, ogre, Xpudding or ooze, quantum mechanic, rust monster, Xsnake, troll, umber hulk, Xvampire, wraith, xorn, Xyeti or ape or other large beast, zombie, Xhuman, ghost, golem, Xdemon, sea monster, lizard, Xlong worm tail, and mimic. XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{msghistory}] XThe number of top line messages to save (and recall with `{\tt \^{}P}') X(default 20). Cannot be set with the `{\tt O}' command. X%.lp X\item[\ib{name}] XSet your character's name (defaults to your user name). You can also Xset your character class by appending a dash and the first letter of Xthe character class (that is, by suffixing one of X``{\tt -A -B -C -E -H -K -P -R -S -T -V -W}''). XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{news}] XRead the {\it NetHack\/} news file, if present (default on). XSince the news is shown at the beginning of the game, there's no point Xin setting this with the `{\tt O}' command. X%.lp X\item[\ib{null}] XSend padding nulls to the terminal (default off). X%.lp X\item[\ib{number\_pad}] XUse the number keys to move instead of {\tt [yuhjklbn]} (default off). X%.lp X\item[\ib{objects}] XSet the characters used to display object classes (default X``\verb&])[="(%!?+/$*`0_.&''). XThis string is subjected to the same processing as the {\it graphics\/} option. XThe order of the symbols is Xillegal-object (should never be seen), weapon, armor, ring, amulet, tool, Xfood, potion, scroll, spell book, wand, gold, gem or rock, boulder or statue, Xiron ball, chain, and venom. XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{packorder}] XSpecify the order to list object types in (default X``\verb&\")[\%?+/=!(*`0_&''). The value of this option should be a string Xcontaining the symbols for the various object types. X%.lp X\item[\ib{pettype}] XSpecify the type of your initial pet, if you are playing a character class Xthat uses both types of pets. Possible values are ``{\tt cat}'' Xand ``{\tt dog}''. XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{pickup}] XPick up things you move onto by default (default on). X%.lp X\item[\ib{rawio}] XForce raw (non-ctrl-break) mode for faster output and more Xbulletproof input (MS-DOS sometimes treats `{\tt \^{}P}' as a printer toggle Xwithout it) (default off). Note: DEC Rainbows hang if this is turned on. XCannot be set with the `{\tt O}' command. X%.lp X\item[\ib{rest\_on\_space}] XMake the space bar a synonym for the `{\tt .}' (rest) command (default off). X%.lp X\item[\ib{safe\_pet}] XPrevent you from (knowingly) attacking your pets (default on). X%.lp X\item[\ib{scores}] XControl what parts of the score list you are shown at the end (ex.\ X``{\tt scores:5top scores/4around my score/own scores}''). Only the first Xletter of each category (`{\tt t}', `{\tt a}' or `{\tt o}') is necessary. X%.lp X\item[\ib{showexp}] XShow your accumulated experience points on bottom line (default off). X%.lp X\item[\ib{showscore}] XShow your approximate accumulated score on bottom line (default off). X%.lp X\item[\ib{silent}] XSuppress terminal beeps (default on). X%.lp X\item[\ib{sortpack}] XSort the pack contents by type when displaying inventory (default on). X%.lp X\item[\ib{standout}] XBoldface monsters and ``{\tt --More--}'' (default off). X%.lp X\item[\ib{time}] XShow the elapsed game time in turns on bottom line (default off). X%.lp X\item[\ib{tombstone}] XDraw a tombstone graphic upon your death (default on). X%.lp X\item[\ib{verbose}] XProvide more commentary during the game (default on). X%.lp X\item[\ib{windowtype}] XSelect which windowing system to use, such as ``{\tt tty}'' or ``{\tt X11}'' X(default depends on version). XCannot be set with the `{\tt O}' command. X\elist X X%.hn 1 X\section{Scoring} X X%.pg X{\it NetHack\/} maintains a list of the top scores or scorers on your machine, Xdepending on how it is set up. In the latter case, each account on Xthe machine can post only one non-winning score on this list. If Xyou score higher than someone else on this list, or better your Xprevious score, you will be inserted in the proper place under your Xcurrent name. How many scores are kept can also be set up when X{\it NetHack\/} is compiled. X X%.pg XYour score is chiefly based upon how much experience you gained, how Xmuch loot you accumulated, how deep you explored, and how the game Xended. If you quit the game, you escape with all of your gold intact. XIf, however, you get killed in the Mazes of Menace, the guild will Xonly hear about 90\,\% of your gold when your corpse is discovered X(adventurers have been known to collect finder's fees). So, consider Xwhether you want to take one last hit at that monster and possibly Xlive, or quit and stop with whatever you have. If you quit, you keep Xall your gold, but if you swing and live, you might find more. X X%.pg XIf you just want to see what the current top players/games list is, you Xcan type X\begin{verbatim} X nethack -s all X\end{verbatim} Xon most versions. X X%.hn 1 X\section{Explore mode} X X%.pg X{\it NetHack\/} is an intricate and difficult game. Novices might falter Xin fear, aware of their ignorance of the means to survive. Well, fear Xnot. Your dungeon may come equipped with an ``explore'' or ``discovery'' Xmode that enables you to keep old save files and cheat death, at the Xpaltry cost of not getting on the high score list. X X%.pg XThere are two ways of enabling explore mode. One is to start the game Xwith the {\tt -X} Xswitch. The other is to issue the `{\tt X}' command while already playing Xthe game. The other benefits of explore mode are left for the trepid Xreader to discover. X X%.hn X\section{Credits} X%.pg XThe original % X{\it hack\/} game was modeled on the Berkeley X%.ux XUNIX X{\it rogue\/} game. Large portions of this paper were shamelessly Xcribbed from % X{\it A Guide to the Dungeons of Doom}, by Michael C. Toy Xand Kenneth C. R. C. Arnold. Small portions were adapted from X{\it Further Exploration of the Dungeons of Doom}, by Ken Arromdee. X X%.pg X{\it NetHack\/} is the product of literally dozens of people's work. XMain events in the course of the game development are described below: X X%.pg X\bigskip X\nd {\it Jay Fenlason\/} wrote the original {\it Hack\/} with help from {\it XKenny Woodland}, {\it Mike Thome}, and {\it Jon Payne}. X X%.pg X\medskip X\nd {\it Andries Brouwer\/} did a major re-write, transforming {\it Hack\/} Xinto a very different game, and published (at least) three versions (1.0.1, X1.0.2, and 1.0.3) for UNIX machines to the Usenet. X X%.pg X\medskip X\nd {\it Don G. Kneller\/} ported {\it Hack\/} 1.0.3 to Microsoft C and MS-DOS, Xproducing {\it PC Hack\/} 1.01e, added support for DEC Rainbow graphics in Xversion 1.03g, and went on to produce at least four more versions (3.0, 3.2, X3.51, and 3.6). X X%.pg X\medskip X\nd {\it R. Black\/} ported {\it PC Hack\/} 3.51 to Lattice C and the Atari X520/1040ST, producing {\it ST Hack\/} 1.03. X X%.pg X\medskip X\nd {\it Mike Stephenson\/} merged these various versions back together, Xincorporating many of the added features, and produced {\it NetHack\/} version X1.4. He then coordinated a cast of thousands in enhancing and debugging X{\it NetHack\/} 1.4 and released {\it NetHack\/} versions 2.2 and 2.3. X X%.pg X\medskip X\nd Later, Mike coordinated a major rewrite of the game, heading a team which Xincluded {\it Ken Arromdee}, {\it Jean-Christophe Collet}, {\it Steve Creps}, X{\it Eric Hendrickson}, {\it Izchak Miller}, {\it Eric S. Raymond}, {\it John XRupley}, {\it Mike Threepoint}, and {\it Janet Walz}, to produce {\it XNetHack\/} 3.0c. X X%.pg X\medskip X\nd {\it NetHack\/} 3.0 was ported to the Atari by {\it Eric R. Smith}, to OS/2 by X{\it Timo Hakulinen}, and to VMS by {\it David Gentzel}. The three of them Xand {\it Kevin Darcy\/} later joined the main development team to produce Xsubsequent revisions of 3.0. X X%.pg X\medskip X\nd {\it Olaf Seibert\/} ported {\it NetHack\/} 2.3 and 3.0 to the Amiga. {\it XNorm Meluch}, {\it Stephen Spackman\/} and {\it Pierre Martineau\/} designed Xoverlay code for {\it PC NetHack\/} 3.0. {\it Johnny Lee\/} ported {\it XNetHack\/} 3.0 to the Macintosh. Along with various other Dungeoneers, they Xcontinued to enhance the PC, Macintosh, and Amiga ports through the later Xrevisions of 3.0. X X%.pg X\medskip X\nd Headed by {\it Mike Stephenson\/} and coordinated by {\it Izchak Miller\/} and X{\it Janet Walz}, the development team which now included {\it Ken Arromdee}, X{\it David Cohrs}, {\it Jean-Christophe Collet}, {\it Kevin Darcy}, X{\it Matt Day}, {\it Timo Hakulinen}, {\it Steve Linhart}, {\it Dean Luick}, X{\it Pat Rankin}, {\it Eric Raymond}, and {\it Eric Smith\/} undertook a radical Xrevision of 3.0. They re-structured the game's design, and re-wrote major Xparts of the code. They added multiple dungeons, a new display, special Xindividual character quests, a new endgame and many other new features, and Xproduced {\it NetHack\/} 3.1. X X%.pg X\medskip X\nd {\it Ken Lorber}, {\it Gregg Wonderly\/} and {\it Greg Olson}, with help Xfrom {\it Richard Addison}, {\it Mike Passaretti}, and {\it Olaf Seibert}, Xdeveloped {\it NetHack\/} 3.1 for the Amiga. X X%.pg X\medskip X\nd {\it Norm Meluch\/} and {\it Kevin Smolkowski}, with help from X{\it Carl Schelin}, {\it Stephen Spackman}, {\it Steve VanDevender}, Xand {\it Paul Winner}, ported {\it NetHack\/} 3.1 to the PC. X X%.pg X\medskip X\nd {\it Jon W\"atte}, with help from {\it Ross Brown}, {\it Mike Engber}, X{\it David Hairston}, {\it Michael Hamel}, {\it Jonathan Handler}, X{\it Johnny Lee}, {\it Tim Lennan}, {\it Rob Menke}, {\it Andy Swanson}, and Xespecially from {\it Hao-yang Wang}, developed {\it NetHack\/} 3.1 for the Macintosh. X X%.pg X\medskip X\nd {\it Timo Hakulinen\/} ported {\it NetHack\/} 3.1 to OS/2. {\it Eric Smith\/} Xported {\it NetHack\/} 3.1 to the Atari. {\it Pat Rankin}, with help from X{\it Joshua Delahunty}, is responsible for the VMS version of {\it NetHack\/} 3.1. X X%.pg X\medskip X\nd {\it Dean Luick}, with help from {\it David Cohrs}, developed {\it NetHack\/} X3.1 for X11. X X%.pg X\bigskip X\nd From time to time, some depraved individual out there in netland sends a Xparticularly intriguing modification to help out with the game. The Gods of Xthe Dungeon sometimes make note of the names of the worst of these miscreants Xin this, the list of Dungeoneers: X X%.sd X\begin{center} X\begin{tabular}{lll} XRichard Addison & Eric Hendrickson & Mike Passaretti \\ XTom Almy & Bruce Holloway & Pat Rankin \\ XKen Arromdee & Richard P. Hughey & Eric S. Raymond \\ XEric Backus & Ari Huttunen & Frederick Roeber \\ XJohn S. Bien & John Kallen & John Rupley \\ XRalf Brown & Del Lamb & Carl Schelin \\ XRoss Brown & Greg Laskin & Olaf Seibert \\ XDavid Cohrs & Johnny Lee & Kevin Sitze \\ XJean-Christophe Collet & Tim Lennan & Eric R. Smith \\ XSteve Creps & Merlyn LeRoy & Kevin Smolkowski \\ XKevin Darcy & Steve Linhart & Michael Sokolov \\ XMatthew Day & Ken Lorber & Stephen Spackman \\ XJoshua Delahunty & Dean Luick & Andy Swanson \\ XBill Dyer & Benson I. Margulies & Kevin Sweet \\ XMike Engber & Pierre Martineau & Scott R. Turner \\ XJochen Erwied & Roland McGrath & Steve VanDevender \\ XMike Gallop & Norm Meluch & Janet Walz \\ XDavid Gentzel & Rob Menke & Hao-yang Wang \\ XMark Gooderum & Deron Meranda & Jon W\"atte \\ XDavid Hairston & Bruce Mewborne & Tom West \\ XTimo Hakulinen & Izchak Miller & Paul Winner \\ XMichael Hamel & Gil Neiger & Gregg Wonderly \\ XJonathan Handler & Greg Olson & X\end{tabular} X\end{center} X%.ed X X%\vfill X%\begin{flushleft} X%\small X%Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.\\ X%%%Don't need next line if a UNIX macro automatically inserts footnotes. X%UNIX is a registered trademark of AT\&T.\\ X%Lattice is a trademark of Lattice, Inc.\\ X%Atari and 1040ST are trademarks of Atari, Inc.\\ X%AMIGA is a trademark of Commodore-Amiga, Inc.\\ X%%.sm X%Brand and product names are trademarks or registered trademarks X%of their respective holders. X%\end{flushleft} X X\end{document} END_OF_FILE if test 34659 -ne `wc -c <'doc/Guidebook.te2'`; then echo shar: \"'doc/Guidebook.te2'\" unpacked with wrong size! fi # end of 'doc/Guidebook.te2' fi if test -f 'doc/window.doc' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/window.doc'\" else echo shar: Extracting \"'doc/window.doc'\" $20576 characters$ sed "s/^X//" >'doc/window.doc' <<'END_OF_FILE' XIntroduction X XThis file documents the support for various windowing systems in XNetHack. The support is through a standard interface, separating the Xmain NetHack code from window-system specific code. The implementation Xsupports multiple window systems in the same binary. Even if you only Xwish to support one window-port on your port, you will need to follow Xthe instructions in Section VII to get a compilable binary. X XContents: X I. Window Types and Terminology X II. Interface Specification X III. Global variables X IV. New or respecified common, high level routines X V. Game startup X VI. Conventions X VII. Implementation and Multi-window support X XI. Window Types and Terminology X XThere are 5 basic window types, used to call create_nhwindow(): X X NHW_MESSAGE (top line) X NHW_STATUS (bottom lines) X NHW_MAP (main dungeon) X NHW_MENU (inventory or other "corner" windows) X NHW_TEXT (help/text, full screen paged window) X XThe tty window-port also uses NHW_BASE (the base display) internally. X XNHW_MENU windows can be used for either menu or text display. Their Xbasic feature is that for the tty-port, if the window is small enough, Xit appears in the corner of the tty display instead of overwriting Xthe whole screen. The first call to add information to the window Xwill decide if it is going to be used to display a menu or text. XIf start_menu() is called, then it will be used as a menu. If Xputstr() is called, it will be used as text. Once decided, there Xis no turning back. For the tty-port, if the data is too large for Xa single screen then the data is paged (with --more--) between pages. XOnly NHW_MENU type windows can be used for menus. X XNHW_TEXT windows are used to display a large amount of textual data. XThis is the type of window one would use for displaying a help file, Xfor example. In the tty window-port, windows of type NHW_TEXT can Xpage using the DEF_PAGER, if DEF_PAGER is defined. There exists an Xassumption that the font for text windows is monospaced. The help Xfiles are all formatted accordingly. X X"window" is always of type winid. This is currently implemented as an Xinteger, but doesn't necessarily have to be done that way. There are Xa few fixed window names that are known throughout the code: X X WIN_MESSAGE (top line) X WIN_STATUS (bottom lines) X WIN_MAP (main dungeon) X WIN_INVEN (inventory) X XOther windows are created and destroyed as needed. X X"Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS XTOS, etc.) "window-port" refers to the windowing platform. This is Xorthogonal (e.g. UNIX might use either a tty window-port or an X11 Xwindow-port). X X XII. Interface Specification X XAll functions below are void unless otherwise noted. X XA. Low-level routines: X Xraw_print(str) -- Print directly to a screen, or otherwise guarantee that X the user sees str. raw_print() appends a newline to str. X It need not recognize ASCII control characters. This is X used during startup (before windowing system initialization X -- maybe this means only error startup messages are raw), X for error messages, and maybe other "msg" uses. E.g. X updating status for micros (i.e, "saving"). Xraw_print_bold(str) X -- Like raw_print(), but prints in bold/standout (if possible). Xcurs(window, x, y) X -- Next output to window will start at (x,y), also moves X displayable cursor to (x,y). For backward compatibility, X 1 <= x < cols, 0 <= y < rows, where cols and rows are X the size of window. X -- For variable sized windows, like the status window, the X behaviour when curs() is called outside the window's limits X is unspecified. The mac port wraps to 0, with the status X window being 2 lines high and 80 columns wide. X -- Still used by curs_on_u(), status updates, screen locating X (identify, teleport). X -- NHW_MESSAGE, NHW_MENU and NHW_TEXT windows do not X currently support curs in the tty window-port. Xputstr(window, attr, str) X -- Print str on the window the given attribute. Only X printable ASCII characters (040-0126) must be supported. X Multiple putstr()s are output on separate lines. Attributes X can be one of X ATR_NONE (or 0) X ATR_ULINE X ATR_BOLD X ATR_BLINK X ATR_INVERSE X If a window-port does not support all of these, it may map X unsupported attributes to a supported one (e.g. map them X all to ATR_INVERSE). putstr() may compress spaces out of X str, break str, or truncate str, if necessary for the X display. Where putstr() breaks a line, it has to clear X to end-of-line. X -- putstr should be implemented such that if two putstr()s X are done consecutively that the user will see the first X and the second. In the tty port, pline() achieves this X by calling more() or displaying both on the same line. Xget_nh_event() -- Does window event processing (e.g. exposure events). X A noop for the tty and X window-ports. Xint nhgetch() -- Returns a single character input from the user. X -- In the tty window-port, nhgetch() assumes that tgetch() X will be the routine the OS provides to read a character. X Returned character _must_ be non-zero. Xint nh_poskey(int *x, int *y, int *mod) X -- Returns a single character input from the user or a X a positioning event (perhaps from a mouse). If the X return value is non-zero, a character was typed, else, X a position in the MAP window is returned in x, y and mod. X mod may be one of X X CLICK_1 /* mouse click type 1 */ X CLICK_2 /* mouse click type 2 */ X X The different click types can map to whatever the X hardware supports. If no mouse is supported, this X routine always returns a non-zero character. X XB. High-level routines: X Xprint_glyph(window, x, y, glyph) X -- Print the glyph at (x,y) on the given window. Glyphs are X integers at the interface, mapped to whatever the window- X port wants (symbol, font, color, attributes, ...there's X a 1-1 map between glyphs and distinct things on the map). Xchar yn_function(const char *ques, const char *choices, char default) X -- Print a prompt made up of ques, choices and default. X Read a single character response that is contained in X choices or default. If choices is NULL, all possible X inputs are accepted and returned. This overrides X everything else. The choices are expected to be in X lower case. Entering ESC always maps to 'q', or 'n', X in that order, if present in choices, otherwise it maps X to default. Entering any other quit character (SPACE, X RETURN, NEWLINE) maps to default. X -- If the choices string contains a '#' then accept a count. X Place this value in the global "yn_number" and return '#'. X -- This uses the top line in the tty window-port, other X ports might use a popup. Xgetlin(const char *ques, char *input) X -- Prints ques as a prompt and reads a single line of text, X up to a newline. The string entered is returned without the X newline. ESC is used to cancel, in which case the string X "\033\000" is returned. X -- getlin() must call flush_screen(1) before doing anything. X -- This uses the top line in the tty window-port, other X ports might use a popup. Xget_ext_cmd(char *input) X -- This routine is only included if COM_COMPL is defined. X Get the extended command in a special way (command X completion on the tty window-port). X ** I think it is pretty lame that this has an #ifdef X ** on it. The #ifdef COM_COMPL should either be yanked X ** inside this function or done away with. -dean Xplayer_selection() X -- Do a window-port specific player type selection. If X player_selection() offers a Quit option, it is its X responsibility to clean up and terminate the process. Xdisplay_file(str, boolean complain) X -- Display the file named str. Complain about missing files X iff complain is TRUE. Xupdate_inventory() X -- Indicate to the window port that the inventory has been X changed. X -- Merely calls display_inventory() for window-ports that X leave the window up, otherwise empty. Xdoprev_message() X -- Display previous messages. Used by the ^P command. X -- On the tty-port this scrolls WIN_MESSAGE back one line. X XC. Window Utility Routines X Xinit_nhwindows() X -- Initialize the windows used by NetHack. This can also X create the standard windows listed at the top, but does X not display them. X -- When the message window is created, the variable X flags.window_inited needs to be set to TRUE. Othewise X all plines() will be done via raw_print(). X ** Why not have init_nhwindows() create all of the "standard" X ** windows? Or at least all but WIN_INFO? -dean Xexit_nhwindows() X -- Exits the window system. This should dismiss all windows, X except the "window" used for raw_print(). Xwindow = create_nhwindow(type) X -- Create a window of type "type." Xclear_nhwindow(window) X -- Clear the given window, when apropriate. Xdisplay_nhwindow(window, boolean blocking) X -- Display the window on the screen. If there is data X pending for output in that window, it should be sent. X If blocking is TRUE, display_nhwindow() will not X return until the data has been displayed on the screen, X and acknowledged by the user where appropriate. X -- All calls are blocking in the tty window-port. X -- Calling display_nhwindow(WIN_MESSAGE,???) will do a X --more--, if necessary, in the tty window-port. Xdestroy_nhwindow(window) X -- Destroy will dismiss the window if the window has not X already been dismissed. Xstart_menu(window) X -- Start using window as a menu. You must call start_menu() X before add_menu(). After calling start_menu() you may not X putstr() to window. Only windows of type NHW_MENU may be X used for menus. Xadd_menu(window, ch, attr, str) X -- Add a text line to the given menu window. If ch is 0, X then the line cannot be selected (e.g. a title). Otherwise, X ch is the response needed to select the line. The value X attr is the same as in putstr(). Xend_menu(window, ch, str, morestr) X -- Stop adding entries to the menu and flushes the window X to the screen (brings to front?). Str gives other valid X (likely canceling) inputs (beyond any standard ones) and X ch is the response to any of them. Morestr is a prompt X to give the user. If morestr is NULL, no prompt will be X printed unless the window-port requires one (e.g. --more-- X in the tty window-port). Xchar select_menu(window) X -- Returns a valid response from the given menu (user typing, X mouse selection, whatever). You may select_menu() from a X window multiple times -- the menu is saved until X start_menu() or destroy_nhwindow() is called on the window. X -- Note that NHW_MENU windows need not have select_menu X called for them. There is no way of knowing whether X select_menu() will be called for the window at X create_nhwindow() time. X XD. Misc. Routines X Xmake_sound(???) -- To be determinded later. THIS IS CURRENTLY UN-IMPLEMENTED. Xnhbell() -- Beep at user. [This will exist at least until sounds are X redone, since sounds aren't attributable to windows anyway.] Xmark_synch() -- Don't go beyond this point in I/O on any channel until X all channels are caught up to here. Can be an empty call X for the moment Xwait_synch() -- Wait until all pending output is complete (*flush*() for X streams goes here). X -- May also deal with exposure events etc. so that the X display is OK when return from wait_synch(). Xdelay_output() -- Causes a visible delay of 50ms in the output. X Conceptually, this is similar to wait_synch() followed X by a nap(50ms), but allows asynchronous operation. Xaskname() -- Ask the user for a player name. Xcliparound(x, y)-- Make sure that the user is more-or-less centered on the X screen if the playing area is larger than the screen. X -- This funciton is only defined if CLIPPING is defined. Xnumber_pad(state) X -- Initialize the number pad to the given state. Xsuspend_nhwindows(str) X -- Prepare the window to be suspended. Xresume_nhwindows() X -- Restore the windows after being suspended. X Xstart_screen() -- Only used on Unix tty ports, but must be declared for X completeness. Sets up the tty to work in full-screen X graphics mode. Look at win/tty/termcap.c for an X example. If your window-port does not need this function X just declare an empty function. Xend_screen() -- Only used on Unix tty ports, but must be declared for X completeness. The complement of start_screen(). X X XIII. Global variables X XThe following global variables are defined in decl.c and must be used by Xthe window interface to the rest of NetHack. X Xchar toplines[BUFSZ] Contains the last message printed to the WIN_MESSAGE X window, used by Norep(). Xwinid WIN_MESSAGE, WIN_MAP, WIN_STATUS, WIN_INVEN X The four standard windows. Xchar *AE, *AS; Checked in options.c to see if we should switch X to DEC_GRAPHICS. It is #ifdefed VMS and UNIX. Xint LI, CO; Set in sys/unix/ioctl.c. X XThe following appears to be Unix specific. Other ports using the tty Xwindow-port should also declare this variable in one of your sys/*.c files. X Xshort ospeed; Set and declared in sys/unix/unixtty.c (don't X know about other sys files). X XIV. New or respecified common, high level routines X XThese are not part of the interface, but mentioned here for your information. X Xchar display_inventory(lets,show_cost) X -- Calls a start_menu()/add_menu()/select_menu() sequence. X It returns the item selected, or '\0' if none is selected. X Returns '\033' if the menu was canceled. Xraw_printf(str, ...) X -- Like raw_print(), but accepts arguments like printf(). This X routine processes the arguments and then calls raw_print(). X -- The mac version #defines error raw_printf. I think this X is a reasonable thing to do for most ports. Xpline(str, ...) X -- Prints a string to WIN_MESSAGE using a printf() interface. X It has the variants kludge(), You(), Your(), and Norep() X which all use the same mechanism. pline() requires the X variable "char toplines[]" be defined; Every putstr() on X WIN_MESSAGE must copy str to toplines[] for use by Norep() X and pline(). If the window system is not active X (!flags.window_inited) pline() uses raw_print(). X X XV. Game startup X XThe following is the general order in which calls from main() should be made, Xas they relate to the window system. The actual code may differ, but the Xorder of the calls should be the same. X X Xchoose_windows(DEFAULT_WINDOW_SYS) /* choose a default window system */ Xinitoptions() /* read the resource file */ Xinit_nhwindows() /* initialize the window system */ Xprocess_options(argc, argv) /* process command line options or equiv */ Xif(save file is present) { X display_gamewindows() /* create & display the game windows */ X dorestore() /* restore old game; pline()s are OK */ X} else { X player_selection() /* select a player type using a window */ X display_gamewindows() /* create & display the game windows */ X} Xpline("Hello, welcome..."); X XChoose_windows() is a common routine, and calling it in main() is necessary Xto initialize the function pointer table to _something_ so that calls to Xraw_print() will not fail. Choose_windows() should be called almost Ximmediately upon entering main(). Look at unixmain.c for an example. X XDisplay_gamewindows() is a common routine that displays the three standard Xgame windows (WIN_MESSAGE, WIN_MAP, and WIN_STATUS). It is normally called Xjust before the "Hello, welcome" message. X XProcess_options() is currently still unique to each port. There may be need Xin the future to make it possible to replace this on a per window-port basis. X X XVI. Conventions X Xinit_nhwindows() is expected to display a gee-whiz banner window, including Xthe Copyright message. X XPorts (MSDOS, TOS, MAC, etc) _may_ use window-port specific routines in Xtheir port specific files, _AT_THEIR_OWN_RISK_. Since "port" and X"window-port" are orthogonal, you make your "port" code less portable by Xusing "window-port" specific routines. Every effort should be made to Xuse window-port interface routines, unless there is something port Xspecific that is better suited (e.g. msmsg() for MSDOS). X XThe tty window-port is contained in win/tty, the X window port is contained Xin win/X11. The files in these directories contain _only_ window port code, Xand may be replaced completely by other window ports. X X XVII. Implementation and Multi-window support X XNetHack 3.1 supports multiple window systems in the same binary. When Xwriting a new window-port, you need to follow the following guidelines: X X1) Pick a unique prefix to identify your window-port. For example, the tty X window port uses "tty"; the X11 window-port uses "X11". X2) When declaring your interface function, preceed the function names with X your unique prefix. E.g: X X void tty_init_nhwindows() X { X /* code for initializing windows in the tty port */ X } X X When calling window functions from within your port code, we suggest X calling the prefixed version to avoid unnecessary overhead. However, X you may safely call the non-prefixed version (e.g. putstr() rather than X tty_putstr()) as long as you #include "hack.h". If you do not X include hack.h and use the non-prefixed names, you will get compile X or link-time errors. X X We also suggest declaring all functions and port-specific data with X this prefix to avoid unexpected overlaps with other window-ports. X The tty and X11 ports do not currently follow this suggestion, but do X use separate non-overlapping convention for naming data and internal X functions. X X3) Declare a structure, "struct win_choices prefix_procs", (with your X prefix instead of "prefix") and fill in names of all of your X interface functions. The first entry in this structure in the name X of your window-port, which should be the prefix. The other entries X are the function addresses. X X Assuming that you followed the convention in (2), you can safely copy X the structure definition from an existing window-port and just change X the prefixes. That will guarantee that you get the order of your X initializations correct (not all compilers will catch out-of-order X function pointer declarations). X X3) Add a #define to config.h identifying your window-port in the X "Windowing systems" section. Follow the "prefix_GRAPHICS" convention X for your window-port. X X4) Add your prefix to the list of valid prefixes listed in the "Known X systems are" comment. X X5) Edit makedefs.c and add a string for your windowing system to window_opts X inside an #ifdef prefix_GRAPHICS. X X6) Edit windows.c and add an external reference to your prefix_procs inside X an #ifdef prefix_GRAPHICS. Also add an entry to the winchoices X structure for your window-port of the form: X X #ifdef prefix_GRAPHICS X { &prefix_procs, prefix_init_function }, X #endif X X The init_function is necessary for some compilers and systems to force X correct linking. If your system does not need such massaging, you X may put a null pointer here. X X You should declare prefix_procs and prefix_init_function as extern's X in your win*.h file, and #include that file at the beginning of X windows.c, also inside an #ifdef prefix_GRAPHICS. Some win*.h files X are rather sensitive, and you might have to duplicate your X prefix_procs and prefix_init_function's instead of including win*.h. X The tty port includes wintty.h, the X11 port duplicates the declarations. X X7) If your port uses Makefile.src, add the .c and .o files and an X appropriate comment in the section on "WINSRC" and "WINOBJ". See X Makefile.src for the style to use. If you don't use Makefile.src, X we suggest using a similar convention for the make-equivalent used X on your system. Also add your new source and binaries to WINSRC and X WINOBJ (if you want the NetHack binary to include them, that is). X X8) Look at your port's portmain.c (the file containing main()) and make X sure that all of the calls match the the requirements laid out in X Section V. X XNow, proceed with compilation and installation as usual. Don't forget Xto edit Makefile.src (or its equivalent) and config.h to set the Xwindow-ports you want in your binary, the default window-port to use, Xand the .o's needed to build a valid game. X XOne caveat. Unfortunately, if you incorrectly specify the XDEFAULT_WINDOW_SYS, NetHack will dump core (or whatever) without Xprinting any message, because raw_print() cannot function without first Xsetting the window-port. END_OF_FILE if test 20576 -ne `wc -c <'doc/window.doc'`; then echo shar: \"'doc/window.doc'\" unpacked with wrong size! fi # end of 'doc/window.doc' fi echo shar: End of archive 53 $of 108$. cp /dev/null ark53isdone MISSING="" for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 \ 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 \ 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 \ 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 \ 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 \ 101 102 103 104 105 106 107 108 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 108 archives. echo "Now execute 'rebuild.sh'" rm -f ark10[0-8]isdone ark[1-9]isdone ark[1-9][0-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0