403 lines
18 KiB
Plaintext
403 lines
18 KiB
Plaintext
/**************************************************************************
|
|
* Copyright (C) 1993 - see 'license.doc' for complete information. *
|
|
**************************************************************************/
|
|
|
|
----- Compiling, Running, and Maintaining CircleMUD -----
|
|
|
|
|
|
This manual is meant to be read by implementors just getting started with
|
|
CircleMUD. This should be the first document you should read after reading
|
|
the main README file.
|
|
|
|
It should be the first documentation you read (after the
|
|
README file in theIt describes how to get the MUD compiled, configured, and
|
|
running; use of command-line options and system logs; and required daily
|
|
maintenance.
|
|
|
|
This i
|
|
|
|
Table of Contents
|
|
---------------------------------------------------------------------------
|
|
|
|
1. Compiling Circle
|
|
1.1. Compatibility Issues
|
|
1.2. How-To
|
|
2. Configuring Circle
|
|
3. Running Circle
|
|
3.1. Execution and 'autorun'
|
|
3.2. Command-Line Options
|
|
4. System Logs
|
|
4.1. Player Information
|
|
4.2. Usage Information
|
|
4.3. Errors
|
|
|
|
|
|
1. Compiling Circle
|
|
-------------------
|
|
|
|
1.1. Compatibility Issues
|
|
|
|
Ultrix 4.0 was used as CircleMUD's development platform up through v2.00;
|
|
starting with 2.10, Linux 0.99.11 was used instead. If you have Ultrix,
|
|
Linux, or another BSD-compatible system, and the gcc compiler, you should
|
|
be able to compile right out of the electronix box. If you don't have gcc,
|
|
try using cc -- on some systems such as AIX, the cc compiler is ANSI
|
|
compliant.
|
|
|
|
The author has personally compiled CircleMUD under the following systems:
|
|
|
|
Ultrix 4.0
|
|
IRIX 4.0.1, 4.0.4, 4.0.5
|
|
SunOS 4.1.1, 4.1.3
|
|
AIX 3.2
|
|
Linux 0.99.11
|
|
ConvexOS V10.2
|
|
|
|
Others have reported successfully compiling Circle under many other
|
|
systems; if you have a BSD-compatible system, chances of getting Circle
|
|
to compile easily are pretty good. Non-BSD systems will probably have
|
|
trouble with certain functions; getting Circle to compile for the first time
|
|
on such systems may be difficult and time-consuming. SVR4 compatibility is
|
|
on the horizon; many functions have already been converted to be SVR4
|
|
compatible, but the code has not yet been fully ported.
|
|
|
|
The Makefile has options to compile the MUD under Linux, AIX, and IRIX.
|
|
It also has an option for SVR4 but, as mentioned above, it does not
|
|
yet completely work. The unmodified Makefile should work with many other
|
|
including those listed above.
|
|
|
|
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). You'll be given credit, of
|
|
course. :)
|
|
|
|
|
|
1.2. How-To
|
|
|
|
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' while in that directory 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.
|
|
|
|
|
|
|
|
|
|
2. Configuring Circle
|
|
---------------------
|
|
|
|
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 description of all the files in the
|
|
Circle distribution.
|
|
|
|
First, you'll probably want to take a look at 'config.c' -- it has dozens
|
|
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.)
|
|
|
|
|
|
|
|
|
|
3. Running Circle
|
|
-----------------
|
|
|
|
3.1. Execution and 'autorun'
|
|
|
|
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.
|
|
|
|
|
|
3.2. 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 or spells).
|
|
|
|
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 still supported but 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.
|
|
|
|
|
|
|
|
|
|
4. System Logs
|
|
--------------
|
|
|
|
CircleMUD writes a wide variety of information to its log file (called
|
|
"syslog"). During Circle's boot sequence, the syslog keeps a record of
|
|
everything the MUD is doing to initialize itself; this can be useful to
|
|
determine what the problem is if the MUD dies while it is booting. Once
|
|
the game is up and running, 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.
|
|
|
|
|
|
4.1. 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.
|
|
|
|
|
|
4.2. 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. The usage information currently logged by Circle is,
|
|
as you can see, somewhat sparse; local MUD admins are encouraged to add
|
|
to this code as is appropriate for their particular site.
|
|
|
|
Usage 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. ]
|
|
|
|
|
|
4.3. 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 looking at the last entries in the system
|
|
log to see the last thing that happened before the shutdown. Often, Circle
|
|
will report an error in the logs just before it crashes. This method is
|
|
particularly useful if the MUD crashes during its boot sequence, because
|
|
the logging during boot is intensive.
|
|
|
|
If Circle shuts down unexpectedly and there is no core dump in the /lib
|
|
directory, the game probably detected an internal error and killed itself.
|
|
Such shutdowns are always preceeded by entries in the system log describing
|
|
the error.
|
|
|
|
If there's no error message at the end of the log, 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.
|
|
|
|
Circle sometimes encouters a serious but non-fatal error; in this case,
|
|
the error will be written to the system log with the prefix SYSERR, but
|
|
the MUD will not shut itself down. You should always be aware of any
|
|
SYSERRs which occur -- they are often useful for forseeing imminent danger
|
|
or averting problems before they become critical. If a SYSERR does
|
|
occur, try to determine if a change you've made recently has caused it.
|
|
Ignoring SYSERRs is like ignoring compiler warnings: you can be tempted
|
|
to ignore them because the game keeps going even if they exist, but you
|
|
can easily get yourself into trouble by not listening. 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! Doing so will make your life (more) difficult.
|
|
|
|
|
|
|
|
Good luck with your MUD!
|
|
|
|
|
|
|
|
-- Jeremy Elson
|
|
jelson@cs.jhu.edu
|