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<69>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<64>t run otherwise.
Now the situation is much different. With the proliferation of user-friendly
codebases any Average Joe can just type <20>make<6B> 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 <20>Net. Some people may tell you that you don<6F>t need to
know how to code in order to run a MUD <20> don<6F>t believe them. Those people are
wrong.
If you want your MUD to succeed and flourish, you<6F>ll have to know how to code in C.
Otherwise, your MUD will be exactly like every other MUD out there. You<6F>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<6F>t
know how to code, you won<6F>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<6F>re a great game-player and have some terrific ideas about how a
MUD should work, but don<6F>t know how to code, you should either learn or find a good
coder who can join your team. Don<6F>t assume that you can get away with running a MUD
without knowing C <20> you can<61>t. Not for very long, anyway.
This document won<6F>t teach you how to program in C; you<6F>ll have to learn that on
your own. Instead, it will try to familiarize you with the way tbaMUD<55>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 <20>get into<74> 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.
expect familiarity to come overnight. The best way to learn is to DO. Get your
hands dirty! Don<6F>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<6F>ll be able to write completely original functions, and even
tear some of tbaMUD<55>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<6F>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<69>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<6F>re working with.
The first section, <20>An Internet Server Tutorial<61>, describes how Internet servers
such as tbaMUD work. It contains interesting background material if you<6F>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<6F>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 <20>server<65> is a program which provides some service to Internet users
(called <20>clients<74>). 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 <20> a single program <20> 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
<EFBFBD> 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<73>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 <20> 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<EFBFBD>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<6F>t work any
more. With one user, that worked fine. But what will happen with 10 users?
Let<EFBFBD>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 <20> 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<EFBFBD>s say that you<6F>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 <20>Waiting for First Number.<2E> If a user types a number while she<68>s in the
<EFBFBD>Waiting for First Number<65> state, you<6F>d store her number somewhere and move her
into the <20>Waiting for Second Number<65> state. If she types a number while in the
<EFBFBD>Waiting for Second Number<65> state, you<6F>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 <20> there is no global state shared by all users.
Now, you might be able to see how this calculator example relates to tbaMUD. Let<65>s
say that the MUD receives the string, <20>Sleep<65> 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 <20>Sleep<65>. 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<72> state.
You can see a list of all possible players<72> states in structs.h (they all start
with <20>CON_<4E>). 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 <20>By what name do you wish to be known?<3F> 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<65>s go back to our previous example and trace exactly what happens when you
type <20>Sleep<65>. First, you type <20>Sleep.<2E> Then, your computer sends the string <20>Sleep<65>
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, <20>Has this
user typed anything?<3F>. Since you typed <20>Sleep<65>, the operating system will respond,
<EFBFBD>Yes!<21>. The MUD will then ask the operating system to deliver the message and will
read your message of <20>Sleep<65>. (All the magic of talking to the operating system and
checking to see whether or not you<6F>ve typed anything happens in comm.c.)
So, now that the MUD now knows that you<6F>ve typed <20>Sleep<65>, it has to decide which of
several functions in interpreter.c should get control next. This depends on what
state you<6F>re in. If you<6F>re in the normal PLAYING state, it will pass control to a
function called command_interpreter, which will interpret <20>Sleep<65> as a normal
command and put you to sleep. If you<6F>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<6F>re in and acts accordingly. For
example, if you<6F>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<69>ll ask you the
question, <20>Did I get that right, Sleep?<3F>.)
In a nutshell, that<61>s how tbaMUD interacts with the Internet. If you don<6F>t
understand all the details, don<6F>t worry <20> it<69>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 <20>
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<65>s
series, but goes into more detail in several areas, and offers more practical code
examples.
2.2 The Way Things Work <20> 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<73>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<55>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 <20>standard error<6F> 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
<EFBFBD>Syntax Check<63> 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
<EFBFBD>mother<EFBFBD> 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<73>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<73>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 <20>*<2A> 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<65>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<65>t interpreted beyond their
placement but they<65>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<65>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<73>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<65>s level. The spell table is sorted for the practice
command for easier visual searching by the player. Neither are critical to the
MUD<EFBFBD>s operation but exist for the players<72> 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<73>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<65>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<73>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
autowizinstances.
From here, the .killscript file is removed since if we<77>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 <20>Syntax Check<63> 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<73>t anyone
connected to the game at all, then the MUD sleeps until someone connects. (<28>If a
tree falls in the forest, and no one<6E>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<6F>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<65>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<EFBFBD>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<65>s
description, changing their password, deleting the character, or entering the game.
The alias system provides a method for player<65>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<65>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<55>s output queue as will
fit in the operating system<65>s socket buffer for each player. Any output that can<61>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<6E>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<72> 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<69>s not necessary since we<77>re about to exit anyway.
The <20>mother<65> 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
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: <20>in<69>, <20>from<6F>, <20>with<74>, <20>the<68>, <20>on<6F>, <20>at<61>, and
<EFBFBD>to<EFBFBD>. This is so the commands do not need to know the difference between "put the
sword in the bag" and <20>put sword bag<61>. 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,
<EFBFBD> "moby dick"<22>, one_argument() would return an argument of <20>"moby<62>, while one_word() would return an argument of <20>moby dick<63>. This function converts the
peeled off argument(s) to lower case as part of the process of storing them in the
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
<EFBFBD>filename<EFBFBD> buffer with the name of a file of type <20>mode<64> for a player with name
<EFBFBD>orig_name<EFBFBD>. 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 <20>orig_name<6D>.
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 <20>num<75> dice, each with <20>size<7A> sides,
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, <20>chain lightning<6E> 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<65>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 <20>.bitvector<6F> 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 <20>accum_duration<6F> variable is set to TRUE. Likewise, if the modifier
is cumulative, the <20>accum_effect<63> variable should be set to TRUE. A string
assigned to <20>to_room<6F> will be passed through act() for the occupants of the same
room as the caster. A <20>to_vict<63> 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 <20>group fly<6C> spell, then you make a <20>fly<6C> spell first. Afterward, you make
the <20>group fly<6C> 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 <20>summon<6F> itself) deal with the conjuration of
mobiles. They require: <20>fmsg<73>, a failure message array index number; <20>mob_num<75>, the
virtual mobile number to summon; <20>pfail<69>, the percent chance of failure; and
<EFBFBD>handle_corpse<EFBFBD>, mostly for the <20>animate dead<61> 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 <20>healing<6E> variable, the
amount of movement points restored to a <20>move<76> variable, and send the target a
message with send_to_char(). The general code will handle updating the character<65>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 <20>blindness<73>,
<EFBFBD>silence<EFBFBD>, or <20>drunken stupor.<2E> There are only three variables used in
mag_unaffects(): to_vict, to_room, and spell. The important variable is <20>spell<6C>,
which determines which spell effect this unaffection spell will counter. The
<EFBFBD>to_vict<EFBFBD> and <20>to_room<6F> 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 <20>to_char<61> and <20>to_room<6F> are expected to be set, as
messages to the character and room, respectively. If <20>to_char<61> is left NULL, it is
assumed the spell failed and a <20>no effect<63> message is given.
A creation spell conjures an item out of nothingness. The only variable expected is
<EFBFBD>z<EFBFBD>, 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 <20>extract<63> variable is TRUE, then the objects in question will be
consumed by the casting. You can also make the function <20>verbose<73>, but it is more
of a debugging/funny option than practical.
3.3.2 Manual Spells
Any spell that doesn<73>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 <20>MANUAL_SPELL<4C>.)
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 <20>argument<6E>
support to spells so that <20>locate object<63> works properly and a <20>change weather<65>
spell could make it <20>better<65> or <20>worse.<2E>
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<6F>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 <20> having lots of skills isn<73>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<EFBFBD>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<6C>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<73>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<6E>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<73>t have it or
he<EFBFBD>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<65>s proficiency (probability of success). This is typically done with:
if (number(1, 101) > GET_SKILL(ch, SKILL_xxx)) {
/* Failure. */
} else {
/* Success. */
}
where you<6F>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<6C>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<77>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<77>re going to be modifying vict in our
skill<EFBFBD>s function after the call to damage(), it<69>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<72> most important decisions because the players
will constantly deal with them, their advantanges, 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
titles. It<49>s an exhaustive list, but the actual addition of a class isn<73>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<6F>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 <20>no
trade<EFBFBD> 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<72>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 <20>class_menu<6E> variable.
2. Lower saving throw values are better.
3. Lower <20>thaco<63> values are better.
3.6 Adding Levels
Some people feel the standard 34 levels aren<65>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<EFBFBD>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<6F>re making more than 127 total levels on the MUD, a little structs.h surgery
is required. The default range on the <20>level<65> variable is -128 to 127. tbaMUD
doesn<EFBFBD>t actually use negative levels so changing it to <20>ubyte level<65> will allow 255
levels. Note that this setting hasn<73>t been tested so test your new level settings
to make sure they work as expected. If you need more than 255 levels, you<6F>ll need
to change the <20>byte<74> to something larger, like ush_int (65,535) or unsigned int(4.2
billion).
Once you<6F>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 theri level to IMP. If you<6F>ve decreased the levels then a <20>set self level
XX<EFBFBD> command should work to drop yourself to the proper level, since you<6F>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<69>ll make the mobiles weaker unless fixed. If reducing the levels, then
you<EFBFBD>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<65>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 <20>color.txt<78> 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<EFBFBD>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<61>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<73>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*
