Merc Release 2.2 Wednesday 24 November 1993 Kahn Hatchet === Player File Format Player files are ascii files. A player file contains a player section followed by one or more object sections. Each section contains several lines. Each line contains a keyword followed by a value. An old Internet dictum says 'be conservative in what you send and liberal in what you accept'. Thus Merc writes player files in a fixed order, but accepts flexible ordering, partial files, et cetera. There are two section types: #PLAYER and #OBJECT. The #PLAYER section defines player values. Each #OBJECT section defines one object. A third section type, #MOB, is partially implemented and may be implemented in a future release. Merc writes one #PLAYER section per file, but will read multiple sections. If the same value is specified twice the later value generally overrides earlier values; some lines, such as the 'Affect line', just append more affects. If a value is not specified, some default value is used. Players are saved with their equipment on. Thus, the values in the #PLAYER section reflect current equipment applies, including 'Hitroll', 'Damroll', 'Armor', and 'AttrMod', as well as hit points, mana, move, and others. Thus, great care is needed when adding or deleting objects which a player is currently wearing. A #OBJECT section contains all the object values, including the object's current wear location. Objects which have been 'oset' retain all of their values. Again, editing an object which is currently being worn requires care; the corresponding #PLAYER state must also be changed to match. Each #OBJECT has a nesting level. Objects in inventory or equipment list have nesting level 0. Objects inside a container in inventory or equipment list have nesting level 1. Objects inside a level-1 object are level 2, et cetera. Objects deeper than nesting level 100 are quietly discarded. This nesting level is used to reconstruct container contents when loading objects. Thus, if you delete a container from a file, its objects are likely to be loaded inside the previous object; and if that's not a container, the player will be unable to get them out of the object. To avoid this problem, reset the nesting level of each contained object to 0. Objects are stored in the file in reverse inventory-order list. This is not pretty, but it allows the use of standard 'obj_to_obj' and 'obj_to_char' calls to construct the object lists. You may add new fields to players and objects. Because of the line-oriented ascii format, changing a structure size in 'merc.h' will never invalidate a player file. Naturally, you must ensure that when an old file which does not contain a line for a new field is read in, the new field is set to some reasonable default value. E.g., if you add a 'home town' name for players, then initialize it to 'Midgaard' before reading in the player file, so that old players get the 'Midgaard' value, and new players get whatever value is on that line of their file. Similarly if you delete a field from the player or object structure, you must leave the parsing line for it in 'fread_char' or 'fread_obj'; simply assign it into a dummy variable. This allows your old player files to continue loading. === How to Add a New Char Field (1) Add the field to the appropriate structure in 'merc.h'. (2) Initialize the field in 'create_char' or 'clear_char' in 'db.c'. (3) Initialize the field in 'load_char_obj' in 'save.c' if needed. Make sure that old players which do not have the field are initialized to a reasonable value. (4) Add lines to write out the field in 'fwrite_char' in 'save.c'. (5) Add lines to read in the field in 'fread_char' in 'save.c'. === How to Add a New Object Field (1) Add the field to the appropriate structure in 'merc.h'. (2) Initialize the field in 'create_object' in 'db.c'. (3) Initialize the field in 'fread_obj' in 'save.c' if needed. Make sure that objects which do not have the field are initialized to a reasonable value. (4) Add lines to write out the field in 'fwrite_obj' in 'save.c'. (5) Add lines to read in the field in 'fread_obj' in 'save.c'.