 |
help > actions > actions
--------
Overview
--------
These functions exist to simplify sending messages to seperate people,
while keeping the grammar right. Consider the old way of doing this:
write("You bing at "+target->query_name()+".\n");
tell_object(target, this_player()->query_name()+" bings at you.\n");
tell_room(environment(this_player()), this_player()->query_name()+" bings "
"at "+target->query_name()+".\n", ({this_player(), target }) );
And now compare that with:
this_player()->targetted_action("$N $vbing at $t.", target);
There are some new things to learn, but once you do, it will make any
situations like these much less painful to code. Consider all those weapons
you have that do specials :).
NOTE: Actions now allow items to be given as targets for targetted/complex
action variants. 'man actions items' for the current status of
action support for items.
-- July 2011, Misery
---------------
Basic functions
---------------
void simple_action(string message) - This function prints out an action
involving just the doer. The doer will get their message, and the rest of
the room will get theirs.
Example:
this_player()->simple_action("$N $vbounce.");
this_player() would see: "You bounce."
others would see: "Megaboz bounces."
If you want to get a lower case version of the above, you would use:
this_player()->simple_action("$n $vbounce.");
The result would be "you bounce." or "megaboz bounces."
void my_action(string message) - Just like simple_action(), but only prints
the message to the doer, and not the rest of the room.
Example:
this_player()->my_action("$N $vbounce.");
this_player() would see: "You bounce."
Others would see nothing.
void other_action(string message) - Just like simple_action(), but only
prints the message to the rest of the room, and not the doer.
Example:
this_player()->other_action("$N $vbounce.");
this_player() would see nothing
others would see: "Megaboz bounces."
void targetted_action(string message, object target) - This works like
simple_action(), but assumes that 'target' is the target of the action, such
as in the example given in the overview.
Example:
this_player()->targetted_action("$N $vbounce at $t.", fing_player_ob);
this_player() would see: "You bounce at Fingolfin."
Fingolfin would see: "Megaboz bounces at you."
others would see: "Megaboz bounces at Fingolfin."
void complex_action(string message, object *targets) - If you have something
more complicated, such as multiple targets, use this one. 'targets' is an
array of objects referring to all the targets of this action.
Example: this_player()->targetted_action("$N $vbounce at $t and $t2.",
fing_player_ob, silence_player_ob);
this_player() would see: "You bounce at Fingolfin and Silence."
Fingolfin would see: "Megaboz bounces at you and Silence."
Silence would see: "Megaboz bounces at Fingolfin and you."
others would see: "Megaboz bounces at Fingolfin and Silence."
--------------
Message format
--------------
One note, each of these can be capitalized whenever appropriate, just use
a capital letter, like a $N, instead of $n. Proper names will always be
capitalized when displayed, however.
$N - A subject of a verb. Defaults to the name of the doer of the action.
The doer himself will see 'You', while everyone else will see their name.
If you want to use someone else here as a subject, supply a number after,
like $N1 would let the target (or the first person in the target list of a
complex action), be treated as the subject of a verb. Note that $N0 is the
same as $N here. There's one more option you can pass here, but it will
help to explain how these functions decide when to use pronouns. Whenever
an action is done, a list is made up of all the objects involved: the doer
and the target(s), if any. The first time one of these is referenced in a
message, their full name is displayed, but any time after that, a pronoun
(he, she, it), is used in place. You can modify this default behavior if
you want by adding an extra flag after the $N. First of all, you can have
$Nf. This will (f)orce a pronoun to be used, instead of a proper noun.
You can also use $Ns. This will (s)upress a pronoun from being used, and
use the proper name instead (except the doer of the verb will still see
'you'). Finally, you can use $NS. This will (S)upress pronoun use for
everyone, including the subject himself. Everyone involved will see the
doer's full name used.
$V - A verb. Like $N, you can place a number after the $V if you want to
change who in the list is actually performing the verb's action. Then,
put the verb, in 2nd person, directly after the $V. It's important to make
sure you're using the second person here, because of the way the verb gets
conjugated. For example, "$N $vlook around." is correct, while
"$N $vlooks around." is not. The word "is" is the conjugation of the word
"be", so "$N $vbe trapped." will display "You are trapped." to the player,
and "He/She is trapped." to others.
$T - The object of a verb. Again, like $N, you can specify a number after
to specify which is the actual object. Unlike everything else, however,
the number after $T defaults to 1 if you don't specify. This is because
for most uses, $T can be used as the 'target'. $T can also take a second
number, which tells who was the subject of this particular action. This
can be very useful for complex messages with multiple verbs/subjects/objects.
For example, a room message of "Megaboz watches as Silence kicks Wildcat.",
with Megaboz as the main doer, and Silence next in the list, with Wildcat
last, the message here would be "$N $vwatch as $n1 $v1kick $t21."
Now, there's 2 parts of the message: "Megaboz watches", and
"Silence kicks Wildcat". The first part is the same as was discussed
before, and the second part has a new subject (silence), a new verb (kick),
and a new object of the verb (wildcat). So, "...$n1 $v1kick $t21", has
$n1, which means that Silence is the new subject. $v1kick has Silence as
the subject of that verb. And finally, $t21: the 2 means that the second
person in the list (wildcat) is the object of the verb, and the 1 means
that the first person in the list (silence) is the doer of this verb. If
you had only used $t2, then it would have incorrectly thought that Megaboz
was the subject of that. Finally, you can also specify an optional pronoun
flag after $T, exactly the same as for $N.
$P - Possessive form. This is used just like $N, except that possessive
is assumed. You can add an optional number or pronoun flag just like with
$N. For example, "$N $vraise $p hand.", would give "Megaboz raises his
hand."
$R - Reflexive form. This is very similar to $P, except that no prnoun flag
is needed here, as the only thing that applies here is to display the prnoun
to everyone. The reflexive form is himself, herself, yourself, etc. Note
that there's 2 ways to acheive this: "$N $vkick $r" and "$N $vkick $t0"
would both generate "Megaboz kicks himself."
------------------
Advanced functions
------------------
These set of functions are less likely to be used, but the doc is here,
just in case.
mixed *tokenize_message(string message) - All the low level functions
parse a message into a tokenized format, using this function. A mixed
array of strings and ints is returned.
string *action_messages(mixed *message, object *who) - This function takes
a tokenized message, and an array of objects as the list of things involved
in the action. An array of messages is returned, each corresponding to
a person in the who array, plus one more for the message to the rest of the
room. This can be useful if you want to obtain the messages that would be
displayed, without actually showing them to the user.
string generate_message(object forwhom, mixed *message, object *who) -
This function is called by action_messages() for each person in the
who list to get its array of messages. message and who are the same, and
forwhom is the specific object to generate the message for.
mixed preserve_messages(object who) - If an object in your target list
has the possibility of getting destructed before you have a chance to
display the message, you can call this on that object. This will return
a temporary object with the name/pronoun set of who. You can destruct
this object if you like, but it will destruct itself automatically, too.
Note that if you need to do this more than once, call this function for each
time you need to do it. The returned object can be substituted in any
of these functions, in place of a target.
string *temote(mixed *message, object target, mixed tnames, int nosay) -
This is the replacement to the old temote() function. It retains total
backwards compatibility, by switching the defines in temote.h over to new
values. message and target are the usual arguments. tnames can be the
return value of a preserve_messages(), in which case, target is ignored
(this is also done this way for back compat). nosay will prevent the text
from being displayed, and just return an array of messages instead.