-----------------------------------

Title: Soul Daemon
Auther: Parthenon @ LPUniversity
Date: 28-JUN-2006
Contributers: Parthenon

-----------------------------------

Contents:

i. What is the soul daemon?
ii. How the soul daemon works.
iii. How to create a client to interface with the soul daemon.


i. What is the soul daemon?

   The LPUniversity soul daemon takes care of keeping track of all programmed
   emotes a user may use. Through the edemote command, you may add, remove, or
   check the syntax of existing emotes using the soul daemon. Also whenever a user
   enters a command that corresponds to an existing emote, the soul daemon will
   build all messages printed to the user, the room, and the targets. If you wish
   to read up on the lib provided client, then you may see the 'emote_client' doc.


ii. How the soul daemon works.

    In LPUniversity there are two types of emotes. There are untargeted emotes,
    and targeted emotes. An untargeted emote has no target. Example: if there
    were an emote called 'smile', then the user would type 'smile' with nothing
    else and the output might look like '<player> smiles brightly'. The user
    might also type something like 'smile warmly' and instead of the default
    'brightly' they will see '<player> smiles warmly'. Then there are the
    targeted emotes. Targeted emotes are targeted at other players so that
    if the smile emote is used, then the user might type 'smile Parthenon' and
    the output would be 'You smile at Parthenon', while other messages are
    printed to the room and Parthenon telling them what is happening. All emotes
    are stored in a mapping variable in the soul daemon called emotes. The form
    this mapping take is:

    ([ <string emote> : <string *msgs>, <string emote> : <string *msgs> ])

    where emote is the name of the emote, and *msgs is an array of the messages
    that will be printed. The name of the emote will either be the verb used
    for the emote OR if it is a TARGETED emote it will have a '/t' appended
    to the end. Example: the smile emote above would most likely have both,
    a 'smile' entry and a 'smile/t' entry. The *msgs variable will hold
    the messages that are printed to the emoter, the room, the target if any,
    and finally a default modifier if any. Using the smile emote as an example
    the mapping might be filled like this (keep in mind that the $'s mark a
    place where text will be replaced with different things, see the emote_client
    doc on what is replaced where):

    ([ "smile" : ({ "$I $V $M.", "$I $V $M.", "brightly"}), "smile/t" :
      ({"$I $V $M at $T.", "$I $V $M at $T.", "$I $V $M at $T.", "brightly"}) ])

    The first element of the one of the values arrays is always the message
    printed to the emoter, the second is always to the room, the third is going
    to be the modifier for an untargeted emote, or the message to the target
    if it is targeted, and the fourth will only be used in the targeted emote
    as the default modifier.

    The syntax the user must use is always <emote> [<target>] [<modifier>].
    When the user enters an emote command, it is parsed to see if there is
    a target, if there is a target then it will print out the targete emotes
    messages using either the default modifier, or the one provided by the player,
    otherwise it prints out the untargeted version. The messages printed out
    to the player, room, and target, will automatically be printed in the
    correct form, such as: the emoter will see 'you', while the room and the
    target will see '<emoter name>'. The verb will also change depending upon
    who sees it.



iii. How to create a client to interface with the soul daemon.

    If you wish to find how to use the lib provided client, you may see the
    doc 'emote_client'. If you wish to create your own client, you are going
    to need to know the function calls to the soul daemon that need to take
    place in order to use it. This section will explain these calls.

    First of all create a basic object for your client. This should usually
    inherit the base object of the lib. You are on your own for creating any
    sort of menu system, this section will just show you the calls you will
    eventually need to make to actually get an emote into/out of the system.

    SOUL_D->set_emote(string emote, string *msgs);

    This function will add an emote to the emote variable in the soul daemon.
    The first argument is a string with the name of the emote... remember, if
    it is a targeted version it must have a '/t' appended to the end of it.
    The second argument will be an array of strings to be printed to the user.
    In an untargeted emote, the first element is the message to the player,
    the second is to the room, and the third is the default modifier. In a
    targeted version, the first element is the message to the player, the
    second is to the room, the third is to the target, and the fourth is
    the default modifier. Also, this function will call save_object() in
    the soul_daemon, this way the emotes get saved in case there is ever data
    loss for some reason.

    SOUL_D->delete_emote(string emote);

    This function will delete an emote with the string name of emote. Again,
    remember that if you want to delete the targeted version of an emote,
    it must have a '/t' appended to the end of it. This function will also
    call save_object() in the soul daemon to preserve data.

    SOUL_D->reset_emotes();

    This function will erase all emotes from the MUD. It resets the emotes
    mapping variable to ([]). This is not reversible so be careful when
    implementing this function.

    SOUL_D->query_emotes();

    This function will return an array of the keys of the emotes mapping.
    In other words it contains a list of all emotes avaialable. Rember that
    the targeted emotes will have a '/t' appended to the end of them.

    SOUL_D->query_emote_msgs(string emote);

    This function will return the array of messages that correspond to a
    particular emote. Remember that if you want the messages for a targeted
    version of an emote you must append a '/t' to the end of the emote name.

