Source diving

Source diving is the action of examining the source code of NetHack. A person who practices source diving is called a source diver. The source code is freely available for anyone, unlike in most commercial programs.

Source diving is usually done when someone wants to know how something really works in the game. Source divers may also program their own patches to the game. Some people may just want to look for easter eggs or interesting comments in the source.

Grep, awk, and Doxygen are useful tools when source diving.

Tips

Function definitions

Most function declarations are in extern.h, sorted by the .c file they're defined in. If you're looking for a function's definition, you can search for the function name in extern.h, then scroll up to the comment giving the file name. Note that some things that look like functions, such as resists_fire(mon), are actually preprocessor macros; most of those are defined in other header files such as youprop.h or mondata.h.

Message sources

You can look up printed messages in the code to get an idea of what governs certain output. However, many messages are constructed using macros and/or string substitution. For example, when trying to mount your steed, you may get the message:

You are unable to swing your leg over.

You won't find this exact message anywhere in the source code, because the line that produces it reads: You("are unable to swing your %s over.", body_part(LEG)). The macro You() prints a message beginning with the word "You"; there are similar macros for messages starting with "Your", "You hear", and "You feel". The "%s" in the message is replaced with the result of the next argument, body_part(LEG), which resolves to a string describing the leg-analogue of your current polyself, if any. In this case, one way to search for the message would be "unable to swing your %s over". In general, if any word or words in a message can vary, replace them with %s in a search; if a number varies, replace it with %ld. (Alternatively, trim to "unable to swing your", if your search mechanism may not cooperate with %s or %ld as part of a search.)

See also

• Beginner's guide to NetHack sources -- note that the .des level file format described here has been replaced with LUA in 3.7 development versions.