This file is my puny attempt to make some kind of documentation for the
trigger system.  Documentation for the Lua language is not included here.

==========================================================================
Different kind of triggers.

This version have three kinds of triggers: Time, Enter and Leave triggers.
Time triggers are triggers that call a script every ten second.
Enter triggers call a script every time a character enter a room,
while Leave triggers call a script when characters leave a room.

There can be any number of triggers for each room/mobile/object.


All <script to call> fields below has a common format:

   <file>:<function>

   File is the filename of the script.
   Function is the function to call.

==========================================================================
Triggers in rooms:

All rooms in the world files now hav a new field (like the door and
extra description fields), called a Trigger field.  Trigger fields
have the following syntax:

T
<trigger> <script to call>


   =======================================================================
   Trigger can be one of the following:

   1   TIME   The script is called every ten second.
   2   ENTER  Call the script when a character enters the room.
   3   LEAVE  Call the script when a character leaves the room.

==========================================================================
Triggers on objects:

Defining a trigger for an object is virtualy the same as for rooms.
The only difference is when some of the triggers are called.
Format of the trigger field:

T
<trigger> <script to call>

   =======================================================================
   Trigger can be one of the following:

   1   TIME   The script is called every ten second.
   2   ENTER  Call the script when a character enters the room the object
              is lying in.  It will not be triggered if the object is in
              a characters inventory or when it is equiped.
   3   LEAVE  Call the script when a character leaves the room the object
              is lying in.  It will not be triggered if the object is in
              a characters inventory or when it is equiped.

==========================================================================
Triggers on mobiles:

Triggers can only be set on E-type mobiles.
The following new keywords are defined:

   TimeTrigger
      Format: TimeTrigger <script to call>
      This script is called every ten second.

   EnterTrigger
      Format: EnterTrigger <script to call>
      The script is called every time a character enters the room
      the mobile is in.

   LeaveTrigger
      Format: LeaveTrigger <script to call>
      The script is called every time a character leaves the room
      the mobile is in.

==========================================================================
Calling sequence of trigger scripts:

Time triggers are called as this:

   function time_trigger_function(me)
      userdata me

   Me is the room/mobile/object the trigger is set on.
	 All returnvalues are discarded.

Enter and Leave triggers are called as this:

   function enter_or_leave_trigger_function(me, ch)
      userdata me
      userdata ch

   Me is the room/mobile/object the trigger is set on.
   Ch is the character that entered/leaved the room.
   The function must return either the number 1 or the number 0.
   If it returns 1, ch is alloed to enter/leave, if it returns
   0 ch can not enter/leave the room.

==========================================================================
Mud specific functions callable from Lua:

Data types in lua:
   number   -- A floating point number.
   string   -- A string.
   userdata -- Some mud specific data.

   =======================================================================
   number(from, to)
      number from, to
      Returns an integer in the range [from...to].

   dice(num, sides)
      number num, sides
      Returns a diceroll with num dices, all of them have sides sides.

   say(str)
      string str
      This function can only be called by scripts set on mobiles.
      It lets the mobile "say" something.

   isroom(what)
   isobject(what)
   ischar(what)
   isplayer(what)
   isnpc(what)
      userdata what
      Theese functions returns true if what is a room/object/...

   tell(who, str)
      userdata|string who
      string str
      Tell who something.  Who can be either a string (in which case it is
      the name of the player to tell) or a userdata field.  Str is the
      string to tell who.

   ask(who, str)
      userdata|string who
      string str
      Like tell(), but ask who instead.

   whisper(who, str)
      userdata|string who
      string str
      Like tell() and ask(), buth whisper str to who instead.

   get_name(who)
      userdata who
      If who is a player, return the players name.  If who is a mobile
      or an object, return the first name of the mobiles/objects alias
      list.

   get_short(who)
      userdata who
      If who is a player, return the name of that player.  If who is a
      mobile or an object, return the short description of that mobile
      or object.

   cap(str)
      string str
      Returns str capitalized.

==========================================================================
