What's this all about? ---------------------- "dump-343" is a patch for Nethack version 3.4.3. It enables you to automaticaly dump certain data on the (most likely) premature death of your character to a file. But dumping, of course, also works after an ascension. In other words, each time a game really ends (character either dead, quit, or ascended), you can get the dump. The following data will be dumped: - character name, alignment, gender, race, role and stats - 20 latest game messages (you can change the number with the #define DUMPMSGS setting in include/config.h) - the final screen picture - inventory - the contents of containers you are carrying - attributes (what you get from, say, quaffing a potion of enlightenment) - known spells - vanquished monsters - genocided monsters - voluntary challenges - skills - the information on the "Goodbye" screen you see after all this and before the score list. This also includes the "killer" string that is shown on the logfile and highscore list as the reason for game ending. The dumping takes place at the time when you get (or could get) this data presented on the screen. All data should be dumped whether or not you choose to view it on the screen. Why this patch? Well, after having gloriously ascended a character, I sometimes wished to keep notes on how this guy has performed. The only way (known to me) to achieve this was to either make a screenshot, or to write it down by hand. Certainly not really appropriate... How do I install the patch, and how do I enable this feature? ------------------------------------------------------------- Installing is easy. Enter a fresh Nethack source directory (from where you can see the src, the include, and all the other sub-directories), and type patch -p1 < name-of-the-patch-file Then edit your include/config.h and add the line #define DUMP_LOG somewhere. I recommend putting it in "Section 5" near the end of the file, that part is meant for experimental stuff and is a good place for settings added for patches. Also add #define DUMPMSGS 20 to define the number of latest messages to be included in the file. If you want to enable the dump patch, but disable the dump filename definition by users (for example because of security reasons in multiuser systems, where it is highly recommended), you can do this by defining a fixed name with the DUMP_FN macro in config.h. For example, #define DUMP_FN "/tmp/dump.nh" Configure, compile, install, voila. Unless you defined the file name with DUMP_FN, the feature is DISabled by default. To enable it, you have to set the option "dumpfile" in your configuration file (most probably $HOME/.nethackrc under Unix, nethack.cnf under OS/2 and defaults.nh in win32 and probably dos; I don't know about other OSes) or in the environment variable NETHACKOPTIONS or using the 'O' command from within the game. The argument for the option is the file the dump is to be written to. Example: OPTIONS=dumpfile:/tmp/dump.nh enables the dumping feature, and all dumps are written to /tmp/nh.dump. Note that _you_ have to make sure that the game actually _can_ write to this file (usually, under Unix systems, it runs under UID=games and GID=bin and can't write to your home directory. You probably want to also include your username or something else in the filename on multiuser platforms to distinguish it from other users' dump files). You can use the "%n" macro in the filename and that will be expanded to the name of your player character when the file is created. For example, if you are playing as "foo" and have configured OPTIONS=dumpfile:/tmp/%n.dump the dump file will be /tmp/foo.dump. This is recommended especially on multiuser systems if you define the file name with DUMP_FN (see above), because otherwise the dumps of all the players would end up being written with the same filename, and a later player would either overwrite the file of the previous player, or wouldn't be able to get the dump file written at all, depending on the file permissions. Otherwise, no "wierd" stuff should be in the file name, no "~", no "$HOME", no blanks. The game might not check for all of this, you are supposed to know what you can use as a filename. All data present before a dump is _overwritten_, once opening a dump file is successful. Make sure you copy it to somewhere else if you want to keep it. Important: check for dependecies with other settings, e.g., disclose. If you tell Nethack to never disclose any information (or only partially) on death, quitting, or ascension by default, then there won't be no dumping of some the non-disclosed information as well! But you will always get the name/alignment/gender/race/role, stats, spells, skills and Goodbye screen dumped regardless of this. Implementation issues --------------------- This version of the patch has #ifdef's around all dump file handling, so if you want to remove the functionality of the patch later, all you really need to do is comment out the #define DUMP_LOG in your include/config.h and recompile. The starting point is function done() in end.c. There, the dump file is opened when you die, before showing any of the information, and closed after showing all of it (_if_ you want to dump, that is). Some relevant functions called from within disclose() have a new (boolean) parameter, "want_dump". If want_dump is set to TRUE, then dumping is performed. If one of these functions is called from somewhere else, say, after quaffing a potion of enlightenment, then no dump is performed (want_dump then is set to FALSE). But I added wrapper functions around them, so that calls from anywhere else in the game don't need to be changed. The relevant functions are - display_inventory() in invent.c - container_contents() in end.c - enlightenment() in cmd.c - list_vanquished() in end.c - list_genocided() in end.c - show_conduct() in cmd.c The display_artifact_score in end.c also dumps information to the file, but since it is only called when the game ends (in ascension or when you escape the dungeon) and never before that, the want_dump parameter is not used there. Basically, whenever some information is printed to the screen, then there's an additional call to dump() (defined in end.c) that also writes to the dump file (if want_dump is TRUE). The other files affected by the patch are botl.c, cmd.c, decl.c, display.c, invent.c, options.c, pline.c, spell.c, topten.c, weapon.c, win/tty/wintty.c, include/decl.h, and include/extern.h. All the rest ------------ If you find any bugs in this patch, please report them to walker@netsonic.fi or to the newsgroup rec.games.roguelike.nethack. Disclaimer: I cannot be made responsible for any damage this patch, application of it, or running a patched binary may cause (not that I think that there is much danger). Since I assume that the patch is "derived from the Nethack source code", I think that it falls under the same licence restrictions as Nethack itself. So, feel free to copy and modify, but grant others the same rights that you have been granted. It's just fair. Enjoy, Tom [25/07/2000] (friedetz@in.tum.de) Jukka [28.06.2006] (walker@netsonic.fi)