------------------------------------------------------------------------------
Title......: Mumps Scripting Tips / Howto / FAQ
Author.....: Axel
Started....: 2004-Sep-22
Last Change: 2004-Oct-07
------------------------------------------------------------------------------

!!! Let me know, if you got ideas what else to put into this file !!!



-> "sending an echo to a room"

   $$send^%room() or room^%act() ?

   If you want to send a message, which was not initiated by a character,
   then it is ok to use $$send^%room(). In _ALL_ other cases use room^%act().
   Why? Because the character might be invisible to some in the room (for
   instance sneaking). The ..^%act() functions make sure that such cases are
   handled correctly.
 



-> "simple (command) parsing"

   Any combination of the functions below is very useful, when adding
   script-based commands, which for instance trigger on the 'cmderr' event.


   1) $$abbrev^util(cmd,full,len)

        Returns 1, if <cmd> an abbreviation of <full>, else 0   
        <len> defines the minimum number of nescessary matching chars        

        Examples: 
          $$abbrev^util("hi","hide",3) == 0
          $$abbrev^util("hid","hide",3) == 1
          $$abbrev^util("hide","hide",3) == 1


   2) $$spaces^util(string)

        Cuts away leading and tailing spaces. In addition it minimizes the
        white-space between words to a maximum of one space. For standard
        MUD input it should not matter if there are one or more spaces
        between keywords. So use this function.

        Examples:
          $$spaces^util("   My   name Is  Axel ") == "My name Is Axel"


   3) $$lower^util(string)

        Converts all letters in a string to low-case. Normally standard MUD
        commands should not be case-sensitive. So using that function might
        be a good idea.

        Example:
          $$lower^util("My nAme is Axel") == "my name is axel"


   4) $$ispart^util(string,word)

        Case-insensitve search for the complete <word> in <string> (delimiter
        is space) Before the search is started $$space() is applied on the
        string.

        The function returns 0, if the <word> was not found and the word-
        number, if it was found.

        Example:
          $$ispart^util("My Name is Axel","axel") => 4
          $$ispart^util("My Name is Axel","axe")  => 0
          $$ispart^util("My Name is Axel","Name") => 2


   5) $$count^util(string,word)

        Returns the number of occurances of <word> in <string>

        Example:
          $$word^util("My Name is Axel"," ")    => 3
          $$word^util("My Name is Axel","Name") => 1
          $$word^util("My Name is Axel","na")   => 0


-> "Text formatting"

   1) $$nam^util(string)

        Converts the first char of the given <string> into a captial letter.


   2) $$lb^util(s,l)

        Return string <s> with a maximum length of <l> aligned to the left
         - if <s> is shorter than <l> the rest is filled up with spaces
         - if <s> is longer than <l>, <s> will be cut to the length of <l>

        Example:
          $$lb^util("axel",6)  => "axel  "
          $$lb^util("axel",2)  => "ax"


-> "Script Execution"

   Some Stuff:
        The MUD engine does not fork(), but uses select(). That means it
        executes the command of player A, then of player B and so on -
        then the combat rounds, then some regen functions etc etc and then
        it loops and checks for commands again. Such a loop is called
        heartbeat or pulse.
   
        Lets say we have two players in the same room who move north at 
        the same time to another room with a script hooking the enter event.
        The game will handle it in following way: 

        First player A is moved, the script triggers and executes. When it
        is finished, the move command of player B is done, the script
        triggers again. Execution is done sequentally and we do not have
        to take care of multitasking stuff executing at the same time.


   1) Locking / Semaphores

        Lets say we got Player B following Player A. Player A moves to another
        room with a mobile who says 'Hello' upon someone entering. Now it
        can be really annoying, if it says 'Hello' mutliple times for every
        char entering. And if there is a group of 6, it would say Hello 6x.

                        :
                enter   ;--- enter event
                        d force^%char(me,"Hello")
                        q
                        :

        If a group moves all chars/followers are moved sequentially to the
        other room within the same heartbeat/pulse. So it would be sufficient
        if we set a lock after the first 'Hello', which removes itself after
        one pulse and while set does not execute the 'Hello' function.

        Above functionality can easily be solved with the function
        $$lock^util(id,pulse).

                        :
                enter   ;--- enter event
                        i $$lock^util($zn,1) q
                        d force^%char(me,"Hello")
                        q
                        :