<html> <head> <title>Output Functions</title> <link rel="stylesheet" type="text/css" href="doc.css" title="Documentation Standard Style"> </head> <body bgcolor="#ffffff"> <table class="main" width="600" border="0"> <tr><td> <div align="right"> DalekenMUD 1.12 documentation. <br>Updated 7 June 2000. <br>Based on original Envy 2.2 documentation. </div> </td></tr> <tr><th class="heading"> <h1>Output Functions</h1> </th></tr> <tr><td> <p>This document covers the main functions for sending information to a character. The central output functions are <code>send_to_char</code>, <code>send_to_all_char</code>, and <code>act</code>. These functions give all of the neccessary flexibility in sending text to a player.</p> </td></tr> <tr><th class="heading"> <h2>send_to_char</h2> </th></tr> <tr><td> <p>The interface for <code>send_to_char</code> is: <blockquote><code> void send_to_char( const char *txt, CHAR_DATA *ch ) </code></blockquote> The string <code>txt</code> is sent to the character <code>ch</code>. Note that you will have to send the character an end-of-line sequence as well such as <code>"\n\r"</code>.</p> </td></tr> <tr><th class="heading"> <h2>send_to_all_char</h2> </th></tr> <tr><td> <p>The function <code>send_to_all_char</code> does away with multiple blocks of code in sending to all active descriptors. This is useful for functions like system warnings and echos.</p> <p>The interface for <code>send_to_all_char</code> is: <blockquote><code> void send_to_all_char( const char *text ) </code></blockquote> The string <code>text</code> is sent to all characters with active descriptors.</p> </td></tr> <tr><th class="heading"> <h2>charprintf</h2> </th></tr> <tr><td> <p>The interface for <code>charprintf</code> is: <blockquote><code> void send_to_char( CHAR_DATA *ch, const char *txt, ... ) </code></blockquote> This function operates much like the <code>send_to_char</code> function but it allows you to use a <code>printf</code> style format. This removes the need for calls to <code>sprintf</code> and the need for buffer strings. </td></tr> <tr><th class="heading"> <h2>act</h2> </th></tr> <tr><td> <p>The function <code>act</code> is much hairier. The following section is a precise reference guide. If you don't already have some notion of what <code>act</code> format strings look like, then you should read some code which uses <code>act</code> (such as some of the spell functions in magic.c) to get a concrete introduction to this function.</p> <blockquote><code> void act( const char *format, CHAR_DATA *ch, const void *arg1, const void *arg2, int type ) </code></blockquote> <dl> <dt><code>const char *format;</code></dt> <dd> This is a format string, with formatting specifications introduced by <code>$</code> (just as <code>printf</code> introduces its formatting sequences with <code>%</code>). Typically this is a complete sentence with a subject and an object. This format string does not need to be terminated with <code>"\n\r"</code>. </dd> <dt><code>CHAR_DATA *ch;</code></dt> <dd> This is the subject of the sentence. It MUST be included. </dd> <dt><code>const void *arg1;</code></dt> <dd> This is usually the object of the sentence, though its meaning will depend on what you want to print out. This may be an object or possibly a text string. </dd> <dt><code>const void *arg2;</code></dt> <dd> This is the target of the sentence, as well as possibly the object of the sentence. This may be either a victim, an object, or possibly a text string. </dd> <dt><code>int type;</code></dt> <dd> This is the 'to' type of the sentence. For 'act', values are: <div align="center"><table width="100%" cellspacing="2" cellpadding="2"> <tr> <td width="30%"><code>TO_CHAR</code></td> <td>Send only to <code>ch</code>.</td> </tr> <tr> <td width="30%"><code>TO_VICT</code></td> <td>Send only to <code>arg2</code> interpreted as a character (and then only if arg2 != ch).</td> </tr> <tr> <td width="30%"><code>TO_ROOM</code></td> <td>Send to all chars in room except <code>ch</code>.</td> </tr> <tr> <td width="30%"><code>TO_NOTVICT</code></td> <td>Send to all chars in room except <code>ch</code> and <code>arg2</code>.</td> </tr> <tr> <td width="30%"><code>TO_ALL</code></td> <td>Send to all chars in the room.</td> </tr> </table></div> </dd> </dl> <p>In <code>act</code>, only characters in the same room as <code>ch</code> are considered. (Thus <code>ch</code> must always be a legitimate character whose location is not NOWHERE). If the target character meets the <code>type</code> requirements, then the formatting string <code>format</code> is used to construct an output string, with <code>$</code> sequences substituted using values from <code>ch</code>, <code>arg1</code>, and <code>arg2</code>. If the target characters of the message are asleep then they will get the message, but other characters have to be awake to receive the message.</p> <p>In the substitution of <code>$</code> sequences, attention is paid to visibility by calling <code>can_see</code> and <code>can_see_obj</code> as needed.</p> <p>The first character of the output string is always capitalized.</p> </td></tr> <tr><th class="heading"> <h2>The '$' sequences</h2> </th></tr> <tr><td> Here are all the <code>$</code> sequences supported by 'act': <dl> <dt><code>$t</code></dt> <dd>Result is simply the <code>arg1</code> argument interpreted as a string.</dd> <dt><code>$T</code></dt> <dd> Result is simply the <code>arg2</code> argument interpreted as a string. </dd> <dt><code>$a</code></dt> <dd> Result is 'a' or 'an' depending on the first letter of <code>arg1</code> (interpreted as a string). If you can't use $t, you can't use $a. </dd> <dt><code>$A</code></dt> <dd> Result is 'a' or 'an' depending on the first letter of <code>arg2</code> (interpreted as a string). If you can't use $T, you can't use $A. </dd> <dt><code>$n</code></dt> <dd> Result is the name of <code>ch</code>. If <code>ch</code> is not visible to the target character, result is the string 'someone'. </dd> <dt><code>$N</code></dt> <dd> Result is the name of <code>arg2</code> (considered as a victim). If <code>arg2</code> is not visible to the target character, result is the string 'someone'. </dd> <dt><code>$e</code></dt> <dd> Result is 'he', 'she', or 'it', depending on the sex of <code>ch</code>. </dd> <dt><code>$E</code></dt> <dd> Result is 'he', 'she', or 'it', depending on the sex of <code>arg2</code> (considered as a victim). </dd> <dt><code>$m</code></dt> <dd> Result is 'him', 'her', or 'it', depending on the sex of <code>ch</code>. </dd> <dt><code>$M</code></dt> <dd> Result is 'him', 'her', or 'it', depending on the sex of <code>arg2</code> (considered as a victim). </dd> <dt><code>$s</code></dt> <dd> Result is 'his', 'her', or 'its', depending on the sex of <code>ch</code>. </dd> <dt><code>$S</code></dt> <dd> Result is 'his', 'her', or 'its', depending on the sex of <code>arg2</code> (considered as a victim). </dd> <dt><code>$r</code></dt> <dd> Result is 'sir', 'madam', or 'buddy', depending on the sex of <code>ch</code>. </dd> <dt><code>$R</code></dt> <dd> Result is 'sir', 'madam', or 'buddy', depending on the sex of <code>arg2</code> (considered as a victim). </dd> </dd> <dt><code>$g</code></dt> <dd> Result is the deity of <code>ch</code>s religion if they follow a religion, otherwise "God". </dd> <dt><code>$G</code></dt> <dd> Result is the deity of <code>arg2</code>s religion if they follow a religion, otherwise "God". </dd> <dt><code>$p</code></dt> <dd> Result is the short description of <code>arg1</code>, considered as an object. If <code>arg1</code> is invisible to the target character, result is the string 'something'. </dd> <dt><code>$P</code></dt> <dd> Result is the short description of <code>arg2</code>, considered as an object. If <code>arg2</code> is invisible to the target character, result is the string 'something'. </dd> <dt><code>$d</code></dt> <dd> Result is the first word in <code>arg2</code>, considered as a string. If 'vo' is <code>NULL</code>, result is the string 'door'. This is meant for extracting the name from a door's keyword list, but may be used in general for other keyword lists. </dd> </dl> </td></tr> </table> </body> </html>