/**************************************************************************
* Copyright (C) 1993 - see 'license.doc' for complete information. *
**************************************************************************/
----- Compiling, Running, and Maintaining CircleMUD -----
Compiling the MUD
-----------------
CircleMUD 2.0 was developed under Ultrix 4.0. If you have Ultrix or another
BSD-compatible system, and the gcc compiler, you should be able to compile
without any problems. If you don't have gcc, try using cc -- on some
systems such as AIX, the cc compiler is ANSI-compatible.
Non-BSD systems will probably have some trouble with certain functions;
getting Circle to compile for the first time may be difficult and time-
consuming.
The Makefile has options to compile the MUD under AIX. The unmodified
Makefile has been tested and found to work under Ultrix 4.0, SunOS 4.1,
ConvexOS, and IRIX 4.0.5. If you port Circle to another operating system
and wish to share your work with others, feel free to mail me your changes
so that they can be included in future releases of CircleMUD (if any).
The /src directory contains the source code for the main MUD; /src/utils
has the source for a dozen or so MUD maintenance utilities. The makefile
is in the /src directory; type 'make' to compile only the Circle server,
type 'make utils' to compile all the utilities, or type 'make all' to compile
everything. You can also make an individual utility by typing 'make x',
where x is the name of the utility you want to compile. Complete
documentation of the utility programs can be found in utils.doc.
The makefile directs all compiled programs to the /bin directory. Although
not necessary, you may want to put Circle's /bin directory in your $PATH.
Setting the Game Up
-------------------
Your first instinct will probably be to put the game up as fast as possible
to see if it works. That's fine, but there are some files you should be
aware of before you put the game up 'for real'. This is just a partial
list -- see 'files.doc' for a complete list of what all the files in the
Circle distribution are.
First, you'll probably want to take a look at 'config.c' -- it has a bunch
of variables you can set to configure various aspects of CircleMUD.
The place where most of your day-to-day changes will be is in the lib/text
directory; that's where the help files, MOTD (Message Of The Day), imotd
(MOTD for immortals), and other text files are all kept.
In particular, you should make sure to put something in your 'policy' file --
it's better to have definite rules from the beginning than to have problems
later on when people try to bend you as far as they can. Also, you should
put tips for new immortals in the 'handbook' file (i.e., "Don't help any
mortals", "Don't kill mobiles", "Don't run through puddles", "Don't bring
glassware into the pool area", etc.)
The area hierarchy is lib/world. lib/world has 5 subdirectories -- wld,
mob, obj, shp, and zon, which is where the world, mobile, object, shop,
and zone files go, respectively. Each directory has a set of world
files in it with the correct extension (i.e., the obj subdir will have
a bunch of files ending with ".obj", such as 30.obj, 31.obj, etc.) plus
two special files -- 'index' and 'index.mini'. You can control which files
are loaded by Circle simply by changing the list of files listed in 'index'.
'index.mini' controls which (smaller) set of world files should be loaded
in the debugging mode (Mini-Mud Mode, explained below.)
Running the Game
----------------
Circle should always be run from circle's "root" directory, not the /bin
directory. You can run it manually by typing 'bin/circle' (useful for
testing and debugging). For running the game "for real", it's better
to use the 'autorun' shell script provided in Circle's root directory.
Autorun lets Circle run itself for long periods of time. It continuously
runs the game as well as removing old system logs, moving newer system logs
to the /log directory, and saving certain log entries to permanent files.
Autorun can be controlled by creating files with certain names. You can
use the 'touch' command to create a file, and, of course, the 'rm' command
to remove a file. If a file called '.fastboot' exists, the Circle will reboot
immediately if it crashes or is shut down instead of waiting 40 seconds as
it normally does. A file called '.killscript' will cause the script to
terminate itself; i.e., if you want to bring the game down. If you want
to temporarily prevent the MUD from rebooting, create a file called 'pause';
the script will go into a wait loop until 'pause' is removed.
Although you can create these files manually, the SHUTDOWN command from
within the MUD has several command-line options which will create these
files for you. See the SHUTDOWN help entry in wizhelp.doc for more
information.
It's not uncommon for CircleMUD to run for a week without crashing. The
game can be rebooted manually with the SHUTDOWN command, or automatically.
Once a day, at a time specified by the REBOOT_AT macro in modify.c, the
game checks for the existence of the file "reboot" in the selected data
directory. If the file exists, the game is rebooted (it terminates nicely,
with a nonzero return value). If the size of the file is nonzero, its contents
are processed by "sh" (with a system() call). If the processing returns
with a nonzero status, the file is renamed to "reboot.FAILED", and the
rebooting is called off. If it returns zero, the file is moved to
"reboot.SUCCEEDED", and the game is rebooted.
The first character to log in to the MUD (i.e., when the playerfile is
empty) will be made the maximum level. You should fix your stats using
the RESTORE command when you first create the character. To make more
God characters, use the ADVANCE command.
Command-Line Options
--------------------
There are a number of command-line options which Circle will recognize.
You can use these when running Circle manually, or put them in the FLAGS
variable in your autorun script to use them all the time.
The syntax is:
circle [-m] [-q] [-r] [-s] [-d <path>] [<port #>]
-m: "Mini-Mud Mode". Mini-mud will be one of your most powerful debugging
tools; it causes Circle to boot with an abridged world, cutting the
boot time down to several seconds. It is useful for testing features
which are not world-related (i.e, new commands.)
CircleMUD uses split world files (in the lib/world heirarchy); each
directory (i.e., wld, obj, mob, shp, and zon) has a file called 'index'
which specifies which files should be loaded at boot-time. The file
'index.mini' specifies which parts of the world should be loaded with
the -m option.
-q: Quick boot - prevents checking of timed out object files. Every time
Circle boots, it checks every object file to see if it has timed out;
if so, it is deleted. This is done primarily to save disk space. If
time is more important to you than space, use the -q option. -q is
automatically activated when you use -m.
-r: Restrict game to new players. Allows you to decide at run-time whether
the game is open to new players or not; -r is equivalent to typing
"wizlock 1" (see wizhelp.doc for more information).
-s: Disable special routines. This option prevents special procedures from
being assigned. It is obsolete because Circle checks to make sure each
mob exists before assigning a spec_proc to it.
-d: Select data directory. This is useful if you want to keep one or more
sets of game data in addition to the standard set. For example, you may
wish to make a copy of the entire world in a separate directory, so that
you can test additions to the code or worldfile without subjecting the
players to unnecessary hazards. The default data directory is 'lib'.
Any coredumps (may they never happen to you!) will take place in the
selected directory.
port : Select the port on which the game is to wait for connections.
Default port is 4000; you can change the default in config.c and
the PORT= line of the autorun script.
System Logs
-----------
CircleMUD writes a wide variety of information to its log file (called
"syslog"). The syslog contains information about players (i.e., when they
connect, disconnect, rent, unrent, quit, die, hit death traps, etc.) as
well as status information about the game itself. The game-related
information falls generally into 2 categories: usage information and
errors.
Player Information
------------------
The player information recorded by Circle's system logs will serve you
very well as your players start to make wild claims about strange bugs
resulting in them losing equipment or points. Many mudders prey on the
insecurities of a new mud administrator who is terrified that his or her
MUD is riddled with bugs and will do anything to satisfy grumpy players --
don't let yourself fall into that trap! CircleMUD is bound to contain
bugs, but most of the core systems have been well tested, so you should
take claims such as "I magically lost all my stuff!" with a grain of salt
and check your system logs.
If a player ever asks you for reimbursement of equipment, money, gold,
experience points, or whatever, your gut reaction should always be to
check the logs first.
As a sidebar, let me point out that the value of system logs is twofold:
1) they actually provide you with valuable information, and 2) they make
your players paranoid. When I first started mudding and I heard about
this mysterious "system log", it made me incredibly paranoid. Now that
I've done a good deal of MUD administration, I've seen the same paranoia
in _many_ other players.
That paranoia is a very good thing -- the system logs become an abstract
and shapeless but omnipresent force on the MUD. Players hear about "the
System Log" and then get paranoid that everything they do is being
recorded, so they tend to behave, lest the evil System Log betray their
wrongdoings to the Gods.
For this reason, when you go to check your logs, it's a good idea to
say something like "Hold on -- let me go check the system logs, OK?"
because it reinforces the syslog's presence in the collective psyche
of your players.
Back to the point -- when someone claims that they've been wronged by the
evil system, always check the logs. The logs give you power to say things
like "What do you mean your items disappeared in rent -- it says right here
in the logs 'Rasmussen has quit the game.' -- you didn't rent at all, you
just QUIT!"
The logs also record when a player's items are dumped due to insufficient
funds (remember -- rent is calculated per day on a PER-SECOND basis! If you
rent at the rate of 100 coins per day and come back 36 hours later, you'll
be charged 150 coins!). Plus, when someone rents, it records in the logs how
much rent cost per day and how much the player had, to diffuse disputes such
as "But I had enough money!!"
In short: the system logs are your friends. Love them.
The autorun script saves 6 levels of raw system logs. In addition, it
greps the logs for certain pieces of extra-juicy information to save
indefinitely.
Usage Information
-----------------
Every 5 minutes, the game counts how many people are playing and records
that information in the system log. Optionally, if you #define RUSAGE
in comm.c, it will also record system resource information such as CPU time
and memory used.
This information isn't critical, but it is interesting to look at the
usage patterns to determine when your peak playing hours are. If you're
good at using 'cut' and other Unix utilities, you can even dazzle your
friends by graphing your MUD's system usage.
[ Note: friends not included with the CircleMUD distribution. ]
Errors
------
Just as your first gut instinct should be to look at the logs if a player
starts begging you for something, your first gut instinct in the event of
a crash or unexpected shutdown should also be to look at the system logs.
A Unix utility called 'tail' is used to look at the last few lines of a text
file -- it's very useful for seeing the last 10 entries in the system log
to see the last thing that happened before the shutdown. Often, the game
will report an error in the logs just before it crashes.
If there is no core dump, the game probably detected an internal error and
killed itself, and it should always record the error in the log before
dying.
If there's no error message at the end of the file, then there probably
IS a core dump, so you can use 'dbx', 'gdb', etc. to examine the core
dump and determine the reason for the crash. The file 'hacker.doc',
generously provided by Furey of MERC Industries, offers useful insight
into the art and science of debugging -- you'd be well advised to give it
a look-see.
Often, Circle will encounter a serious but non-fatal error; in this case,
the error will be written to the system log with the prefix SYSERR. You
should always be aware of any SYSERRs which occur -- and if they do occur,
try to determine if a change you've made recently has caused it. Don't
just ignore it. The autorun script saves all SYSERRs to the file log/errors.
Day-To-Day MUD Administration
-----------------------------
Okay, so now you have your wonderful CircleMUD up and running and all is
right with the world. Right?
Well, technically, yes. Circle requires very little day-to-day attention
in order to keep the progam itself running smoothly. But the MUD itself
is just a series of instructions running on a computer, processing data.
Never lose sight of the fact that there will be dozens, hundreds, or maybe
even thousands of people connecting to your MUD -- and they are NOT
programs. They're people!
What I'm getting at is this: from the technical side, there are relatively
few things you have to do to keep the game running. But you can't just plop
a MUD on the Internet and then ignore it! Spend time on your MUD. Try to
keep up with the boards, and make an effort to respond to the complaints,
ideas, and suggestions posted there. Take a look at the 'bug', 'typo', and
'idea' files from time to time -- and maybe even respond to some of the ideas
using Mudmail. Try to respond to Mudmail you receive from players in a
timely manner. Make sure that your 'news', 'policy' and other text files
are up-to-date and suit the political climate on your MUD.
If you can't or just don't want to deal with the player politics, make sure
sure that you choose someone who can and will, and make them responsible for
dealing with it. If no one does it, your MUD will stagnate and die.
Maintaining CircleMUD
---------------------
CircleMUD requires little technical maintenance. You should look at the
log/errors file regularly to make sure there are no recurring problems.
Also, you probably will want to 'purge' the playerfile on a regular basis
(i.e., remove "deadweight" characters). You can decide how often to purge
the playerfile -- every day if disk space is tight, or every month if it
isn't. The purgeplay utility program (included) removes deadweight players.
You should run the 'purgeobjs' script (in the lib/plrobjs) directory after
you purge the playerfile -- it removes the object files of players who no
longer exist in the playerfile.
The 'automaint' script in the main circle directory will automatically purge
the playerfile and player objects for you. DO NOT RUN THIS SCRIPT WHILE
THE MUD IS RUNNING!
Good luck with your MUD!
-- Jeremy Elson
jelson@circle.cs.jhu.edu