STORYTELLER     "makes mobile a storyteller"

  debug         if set to 1, it sends debug messages to the room (not done!)

  info          output some information about the mobile and its story

  story         will open an editing session to input the story-script.
                When the session is done and saved, the script will be
                compiled.

                Example: /lib m 103 set 1 story



STORY-SCRIPT

  The story script is a list of commands. One command per line. Each
  command is followed by a relating argument. A list of possible commands
  is shown below:


  TERMINATION-COMMANDS:

    remember <pulse>    This has the same functionality as the remember
                        argument in the standard libraries. It will remember
                        the entering char for <pulses> until it will trigger
                        again.
        
    remember-any <pls>  This has the same functionality as the remember-any
                        argument in the standard libraries. It will remember
                        the entrance of any char and will not trigger again
                        for any char, until the given amount of <pls> pulses
                        has run off.

 

  CONDITIONAL/JUMP-COMMANDS:

    <label>:            define a label

    goto label          jump to a defined label

    set <var>=<n>       set <var> to the numeric value <n> on the storyteller.

    if <var>=<n> label  compare <var> with <n>. If true jump to the
                        defined label <label>. Possible operators are: =,<,>
                       
                        As a substitute for <var> you may set keywords, which
                        return values regarding the player who triggered the
                        story. See below 'IF FUNCTIONS'.
                          Example: if $level>10 label

    if <num> label      do a random roll from 1 to <num> and if the result
                        is <num> then jump to the given label  (chance!)

    done                will completely exit and stop the story-script

    hang                will exit the story script, but keep an idle state -
                        that means it will not yet be free to trigger for
                        another player. Might be a good idea to make sure it
                        is completely stopped after a while by using listen,
                        receive or timer event.

  
  IF-FUNCTIONS:
    
    $age                returns the age of the player

    $align              return align of player

    $camefromdir        return direction where player came from

    $class              return class index of player

    $hour               return hour of the day

    $level              returns the level of the player

    $mob_in_room(x)

    $obj_at_player_eq_pos(x)

    $obj_in_room(x)

    $obj_in_player_inveq(x)

    $obj_in_teller_inveq(x)

    $race               returns the race of the player
                        0 human       1 elf         2 dwarf        3 orc
                        4 black orc   5 night gob   6 forest gob   7 skaven
                        8 immortal

    $room               return room number of storyteller

    $sex                0: neutral, 1: male, 2: female

    $sideok             storyteller and player of same side?

    $wps                returns the number of war-points of the player


  COUNTING-COMMANDS:

    inc <var>           increment the value of <var>
 
    dev <var>           decrement the value of <var>



  INTERACTION-COMMANDS:


    actor <vnum>        Switches the actor to the first mobile with the
                        given <vnum> in room. If <vnum> is omitted it will
                        switch back to the storyteller itself.

                        Following commands are influenced by 'actor':
                          echo, emote, force, give, say, object, purge, mobile

    devote              switch to devote mode (see: goalone)

    echo <text>         Echos <text> in the room of the current actor.

    emote <text>        Mobile will issue following text as emote. (*)

    force <command>     Mobile will be forced to do the given command. This
                        might be anything, from opening or closing stuff,
                        saying, emoting, telling, socializing -- anything. (*)

    give <vnum>         give object <vnum> from the actor to the one who
                        triggered the story.

    gixexp <xp>         give <xp> experience points

    goalone             switch to alone mode (see: devote)

    ldesc <ldesc>       change ldesc of the actor.
                        (<ldesc> = "off", set it back to default)

    move <room>         move actor to room <room>

    say <text>          Mobile will say the given text. (*)
        
    sayc <chance> <text>

    saycl <chance> <label> <text>

    vanish              purge actor and return to storyteller

    wait <pulses>       This is not a real communication command, but it
                        fits in, since it controls the communication flow.
                        When the command is executed, the script waits <x>
                        pulses until the next command is executed.
                        If no <pulses> arguments is given, then the storyteller
                        engine tries to decide itself how long to wait.
                        (The value will be between 40 and 80)

    walk <room>         let actor walk to room <room> at 2s / room
                        (if <room> = "back", let him return)


  HANDLERS:

    listen <phrase>{,<phrase>}=<label>
                        Install a listen-handler, which will jump to <label>,
                        if the storyteller mobile hears one of the given
                        phrases.

                        To add socials, you have to add a '*' in front of the
                        phrase.

                        All listen-handlers will be removed after a trigger.

                        Note: "listen off" removes all listen-handlers and
                              timers.


    receive <vnum>=<label>
                        Will install a receive-handler, which will jump
                        to <label>, if an object <vnum> is given to the
                        storyteller mob.

                        All receive-handlers will be removed after a trigger.

                        Note: "receive off" removes all receive-handlers and
                              timers.


    timer <pulses>=<label>
                        Jumps to <label> in <pulses>. Using 0 as value will
                        cancel an existing timer. There may only be one
                        timer per label, so if you try to set another one,
                        it will overwrite the first one.



  INTERFACE-COMMANDS:

    call <label>        <label> of the relating mobile script will be
                        executed. Only Scripters or Immortals of suitable
                        level are able to set those. The label in the
                        relating script _must_ have following syntax:
                        
                        <label>(me,who)

                        You may set 'quit=1' to cancel the current
                        story.

                        Possible interface functions from scripting are:
                          var^%lstory()         to set/read a variable
                          vdel^%lstory()        to delete a variable
                          goto^%lstory()        to start a story at given label
                          stop^%lstory()        to stop a story
                        


  MISC-COMMANDS:
     
    #                   A line starting with # is treated as a comment

    object <vnum>       load object <vnum> and put it into the actors inv

    purge <vnum>        purges the first object in the with <vnum> from
                        the actors equipment/inventory.

    mobile <vnum>       load mobile <vnum> and put it into the actors room


  VARIABLES:

    Variables starting with:

    *   are not deleted when the script ends
    %   are saved on the player
    @   are saved on the player
    @@  are not specific to the teller


(*) The name of the player who entered, will be substituted for '$n'.



EXAMPLE-STORY-SCRIPT(s):

 1) 
   ## removed ##


 2)
  #
  # test script to illustrate receive-handlers
  #
  receive 510=beer
  receive 415=cookie
  done

  beer:
    say Ohhh - beer!!
    done

  cookie:
    say I really do love cookies.
    done