This is the document for TeenyMUD 1.1. Seems quite solid. In general, a lot of minor bug fixes over 1.0, and some fairly major improvements. See below. Introduction ------------ TeenyMUD is a disk-based clone of the TinyMUD server. It is completely new code, and is not based on the original TinyMUD code at all. It is NOT written in ANSI C. The game implemented by TeenyMUD is a fairly vanilla version of TinyMUD -- pages, whispers, emotes (':' command), NO pronoun substitions, NO message pages, NO Muck extensions and so on. What follows is somewhat technical, but I frankly think you really need to read and understand all of it to run TeenyMUD with any degree of success. Bringing the server up ---------------------- First you have to make the thing. There is a Makefile supplied, typing 'make teeny' at the shell prompt should do it. In order to bring the server up coherently, you need to understand vaguely how the server works, so here we go: The database is stored in two files, an index file and a chunks file. We'll get to the index file shortly. The chunks file is where most of the data lives, scattered about more or less at random in the file. When data is required, it is read in from this file and 'cached' in memory, subsequent accesses to the same data can use the cached data and avoid referencing the disk. The cache size is limited, however, so when too much data is read in, the least recently referenced data is tossed out of the cache, and written back to the chunks file if it has been changed since it was read (or is data for a completely new object). Subsequent references to that data will then, of course, force the data to be read back in from the chunks file. The index file is used to store data about where in the chunks file the data for any particular object can be found. In general, this data is read in when the server is brought up, and kept in memory permanently. Along with this data is stored the flags and name of each object in the database -- these are referenced rather frequently, and so are stored with the permanently-in-memory data. Incidentally, back of the envelope computations suggest that the permanent memory usage of each object will be about 50 to 60 bytes, roughly one fifth of what a TinyMUD uses per object. This does not include the cached data, of course. The upshot of all this is that the index file on disk holds the locations of everything in the chunks file at server startup time. Since things are constantly being read from, and written back to the chunks file (at possibly different places), the index file rapidly becomes wildly inaccurate. The correct data is, of course, always available in memory. Furthermore, the data in the chunk file is not completely up to date, since a recently changed object may well be in the cache and not written back to the chunks file. Thus, the server does periodic dumps to write everything back to the chunks file, and rewrite the index file to correctly reference all this data -- i.e. 'bring the db into synch'. The server then immediately copies the index file to 'old.index' and the chunks file to 'old.chunks'. If the server crashes, the active index and chunk files are rubbish, but the 'old.index' and 'old.chunk' form, as a pair, a database correct and complete up to the last dump. Suitable use of the cp command should let you bring the server back up as of the most recent dump. The server accepts several command line flags: -l specifies that an existing database (index/chunkfile pair) is to used. Without this flag, the server will create a minimal database (Limbo and Wizard) from scratch. This flag cannot be used with the -t or -s flags. -s specifies that a small initial database -- Limbo and Wizard -- should be built and used. -t <text database> loads a text dump database, instead of an indexfile/chunkfile pair. See below for more on this type of database. This flag cannot be used with the -l or -s flags. NOTE: You MUST use exactly one of the -l, -s, -t flags to tell the server where to get its database. The following flags are optional. -C n specifies that a cache of size n kilobytes is to be used. -c <name> specifies the name to use for the chunkfile (defaults to chunky.bits if this flag is absent). -i <name> specifies the name to use for the index file (defaults to chunky.index if this flag is absent). Typically, you will first start the server with the -s flag, to force it to build an initial database into chunky.bits and chunky.index. Then you may shut the server down, and use the supplied startserver script to bring it back up with a log file named 'logfile' and load this database. The Console ----------- Running the server in the foreground gives you access to the console. Pressing ^C (sending the server process a SIGINT) will cause the MUD to freeze completely, and give you a console prompt. The console accepts a few commands: s shut the server down after dumping the database. d dump the database w console WHO list. Shows who has 'Blown Quotas' -- i.e. who is spamming the server with lots of commands rapidly. b n boots player n off the game g 'go'. Stops the console, and lets the server continue. t [str] create a text dump of the current database. This may be loaded at some later time by invoking the server with the -t flag. Optionally, the name of the text dump file may be given here (e.g. t dump.text). If no name is given, the default name, teeny.text, is used. The console is useful for a few things. Starting the initial database can be accomplished by starting the server in the foreground, with the -s flag, pressing ^C, and typing 's' at the console prompt. This has the effect of building the initial minimal database (Wizard and Limbo), and then shutting down the server, dumping this database into a usable chunks file/index file pair. The -l flag can then be used when restarting the server. If someone is spamming your game, sending it thousand of commands rapidly, and if you can foreground the server, you can grab the console, type 'w' to see who has lots of blown quotas, and boot them off with a suitable 'b' command. This capability exists because of what happened to Islandia on its last night. TeenyMUD is not, in general, spammer friendly -- when a player's command quota runs out in a given time slice, Teeny does not merely slow them down, it throws commands from that player away for the duration of the time slice. The text dump and load facilities are useful for portability and de-fragmenting your database. Attempting to move an existing index file/ chunks file pair to a new machine is probably a bad idea, and bad things may well result. To move to a new machine, use the t command on the console to create a text dump, move the text dump file to the new hardware, and load it into the server with the -t flag on the command line. Doing an immediate console dump (or shutdown) will create an index file/chunks file pair that can be used on the new machine. In addition, each time a dump occurs, fragmentation data is written to the log file (i.e. on standard error). This consists of 4 numbers, each counting the number of free chunks (holes) in your chunkfile in a certain range of sizes. The first number is the number of free chunks of size zero or less, and should *always* be a zero. The second is the number of non-empty free chunks too small to be used for anything, the next is the number of chunks of useful size less than 512 bytes, and the last number is the number of free chunks of size greater than 512 bytes. All these numbers should be 'small', whatever that means. If they indicate that an unsatisfactory percentage of your chunkfile is taken up by unusably small chunks, your database is said to be 'fragmented'. To de-fragment, you can bring the server up, do a text dump from the console, shut the server down, and immediately restart with the -t flag to re-load the text dump. This simply rebuilds a new copy of the old database, but does so in a 'sequential' fashion, which leaves no holes in the chunks file. If you dump from the console immediately, you should get Fragmentation data of '0 0 0 0'. Configuring the server ---------------------- You will need to make some changes here and there to set the server up to work as you want it to, mostly to #define directives in includes/teeny.h. First, you need to edit the text hardcoded in the function 'greet()' in misc.c to greet players with a banner more appropriate to your game. You may also want to fiddle with the values of the TIME_SLICE and SLICE_QUOTA and DUMP_INTERVAL in includes/teeny.h. TIME_SLICE and SLICE_QUOTA are probably fine as distributed. These two define, roughly, how spammable your MUD is. Each player is allowed SLICE_QUOTA commands in each TIME_SLICE interval. DUMP_INTERVAL is, of course, the frequency at which to dump the database as described above (NOT text dump -- this can only be done from the console). Added in version 1.1 is TIMESTAMPS. This does not actual provide full timestamping. What it does do is build a database library capable of supporting timestamping, the MUD databases (both chunks file, and text dump) will have timestamp fields in them. NOTE: This obseletes older databases, though probably a text dump could be converted with a trivial script. A function stamp(<object number>) exists in utils.c. Scribbling suitable calls throughout the code will cause timestamps to be somewhat meaningful. See internals.doc for details. Defining LOGCOMMANDS will cause all player commands (except WHO and QUIT) to be logged on standard error (your logfile). Commenting this define out will turn logging of player commands off -- probably a good idea. Log files get very large otherwise. Other defines that are probably ok as distributed are the SLACK and GROWTH_INCREMENT constants defined in includes/db.h. You may want to tweak these in, say, a fast growing MUD. SLACK is the amount of free space added to the index above and beyond the number of objects currently in the database. If this is greater than the number of objects created between the time the server is started, and the time it is shut down, then the index will never have to be re-sized. This is good, because re-sizing the index tends to waste memory. The GROWTH_INCREMENT constant is the number of index entries to be added to the index in the even that it should become necessary to re-size it. The port upon which the server listens for new connects (the port at which the server 'lives') is defined by MUDPORT in mud/tcpio.c. It is distributed as 6666. Lastly, you will need to select a cache size for your game -- this is slightly tricky and depends on several factors. I see two reasonable approaches to this problem: a) determine how much real memory you will typically have to run the server with, and tune the cache so that the virtual memory size is roughly equal to this. You should NEVER run the server with a cache so large that the virtual size is routinely greater than the real size -- if the operating system starts to page your cache in and out of its own paging/swapping files, performance will drop sharply. See your local man page on ps, and ask around if you don't understand all this. b) determine how many players will be active during fairly busy periods, and make the cache large enough to hold the data associated with them, and any 'social' rooms that will usually have players in them. Roughly, multiply the number of players plus the number of rooms by, say, 2K and double that for a fudge factor. This will allow the commonly referenced things to be usually in cache, and you will just have to accept that exploring players, will cause a fair amount of disk activity. The first option will give you a the maximum size cache you should be using, the second will be the minimum. Note that you should periodically re-tune your cache, since as your database grows, the amount of permanently resident data (the flags and names) will grow. If you have your cache tuned with a small database to approximately fill available real memory, when the database grows so will your process size, your server will start to page and performance will drop. Also, keep an eye on the load your machine is under, and re-tune appropriately. As I have not run any benchmarks, the above remarks on cache tuning are merely educated guesses on my part. Cache tuning is well known to be a black art. The Wiz Password ---------------- Ok, you made it this far, so I'll tell you what how to log in as the Wiz in the minimal db you get at the beginning. The name is 'Wizard', the password is 'foo'. CHANGE THIS PASSWORD. Note that you have to be sort of careful as a wiz, in particular you can turn off your own Wiz bit. This is not a good idea. In addition, TeenyMUD has no God Priv, so all wizards have the same powers (somewhat extensive). The Future ---------- I have no plans whatsoever to extend this server at all. I hope to fix bugs as they appear, and no more. You, gentle reader, may want to hack at the server a little or a lot. Read the internals document if you plan to do so. Andrew/bob