tbamud/doc/act.txt

If you have any additions, corrections, ideas, or bug reports please stop by the
Builder Academy at telnet://tbamud.com:9091 or email rumble@tbamud.com -- Rumble

The act() Function 
Originally by Alex Fletcher. Based on text from the DikuMud authors 

This document is intended to give an overview of the act()function and give a 
summary of the various flags and the associated descriptive control characters. 
The act() function is one of the primary functions for sending a message from 
the game to a character or number of characters in a room. 

Contents 

1 The act()Function

1.1 Overview
1.2 The Function
1.3 TheParameters
1.4 Control Characters
1.5 Examples

1 The act()Function 

1.1 Overview 
The act() function is used to process and send strings of text to characters 
in a room. It can be used to send the same basic string to a number of 
characters filling in certain segments <20> designated by control characters <20> 
in different ways, dependant on what each character can see and who each 
character is. Once the text string passed to the function has been parsed, it 
is capitalized and a newline is added to its tail. 

1.2 The Function 
The act()function is found in the comm.c source file and is described as: 

void act(const char *str, int hide_invisible, struct char_data *ch, 
struct obj_data *obj, const void *vict_obj, int type) 

These pieces are used as follows: 

str: This is the basic string, a null terminated character array, including 
control characters (see section 1.4 on <20>Control Characters<72>), to be sent to 
characters designated by the targets. 

hide_invisible: A TRUE or FALSE value indicating whether or not to hide the 
entire output from any characters that cannot see the <20>performing character<65>. 

ch: The <20>performing character<65>. This is the character that the output string 
is associated with. The character is used to determine the room for the output
of the action in question. 

obj: An object (an actual item <20> obj_data) used in the course of the action. 

vict_obj: This can be either a character involved in the action, another 
object, or even a predefined string of text. 

type: One of TO_VICT, TO_CHAR, TO_NOTVICT, or TO_ROOM. This indicates who it 
is to be targeted at. 

1.3 The Parameters 
Of the various parameters passed to the act() function, the str is the most 
important, as it is the basis for the actual final output. If this parameter 
is a null-pointer or points to a null-character, then the function returns 
immediately. The next important parameter is the ch parameter. This, as 
mentioned, points to the central character associated with the output string 
and action. 

obj is an object of type struct obj_data *that is passed to the function. If 
there is no object to pass to the function, then a NULL or 0 should be passed 
in this location. 

The next parameter vict_objcan be a number of things ranging from a game object
(strcut obj_data *), through to a character (struct char_data *), and even a 
null terminated character array (char *). 

Do note, however, that obj and vict_obj are both ignored if there is no control
character reference (see section 1.4 <20>Control Characters<72>) to them and the type
is set to TO_ROOM or TO_CHAR. In these cases, NULL should be supplied as the 
input to the function. 

The hide_invisible flag dictates whether or not the action output should be 
hidden from characters that cannot see ch. If the flag is set to TRUE 
(non-zero), then this is the case. 

The type determines who the output is to be sent to. There are four options for
this (all defined in comm.h) described below: 

TO_ROOM: This sends the output to everybody in the room, except ch. 

TO_VICT: This option sends the output to the character pointed to by vict_obj. 
In this case, vict_obj must point at a character rather than an object. 

TO_NOTVICT: In another case where vict_obj must point to a character. This 
sends the output to everybody in the room except ch and vict_obj. 

TO_CHAR: Finally, this option sends the output to the ch. 

TO_SLEEP: This is a special option that must be combined with one of the above
options. It tells act() that the output is to be sent even to characters that 
are sleeping. It is combined with a bitwise <20>or<6F>. i.e. TO_VICT | TO_SLEEP. 

When the string has been parsed, it is capitalized and a newline is added. 

1.4 Control Characters 
In a manner similar to the printf() family of functions, act() uses control 
characters. However, instead of using the % symbol, act() uses the $ character 
to indicate control characters. 

$n Write name, short description, or <20>someone<6E>, for ch, depending on whether 
ch is a PC, a NPC, or an invisible PC/NPC. 
$N Like $n, except insert the text for vict_obj.*
$m <20>him,<2C> <20>her,<2C> or <20>it,<2C> depending on the gender of ch. 
$M Like $m, for vict_obj.*
$s <20>his,<2C> <20>her,<2C>or <20>it,<2C> depending on the gender of ch. 
$S Like $s, for vict_obj.* 
$e <20>he,<2C> <20>she,<2C> <20>it,<2C> depending on the gender of ch. 
$E Like $e, for vict_obj.*
$o Name or <20>something<6E> for obj, depending on visibility. 
$O Like $o, for vict_obj.*
$p Short description or <20>something<6E> for obj. 
$P Like $p for vict_obj.*
$a <20>an<61> or<6F>a<EFBFBD>, depending on the first character of obj<62>s name. 
$A Like $a, for vict_obj.*
$T Prints the string pointed to by vict_obj.*
$F Processes the string pointed to by vict_obj with the fname() function prior
to printing.*
$u Processes the buffer and uppercases the first letter of the previous word 
(the word immediately prior to the control code). If there is no previous word,
no action is taken. 
$U Processes the buffer and uppercases the first letter of the following word 
(the word immediately after to the control code). If there is no following 
word, no action is taken. 
$$ Print the character <20>$<24>. 

NOTE*: vict_obj must be a pointer of type struct char_data *. 

1.5 Examples 
In all of the following examples, ch points to male character Ras, vict always
points to the female character Anna. obj1 is a small sword, and obj2 is a small
sack. 

act("$n smiles happily.", TRUE, ch, NULL, NULL, TO_ROOM); 
This is sent to the room that Ras is currently in, and the string that they see
if they can see him is: 
Ras smiles happily. 
If a character cannot see Ras, then they will not see the action at all. 

act("You kiss $M.", FALSE, ch, NULL, vict, TO_CHAR); 
In this action, Ras is kissing Anna, and Ras will see: 
You kiss her. 

act("$n gives $p to $N.", TRUE, ch, obj1, vict, TO_NOTVICT); 
The output from this string is sent to everyone in the room except for Ras and 
Anna. Of course, if they cannot see Ras, then they will not see any output at 
all. The string that each character in the room will see is: 
Ras gives a small sword to Anna. 
If a character cannot see Anna, then someone will be used in place of her name,
and if they cannot see the small sword, then something will be used in its 
place. 

act("$n gives you $p.", FALSE, ch, obj1, vict, TO_VICT); 
Similar to the prior example, this is the output for Anna. She will see this 
even if she cannot see Ras, and the output that she will get is: 
Ras gives you a small sword. 
Just as per the last example, if she cannot see Ras, someone will be used in 
place of his name, and if she cannot see the sword, then something will be 
used in its place. 

act("$n puts $p in $s $O.", TRUE, ch, obj1, obj2, TO_ROOM); 
This action uses two objects rather than two characters, and is displayed to 
the entire room (with the exception of Ras of course). If the character can 
see Ras, they will see: 
Ras puts a small sword in his small sack. 
Otherwise, they will see nothing. Again, as per the prior two examples, 
something will be used in place of any objects that the viewing character 
cannot see. 

act("The $F opens quietly.", FALSE, ch, NULL, EXIT(ch, door)->keyword, TO_ROOM); 
If the keywords for the door were gate wooden, then this would send the output 
string of: 
The gate opens quietly. 
to all of the characters in the room with the exception of Ras. 

In addition to these examples, a multitude of other examples can be found 
scattered throughout the tbaMUD source code.