Valid XHTML
          1.0! Valid CSS!

ZeusThe Catch Function System

How to do special cases in the zonefiles

Originally created by Ithor (J.Willie) for Northern Lights AberMUD (NL-dirt 1.2).
Updated and maintained by Vitastjern, for Northern Lights AberMUD (NL-dirt 2.0).
Copyright (c) Northern Lights AberMud 1993 - 2005.

Contents:


Introduction

The catch system is simply a way to specify many more special things in zone files, without adding hardcode to the mud engine. Instead the information is used to generate C code to cause your specials to happen. This document will explain how to use the catches and what each of the catch functions does.

One important thing to consider is that complicated catches should be written by those that have a working knowledge of the dirt source code.

There are two main types of catches, those bound to in-game commands like "give" for instance, and those bound to events.
All catches bound to a command in the game are called before the actual code for the command. This means that none of the ordinary checks will be done, and the catch writer will have to consider the limitations of the command on his or her own. One example is that if you create a catch on the give command, you need to make certain that the mobile is in the same room as the player that tries to give it something.

A way to get around the limitation of using in-game command catches, is to use so called event catches as far as possible. Event catches call the catches after the sanity checks have been made. Instead of putting a catch on the "give" command, in most cases it will be much easier to put the catch on the "on_give" event instead.
The on_give event will automatically check for things like that the mobile is in the same room as the player that tries to give it something, and that the object is actually there to be given away, that the mobile is alive, and it will also set certain variables that can be used inside the catch.

There are 3 basic types of items in the mud, mobiles, objects and locations. Each of these may have any number of catch entries. A catch in general has the form

  Catch = VERB_LIST; FUNCTION_LIST;
A VERB_LIST is just a list of verbs in the mud and consists of in-game commands or events. Each verb is seperated by commas. The FUNCTION_LIST is also seperated by commas. Blank characters (spaces, tabs or new lines) are ignored.

Example:

    Name     = Tuss
    Strength = 10000
    Damage   = 300
    ...
    Catch    = pet, hug;
      if_here_alive(Tuss)
        send_message(TO_MYNUM, "Tuss purrs and licks your hand."),
        fail(),
      endif;
    Catch    = on_kill; // Trying to kill Vitastjern's cat!
      deathtrap(CATCH_INITIATOR, 
                "Attacking Vitastjern's cat is bound to be a bad idea, "
                "especially bearing in\nmind his vital statistics "
		"(namely, damage 300 and strength 10,000), and so\n"
                "exorcism is in your own best interests. But these "
                "things have to be done with\nstyle, so...\n"
                "        You are summoned by the Gods, rolled in "
                "catnip, and translocated to a\ngladiatorial arena, where "
		"a lioness seems to be taking quite an interest in you.\n"
		"The collective purr of the crowds is deafening. Your "
		"last recollection is of\na sign on one wall warning "
		"your future incarnations about the consequences of\n"
                "being unkind to cats.\n",
                "%m had the bad taste to attack Vitastjern's cat and "
                "is dragged\naway to the gladitorial arena to meet the"
                " lions!",
                NO_MSG,
                NO_MSG,
                "\t\tBye Bye.... Slain by a Kitty Cat!");
    End      = Tuss
Note that every catch function, except the last one in a catch, is ended with a comma. The code generator is told to expect the end of a catch when it encounters a semicolon at the end of a catch function. The VERB_LIST is also ended with a semicolon.

You can use conditions within the catch, the if_here_alive() catch function in the pet, hug catch is an example of this. The catch will only go through if the mobile Tuss is actually alive and in the same location as the player hugging or petting him.
All conditions can be negated by adding a "not_" to the condition catch function after the "if_", ie if_not_here_alive().

To ensure readability, we strongly suggest the use of indentation. Each catch function is indentated two spaces, and after an condition (ie if_*), there is an added two space indentation for the duration of the condition. When the condition ends, the extra two space indention is no longer needed.

In the second example we're using the on_kill event, which automatically checks if the mobile Tuss is present and not already dead...

Mobile or Object catches look exactly like the example catches above, with few exceptions. However, location catches need to be a little different. A locations definition normally looks something like

  room_name <exit list>;
  lflags{}
  room_title^
  description
  ^
The location catch starts on the very next line after the description and ^ character. It is important that you do not leave a blank line and that if for some reason you have a room called catch, that you place at least one blank line between rooms. In addition, the list of location catches must end with the keyword EndCatch on it's own line. There should be no blank lines between catch entries.

Example:

  Glacier s:pointe e:edge;
  lflags{Outdoors Cold}
  Lost on the Glacier^
    You find yourself on fairly safe footing atop the glacier, but if you stay 
  here too long, you could soon freeze to death.
  ^
  Catch = on_dig;
    send_message(TO_MYNUM, "You find nothing special here, but don't give "
               "up the search."),
    fail();
  EndCatch


Zone keywords

Zone keywords and the importance of their correct position in the zone file are discussed more closely in A manual for the aspiring world builder, in the Tips for creating and maintaining your zone section. However, there are a couple keywords that are used for catch purposes. These keywords will be discussed in this section.

The %quest_info keyword starts a section where only one event will be catchable, namely the quest_info event. This is used to get the quest status so that the quest commands can display if a quest is in progress, ruined, doable, etc. The quest_info event must always end with a fail() catch to indicate that there has been a catch at all.

The %world_catches keyword starts a section much like %zone_catches, but you should make every attempt to avoid putting anything here, if at all possible, as it will run very, very, very often and every little catch added here will help to slow down the mud. As with %zone_catches, the adding of additional events catched in the world on a zone has less overhead than the first one, but it should still be done with extreme caution.

The %zone_catches keyword starts a section of the zone file that will catch one or more catches in the same format as locations catches, ie ending with an EndCatch. The catches will be for the whole zone and called for every player in the room. Use this with some caution, as these catches will be run a lot more often than others. Adding a single catch here adds to the processing time of the entire mud. Once you have, however, adding catches to other events will add much less overhead per catch.

The %globalcode keyword is used to write functions to use inside the zone. Leave this to the coders, since to properly use it you need access to the source and some knowledge of the internal plumbings of Northern Lights.
This section, if it exists, must be placed last in the zone file.


Variables and constants


  loc : is the name of a location.  eg church@start
  mob : refers to a mobile name.    eg Puff
  obj : is the name of an object,   eg umbrella@start
The @zone part is only required if refering to things in another zone.
  string : anything enclosed in " "
Note that a string in excess of 72 characters should have linebreaks added to it, and that it for readability can be divided over several lines in the catch function. A linebreak is preferrably placed so that it replaces a space somewhere between position 68 and 75. Use the newline code "\n" to represent a linebreak.

When the catch is called, a number of variables are set including the ones above. The values some of these variables are set to before the call is explained in the events and extra verbs section.
The catch_tmp variable is a means of having a variable that can be used within the catch to store values in. It has the scope of the catch only, but is always available without having to be declared. For typed variables (where you can't save a value of the wrong type), use catch_tmp_loc, catch_tmp_mob and catch_tmp_obj. The mynum variable is used to denote the player.
In any of the normal catch calls that need one, a constant can be used in place of a location, object or mobile. Those constants are references that will be replaced by the at a catch call automatically set variables.
With the exception of catch_tmp, catch_tmp_loc, catch_tmp_mob and catc_tmp_obj, no variables may be changed inside the catch unless permission is given in the specific event.

     Constant              Replaced with        Comment
     --------              -------------        -------
     CATCH_ARG           - catch_arg
     CATCH_CHAIN_START   - catch_chain_start    The entity on which the catch
                                                was first called. This should
						in most cases equal catch_this,
						but differs if a catch does a
						trigger_* call, in which case
						the catch_this variable changes
						to the new object being called
						while catch_chain_start does 
						not.
     CATCH_EXTRA	 - catch_extra
     CATCH_INITIATOR     - catch_initiator
     CATCH_LOCATION      - catch_location
     CATCH_LOC_MYNUM     - catch_loc_mynum      Read only, equals ploc(mynum).
     CATCH_MYNUM         - mynum                Read only.
     CATCH_MYNUM_ID      - player_id(mynum)     Read only, absolute player id.
     CATCH_TARGET        - catch_target
     CATCH_THIS          - catch_this           The entity the catch is 
                                                attached to.
     CATCH_TMP           - catch_tmp            Temp variable.
     CATCH_TMP_LOC       - catch_tmp_loc        Type checked temp variables to
     CATCH_TMP_MOB       - catch_tmp_mob        be used at the catch writer's
     CATCH_TMP_OBJ       - catch_tmp_obj        discretion.
Most other things are probably numbers (integers).


Verbs

The verbs used to attach catches to can be selected from the in-game commands. Type HELP while on Northern Lights to get a list of commands. You may also use special actions, all listed at the end of the ACTIONS list.
It is preferrable to, as far as possible, attach the catch to an event instead of the corresponding command.


List of events and extra verbs

These are a few names that can be used instead of a verb, to attach a catch to in order to get things to happen at particular times. The majority of the events have sanity checks before even calling a catch.


Explanation of events and extra verbs

armor_mod
Enables the setting of a armor modifier value on an object that is "active" in the inventory. An active object is an object that is worn and/or wielded if worn and/or wieldable, or just in the top level of the inventory. It may not be in a container. The main use for this event is to enable easy modification of catch_arg to a value different from the default value.
Objects with a armor modifier needs the ArmorBonus attribute to be considered. Blessed and Cursed oflags also influences the modifier. The modifier value is used in for instance the calculation of armor in a fight, and in the STAT and USTAT commands.
If catch_arg has been set to 0, the Blessed and Cursed oflags will not change the modifier value.
WARNING: In this event you may NOT assume knowledge of mynum, nor use mynum or any catches that assumes mynum. You must use catch_initiator etc.
Note that armor_mod is also called on world catches. Catching this on the world should be avoided if at all possible (just like any other world catch). If you have to use a world catch for armor_mod make sure that the catch_arg value is increased or decreased by the right amount, and do not set it to a specific amount. This is because some other world catch may also be changing the value, and the sum of the values should be in catch_arg after the event.
armor_mod sets the following variables before the call:
     - catch_initiator = the attacker if in a fight, else -1
     - catch_target    = the mobile using the modifier object
     - catch_arg       = the damage modifier value (default is 0)
     - catch_location  = where the catch_target is currently

break_attack
Called in a fight when fight calculations are made, after all checks for valid victims, weapons wielded etc are made. This event can be attached to a mobile attacking, a mobile victim, a weapon used by the attacker, the location the victim is in or the zone the victim is in, and is checked in that same order.
The event can be used for "instant kill" mobiles, where the weapon the attacker is using plays a significant role.
Note: Put a fail() at the end of the catch if you want the fight to be broken by the catch. A succeed() will allow the fight code to continue and might also cause the catch to be triggered in the next round of the fight.
WARNING: In this event you may NOT assume knowledge of mynum, nor use mynum or any catches that assumes mynum. You must use catch_initiator etc.
break_attack sets the following variables before the call:
     - catch_initiator   = The attacker -- may be a mobile
     - catch_target      = The victim
     - catch_location    = The location of the victim
     - catch_arg         = The weapon (if any) wielded by the attacker,
                           -1 if no weapon is used. 

burn_out
Called on objects that have burned out. If the catch fails, nothing more happens and everything has to be done in the catch (rember to send messages about the event to both the player and the room where the player is). If the catch is successful, the object burns to dust as normal and nothing more happens. However, if the catch is successful and changed the catch_arg variable, the object will go through "standard recycling", being recycled for the position given in catch_arg. The only difference between the two successful cases is that if the catch_arg is changed, the object doesn't stay destroyed, but instead is recycled after burning to dust.
burn_out sets the following variables before the call:
     - catch_location  = The room where the event is taking place.
     - catch_initiator = The player that carries the burning object.
     - catch_target    = The object that is burning to dust.
     - catch_arg       = The location where the object will end up. This
                         defaults to destroyed@dead, but if it is changed,
			 the object is recycled into the position given in
			 catch_arg after the catch returns successfully.

damage_mod
Enables the setting of a damage modifier value on an object that is "active" in the inventory. An active object is an object that is worn and/or wielded if worn and/or wieldable, or just in the top level of the inventory. It may not be in a container. The main use for this event is to enable easy modification of catch_arg to a value different from the default value. Objects with a damage modifier needs either the DamageBonus or DamagePenalty attributes to be considered. Blessed and Cursed oflags also influences the modifier. The modifier value is used in for instance the calculation of damage in a fight, and in the STAT and USTAT commands.
If catch_arg has been set to 0, the Blessed and Cursed oflags will not change the modifier value.
WARNING: In this event you may NOT assume knowledge of mynum, nor use mynum or any catches that assumes mynum. You must use catch_initiator etc.
Note that damage_mod is also called on world catches. Catching this on the world should be avoided if at all possible (just like any other world catch). If you have to use a world catch for damage_mod make sure that the catch_arg value is increased or decreased by the right amount, and do not set it to a specific amount. This is because some other world catch may also be changing the value, and the sum of the values should be in catch_arg after the event.
damage_mod sets the following variables before the call:
     - catch_initiator = the player using the modifier object
     - catch_target    = the victim of the attack if in a fight, else -1
     - catch_arg       = the damage modifier value (default is 3)

follow_player
Called on all mobiles in a room when a player leaves the room, and is used to make mobiles stick around a player.
follow_player sets the following variables before the call:
      - catch_initiator   = the exit we are going through
      - catch_target      = the location we arrive in
      - catch_arg         = the exit we came through when in the new location
      - catch_location    = the location we came from
Please observe that the player being followed is preferably stored in an object in the zone file and checked against at the start of the follow_player event.

get_from
Called (once per command only, even if the command is a 'get all' or 'get class' command) on the container the player is trying to get things from, if (s)he is trying to get something from a container, and on the location the player is in (regardless of whether the player is picking something up from the room or a container). The location event is not triggered if the player takes something from a container (s)he is already carrying, however.
get_from sets the following variables before the call:
      - catch_initiator   = The player that is getting the object.
      - catch_location    = The room where the event is taking place.
      - catch_target      = The container the player is trying to get
                            things from. If the player is getting
			    something from the room, this will be the
			    invalid obj (-1).
      - catch_arg         = The object being picked up or the invalid
                            obj (-1) if it's a 'get all' or 'get class'
			    command.

get_obj
Called on the object being taken with a get (or as a first part of put) and on the location where the player taking it is. Failing the catch will prevent the player from picking the object up.
get_obj sets the following variables before the call:
      - catch_initiator   = The player that is getting the object.
      - catch_location    = The room where the event is taking place.
      - catch_target      = The container the player is trying to get
                            things from. If the player is getting
			    something from the room, this will be the
			    invalid obj (-1).
      - catch_arg         = The object being picked up.

look_msg
Called on the mobiles in a room when someone makes a look in in a room, and can be used to change the message displayed for a mobile. Remember to fail after outputting message. Message should be sent with send_message(TO_MYNUM, ...) or by codeline(bprintf(...);), with the first way being preferred.
Note that no catch variables are set in this event.

mobile_killed
When someone is killed, this event is first checked for under %world_catches, then in the zone, followed by the location in which the death occured. If there is no catch on either of these, the event is triggered on the victim in the case that the victim is a mobile. If all triggered catches succeeds, the kill continues as normal. If either of the catches fails, the kill fails and the victim is restored. Remember to set the victim's strength back to zero or more when failing.
mobile_killed sets the following variables before the call:
     - catch_initiator    = The player or mobile that gave the killing blow.
     - catch_target       = The player or mobile that was killed.
     - catch_arg          = The verb code for the killing spell, or < 0 for
                            normal weapon/hand hit.
     - catch_location     = The location the victim was in.

on_bar
Called on the baring mobile when another mobile or player tries to move in a direction and there is a mobile with a corresponding bar mflag in that location. There must be at least one Bar-mflag attached to the mobile owning the catch.
on_bar sets the following variables before the call:
     - catch_location     = The location the baring mobile is currently in.
     - catch_target       = The room the moving mobile will end up in if (s)he
                            manages to move.
     - catch_arg          = The direction the mobile is trying to move in.
     - catch_initiator    = The moving mobile.
     - catch_extra        = 0
Example:
     Name     = Doorman
     Location = IN_ROOM:Entry
     Mflags   {BarNorth}
     ...
     Catch    = on_bar;
       send_message(TO_MOB, CATCH_INITIATOR, "%c steps into your way and "
                    "says '%sWe do not accept visitors today.&*'"),
       fail();
     End      = Doorman
As a result, whenever a player tries to go north, (s)he sees the following message:
  The Doorman steps into your way and says 'We do not accept visitors today.'
The return values at the end of the catch enables different behaviour from the barring mobile.
  Possible return values:
    - continue()   -- Display the default bar messages. No move.
    - fail()       -- Supress the standard message and leave it up to the
                      catch to supply a message. No move.
    - succeed()    -- Supress the standard message and leave it up to the
                      catch to supply a message. Allow the move.

If the mobile has more than one Bar-mflag, one might want to send different messages or execute different catch functions for different directions.
     Name     = Guard
     Location = IN_ROOM:Entry
     Mflags   { BarEast BarWest }
     ...
     Catch    = on_bar;
       if (catch_arg == DIR_EAST)
         send_message(TO_MYNUM, "%c says '%sHey! You're not going "
	              "to the bedroom of the King, are you?&*'"),
       elseif (catch_arg == DIR_WEST)
         send_message(TO_MYNUM, "%c says '%sI cannot let you enter the "
	              "throne room!&*'"),
       endif
       fail();
     End      = Guard

on_break
Called on an object after sanity checks and all parameters are set correctly. Use this call instead of catching hit/break when your intent is to wreck an object.
on_break sets the following variables before the call:
     - catch_initiator = The player triggering the catch (mynum)
     - catch_target    = The object being broken
     - catch_location  = Where the player breaking the item is located
     - catch_arg       = The object used as a tool to break the catch_target
                         or, if no tool is used, -1

on_dig
Called after sanity checks are done and all parameters are set correctly. Use this instead of catching dig.
on_dig sets the following variables before the call:
     - catch_initiator    = The player triggering the catch (mynum)
     - catch_target       = The object being dug open (hole, snow etc)
     - catch_arg          = The object being used as a tool to dig with
     - catch_location	  = The location where the catch takes place

on_drink
on_eat
Called on the object being eaten/drunk. Some checks are done, like that the mobile has the object within reach, but no check is made for the Food oflag. Only one of the events are called, and it's depending on if you use the eat or the drink command. If you don't care to separate them, just catch both on the same catch.
Note: If all you intend to do is to change the default heal value or the default eat/drink messages, use the FoodHeal, FoodMsg and FoodRoomMsg constructs in the object itself.
on_drink and on_eat sets the following variables before the call:
     - catch_location     = The location the object is currently in.
     - catch_initiator    = The mobile consuming the food.
     - catch_target       = The mobile consuming the food.
     - catch_arg          = The object being eaten.

on_drop
Called on the object dropped and on the location in which the drop takes place after various sanity checks.
Note: Any on_pit_drop catches are executed after the on_drop ones.
on_drop sets the following variables before the call:
     - catch_initiator    = The player dropping the item.
     - catch_location     = The location where the drop takes place.
     - catch_arg          = The item being dropped.

on_enter_room
Triggered on a room when someone enters that room. It doesn't matter if it fails or succeeds, entering can't be aborted.
on_enter_room sets the following variables before the call:
     - catch_initiator    = The player triggering the catch, or -1.
     - catch_target       = The player entering the room.
     - catch_arg          = The exit through which the mobile entered, or
                            -1 if no such exit can be found. Ie, if a player
			    moves north into this room, he's entering from
			    the south exit, and this variable will contain
			    DIR_SOUTH. If he went through a one way exit, or
			    teleported in, the argument is instead -1.
     - catch_extra	  = The location the mobile came from.  

on_give
Called on the object and mobile involved in the give command after all the sanity checks have been passed correctly.
on_give sets the following variables before the call:
     - catch_initiator    = The player triggering the catch.
     - catch_target       = The mobile that's given the object.
     - catch_arg          = The object that's given to the mobile.

on_jump
Called on locations and executed after various sanity checks (ie if the player is sleeping etc).
Note: on_jump is called after on_pit_jump events. This means that if there is a pit with an on_pit_jump catch attached to it in the room, the on_pit_jump catch is executed first.
on_jump sets the following variables before the call:
     - catch_initiator = The mobile doing the jump (mynum).
     - catch_location  = The location where the jump catch is attached.

on_kill
Called after all sanity checks are done when someone attacks a mobile using the kill command and its aliases. This is for replacing kill catches where possible, for things like special one hit weapon attacks etc.
For more complex events involving killing mobiles, for instance if you need to break an attack even if it's done through spells, by a mobile or the break is later in the fight, see break_attack.
on_kill sets the following variables before the call:
     - catch_target       = The victim of the attack.
     - catch_arg          = The weapon being used (this may be invalid, if
                            the attacker is using his/her bare hands).
     - catch_initiator    = The attacker (mynum).

on_leave_room
Triggered on a room when someone tries to leave that room. If the trigger fails, the leave will be halted and no move to the new location take place. If the trigger succeeds, the move carries on like it always would without a catch.
on_leave_room sets the following variables before the call:
     - catch_initiator    = The player triggering the catch, or -1.
     - catch_target       = The player exiting the room.
     - catch_arg          = 0-5 for the exit the player is exiting through,
                            otherwise the negative verb code, or -1 if
			    unknown.
     - catch_extra        = 0-5 for the exit the player is exiting through,
                            or -1. If the catch_arg is greater than or equal
                            to zero, catch_extra is the same as catch_arg.
                            Otherwise catch_extra is still 0-5 if an exit
                            can be found in the source room, that leads to
			    the destination room, or -1 if none can be found.
                            NOTE: Don't use this for catching normal player
                            movement, instead check catch_arg. This is mostly
                            for messages.

on_pit_drop
Called on dropped objects, when someone drops the object in a room where an object with the Pit oflag is, and is called on the Pit-flagged object itself.
The object with the Pit oflag must actually be in the room, not on a player in the room, etc. This makes it possible to make pits send stuff elsewhere than pit@pit (The Pit, or pit1), only accept food, or anything else you want to do. It is called once for every object in a "drop all".
on_pit_drop sets the following variables before the call:
     - catch_initiator    = The object that caused the event (the object
                            with the Pit oflag).
     - catch_target	  = The location that objects will fall to when
                            dropped. This location can be changed by a
			    succeeding catch to move where they land.
     - catch_arg	  = The object that is dropped.

on_pit_jump
Called on objects with the Pit oflag only, when someone executes a jump in the room where the object is (if it's actually in the room, not on a player in the room, etc). Makes it possible to make pits go to new places, reject jumps, etc.
on_pit_jump sets the following variables before the call:
     - catch_initiator   = The player triggering the catch.
     - catch_target      = The object that caused the trigger (the object
	                   with the Pit oflag). This is useful with 
			   trigger_o_catch().
     - catch_arg         = The location that you will fall to when jumping.
                           This location can be changed by a succeeding
			   catch to move where you land.

on_reset
Events that occur whenever the item is reset.
Be very, very careful when using this event as it can yield unexpected results if used to twiddle other items than the one the event is attached to. Mobiles are reset before objects and locations are reset last. This means that if a mobile has an on_reset event that changes an object, the changes will be made undone as the object is reset... It also means that if object X has an on_reset event that changes object Y, which is reset after X, Y will change back to its default. A way to avoid this is to place fiddly object and mobile on_reset events in an location instead.
If confused, please refer to a coder to fix your on_reset event.

on_special
For special cases to move hardcode to catches, the use of this requires the help from the administrators, so don't use it unless you are told to.

on_tick
Called every "tick" (ie based on a timer that triggers every 2-3 seconds) on all "active" locations, and all the mobiles and objects in those locations (including things carried by mobiles and players in their top level inventory, ie not in a container). An "active" location is a location that has at least one player in it. Beware that since this is not triggered by the activities of a player, there is no active player set (that is, mynum is not set, etc).
WARNING: In this event you may NOT assume knowledge of mynum, nor use mynum or any catches that assumes mynum.
on_tick sets the following variables before the call:
     - catch_initiator    = -1
     - catch_target       = -1
     - catch_arg          = 0

player_command
Called after each command the player does, on locations, mobiles and objects in the same room as the player, including things in players top level inventory. This call is made to match player_tick exactly, except that it's called not on ticks but after commands, and it has catch_initiator set to the player instead of -1, which makes it possible to differentiate them.
player_command sets the following variables before the call:
     - catch_initiator     = The player triggering the catch (mynum).
     - catch_target        = The player triggering the catch (mynum).
     - catch_arg           = 0

player_event
Called after each command that the player does, on the location the player is in after the command, plus on the mobiles and objects in that location (including things carried by players in their top level inventory, ie not in a container).
player_event sets the following variables before the call:
     - catch_initiator    = The player triggering the catch (mynum)
     - catch_target       = The player triggering the catch (mynum)
     - catch_arg          = 0

player_login
Called on the location a player enters in, and also in all zone global catches, every time a player logs into the game.
player_login sets the following variables before the call:
     - catch_location     = the location the player is in

player_logout
Called on the location a player exits the game in, and in all zone global catches, every time a player logs out from the game (this includes deathtraps, being killed, quitting, timing out, etc).
player_logout sets the following variable before the call:
     - catch_location     = the location the player is in

player_tick
Called every "tick" (ie based on a timer that triggers every 2-3 seconds) on locations, mobiles and objects in the same room as each player (including things carried by players in their top level inventory, ie not in a container). This is called once per player, so with multiple players in a room it can be called more than once per tick and location. Altough this is not triggered by a player but by a timer, players will, one at a time, be the active player (ie mynum is set to one player each call) to make it easier to use catch functions.
player_tick sets the following variables before the call:
     - catch_initiator    = -1
     - catch_target       = The player triggering the catch (mynum)
     - catch_arg          = 0

put_in
Called on the objects involved in the put command after all the sanity checks have been passed correctly. Use this for PUT xx IN yy constructs where xx is a container that is big enough to hold yy. Use the put_on when dealing with objects that aren't being placed in containers.
put_in sets the following variables before the call:
     - catch_initiator    = The player triggering the catch.
     - catch_target       = The object you are putting something in.
     - catch_arg          = The object that is being put into something.

put_on
Called on the objects involved when putting an object onto another object after all the sanity checks except the ones for containers have been passed correctly. Use this for PUT xx ON yy constructs. Use the put_in event for putting things in containers.
put_on sets the following variables before the call:
     - catch_initiator    = The player triggering the catch.
     - catch_target       = The object you are putting something on.
     - catch_arg          = The object that is being put onto something.

quest_info
NOTE: This event is to be used exclusively in the %quest_info zone section.
This catched event will be used to get the quest state, to allow quest commands to display if a quest is in progress, ruined etc. This catch should always fail to indicate that there was a catch at all. Returning from a quest_info catch call should be done exclusively with the quest_info_return() call, as that will set all the variables correctly and then return fail().
quest_info sets the following variables before the call:
     - catch_initiator    = The quest flag number of the quest being tested.
     - catch_target       = -1. Can be changed to return who set the quest
                            to the current state (ie, who finished it).
     - catch_arg          = 0. Must be updated to set the state of the quest.

room_descr
Failing this call will stop the description of the room from being displayed, but will display everything else about the room (title, list of objects and mobiles, flags for wizards, etc). This allows for replacing a room description, or adding text before or after it under certain conditions.
If you want to add text after the description, use the show_me_loc_descr() call to display the description as normal, then adding more by calling send_message(TO_MYNUM, ...). The mynum variable is guaranteed to be set in this event.
room_descr sets the following variables before the call:
     - catch_location  = The room where the catch was triggered.
     - catch_initiator = The mobile looking in the room (mynum).
     - catch_arg       = -1

room_title
Failing this call will display nothing about the room, (save for the zonename and room number for wizards) except what was output in the catch. The mynum variable is guaranteed to be set in this event.
room_title sets the following variables before the call:
     - catch_location  = The room where the catch was triggered.
     - catch_initiator = The mobile looking in the room (mynum).
     - catch_arg       = -1

sit_down
Called, after sanity checks, on locations and locations only for catching sitting down in that location.
For catching the SIT ON <something> command, use the sit_on event instead.
sit_on sets the following variables before the call:
     - catch_initiator = The mobile sitting down (mynum).
     - catch_location  = The location in which the mobile sits down.

sit_on
Called on an object when a player tries to sit on this object after sanity checks are done. If you wish to output a different message to the standard ones the catch must output the new message, set the player to sitting (if that is what is wanted) and then fail.
sit_on sets the following variables before the call:
     - catch_initiator    = The player triggering the catch (mynum)
     - catch_target       = The object the catch belongs to
     - catch_location	  = The location where the catch takes place


List of catch functions

Catch functions are the core of a catch. These catch functions are used by the mud generator to create the compileable C-source code. When a catch is called the code generated from the catch functions that make up the catch are executed. It is possible to add conditional cases and to end a catch before it has exectuted all of the functions it contains.


Explanation of catch functions

add_obj_armor(obj, int)
add_obj_counter(obj, int)
add_obj_damage(obj, int)
These functions behave like their names suggest, adding the int value to the current value of armor,counter or damage. No restrictions are placed technically, though both armor and damage should be in range of 0 - 255, since they are unsigned chars. Note that to set one of these values to mynum, try code_line(osetcounter(OBJ...,mynum);),

add_score(score, mob)
This functions optionally takes a mobile argument, if it is left out then the score will be added to that of mynum. This will also cause mynum to save immediately, thus avoiding any losses.
  example:
    add_score(100),                <-- 100 to current players score
    add_score(100, Doctor@green),  <-- 100 to the doctor's score

awiz_message(<message>[, <variable>])
Sends a "system message" to archwizards and up only. The optional last variable argument is analogous to send_message().
See the string macro list in send_message() for a full list of accepted macros to be used in the message.

breakloop()
This function takes no arguments, but simply forces a loop to abort. The loop will terminate (ie not run any more cycles, even if it was not done) and the catch will continue running on the next line after the corresponding endloop.
See also loop_foreach(), loop_inventory(), loop_online_players(), endloop and nextloop().

clear_exit(Location, direction)
Removes the exit in <location> in <direction>.

clr_lflag(word, location)
Clears the specified location flag.

clr_quest(quest[, mobile][, message][, bonus])
Clears the specified quest. You can specify a message and a bonus to be recieved each time the quest is removed. The two last fields can be excluded. The bonus can be negative. Mobile is assumed to be mynum if nothing else is said in the second field.
See the string macro list in send_message() for a full list of accepted macros to be used in the message.

clr_oflag(word, obj)
Clears the specified object flag.

clr_mflag(word, mob)
clr_pflag(word, mob)
clr_sflag(word, mob)
clr_spell(word, mob)
Takes a single word as an argument and sets the approriate flag to False, either on mob, or on mynum if no mob is specified. These functions are logged. Also causes mynum to save. It should be noted that spells can not be set on mobiles and it makes little sense to set mflags on players.

code_line(C code)
This allows the coder to enter any line(s) of C code they wish. No checking at all is done to this until zone_catch.c is compiled, and it is left entirely to the user to ensure variables are valid etc. The generator will read until it finds a matching ')' character for the initial `(' character. Thus anything inside the `(' and `)' will be read and written as C code. The only limit on length is buffer sizes, and it is thus suggested that only a few lines at most is entered per catch call (better to use 1 line C code) and use more than one code_line command as it makes absolutely no difference to the final code and helps make sure buffer overflows don't stop the compile.

create_obj(obj[, <LOC, location>|<OBJ, object>|<MOB, mobile, carryflag>])
Brings a destroyed object into the game. If no second argument is given, it places the object in the room with the current player (mynum).
If a second argument is given, it specifies the type of location the object is sent to, a location, object or an mobile. The third argument is this location.
If the second argument is a mobile, you will have to also provide a carryflag.
No message is sent. It is not likely to care if the object is already in the game, it will still put it in the room with mynum, but it doesn't check that it hasn't taken it from someone else Checking is left up to you.
Examples:
   create_obj(pumpkin),
   create_obj(glamdring, loc, vitastjern@home),
   create_obj(sandwich, obj, sack),
   create_obj(mouse, mob, tuss@dflame, CARRIED_BY),
In the first example, the pumpkin object is created in the same location as the player that triggered the catch is in. In the second example the Glamdring is created in Vitastjern's home room. In the third example, a sandwich is created and placed inside the sack, please note that no checks are made for if it fits in there or if the sack is a container at all. In the fourth example, the mouse is placed in Tuss' inventory.

deathtrap(loc, msg_me, msg_room, msg_world, msg_loc, crap_msg)
This causes the DEATH of a player by death trap.
    loc       : Player is moved here to die. Optional
    msg_me    : The message sent to the player before death.
    msg_room  : Message sent to the room player is in when trap was triggered.
    msg_world : A message sent to the world (as in send_message(TO_WORLD, ))
    msg_loc   : What is sent to the room loc. (Nothing if NULL loc)
    crap_msg  : The crapup message. The one between the -=-=-=-= lines
Upon triggering this catch the messages msg_me, msg_world and msg_room are sent immediately. If a location [loc] was specified then the player will be moved to loc and the msg_loc sent there. If no loc is required, (ie you simply leave it out) then the player is not moved. However, the msg_loc will still be sent if it exists, it will just be sent to the same room as msg_room. This may be of little use but there is no point to restricting it.

If the player is moved, all items are carried with them. In either case everything the player carries will be dumped in their final location. The player will then be killed by death trap. This cost no points. The crap_msg is sent if given, else a standard one will be used.

     "Oh dear, you seem to be dead!"
Wizards are informed and the death logged as is standard with crapup. Note, any message you don't want to send, put NO_MSG or "" in it's place, but be SURE not to forget commas here.


See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

deathtrap_all_at(loc, lvl, msg_me, msg_room, msg_world, crap_msg)
The function deathtrap_all_at() is similar to deathtrap() but will kill everyone in the location below the level lvl.
    loc       : the location in which all players will now deathtrap
    lvl	      : only players below this level will be affected
    msg_me    : message given to each player when they are deathtrapped
    msg_room  : message sent to all players at the location except the
                deathtrapping player (once per DTer)
    msg_world : A message sent to the world (once per DTer)
    crap_msg  : The crapup message each player will get. The one between 
                the -=-=-=-= lines
In all above messages except crap_msg, %m can be used to denote the player that is currently deathtrapping.
See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

debug_message(<message>[, <variable>])
Sends a debug message to the debug eventlog. The optional last variable argument is analogous to send_message().
See the string macro list in send_message() for a full list of accepted macros to be used in the message.

destroy_obj(obj)
This function removes the object specified from the game. It doesn't tell anyone about it though. The default location for destroyed items is Destroyed@dead.

eat_obj(obj)
Same as destroy really, except the object is placed in Eaten@dead.

endloop
Marks the end of a loop, takes no arguments, and shouldn't be followed by a comma. This is the same to a loop as endif is to ifs.
See also loop_foreach(), loop_inventory(), loop_online_players(), breakloop() and nextloop().

exec_command([<mobile>,] string)
Makes the given mobile (or mynum if not supplied) execute the command given in the string, as if it had been typed by the player at the command prompt.
Note: This catch must be used with outmost caution!

fail()
This function is a directive, tells the mud that it should NOT do the command like normal after executing the special code.

find_object(object, str1, str2, state1, state2)
      object : The object you wish to find, (create) 
        str1 : Message the finder gets. ("" means no message)
        str2 : Message that the rest of the room gets.
      state1 : The new state of object, optional, may be left out. Also
               note that -1 means no state change.
      state2 : The new state of the object the catch is attached to. It MUST
               be an object if this is used. Optional, same as state1.
This function can be used to create an object, put it in room with mynum, and set states on objects involved as well as send messages to the room and mynum. No checks are made about the object, thats left to you.
Example:
  if (state(OBJ_ZONE_TABLE) == 1)
    find_object(bottle, "You find a bottle hidden on the table",
                        "%m finds a bottle on the table", -1, 0),
    fail(),
  endif;

See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

full_heal_me()
heal_me(str)
Full_heal_me() takes no arguments and will fully heal mynum.
The last case, of heal_me, also adds strength to mynum, but has no affect if mynum is a wizard, and will never heal beyond maximum. This CAN be used to kill if str is negative and large enough. No messages are sent.

give_obj_to_mob(obj, mob)
Performs a normal giving of the object to the mobile.

heal_mob([<mobile>, ]<amount>[, <max_value>[ <min_value>]])
Heals the given mobile (or mynum if no mobile is given) for the strength amount supplied, up to the maximum of max_value and at least up to mean_value. If max_value is left out, it defaults to -1 which then is interpreted as meaning the max strenght for the mobile.

hit_me(mob)
Causes the mob to hit the current player, if they are present.

hurt_mob([<mobile>, ]<amount>[, <min_value>])
Hurts the given mobile (or mynum if no mobile is given) for the strength amount supplied, down to the min_value, which defaults to -1 if not given. To prevent death by this call, set min_value to 0 or 1, for example.

if (condition)
elseif (condition)
The if construct allows you to set conditions on actions. This has a strict syntax, and failure to use it correctly will produce unknown results.
    if (condition)
      statements .....
    elseif (condition2)
      statements ....
    .....
    else
      statments ....
    endif
The condition part is infact simply a string. It is C code and will be copied as is. Any C function may be used here, but it is critical you match all the brackets, as it will continue to read until it finds a match for every bracket opened.

if_alive(mob)
This test to see if the mobile specified is alive. As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.
  Example:

  if_alive(figure)
     ......

  C code produced:

  if (alive(max_players+MOB_BLIZZARD_FIGURE) != -1)

if_carrying(<object>[, <mobile>][, DEEP_SEARCH])
Check if mynum is carrying the object obj. The optional mobile argument defaults to mynum and is the mobile that is tested for carrying the object. Only the top level of the inventory is checked, unless the DEEP_SEARCH optional argument is set.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_chance(int)
elseif_chance(int)
These provide a way to allow things to happen randomly. The chance is a percentage chance that the if will succeed, and it is calculated at run time, not at compile time. The elseif version is merely to allow the building of
if () ... else if () ... else ...
constructs as using else followed by if_chance would produce similar, but not the same code. This is planned to be changed in the future.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_comline_has(string, string, ...)
This compares the command line minus the verb with all of the strings you give, and succeeds if any of them match. The command is no longer case sensitive, that means that if_comline_has("coin", "gold") will match either `drop Coins' or `drop coins'

As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.
Remark: You must use lowercase in the string or the catch won't work.

if_counter(object, int)
if_counter_greater(object, value)
if_counter_is_me(object) if_counter_less(object, value)
The function if_counter() will return true if the object's counter equals int while if_counter_greater() and if_counter_less() will test if the value is greater or lesser than the given value, instead of it's equal.
If_counter_is_me() works like if_counter(), but checks if the object counter contains mynum.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_fighting([<mobile>][, <mobile>[, ...]])
Checks if the mobile (defaults to mynum if not given) is currently in a fight. If more than one mobile is given, the second mobile and up represents a list of opponents. If the mobile is any of the opponents in the list (or the list is empty), the check is true.

if_has_flag_obj([CHECK_ROOM, ] <oflag> [, DEEP_SEARCH][, <mobile>])
Check if the mobile (or mynum if no mobile is given) is carrying an object that has the given oflag set on it. If the CHECK_ROOM constant is given, the room is also checked (useful for oflag Lit, for example). If the DEEP_SEARCH constant is given, containers carried by the mobile will be recursively searched for such objects, if none is found in the mobile's top level inventory.

if_here_alive(mob1[, mob2])
Combines the effects of if_mob_here(mob1) and if_alive(mob1) since they are used so often together. The second optional argument (mob2) defaults to mynum and is used to determine at which location "here" is.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_in_deathroom([OR_DESTROYED, ]<object>)
Checks if the object, or a container containing the object, is in a deathroom. This explicitly excludes limbo@limbo. If the optional first parameter is given, the check will be for if the object is in a deathroom or is destroyed.

if_in_room(<location>[, <mobile>])
Tests if the mobile (or mynum if no mobile is given) is in the given location.

if_in_room_list(<mobile>, <location>[, <location> ...])
Tests if the mobile (or mynum if no mobile is given) is in any of the listed locations.

if_in_zone(<zone>[, <mobile>])
Tests if the mobile (or mynum if no mobile is given) is in the given zone.

if_is_mobile(variable)
if_is_player(variable)
Determines if the mobile stored in the variable is a mobile or a player. As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_is_mortal([<mobile>])
Checks if the mobile (defaults to mynum if not given) is a mortal.

if_level([mobile,] level)
if_level_less([mobile,] level)
if_level_greater([mobile,] level)
These functions are used to test someone's level. if_level_less and if_level_greater will return true in case the level is less (or greater) than the level provided. Mynum is assumed if no mobile (player) is given.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.
Al mobiles have level -1.
Some valid constants are:
      Constant name    Comment
      -------------    -------
      LVL_GUEST
      LVL_NOVICE
      LVL_ADVENTURE
      LVL_HERO
      LVL_WARRIOR
      LVL_CHAMPION
      LVL_KNIGHT
      LVL_CONJURER
      LVL_MAGICIAN
      LVL_ENCHANTER
      LVL_SORCERER
      LVL_MAGE
      LVL_LEGEND
      LVL_LORD
      LVL_WIZARD        Use this constant with if_level_less to signify
                        all mortal levels.

if_me_name(player)
Checks if mynum is named as the given argument. Capital letters does not affect the comparison.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_mob_here(mob)
if_obj_here(obj)
Test to see if a mobile or object is in the same location as mynum. Will not check for objects in the inventory.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_killed_by_me(mob)
Is true if the mobile is dead and the mobile's score is mynum, indicating that mynum killed the mobile.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_obj_at(object, LOC|MOB|OBJ, location|mobile|object[, carryflag])
Checks if the object is in the specified place. A carryflag may be supplied only if the place was a mobile, and is then used to check that the object has the correct carryflags too.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_obj_is(word)
This is also a form of if statement, except that it's argument is a single word. The "if" will succeed if either of the objects on the command line have names or altnames that contain the word given.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.
 Example: 

   Catch = give;
           if_obj_is(coin),
             send_message(TO_MYNUM, "The beggar thanks you for the money."),
           endif,
           succeed();
If this catch was attached to the mobile, beggar, then anyone giving an object with the name "coin" or "coins" etc to him, would get the message.

if_player_in_room(<location>[, MOB|OBJ|VAR, <mobile>|<object>|<variable>])
With one argument only, checks if there are any mortals in the specified location. With an additional argument, checks if the player with a certain player id is in the location. If the argument is a mobile, the score is checked for the player id. If the argument is an object, the counter is checked. If the argument is a variable, it should contain the player id.
Note: if_player_in_room() is solely intended for use within the quest_info catches.
See also if_player_in_room_list() and, if you wish to check for mortals inside an entire zone, if_player_in_zone().

if_player_in_room_list([MOB|OBJ|VAR, <entity or variable>, ]<location>[, ...])
Same as if_player_in_room(), but has the location last instead of first, and can take a list of locations, not just one.
Note: if_player_in_room_list() is solely intended for use within the quest_info catches.

if_player_in_zone(<zone>[, MOB|OBJ|VAR, <mobile>|<object>|<variable>])
With one argument only, checks if there are any mortals in the zone. With an additional argument, checks if the player with a certain player id is in the zone. If the argument is a mobile, the score is checked for the player id. If the argument is an object, the counter is checked. If the argument is a variable, it should contain the player id.
Note: if_player_in_zone() is solely intended for use within the quest_info catches.
See if_player_in_room() if you wish to check for mortals in a specified location and not an entire zone.

if_quest_completed(<quest>[, <mobile>])
Checks if the given quest has been completed this reset. If a mobile is given too, it instead checks if the mobile has completed the quest (ever).

if_quest_is(<quest>)
This call is only for use in the quest_info catches.
It simply checks if the call to the quest_info catch is for the given quest or not.

if_sitting([<mobile>])
if_sleeping([<mobile>])
if_standing([<mobile>])
Tests if the mobile (or mynum if no mobile is given) is standing, sitting or sleeping, respectively.

if_state(obj, int)
Used to test the object's state value. If_state will return true if the object's state is int.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_tst_attribute(flag, object)
Similar to the other if_tst commands except it works on objects and their attribute flags. As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.


NOTE: All if's must be terminated with an endif.

if_tst_lflag(<flag>, <location>)
Tests if the given lflag is set on the specified location.

if_tst_mflag(flag, mob)
if_tst_pflag(flag, mob)
if_tst_sflag(flag, mob)
These functions must be given a valid flag of the appropriate kind. The mob is optional. If no mob is specified, the flag will be set upon 'mynum' (The player currently doing a command) and in this case, the action will be logged by the mud. As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_tst_oflag(flag, object)
Similar to the other if_tst commands except it works on objects and their flags. As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.


NOTE: All if's must be terminated with an endif.

if_tst_spell(spell)
Similar to the conditionals for flags, except these can only be tested on mynum. As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_using_obj(obj)
Checks if mynum is using the object that is given as an argument to the call. What using entails is "wielding" for weapons, "wearing" for armor/rings/etc, and both wielding and wearing for things that are both, etc.
As with all if_* constructs, the [else]if_[not_]* constructs are valid when building the statements.

if_var_equals(<variable>, <type>, <value>)
if_var_greater(<variable>, <type>, <value>)
if_var_less(<variable>, <type>, <value>)
This is an attempt to finally get to avoid the need of the generic if() almost completely and to get some type checking and such in there. This will test a catch variable against the given value. <value> is a value of the type <type>, and <type> is the literal name of the type you want to test against. Possible types are: location, object, mobile, integer, variable, player, direction and code.
Examples:
     if_var_greater(CATCH_TMP, integer, 3),
     if_not_var_equals(CATCH_CHAIN_START, variable, CATCH_THIS),
     if_var_equals(CATCH_TARGET, mobile, Puff),
     if_var_equals(CATCH_ARG, direction, East),

The code type allows comparison with with anything that will make the comparison legal code. This is to remove some use of code_line() and should be used as little as possible, eg really only when you would have to use code_line() to avoid it. See also set_var().

jump_to(loc)
Used to invoke jumping, like so:
     catch = jump;
       jump_to(far_below),
       fail();
The location can in this call be replaced with ?(loc, loc, loc, ...) in which case a random location will be chosen out of the given ones each time the call is made.
       jump_to(?(far_below, further_away, the_hole)),
will randomly pick one of the locations far_below, further_away or the_hole.

log_message(<message>[, <variable>])
Sends a log message to the mudlog. The optional last variable argument is analogous to send_message().
See the string macro list in send_message() for a full list of accepted macros to be used in the message.

loop_foreach(<variable or name_of_temp>, LOC|MOB|OBJ, <entity> [, <entity> ...])
Loop over the list of entities, putting them into the given variable and running the code in the loop, then putting the next entity in there, etc. One by one the list is looped through.
If you don't give a catch variable you can instead give a name of a real C variable to create and use for the loop. This is less useful, since you can't access it in most normal catch functions, but if you can't use catch variables for some reason you can use this and at some point move it to catch variables with code_line() or such.
A loop must always be ended with an endloop. See also nextloop() and breakloop().

loop_inventory(<variable or name_of_temp> [, LOC|MOB|OBJ, <entity>])
Loop over the inventory of the location/mobile/object given (or mynum's inventory if not given), putting them into the given variable and running the code in the loop, once per object in the inventory. See loop_foreach() for more details on looping in general.
A loop must always be ended with an endloop. See also nextloop() and breakloop().

loop_online_players(<variable or name_of_temp>)
Loop over the players that are online, putting each player into the given variable and running the code in the loop for each of them. See loop_foreach() for more details on looping in general.
A loop must always be ended with an endloop. See also nextloop() and breakloop().

me_to_mob(mob[, {leave_msg|NO_MSG}[, {entry_msg|NO_MSG}]])
Moves the current player (mynum) to the specified mobile. It also sends the messages <name> has left. and <name> has arrived. to the locations involved. The two last arguments are optional. The arguments consist of the strings that are to be sent to the location the player left and the location the player arrives in. NO_MSG can be used to prevent a message to be sent at all. Not supplying the strings will default them to the original "%m has left." and "%m has arrived." strings.
See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

me_to_room(location[, {leave_msg|NO_MSG}[, {entry_msg|NO_MSG}]])
Moves mynum to the room thats is specified in the same way as me_to_mob. The two last arguments are optional. The arguments consist of the strings that are to be sent to the location the player left and the location the player arrives in. NO_MSG can be used to prevent a message to be sent at all. Not supplying the strings will default them to the original "%m has left." and "%m has arrived." strings.
See the string macro list in send_message() for a full list of accepted macros to be used in the messages.
The location can in this call be replaced with ?(loc, loc, loc, ...) in which case a random location will be chosen out of the given ones each time the call is made.

mob_to_me(mob)
Does the opposite of me_to_mob and moves the mobile to mynum. NO messages are sent in this case.

mob_to_room(loc, mob)
Moves mob to loc, and does not send any messages indicating this has happened.
The location can be selected randomly by replacing the location with a ?() construct, like in the jump_to() function.

nextloop()
This function takes no arguments, but simply forces a loop to stop the current cycle and start with the next one straight away.
See also loop_foreach(), loop_inventory(), loop_online_players(), endloop and breakloop().

obj_to_any(object, LOC|MOB|OBJ, location|mobile|object, carryflag)
Place the object in the specified destination, using the given carryflag.

put_obj_mob(obj, [mob[, CARRYFLAG]])
put_obj_obj(obj, obj)
put_obj_room(obj, loc)
These functions set the location of an object with no messages sent. put_obj_obj() is used to put the first object in the second, and put_obj_room places the object in the room. It makes no considerations of where the object was or any other side effects of moving the object, such as those that can occur by moving a door.
In put_obj_mob, the mobile is optional and defaults to mynum. The optional CARRYFLAG in put_obj_mob allows you to specify how the object is carried by the mobile. Valid carry flags for the catch are WIELDED_BY, BOTH_BY, WORN_BY and the default CARRIED_BY, which is automatically set if no carry flag has been provided. Explanations of the carry flags can be found in the zone building manual.
The location in put_obj_room() can be selected randomly by replacing the location with a ?() construct, like in the jump_to() function.

quest_info_return(<quest_return_const> [, MOB|OBJ|VAR, <mobile>|<object>|<variable>])
This call is only for use in quest_info event catches. This call will fail() and return the constant to indicate the quest state. The optional argument is for returning a player id of the player that put the quest in the state (ie who completed it). If the optional argument is a mobile, the killer of the mobile is returned. If it's an object, the counter is returned. If it's a variable, the value of the variable is returned.
The available quest state constants are:
  QUEST_UNAVAILABLE, QUEST_PRISTINE, QUEST_NOT_STARTED,
  QUEST_IN_PROGRESS, QUEST_COMMITTED, QUEST_COMPLETED,
  QUEST_RUINED

quit_mob(mob)
Causes a mobile to leave the game. The mobile is NOT optional here as you can not cause aplayer to leave via this method. All that is carried by the mob, will be dropped in the room first and no message will be sent, leaving the choice of message to the coder.
 Note:
  This is equivalent to

      dumpstuff(mob, ploc(mob));
      strcpy(pname(mob), "");

   Exactly what happens with the MFL_QFOOD flag.

random_dir_exit(loc, exit)
Randomly selects an direction to assign <exit> to. Exits may be either locations or objects (linked) preceeded by the '^' character.

random_exit(loc, dir, exit_list)
This randomly selects an exit from the exit list and sets the exit in direction <dir> to it. The exit_list is just a comma seperated list of exits, which may either be locations or objects. If the exit is an object it should be preceeded by the '^' character.

NOTE: Exit info is not reset to it's original state at reset time.

random_state(obj, val)
Set the objects state to a random value from 0 to val. DO NOT use 0 as the val argument.

random_messages([<mob>, ]<chance>, [ <flags>, ][<mob2>,]<msg>[, <msg> ...])
random_message_me([<mob>, ]<chance>, [ <flags>, ][<mob2>,]<msg>[, <msg> ...])
random_messages_to([<mob>, ]<chance>, [ <flags>, ][<mob2>,] <loc>, <msg>[, <msg> ...])
random_says([<mob>, ]<chance>, [ <flags>, ]<mob2>, <msg>[, <msg> ...])
random_says_to([<mob>, ]<chance>, [ <flags>, ]<mob2>, <loc>, <msg>[, <msg> ...])
random_tells([<mob>, ]<chance>, [ <flags>, ]<mob2>, <msg>[, <msg> ...])
random_tells_to([<mob>, ]<chance>, [ <flags>, ]<mob2>, <loc>, <msg> [,<msg> ...])
Explanation of parameters:
     mob         - a mobile to use with the %m etc in the msg messages, 
                   thus being where the my/you/your/etc messages go.
		   Mob is optional and will default to mynum if left out. 
		   Its main use is for calls when mynum is unknown.
		   Mob, if given, will act as mynum in all regards during 
		   this function call, so any reference to mynum in this 
		   function description can be read as "mob if given, 
		   otherwise mynum".
     chance      - the percentage chance that the call will do anything at all.
                   A value of 100 will cause the message to be sent every tick
		   which is useful for testing purposes, but not very nice
		   at other times.
     flags       - optional argument to allow for the message not being sent
                   to blind or deaf people. Use NOT_DEAF, NOT_BLIND, 
		   NOT_DEAF_OR_BLIND as parameters. As a default, all *_says*
		   and random_tells* catches automatically set the NOT_DEAF 
		   value, while the others all set the value to 0 which means 
		   that the message is sent to everyone.
     mob2        - the actor in the spec_strings.
                   Mob2 is mandatory in the random_says* and random_tells* 
		   functions, and optional in all the random_message* 
		   functions, as long as %a or %<> is never used in 
		   the spec_strings.
     loc         - A location to send the messages to. Loc is non optional in
                   the calls that accept it. Use CATCH_LOC_MYNUM if you wish
		   to use the location that mynum is in.
     msg         - A string formatted after the rules given below. It is
                   optional to use more than one string and in that case
		   one string will be picked randomly out of all the
		   spec_strings.	     
random_tells() will only send the messages to mynum if mynum is set. Otherwise the message will be sent to everyone in the location where the catch was executed.
random_tells_to() will send the tell to everyone in the location given.
random_message_me() is the same as all the other random_message* functions, but sends a message only to mynum.
random_messages_to() and random_says_to() are the same as their counterparts without the "_to", but they will always send to the supplied location, and also to mynum if mynum is set, even if mynum isn't in that room.

The spec_strings are normal strings that can contain the special sequences started with a percent character that allows for making one message fit everyone in the room. Here's a list of sequences and what they are translated to:

     %i - is/are -- short for %(is:%:are)
     %y - adds "ies" for everyone, but "y" for mynum -- short for %(ies:%:y)
     %z - adds "s" for everyone but mynum -- short for %(s:%:) (eg %m move%z)
     %( - msg1 for others, msg2 for others that can't see mynum because of
          invisibility, msg3 for mynum, ie %(msg1:msg2:msg3).
	  msg2 and msg3 can be just a %, which will make them the same as
	  msg1. 
     %s - start the color for say (use instead of a color code).
          Note that all colors are automatically turned off at the end of 
	  a line, so if the say contains a newline, you need to add another 
	  %s at the first position of the next line of text.
	  Turn off color with &*. For more colors, please see INFO COLOR
	  from within the game.
     %B - add a beep/bell to the message. Use with caution since it tend
          to be annoying.
     %p - pname(mynum)'(e)s, or "your" for mynum. This macro will
          automatically capitalize the first letter after punctuation.
	  Accepted punctuation is ".", "?" or "!", or the beginning
	  of the string.
     %m - pname(mynum), or "you" for mynum. This macro will
          automatically capitalize the first letter after punctuation
	  as in %p.
     %M - pname(mynum) for everyone, including mynum and people that can't
          see mynum because of invisibility
     %a - pname(actor), ie the name of the supplied mob
     %P - message depending on mynum's gender -- short for %[his:her:your]
     %h - message depending on mynum's gender -- short for %[he:she:you]
     %[ - message depending on mynum's gender, including a message to mynum.
          The messages are delimitred with a ":"; male:female:to_mynum
	  ie %[message if mynum is male:message if mynum is female:
	       message to mynum him/herself]
     %{ - message depending on mynum's gender, no special message to mynum.
          The messages are delimitred with a ":"; male:female
	  ie %{message if mynum is male:message if mynum is female}
     %< - message depending on actor's gender
          ie %<message if actor is male:message if actor is female>
     %% - a literal percent character
     \n - used to signify a newline. Note that all color codes are ended at
          a newline so if you wish the color code to continue across the
	  newline you need to start the next line with the same color code.
Example:
     random_messages(100, mayor, "%a looks at %m, points at %p arm "
	            "and says '%s%M, you have\n%sthe sacred "
		    "mark!&*'\n%a raises %<his:her> staff and "
		    "turns to the crowd, ignoring the surprised\n"
		    "expression on %[the marked man's:the marked "
		    "woman's:your] face, and continues '%sLook "
		    "at %{his:her} arm!&*'");
Assuming that the player is female, called Leeloo and the mayor is male and called The Mayor, the resulting messages to the player will look like this:
   The Mayor looks at you, points at your arm and says 'Leeloo, you have
   the sacred mark!'
   The Mayor raises his staff and turns to the crowd, ignoring the surprised
   expression on your face, and continues 'Look at her arm!'
The resulting message to everyone else will be:
   The Mayor looks at Leeloo, points at her arm and says 'Leeloo, you have
   the sacred mark!'
   The Mayor raises his staff and turns to the crowd, ignoring the surprised
   expression on the marked woman's face, and continues 'Look at her arm!'
Example:
     random_messages(100, NOT_BLIND, "%m %i pulled back by a rope as "
                    "%h tr%y to reach %P %(horse:%:old faithful horse).");
Assuming that the player is male, called Kalzar, and isn't blind, mynum will see:
   You are pulled back by a rope as you try to reach your old faithful horse.
Everyone else will see:
   Kalzar is pulled back by a rope as he tries to reach his horse.
Example:
     random_messages(20, "%B%m suddenly fart%z very loudly"
                    "%( and blushes:: and start to blush).");
Assuming that the player is male, called Kalzar, mynum hear a beep and will see:
   You suddenly fart very loudly and start to blush.
Everyone else will hear the beep and then see:
   Kalzar suddenly farts very loudly and blushes.
Should Kalzar be invisible the result would instead be a beep followed by:
   Someone suddenly farts very loudly.

replace_obj(<old_object>, <new_object>)
Replaces the first object with the second one. The new one is created and placed in the same place and with the same carryflags as the old one (carried, wielded, in a room etc) and the old one is then destroyed.

resetme()
Will reset the object, mobile or location that the catch is bound to.

send_item_player( player_name, [obj | mob] , item_name, [carry flag], "message to original room", "message to player", "message to destination room")
Either an object or a mobile can be sent, if n object is sent, then an optional carry flag can be specified. Only IN_CONTAINER is not valid. If the messages are not required then use NO_MSG. Note that messages might give away you being invisible, as no checking will be done.

Important: Do not use the "message to destination room" if the catch is to be triggered by on_reset. Use NO_MSG then instead.

Example usage:

     Catch      = on_reset;
       send_item_player(Ithor, obj, Ithring, WORN_BY,
                        "The ring fades slowly out of existance.",
                        "Your wedding ring appears on your finger.",
                        NO_MSG);

See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

send_message_bd(dest, "string") Not to deaf/blind people
send_message_d(dest, "string") To blind but not deaf people
send_message_b(dest, "string") To deaf but not blind people
send_message(dest, "string") To everyone
This function sends the message string to the dest(ination). The exact meaning of this depends on what destination is chosen. Below is an explanation of destinations and also an explanation of macro sequences that can be used in the message string.

Valid destinations

TO_ALL
To everyone logged in without exception. Used only in very special cases since global messages should be used with caution.

TO_HELPER
To the player/mobile currently helping mynum, if any.

TO_HERE
Combines TO_MYNUM and TO_ROOM for the cases when you want mynum and the people in the same location as mynum to recieve the same message.

TO_ME
This sends the message to the mobile whose catch is being executed. Makes no sense with location or object catches.

TO_MOB
This will, like TO_MLOC (se below), take a mobile as a second argument. This will send the message, not to the location as in TO_MLOC, but to the mobile itself. The biggest use for this function is to send messages to a specific player, whos number is stored in one of the CATCH_* variables, when the player is not mynum. The corresponding TO_ROOM equivalent for that case is TO_MLOC, which does not send a message to the player/mobile, but only to the room.

TO_MYNUM
To the player/mobile doing the current command.

TO_OUTSIDE
To all outdoor rooms that aren't soundproof. Not to mynum.

TO_ROOM
To everybody in the room with the player mynum, but NOT to mynum.

TO_WORLD
To everyone not in a soundproof room. Not mynum though.

When one of the following destinations are given, send_message functions will expect to find an additional argument immediately following this one. This argument will be a location, mobile or object as appropriate.
TO_LOC
Sends a message to the specified room. Use send_message(TO_LOC, location, "string") to use this argument.

TO_MLOC
Send the message to the room that contains the mobile. Use send_message(TO_MLOC, mobile, "string") to use this argument. The message will NOT be sent to the mobile.

TO_OLOC
To the room that contains the object. Note however, if the object is not in a room, then no message will be sent. Use send_message(TO_OLOC, object, "string") to use this argument.

TO_AOLOC
To the "absolute location" room of the object. That is, always the room where the object is, or the object where the container of the object is, and so on outwards until a room is found. Use send_message(TO_ALOC, object, "string") to use this argument.

It is important to realise with all of these that no consideration is given to the visibility of mynum, or the object/mobile in question, and the messages will be sent to all in the location, mynum included.

Macros useable in the string

    %m  Translated to mynum's name.
    %c  Translates to the name of the thing the catch belongs to.
    %v  Translates to the name of an object stored in a supplied catch
        variable (argument).
    %V  Translates to the name of a mobile stored in a supplied catch variable
        (argument).
    %l  Translates to the location title (eg Forest Track).
    %L  Translates to the location "wizname" (eg valley24).
    %C  The name of the catch trigger chain starter (same as %c unless a
        trigger_* call has been used to trigger another catch from a catch).
    %s  Let everything after the %s be in the same color as the say color.
    %{str1:str2}   Selects str1 if mynum is male, and str2 if mynum
                   is female.
    %<str1:str2>   Selects str1 if the mobile the catch belongs to 
                   is male, and str2 if the mobile is female.
    %B  Add a beep to the string.  Use with caution.
    %d  north/south/east/west/down/up as specified by the direction stored in
                    a variable
    %D  the north/the south/the east/the west/below/above as specified by a
                    variable
    %i  the given number as digits (eg 5)
    %I  the given number as text if it is between 0 and 20. Otherwise the
                    number as digits. (eg two/eleven/34)
    %j  the given object's counter as digits (eg 5)
    %J  the given object's counter as text (is to %j what %I is to %i).
Please take note that some of the macros have been changed to harmonize with random_messages().

Examples:

     send_message(TO_MYNUM, "The %v is a very normal %v.", CATCH_ARG),
     send_message(TO_MOB, CATCH_INITIATOR, "%V is mobile %I.", CATCH_TARGET),
     send_message(TO_HERE, "The guard shouts '%m! Come back here!'"),
     send_message(
     send_message(TO_MLOC, Puff, "Puff hickups."),
     send_message(TO_WORLD, "The world counter %v is not at %j.", CATCH_ARG),
Note: You may only use one variable (CATCH_ARG and CATCH_TARGET in the examples above) in each send_message, however this variable can be used by one or several macros to display different info belonging to the variable, as in some of the examples above.

set_counter_to_me(obj)
Set the counter of the object to the player_id of mynum.

set_exit(loc1, dir, exit)
Sets the exit in direction <dir> in room <loc1> to <exit>. <exit> may be either another location, or a linked object. (It does not strictly have to be linked, but generate will warn about it, and the mud may crash, so DONT use non-linked objects) if an exit is an object, then it must be preceeded by the '^' character

NOTE: Exit info is not reset to it's original state at reset time.

set_mob_strength(<mob, >str)
Sets the mobile's strength to the value of str. The mobile is optional and defaults to mynum. No messages are sent.
Note: str may be negative, which means that this can be used to kill.

set_obj_*(<obj>, <int>|<var>)
All the set_obj functions set certain integer values on objects. Normal game restrictions still apply, like state between 0 and 3, or armor from 0 to 255.
You may use a variable instead of a pure integer as the parameter to set a value on the object.

set_lflag(word, location)
Sets the desired location flag in the desired location.

set_oflag(word, obj)
Sets the desired flag on the specified object. Checks are made for both arguments validity.

set_percent_strength(percentage, mob)
Set strength to a percentage of the current strength. If the resulting strength is larger than maxstrength, maxstrength is used. The second argument is optional and defaults to mynum if unused.

set_quest(quest[, mobile][, message][, bonus])
Set a quest flag on mynum. You can specify a message and a bonus to be recieved each time the quest is solved. The three last fields can be excluded. Mobile is assumed to be mynum if nothing else is said in the second field.
See the string macro list in send_message() for a full list of accepted macros to be used in the message.

set_mflag(word, mob)
set_pflag(word, mob)
set_spell(word, mob)
set_sflag(word, mob)
Set the appropriate spell or flag on the specified mobile. If no mobile is given, then the player known as mynum is used. Note this is logged by the game. NOTE that spells are for players and mflags for mobiles only.

set_sitting([<mobile>,] [<mob_msg>], [<room_msg>])
set_sleeping([<mobile>,] [<mob_msg>], [<room_msg>])
Sets the mobile (or mynum if no mobile is given) as sitting or sleeping, respectively. Optionally sends messages, if given, and not NO_MSG, to the mobile and/or room.
See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

set_standing([<mobile>,] [<mob_msg>], [<room_msg>])
Sets the mobile (or mynum if no mobile is given) as not sitting and not sleeping, ie standing. Optionally sends messages, if given and not NO_MSG, to the mobile and/or the room.
See the string macro list in send_message() for a full list of accepted macros to be used in the messages.

set_title(string[, player])
This will set a title on either mynum or player if a player is given. This means that the catch can be used even when mynum is unknown, however you should not attempt to set mobile titles. The catch will fail if given an empty string.
Note that you can include a single %s for mynum's name, but no checking will be done for validity.
Note also that it is preferred to use title_override() instead of set_title in most cases, since set_title destroys the player's original title.

set_var(<variable>, <type>, <value>)
Sets the variable to a value of type <type>. <value> is a value of the type <type>, and <type> is the literal name of the type you want to test against. Possible types are: location, object, mobile, integer, variable, player, direction and code.
The code type makes it possible to set from anything that will make the comparison legal code. This is to remove some use of code_line() and should be used as little as possible, eg really only when you would have to resort to the use of code_line() to avoid it. See also if_var_*().

set_var_rnd_entity(<variable>, <type>, <value>[, <value> ...])
Sets the variable to a value of type <type>, selected at random from the given <value> entries. Possible types are: location, object, mobile.
Example:
   set_var_rnd_entity(CATCH_TMP, mobile, Helios@island, Puff@start),

set_var_rnd_range(<variable>, <start>, <stop>)
Sets the variable to a random value between <start> and <stop>, inclusive. <start> and <stop> are two integers, and <stop> is greater than <start>.

show_loc_examine(loc[, ALWAYS_LONG][, mob])
Shows the (always long, even when the player has BRIEF on, if the ALWAYS_LONG argument is given) location description for the given location to the given mobile, or mynum if mobile is not given.
See also the show_me_loc_descr() catch and the room_descr event.

show_me_loc_descr(<location>)
This is a call expecially designed for use with the room_descr event, and will display only the text of the room description to mynum, nothing more (unlike show_loc_examine() catch, which will do a complete look in the room, listing room title, flags for wizards, description, objects and mobiles in the room, etc).

show_obj_examine(object, SHOW_OTHERS)
Shows the examine text of an object. Useful if you wish to display the examine text without having to break the catch with succeed().
SHOW_OTHERS is an optional argument and used if you wish to have the normal "<name> carefully inspects the <object>" text given to everyone but mynum in the location. Invisibility is handled automatically.

shuffle_exits(loc, exit_list)
This is similar to random_exit, except that it shuffles the exits in all directions.

silent_to_mob(mob1[, mob2])
This moves either a mobile to the same room as another mobile. Note that it moves mob2 to the room that mob1 is in. If mob2 isn't soecified then mynum will be assumed to be the victim. It is totally silent, no one will see the mob/mynum move including mynum.

silent_to_obj(obj[, mob])
Move the mobile (or mynum if mobile is not set) to the location where obj is. The location will always be the "outer location", so it's safe to use without checking where the object is. That is, if obj is in a container carried by a player standing in a location then this is the location that mob/mynum will be transported to.

silent_to_room(loc[, mob])
Like silent_to_mob, this function moves either mob or mynum to the specified room with out any message at all. Again leaving out mob will cause mynum to be the victim. It is preferred to use me_to_room() with two NO_MSG arguments to the use of this function. The difference between the two calls is that this one will not give the player a "look" in the room they go to, while me_to_room() will. Only use this function if you want to get rid of that effect in me_to_room().
The location can be selected randomly by replacing the location with a ?() construct, like in the jump_to() function.

succeed()
Direct the mud to execute the command as normal.

title_override(string[, player])
Set an override title that will show instead of the player's title until the next reset or the player logs out or deathtrap, etc. If no player is given, mynum is assumed. Use %s in the string to specify the player name. Do not attempt to change mobile titles with this catch.
See also set_title()

trigger_o_catch(obj)
trigger_m_catch(mob)
trigger_l_catch(loc)
These allow the catch coder to force other catches to get triggered with the same verb. It also means that if the result of a catch was unsatifactory, you can retrigger. WARNING: this can cause infinite loops if you are not careful. This can be harmful to the health of the mud.

trigger_o_my_event(obj)
trigger_l_my_event(loc)
Trigger the catchable event my_event at the given location/object, allowing certain conditions in many parts of a zone or the MUD to call on a single catch that have no other function than being called.

return_trigger()
return_trigger() will just return the result of the last trigger call to it's parent, or to the mud if it was the original.

wiz_message(<message>[, <variable>])
Sends a "system message" to wizards (ie a yellow bracket enclosed message) that only reaches the wizards that do not have QUIET on. The optional last variable argument is analogous to send_message().
See the string macro list in send_message() for a full list of accepted macros to be used in the messages.


Last edited March 31, 2006

aber@ludd.ltu.se