This is the README-2.0 file, originally for TinyMUSH 2.0. If you are
reading it and you haven't read the README file yet, you are out of
order. Go back.
Notice: The database format has changed between 2.0.p6 and 2.0.p7. If you
are running TinyMUSH 2.0.p6 or earlier, you will need to back the database
down to flat file format and reload it. Instructions for doing this are
included later in this file.
TinyMUSH 2.0.p7 supports two styles of cacheing: by object and by
attribute. The default cacheing style is attribute-level cacheing, read the
Makefile for instructions on using object-level cacheing. The two cacheing
styles use different database formats, so switching from one style to the
other requires a db_unload -> recompile -> db_load sequence.
*** When you unload the database to flat file format it is important to use
your original db_unload/dbconvert (most likely from 2.0.p6). 2.0.p6 and
2.0.p7 use different methods for locating attributes in the attribute
database, and neither can find attributes stored by the other. DO NOT
use the db_unload/dbconvert that you build from the 2.0.p6 sources to
unload anything but a 2.0.p6 database.
TinyMUSH 2.0 has been greatly improved over earlier versions of MUSH,
many new features, bug fixes, and performance and security improvements
have been made:
o Overall performance: Many areas in the code that performed linear
searches of large lists have been rewritten to use hashed lookups.
o Network traffic: Output is now coalesced into larger blocks before being
sent. This results in fewer and larger blocks of text being sent out
over the network.
o Memory use for large databases: The attribute text strings have been
moved to a separate disk-based database, and cacheing is used to keep
recently-referenced attributes in memory.
o Improved security: The command parser has been rewritten to fix the
bugs that let players coerce programmed objects into performing
unintended commands for them.
o User-named attributes: Users can define new attributes on objects in
addition to the standard attributes.
o Builtin support for transmitting WHO data to a remote RWHO server.
o Many new commands, functions, attributes, and flags.
o Most of the constants that were previously hardcoded or were defined
as #define constants may now be set via a runtime configuration file.
Refer to the file CHANGES for information about new features, commands,
and bug fixes.
Conversions from Other Database Formats:
---------------------------------------
TinyMUSH 2.0 is able to read the following database formats:
TinyMUD (up to version 1.5.5)
TinyMUSH Classic
PernMUSH/PennMUSH (up to version 1.19)
[ except for version 1.16 through 1.17.01 ]
TinyMUSH 2.0 (all versions)
TinyMUSE (up to database format 7)
Instructions for Building:
-------------------------
1. Run 'configure'. This will customize autoconf.h and Makefile for your
system.
2. 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), any esoteric libraries needed by
your system, and the location of the MUSH game files.
3. Run make. This will produce netmush, mkindx, and dbconvert.
4a. If you are starting from scratch, do the following:
- Run make new-install.
- cd to the game directory.
- Make your configuration file, as described later in this file under
the heading 'Making a New Configuration File'
- [csh] netmush -s <your-mud-name>.conf >& <your-mud-name>.log &
[sh] netmush -s <your-mud-name>.conf > <your-mud-name>.log 2>&1 &
- Log in to the mud as player wizard (password p0trzebie), and shut it
down.
4b. If you are converting an existing pre-TinyMUSH 2.0 database 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.
- Make a backup copy of your original database.
- cd to the source directory.
- Run make new-install.
- cd back to the game directory.
- Make your configuration file, as described later in this file under
the heading 'Making a New Configuration File'
- If you are loading a PernMUSH database from PernMUSH version 1.12
or earlier:
o Examine the first line of the database (with head or another
similar tool). If the first line is not '+V2', do the following:
. echo '+V2' | cat - <database-name> > tempfile
. mv tempfile <database-name>
o Load the database with the command:
. db_load <mud-name>.gdbm <database-name> <mud-name>.db.new
- If you are loading a PernMUSH database from PernMUSH version 1.13
to 1.15:
o Examine the first line of the database (with head or another
similar tool). If the first line is not '+V2', do the following:
. echo '+V2' | cat - <database-name> > tempfile
. mv tempfile <mud-name>.db
o Make your configuration file according to the instructions
for step 5, below.
o Load the database by doing the following:
. netmush <mud-name>.conf &
. Log in to the mud as a wizard and shut it down.
- If you are loading a PernMUSH database from PernMUSH version 1.16
to 1.17.01, you must first upgrade to PernMUSH version 1.18 before
converting to TinyMUSH 2.0, and then follow the instructions for
upgrading from PernMUSH 1.18.
- If you are loading a PernMUSH database from PernMUSH version 1.17.02
to PernMUSH 1.18.02, do the following.
o Correct the MUSH version number on the database file by
performing these commands:
. echo '+V258' | cat - <database-name> > tempfile
. mv tempfile <mud-name>.db.
o Make your configuration file according to the instructions
for step 5, below.
o Load the database by doing the following:
. netmush <mud-name>.conf &
. Log in to the mud as a wizard and shut it down.
o Note: you will get a warning in the logfile when loading:
'Duplicate MUSH version header entry ...', but you may ignore it.
- If you are loading a PennMUSH database from PennMUSH version 1.18.03
or higher:
o Move the database to the file <mud-name>.db.
o Load the database by doing the following:
. netmush <mud-name>.conf &
. Log in to the mud as a wizard and shut it down.
- If you are loading a TinyMUSE, TinyMUD, or an older TinyMUSH database,
do the following:
o db_load <mud-name>.gdbm <database-name> <mud-name>.db.new
4c. 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
4d. 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
4e. If you are converting an existing TinyMUSH 2.0 database created by
patchlevel 7 from attribute cacheing to object cacheing (or vice versa),
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.
- Edit the Makefile to select the desired cacheing style.
- 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
- Reload the database with the command:
o db_load <mud-name>.gdbm <mud-name>.db.FULL <mud-name>.db.new
5. Edit the .txt files to your liking, in particular connect.txt and motd.txt.
This is not necessary if you are reinstalling TinyMUSH 2.0.
6. Start up TinyMUSH 2.0 by running Startmush.
Making a New Configuration File:
-------------------------------
TinyMUSH 2.0 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 netmush.conf to <your-mud-name>.conf
and edit it as follows:
- Replace netmush.<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 rwho_host <ip-addr> Host to transmit RWHO data to.
o rhwo_password <pass> Password for transmitting RWHO data.
o rwho_transmit yes Needed to turn on RWHO transmission
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. The file
INFO has a list of them broken down by topic, and more information
on individual flags 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 mush, 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: mushhacks@caisr2.caisr.cwru.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.
Environment:
-----------
TinyMUSH 2.0 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:
Sun-3 SunOS 4.1
Sun-386i SunOS 4.0.3
Sun-4/Sparc SunOS 4.1.3
Intel 386/486 Unix System V Release 4.0; Linux 0.99.5 and up
Prime EXL7360 RISC/os 4.52.p2
DEC 3100 Ultrix V4.2
VAX ???? VMS ???
If you get TinyMUSH 2.0 working on another platform, please let us know
about it!
Known Problems:
--------------
On some Unixes, the ndbm package does not work. If netmush or dbconvert hang
or abort when trying to open the database, most likely your ndbm is broken.
To correct this problem, edit the Makefile (AFTER running configure) and add
the file myndbm.o to the 'LIBOBJS =' line near the top. Also edit the file
'autoconf.h' and make sure both HAVE_DBM and HAVE_NDBM are #undef-ined.