\documentclass[11pt]{article}
\usepackage{url}
\usepackage{times}
\usepackage[T1]{fontenc}
\usepackage{varioref}
\usepackage{multicol}
% Document typeset from the original document that was typeset by Jeremy Elson.
% This document typeset by Alex Fletcher <furry@circlemud.org> on Dec 4/2001

\addtolength{\topmargin}{-.5in}       % repairing LaTeX's huge  margins...
\addtolength{\textheight}{1in}        % more margin hacking
\addtolength{\textwidth}{1in}         % and here...
\addtolength{\oddsidemargin}{-0.5in}
\addtolength{\evensidemargin}{-0.5in}
\setlength{\parskip}{\baselineskip}
\setlength{\parindent}{20pt}
\newenvironment{Ventry}[1]
  {\begin{list}{}{\renewcommand{\makelabel}[1]{\textsf{##1:}\hfil}
    \settowidth{\labelwidth}{\textsf{#1:}}
    \setlength{\leftmargin}{\labelwidth}
    \addtolength{\leftmargin}{\labelsep}
  }
  }
  {\end{list}}

\title{The \texttt{act()} Function}
\author{Alex Fletcher\\
{\it Based on text from the DikuMud authors}}
\begin{document}

\maketitle

\begin{abstract}
This document is intended to give an overview of the \texttt{act()} function and give a summary of the various flags and the associated descriptive control characters.  The \texttt{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.
\end{abstract}

\tableofcontents

\section{The \texttt{act()} Function}
\subsection{Overview}\label{overview}
The \texttt{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 -- designated by control characters -- 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.

\subsection{The Function}\label{function}
The \texttt{act()} function is found in the \texttt{comm.c} source file and is described as:
\begin{verbatim}
  void act(const char *str, int hide_invisible, struct char_data *ch,
           struct obj_data *obj, const void *vict_obj, int type)
\end{verbatim}
These pieces are used as follows:
\begin{Ventry}{hide\_invisible}
\item[str] This is the basic string, a null terminated character array, including control characters (see section~\vref{controlcharacters}~`Control Characters'), to be sent to characters designated by the targets.
\item[hide\_invisible] A \texttt{TRUE} or \texttt{FALSE} value indicating whether or not to hide the entire output from any characters that cannot see the ``performing character''.
\item[ch] The ``performing character''.  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.
\item[obj] An object (an actual item -- \texttt{obj\_data}) used in the course of the action.
\item[vict\_obj] This can be either a character involved in the action, another object, or even a predefined string of text.
\item[type] One of \texttt{TO\_VICT}, \texttt{TO\_CHAR}, \texttt{TO\_NOTVICT}, or \texttt{TO\_ROOM}. This indicates who it is to be targeted at.
\end{Ventry}

\subsection{The Parameters}\label{parameters}
Of the various parameters passed to the \texttt{act()} function, the \texttt{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 \texttt{ch} parameter.  This, as mentioned, points to the central character associated with the output string and action.
\par
\texttt{obj} is an object of type \texttt{struct obj\_data~*} that is passed to the function.  If there is no object to pass to the function, then a \texttt{NULL} or \texttt{0} should be passed in this location.
\par
The next parameter \texttt{vict\_obj} can be a number of things ranging from a game object (\texttt{strcut obj\_data~*}), through to a character (\texttt{struct char\_data~*}), and even a null terminated character array (\texttt{char~*}).
\par
Do note, however, that \texttt{obj} and \texttt{vict\_obj} are both ignored if there is no control character reference (see section~\vref{controlcharacters}~`Control Characters') to them and the \texttt{type} is set to \texttt{TO\_ROOM} or \texttt{TO\_CHAR}.  In these cases, \texttt{NULL} should be supplied as the input to the function.
\par
The \texttt{hide\_invisible} flag dictates whether or not the action output should be hidden from characters that cannot see \texttt{ch}.  If the flag is set to \texttt{TRUE} (non-zero), then this is the case.
\par
The \texttt{type} determines who the output is to be sent to.  There are four options for this (all defined in \texttt{comm.h}) described below:
\begin{Ventry}{TO\_NOTVICT}
\item[TO\_ROOM] This sends the output to everybody in the room, except \texttt{ch}.
\item[TO\_VICT] This option sends the output to the character pointed to by \texttt{vict\_obj}. Obviously, in this case, \texttt{vict\_obj} must point at a character rather than an object.
\item[TO\_NOTVICT] In another case where \texttt{vict\_obj} must point to a character.  This sends the output to everybody in the room except \texttt{ch} and \texttt{vict\_obj}.
\item[TO\_CHAR] Finally, this option sends the output to the \texttt{ch}.
\item[TO\_SLEEP] This is a special option that must be combined with one of the above options.  It tells \texttt{act()} that the output is to be sent even to characters that are sleeping.  It is combined with a bitwise `or'.  For example, \texttt{TO\_VICT $|$ TO\_SLEEP}.
\end{Ventry}
When the string has been parsed, it is capitalized and a newline is added.

\subsection{Control Characters}\label{controlcharacters}
In a manner similar to the \texttt{printf()} family of functions, \texttt{act()} uses control characters.  However, instead of using the {\bf \%} symbol, \texttt{act()} uses the {\bf \$} character to indicate control characters.
\begin{description}
\item[\$n] Write name, short description, or ``{\it someone}'', for \texttt{ch}, depending on whether \texttt{ch} is a PC, a NPC, or an invisible PC/NPC.
\item[\$N] Like {\bf \$n}, except insert the text for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must point to an object of type \texttt{struct char\_data~*}.
\item[\$m] ``{\it him},'' ``{\it her},'' or ``{\it it},'' depending on the gender of \texttt{ch}.
\item[\$M]  Like {\bf \$m}, for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{struct char\_data~*}.
\item[\$s] ``{\it his},'' ``{\it her},'' or ``{\it it},'' depending on the gender of \texttt{ch}.
\item[\$S] Like {\bf \$s}, for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{struct char\_data~*}.
\item[\$e] ``{\it he},'' ``{\it she},'' ``{\it it},'' depending on the gender of \texttt{ch}.
\item[\$E] Like {\bf \$e}, for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{struct char\_data~*}.
\item[\$o] Name or ``{\it something}'' for \texttt{obj}, depending on visibility.
\item[\$O] Like {\bf \$o}, for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{struct obj\_data~*}.
\item[\$p] Short description or ``{\it something}'' for \texttt{obj}.
\item[\$P] Like {\bf \$p} for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{struct obj\_data~*}.
\item[\$a] ``{\it an}'' or ``{\it a}'', depending on the first character of \texttt{obj}'s name.
\item[\$A] Like {\bf \$a}, for \texttt{vict\_obj}. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{struct obj\_data~*}.
\item[\$T] Prints the string pointed to by \texttt{vict\_obj}.  NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{char~*}.
\item[\$F] Processes the string pointed to by \texttt{vict\_obj} with the \texttt{fname()} function prior to printing. NOTE: \texttt{vict\_obj} must be a pointer of type \texttt{char~*}.
\item[\$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.
 \item[\$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.
\item[\$\$] Print the character `\$'.
\end{description}

\subsection{Examples}\label{examples}
In all of the following examples, \texttt{ch} points to male character {\bf Ras}, \texttt{vict} always points to the female character {\bf Anna}.  \texttt{obj1} is {\it a small sword}, and \texttt{obj2} is {\it a small sack}.

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

\begin{verbatim}
  act("You kiss $M.", FALSE, ch, NULL, vict, TO_CHAR);
\end{verbatim}
In this action, {\bf Ras} is kissing {\bf Anna}, and Ras will see:
\begin{quote}
{\em You kiss her.}
\end{quote}

\begin{verbatim}
  act("$n gives $p to $N.", TRUE, ch, obj1, vict, TO_NOTVICT);
\end{verbatim}
The output from this string is sent to everyone in the room except for {\bf Ras} and {\bf 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:
\begin{quote}
{\em Ras gives a small sword to Anna.}
\end{quote}
If a character cannot see Anna, then {\it someone} will be used in place of her name, and if they cannot see the small sword, then {\it something} will be used in its place.

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

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

\begin{verbatim}
  act("The $F opens quietly.", FALSE, ch, NULL, EXIT(ch, door)->keyword, TO_ROOM);
\end{verbatim}
If the keywords for the door were {\it gate wooden}, then this would send the output string of:
\begin{quote}
{\em The gate opens quietly.}
\end{quote}
to all of the characters in the room with the exception of Ras.
\par
In addition to these examples, a multitude of other examples can be found scattered throughout the CircleMUD source code.
\appendix
%
% The following is a reiteration of some of the above sections into a one-page, two column
% quick reference sheet.
%
\newpage
\pagestyle{empty}
\setlength{\topskip}{0cm}
\setlength{\footskip}{0cm}
\section{\texttt{act()} Reference Sheet}
\begin{verbatim}
  void act(const char *str, int hide_invisible, struct char_data *ch,
           struct obj_data *obj, const void *vict_obj, int type)
\end{verbatim}
\begin{Ventry}{hide\_invisible}
\item[str] String to be parsed.
\item[hide\_invisible] If \texttt{TRUE}, hide from characters that cannot see the ``performer''.
\item[ch] The ``performer''.  Also determines the room for the output.
\item[obj] \texttt{struct obj\_data~*}
\item[vict\_obj] Predefined string of text, or second character or object.
\item[type] \texttt{TO\_VICT}, \texttt{TO\_CHAR}, \texttt{TO\_NOTVICT}, or \texttt{TO\_ROOM}.
\end{Ventry}
 \vspace*{0.5cm}
\renewcommand{\columnseprule}{0.5pt}
\begin{multicols}{2}
\begin{description}
\item[\$a] ``{\it an}'' or ``{\it a}'', depending on the first character of \texttt{obj}'s name.
\item[\$A] Like {\bf \$a}, for \texttt{vict\_obj} which is of type \texttt{struct obj\_data~*}.
\item[\$e] ``{\it he},'' ``{\it she},'' ``{\it it},'' depending on the gender of \texttt{ch}.
\item[\$E] Like {\bf \$e}, for \texttt{vict\_obj} which is of type \texttt{struct char\_data~*}.
\item[\$F] Processes the string pointed to by \texttt{vict\_obj} (pointer of type \texttt{char~*}) with the \texttt{fname()} function prior to printing.
\item[\$n] Write name, short description, or ``{\it someone}'', for \texttt{ch}, depending on whether \texttt{ch} is a PC, a NPC, or an invisible PC/NPC.
\item[\$N] Like {\bf \$n}, except insert the text for \texttt{vict\_obj} which is of type \texttt{struct char\_data~*}.
\item[\$m] ``{\it him},'' ``{\it her},'' or ``{\it it},'' depending on the gender of \texttt{ch}.
\item[\$M]  Like {\bf \$m}, for \texttt{vict\_obj} which is of type \texttt{struct char\_data~*}.
\item[\$o] Name or ``{\it something}'' for \texttt{obj}, depending on visibility.
\item[\$O] Like {\bf \$o}, for \texttt{vict\_obj} which is of type \texttt{struct obj\_data~*}.
\item[\$p] Short description or ``{\it something}'' for \texttt{obj}.
\item[\$P] Like {\bf \$p} for \texttt{vict\_obj} which is of type \texttt{struct obj\_data~*}.
\item[\$s] ``{\it his},'' ``{\it her},'' or ``{\it it},'' depending on the gender of \texttt{ch}.
\item[\$S] Like {\bf \$s}, for \texttt{vict\_obj} which is of type \texttt{struct char\_data~*}.
\item[\$T] Prints the string pointed to by \texttt{vict\_obj} which is of type \texttt{char~*}.
\item[\$u] Processes the buffer and uppercases the first letter of the previous word (the word immediately prior to the control code).
 \item[\$U] Processes the buffer and uppercases the first letter of the following word (the word immediately after to the control code).
\item[\$\$] Print the character `\$'.
\end{description}


\end{multicols}
\end{document}
\end