HOW TO READ THE NETHACK SOURCE CODE   

                                           Version 0.1
                                           April 12, 2001
                                           Rob Ellwood
                                           rob.ellwood@home.com


0.0   INTRODUCTION

	Kiyoshi Aman asked the RGRN newsgroup how he could find 
the section of code defining the maximum HP allowed.  This 
document is a rewrite of my reply.  (I may eventually rewrite
and greatly expand this, but don't hold your breath.)

	I will assume that you have some programming skills.  If 
you don't know C, understanding the code will be an uphill 
battle.  (I only have limited knowledge of C, and I often find
the code an uphill battle.)

   0.1   Acknowledgments:

	I took some information on variable names from postings
by Ross Presser and Dylan O'Donnell.


1.0	RESOURCES

   o  The source code itself, available for download at:
http://www.nethack.org/

   o  People on the NGRN newsgroup are helpful if you have a 
specific question.

   o  German Martin's "Nethack Sources How-To" explains how
to make changes to the source.  In passing, he does a few 
things like list and briefly describe some of the important 
subroutines.

	The file name is sources.txt.  As of 2001, SLASH'EM's source 
files include a copy, but not NetHack's.  Try these sites:
http://www.lab3.kuis.kyoto-u.ac.jp/members/aoki/nethack/files/Tips/sources.gui
http://avrc.city.ac.uk/nethack/slashem/slashem-0.0.5E7F1/sources.txt 
	...or do a web search, or ask on the newsgroup.

   o  Jason Short's online NetHack Cross Reference tool:
http://nethack.dhs.org/

   o  If you want to modify and compile NetHack, there
is a free DOS / Windows compiler at:
http://www.delorie.com/djgpp/



2.0   FINDING THE RIGHT SECTION

	Either download the code or use an online code browser like
at Jason Short's site.


   2.1   Standard Abbreviations In The Code

m   = monster
u   = you; the player

	So the file "mhitu.c" has the code for monsters hitting you.
See appendix 1 for some other abbreviations.

	Variables in upper case are defined in header files.  
All objects 

	How do you spot that something invokes a preprocessor 
macro?  Upper case again?



   2.2   Finding The Message

	Kiyoshi Aman wanted to find the section of code defining 
the maximum HP allowed.  To track this sort of thing down, try to
remember a NetHack message which is related to what you're
interested in.  For example, you gain HPs when you go up
levels.  The message is "You feel more experienced".  You
also gain HPs when nurses pummel your naked bod.  Part of
the message is "I hope you don't mind".

        Clip off the initial "you" and "you feel" parts of any 
messages; the code uses a trick to generate these.  Use a 
search command to find all the .c files that contain the 
remaining text.  Open the files one by one.

        Here, "more experienced" appeared in muse.c and exper.c.  
muse.c = "monster use" and the message must be "the orc appears 
more experienced".  That's not of interest here, so exper.c is 
the file to look at.

        When I edit exper.c and search for that message, I
find a routine pluslvl, which calls a routine newhp to figure 
out the new hit points.  We're getting close.  Unfortunately, 
the newhp routine is not in exper.c.


   2.3   Tracing Back

        I didn't search for .c files with newhp.  Some important 
routines are called from dozens of different places.  (Well, not 
newhp, but you get the idea.)  Instead, I went to Jason Short's 
site and searched for the identifier newhp.  It told me that the 
function was declared in attrib.c, and took me directly to the 
relevant spot.

        newhp always adds at least one to your current hit 
points.  Therefore, there is no explicit upper limit to your
HPs.  



APPENDIX 1:  STANDARD ABBREVIATIONS


dog = a pet of any type
gd  = guard
m   = monstr
pri = priest
shk = shopkeeper
u   = you; the player
wiz = the Wizard of Yendor


	Qualifiers:

tmp (mtmp, otmp):  the monster or object the subroutine is 
                   being applied to.

is:  "isfoo" is true if the monster in question is a foo.
   isshk         A shopkeeper 
   iswiz         The Wizard of Yendor
   isminion()    A deity's minion ("Odin's angel, Moloch's succubus")
   is_lminion()  A lawful ditto.  Now all A & lawful high priests
   is_rider()    One of the three Riders




	(Notes to myself:  copy over German Martin's list of 
subroutines.  Carefully document all of the random number 
routines.  Does anyone know of an online tutorial on C?  Or
an online textbook-class reference?  Find and copy over that
"select a random YAFM" bit of code.  Explain header files.
Explain common preprocessor macros.)