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 potrzebie), 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.

