The MUD Coder's Handbook
for Merc and Ack!mud

written by Zenithar (Stephen Zepp) zenithar@nucleus.atom.com

DISCLAIMER:  This handbook is written based on my personal experience with merc and ack!mud code.  I make no claims to it's accuracy, but everything I have learned so far is working for me :)  I use a linux based p90 server with a T-1 line and 24 meg of memory to run Shades of Evil, the only current Ack!mud based mud in existence, located at soe.nuc.net 6666.  Come check us out :)

CREDITS:  All the standard diku and merc credits apply, and Ack!mud was written by Stephen Dooley (Stimpy), with major modifications by myself, Altrag, and many others on my coding team.  Thanks, all :)

Table of Contents

I.  General Merc overview
II. File Structure (code)
III. Player Files
IV. Spells and Skills
V. Internal Merc type stuff
VI. Ack!mud specific implmentations

I. General Merc Overview

	Merc and Ack!mud code is written in ANSI C, using standard TCPIP protocols.  While I won't get into the base level socket call design, any good reference book on TCPIP implementations in C should be used if a greater understanding of this area is desired.

	The code has a basic loop in comm.c that handles the game control.  Basically, two routines are run continuously: player input/output, and the update handler.  All player input is routed through interp.c and handler.c based on the commands that are defined in various files, headers of which are all located in merc.h.  
	The update handler (in update.c) takes care of everything from player regen to area repops to weather updates.  It is set up with a group of event timers.  One loop through the update handler decrements each timer, then checks to see if a timer reaches 0.  This indicates that an event needs to occur, like a spell expiring, an area repopulating, etc, and calls the appropriate code module to handle those actions.
	As you can see, the general program flow is rather simple.  It is basically just a two level control tree, with several thousand calls to various support routines located in the rest of the files, detailed in the next section.

II. File structure (code)

	The code is comprised of over 20 internal .c files that are mostly grouped functions according to the functions purpose.  Primarily, the functions in a file are pretty obvious..information commands for the player are in act_info.c, etc.  merc.h has a full list of every function that can be called externally, so if you need a function, check there first to see if it has been written.

FILES:

act_clan.c :	contains player commands for clan oriented stuff.
act_comm.c :	mostly player communication commands.
act_mob.c : 	ackmud specific intelligent npc functions.
act_move.c :	all move oriented commands.
act_info.c	mostly information oriented commands, including things like worth, score, etc.
act_obj.c :	object manipulation commands
act_wiz.c :	immortal command functions
area*.c :	area stuff
build*.c	online building functions
clutch.c	 :	implementation of type clutch objects
comm.c	most TCPIP stuff, plus the overall main function
const.c :	a VERY important file, this defines most constants in the game, plus all skill and spell 		command parameters, plus lots of other stuff..very important to be familiar with this file.
db.c :		All the initial boot up functions are here.  again, be familiar with this file.
trigger.c :	I THINK this handles event triggers.
fight.c :		All the fighting code, including many fight oriented skills.
handler.c :	various internal char, spell (affect) and item routines..uch usful stuff..get VERY familiar 		with this one.
interp.c		The player command router, plus social handler and definitions.
macros.c :	A catch all for various commonly called routines, like exp_for_mob, etc.
magic*.c :	The actaul functions to handle skill and spell effects.
merc.h :	The general header file that contains just about everything in merc.  This might be the 		most important file to know well.  It contains a directory of where all other functions are, 		also.
save.c :		Handles most pfile saving and loading.
update.c :	The update handler.

	This is by no means a complete list of all the files, just those that I feel are important to understand to modify a mud.  

III. Player files

	Player files ae really the heart of the code, in that everything that happens to the players gets stored here.  There are over 50 seperate fields, each are mostly self explanatory.  The saver saves things in a specific order (overwriting the old file, which CAN cause problems), but the loader decodes files as they load line by line, which makes pfile changes rather easy.  Look over this setup when you want to add something to your code that must be saved.

IV.  Spells and skills

	Another very important area that adds to muds is the skills and spells that area available to a player.  Here is a step by step provedure to add new spells and skills.

SPELLS:

	1) write the function code iteself, and place in one of the magic*.c files.
	2) Add the spell parameters to constant.c  This defines casting cost, duration, etc.
	3) Add the spell header to merc.h in the DO_SPELL area.  Just copy an old one.
	
SKILLS:

	Skills are really just spells that always apply themselves, like dodge or parry.  Also, skills like trip, disarm, etc fall into this catagory.  THe procedure is mostly the same, but since you don't use the spell handler (do_cast in magic.c), you have to add a few more things.

	1) write the function itself.
	2) add the skill parameters to const.c
	3) add the skill header to DECLARE_DO_FUN in merc.h
	4) add a gsn for the skill in merc.h
	5) umm, I forgot the last one :(   ANYONE?  ANYONE? STIMPY?? :P

V. Internal merc stuff

	There is so much to cover, I can only talk about the basic stuff right now.

	Lists:  Merc maintains a large amount of lists (pointer based) for just about everything in the mud, from areas to rooms to players in the rooms to affects on a char to followers (this is just a demonstrative sample).  It will be important to eventually understand all the lists, becuase they can give you important information for good code management.  Here are some of the more important ones.

	affects:		players maintain lists of the affects that are cast on them, which are updated by the update handler.  A majority of affects are manipulated by affect_add, affect_modify, and affect_remove.

	(more lists to follow )

V!. Ack!mud specific implementations

DISCLAIMER: while many of these designs may be in place on other muds, the specific ack!mud implementations are unique, and in many cases superior :)

vampyres
multi-classes
remorts
adepts
room affects
mercenary mobs
online building
clan code
colours, both in descriptions and communication

(more to follow)

VII. Conclusion

	First of all, this is a rough draft.  

	Any suggestions, comments, or additions, pls e-mail zenithar at the previously listed address.  Feel free to modify this document directly, but pls put a *** at the beginning of any changed or new line, so that I can assimilate the change into the master document.  Thank you :)

Zenithar