tbamud/doc/coding.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

How To Convert Your Ideas Into Reality 
A tbaMUD Coding Manual 
Originally by Jeremy Elson and the rest of the CircleMUD Group 
Section 4 written by Luis Pedro Passos Carvalho 

This is a guide to writing C code for use with tbaMUD. It includes a description
of commonly used functions, tips on how to add new commands and spells, and 
other commonly asked coding questions. Good familiarity with both C and UNIX is 
assumed, although system-level UNIX C programming skills are not required. The 
intended audience is for tbaMUD coders, and this document does not cover 
building. See building.txt for details on that. 

More information about tbaMUD, including up-to-date versions of this 
documentation can be found online at http://tbamud.com

Contents 

1 Introduction

2 Overview and Coding Basics
2.1 An Internet Server Tutorial
2.2 The Way Things Work Overview
2.2.1 Boot Phase
2.2.2 Interactive Phase
2.2.3 Shutting Down
2.3 Global Variables
2.3.1 World Variables
2.3.2 Object Instance Lists
2.3.3 Other
2.4 Frequently Used Functions
2.4.1 Basic String Handling
2.4.2 Argument Processing
2.4.3 Character Output (Hello, world!)
2.4.4 File Input
2.4.5 Utility Functions
2.4.6 Character/Object Manipulation
2.4.7 Object Locating
2.4.8 Character Locating
2.4.9 Violence

3 Adding Features
3.1 Adding Commands
3.2 Adding Socials
3.3 Adding Spells
3.3.1 Template Spells
3.3.2 Manual Spells
3.4 Adding Skills
3.5 Adding Classes
3.6 Adding Levels
3.7 Adding Color 

4 Writing Special Procedures
4.1 Overview of Special Procedures
4.2 Pulsed vs. Command-Driven Special Procedures
4.2.1 Pulsed Special Procedures
4.2.2 Command Driven Special Procedures
4.2.3 Preparing for all occurrences
4.3 Relating Special Procedures to Objects, Mobiles, and Rooms
4.4 The Special Procedure Function Header
4.5 The Special Procedure Return Value

1 Introduction 

When DikuMUD was first released in 1990, the authors were rightly more concerned 
with getting their product released than with little cosmetic details. Between 
writing 25,000 lines of C code and building the entire DikuMUD world, complete with
objects, rooms, and monsters, it’s understandable that making the code portable or
clean was not at the top of the list of their priorities. Most DikuMUD 
distributions were not portable and had a number of bad bugs and even syntax errors
which prevented the code from compiling at all. If a potential MUD implementor 
wanted to run a Diku, an excellent knowledge of C was necessary, because the MUD 
simply wouldn’t run otherwise. 

Now the situation is much different. With the proliferation of user-friendly 
codebases any Average Joe can just type “make” and inflict yet another MUD on the 
world. Therefore, the number of truly unique MUDs as a fraction of the total is 
dropping drastically because coding experience is no longer a prerequisite to being
able to put a MUD up on the ‘Net. Some people may tell you that you don’t need to
know how to code in order to run a MUD – don’t believe them. Those people are 
wrong. 

If you want your MUD to succeed and flourish, you’ll have to know how to code in C. 
Otherwise, your MUD will be exactly like every other MUD out there. You’re not the
only person who knows how to type make! Although the quality and originality of your
areas is also very important, it is the code and trigedit that transforms the
areas from lifeless text files into a living, breathing virtual world. If you don’t
know how to code, you won’t be able to add new features, respond to requests of 
your players, add new world flags for your area builders, or even fix the simplest 
of bugs. Running a MUD without knowing how to code is certainly a recipe for 
disaster. If you’re a great game-player and have some terrific ideas about how a
MUD should work, but don’t know how to code, you should either learn or find a good
coder who can join your team. Don’t assume that you can get away with running a MUD
without knowing C – you can’t. Not for very long, anyway. 

This document won’t teach you how to program in C; you’ll have to learn that on 
your own. Instead, it will try to familiarize you with the way tbaMUD’s code is 
structured so that you can put your C skills to good use. Even for the best 
programmers, it takes a while to “get into” a program and feel comfortable enough 
with the way it works to start modifying it. Hopefully, by reading this manual, 
your breaking-in period for getting to know tbaMUD will be minimized. 

tbaMUD consists of about 50,000 lines of moderately dense C code, so you shouldn’t 
expect familiarity to come overnight. The best way to learn is to DO. Get your 
hands dirty! Don’t be afraid to tinker with things. Start small by modifying 
existing functions. Then, work your way up to creating new functions by copying old 
ones. Eventually you’ll be able to write completely original functions, and even 
tear some of tbaMUD’s native functions out as you realize completely new ways of 
implementing them! But you should learn to walk before you try to run. 

Most of all, try to remember that coding for a MUD should be fun. It can sometimes 
be easy to lose site of the ultimate goal of personal enjoyment that MUDs are 
supposed to provide, particularly when they start to get crushed under the weight 
of their own politics or the egos of their administrators. If you enjoy coding, but 
find yourself spending more time on politics than you are on code, don’t be afraid 
to restructure your MUD or even remove yourself as Imp to a lower wizard position 
which requires less politics. 

A final thought: nothing will turn potential players away from your MUD more than 
logging in and finding that it’s exactly like half the other tbaMUDs out there. 
Strive to show the world something new and unique. And may the source be with you. 

2 Overview and Coding Basics 

Before getting down to the details of learning how to write code, we will first 
examine generally what a MUD is and what it does, to give you an overview of what 
type of program you’re working with. 

The first section, “An Internet Server Tutorial”, describes how Internet servers 
such as tbaMUD work. It contains interesting background material if you’d like a 
deeper understanding of how the MUD actually interacts with the Internet and the 
computer on which it runs, but little practical coding advice. So, if you’re 
reading this document purely to learn how to write MUD code, you should skip to the 
second section. 

2.1 An Internet Server Tutorial 

An Internet “server” is a program which provides some service to Internet users 
(called “clients”). There are many different types of servers on the Internet. FTP 
servers allow you to transfer files between a remote computer and your own. Telnet 
servers allow you to connect to remote machines. News servers allow you to read 
USENET news. Similarly, tbaMUD is a server which allows you to play a game. 

However, MUDs such as tbaMUD differ from most Internet servers in several very 
important ways. When ten different people connect to tbaMUD, they can all interact 
with one another. tbaMUD – a single program – must be aware of many users at the 
same time. On the other hand, most other Internet servers such as FTP servers are 
written to only be aware of one user at a time. If more than one user wants to use 
an FTP server simultaneously, the operating system runs two copies of the server: 
one to handle each user. Each individual copy of the FTP server is not aware of 
anything but the single user it has been assigned to serve. 

This approach of making one copy of the program per user works quite well with an
FTP server because all the users of an FTP server do not need to interact with one 
another. However, this approach does not work well at all with MUDs, because it 
makes the task of allowing users to communicate and interact with each other quite 
difficult. 

In addition, most simple Internet servers do not actually contain any network code 
– the Internet superserver (inetd) contains most of the code to perform the network 
magic, allowing the individual servers such as FTP and telnet to be network-unaware 
for the most part, simply reading from standard input and writing to standard 
output as if a user at a normal terminal was using the program. The Internet 
superserver is responsible for setting up standard input and standard output so
that they are actually network sockets and not a text terminal. 

To sum up, a MUD such as tbaMUD does not have the luxury of being able to handle 
multiple users by allowing the operating system to make many copies of the MUD. The 
MUD itself must be capable of handling many users. The MUD also doesn’t have the 
luxury of allowing a pre-written program such as inetd to set up its network 
connections. The MUD itself is responsible for setting up and keeping track of all 
of its own network connections, as well as splitting its time evenly among all of 
its players. The MUD cannot stop and wait for a player to type something – if 
it stops and waits for that player, the MUD will appear to have frozen from the 
point of view of all the other players! 

Let’s make this idea more concrete with an example. Imagine that your first 
programming assignment in a C class is to write a simple calculator that gets two 
numbers from a user as input, multiplies them together, and then prints the product 
on the screen as output. Your program would probably be quite simple: it would 
prompt the user for the two numbers, then stop and wait while the user types the
numbers in. 

Now, imagine that your project is to write a program that lets 10 people 
simultaneously connect to your calculator and multiply their own numbers together. 
Forget for a moment the problem of how to write the network code that allows people 
to connect to your program remotely. There is a more fundamental problem here: your 
original strategy of stopping and waiting for the user to type input won’t work any 
more. With one user, that worked fine. But what will happen with 10 users? 

Let’s say your program stops and waits for the first user to type something. Now, 
what happens if the second user types something in the meantime? The program will 
not respond to the second user because it is still waiting for a response from the 
first user. Your simple calculator has suddenly become much more complex – now, it 
must constantly cycle through all users, asking the operating system if any one of 
them have typed something, without ever stopping to wait for a single user. When 
input comes in from any one of the users, your program must immediately process it 
and move on to the next user. 

Let’s say that you’ve written a program which does the cycling among users 
described in the previous paragraph. Now, imagine that the operating system tells 
you that User 4 has just typed the number 12. You might be able to see the second 
problem: what does that 12 mean? Is 12 the first or second multiplicand for your 
calculator? Should you immediately multiply the 12 with some other number, or store 
it and wait for another number to multiply by 12? 

Your simple calculator has become more complicated again! Now, in addition to 
cycling through all users to check if any have typed anything, you must remember 
the STATE each user is in. In other words, each user might start out in a state 
called “Waiting for First Number.” If a user types a number while she’s in the 
“Waiting for First Number” state, you’d store her number somewhere and move her 
into the “Waiting for Second Number” state. If she types a number while in the 
“Waiting for Second Number” state, you’d retrieve the first number from memory, 
multiply it by the number just typed, and print the result. Of course, each user 
can be in a different state – there is no global state shared by all users. 

Now, you might be able to see how this calculator example relates to tbaMUD. Let’s 
say that the MUD receives the string, “Sleep” from a user. What should tbaMUD do 
with this string? Maybe the user is trying to log in, typing her name which happens 
to be “Sleep”. Maybe the user is typing in her password. Maybe the user is already 
logged in, and is trying to go to sleep! Just like with our calculator, the MUD 
knows how to interpret data it receives from users by examining the users’ state. 

You can see a list of all possible players’ states in structs.h (they all start 
with “CON_”). All users are put into the CON_GET_NAME state when they first connect 
to the MUD. CON_GET_NAME simply means that the MUD is waiting for the user to type 
her name, at the “By what name do you wish to be known?” prompt. The normal state 
that most players are in most of the time is the CON_PLAYING state, which indicates
that they have already logged in and are playing normally. 

Now, let’s go back to our previous example and trace exactly what happens when you 
type “Sleep”. First, you type “Sleep.” Then, your computer sends the string “Sleep” 
over the Internet to the computer on which the MUD is running. Within one tenth of 
a second, tbaMUD checks with the operating system to see if any of its users have 
typed anything. When tbaMUD gets to you, it asks the operating system, “Has this 
user typed anything?”. Since you typed “Sleep”, the operating system will respond, 
“Yes!”. The MUD will then ask the operating system to deliver the message and will 
read your message of “Sleep”. (All the magic of talking to the operating system and 
checking to see whether or not you’ve typed anything happens in comm.c.) 

So, now that the MUD now knows that you’ve typed “Sleep”, it has to decide which of 
several functions in interpreter.c should get control next. This depends on what 
state you’re in. If you’re in the normal PLAYING state, it will pass control to a 
function called command_interpreter, which will interpret “Sleep” as a normal 
command and put you to sleep. If you’re in any other state, control goes to a 
function called nanny, which is responsible for handling all sockets in any state 
other than PLAYING. nanny checks what state you’re in and acts accordingly. For 
example, if you’re in the GET_NAME state, nanny activates the code to check whether 
or not "Sleep" is the name of a known player (in which case it puts you into the 
state asking for your password), or a new player (in which case it’ll ask you the 
question, “Did I get that right, Sleep?”.) 

In a nutshell, that’s how tbaMUD interacts with the Internet. If you don’t 
understand all the details, don’t worry – it’s not necessary to understand things 
on this level to be a successful MUD coder. If you are interested, however, there 
are some excellent references you can read for more information: 

"Internetworking with TCP/IP" by Douglas Comer. The canonical text describing 
Internet protocols; comes in three volumes. Volume 1 gives an excellent description 
of how Internet protocols, error handling, routing, and nameservice works. Volume 3 
describes specifics of writing Internet Servers in C. (Volume 2 describes how 
Internet protocols are implemented by operating systems and is not as apropos to 
this discussion.) 

"Advanced Programming in the UNIX Environment" by Richard Stevens. An excellent 
UNIX reference for the serious system programmer. Describes POSIX quite well – 
worth its weight in gold for anyone trying to write portable UNIX applications. 
Sections on signal semantics and non-blocking I/O particularly apropos to Internet 
servers. 

"UNIX Network Programming" by Richard Stevens. Similar to Volume 3 of Comer’s 
series, but goes into more detail in several areas, and offers more practical code 
examples. 

2.2 The Way Things Work – Overview 

2.2.1 Boot Phase 
tbaMUD is a complex system of code, data files, and external input all interacting 
in fun, unexpected ways. As with any program, it doesn’t just spring into existence 
ready to play, but must cull information from the administrator and the system 
itself to determine how it should begin. 

The first action by tbaMUD on startup is to check for the existence of any 
command-line parameters, as seen in the main() function. These can have radical 
impact on tbaMUD’s operation so it must check them before any other action. For 
example, tbaMUD might be given the -d parameter, specifying an alternate library 
directory, so it cannot have done any processing on data files prior to the 
command-line reading. 

After finishing the immediate input, the next step is to be able to communicate to 
the outside world. The communication may be either the “standard error” file 
descriptor or a file, depending on the command-line options and whichever tbaMUD 
succeeds in opening. 

From here there are two possible branches depending on administrator input. If 
“Syntax Check” mode is enabled, then we load only the world. Otherwise, we start 
initializing the game in preparation for loading the world and accepting players. 
Since syntax checking is a subset of the normal startup phase, this document shall 
follow only the most common action of a non-syntaxcheck boot. 

A few minor items precede the loading of the world: initializing the random number
generator, creating the .killscript file, finding (or guessing) the maximum number 
of players the operating system will allow simultaneously, and opening the file 
descriptor later to be used to accept connections. This early opening of the 
“mother” file descriptor is why there is a period of time during startup where a 
player connection will be accepted but not receive a login prompt. tbaMUD does not 
check for connection attempts while it loads the world database but the operating 
system will complete the connection anyway and post notification to be seen later. 

The world loading starts by reading in the MUD date and a few simple text files for 
player reference. If the date file cannot be loaded, then a default date is 
provided for the calculations. After randomly generating the weather, in the date 
function, the following user text files are loaded: news, credits, mortal and 
immortal message of the day, mortal and immortal help default, message screen, 
general MUD info, wizard list, immortal list, policies, immortal handbook, 
background story, and login greeting screen. These files are reproduced verbatim by 
various user commands and exist for the players and/or administrators to read. The 
MUD doesn’t interpret these in any way. 

Next, the spell definitions are loaded for player use. The spello() function gives 
such important information as casting cost, valid targets (area, self, etc.), spell 
type, valid casting positions (sitting, standing, etc.), spell name, and wear off 
message. Any skill or spell that isn’t set up via mag_assign_spells() will not be 
usable even if appropriate code exists elsewhere that would make it have an effect. 
Any spell defined here that does not have appropriate code elsewhere to handle it 
will do nothing when used. 

As far as the game world, the zones must be loaded first to define the structure of 
the rest of the objects. The lib/world/zon/index file is first consulted for the 
list of zone files that are requested to load. The index.mini file is used in the 
event mini-MUD mode was requested earlier on the command line. Each zone file is 
read in order to pull in the name, description, reset time, room range, and zone 
commands. Any error on loading will result in the MUD aborting startup. The rooms 
are read next from lib/world/wld/indexin the same manner as the zones, with the 
added restriction that each room must fall within the ranges defined by the 
previously-loaded zones. This restriction ensures the code can access the zone 
record of a room without worrying about any rooms not having an associated zone. 

The rooms, as loaded, contain virtual numbers of the rooms they are supposed to 
exit to. It is slow to do virtual to real number translation while the MUD is 
running so all room exits are replaced by their real number equivalents during 
startup. Then the pre-defined starting locations for mortals, immortals, and frozen 
characters are checked to make sure they exist. If the mortal start room does not 
exist, the MUD aborts with an error. A missing immortal or frozen start room is 
redirected to the mortal start room to allow booting to continue. The mortal start 
room must exist in a room file loaded by lib/world/wld/index.mini file for mini-MUD
mode to work. 

Mobiles from lib/world/mob/index and objects from lib/world/obj/index are loaded
afterward. Mobile and object virtual numbers need not correspond to the zone number 
ranges as rooms do but it is encouraged. There are various sanity checks done to 
mobiles and objects that may be printed during startup. Any warnings issued should 
be fixed but should not adversely affect the MUD itself. 

In the same manner as the room number virtual to real translation, the zone reset 
information is also translated. The zone reset structure contains a variety of 
different records so it takes special care to find the appropriate numbers to 
translate from virtual to real. Any virtual numbers that cannot be resolved result 
in that zone command being disabled. Such entries have their type set to ‘*’ to 
avoid the error in the future. 

Triggers from lib/world/trg/index are loaded next. Trigger virtual numbers also
do not need to correspond to the zone number ranges as rooms do but it is encouraged. 
There are various sanity checks done that may be printed during startup. Any 
warnings issued should be fixed but should not adversely affect the MUD itself. 

If special procedures are enabled, as they usually are, the shops are loaded from 
lib/world/shp/index last. Contrary to the rooms and zones, the shops contain lists 
of virtual numbers to sell so any errors will only show up when attempting to use 
the shop. 

The entire help database for tbaMUD is loaded into memory after the world has been 
loaded. This should be about 500kB with the stock tbaMUD help files, but the extra 
memory used saves the MUD from having to manipulate the help files to find the 
appropriate entries after the boot. Even though the help index is stored by 
keyword, any entry having multiple keywords is only stored once for each set. 

An index of the player file is built to allow random access to each player as 
attempt to connect or save. The index stores the player’s name, to search by for 
login, and their ID number, for the mail system to search by. The array index is 
their position in the player file, used for loading and saving. 

Fight messages and socials loaded next are placed by line in their appropriate 
categories. The messages and socials themselves aren’t interpreted beyond their 
placement but they’ll be used extensively in the game. Spells defined earlier from 
mag_assign_spells()get their battle messages from this file. Defaults are provided 
for the battle messages if none is defined. 

Special procedures must be associated with their now-loaded object so they’re 
processed now. A virtual number that cannot be resolved for the special procedure 
elicits a warning message on startup but a missing special procedure function will 
cause a compiler error. Shopkeepers are assigned via assign_the_shopkeepers() 
instead of the standard assign_mobiles() so they can be automatically handled as a 
result of the shop files loaded earlier. 

Since the spells are skills were defined earlier, they can then be assigned to each 
class upon a certain level. The spells and skills given to the various classes only 
depend upon a SPELL_ or SKILL_ definition so the assignment doesn’t need to care if 
it is a generically handled spell or a custom implemented skill. The spells and 
skills may be assigned per the whims of the administrator based on their view of 
the appropriate classes. 

The command and spell tables must be sorted for special circumstances. In the case 
of the command table, it is for the commands input which displays all known 
commands for that player’s level. The spell table is sorted for the practice 
command for easier visual searching by the player. Neither are critical to the 
MUD’s operation but exist for the players’ benefit. 

The tbaMUD mail system saves MUD messages into the players file. It requires an 
index be built on startup to keep track of which blocks are free and which blocks 
have mail messages yet to be delivered. It is also important for the code to check 
the mail file to make sure it hasn’t been corrupted somehow. A report on the number 
of messages present in the system is printed when finished. 

The stupid-people prevention code of site banning and invalid name rejection comes 
next. The site ban code loads a text file list of all sites that have been deemed 
unworthy to connect to the MUD. Invalid name rejection loads a list of substrings 
that must not appear in any character’s name that is being created. The invalid name
list can be found at lib/misc/xnames.

After deleting any expired rent files, the house code loads up any abodes defined. 
It must make sure the rooms still exist and the owner is still in the game before 
setting up the house, atrium, and guest list. Houses are not loaded in mini-MUD 
mode since most of the rooms will likely not exist. 

The final step of the world startup resets every zone. This populates the world 
with mobiles, the mobiles with objects, and places other objects that should be on 
the ground. From here, all zone timers are started and will continue to reset (or 
not) depending on their settings and the number of people in the zone. The time is 
recorded after the zone reset to provide a display of the amount of time the MUD 
has been running. 

Once the world has finished being loaded, tbaMUD tells the operating system what 
sort of signals it wants to receive and which to ignore. It doesn’t want to receive 
a SIGPIPE, which would abort the program whenever it tried to write to a player who 
abruptly disconnected. The user-defined signals (Unix) SIGUSR1 and SIGUSR2 are set 
to re-read the wizard list file and unrestrict the game, respectively. SIGUSR1 is 
sent by autowiz whenever it finishes writing the file. SIGUSR2 may be sent by the 
administrators, using kill -USR2 pid-of-mud, if accidentally banning themselves 
from their own MUD. A 3-minute timer signal prevents the MUD from being stuck in an 
infinite loop forever. The common shutdown signals of SIGHUP (Unix), SIGTERM, and 
SIGINT are mapped to a function that prints their reception and then quits the 
program. The children signal, SIGCHLD, is set up to remove finished 
autowiz instances. 

From here, the .killscript file is removed since if we’ve made it this far, we can 
start successfully. The only thing left now is to enter the interactive phase in 
game_loop(), unless the “Syntax Check” option is enabled. 

2.2.2 Interactive Phase 

Everything that ever happens while the MUD is interactively processing players 
occurs as a descendant of game_loop(). It is responsible for all network I/O, 
periodic tasks, and executing player actions. Consequently, game_loop() has the 
most concentration of newbie-eating code in the code base. Care should be taken to 
fully understand the network I/O infrastructure before trying to modify it. 

Each second of the game is divided into pulses, or points in time that network I/O
is processed and commands run. This works to limit the number of possible commands 
the player can enter per second, such as speed-walking. If the game falls behind 
schedule, it will continuously process the pulses until it has caught up with where 
it is supposed to be. If over 30 seconds have passed, only 30 seconds are processed 
as it would be computationally expensive to do them all. If there isn’t anyone 
connected to the game at all, then the MUD sleeps until someone connects. (“If a 
tree falls in the forest, and no one’s around to hear it...") 

The first task of the pulse is to check for network socket input. First, any 
pending connections are given descriptors to track them. Then any descriptors with 
a socket in the exception set is kicked from the game. Incoming socket data is read 
next, checked for command history or repeat operations, and placed on the 
appropriate descriptor’s command queue. 

Having read commands, they are then set up to be executed. A player must first be 
in a condition to execute those commands, so anyone with a wait state is skipped 
and people idled are pulled back into the game. Depending on the player’s 
activities, the input may be sent through either the message writing system, the 
text pager, the nanny() login sequence, the alias system, or straight to the 
in-game command interpreter. 

In the message writing system (see modify.c), any input, except for an /s at the 
beginning of a line, is simply appended to the string the character has decided to 
edit. An /s at the beginning of a line finishes the editing and returns the player 
to their previous state. Typical uses of this are using OLC, editing the 
character’s description in the menu, or writing to boards and notes in the game. 

The text pager allows the player to scroll around pages of text the MUD has 
produced. It allows refreshing the current page, going back a page, or continuing 
down the page. The text pager returns the player to their previous state upon 
reaching the end of the text or the user telling it to quit. 

The nanny() login sequence guides the player through the initial authentication and 
entering of the game. Here they are prompted for the character name and password. 
Upon successful login they may take actions such as changing their character’s 
description, changing their password, deleting the character, or entering the game. 

The alias system provides a method for player’s to shortcut the typing of commands. 
Each line of input is compared against their existing aliases and, if a match is 
found, the desired alias result is applied to their input and placed on the command 
queue. This process applies before the command interpreter so the game need not 
care what aliases each player may define. 

Finally, the command interpreter pulls off a line of input from the player’s 
command queue. It uses the command table in interpreter.c to find the appropriate 
function, if any, to call for the given command. It does various checks to ensure 
the character is the proper level, in the correct position, and not frozen. Any 
applicable special procedures are checked before running the function in the 
command table. The special procedure may override the function completely, as the 
shopkeepers do with the buy and list commands, or allow it to execute. 

Processing the commands likely generated output for the player so the network 
output is processed next. As much data is sent from the MUD’s output queue as will 
fit in the operating system’s socket buffer for each player. Any output that can’t 
fit in the socket buffer is held until the next pulse when perhaps some of the 
pending output will have been delivered. If any players decided to exit the game or 
otherwise disconnected, their descriptor is marked for removal and the connection 
closed. 

Lastly, the periodic tasks are executed via the heartbeat() function. Each task may 
run every minute, every 5 minutes, every pulse, or any other time increment. The 
list of tasks to run includes: 

Process each zone’s timed updates. 
Disconnect idle descriptors in the login sequence. 
Execute any triggers that are fired.
Determine effects of violence. 
Check the weather. 
Test for magical affect expiration. 
Regenerate health, mana, and movemen
Auto-save characters. 
Saving the MUD time. 
Extracting dead characters. 

If the user-defined signals SIGUSR1or SIGUSR2have arrived, they are processed at 
the bottom of the game loop. Doing such work in the signal handler itself is unsafe 
and could cause unpredictable behavior. 

2.2.3 Shutting Down 

The first responsibility on shutdown is to save the players’ characters to disk. 
tbaMUD tracks which characters have been modified with a PLR_CRASH flag so it only 
needs to save those characters which have changed in the period from the last 
auto-save to the shutdown. 

To disconnect the network connections, each player socket is closed in turn. 
Closing their connection also frees up any memory associated but, unless memory 
allocation tracing is enabled, it’s not necessary since we’re about to exit anyway. 
The “mother” descriptor is closed last, preventing any new players from connecting. 

Left to do are: closing the player files, saving the current MUD time for next 
startup, and logging normal termination of game. Saving the MUD time tries to 
maintain some appearance of continuity in your calendar. 

The final actions before exiting are only significant if the program is running 
with a memory allocation tracer. Here it sets about explicitly freeing every known 
piece of memory previously in use by the MUD. This is done to leave only forgotten 
allocations that may indicate a long-term memory leak in the program. The operating 
system will remove even forgotten memory when the program exits but the information 
may help prevent an ever-increasing memory usage while running. Memory tracing will 
vary depending on your operating system and may not necessarily be available on 
your particular platform. 

That’s it, show’s over. “return 0;’’ 

2.3 Global Variables 
tbaMUD doesn’t use objects in the sense of object-oriented languages so there are 
various global variables kept that must be manipulated in order to change the game 
world. Some are stored as arrays; others as lists. The global variables kept as 
arrays generally have an associated top_of_... function to denote its boundary. 

This is not an exhaustive list but the most frequently encountered of the ones in 
use. A large number of global, constant strings are kept in constants.c but they’re 
simply read from. Also see config.c for a number of configuration global variables. 

2.3.1 World Variables 
struct room_data *world; This array of struct room_data stores all the information 
for the rooms of the MUD universe. In addition to room titles, flags, and 
descriptions, it also contains lists of people, mobiles, objects, and triggers
currently in the rooms. 

struct char_data *mob_proto; While rooms are singular entities, there may be many 
copies of a single mobile running around the game world. The mob_proto array of 
struct char_data contains the base information for all mobiles, as well as being 
used for string sharing amongst all the copies. 

mob_rnum top_of_mobt; The highest valid array index of mob_proto and mob_index is 
stored here. This is not the count of items in the array. That is top_of_mobt + 1. 

struct index_data *mob_index; 

struct index_data *obj_index; The number of instances of each particular mobile or 
object is tracked through these dynamic arrays of struct index_data. This is also 
the location for reverse-mapping the mobile/object real number back into a virtual 
number. In addition, the special procedure and several other variables are stored 
here to avoid keeping redundant data on every mobile/object in the game. 

struct obj_data *obj_proto; This is analogous to mob_proto, except for objects. It 
is kept as a dynamic array of struct obj_data. 

obj_rnum top_of_objt; The highest valid array index of obj_protoand obj_indexis 
stored here. This is not the count of items in the array. That is top_of_objt + 1. 

struct zone_data *zone_table; A dynamic array of type struct zone_data storing all 
the information for zone resets, titles, and room ranges. 

zone_rnum top_of_zone_table; The highest valid array index of zone_table is stored 
here. There are top_of_zone_table + 1 zones in the array. 

2.3.2 Object Instance Lists 

struct descriptor_data *descriptor_list; All players connected to the MUD have a 
descriptor used to send the MUD’s output to and receive player input from. Each 
descriptor does not necessarily have a character (not logged in yet). These are 
stored as a linked list of struct descriptor_data using the nextfield. 

struct char_data *character_list; All player characters and mobiles are kept in a 
linked-list of struct char_data. This list uses the nextfield of the structure. 

struct obj_data *object_list; As all characters and descriptors are kept in a 
linked-list, so too are all the objects in the world kept. This list uses the 
nextfield of struct obj_data. 

2.3.3 Other 

const struct command_info cmd_info[] All user commands are kept in a large array in 
interpreter.c. The ACMD functions use this array, along with the command array 
index variable they are given, to figure out what specific text the user typed to 
get to this command function. This allows them to handle multiple commands with the 
same function with CMD_IS(). The size of the array is static and determined by the 
computer at the time of compilation. 

struct weather_data weather_info Raining? Snowing? Weather changes occurring in 
weather.c are stored in this structure. The sun’s current state (dawn, dusk, etc.) 
is kept here as well. 

struct time_info_data time_info The current date and time of the game world. Used 
in the shop code for opening and closing the stores on schedule. 

2.4 Frequently Used Functions 

2.4.1 Basic String Handling 

int str_cmp (const char *a, const char *b) 

int strn_cmp (const char *a, const char *b, int len) These are portable, 
case-insensitive versions of the strcmp() and strncmp() functions. Like their C 
library counterparts, these functions perform a character-by-character comparison 
and return the difference of the first mismatching characters or zero, if the two 
strings are equal. The strn_cmp() function only compares the first lencharacters of 
the first string to the second string. 

Many platforms have built-in routines to do case-insensitive string comparisons. 
Where applicable, str_cmp() and strn_cmp() are aliases for the platform-specific 
equivalents. On platforms without these functions built-in, tbaMUD will supply a 
working implementation. One should prefer the tbaMUD names to ensure portability 
since it incurs no runtime performance cost. 

int isname (const char *str, const char *namelist) Compare a string, str, to each 
of a list of space-delimited keywords, namelist, using str_cmp(). This is used for 
matching an argument to an object or mobile, which has its keywords arranged like, 
bottle brown beer. 

bool is_abbrev (const char *str, const char *arg2) A case-insensitive substring 
match. Equivalent to: "strn_cmp(needle, haystack, strlen(needle)) == 0" Generally 
this is user-extended to act like isname(), except for abbreviated keywords. 

void skip_spaces (char **string) The command interpreter hands off " cabbage" if 
the user types in "look cabbage". Since comparisons need to be done without the 
extra space in the string, this function removes it. It is also used internally for 
the argument splitting functions to properly handle user input such as: "put the 
cabbage in the bag". 

bool is_number (const char *str) Tests if an entire string is an ASCII-encoded, 
decimal number by performing isdigit() on each character of the string. 

char *delete_doubledollar (char *string) The MUD, in processing input, converts a 
single dollar sign to a double dollar sign. If you want to echo out a user’s input 
through something other than act(), you will want to smash ’$$’ into ’$’ by using 
this function. 

2.4.2 Argument Processing 

char *one_argument (char *argument, char *first_arg) 

char *two_arguments (char *argument, char *first_arg, char *second_arg) 

char *any_one_arg (char *argument, char *first_arg) These functions are frequently 
used in MUD commands to parse the arguments to those commands. As their names 
imply, one_argument() will peel off one argument from the string given by the user 
while two_arguments() will peel off two at a time. Note that these functions ignore 
(and will not return) words such as: “in”, “from”, “with”, “the”, “on”, “at”, and 
“to”. This is so the commands do not need to know the difference between "put the 
sword in the bag" and “put sword bag”. If those words are really needed for the 
command, then use any_one_arg() instead. It works just like one_argument() in all 
other respects. All of these functions convert the peeled off argument(s) to lower 
case as part of the process of storing them in the user-supplied buffer. 

char *one_word (char *argument, char *first_arg) Peels an argument off from a 
string like one_argument, but respects grouping via quoting. If the user supplies, 
‘ "moby dick"’, one_argument() would return an argument of ’"moby’, while one_word()
would return an argument of ‘moby dick’. This function converts the 
peeled off argument(s) to lower case as part of the process of storing them in the 
user-supplied buffer. 

void half_chop (char *string, char *arg1, char *arg2) Apparently a DikuMud relic. 
Instead of returning the leftover argument bits in the return value, this copies 
the result (sans leading spaces) into a second buffer. 

2.4.3 Character Output (Hello, world!) 

void log (const char *format, ...) Whenever a piece of information needs to be sent 
to the MUD’s logs, this is the function to use. It is especially useful for 
debugging and supports variable arguments like the printf() and sprintf() 
functions. To prevent compilation errors due to a conflict with C’s natural 
logarithm function of the same name, ‘log’ is actually an alias for this function’s 
real name, basic_mud_log(). 

void mudlog (const char *str, int type, int level, bool file) In most cases 
mudlog()is better than log() because it announces to both the immortals on the MUD 
and, optionally, the file logs. Chances are the immortals will notice something 
faster while logged in to the game than in the system logs. 

void send_to_char (struct char_data *ch, const char *messg, ...) This is the game’s 
tether to the players; its mouth; its voice. Most game output goes through this 
function so it is used very frequently. It supports variable argument formatting 
like the C library’s printf() and sprintf()functions. 

void act (const char *str, bool hide_invisible, struct char_data *ch, struct 
obj_data *obj, const void *vict_obj, int When dealing with character interactions 
there are frequently three situations to cover: the actor, the target, and the 
observers. This function takes care of such output along with handy cases for his/her,
he/she/it, and other language special cases. 

See the ’act()’ documentation (act.txt) for more information on what each 
particular parameter is used for. 

void page_string (struct descriptor_data *d, char *str, bool keep_internal) Places 
the character into a pageable view of whatever string is given to it. Handy for 
long board messages, opening announcements, help text, or other static information. 

2.4.4 File Input 

int get_line (FILE *fl, char *buf) Reads one or more lines, if possible, from the 
given file handle into a user-supplied buffer. This skips lines that begin with an 
asterisk (*), which are considered to be comments, and blank lines. The returned 
line has the line terminator(s) removed, and the total number of lines read to find 
the first valid line is returned. A value of zero indicates that an error occurred 
or that end of file was reached before a valid line was read. 

int get_filename (char *orig_name, char *filename, int mode) Fills in the 
’filename’ buffer with the name of a file of type ‘mode’ for a player with name 
‘orig_name’. The mode parameter can be one of: 

CRASH_FILE, for player object files, PLR_FILE, for player files, The returned filename
contains a path to a file in a directory based upon the file type and the first letter
of ‘orig_name’. 

2.4.5 Utility Functions 

int rand_number (int from, int to) Rolls a random number using a (pseudo) random 
number generator in the range [from, to]. The random number generator is seeded 
with the time tbaMUD booted as returned by the time() system call. This provides a 
good, difficult to predict sequence of numbers. 

int dice (int num, int size) Simulate rolling ‘num’ dice, each with ‘size’ sides, 
and return the sum of the rolls. 

size_t sprintbit (bitvector_t bitvector, const char *names[], char *result, size_t 
reslen) Treat an array of strings as if they were descriptions for the individual 
bits in ‘bitvector’ and create a string describing it. This is used by the wizard 
function do_stat() to give human-readable output to the various bitvectors used as 
storage by the code. This is the approximate reverse of “PRF_LOG1 | PRF_DEAF”, for 
example. 

size_t sprinttype (int type, const char *names[], char *result, size_t reslen) 
Retrieves a value from an array of strings. The difference between this and 
“array[number]” is that this will avoid reading garbage values past the end of the 
array. sprinttype() assumes the string arrays are terminated by a “\n” entry. 

int search_block (char *arg, const char **list, int exact) Searches an array of 
strings for a match to ‘arg’ and returns the index in the array of the match, or -1 
if not found. If ’exact’ is false, then a prefix match is done akin to is_abbrev(). 
This is useful to map symbolic names to numerical constants. Think of it as the 
opposite of array[number]: “What index has this value?” 

2.4.6 Character/Object Manipulation 

void char_to_room (struct char_data *ch, room_rnum room) 

void char_from_room (struct char_data *ch) Reciprocal, low-level functions to put a 
character into and remove a character from a given room. The room number must be 
specified with a “real number” (an index into the room tables) as returned by 
real_room(). 

Since a character can only be in one room at a time, you must call char_from_room() 
to remove a character from his current location before placing him in another. 
After a char_from_room() call, the character is in NOWHERE and must be moved to 
another room using char_to_room(). 

These functions do not check if the character is allowed to enter or leave the 
room; nor do they provide output to indicate that the character is moving. 

void extract_char (struct char_data *ch) Remove the character from the game world 
and then frees the memory associated with it. Players are saved before removal. Any 
objects still on the character are dumped on the ground. 

void equip_char (struct char_data *ch, struct obj_data *obj, int pos) 

struct obj_data *unequip_char (struct char_data *ch, int pos) Takes a free-floating 
object (i.e., not equipped, in inventory, on the ground, or in another object) and 
equips it to the character for the specified location. unequip_char() does the 
opposite; it removes the object from the character’s equipment list and returns it 
as a free-floating object. The object being unequipped must be placed elsewhere or 
destroyed. Note that some objects may not be equipped by characters of certain 
classes and/or alignments. 

void obj_to_char (struct obj_data *object, struct char_data *ch) 

void obj_from_char (struct obj_data *object) Reciprocal, low-level functions to put 
an object into and remove an object from a given character’s inventory. Since an 
object can only be in one location at a time, you must use one of the obj_from_X() 
functions to remove it from its current location before using obj_to_char()to place 
it in someone’s inventory. After an obj_from_char()call, the object is in NOWHERE 
and must be moved to another location using one of the obj_to_X() functions. 

These functions do not check if the character is allowed to carry or discard the 
object; nor do they provide any output to inform anyone that the character has 
received or discarded the object. 

void obj_to_obj (struct obj_data *object, struct obj_data *cont) 

void obj_from_obj (struct obj_data *object) Reciprocal, low-level functions to put 
an object into and remove an object from a given container object. Since an object 
can only be in one location at a time, you must use one of the obj_from_X() 
functions to remove it from its current location before using obj_to_obj() to place 
it within another object. After an obj_from_obj() call, the object is in NOWHERE 
and must be moved to another location using one of the obj_to_X() functions. 

These functions do not check if the container is allowed to carry or discard the 
object; nor do they provide any output to inform anyone that the container has 
received or discarded the object. 

void obj_to_room (struct obj_data *object, room_rnum room) 

void obj_from_room (struct obj_data *object) Reciprocal, low-level functions to put 
an object into and remove an object from a given room. Since an object can only be 
in one location at a time, you must use one of the obj_from_X() functions to remove 
it from its current location before using obj_to_room() to place it in a room. 
After an obj_from_room() call, the object is in NOWHERE and must be moved to 
another location using one of the obj_to_X() functions. 

These functions do not check if the room is allowed to contain or discard the 
object; nor do 

they provide any output to inform anyone that the room has received or discard the 
object. 

void extract_obj (struct obj_data *obj) Removes the object from its place in the 
world, then destroys it. 

2.4.7 Object Locating 

struct obj_data *get_obj_in_list_num (int num, struct obj_data *list) Get an object 
from ‘list’ with the specified real object number. Only takes first object; no 
"2.bread” support. 

struct obj_data *get_obj_num (obj_rnum nr); Find the first object in the world with 
the real object number given. Does not have “2.” support. 

struct obj_data *get_obj_in_list_vis (struct char_data *ch, char *name, int 
*number, struct obj_data *list) Find the ‘number’-th object in ‘list’ with keyword 
’name’ that the character can see. A NULL is returned on failure to locate such an 
object, or if not enough objects to satisfy ‘number’ were found. ‘number’ is a 
pointer to an integer so it can be decremented when doing multiple searches, such 
as room then world. If the first object is desired, ‘number’ is left NULL. 

struct obj_data *get_obj_vis (struct char_data *ch, char *name, int *number) Find 
the ‘number’th object in the world with keyword ‘name’ that the character can see. 
A NULL is returned on failure to locate such an object, or if not enough objects to 
satisfy ‘number’ were found. ‘number’ is a pointer to an integer so it can be 
decremented when doing multiple searches, such as room then world. If the first 
object is desired, ‘number’ is left NULL. 

struct obj_data *get_obj_in_equip_vis (struct char_data *ch, char *arg, int 
*number, struct obj_data *equipment[]) Find the ‘number’-th object in the 
character’s equipment list with keyword ‘name’ that the character can see. A NULL 
is returned on failure to locate such an object, or if not enough objects to 
satisfy ‘number’ were found. ‘number’ is a pointer to an integer so it can be 
decremented when doing multiple searches, such as equipment then inventory. If the 
first object is desired, ‘number’ is left NULL. 

int get_obj_pos_in_equip_vis (struct char_data *ch, char *arg, int *number, struct 
obj_data *equipment[]) Return the index of the ’number’-th object in the 
character’s equipment list with keyword ’name’ that the character can see. A -1 is 
returned on failure to locate such an object, or if not enough objects to satisfy 
‘number’ were found. ‘number’ is a pointer to an integer so it can be decremented 
when doing multiple searches, such as equipment then inventory. If the first object 
is desired, ‘number’ is left NULL. 

int generic_find (char *arg, bitvector_t bitvector, struct char_data *ch, struct 
char_data **tar_ch, struct obj_data Searches any or all of the character’s 
equipment, inventory, current room, and world for an object with the keyword given 
in ‘arg’. A 2nd or 3rd object is denoted in “2.object” notation. The function’s 
return value specifies where the object was found, or 0, and the ‘tar_obj’ value is 
updated with the object itself, or NULL. NOTE: This also does characters, either 
separately or simultaneously. 

2.4.8 Character Locating 

struct char_data *get_char_room (char *name, int *number, room_rnum room); Find the 
‘number’th character in the room with the keyword ‘name’. A NULL is returned on 
failure to locate such a character, or if not enough characters to satisfy ‘number’ 
were found. ‘number’ is a pointer to an integer so it can be decremented when doing 
multiple searches, such as room then world. If the first character is desired, 
‘number’ is left NULL. 

struct char_data *get_char_num (mob_rnum nr); Find the first mobile in the world 
with real mobile number given. This does not have support for “2.” notation. 

struct char_data *get_char_room_vis (struct char_data *ch, char *name, int 
*number); Find the ‘number’-th character in the room with the keyword ‘name’ that 
is visible to the character given. A NULL is returned on failure to locate such a 
character, or if not enough characters to satisfy ‘number’ were found. ‘number’ is 
a pointer to an integer so it can be decremented when doing multiple searches, such 
as room then world. If the first character is desired, ‘number’ is left NULL. 

struct char_data *get_char_world_vis (struct char_data *ch, char *name, int 
*number); Find the ‘number’-th character in the world, searching the character’s 
room first, with the keyword ‘name’ that is visible to the character given. A NULL 
is returned on failure to locate such a character, or if not enough characters to 
satisfy ‘number’ were found. ‘number’ is generally a pointer to an integer so it 
can be decremented when this does both searches. If the first character is desired, 
‘number’ is left NULL. 

struct char_data *get_char_vis (struct char_data *ch, char *name, int *number, int 
where); When ‘{textttwhere’ is FIND_CHAR_WORLD, call ‘get_char_world_vis()’. 
If‘where’ is FIND_CHAR_ROOM, call ‘get_char_room_vis()’. Otherwise, return NULL. 
This is kept for compatibility with various calls in the source code or if people 
want to easily change a search based on a variable. 

int generic_find (char *arg, bitvector_t bitvector, struct char_data *ch, struct 
char_data **tar_ch, struct obj_data); Searches the character’s current room and/or 
world for a character with the keyword given in ‘arg’. A 2nd or 3rd character is 
denoted in “2.character” notation. The function’s return value specifies where the 
character was found, or 0, and the ‘tar_ch’ value is updated with the character 
itself, or NULL. NOTE: This also does objects, either separately or simultaneously. 

2.4.9 Violence 

void set_fighting (struct char_data *ch, struct char_data *victim); Initiates 
fighting between ‘ch’ and ‘victim’. 

void stop_fighting (struct char_data *ch); Removes the character from a fighting 
posture. Note that if an enemy is still considered fighting this character, the 
character will revert back to fighting as soon as the enemy hits them again. 

void hit (struct char_data *ch, struct char_data *victim, int type); Makes the 
character attempt to hit the victim. The type determines if it is a skill, backstab 
in particular, or other type of damage to attempt to hit with. The type is 
generally left as TYPE_UNDEFINED to use the character’s natural type. 

int damage (struct char_data *ch, struct char_data *victim, int dam, int 
attacktype); Cause bodily harm to the victim, courtesy of the character. The damage 
and attacktype determine the message reported. Immortals and shopkeepers (that 
aren’t charmed) may not be injured. Damage is capped at 100 per hit. 

3 Adding Features 

3.1 Adding Commands 

In the course of writing new functionality for your MUD, one of the first projects 
you may try is to add your own command. Most commands will require you to implement 
some method to manipulate and parse the user’s input. In tbaMUD, this is done with 
’command functions’ which have a special declaration form: 

ACMD(do_/* Command name. */) 

{ 
/* Command code. */ 
} 

The command functions are then registered with the command interpreter by adding 
them to the cmd_info[] table in interpreter.c. The order within the command table 
is significant; entries at the top are substring matched prior to entries lower in 
the list. So if ’kill’ is before ’kiss’, then ’ki’ will match ’kill’. Something 
else to be aware of is that this can render commands unreachable, such as ’goad’ 
being before ’go’. The’go’ can never be matched because ’goad’ will always have a 
valid substring matched first. 

The fields of importance are: 

const char *command The name of the command being registered. Remember the 
substring matching when deciding upon the order in the table. 

const char *sort_as the minimum abbreviated command that will match.

byte minimum_position One of the POS_xxx constants #define’d in structs.h. This 
enforces the minimum position, inclusive, the user must be in, in order to execute 
the command. 

ACMD(*command_pointer) This is the name of the function the command will call. It 
must be defined in the code with the ACMD() macro and prototyped above the command 
table itself. 

sh int minimum_level The minimum level, inclusive, the user must be to execute the 
command. 

int subcmd To allow the same code function to handle multiple, similar commands, 
this field allows an identifying number to be given to the command’s function. 

The ACMD declaration form is a C macro that sets up the command function to receive 
the right arguments. All command functions in tbaMUD receive the same set of 
parameters: 

struct char_data *ch The character that issued the command (or, perhaps, was forced 
to issue the command): the actor. 

const char *argument A string that contains the arguments the user gave to the 
command, with any leading spaces from the command interpreter still intact. For 
example, if the user typed "tell ras Hello, there" at the prompt, argument would be 
" ras Hello, there". This string is typically processed using one or more of the 
functions from Sections 2.4.1 (Basic String Handling) or 2.4.2 (Argument Processing). 

int cmd The index within the command table where this command was found. Useful 
when multiple commands can invoke the same command function and you want to 
identify which command was issued. Since command indices can change when you add 
new commands, the primary use of this field is in special procedures and with the 
IS_CMD macro. Do not confuse this with the subcmd parameter, which is more general 
purpose. 

int subcmd A special, user-defined integer value passed to select a "subcommand." 
Usually zero, but sometimes used when multiple commands with similar behavior are 
implemented with a single command function. Since the subcmd’s value is supplied 
within the command table and has a meaning determined entirely by the command’s 
author, it will not change when you add new commands. 

A command with no arguments is very simple to write. For example, here is a simple 
command that sends a nice, personalized greeting to the user when she runs it: 

ACMD(do_hello) 
{ 
act("Hello, $n.", FALSE, ch, NULL, NULL, TO_CHAR); 
} 

To allow the user to access this command, you have to add it to the command table 
as discussed before. This can be done by adding the ACMD prototype above cmd_info[] 
(if necessary) in interpreter.c, like: 

ACMD(do_hello); 

and then adding to cmd_info[]the command’s information, as previously discussed: 

{ "hello", POS_DEAD, do_hello, 0, 0 }, 


Our information specifies this is a command named "hello" which anyone can use, 
regardless of their position (since dead is the minimum) or level (since 0 is the 
minimum), calls the do_hello() function to be executed, and has no subcmd. Note 
that because cmd_info[] does not encode information about the arguments to the 
command, we don’t need to do anything different for commands that take arguments. 

Since the command interpreter doesn’t process arguments for us (allowing 
cmd_info[] to be simple and general), we have to process them ourselves. Suppose we 
want to update our "hello" command to send a greeting to other users, when its 
invoked with an argument. First, we need to get the first argument (if any) by 
using the one_argument() function. In order to do this, we need a place to store 
the first argument (if any), which we declare as a local character buffer of length 
MAX_INPUT_LENGTH. (Note that regardless of what length we expect the argument to 
be, we always make our buffer the maximum input size, so users cannot overflow the 
buffer and crash the game.) 

After this, we need to see what the argument is. If it is nothing, we’ll default to 
our old behavior of just saying hello to our user. Otherwise, we need to look up 
the character with the given name. If we can’t find anyone by that name, we send an 
error message. If we find someone, we send the greeting to the character we found. 
We check if the given argument is empty by seeing if its first character is C’s end 
of string marker (’0’ or 0). Since one_argument() strips leading spaces for us, we 
don’t have to worry about them. If the string is not empty, we need to look up a 
character in the current room by that name, using get_char_vis() (see Section 
2.4.8. Character Locating). 

Our changes give us: 

ACMD(do_hello) 
{ 
char arg[MAX_INPUT_LENGTH]; /* First argument. */ 
struct char_data *targ; /* Who to greet? */ 

one_argument(argument, arg); 
if (!*arg) { /* Common idiom for empty string test. */ 
  act("Hello, $n.", FALSE, ch, NULL, NULL, TO_CHAR); 
  return; /* We’re done for this case. */ 
  } 
else if (!(targ = get_char_vis(ch, arg, FIND_CHAR_ROOM))) { 
  send_to_char(ch, NOPERSON); 
  return; /* Done for this case. */ 
  } 
/* Otherwise we got a target: */ 
act("You greet $N.", FALSE, ch, NULL, targ, TO_CHAR); 
act("$n greets you.", FALSE, ch, NULL, targ, TO_VICT); 
act("$n greets $N.", FALSE, ch, NULL, targ, TO_NOTVICT); 
} 


NOPERSON is a constant defined in config.c for use an error message when the target 
of a command cannot be found. Other such constants are OK (for when everything goes 
well) and NOEFFECT (as a general failure message for skills, spells, and commands 
whose success rely on chance). 

Of course, this command is extremely simplistic. Doing something of interest is up 
to you, as the programmer. Our "hello" command only serves as a starting point and 
demonstration of some idioms used throughout tbaMUD. 

3.2 Adding Socials 

Socials are commands that only write messages to the user and possibly his room 
and/or an optional victim, bodypart, or object. Examples are typical mud commands 
like "nod" or"wave", to let players perform various demonstrative actions. Socials
are described in-depth in the socials.txt file.

3.3 Adding Spells 

tbaMUD improves greatly over standard Diku handling for spells, but how you go 
about adding them depends on the type of spell you want to make. Damage, affection, 
group, mass area, area, monster summoning, healing, status removal, and item 
enchanting spells are all generated in a template format with a touch of special 
messages and coding effects. More complicated spells such as ’locate object’, 
’summon’, or ’identify’ are a combination of the behavior of spells and commands. 
They are spells in the sense the code checks for mana and requires the ’cast’ 
syntax but are also commands in the sense that beyond the basic handling, the spell 
is implemented as a subroutine with given parameters. Visit http://tbamud.com for a 
tutorial on how to add spells.

All spells require a definition to determine the amount of mana used, how the spell 
behaves, and what the spell is named. To do that, the function spello() is called 
from mag_assign_spells() in spell_parser.c. It is called as: 

spello( 
unique_spell_number = ID# from 0 .. TOP_SPELL_DEFINE for this spell. 

spell_name = Name to be used for ’cast’ command. max_mana = Mana cost of spell when 
first learned. 

min_mana = Minimum mana cost to ever cast the spell. 

mana_change = Reduction in mana cost per level beyond learning it. 

minimum_position = Whether castable sitting, standing, fighting, etc. 

valid_targets = If the spell targets people, yourself, items, etc. 

offensive = Whether casting on someone else is a hostile action. 

spell_routines = One or more of the magic template classifications. 

wear_off_message = Text to display when the spell wears off, or none. 

A spell with a minimum position value of 0 may not be cast by mere mortal players. 
For example, the spell "armor" is described as: 

spello(SPELL_ARMOR, "armor", 30, 15, 3, POS_FIGHTING, TAR_CHAR_ROOM, FALSE, 
MAG_AFFECTS, "You feel less protected."); 

This spell costs 30 mana at the first level it is learned and decreases in cost by 
3 mana per level afterward until it reaches the minimum of 15. The spell may be 
cast either fighting or standing, but not sitting, resting, sleeping, or otherwise 
incapacitated. Armor will target anyone in the current room as a non-hostile 
action. It processes through MAG_AFFECTS so there will be a lingering affection, 
after which the "You feel less protected" message will display. 

To allocate a new spell, create a new #define symbol in spells.h in the same 
pattern as the others there. In that header, give the new spell an unused spell 
number equal to or less than MAX_SPELLS. If you run out of spell slots then other 
means not covered here will be necessary to add more spells. 

3.3.1 Template Spells 

Similar types of spells have generalized routines that handle multiple spells with 
very little different code. A damage spell is a damage spell is a damage spell. 
Even if a spell does multiple actions, such as blinding plus damage plus monster 
summon, the damage portion of the spell acts identical to a spell that simply does 
damage. The only difference is how much it does and whether there are special 
mitigating factors. For example, ’chain lightning’ in mag_damage() (since it is a 
MAG_DAMAGE spell) is simply: 

case SPELL_CALL_LIGHTNING: 
dam = dice(7, 8) + 7; 
break; 

So the spell does 7d8+7 damage. Simple enough. All checking for saving throws, 
valid targets, proper mana reserves, etc. is all handled by the generic code with a 
bit of definition for the code to operate by. 

The code fragment in the template sections can use any information about the 
caster, target, or environment that it chooses to modify the damage, success, or 
effect done to the target. Some spells do more damage if the caster is a magic 
user. Others might outright kill lower level targets but only slightly wound more 
experienced ones. The effect is up to you. 

Affection spells require more in their fragment than the simple damage spells. They
create affection structures that are then given to the target of the spell for 
their specified duration if the spell succeeds. More than one affection can be 
given by a single spell, as shown below in "bless": 

case SPELL_BLESS: 
af[0].location = APPLY_HITROLL; 
af[0].modifier = 2; 
af[0].duration = 6; 

af[1].location = APPLY_SAVING_SPELL; 
af[1].modifier = -1; 
af[1].duration = 6; 

accum_duration = TRUE; 
to_vict = "You feel righteous."; 
break; 

Any modifier listed in structs.h in the APPLY_xxxsection may be used as the 
location field. The modifier’s effect will depend on the affection type used. Up to 
MAX_SPELL_AFFECTS values can be assigned to. Although not listed in the above 
example, a ‘.bitvector’ value may be assigned to if the spell should tag the player 
with an AFF_ flag. If multiple castings of the same spell should be cumulative in 
duration, the ‘accum_duration’ variable is set to TRUE. Likewise, if the modifier 
is cumulative, the ‘accum_effect’ variable should be set to TRUE. A string 
assigned to ‘to_room’ will be passed through act() for the occupants of the same 
room as the caster. A ‘to_vict’ string will be given to act() with the target of 
the spell as the recipient of the message. 

Group spells simply call another spell on everyone in your current group. If you 
want a ‘group fly’ spell, then you make a ‘fly’ spell first. Afterward, you make 
the ‘group fly’ definition and then fill in some template areas of the
perform_mag_groups() function. What you write there will depend on how your spell
is designed. 

General summoning spells (not ‘summon’ itself) deal with the conjuration of 
mobiles. They require: ‘fmsg’, a failure message array index number; ‘mob_num’, the 
virtual mobile number to summon; ‘pfail’, the percent chance of failure; and 
‘handle_corpse’, mostly for the “animate dead” spell so it can move the items from 
the corpse being animated to the mobile being summoned. These spells lend
 themselves to more customization than some of the other types. 

Healing spells in mag_points() can restore either health or movement points by 
default. Just assign the amount of health healed to a ‘healing’ variable, the 
amount of movement points restored to a ‘move’ variable, and send the target a 
message with send_to_char(). The general code will handle updating the character’s 
attributes, position, and make sure a dying character is restored to normal 
functions if healed sufficiently. 

Unaffection spells revert the effects of other spells, such as “blindness”, 
“silence”, or “drunken stupor.” There are only three variables used in 
mag_unaffects(): to_vict, to_room, and spell. The important variable is ‘spell’, 
which determines which spell effect this unaffection spell will counter. The 
‘to_vict’ and ‘to_room’ messages are optional but sent to the victim and room, 
respectively, if provided. 

Object alteration spells deal with magical modifications to items, such as 
poisoning, cursing, enchanting, or making them invisible. These spells are all 
unique by nature so only ‘to_char’ and ‘to_room’ are expected to be set, as 
messages to the character and room, respectively. If ‘to_char’ is left NULL, it is 
assumed the spell failed and a “no effect” message is given. 

A creation spell conjures an item out of nothingness. The only variable expected is 
‘z’, which specifies the object virtual number that should be created. Note that 
only a single object is created and there is no current mechanism for making 
multiples. 

The last function of note, mag_materials(), is not a spell type at all but a helper 
function which can be used to require up to 3 spell reagents for a particular spell 
to be cast. The function will return TRUE if the caster has the objects, otherwise 
FALSE. If the ‘extract’ variable is TRUE, then the objects in question will be 
consumed by the casting. You can also make the function ‘verbose’, but it is more 
of a debugging/funny option than practical. 

3.3.2 Manual Spells 

Any spell that doesn’t fit one of the template molds is implemented as a manual 
spell. Adding a manual spell requires a function to be written, generally in 
spells.c, with the ASPELL() macro. After the requisite spell identifier macro is 
added to spells.h, add it to the manual spell list in spell_parser.c, call_magic(). 
(Search for “MANUAL_SPELL”.) 

Manual spells are given: 

level: The effective character level of the spell being cast. This is NOT the same 
as the level of the character because the spell could have been case by a wand, 
staff, or scroll instead of the character. 

ch: The character causing the spell. 

victim: The target of the spell, if a character. 

obj: The target of the spell, if an object. 

Other than that, manual spells can do anything. Think of them as being similar to 
standard commands in power and scope. A useful modification is to add ’argument’ 
support to spells so that “locate object” works properly and a “change weather” 
spell could make it “better” or “worse.” 

3.4 Adding Skills 

Skills in tbaMUD are usually implemented as commands. The first steps to adding a 
skill are similar to those of adding a spell. First, make sure you have a clear 
idea of what your skill is going to do, who you’re going to give it to, and how it 
fits in with the rest of the game. Try to avoid making too many skills that do 
basically the same thing – having lots of skills isn’t a meaningful feature if most 
of them can be ignored. 

After you have a good idea of what you want to do, why you want to do it, and why 
it’s a good idea to do it, then start by adding a SKILL_xxx #define to spells.h and 
the corresponding skillo() line to mag_assign_spells() in spell_parser.c. The 
skillo() function takes, as its first argument, the SKILL_xxx #define and, as its 
second, the name of the skill, as a string. This registers the skill as something 
that can be practiced. As with spells, you have to register the skill’s 
availability with individual classes at the appropriate levels in the 
init_spell_levels() function of class.c. 

Now your skill can be gained and practiced by players of an appropriate level and 
class, but it doesn’t actually do anything. Most skills, like "bash" and "kick", 
are simply commands that perform skill checks. The setup and everything else is the 
same as in Section 3.1, Adding Commands. The body needs to account for (1) whether 
the command’s user can access the skill and (2) whether they were successful in 
using the skill. For (1), tbaMUD uses the idiom 

if (IS_NPC(ch) || !GET_SKILL(ch, SKILL_xxx)) { 
  send_to_char(ch, "You have no idea how.\r\n"); 
  return; 
} 

to check if the skill is available. The GET_SKILLmacro returns the proficiency (as 
a percentage) the given character has in the given skill. If the proficiency is 0%, 
the player does not have the skill (either because his class doesn’t have it or 
he’s not learned it, yet). This check is preferred over directly testing if the 
player is of the right class(es) to use the skill, since that would require you to 
change several functions across several files to give skills to other classes 
(instead of just being able to add spell_level() calls in class.c). 

At this point you would do argument processing in the typical manner, as well as 
any other checks that are necessary (for instance, you might want to check if the 
room is peaceful, as done in do_bash() in act.offensive.c). Last, you want to check 
for the success or failure of the skill by rolling a percentage to compare against 
the user’s proficiency (probability of success). This is typically done with: 

if (number(1, 101) > GET_SKILL(ch, SKILL_xxx)) { 
  /* Failure. */ 
} else { 
  /* Success. */ 
} 

where you’d replace the comments with the relevant failure or success code. 

For skills that do damage, like "bash" and "kick", the messages for success and 
failure are typically not encoded in the skill itself, but instead as damage 
messages in lib/misc/messages, which has the format: 

M 
<skill number> 
<death messg to skill user> 
<death messg to skill victim> 
<death messg to others> 
<miss messg to skill user> 
<miss messg to skill victim> 
<miss messg to others> 
<hit messg to skill user> 
<hit messg to skill victim> 
<hit messg to others> 
<attempt to hit immortal messg to skill user> 
<attempt to hit immortal messg to skill victim> 
<attempt to hit immortal messg to others> 

The skill number is the #define as appears in spells.h and the rest are single line 
messages that will be passed to act(). This is similar in many respects to 
lib/misc/socials. The format is discussed in more detail in a comment at the 
beginning of lib/misc/messages. 

These messages are then displayed by calling damage() with the appropriate 
arguments, as discussed in Section 2.4.9, Violence, with the attacktype argument 
set to the SKILL_xxx #define, as in 

/* 
* See above and Section 3.1, Adding Commands: 
* ... skill checks, argument processing, etc. 
* ... vict is set to skill’s victim. 
*/ 
if (number(1, 101) > GET_SKILL(ch, SKILL_FOO)) { 
  /* Failure means 0 damage is done. */ 
  damage(ch, vict, 0, SKILL_FOO); 
} else { 
  /* Success means we do some damage. */ 
  damage(ch, vict, 10, SKILL_FOO); 
} 

Note that even when the skill succeeds and, thus, our call to do 10 damage to the 
victim of the skill is made, we’re not guaranteed to do the damage. The hit may 
miss, in which case damage() returns 0. Additionally, the hit may kill the victim, 
in which case damage() returns -1. If we’re going to be modifying vict in our 
skill’s function after the call to damage(), it’s important to take these return 
values into consideration. See do_bash() in act.offensive.c. 

3.5 Adding Classes 

Classes are one of the implementors’ most important decisions because the players 
will constantly deal with them, their advantages, and their limitations. A good 
class should be balanced so that it has its own unique perks and flaws, never 
making other classes pointless to play. 

Most changes to be done for classes will be found in the class.c file. There may be 
special quirks for classes implemented in the other files but the basic defining 
characteristics are all there. The class needs a name, abbreviation, menu entry, 
unique class number, skill list, guild information, saving throws, combat hit 
probabilities, an ability priority list, hit/mana/move advancement per level, basic 
starting kit, opposing item flags, spells, skills, experience charts, and level 
titles. It’s an exhaustive list, but the actual addition of a class isn’t nearly as 
complicated as it sounds. 

The first change for a class required external of class.c is in structs.h. There, 
search for CLASS_UNDEFINEDand add a new CLASS_xxxdefinition for your class name 
with the next available number. Remember to bump the value of NUM_CLASSES, just 
below, by 1. 

Then search structs.hfor "Extra object flags" so you can add an "ITEM_ANTI_xxx" 
flag for your new class. As before, use the next available number in the sequence 
for ITEM_xxx flags. 

The "ITEM_xxx" extra flags have a corresponding text description in constants.c, so 
search it for "ITEM_x (extra bits)". Add a string giving a short name for the new 
ITEM_ANTI_xxx flag, in the appropriate order, before the "\n" entry near the 
bottom. 

The shops have a similar "don’t trade" setup, so search shop.hfor "TRADE_NOGOOD" 
to add a new TRADE_NOxxx item to the list for the class to be added. Below that 
(near "NOTRADE_GOOD"), a line will need to be added for each new class so the ’no 
trade’ status of a shop can be tested for the class. 

With the definitions in shop.h, the shop code in shop.c can then be modified to 
take into account the new classes. In a manner similar to constants.c, there’s a 
table in shop.c with textual names for the TRADE_NOxxx values. Add the new class 
names to the "trade_letters[]" array in the same order as the TRADE_NOxxx bits were 
added to shop.h. Also in shop.c, the is_ok_char() function will need modified to 
add "IS_xyz(...) && NOTRADE_xyz(...)" conditions, to make the above changes take 
effect. 

Lastly for changes beyond class.c, search utils.h for "IS_WARRIOR" and make a 
similar definition below it for the new class. 

Most of the changes to class.c will be straight-forward if going by the existing 
classes, so only a few items of note: 

1. The letters used in parse_class() must be unique and should correspond to the 
highlighted characters in the ’class_menu’ variable. 
2. Lower saving throw values are better. 
3. Lower ’thaco’ values are better. 

3.6 Adding Levels 

Some people feel the standard 34 levels aren’t enough and want to add more. Others 
feel 34 is too many and want to reduce it. Fortunately, changing the number of 
levels in the MUD is fairly painless. There are only three important things to 
remember: adjusting the secondary tables to match your new levels, making over 127 
levels requires some additional modifications, and to readjust the mobiles 
afterward. 

The secondary functions that rely on levels directly are: saving_throws, thaco, 
backstab_mult, level_exp, title_male, and title_female. These must be changed to 
correctly cover the entire range of new levels for the MUD. If not, the missing 
levels will have incomplete data and may act in unexpected ways. Fortunately, 
you’ll receive error messages in the logs if such an event happens. 

As the number of mortals levels is always one less than the lowest immortal level, 
changing LVL_IMMORT in structs.hto a new value will give the desired change. Make 
sure you change the functions described above at the same time. The other immortals 
levels should be adjusted accordingly. 

If you’re making more than 127 total levels on the MUD, a little structs.h surgery 
is required. The default range on the ’level’ variable is -128 to 127. tbaMUD 
doesn’t actually use negative levels so changing it to ’ubyte level’ will allow 255 
levels. Note that this setting hasn’t been tested so test your new level settings 
to make sure they work as expected. If you need more than 255 levels, you’ll need 
to change the ’byte’ to something larger, like ush_int (65,535) or unsigned int(4.2 
billion). 

Once you’ve changed the number of levels on your MUD, the implementor character you 
may have already created will now have the wrong level to be an implementor. The first
player to login with UID 1 by default has acces to the cheat command and can increase
their level to IMP. If you’ve decreased the levels then a ’set self level XX’ command
should work to drop yourself to the proper level, since you’re considered above the
new implementor level still. 

Now remember to change all the mobiles too so they have proper levels. If you added 
levels, it’ll make the mobiles weaker unless fixed. If reducing the levels, then 
you’ll end up with error messages in the logs when those mobiles try to use saving 
throws or other level-dependent values. 

3.7 Adding Color 

Color is handled in a varying scale of color levels the player can choose to 
display. The possible levels are off, brief, normal, and complete. If a player has 
color off, no color, other than default, can be sent. 

To send color to the players, use the CC* family of macros: 

CCNRM: Normal text color, as defined by player’s terminal. 
CCRED: Red 
CCGRN: Green 
CCYEL: Yellow 
CCBLU: Blue 
CCMAG: Magenta 
CCCYN: Cyan 
CCWHT: White 

Each macro takes a pointer to the character and the level at which the color given
should be displayed. If the player uses a lower level of color than given to the 
macro in the code, the color code will reduce to an empty string so it does not 
appear. See ’color.txt’ for more information on this process. 

Now suppose you wish to add high-intensity colors, blinking, or backgrounds for 
your text. The place to look for the existing color codes is in screen.h, but 
you’ll just see codes like "\x1B[31m" there. So what is "\x1B[31m"? It is an ANSI 
color code understood by various terminal emulations to display color. There are 
predefined colors for each code and a special format to use so you can’t just make 
up codes and expect them to work. 

In order to compare the low-intensity colors with the high-intensity, an additional 
color must be known to complete the pattern, black: 

#define BBLK "\\x1B[30m" 

The terminal background color is assumed black by tbaMUD so that particular color 
definition isn’t in screen.h. Now a comparison of red and green with their bright 
counterparts: 

#define KRED "\\x1B[31m" (Dark) 
#define BRED "\\x1B[0;1;31m" (Bright) 
#define KGRN "\\x1B[32m" (Dark) 
#define BGRN "\\x1B[0;1;32m" (Bright) 

If you want the bright colors, you can extend this pattern to get the other standard colors. 

Once the #define is in screen.h, it needs to be usable via the CC* color convention 
to respect the color level of the players, so for every new color code add a CC* 
for it, such as: 

#define CCBRED(ch,lvl) (clr((ch),(lvl))?BRED:KNUL) 
#define CCBGRN(ch,lvl) (clr((ch),(lvl))?BGRN:KNUL) 

With a number of colors, making a new CC* code for each one may get tedious. You 
may want to add a new macro, such as: 

#define CC(ch, color, lvl) (clr((ch),(lvl))?(color):KNUL) 

Then you can use CC(ch, KRED, C_NRM)instead of CCRED(ch, C_NRM). Whether or not 
you want to use this idiom is up to you. It might come in handy once you get into 
blinking (use sparingly!) and background colors. The background colors are 
"\x1B[40m" (black), "\x1B[47m" (white), and everything in the middle as per the 
foreground colors. 

4 Writing Special Procedures 

Basic special procedures have largely been replaced by trigedit. Thus shifting the 
workload from the coder to the builder to add life and creativity into their zones. 
While it is easier, and less time consuming, to make triggers than special 
procedures they are still used for such functions as banks and guildmasters.

Using special procedures, your virtual world is not just a bunch of monsters, 
objects and rooms, reduced to a number of statistics. Just like good descriptions 
add atmosphere to the world, good use of special procedures adds flesh and life to 
the world. 

Several special procedures are provided with stock tbaMUD which you can use to 
create your own and get used to the mechanics of special procedures. These special 
procedures can be found in castle.c and spec_procs.c. They range from very simple 
procedures, like puff (pulsed special procedure) or bank (command-driven special 
procedure), to very complex procedures like the guild master. 

In this chapter, FALSE refers to the value 0 and TRUE to any non-zero value. 

4.1 Overview of Special Procedures 

Special procedures are nothing more than C functions, which are associated to 
mobiles, objects and rooms. 

In the standard version of tbaMUD, special procedures are defined and assigned at 
compile time and cannot be changed or reassigned during runtime. 

4.2 Pulsed vs. Command-Driven Special Procedures 

Special procedures are called at three points in code: the command interpreter 
(command-driven special procedures), the game heartbeat and the violence code 
(pulsed special procedures). 

There is no information kept to know if the special procedure is pulsed or 
command-driven, other than the behavior of the special procedure itself. When 
creating a special procedure you must keep in mind that it will be called in each 
of the three places and must therefore be prepared to react to all situations 
accordingly. 

In the next two sub-sections we will present both types of special procedures, and 
in the third sub-section we’ll explain how to differentiate the three types of 
call. 

4.2.1 Pulsed Special Procedures 

Every tick, the function heartbeat goes through the list of mobiles and the list of 
objects, updating everyone of them. If a mobile or an object as a special procedure 
associated to it, that special procedure is run with the parameters cmd and 
argument set to 0 and NULL respectively. 

When there is a fight, the special procedure of a fighting mobile is called once 
per round with the same arguments. 

4.2.2 Command Driven Special Procedures 

Whenever a player issues a command, the command interpreter tries to identify it in 
the Master Command Table. If it succeeds, before running the command associated in 
the table, it checks for special procedures in the following order: 

room the player is in; 
objects in the player’s equipment (does not enter the containers); 
objects in the player’s inventory (does not enter the containers); 
mobiles in the room; 
objects in the room floor; 

The first special procedure to succeed and return TRUE finishes the interpreting of 
the command. 

If no special procedure returned true or no special procedure was found, then the 
command interpreter runs the procedure specified in the Master Command Table. 

4.2.3 Preparing for all occurrences 

In order to make your special procedure react accordingly to all the different 
places where the special procedure can be called you need to distinguish those 
places. The way to do it is through the parameters. 

Whenever cmd is 0, the special procedure has been called as a pulsed special 
procedure, otherwise it is a command-driven special procedure. 

To detect if the procedure was called through the violence code, it is a pulsed 
special procedure and IS_FIGHTING(me) must be true. Of course, this only has 
meaning for a mobile special procedure. 

4.3 Relating Special Procedures to Objects, Mobiles, and Rooms 

The special procedures are assigned to the prototypes of the objects and mobiles, 
not to the instances themselves. There are functions provided to assign the special 
procedures: 

ASSIGNMOB(<vnum>,<special procedure>) 
ASSIGNOBJ(<vnum>,<special procedure>) 
ASSIGNROOM(<vnum>,<special procedure>) 

tbaMUD also provides a place where to put all the special procedure assignments: 
the functions assign_mobiles, assign_objects, and assign_roomsin spec_assign.c. 

4.4 The Special Procedure Function Header 

The function header of any special procedure is defined in the macro SPECIAL(<name>)
and is as follows: 

int (<name>)(struct char\_data *ch, void *me, int cmd, char *argument) 

where <name>is the name of the special procedure. 

The parameters to the function are: 

ch: Character that issued the command to command interpreter that triggered this 
special procedure. 

me: The mobile, object or room to which the special procedure is given. 

cmd: The command that chissued as recognized by the command interpreter, or zero if 
the special procedure is being called by the pulse code. 

argument: The command that the played has introduced at the prompt or an empty 
string if the special procedure is being called by the pulse code. 

4.5 The Special Procedure Return Value 

The return value of a special procedure is looked at only by the command 
interpreter and has meaning only for command-driven special procedures. Pulsed 
special procedures should always return false. 

A command-driven special procedure can return two values: 

FALSE:: The procedure did not process the command given and it should be processed 
in the standard way by the command interpreter. 

TRUE:: The procedure reacted to the command given and so, the command interpreter 
should ignore it.