[[ Editor - This capture was graciously provided by Grumpy. I took the liberty
of editing his emotes so that the document read as third person singular to
match the others. I also cleaned up spurious characters in a few places. I
read the document through, so there is no chance meaning changed. I will leave
things alone rather than risk changing the meaning. These policies will apply
to the complete set. ]]

Descartes says: since the class is so small, I do not want to cover a ton
of new junk and get more out of whack than we aleady are :)
Descartes says: so, I will play around with concerns you guys have right now
The Killer smiles
Grumpy says: okie i got one..about the message efun()
Grumpy says: what are all the first arguments?
--==** /doc/efun/m/message **==--

message(3)             C LIBRARY FUNCTIONS             message(3)

NAME
     message() - deliver messages to "living" objects

SYNOPSIS
     void message(string class,  string  message,  mixed  target,
     mixed exclude);

DESCRIPTION
     message calls receive_message(string class, string  message)
     in  all  objects  in  the target list excluding those in the
     exclude list. This basically tells the object the message.

     Class is the type of message (used for clients and such). An
     example would be 'combat', 'shout', 'emergency' etc.

     Message is a string containing the text to send.

     Target is a list of objects to be sent the message. This can
     be  either  a single object string or object pointer, or may
     be an array of  either.   If  a  target  is  non-living  all
     objects in its environment will receive the message.

     Exclude is a list of objects that  should  not  receive  the
     message.  This  can  either  be  one  object  or an array of
     objects.

SEE ALSO
     write(3), shout(3), tell_object(3).

Sun Release 4.1           Last change:                          1

Descartes says: ok :)
Descartes says: generally, in area programming, write() and say() will work
just fine
Grumpy nods
Grumpy says: sometimes i have to use other objects to tell stuff to the
players 
The Killer ups his hand .
Descartes says: write() and say() used to be efuns themselves
Grumpy says: i like tell_room but the problem is (well i think so) it tells
the player doing it as well as the rest of the room
Descartes says: they would send text directly to the user
Grumpy says: so i use message and tell_object
Descartes says: tell_room() exists only for backwards compatibility
Descartes says: tell_object() is for backwards compat too
Descartes says: should not use those :)
Descartes says: at any rate...
The Killer says: what is the difference between set_hit_func() and
set_hit() ?                           
Descartes says: when they were efuns, they sent text directly to the user
Descartes says: one sec the killer :)
Dagger bows
Grumpy says: i have a player using one object
The Killer bows
Frog bows to Dagger
Descartes says: this means that the text did not get formatted and colored
and other stuff
Grumpy says: that evokes a function in another object
The Killer looks at his surroundings.
Grumpy says: so i used tell_object to get the second object to interact with
the player
> Descartes says: so I simulated the efuns in the mudlib, using message()
instead
Descartes says: cd /adm/SimulEfun
Grumpy says: ahhhhhh i see
Descartes says: then more communications.c           
The Killer smiles
--==** /adm/SimulEfun/communications.c **==--

varargs void say(mixed str, object ob) {
    if(!environment(this_player())) return;
    message("say", str+"", environment(this_player()),
      (objectp(ob) ? ({ this_player(), ob }) : ({ this_player() })));
}

void tell_object(object ob, mixed str) { message("tell", str+"", ob); }

varargs void tell_room(object ob, mixed str, mixed exclude) {
    if(!ob) return;
    message("environment", (str ? str+"" : ""), ob,
      (exclude ? (pointerp(exclude) ? exclude : ({exclude})) : ({})));
}

varargs void shout(mixed str, mixed exclude) {
    if(objectp(exclude)) exclude = ({ exclude });
    else if(!pointerp(exclude)) exclude = ({});
    if(this_player()) exclude += ({ this_player() });
    message("shout", str+"", users(), exclude);
}

Descartes says: those are the actual definitions of those functions
say message has a string called class as first argument  
Grumpy says: message has a string called class as first argument
Descartes says: so by using them, you are actually writing slower code
Grumpy nods
Descartes says: getting to that grumpy :)
Grumpy says: i see
Grumpy blushes
Descartes says: if you look at tell_room() and tell_object(), it is
actually no more difficult to use message() than them
Dagger looks over Frog
Descartes says: so long as you understand message()
Descartes says: what message does, is allow stuff to get processed by the
mudlib *before* it is sent to the user
Descartes says: message() takes at least 2 arguments, and can take up to 4
Descartes says: the first two args are mandatory
Descartes says: 1) message class
Descartes says: 2) message
The Killer looks at his surroundings.
Descartes says: the message class classifies what sort of message is being
sent
Descartes says: most common are "my_action" and "your_action"
Descartes says: but there are others, and I will write a doc file of them 
all :)
Frog says: what "I" see, and what "others" see?
Descartes says: not really
Grumpy says: cool :)
Descartes says: something which describes "what I do" is "my_action"
Descartes says: actually your_action is other_action
Frog nods
Descartes says: what describes what another person does is other_action
Descartes says: but there are other types
Descartes says: like "tell", "environment", "room_description", "smell",
"listen" :)
Grumpy says: how would u use instead of tell_object? "my_action"?
Dagger says: sorry
Grumpy says: oh..so most of lfuns use the message efun then
Descartes says: message("my_action", msg, this_player())
You smile
Descartes says: that is = to write()
The Killer says:  which one we should use then ?
Descartes says: tell_object() is message("tell", msg, ob);
Descartes says: where ob is the object being told to
Descartes says: so you see, you have no control over the message classes
when you use the other stuff
Descartes says: and the other stuff is slower, since it does eventually
call message() anyways
Grumpy nods
Frog says: better that we just call message() in our code directly?
The Killer says: i see ...
Descartes says: of course...
Descartes says: write("You kick the troll.");
Descartes says: is much easier to write than...
Descartes says: message("my_action", "You kick the troll.");
Descartes says: right, write() is slower
Descartes says: so the first is the message class, the second argument is
the string the user should see
Descartes says: the third argument is who should see the message
Descartes says: if no third argument exists, then the message goes to
this_player()
Descartes says: if the third argument is an array of objects, the message
goes to each of those objects
Descartes says: if the third argument is living it goes directly to the
object
Descartes says: if, instead, the third argument is something like a room
Descartes says: then the message is sent to all the objects in its
inventory
Descartes says: does that all make sense? :)
You smile
Descartes says: fourth argument also is optional
Descartes says: if omitted, nothing happens
Lassondra grins
Descartes says: it can be an array of objects or s single object    
Descartes says: that object or array of objects, if they belong to the
group of objects supposed to see the message, they will be excluded
Descartes says: say()'s use of this si a good example
Descartes says: for my speaking, what I say looks like this:
Descartes says: message("talk", msg, environment(this_player()), ({
this_player() }));
Descartes says: where msg = "Descartes says: hi"
Descartes says: clearly, I do not want to be seeing Descartes says: hi
Descartes says: but I am in the room
Descartes says: so you use the fourth argument to exclude me :)
Grumpy says: :)
You shake your head
Frog shakes his head
Descartes says: next question?
Lassondra shakes her head
You giggle
The Killer says: no
The Killer says: my question was ..
The Killer says: what 's the deffernce between set_hit() and set_hit_func() ?
Descartes says: ahh
Descartes says: set_hit_func() should never be used
The Killer smiles
Descartes says: it exists for old code from before you ever wizzed :)
Descartes says: set_hit() is faster and does everything you need to do :)
The Killer says: so how can i transfer this to that ?
Grumpy says: um..what does set_hit() do btw?
Descartes says: to set_hit()?
Descartes says: set_hit(function|string)
The Killer says: yup
Descartes says: if you pass a string, the wielder sees that string whenever
they hit
Descartes says: if you pass a function, that function gets called every hit
Descartes says: the number returned by your function is added to the damage
Grumpy says: ahhh...
Descartes says: set_hit("The sword strikes mightily.");
Descartes says: set_hit( (: this_object(), "weapon_hit" :) );
Descartes says: the second will call int weapon_hit(object attacker) in
your code any time the weapon hits an enemy
Descartes says: whatever you return there is added to the damage
Descartes says: all that make sense?
Descartes says: useful for making race specific weapons
The Killer says: sure..sure
Descartes says: like orc_slayer and such
Grumpy says: okie..i know wc determines ur weapons hitting power
Descartes says: another question?
The Killer shakes his head
Grumpy says: how does wc work? in terms of damage
> Descartes says: I could not begin to explain that other than to see look at
/std/living/combat.c
Descartes says: and that will change with the new combat anyways :)
Descartes says: it is extremely complex :)
Grumpy says: that is true
The Killer nods
Descartes says: another question?
Grumpy says: okay..yesterday i tried quite a while to figure out how much xp a
certain person has to spend to get to particular skill lvl
The Killer shakes his head
Grumpy says: where are the skill/xp pts kept?
Descartes says: that again is about to change :)
You fall down laughing
Descartes says: and I could not give a useful answer
Frog sighs
Grumpy says: i'm hooked on redundant questions
Descartes says: other than to say look at /d/standard/adv_main.c
The Killer looks at his surroundings.
The Killer smiles
Grumpy says: okie..what is previous_object()?
Descartes says: but that is totally unlike what things will be like :)
Descartes says: previous_object() is the object which called the function
being executed
Descartes says: when object A does B->foo()
Descartes says: while foo is being executed in B, A is previous_object()
Descartes says: mostly used for security
Grumpy says: ahhhhhh makes some of my coding a bit simpler...
Descartes says: another question? :)
The Killer smiles
Grumpy says: what is __DIR__ ?
Descartes says: it is a globally available #define  
Descartes says: it is equal to the directory from which the current object
comes
Descartes says: for example
Descartes says: if __DIR__ is in /d/standard/square
Descartes says: __DIR__ = "/domains/standard/"
The Killer looks at his surroundings.
Descartes says: another question? :)
The Killer shakes his head
Grumpy says: so we use it for say...
Frog says: how would i find the parent dir of __DIR__?
Descartes says: exits in your rooms
Grumpy says: a room file which has a monster in /obj/monster
Descartes says: that way if you ever changed the directory structure of
your area, you would have to change nothing :)
Grumpy nods
Descartes says: parent of __DIR__?
Grumpy says: i see :)
Descartes says: __DIR__+"../"
Frog nods
Descartes says: not sure if it will work or not, but worth a shot :)
Grumpy says: i'd just use __DIR__+"/obj/monster"
Grumpy says: awright my last one...SetNoClean
Descartes says: another question?
Grumpy says: what is that?
The Killer looks at his surroundings.
Descartes says: SetNoClean() :)
Grumpy says: so the room doesn't reset?
Descartes says: well, every half hour or so, any object which has not had a
function called in it has the function clean_up() called in it
Descartes says: that is defined in /std/clean_up.c
Descartes says: that simply checks to see if the object can be cleaned from
the game
Descartes says: the first thing clean_up() does is check if SetNoClean(1)
has been called      
Descartes says: if it has, then it will not destruct
Grumpy says: ahhh
Descartes says: in other words, this keeps your objects from being removed
Descartes says: no reason to use it though
Descartes says: unless you have an object that *must* not be destroyed
Descartes says: use it rarely
Grumpy nods
Grumpy says: yea..i was just curious
Descartes says: clean_up() helps save memory
Descartes says: sometimes it is necessary :)
Grumpy says: yea i guess ships have that function
The Killer nods
Descartes says: \right
Grumpy says: okie..last last one..
Descartes says: a player would be pissed if they got cleaned up :)
You grin
Descartes nods
Grumpy says: earlier today u were talking about (int)something->something
The Killer ponders
Descartes says: right
Descartes says: casting calls
Grumpy says: u always have to use the (variable) when u call another function?
Descartes says: (int) is called a cast
Grumpy says: from another obj ie
Descartes says: technically, no... but you should
Frog says: cast changes a variable from one type to another?
Descartes says: if you call another function in another object AND you are
using that value in a comparison, then you have to cast it
Descartes says: but it is simply just best ALWAYS to cast external calls
Descartes says: no frog
Descartes says: not like a C cast
Descartes says: it is just more like pointing out to the driver what it is
Grumpy says: ahh so the driver doesn't mess up..
Descartes says: no, the driver will not mess up
Descartes says: just coding style
Descartes says: making code readable really
Grumpy nods
Descartes says: LPC types are handled rather oddly
Grumpy says: i see
Descartes says: I just recommend you always cast because it is a very good
thing
The Killer nods
Grumpy says: well one time..while making my workroom it failed to load my room
'cos i hadn't casted
Descartes says: right
Descartes says: the driver wants it some times
Descartes says: but there is no good reason *to the driver* why it wants
that variables 
Descartes says: it already knows what type the thing is :)                 
Descartes says: that is why types are so weird in LPC
Grumpy nods
Descartes says: so bottom line is: always cast call others :)
Grumpy says: why is mixed used? can't just a string do the same thing?
Descartes says: *I* use mixed for situations where I am writing functions
which can take arguments of varying type
Descartes says: like set_hit(mixed val) {
say then u do a stringp check and so on
Grumpy says: then u do a stringp check and so on
Descartes says: if(!stringp(val) && !functionp(val)) error("Bad argument 1
to set_hit().\n");
Descartes says: right
Descartes says: when I use it, I check what type it is and act accordingly
Descartes says: otherwise, using mixed when you know what the value is
supposed to be is bad
Grumpy says: okie how would u convert a variable to another kind?
Descartes says: cause then you will get errors and not no why
You ack
Grumpy says: i see....
Descartes says: depends on from what to what :)
Descartes says: to_int() will convert strings and floats to ints
Grumpy says: well i get the user to load a string "5 to 3"
Descartes says: to_float() ints and strings to floats
Grumpy says: so i need to separate them to 2 ints
Descartes says: right :)
Frog says: and converting integers to string?
Descartes waves
Grumpy says: to_string i assume
Descartes says: to_string() right :)
Grumpy nods
Grumpy says: okie