This is the README file for TinyMUX 1.1.
*** When you unload the database to flat file format it is important to use
your original db_unload/dbconvert.
Refer to the file CHANGES for information about new features, commands,
and bug fixes.
The latest version of this code can generally be found running at:
Children of the Atom: bison.range.orst.edu 2099
Conversions from Other Database Formats:
---------------------------------------
TinyMUX 1.1 has been proven to read the following database formats:
TinyMUSH 2.0 (all versions)
TinyMUSH 2.2.0 or 2.2.1 release version (not beta)
PennMUSH 1.50 patchlevel 8-15.
PennMUSH DarkZone 1.50.
Instructions for Building:
-------------------------
[NOTE: It is HIGHLY recommended that you preserve a previous setup if you
had one while converting, and make sure the conversion process has completed
successfully before you delete your old distribution.]
1. cd to the src/gdbm-1.7.3 directory. Run 'configure', then 'make'.
2. cd .. back to the source directory. Run 'configure'. This will customize
autoconf.h and Makefile for your system.
3. Edit the Configuration section of the Makefile. Most likely, all you will
need to change are any C flags needed by your particular C compiler,
(in particular -fpcc-struct-return), and any esoteric libraries needed by
your system. Also, there are some #defines in config.h that you may want
to change, but in general, the defaults should not be changed.
Within the Makefile, you can also enable:
- Memory based database handling (as opposed to the default disk
based handling, see README.MEMORY)
- Radix string compression (see README.COMPRESSION)
4. Run make depend, then make. This will produce netmux, mkindx, slave,
and dbconvert.
5. Here are some hints to remember if you are installing for a previously
existing setup:
- All databases go in game/data. All text files go in game/text.
- The scripts db_load, db_unload, and db_check may be found in the
game/data directory.
- If you change the GAMENAME in mux.config, be sure to change the
filenames in <gamename>.conf as well.
- You should NEVER need to modify anything in the bin directory.
- You should ALWAYS unload to flatfile, and reload when you change
or upgrade distributions.
- Read 'wizhelp config parameters' when you get the MUX started.
If you are upgrading from PennMUSH, for example where the master
room is set as #2, you would have to place the config parameter
'master_room 2' in your configuration file.
- Database numbers in <gamename>.conf should NEVER have '#' in front of
them, only the number itself is necessary.
- If you had a mail database previously, remember to adjust
mail_expiration accordingly, or else ALL @mail older than the
default value of 14 days will be deleted.
- If you do not want to use the built-in +help command, redefine
PLUSHELP_COMMAND in config.h to be something else.
5a. If you are starting from scratch, do the following:
- cd to the game directory.
- Make your configuration file, as described later in this file under
the heading 'Making a New Configuration File'
- [csh] bin/netmux -s <your-mud-name>.conf >& <your-mud-name>.log &
[sh] bin/netmux -s <your-mud-name>.conf > <your-mud-name>.log 2>&1 &
- Log in to the mud as player wizard (password potrzebie), and shut it
down.
5b. If you are converting an existing TinyMUSH 2.0 database created by
patchlevel 0 (database version 3), do the following:
- cd to the game directory.
- Log in to the mud and shut it down. If you are running a script
to automatically restart the mush if it goes down, also kill that
script.
- Unload the database with the command:
o db_unload <mud-name>.gdbm <mud-name>.db.new <mud-name>.db.FULL
- cd to the source directory.
- Run make install.
- cd back to the game directory.
- Delete the files <mud-name>.gdbm, <mud-name>.db, and <mud-name>.db.new
- Reload the database with the command:
o db_load <mud-name>.gdbm <mud-name>.db.FULL <mud-name>.db.new
5c. If you are converting an existing TinyMUSH 2.0 database created by
patchlevels 1 through 4 (database version 4) or patchlevels 5 or 6
(database version 5) do the following:
- cd to the game directory.
- Log in to the mud and shut it down. If you are running a script
to automatically restart the mush if it goes down, also kill that
script.
- Unload the database with the command:
o db_unload <mud-name>.gdbm <mud-name>.db.new <mud-name>.db.FULL
- cd to the source directory.
- Run make install.
- cd back to the game directory.
- Delete the files <mud-name>.gdbm.db, <mud-name>.gdbm.dir,
<mud-name>.gdbm.pag, <mud-name>.db, and <mud-name>.db.new
- If you are running on an HP-UX system, create the database files:
o touch <mud-name>.gdbm.db <mud-name>.gdbm.dir <mud-name>.gdbm.pag
o chmod 600 <mud-name>.gdbm.*
- Type 'head <mud-name>.db.FULL'. If the first line is '+V8710',
do the following:
o mv <mud-name>.db.FULL <mud-name>.db.FULL1
o echo '+V8709' | cat - <mud-name>.db.FULL1 > <mud-name>.db.FULL
o In the next step, ignore the error
'Duplicate MUSH version header entry ...'
- Reload the database with the command:
o db_load <mud-name>.gdbm <mud-name>.db.FULL <mud-name>.db.new
5d. If you are converting a PennMUSH 1.50 database:
- Copy the database to the MUX directory, and rename it to
<mud-name>.db.new.
- Copy the mail database to the MUX directory and rename it to
mail.db, or whatever your mail_database configuration option is
set to.
- Run 'Startmux', log in to the MUX as a wizard and shut it down.
- NOTE: If you are experiencing conversion problems with your Penn
database, reload your old Penn setup, and do a @dump/paranoid.
This should eliminate hard newlines that mess up the conversion
process.
5e. If you are converting a PennMUSH DarkZone database:
- Copy the database to the MUX directory, and rename it to
<mud-name>.db.
- Append your mail alias database to the end of your mail database,
using cat or a similar utility.
- Copy the mail database to the MUX directory and rename it to
mail.db, or whatever your mail_database configuration option is
set to.
- Copy the COMMAC.DB to the MUX directory and rename it to commac.db,
or whatever your commac_database configuration option is set to.
- Run 'Startmux', log in to the MUX as a wizard and shut it down.
- NOTE: If you are experiencing conversion problems with your DZ
database, reload your old DZ setup, and do a @dump/paranoid.
This should eliminate hard newlines that mess up the conversion
process.
5f. If you are converting a database from TinyMUSH 2.0.10 or Tinymush 2.2:
- cd to the game directory.
- Log in to the mud and shut it down. If you are running a script
to automatically restart the mush if it goes down, also kill that
script.
- Unload the database with the command, making sure to use your
ORIGINAL dbconvert:
o db_unload <mud-name>.gdbm <mud-name>.db.new <mud-name>.db.FULL
- Copy <mud-name>.db.FULL to the MUX directory.
- Reload the database with the command, using your new dbconvert:
o db_load <mud-name>.gdbm <mud-name>.db.FULL <mud-name>.db.new
6. Edit the .txt files to your liking, in particular connect.txt and motd.txt.
This is not necessary if you are reinstalling TinyMUX 1.1.
7. Start up TinyMUX 1.1 by running Startmux.
8. @ccreate a channel named 'Public', and a channel named 'Guests' from
within the MUX. Created players will automatically be joined to 'Public'
with alias 'pub', guests will automatically join 'Guests' with alias 'g'.
Making a New Configuration File:
-------------------------------
TinyMUX 1.1 gets the information it needs to operate the game (aside from
the database itself) from a configuration file that is read in at startup.
The configuration file contains various parameters, such as where to find
the database, what port to listen for connects, and many other things.
Follow these instructions to make a configuration file for your mush from
the supplied template configuration file:
In your game directory, copy the file netmux.conf to <your-mud-name>.conf
and edit it as follows:
- Replace netmux.<whatever> in the 'xxx_database' lines with
<your-mud-name>.<whatever>.
- Set the port number on the 'port' line to the correct port.
- Set the mud name on the 'mud_name' line to the name of your mud.
- Make any other configuration changes you want to make at this time.
Here are some of the common ones to change:
o money_name_singular <text> The name of one coin (penny)
o money_name_plural <text> The name of several coins (pennies)
o fork_dump no Do this if you have little swap space.
o paycheck <amount> Players get this much money each day
they connect.
o paystart <amount> Players start out with this much money.
o payfind <chance> Each time a player moves, he has a
1 in <chance> chance of finding a penny.
o player_starting_room <roomno> The room that new players are
created in.
There are many more configuration directives available. Information
on individual directives can be obtained with the WIZHELP <directive>
command within the mush.
Tuning the Database Cache:
-------------------------
Hi. Andrew Molitor here. I am not exactly an expert on cache tuning, but
then, nobody is. It's something of a black art. The basic tradeoff here is
this: If you make your cache larger, it will consume more memory, but you
will have to make disk accesses less often to get data. This sounds great,
until you remember that if you consume *enough* memory, the operating system
will begin to page random bits of your game on and off of disk -- you are
better off staying small enough to not have that happen, and do your own
getting data on and off disk.
So, you want your cache as large as possible until it gets Too Large, which
is usually when you begin to page too much (more hard page faults in the
output on @list process than I/O in the read column on @list db_stats is a
reasonable guideline. Ideally many fewer page faults), or when your sysadmin
comes pounding on your door wondering what that ENORMOUS process is you have.
What about depth and width? Well, the wider it is, the faster you'll look
things up in it, but the shallower it is, the more it will tend to 'stretch'
outside the specified size. As a guideline, a depth of 9 or 10 seems to be
minimal, and for a few hundred wide, make it at least 15 deep. That's for
object level caching (recommended). For attribute level cacheing, make it,
oh, 50 percent deeper?
There are some statistics you should be aware of:
- paging -- the hard page faults field of @list process cache hit
ratio. The percentage of total reads (ignore writes, they rarely
amount to anything) which require I/O. See @list db_stats for these
numbers, the 2nd column is where to look. Total calls and I/O are the
numbers to be looking at.
- cache size -- this is right at the bottom of the output from @list
db_stats.
If your cache size is, after running a bit, larger than the original depth X
original width, your cache is 'stretching', and is probably too shallow, and
possibly too small.
If you are making a lot of page faults, your process size is too large, try
shrinking the cache, or filtering out unused attributes, or both, to shrink
process size.
If your cache hit ratio is under about 95-97 percent, your cache is probably
too small, and it should grow. Either wider or deeper, wider is preferable
unless your cache tends to stretch, see above.
It's a careful dance you need to do, so watch the statistics, and don't be
afraid to try tinkering with the cache size this way and that. Note that
under SunOS (and SysV?) doing I/O will tend to generate page faults as well,
so shrinking your cache may force the database to do more reading and writing
of the disk, and actually increase the number of page faults! So don't just
twiddle a parameter and call it done, watch those numbers!
Good luck ;)
What to do if you find a bug:
----------------------------
- Make sure it really is a bug and not a new feature or design decision.
(If it crashes the mux, it's a bug) If you can't tell, consider it a bug.
- Try to come up with an easily-reproducible sequence of events that will
demonstrate the bug.
- Send us mail about it at: lauren@ranger.range.orst.edu
If the bug crashes the mush, try to include the following information
from running dbx (or gdb) on the resulting core file:
- Output of the 'where' command.
- Output of the 'dump' command for each procdeure level.
- To use gdb or dbx, make sure you are in the game/ directory, and type
gdb bin/netmux core OR dbx bin/netmux core
- From there, simply type 'help' for help, or 'quit' to exit.
Environment:
-----------
TinyMUX 1.1 should run on must Unixes with BSD-style sockets and a C compiler
that groks function prototypes. It has been run successfully on the following
platforms:
SunOS 4.1.3, 4.1.4
Linux kernels 1.2.3 - 1.3.5
NeXTStep version 2.0
FreeBSD 2.0.5R
Solaris 5.4
Ultrix 4.2
AIX 4.0
If you get TinyMUX 1.1 working on another platform, please let us know
about it!