LPC MANUAL --- INTRODUCING
==========================

Contents:

    1. introduction
    2. implementation
    3. triggers versus direct calls
    4. set_living_name()


1. INTRODUCTION
===============

This manual is about NPC's introducing themselves to other people. It
includes the complete syntax of the functions to handle introductions. This
manual is not complete, not does it pretend to be. There will always be
different cases and people will always argue with possible ways of handling
matters. That is perfectly fine. However, this manual does offer what I
consider to be the best way of handling introductions.

/Mercade


2. IMPLEMENTATION
=================

The act of introducing someone take place as follows:
    AA introduces BB to CC

Naturally, AA can introduce him/herself and then BB will be the same living
as AA. CC can be a single living or be multiple livings. By default, if one
types 'introduce me' this will cause him/her to introduce him/herself to
all livings in the room. When someone (CC) receives an introduction, the
function

    void add_introduced(string name);

is called in the receivers. In players, this function is used to register
the introduction and store the name in a list that can be viewed with the
command 'introduced', or later the name can be remembered with the command
'remember'. In NPC's this function is not defined, but that does not mean
we cannot define it ourselves and use it. The following is an example of
what the function could look like.

/*
 * Function name: add_introduced
 * Description  : Whenever someone is introduced to me (CC), this function
 *                is called in me to tell me that 'name' (BB) is being
 *                introduced to me. The living that does the introduction
 *                (AA) is available though this_player().
 * Arguments    : string name - the [lower case] name of the living that
 *                              is being introduced to me. (BB)
 */
public void
add_introduced(string name)
{
    /* In players, this function makes sure that 'name' appears on your
     * 'introduced' list and then you may later 'remember' him/her. In
     * NPC's you may for instance use it to return the honour by
     * introducing yourself. Note that we don't necessarily have to use
     * an alarm since this function is called _after_ all messages from
     * the original introduction have been printed.
     */
    command("say How delighted to meet you!");
    command("introduce me to " + name);
}


3. TRIGGERS VERSUS DIRECT CALLS
===============================

The usual way of noticing when someone was being introduced to an NPC was
by using triggers. Triggers parse _all_ text printed to the NPC to see
whether something useful is among it. For emotions, this is the only way to
notice that we are being smiled at or that we are kicked for instance. For
emotions, triggers are still the way to go, but I would like to strongly
discourage the use of triggers to catch introductions. Instead, I think
that all introductions should be caught using the function described above.
For this there are a few reasons.

As easy as triggers are to code (examples exist), it is even easier to use
the function add_introduced() because it saves you from parsing the result
of the trigger and trying to figure out who actually introduced who. Now
you get all the information you need presented to you on a silver tray. A
much more important reason for using add_introduced() is that it is a lot
better for our systems resources. As I remarked earlier, triggers parse all
text printed to the NPC to find whether it just parhaps happens to be an
introduction. This parsing is rather costly, but even if it were not, it is
naturally always easier to wait for add_introduced() to be called than to
actively search for a possible introduction.


4. SET_LIVING_NAME()
====================

If you want your NPC to be able to introduce him or herself, you may also
want to export the name of the living by using the efun set_living_name().
In the past it has been rumoured that you need to have the living name set
in order to make it possible for players to remember the name of the NPC,
but this certainly is not valid anymore. However, it can be useful to set
the living name. [See the manual page on set_living_name() for information
and its syntax.] For instance, it allows you to use the name of that NPC as
argument to for the command goto. With respect to the living name I just
want to give you one warning:

    When you intend to use set_living_name() on an NPC make very sure that
    you banish the name for use by players and if a player with that name
    already exists, do NOT use the name for your NPC.

If another NPC already uses a name, you can still use set_living_name() on
your NPC too if you like the name, though when find_living() is used to
find the living, you never know which of the NPC's with the same names if
returned.
