This is the README file for TinyMUSH 2.0.
Notice: The database format has changed between patchlevel 4 and patchlevel 5.
If you are running TinyMUSH 2.0 patchlevel 4 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.
*** When you unload the database to flat file format it is important to use
your original db_unload/dbconvert (most likely from patchlevel 4).
Patchlevel 4 and patchlevel 5 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
patchlevel 5 sources to unload anything but a patchlevel 5 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. Edit the Configuration section of the Makefile. Most likely, all you will
need to change is which C compiler to use and the location of the
MUSH game files.
2. Run make. This will produce netmush, mkindx, and dbconvert.
3a. If you are starting from scratch, do the following:
- Run make 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.
3b. 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 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
3c. 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 reinstall.
- 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
3d. If you are converting an existing TinyMUSH 2.0 database created by
patchlevels 1 through 4 (database version 4), 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 reinstall.
- 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
4. 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.
5. 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 mush.<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.
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: mushbugs@caisr2.caisr.cwru.edu
If the bug crashes the mush, try to include the following information
from running dbx 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
Intel 386/486 Unix System V Release 4.0
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.
Get a copy of the source (ndbm.c and ndbm.h) from an FTP site that has them
(consult archie), uncomment the lines that start with DBM_S and DBM_O in the
configuration section of the Makefile, and rebuild.
The GNU malloc package does not work properly on all platforms, notably
Sun-3's. If you encounter this problem, comment out the lines that start with
ALC_S and ALC_O in the configuration section of the Makefioe, and rebuild.