/* ************************************************************************ * File: running.doc Part of CircleMUD * * * * All rights reserved. See license.doc for complete information. * * * * Copyright (C) 1993-95 by the Trustees of the Johns Hopkins University * * CircleMUD is based on DikuMUD, Copyright (C) 1990, 1991. * ************************************************************************ */ RUNNING WITH IT Compiling, Running, and Maintaining CircleMUD Summary: This document describes how to compile CircleMUD for the first time, configuration information, how to run the server including documentation of command-line options, a description of system logs and how to use them, and a description of daily and long-term maintenance required by the MUD. Intended Audience: Implementors new to CircleMUD or MUD administration in general. This document should be the first documentation read after the main "README" file in Circle's home directory. Table of Contents --------------------------------------------------------------------------- 1. Welcome to CircleMUD! 1.1. Background and Introduction 1.2. Giving Credit Where Credit Is Due 2. Compiling Circle 2.1. Porting and Compatibility Issues 2.2. Makefile Options 2.3. Compiling the Source 3. Running Circle 3.1. Execution and 'autorun' 3.2. Command-Line Options 3.3. Creating an Implementor Character 4. Configuring Circle 4.1. config.c 4.2. Text Files 4.3. World Files 5. System Logs 5.1. Player Information 5.2. Usage Information 5.3. Errors 6. MUD Maintenance 6.1. Technical Maintenance 6.2. Diplomatic Maintenance 7. A Final Thought --------------------------------------------------------------------------- 1. Welcome to CircleMUD! 1.1. Background and Introduction CircleMUD is a derivative of DikuMUD -- the Multi-User Dungeon developed at DIKU (the Department of Computer Science at the University of Copenhagen). Circle 1.0 ran at Johns Hopkins University with moderate popularity from January 1992 to September of 1992. After CircleMUD 2.0 was publicly released in June of 1993, Circle has been maintained as a public code base that anyone can use to start a MUD. The original CircleMUD has not run since it went down in 1992, nor will it ever run again. Hundreds of carefully spent hours have gone into the development of Circle, but it is not a finished product -- it's only a beginning. It has only a small number of spells and skills, a small world with relatively few areas, and only the 4 original Diku classes. From a gamer's point of view, it pales in comparison to other MUDs which have dozens of spells spread over a dozen classes, a rich palette of skills, and thousands upon thousands rooms, mobiles, and objects. On the other hand, from a programmer's point of view, Circle is very highly developed. While the look and feel of the original DikuMUD has been maintained, most of the underlying code and many of the structures have been optimized, reworked, or completely redesigned to be efficient, compact, and easily changeable and extensible. Dozens of features which have become standard in the MUDding world over the past few years, although they were not part of the original Diku release, were added to Circle as well. The result is that CircleMUD is a launching pad for your own MUD ideas. My hope in releasing it is that it will free potential MUD implementors from having to worry about dealing with bug-ridden code or wasting time reinventing the wheel by re-coding standard MUD features, allowing them to devote more effort towards creatively shaping Circle into their own unique vision of how a MUD should look and feel. The reason why Circle has so few specialized spells, skills, classes, and races is to encourage implementors just like you to create your own unique system instead of just another stock MUD that everyone has seen before. So, it is with this message that I inflict my code on the world: don't just put another generic MUD on the Net -- give us something new and exciting, and have as much fun as possible in the process! 1.2. Giving Credit Where Credit Is Due Before doing anything else, please look at CircleMUD license in the file license.doc. USE OF THIS SOFTWARE IN ANY CAPACITY IMPLIES THAT YOU HAVE READ, UNDERSTOOD, AND AGREED TO ABIDE BY THE TERMS AND CONDITIONS SET DOWN BY THE CIRCLEMUD LICENSE. The license is simple. It boils down to the message, "Don't rip off other people's work." Unfortunately, this simple message ended up becoming somewhat long-winded because I was trying to prevent people from abusing DikuMUD in the future as they have in the past. Also, out of courtesy if nothing else, please keep the 'credits' file intact. You can add your own credits on top of the existing file, but I'd appreciate it if you would not simply remove it and all references to the word "Circle" everywhere in the MUD. 2. Compiling Circle 2.1. Porting and Compatibility Issues Ultrix 4.0 was used as CircleMUD's development platform up through v2.00. Starting with 2.10, various versions of Linux were used from 0.99.11 up to 1.1.91. SunOS 4.1.3 on a Sun Sparcstation was also used for testing many versions after 2.20. For Circle 3.0, a great effort was made to make Circle more portable by converting all of its system calls over to POSIX compliance. (POSIX stands for Portable Operating System Interface for UNIX and is an effort to standardize the way UNIX programs talk to the operating system. For more information, see Stevens' excellent book, "Advanced Programming in the UNIX Environment.") Converting Circle to POSIX vastly helps portability on POSIX- compliant systems; most modern operating systems are POSIX-compliant. Unfortunately, on some older systems that are not (such as NextSTEP 2.x), it may be more difficult to compile 3.0 than it was to compile earlier versions. The most important result of POSIX-standard system calls for MUD implementors is that Circle is now compatible with SVR4 versions of Unix. In fact, Circle 3.0 compiles right out of the box under Solaris 2.3 (although it does require extra libraries at the link stage -- see the next section on Makefile options for details). If you have any POSIX-compliant operating system such as SunOS, Solaris, Linux, or Ultrix, and an ANSI- compatible C compiler such as gcc, you should be able to compile Circle with no changes to the source at all. CircleMUD 3.0 has been found to be compatible with the following systems: <still under construction. this is beta documentation, remember?> 2.2. Makefile Options Before trying to compile Circle, take a look at the beginning of the Makefile. It has a number of options for specific operating systems. If you see your operating system listed, activate the appropriate lines as instructed in the Makefile. The Makefile currently has options to compile the MUD under AIX, IRIX, SVR4 systems such as Solaris. If your operating system isn't listed, don't make any changes to the Makefile at all -- just try compiling with the unmodified Makefile. 2.3. Compiling the Source 1) Go into the /src directory 2) Type 'make all' and cross your fingers. The /src directory contains the source code for the main MUD and /src/utils has the source for a dozen or so MUD maintenance utilities. The Makefile itself is in the /src directory. All compiling should be performed from the /src directory. To compile the Circle server alone, simply type 'make'. Type 'make utils' to compile the administration utilities. Type 'make all' to compile both the server and the utilities. You can also compile 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. Despite my best efforts there's a chance that you'll have problems compiling Circle if you're using some version of UNIX that I've never seen before. It's impossible to give general advice on how to port software, except to say that you should ask a friend who knows a lot about both UNIX and C to help you. Also, if you have problems, you should definitely look at the CircleMUD FAQ (Frequently Asked Questions list with Answers), which you'll find in Circle's home directory. If you do port Circle to some other platform successfully, please share your hard work with others by sending a description of what you had to do to get Circle to compile on your system to jelson@jhu.edu. Be sure to include the specific name of your operating system and hardware. 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. 3. Running Circle 3.1. Execution and 'autorun' 1) type 'autorun &' 2) Wait a few moments for the server to boot. 3) type 'telnet localhost 4000'. 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 options which will create these files for you. See the SHUTDOWN help entry in wizhelp.doc for more information. 3.2. Command-Line Options Circle recognizes a number of command-line options. You can use them by actually specifying them on the command-line when running Circle manually; or, by adding them to the FLAGS variable in your autorun script to use the options automatically every time you run the MUD with autorun. 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 hierarchy); 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 Restricted game. Allows you to decide at run-time whether or not the game will allow new characters to be created. Using -r is equivalent to typing "wizlock 1" (see wizhelp.doc for more information). -s Special routines disabled. Allows you to suppress the assigning and calling of all mobile, object, and world special procedures. Historically used as a debugging tool in conjunction with the -d option (see below), but now obsolete because Circle checks to make sure entities exist before attempting to assign a spec_procs to them. -d Data directory. Useful as a debugging and development tool, if you want to keep one or more sets of game data in addition to the standard set, and choose which set is to be used at run-time. 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 world files without subjecting players to unnecessary hazards. The default data directory is 'lib'. Any core dumps (may they never happen to you!) will take place in the selected data directory. port Port selection. Allows you to choose on which port the game is to listen for connections. The default port is 4000, which is historically the port used by most DikuMUDs. You can change default in config.c and the PORT= line of the autorun script. (The PORT= line of config.c simply passes the value as a command-line parameter to circle.) The port specified on the command line or by the autorun script will take precedence over the port specified in config.c. 3.3. Creating an Implementor Character The first character to log in to the MUD will be made the maximum (Implementor) level. If you log in and aren't made an implementor, then the playerfile probably isn't empty -- take the MUD down, delete the playerfile (lib/etc/players), and start the MUD again. You should fix your stats using the RESTORE command when you first create the character (i.e., type "RESTORE <your-name>". Once you're logged in as an implementor, type WIZHELP for a list of privileged commands. Documentation of those commands is contained in the file wizhelp.doc. wizhelp.doc is in the standard help file format, so you can simply add it to the help index file if you want online help available for wizard commands. (wizhelp.doc is not contained in the online help by default as a security precaution.) To create additional wizard characters, log them in normally as level 1. Then, advance them using your implementor character, using the ADVANCE command. See wizhelp.doc for more information. 4. Configuring Circle Once you get over the initial euphoria of having your own MUD compile and run successfully for the first time, you should be aware of some of the files which control how Circle looks and feels so that you can configure it for your personal taste. 4.1. config.c The most useful file for configuration is the config.c source file. It has dozens of options useful for customizing your MUD. Before you open your MUD to players, you should read through config.c from beginning to end, checking what options are available as well as making sure they're all set the way you want them. Remember, you have to recompile and rerun the MUD before any changes you make to config.c take effect, of course. 4.2. Text Files The place where most of your day-to-day changes will be is in the lib/text directory, which contains all of the text files read by players. The most visible file is "motd", (Message Of The Day), which is the message that mortals seen (though not necessarily read!) when they log in. Similarly, the "imotd" (Immortal MOTD) is seen by immortals when they log in. Other interesting files are "news" (for the NEWS command), "help" (for the HELP command), "help_table" (for HELP <x>), and others. One file is particularly important: "policy". Despite what anyone tells you and your best efforts to the contrary, your MUD will have political problems. If anyone tells you that you can run a MUD without politics, they're wrong. If you tell your players that you're going to run a revolutionary MUD that doesn't have any politics, you're lying. Every MUD has political problems sooner or later (usually sooner). There are various ways to make political problems easier to handle, but the best way is to decide on some ground rules from the very beginning, and then set those decisions down in writing. That's what the "policy" file is for. You probably know what kind of political problems MUDs have (you're not trying to run a MUD without ever having played one, are you!?) -- stuff like playerkilling, thieving, kill stealing, client use, multi-char playing, reimbursements, etc. Decide on your policies early and make sure your characters know what those policies are. It's also important to set down in writing rules for what immortals are allowed to do and not allowed to do. That's what the "handbook" (Immortal Handbook) is for. Immortals will always try to bend you as far as they can, so it's important for you to decide on answers to questions before those questions come up. Can immortals assist players? What about giving a single 'cure light' for a player about to die? Can immortals kill mobiles for their own enjoyment? Can they kill players for the same reason? Are they allowed to make policy? Break policy? Moderate disputes? Turn over each others' decisions? 4.3. World Files The root of 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 appropriate 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 called "index" and "index.mini". "index" is a list of which world files are to be loaded by Circle. This makes the job of adding new areas easier -- just add the new area files to your area directory, and then add the name of the new file to "index". "index.mini" controls which (smaller) set of world files should be loaded in the debugging mode (Mini-Mud Mode, explained below.) 5. System Logs CircleMUD writes a wide variety of information to standard output and standard error. If you're using the autorun script, the boot messages are put into a file called "syslog". During Circle's boot sequence, the system log 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 player information, recording when players connect, disconnect, rent, unrent, quit, die, hit death traps, etc. The game also records status information about itself, falling generally into two categories: usage information and errors. 5.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 (XP), 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!" To diffuse disputes such as, "The game dumped my stuff, but I had enough money!!", two types of log entries are written. First, every time a character rents, the log records the character's per diem rent rate as well as the total amount of money on hand and in the bank. Second, the log records makes a record of all characters' equipment dumped due to insufficient funds. Remember, rent is specified as a daily rate but is amortized on a per- second basis! In other words, if you rent at the rate of 100 coins per day and come back 36 hours later, you'll be charged 150 coins. 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. The system logs are your friends. Love them. 5.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. ] 5.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 preceded 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 encounters 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 foreseeing 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. 6. MUD Maintenance 6.1. Technical Maintenance Once you get the MUD up and running, you'll surely want to modify it -- adding new areas, new features, new code, and new ideas! But, those topics are beyond the scope of this document. See coding.doc, areas.doc, and other creation documents for more information about how to customize your MUD once you get it up and running. This section simply focuses on some of the simple maintenance that'll be necessary to keep your MUD running smoothly. Make sure not to get so caught up in being a God that you forgot you're also supposed to be acting as a software engineer! First, you should look at the log/errors file regularly to make sure there are no recurring problems, particularly problems that may have been caused by code you've added. If the MUD crashes, it will usually generate what's called a "core dump" -- a big file called "core" in your lib directory, created by the operating system to record the state the game was in the moment before it crashed. You should look at the core dump using a debugger such as "gdb" or "dbx" to determine why the MUD crashed. See the file "hacker.doc" for more information about debugging. You probably will want to clean out the playerfile on a regular basis to remove deadweight characters (i.e., people who log in and look around for 10 minutes, and then never come back). 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 in the src/util directory removes deadweight players. Make sure to run the "purgeobjs" script (in the lib/plrobjs directory) after you purge the playerfile. purgeobjs 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. 6.2. Diplomatic Maintenance Okay, so now you have your wonderful CircleMUD up and running smoothly and all is right with the world. Right? Wrong. Well, technically, right. Circle requires very little day-to-day attention in order to keep the program 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! From the technical side, there are relatively few things you have to do to keep the game running. But you can't just dump 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 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. 7. A Final Thought Try to remember that running a MUD should be fun. It can sometimes be easy to lose sight of the ultimate goal of personal enjoyment that MUDs are supposed to provide, particularly when MUDs start to get crushed under the weight of their own politics or the egos of the administrators. If you find that your MUD is more of a source of frustration than enjoyment, don't be afraid to close it. Good luck with your MUD! And, always feel free to write me and let me know what you think of the MUD, and the interesting things you've done with it. I can't promise a timely response, but I love hearing from people who are using my code. Jeremy Elson jelson@jhu.edu