SPECIAL EVENTS CODING.
==============================================================================

Basically special event coding is coding exceptions for an object/mobile or 
room in standard C/MUD C. All I did is add some macros to make life a little
easier. In the zone_writing.doc you can find how you can add special event code
to an object/mobile/room. This file is to show what options there are, and what
values are to your disposal when writing the code.

First of all: To use the macros i use, you need to include the file "special.h"
in your zone.


EXPLENATION OF MACROS
=============================================================================

catch_..... 	: a macro that will check which event is being called.

send_room_but_player(Mode,String) = Send string to everyone in room, except
                                    for the active player, using Mode.
send_with_name(Mode,String)       = same as the one above, only you can use
                                    %s to denote the active player's name.
send_room(S)			  = Send to everyone in the same room as the
                                    active player. (In most cases you can
                                    use standard bprintf).
send_player(S)			  = Send to the active player. (In most cases 
                                    you can use standard bprintf).
send_to(Player,String)		  = Send string to player.
place_object_in_room(O,L)	  = Place object O in room L.
place_object_in_inv(O,P)	  = Put object in mobile/player P his/her
                                    inventory.
create_object(O)		  = Create object O in the room it is in
                                    now. (clears OFL_DESTROYED).
armor_class(O)                    = the armor value of the object.
trans_player_to(L)		  = move active player to location L, and do
                                    a look.
player_strength(P)		  = Strength of the player/mobile P.
start_fight(A,V)		  = Start a fight, A=attacker and V=victim.
                                    Both A and V should be player/mobiles.
mobile(M)			  = convert Mobile number to internal
                                    representation. 
mobnum(M)		          = convert internal representation to
                                    mobile number.
death_trap(S)			  = Kick someone off with message in the 
                                    string S.
fail(E)	                          = Fail to continue with the command, ie
                                    don't do anything more. E should be <>1.
succeed()		          = continue with command processing, ie
                                    fail(1).
do_not_continue                   = set error value, but do not return to 
                                    caller function.
param_s.ret			  = Denotes if the the program should 
                                    continue with the default code for
                                    that object, or should return to
                                    the parser. if this value is 1 (Default)
                                    the program will continue. If it is any
                                    other value it will return to the parser.


LISTING OF ALL EVENT HANDLERS AND AVAILABLE VARIABLES (A-Z).
==============================================================================

catch_break:
    Description
        This is the same as catch_kill, except this works on objects instead
        of mobiles. Code can be placed in an object.

    Variables
        THIS_OBJECT  : The object you want to break.
        param_s.pl   : not filled in.
        event        = E_ONKILL


catch_close:
    Description
        Player tries to close an object, either door or container. Code can
        only be placed in the object that should be closed.

    Variables
        THIS_OBJECT  : The object the player wants to close.
        THIS_PLAYER  : current user.
        THIS_LOCATION: the location of the player.
        event        = E_ONCLOSE

catch_death:
    Description
        This one is called when a mobile dies. Code which uses this event can
        only be placed in a mobile
 
    Variables
        THIS_OBJECT  : Not set.
        THIS_PLAYER  : The attacker (NOT the active player).
        param_s.pl   : The victim (the one that dies).
        THIS_LOCATION: The location of the victim.
        event        = E_ONKILLED


catch_dig:
    Description
        Player digs in a room. Code can be placed in room, or any object in the
        room.

    Variables
        THIS_PLAYER  : active player.
        THIS_OBJECT  : Object given as parameter (example: dig pick, then 
                       THIS_OBJECT is the number of pick).
        THIS_LOCATION: The location of the active player.
        param_s.misc : ONLY if code is in object. It gives you the object 
                       number of the object that has the code.
        event        = E_ONDIG


catch_drop:
    Description
        This is a fairly complex event, since there are two types of drops:
        In a pit or a normal. Therefore this command is split in two.
        The code for a normal drop can be placed in a room or an object. The
        code for a drop in pit situation can only be placed in the object.
        The type of drop can be determined by checking the variable 
        param_s.misc.
  
    Variables
        THIS_OBJECT  : The object that is being dropped (also works for cloned
                       objects).
        THIS_PLAYER  : The active player.
        THIS_LOCATION: Normally is the location of the player, but in some
                       zones like, quarry or sea this object is manipulated to
                       point to another location.
        param_s.misc : On a normal drop = D_NORMAL
                       In pit drop      = D_INPIT
        event        = E_ONDROP


catch_eat:
    Description
        The player tries to eat/drink an object. Code can be placed in an
        object.

    Variables
        THIS_PLAYER  : The active player.
        THIS_OBJECT  : The object the player wants to consume
        THIS_LOCATION: The location the player is in.
        event        = E_ONCONSUME


catch_entry:
    Description
        Checks if the room a player wants to move to objects to that move.
        Code can be placed in a room.

    Variables
        THIS_PLAYER  : The player that wants to move.
        param_s.ob   : The direction in which the player was moving
        param_s.misc : The destination room.
        THIS_LOCATION: The location the player is in at the moment.
        event        = E_ONEXAMINE


catch_examine:
    Description
	handle this code when a player examines an object/mobile.
        Code can be placed in object or mobile.

    Variables 
        THIS_PLAYER: The current player (the one that does the examine)
        THIS_OBJECT: The object (if one) the player is examining. Value
                     is -1 if no object is being examined.
        param_s.pl : The mobile (if one) the player is examining. Value
                     is -1 if no mobile is being examined.
        event      = E_ONEXAMINE


catch_get
    Description
        The player wants to get something from somewhere. This command
        has three special events check, one before, one during and one
        after get. Code can be placed in objects, mobiles and rooms.

    Variables
        THIS_PLAYER  : The active player
        THIS_OBJECT  : The object the player wants to get. If it is the
                       before check, the code will continue with the value
                       in this variable.
        THIS_LOCATION: The location the object is in, if object is in
                       container, else the location of the active player.
        param_s.misc : Depending on the check it is either
                       - BEFORE_GET
                       - DURING_GET
                       - AFTER_GET
        event        = E_ONGET


catch_give:
    Description
        The player wants to give something (an object) to someone (player
        or mobile). Code can be placed in either the object or mobile.

    Variables
        THIS_PLAYER  : The active player.
        THIS_OBJECT  : The object the player wants to give.
        param_s.pl   : The player/mobile, he/she wants to give the object
                       to.
        THIS_LOCATION: The location the active player is in. 
        event        = E_ONGIVE


catch_init:
    Description
        This one gives you the oppurtunity to initialise data. Code can be
        placed anywhere.

    Variables
        event = E_ONINIT


catch_jump:
    Description
        Jump from one place to another (or not). Code can only occur in rooms.

    Variables
        THIS_PLAYER  : active player
        THIS_LOCATION: the room the player is in.
        param_s.to   : The destination location according to the jumptable.
        event        = E_ONJUMP


catch_kill:
    Description
        The player is trying to attack someone. Code can only be placed in
        mobiles.

    Variables
        THIS_PLAYER  : The active player.
        param_s.pl   : The player/mobile the player wants to kill.
        THIS_LOCATION: The location of the active player.
        event        = E_ONKILL

catch_light:
    Description
        This one can only occur in objects. It is meant to attach a special
        event on the light command.

    Variables
        THIS_OBJECT  : The object the player is trying to light. 
        THIS_PLAYER  : The active player.
        THIS_LOCATION: The location of the object.
        event        = E_ONLIGHT

catch_lock:
    Description
        The user tries to lock an object either door or container. Code can
        only be placed in the object that should be closed.

    Variables
        THIS_OBJECT  : The object the player wants to lock.
        THIS_PLAYER  : The active player.
        THIS_LOCATION: The location of the player.
        event        = E_ONLOCK


catch_movement:
catch_move:
    Description
        The player wants to move from one room to the other. This one checks
        if the current room, or mobiles in the current room object to that
        move. Also see catch_entry. Code can be placed in mobile or room.

    Variables
        THIS_PLAYER  : The player that wants to move.
        param_s.pl   : The number of the mobile that is checked. (If mobile)
        THIS_LOCATION: The location the player is in.
        param_s.ob   : The direction the player is moving in. 
        event        = E_ONMOVE


catch_open:
    Description
        The player wishes to open an object either door or container.
        Code can only be placed in the object.

    Variables
        THIS_OBJECT  : The object the player wishes to open
        THIS_PLAYER  : The active player
        THIS_LOCATION: location of the player
	event        = E_ONOPEN


catch_push:
    Description
        The player is trying to push an object. Code can only be placed in
        the object that should be pushed.

    Variables
        THIS_PLAYER  : The active user.
        THIS_LOCATION: The location of the player.
        THIS_OBJECT  : The object that the player wants to push.
        event        = E_ONPUSH


catch_put:
    Description
        The player wants to put an object somewhere else (another object).
        Code can be placed in either the destination object or the object
        that should be moved.

    Variables
        THIS_PLAYER  : The player that typed the put command.
        param_s.misc : The object the player wants to put.
        THIS_OBJECT  : The object where THIS_OBJECT should go in/onto.
        THIS_LOCATION: The location of THIS_OBJECT.
        put          = E_ONPUT


catch_sit:
    Description
        The player sits (on something). If player tries to sit on an object,
        the code can occur in an object or room. If it is just plain sit,
        then only the room the player is in is checked.

    Variables
        THIS_PLAYER  : active player
        THIS_LOCATION: the location of the player.
        THIS_OBJECT  : the number of the object the player tries to sit on.
                       Only filled in if parameter is given.
        param_s.misc = VERB_SIT
        event        = E_ONMISC


catch_sleep:
catch_trance:
    Description
        The player is trying to sleep/trance. This code can only be placed
        in a room. The code is called AFTER the player status is set to 
        sleep/trance.

    Variables
        THIS_PLAYER  : The active player
        THIS_LOCATION: The location of the player.
        event        = E_ONREST

catch_tell:
    Description
        The player tries to talk to a mobile. The code can only be placed in
        a mobile.

    Variables
        THIS_PLAYER  : The active player
        param_s.buf  : The message the player wants to tell.
        param_s.pl1  : The mobile the player wants to talk to
        THIS_LOCATION: The location the player is in.
        event        = E_ONCOMM
        param_s.ret  : This value can be set to the following values:
                       -1 : Stop processing, show no error message.
                       1  : Stop with the whats the use message.
                       0  : Send a new message pointed to by param_s.buf,
                            back to the player.


catch_tie:
    Description
        Player tries to tie an object to something. The object should have
        the oflag "Rope" for this one to work. Code can be placed in rooms
        or objects.

    Variables
        THIS_PLAYER  : The player that typed the tie command.
        THIS_OBJECT  : The object the player wants to tie 
        THIS_LOCATION: The location the player is in.
        event        = E_ONTIE


catch_timer
    Description
        A special function that is called every 2 seconds IF a player is in
        the room the object/mobile is in. This can also be used for the room.
        bprintf can't be used in this event.

    Variables
        event          = E_ONTIMER
        If used in room code:
        - none
        If used in mobile code:
        - THIS_PLAYER  : The player that is in the room and that is being
                         checked. (If more players are in the room the function
                         will be called more than once).
        - param_s.pl   : The mobile where the code is in.
        If used in object:
        - THIS_OBJECT  : The object the code is in.
        - THIS_LOCATION: The location the variable is in.


catch_throw
    Description
        The player wants to throw a certain object. Code can only be placed 
        in the object.

    Variables
        THIS_PLAYER  : The active player
        THIS_OBJECT  : The object the player wants to throw.
        THIS_LOCATION: The location the player is in.
        event        = E_ONTHROW


catch_trance
    See catch_sleep


catch_unlock:
    Description
        The user tries to unlock an object either door or container. Code can
        only be placed in the object that should be closed.

    Variables
        THIS_OBJECT  : The object the player wants to unlock.
        THIS_PLAYER  : The active player.
        THIS_LOCATION: The location of the player.
        event        = E_ONUNLOCK


catch_untie:
    Description
        Player tries to untie a rope. (oflag "rope" not needed). Code should
        be in an object.

    Variables
        THIS_PLAYER  : The player that typed the untie command.
        THIS_OBJECT  : The object the player wants to untie.
        THIS_LOCATION: The location the player is in.
        event        = E_ONUNTIE


catch_wave:
    Description
        If the player uses the wave command with as parameter an object,
        this code is called. That's also the reason that it can only be
        coded in an object.

    Variables
        THIS_PLAYER  : The active player
        THIS_LOCATION: The location of the player.
        THIS_OBJECT  : The object the player waves with.
        param_s.misc = VERB_WAVE
        event        = E_ONMISC


catch_wear:
catch_wield:
    Description
        This will catch the wear/wearall and wield command. It can only occur
        in an object.

    Variables
        THIS_OBJECT  : the object the player wants to wield/wear
        THIS_PLAYER  : The active player.
        THIS_LOCATION: The location of the player.
        event        = E_ONUSE


catch_while_fighting:
    Description
        This is a complex one. This code is only checked if the attacker is
        a player and the victim isn't aliased. Because the fighting occurs on
        a timer interval you can't use the bprintf function here. The code
        can only be located in a mobile.

    Variables
        THIS_PLAYER  : The player/mobile who is hitting (attacker).
        param_s.pl   : The player/mobile on the receiving end (victim).
        THIS_OBJECT  : The weapon the attacker is wielding.
        THIS_LOCATION: The location of the attacker (which is almost always
                       the same as the location of the victim).
        event        = E_WHILEFIGHT

More not documentated events exsist.



SMALL C-SYNTAX
==============================================================================

Comparing integers:

x != y   x is not equal to y
x == y   x is equal to y
x <  y   x is smaller than y
x >  y   x is greater than y
x <= y   x is smaller or equal to y
x >= y   x is greater or equal to y
         (mobile,object and room numbers are integers).

string comparison:

strcmp(A,B)  
             compare string A with B. return value is < 0 if A is smaller
             than B, 0 if A is equal to B, > 0 if A is greater than B. This
             function is case-sensitive!
strcasecmp(A,B)
             Same as strcmp, except now case insensitive.
strncmp(A,B,n)
             Check the first n bytes of string A with the first n of string
             B. return values are equal to strcmp.
strncasecmp(A,B,n)
             Same as strncmp, only now case insensitive.


check_statements:
  They can consist of one or more string/integer comparisons. Checks must
  be linked using && (and) or || (or). 

if-statement:

if (    )
{  ...code
}
else <if (   )>
{
}

while-statement:

while (  )
{
}

repeat-until statement:

do
{
}
while (  );

case statement:

switch (value) {
case option1 : ..... 
               break;
case option2 : ..... 
               break;
default      :
}