<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<title>Installing and Using CoffeeMud 5.9</title><link rel="StyleSheet" href="style.css" type="text/css" media="screen" /><!-- Modified by Josh Mueller, 2006-5-5, fix validation problems, add index, and fix spelling errors --></head>
<body>
<center>
<table border="1" bordercolor="gray" cellpadding="5" cellspacing="0" width="100%">
<tbody>
<tr>
<td colspan="2" align="left" bgcolor="#dfdfdf" width="100%">
<h1>Installing and Using CoffeeMud 5.9</h1>
</td>
</tr>
<tr>
<td align="left" valign="top" width="35%">
<ul>
<li><a href="#installation">Installation</a></li>
<li> <a href="#upgrading">Upgrading</a>
<ul>
<li><a href="#unchanged">Unchanged DB</a></li>
<li><a href="#changedfdb">Changed w/fakedb</a></li>
<li><a href="#changed">Changed w/o fakedb</a></li>
</ul>
</li>
<li><a href="#settings">Settings</a></li>
<li><a href="#multihosts">Multiple Hosts</a></li>
<li><a href="#package">The CoffeeMud Package</a></li>
<li> <a href="#database">The Database</a>
<ul>
<li><a href="#access">Microsoft Access</a></li>
<li><a href="#mysqlwin">MySQL/ Win</a></li>
<li><a href="#mysqllinux">MySQL/ Linux</a></li>
<li><a href="#hsql">HSQL</a></li>
<li><a href="#derby">Derby</a></li>
</ul>
</li>
<li><a href="#shutdown">Offline/ Shutdown</a></li>
</ul>
</td>
<td align="left" valign="top"> <img src="images/zip.jpg" alt="unzipping" />
<h2><a name="installation">Installation</a></h2>
<p>The first and most critical step in installing CoffeeMud 5.9
is to make sure that you have downloaded and installed the latest
version of the Sun Java SDK, though it only requires JDK 1.6 or
better. If
you are using some flavor of Unix or Linux instead of Windows, make
sure you aren't trying to get by with GCJ -- CoffeeMud (and Sun) do not
support it.</p>
<p>Now, if you are upgrading from a previous version of
CoffeeMud, you need to stop here and skip ahead to the section on
upgrading. If this is your first installation, keep reading.</p>
<p>You will now need to unpack the CoffeeMud.zip package into a
directory on your hard drive. This directory may be called, for
instance, "CoffeeMud".</p>
<p>If you are using a UNIX/Linux system, you should now bring up
a console and cd to whatever directory you unpacked CoffeeMud to. You
will first want to convert the dos-formatted install scripts to unix
format. To do this, enter <code>dos2unix InstallUNIX.sh</code> and <code>dos2unix
mudUNIX.sh</code>. Make sure you can write to mudUNIX.sh by issung the
the command <code>chmod 766 mudUNIX.sh</code> Now, enter <code>sh
InstallUNIX.sh</code> Follow the prompts by inputting the directory of
JAVA; do not enter a trailing slash, for instance: <code>/opt/jdk/jdk1.6.0_22</code>
Continue following the prompts: Say <code>y</code> if you want to
compile the main program, <code>n</code> if you don't. Enter the name
of your new MUD (this only works FIRST RUN; you cannot use this to
change MUD's name in the FUTURE). Say <code>y</code> if you want to
start your MUD now, and <code>n</code> if you don't. Hit enter after
the nohup comes up. </p>
<p>If you are using Windows, or you are using UNIX/Linux and have
completed the above instructions...</p>
<p class="bold">Congratulations!</p>
<p>You have successfully installed CoffeeMud.</p>
<p>You may wish, at this point, to investigate the settings and
components of the CoffeeMud server. If so, by all means, continue
reading this document. If you couldn't care less, then go into the your
CoffeeMud directory on a command line or DOS prompt and enter (for
Windows or DOS users):</p>
<p><code>java -classpath ".;.\lib\js.jar;.\lib\jzlib.jar"
-Xmx85m com.planet_ink.coffee_mud.application.MUD "Your Muds Name"</code></p>
<p>And for Unix, Linux, or FreeBSD users, the command differs
only in the classpath:</p>
<p><code>java -classpath ".:./lib/js.jar:./lib/jzlib.jar"
-Xmx85m com.planet_ink.coffee_mud.application.MUD "Your Muds Name"</code></p>
<p>This will start up the CoffeeMud server. Remember to change
the "Your Muds Name" text at the end to the unique name you want to
give your mud. If you are running Windows, you might also get away with
first modifying the file <code>mud.bat</code>
using your best text editor, and then executing that file. If you are
running some
flavor of FreeBSD, Unix, or Linux, you also have a mudLINUX.sh you may
first modify, then make executable using the command <code>chmod 755
mudLINUX.sh,</code> and then execute.</p>
<p>Now, connect to the server on port 5555 using your telnet or
other MUD client. Create yourself a new character. This new character
will be your administrative player, or Archon, so most of the player
settings, such as class, race, stats, etc. won't matter much (though I
would stay away from the Apprentice class). When your
character logs in for the first time, you will see a book in a room.
Your player should pick up the book and read it. The commands to do
this are:</p>
<pre>get book<br />read book<br /></pre>
<p>Doing this will turn your player into an Archon. An Archon is
an all-powerful administrative player who is capable of all manner of
magical conjurations. You will probably want to import a bunch of areas
into your database right away. If so, you should enter:</p>
<pre>ahelp import<br /></pre>
<p>This will tell you how to import *.CMARE files, which are
CoffeeMud formatted area files. Other formats are supported as
well.
Another way to quickly see some content in your mud is to enter
this long command:</p>
<p><span style="font-family: monospace;">generate area
random_dungeon areaname=MyRandomDungeon south</span></p>
<p>This will generate a
random 30-60 room dungeon based on one of the random themes in the
/resources/randreas/example.xml file to the south of
your current room.</p>
<p>If you'd like to actually learn how to use the CoffeeMud
engine, you should do the following:</p>
<ul>
<li>Finish reading this document</li>
<li>Go through the <a href="../coffeemud.ini">coffeemud.ini</a>
file, and use the <a href="MUDGrinder.html">MudGrinders</a> Control
Panel.</li>
<li style="list-style-type: none; list-style-image: none; list-style-position: outside;">
<ul>
<li>Set your DOMAIN field</li>
</ul>
<ul>
<li>Set your SMTPSERVERNAME field</li>
<li>Set your ADMINEMAIL and MUDSTATE fields</li>
<li>Set your START field</li>
<li>Set your SOUNDPATH field</li>
<li>Set your MXPIMAGEPATH field</li>
</ul>
</li>
<li>Read the <a href="ArchonGuide.html">Archon's Guide</a>.</li>
<li>Review the <a href="GameBuildersGuide.html">Game Builders
Guide</a>.</li>
<li>Check the <a href="BuildersFAQ.html">Builders FAQ</a>.</li>
<li>Peruse the <a href="Reference.html">Reference Guide</a></li>
<li>Remember the <a href="WebServer.html">Web Server Guide</a>.</li>
<li>Be aware of the <a href="SMTPServer.html">SMTP Server Guide</a>.</li>
<li>Rely on the <a href="Programming.html">Programmers Guide</a>.</li>
<li>Be amused with the <a href="RandomAreas.html">Random Areas
Guide</a>.</li>
</ul>
<p>Otherwise, once you have your administrator and a few areas,
you are technically ready to play!</p>
<img src="images/mug.jpg" alt="CoffeeMud logo" />
<h2><a name="upgrading">Upgrading From a Previous Version of
CoffeeMud</a></h2>
<p>There are three upgrade paths, one where the database schema
was not changed (4.5.0 to 4.5.1), and two others where the database
schema was changed (i.e. 4.7 to 5.0) . If you are unsure, or don't know
how to tell, go ahead and follow the changed database schema process.</p>
<h3><a name="unchanged">Unchanged Database Schema Process</a></h3>
<p>If you are upgrading to a version where the database schema
has (presumably) not changed, you still must expect that many other
things probably have. Therefore, follow these steps:</p>
<ul>
<li>
<p>First go into the directory that contains your olde
version of CoffeeMud and obliterate the entire "com" path. Just wipe it
away. You won't need it, and it will just cause problems anyway. If you
had any custom classes in there, you might want to pull them out first
and copy them elsewhere.</p>
</li>
<li>
<p>Next, save away (in another directory) your coffeemud.ini
file, and perhaps your mud.bat or mudLINUX.bat. Also save away any
files in the resources or web directory you might have customized to
your mud, including perhaps your resources/text/intro.txt file for
instance.</p>
</li>
<li>
<p>Now unpack/unzip the new version of CoffeeMud on TOP of
your olde one.</p>
</li>
<li>
<p>Open up the coffeemud.ini file that comes with the new
version and also open up your olde customized coffeemud.ini file you
saved away in step 2. Merge over from the old ini file the settings
that
differ from the new one. The idea here is that the new coffeemud.ini
file may contain new settings you need to be aware of. However, your
old custom settings will still apply in the new version -- especially
your database settings for instance.</p>
</li>
<li>
<p>Copy your intro.txt on top of the one from the new build.
As in step 4, merge any other files back into their counterparts in the
new build.</p>
</li>
<li>
<p>Smile, you are done.</p>
</li>
</ul>
<h3><a name="changedfdb">Changed FakeDB Database Schema Process</a></h3>
<p>If you are upgrading to a version with an updated database
schema, follow the correct instructions for your database type. If you
are using fakedb, follow the instructions below. If you don't know
whether or not you are using fakedb, then you ARE using fakedb and
should follow these instructions:</p>
<ul>
<li>
<p>Go into the CoffeeMud directory for your olde version and
copy the entire fakedb data directory to somewhere else on your hard
drive. On CoffeeMud versions 1.2 - 4.7, your fakedb data directory is
located in your coffeemud folder in the "data" directory. In versions
5.0 and higher, it is located in your coffeemud folder in the
"resources/fakedb" directory. You should see a file called
fakedb.schema, along with numerous fakedb.data.* files. Copy them all,
and remember where you put them!</p>
</li>
<li>
<p>Go back to the beginning of this section and follow steps
1 through 5 from the <em>unchanged database schema</em> process.</p>
</li>
<li>
<p>From the command line, go into your CoffeeMud directory,
and from there into fakedb data directory. Delete all the files
matching fakedb.data.*, praying you remembered where you saved this
stuff away just 2 steps ago. Do NOT delete the fakedb.schema
file! If everything
went well, the new fakedb.schema from the new version of CoffeeMud is
still in your fakedb data directory.</p>
</li>
<li>
<p>Still from the command line, go into your CoffeeMud
directory and enter the following: <code>java
com.planet_ink.fakedb.DBUpgrade</code></p>
</li>
<li>
<p>Follow the instructions for this little program.</p>
</li>
<li>
<p>Smile, you are done.</p>
</li>
</ul>
<h3><a name="changed">Changed Database Schema Process (not FakeDB)</a></h3>
<p>Now, if you are upgrading to a version with an updated
database schema and you are NOT using fakedb, but are using Access, SQL
Server, MySQL, or some other database, follow these instructions:</p>
<ul>
<li>
<p>Go into the CoffeeMud directory for your olde version and
copy the entire fakedb data directory to somewhere else on your hard
drive. On CoffeeMud versions 1.2 - 4.7, your fakedb data directory is
located in your coffeemud folder in the "data" directory. In versions
5.0 and higher, it is located in your coffeemud folder in the
"resources/fakedb" directory. You should see a file called
fakedb.schema, along with numerous fakedb.data.* files. Copy them all,
and remember where you put them! Even though you aren't using FakeBD,
you will still need to copy FakeDB's schema for use with the upgrade
application.</p>
</li>
<li>
<p>Go back to the beginning of this section and follow steps
1 through 5 from the <em>unchanged database schema</em> process.</p>
</li>
<li>
<p>Following the instructions provided by your database
system, create a brand NEW database for the new version of CoffeeMud.
You will need to use the appropriate database schema provided in the
new version of CoffeeMud to do this. If you have forgotten what this
means, consult the section of this document dealing with the CoffeeMud
Database. Make sure you preserve your olde CoffeeMud database from the
olde version!</p>
</li>
<li>
<p>From the command line, go into your CoffeeMud directory
and enter the following from the command line: <code>java</code><code>
-Xms16m -Xmx256m</code><code>
com.planet_ink.fakedb.DBUpgrade</code></p>
</li>
<ul>
<li>NOTE: You may need to add the classpath variable to your
database connector (if not FakeDB). Refer to the first-time
installation instructions for the CLASSPATH format. For example,
if you are using a MYSQL drive, the command might look like:</li>
<ul>
<li><code>java
-Xms16m -Xmx256m -cp
"/myjavastuff/drivers/mysql-connector-java-5.1.6-bin.jar"
com.planet_ink.fakedb.DBUpgrade</code></li>
</ul>
</ul>
<li>
<p>Follow the instructions for this little program.</p>
</li>
<li>
<p>Now open up your coffeemud.ini file and make any changes
necessary to point CoffeeMud to the database for the new version. This
may require creating a new ODBC data source, or just modifying the
DBSERVICE line, depending on your database type.</p>
</li>
<li>
<p>Smile, you are done.</p>
</li>
</ul>
<br />
<img src="images/settings.jpg" alt="settings" />
<h2><a name="settings">Settings</a></h2>
<p>All of the general purpose settings for the CoffeeMud server
are kept in the INI file, called "coffeemud.ini". This file may be
modified with your favorite text editor: textpad, vi, emacs, copycon,
Whatever! If you are adventurous, you may also specify a custom ini
file other than "coffeemud.ini" by putting a boot= myfile.ini entry in
your startup line just before the name of your mud. Why would you want
to? I don't know, but you can.</p>
<p>If you are happy with the standard installation, you will
usually also be content to leave most of the INI file alone. You will
eventually, however, probably find a need to at least modify the
"START" setting. Any changes to the coffeemud.ini file will require
that CoffeeMud be restarted before the changes will take effect.</p>
<p>Below are some of the more important configuration settings to
be aware of in your ini file. There are actually many many more, but
they just aren't discussed here. The best way to modify those "other"
settings is through the Control Panel in the <a href="MUDGrinder.html">MUDGrinder</a>
web site.</p>
<ul>
<li> <span class="bold">SYSMSGS, ERRMSGS, WRNMSGS, DBGMSGS,
ACCMSGS, HLPMSGS</span>
<p>These entries refer to logged system messages, logged
error messages, warning messages, debug messages, web server
access logs, and help requests. When logging is
directed to a file, that file is called "mud.log". The possible values
for each of these settings is either "ON", which will direct the
indicated messages to the screen only, "OFF" to disable the messages
entirely, "FILE" to direct the messages to the "mud.log" file only,
"OWNFILE" to direct the messages to a file of its very own, or
"BOTH" for both screen and normal file output. By default, SYSMSGS,
WRNMSGS,
and ERRMSGS
are set to "BOTH", while DBGMSGS and ACCMSGS are set to "OFF", and
HLPMSGS set to "OWNFILE".</p>
</li>
<li> <span class="bold">PORT</span>
<p>This is the TCP/IP port number which the main CoffeeMud
server will listen on. By default the setting is 5555. If you would
like to change this number to some other port, you may do so! You may
also add other numbers, separated by commas, to listen on multiple
ports!</p>
</li>
<li> <span class="bold">MUDSTATE</span>
<p>This is a short description of the state of your mud as
you want it published to the I3 or IMC2 network. A number from 0
(meaning Development) to 3 (Live and Ready) is expected.</p>
</li>
<li> <span class="bold">START</span>
<p>This setting designates the Room ID of the place on your
map where new players will start off at. It also dictates where players
are brought to when the Recall skill is used. By default, an arbitary
room ID has been assigned. Once you've put together a few areas, you
had better update this setting before new players start arriving.</p>
</li>
<li> <span class="bold">CHANNELS</span>
<p>This is a comma separated list of channels which the users
of your system may converse publicly on. The channel names
given here are completely arbitrary and may be meaningful or whimsical
terms, though the names may not contains spaces. There are lots
of options to peruse over here, and a couple of standard
channels are specified to get you started. The limit for the number of
standard channels
plus any InterMud channels (see <span class="bold">I3CHANNELS</span>
below) is 48 or so. That's more than plenty, right?</p>
</li>
<li> <span class="bold">BACKLOG</span>
<p>This TCP/IP setting denotes how many connections can be
queued up when the server is busy. Leave it at 6.</p>
</li>
<li> <span class="bold">BIND</span>
<p>This TCP/IP setting will limit the IP addresses which can
connect to your server. It is commented out by default, which means
that everyone is allowed to connect. Leave it that way, unless you want
your mud to be secret.</p>
</li>
<li> <span class="bold">RUNI3SERVER</span>
<p>This setting tells CoffeeMud whether to start up the
built-in InterMud3 server and make a connection to the InterMud router.
A value of "TRUE" will turn on the I3 server and make the connection.</p>
</li>
<li> <span class="bold">I3PORT</span>
<p>This is the TCP/IP port number which the main InterMud3
server will listen on. By default the setting is 27766. If you would
like to change this number to some other port, you may do so. If the <span class="bold">RUNI3SERVER</span> entry above is FALSE, this setting
will have no effect.</p>
</li>
<li> <span class="bold">I3CHANNELS</span>
<p>This is a comma separated list of InterMud3 channels which
the users of your system may converse publicly on. Each channel entry
is separated by a comma. Each entry consists of a locale channel name
(no spaces in the name), followed by a space, followed by a mask to
limit who can view or chat on the channel, followed lastly by the name
of the InterMud3 channel to map this local channel
to. A couple of standard channels are specified. The limit for the
number of standard channels (see <span class="bold">CHANNELS</span>
above) plus any InterMud channels is 48.</p>
</li>
<li> <span class="bold">RUNWEBSERVERS</span>
<p>This setting tells CoffeeMud whether to start up the
built-in web servers. A value of "pub,admin" will turn on both of the
main web servers.
Even if you don't wish to publish any of your MUDs information to the
web, you may want to run the Admin web server so that you can use the
MUDGrinder area editing tool. See the <a href="MUDGrinder.html">MUDGrinder
Guide</a> for more information on this tool. For more information on
the CoffeeMud web server in general, please read the <a href="WebServer.html">WebServer Guide</a>.</p>
</li>
<li> <span class="bold">RUNSMTPSERVER</span>
<p>This setting tells CoffeeMud whether to start up the
built-in SMTP (mail) server. A value of "TRUE" will turn on the SMTP
servers. Even if you don't wish to allow any incoming mail, you may
want to run the mail server so that you can create outgoing newsletters
for your players. For more information on the CoffeeMud SMTP server in
general, please read the <a href="SMTPServer.html">SMTPServer Guide</a>.</p>
</li>
<li> <span class="bold">ITEMS, MOBS, BEHAVIORS, ABILITIES,
CHARCLASSES, RACES, COMMANDS, LOCALES, AREAS, EXITS, etc </span>
<p>These settings each specify a path on your local drive
which will contain Java class files. These class files are typically
classes which you might want to use with your CoffeeMud system, but
which are not included with the standard CoffeeMud distribution. See
the <a href="Programming.html">Programmer's Guide</a> for more
information on writing custom classes for CoffeeMud.</p>
</li>
<li> <span class="bold">DBCLASS</span>
<p>This specifies the name of the Java class which will be
used as your JDBC or ODBC database driver. If you are using a System
ODBC data source, this entry will typically be
"sun.jdbc.odbc.JdbcOdbcDriver". By default, however, the CoffeeMud
"fakedb" package is installed. The driver name for this class is
"com.planet_ink.fakedb.Driver". See the next section on "The CoffeeMud
Database" for more information.</p>
</li>
<li> <span class="bold">DBSERVICE</span>
<p>This is the name of the JDBC or ODBC Service as defined by
your local operating system. It typically denotes the name of the ODBC
service, or the name of the database in other instances. For a System
ODBC service, this value will typically look like
"jdbc:odbc:SystemServiceName". By default, however, the fakedb package
is used. The format of the service name for fakedb is
"jdbc:fakedb:DataPath". Where DataPath is a local drive path containing
the "fakedb.schema" file, where your flat data files will be created.
See the section on "The CoffeeMud Database" for more information.</p>
</li>
<li> <span class="bold">DBUSER, DBPASS</span>
<p>This specifies the name and password which may or may not
be required to log into your ODBC service, or database. Not required
for fakedb, and thus blank by default.</p>
</li>
<li> <span class="bold">DBCONNECTIONS</span>
<p>This is the number of independent connections to make to
the database through your JDBC/ODBC driver. 1 or 2 is plenty. CoffeeMud
is not especially database intensive.</p>
</li>
<li> <span class="bold">DBREUSE, DBPINGINTERVALS</span>
<p>These are for tweeking how CoffeeMud uses database
connections. DBREUSE is true to permit the mud to re-use existing
connections over and over, instead of making new ones. When
DBREUSE is true, DBPINGINTERVALS will help you keep them alive during
dormancy by saying how frequently to ping those connections with a
trivial query.</p>
</li>
</ul>
<p>* In Addition to the above, you will find other numerous flags
and settings which allow you to better customize your CoffeeMud. Make
sure you check out the Control Panel feature in the MUDGrinder to
modify most of them.</p>
<p><img style="width: 73px; height: 73px;" src="images/sprockets.jpg" alt="packages" /> </p>
<h2><a name="multihosts">Multiple Hosts</a></h2>
<p>There may be circumstances under which you may want to run
your mud not only on multiple ports, but with multiple configurations,
or multiple maps, perhaps even multiple player bases. This is
accomplished by including the "BOOT=" command line parameter multiple
times. Each occurrence should be followed by the name of a valid
coffeemud ini file, as described in the previous section. The
server will then attempt to boot two muds in the same Java environment,
each relying to some extent on their own ini files for database and
other information.</p>
<p><code>java -classpath ".:./lib/js.jar:./lib/jzlib.jar
-Xmx256m com.planet_ink.coffee_mud.application.MUD
boot=coffeemud1.ini boot=coffeemud2.ini "Your Two-Headed Muds Common
Name"</code></p>
<p>The first BOOT parameter is considered by the CoffeeMud Engine
to be the Primary Host (HOST0), and any game resources that are shared
will be done with this host. Subsequent ini file
configurations will rely on the Primary Hosts ini file to fill in any
gaps in necessary configuration entries. Subsequent hosts will
also use their own ini files to select which resources to share with
the Primary Host, and which to manage independently, separately,
and privately from the Primary host. </p>
<p>Important INI file entries for Subsequent Host ini files:</p>
<p>PORT: required in all ini files. No host will boot
without at least one unique value here.<br />
DBCLASS: if a subsequent hosts ini file contains a DBCLASS entry, then
that host will manage its own private Database connections. <br />
NUMLOGS, SYSMSGS, ERRMSGS, etc: manage its own log file. <br />
SYSOPMASK, JSCRIPT, GROUP_*: manage its own security settings<br />
RUNWEBSERVERS: launch its own web servers<br />
RUNSMTPSERVER: launch its own smtp server (but why?!)<br />
RUNI3SERVER, other I3 settings: always ignored. Only the Primary Host
may launch I3 servers and clients.<br />
RUMIMC2CLIENT, other IMC2 settings: always ignored. Only the
Primary Host may launch IMC2 clients.<br />
PRIVATERESOURCES: defines resources not shared with the Primary Host.
See below.<br />
</p>
<p>All other ini file entries will either be specified in
the Subsequent Hosts ini
file and therefore unique, or they will not be specified, and therefore
have their values copied from the Primary Host ini file. </p>
<p>The PRIVATERESOURCES entry defines which of the CoffeeMud
engines primary resources will be private to the Subsequent Host,
meaning not shared with the Primary Host. This ini file entry is
a comma-delimited list of resources to maintain privately in the
Subsequent Host, and is defined only in each Subsequent Hosts ini file.
Each resource manages a different sphere of MUD
activity, so it is wise to consider carefully the interactions of
shared and unshared resources. For instance, the CHANNELS
resource manages list of channel names and their functions, while
SESSIONS manages the list of online players and who may speak to each
other over channels, JOURNALS the list of command journals, STATS the
player statistics, MAP the world map, LOGINS the list of start rooms,
QUEST the list of quests, FACTIONS your factions list, CLANS the player
clans, POLLS the online polls, CATALOG your item drop tables and object
catalogs, PLAYERS the player cache and tables, TITLES your automatic
vanity titles, TIME the global calendar/clock, DBVFS the
database-portion of your file system (very
important if you want different intro.txt or other files for different
hosts), and the various object types if you want to prevent your
builders to have different available objects on different hosts.</p>
<p>It is recommended that your subsequent ini files include, at
least the PORT, one new administrative RUNWEBSERVERS entry, a DBCLASS
entry pointing to a dedicated CoffeeMud database for each host, and
several PRIVATERESOURCES.. probably DBVFS, PLAYERS, MAP, STATS,
QUEST, and CLANS. If you dont want your players to be able
to chat with each other over channels, or see each other with the WHO
command, you might add CHANNELS and SESSIONS to the list as well.</p>
<img src="images/hd.jpg" alt="packages" />
<h2><a name="package">The CoffeeMud Package</a></h2>
<p>Here is a summary of the directories inside the CoffeeMud
package, along with some of the important files you may want to edit
when configuring your server.</p>
<img src="images/dir-com.jpg" alt="com" />
<p>The directories inside the <code>com</code> directory contain
all the Java Class files, which are the executable portion of
CoffeeMud. All of the Java source files are also found herein.</p>
<img src="images/dir-guides.jpg" alt="guides" />
<p>The <code>guides</code> directory is where you'll find this
document, as well as other HTML documents you may find helpful in
configuring your server as well as building areas inside it.</p>
<p>The <code>guides/database</code> directory is where you'll
find several SQL scripts necessary to configuring another database
engine, such as SQL Server, MySQL, PostgreSQL, Access, and others.</p>
<p>The <code>guides/images</code> directory contains image files
used inside the HTML files in the guides directory.</p>
<img src="images/dir-lib.jpg" alt="lib" />
<p>The <code>lib</code> directory holds any external libraries
or
components necessary to run CoffeeMud, but not necessarily part of the
CoffeeMud source proper. For instance, this directory holds the Mozilla
Rhino Javascript library jar file, called js.jar, as well as the zlib
library file, called jzlib.jar.</p>
<img src="images/dir-web.jpg" alt="web" />
<p>The <code>web</code> directory is where you'll find several
important files related to the configuration of the two default web
servers: admin, and public (pub): You may want to edit them at some
point, or not. It's up to you. You'll probably be happier if you at
least look them over so you know what settings you CAN edit.</p>
<table border="1" width="100%">
<tbody>
<tr>
<td>admin.ini</td>
<td>The configuration file for the admin web server. This
is the server which, by default, governs the MUDGrinder and other
server administrative pages and utilities.</td>
</tr>
<tr>
<td>common.ini</td>
<td>The configuration file for certain settings common to
both the admin and public web servers.</td>
</tr>
<tr>
<td>pub.ini</td>
<td>The configuration file for the public web server.</td>
</tr>
<tr>
<td>email.ini</td>
<td>The configuration file for the smtp server.</td>
</tr>
</tbody>
</table>
<p>The <code>admin</code> directory is where the pages made
available by the admin web server are found, by default. This directory
also contains the <code>admin/images</code> to store image files
displayed by the admin pages, as well as the <code>admin/grinder</code>
directory, where the MUDGrinder pages are stored by default.</p>
<p>The <code>admin.templates</code> directory is where the
default error page for the admin web server is found.</p>
<p>The <span style="font-family: monospace;">clan</span><code>.templates</code>
directory is where the
default clan/guild web site is found.</p>
<p>The <code>pub</code> directory is where the pages made
available by the pub web server are found, by default. This directory
also contains the <code>pub/images</code> to store image files
displayed by the public web pages, as well as the <code>pub/sounds</code>
directory where MSP sound files are stored for players to access.</p>
<p>The directory <span style="font-family: monospace;">pub/images/mxp</span>
contains all of the MXP displayable images, including the file <span style="font-family: monospace;">pub/images/mxp/intro.jpg</span>,
which is the image displayed when players who have MXP compliant mud
clients log into your mud. To use multiple/random intros, just insert
numbers before the extension for additional ones (intro1.jpg,
intro234.jpg)</p>
<p>The <code>pub.templates</code> directory is where the default
error page for the pub web server is found.</p>
<img src="images/dir-resources.jpg" alt="resources" />
<p>The <code>resources</code> directory is where you'll find
most
of the important files for tinkering with the configuration of several
aspects of your system. Some of these files are in the resources
directory itself, and some are in its subdirectories. The important
files found in the resources directory are:</p>
<table border="1" width="100%">
<tbody>
<tr>
<td>achievements.ini</td>
<td>The configuration file for the Achievements system. Edit away!</td>
</tr>
<tr>
<td>chat.dat</td>
<td>The configuration file for the MudChat behavior. You
can edit this one too.</td>
</tr>
<tr>
<td>clangovernments.xml</td>
<td>The configuration file for the Clan Types.</td>
</tr>
<tr>
<td>ipblock.ini</td>
<td>A list of all ip addresses or ip ranges to block!</td>
</tr>
<tr>
<td>laws.ini</td>
<td>The default configuration file for the Arrest behavior.
You can edit this, but its easier to deal with law through law books.</td>
</tr>
<tr>
<td>lawtoc.ini</td>
<td>The default pages file for the GenLawBook item.</td>
</tr>
<tr>
<td>movingroom.xml</td>
<td>A sample configuration file for the MovingRoom behavior.</td>
</tr>
<tr>
<td>parser_en_TX.properties</td>
<td>The definitions file for CoffeeMud's user-input
translation engine.</td>
</tr>
<tr>
<td>translation_en_TX.properties</td>
<td>The definitions file for CoffeeMud's user-putput
translation engine.</td>
</tr>
<tr>
<td>socials.txt</td>
<td>The text file holding all of the socials. There is a
command line tool for updating this file.</td>
</tr>
<tr>
<td>mxp_images.ini</td>
<td>A definition table for the default image files used for
mxp clients.</td>
</tr>
<tr>
<td valign="top">titles.ini<br />
</td>
<td valign="top">A definition file for automatic player
titles. Can be modified directly, or with the CREATE/LIST/DESTROY TITLE
commands.<br />
</td>
</tr>
<tr>
<td>lists.ini</td>
<td>A properties file containing several miscellaneous
charts and tables for user modification.</td>
</tr>
</tbody>
</table>
<p>The <code>resources/catalog</code> directory is not locally
accessible, and exists only in the coffeemud database file system
(VFS). It is completely system generated, and contains xml
(*.cmare)
versions of all the mobs and items you use in your Catalog system.
See
the Archon's or Game Builder's guide for more information.</p>
<p>The <code>resources/fakedb</code> directory is where all
area, room, mob, journal, and player data is stored when the FAKEDB
system is being used. When FAKEDB is not being used, this directory is
unused.</p>
<p>The <code>resources/examples</code> directory is where you'll
find sample files for a variety of things.<br />
</p>
<table border="1" width="100%">
<tbody>
<tr>
<td>areareaction.ini</td>
<td>A template for use by the Faction system for automatic
mob reactions based on area. See AUTOREACTION in your
coffeemud.ini file for more information on this system.</td>
</tr>
<tr>
<td valign="top">deities.cmare<br />
</td>
<td valign="top">A cmare file with some example deities to
load into your mud. Use the IMPORT command to load this set of mobs.<br />
</td>
</tr>
<tr>
<td valign="top">factiontemplate.ini<br />
</td>
<td valign="top">A template file for use by the creation
wizard when new factions are created. Do not modify this file!!<br />
</td>
</tr>
<tr>
<td>FindRawMaterial.js</td>
<td>A sample Command class written in javascript as an
example of how to write coffeemud commands in javascript. Use
LOAD COMMAND resources/examples/FindRawMaterial.js to install it, and
then
enter FINDRAWMATERIAL IRON at the command line to run it.</td>
</tr>
<tr>
<td valign="top">reputation.ini<br />
</td>
<td valign="top">Sample faction ini file, which you may add
to the value of the FACTIONS tag in your coffeemud.ini file to make use
of.<br />
</td>
</tr>
<tr>
<td valign="top">Lemmings.js<br />
</td>
<td valign="top">A sample MOB class written in
javascript
as an example on how to write coffeemud code. Use LOAD MOB
resources/examples/Lemming.js to load it up, and see the Programmer's
Guide for more information<br />
</td>
</tr>
<tr>
<td>namereaction.ini</td>
<td>A template for use by the Faction system for automatic
mob reactions
based on mob name. See AUTOREACTION in your coffeemud.ini file
for more
information on this system.</td>
</tr>
<tr>
<td>QuickWho</td>
<td>Another sample Command class written in javascript as
an
example of how to write coffeemud commands in javascript. Use
LOAD COMMAND resources/examples/QuickWho.js to install it, and then
enter QUICKWHO at the command line to run it.</td>
</tr>
<tr>
<td>racereaction.ini</td>
<td>A template for use by the Faction system for automatic
mob reactions
based on mob race. See AUTOREACTION in your coffeemud.ini file
for more
information on this system.</td>
</tr>
</tbody>
</table>
<p>The <code>resources/factions</code> directory is where you
should put all of your faction definition files. The
standard faction shipped with the mud, called Alignment, is found in
there.</p>
<p>The <code>resources/help</code> directory is where you'll
find
all of the files responsible for the numerous standard and archon HELP
entries. It also contains the two text files shown when help and ahelp
are entered without parameters. The *.ini files are formatted as java
property files, meaning that they are in ENTRY=VALUE format. The VALUE
may span several lines, so long as it ends with a backslash \. Files
that contain help entries for the ARCHELP (archon help) command all
start with arc_*, while those that do not are for the HELP (player
help) command.</p>
<p>The <code>resources/progs</code> directory contains several
sample program files:<br />
</p>
<table border="1" width="100%">
<tbody>
<tr>
<td>autoplayer</td>
<td>Don't look in here -- it's barely even started.
Just junk right now.</td>
</tr>
<tr>
<td valign="top">blackjack.script<br />
</td>
<td valign="top">Sample blackjack dealer
MOBPROG. By adding LOAD=progs/blackjack.script to the parameters of a
Scriptable behavior which has been added to a genmob, you can make that
mob a blackjack dealer. See help on Scriptable for more information.<br />
</td>
</tr>
<tr>
<td>chardesc.script</td>
<td>A sample script to use with your coffeemud.ini files'
CHARCREATIONSCRIPTS entry.</td>
</tr>
<tr>
<td valign="top">clearChannelQue.js<br />
</td>
<td valign="top">Sample javascript archon command that
clears the backlog on a given chatter-channel. To use the command,
enter JRUN resources/progs/clearChannelQue.js <channel_name><br />
</td>
</tr>
<tr>
<td valign="top">coffeeanthem.script<br />
</td>
<td valign="top">Sample MOBPROG script to make a mob sing
the CoffeeMud anthem every day. Added to mobs the same way
blackjack.script is added above.<br />
</td>
</tr>
<tr>
<td valign="top">craps.script<br />
</td>
<td valign="top">Sample MOBPROG script to make a mob a
craps dealer. Added to mobs the same way blackjack.script is added
above.<br />
</td>
</tr>
<tr>
<td valign="top">everyoneIsHome.js<br />
</td>
<td valign="top">Sample javascript archon command that
tests to see if any mobs are outside their home areas. To execute,
enter JRUN resources/progs/everyoneIsHome.js<br />
</td>
</tr>
<tr>
<td valign="top">heresy.script<br />
</td>
<td valign="top">Sample MOBPROG script to make
a mob accuse anyone who enters their room of heresy. Added to mobs the
same way blackjack.script is added above. Requires that the area the
mob is home to has the Arrest behavior (to implement law in that area).<br />
</td>
</tr>
<tr>
<td valign="top">knucklebones.script<br />
</td>
<td valign="top">Sample MOBPROG script to make a mob a
knucklebones dealer. Added to mobs the same way blackjack.script is
added above.<br />
</td>
</tr>
<tr>
<td valign="top">maxItemsRoom.js<br />
</td>
<td valign="top">Sample javascript archon command to tell
you which rooms have the most items in them. To execute, enter JRUN
resources/progs/maxItemsRoom.js<br />
</td>
</tr>
<tr>
<td valign="top">mrinfo.script<br />
</td>
<td valign="top">Sample MOBPROG script to demonstrate
various triggers. Added to mobs the same way blackjack.script is added
above.<br />
</td>
</tr>
<tr>
<td>scriptableTest.script</td>
<td>A MOBPROG to test various triggers in Scriptable.</td>
</tr>
<tr>
<td valign="top">strangetrader.script<br />
</td>
<td valign="top">Sample MOBPROG script to demonstrate
various triggers. Added to mobs the same way blackjack.script is added
above.<br />
</td>
</tr>
</tbody>
</table>
<p>The <code>resources/quests</code> directory contains several
sample quests. Each quest is in its own directory, along with any
supporting Scriptable *.script files, and any supporting mob or item
*.cmare files. The CREATE QUEST command is used to load each of these
*.quest files. Quests may also be loaded via the MUDGrinder.</p>
<p>The <code>resources/randareas</code> directory contains
sample
random area data templates, which all end with the *.xml extension. The
sample file "example.xml" is in this directory, which contains
instructions for making new template files by hand. Random area
templates
can also be modified via the MUDGrinder.</p>
<table border="1" width="100%">
<tbody>
<tr>
<td>example.xml</td>
<td>A default area generation file for the GENERATE command.</td>
</tr>
</tbody>
</table>
<p>The <code>resources/skills</code> directory contains the
database of recipes used by the Common skills in CoffeeMud. Each text
file contains recipe for a single skill, and each is formatted in
tab-delimited format, with rows separated by carriage returns. This
directory includes:<br />
</p>
<table border="1" width="100%">
<tbody>
<tr>
<td valign="top">alchemy.txt</td>
<td valign="top">Recipes for the Alchemy skill<br />
</td>
</tr>
<tr>
<td>allqualifylist.txt</td>
<td>List of skills that span across all classes.</td>
</tr>
<tr>
<td valign="top">armorsmith.txt</td>
<td valign="top">Recipes for the Armorsmithing skill<br />
</td>
</tr>
<tr>
<td valign="top">bake.txt</td>
<td valign="top">Recipes for the Baking skill<br />
</td>
</tr>
<tr>
<td valign="top">blacksmith.txt</td>
<td valign="top">Recipes for the Baking skill<br />
</td>
</tr>
<tr>
<td valign="top">cagebuilding.txt</td>
<td valign="top">Recipes for the Blacksmithing skill<br />
</td>
</tr>
<tr>
<td valign="top">carpentry.txt</td>
<td valign="top">Recipes for the Carpentry skill<br />
</td>
</tr>
<tr>
<td valign="top">clancraft.txt</td>
<td valign="top">Recipes for the Clan Crafting skill<br />
</td>
</tr>
<tr>
<td valign="top">cobbler.txt</td>
<td valign="top">Recipes for the Cobbler skill<br />
</td>
</tr>
<tr>
<td valign="top">components.txt</td>
<td valign="top">Definitions file for spell/skill
components. Can modify this file, or use CREATE/LIST/DESRTROY
COMPONENTS commands<br />
</td>
</tr>
<tr>
<td valign="top">costume.txt</td>
<td valign="top">Recipes for the Costuming skill<br />
</td>
</tr>
<tr>
<td valign="top">expertises.txt</td>
<td valign="top">Definitions file for spell/skill
expertises. Can modify this file, or use CREATE/LIST/DESTROY EXPERTISES
commands<br />
</td>
</tr>
<tr>
<td valign="top">fletching.txt</td>
<td valign="top">Recipes for the Fletching skill<br />
</td>
</tr>
<tr>
<td valign="top">foodprep.txt</td>
<td valign="top">Recipes for the FoodPrep skill<br />
</td>
</tr>
<tr>
<td valign="top">glassblowing.txt</td>
<td valign="top">Recipes for the Glass Blowing skill<br />
</td>
</tr>
<tr>
<td valign="top">herbalism.txt</td>
<td valign="top">Recipes for the Herbalism skill<br />
</td>
</tr>
<tr>
<td valign="top">herbology.txt</td>
<td valign="top">Recipes for the Herbology skill<br />
</td>
</tr>
<tr>
<td valign="top">instruments.txt</td>
<td valign="top">Recipes for the Instruments skill<br />
</td>
</tr>
<tr>
<td valign="top">insultd.txt</td>
<td valign="top">Insults text source file for the Joke skill<br />
</td>
</tr>
<tr>
<td valign="top">insulto.txt</td>
<td valign="top">Other insults text source file for the
Joke skill<br />
</td>
</tr>
<tr>
<td valign="top">jewelmaking.txt</td>
<td valign="top">Recipes for the Jewelmaking skill<br />
</td>
</tr>
<tr>
<td valign="top">leatherworking.txt</td>
<td valign="top">Recipes for the Leatherworking skill<br />
</td>
</tr>
<tr>
<td valign="top">liquors.txt</td>
<td valign="top">Recipes for the Distilling skill<br />
</td>
</tr>
<tr>
<td valign="top">masterarmorsmith.txt</td>
<td valign="top">Recipes for the Master Armorsmithing skill<br />
</td>
</tr>
<tr>
<td valign="top">mastercostume.txt</td>
<td valign="top">Recipes for the Master Costuming skill<br />
</td>
</tr>
<tr>
<td valign="top">masterleatherworking.txt</td>
<td valign="top">Recipes for the Master Leatherworking skill<br />
</td>
</tr>
<tr>
<td valign="top">mastertailor.txt</td>
<td valign="top">Recipes for the Master Tailoring skill<br />
</td>
</tr>
<tr>
<td valign="top">masterweaponsmith.txt</td>
<td valign="top">Recipes for the Master Weaponsmithing skill<br />
</td>
</tr>
<tr>
<td valign="top">papermaking.txt</td>
<td valign="top">Recipes for the Papermaking skill<br />
</td>
</tr>
<tr>
<td valign="top">poisons.txt</td>
<td valign="top">Recipes for the Poisons skill<br />
</td>
</tr>
<tr>
<td valign="top">pottery.txt</td>
<td valign="top">Recipes for the Pottery skill<br />
</td>
</tr>
<tr>
<td valign="top">recipes.txt</td>
<td valign="top">Recipes for the Cooking skill<br />
</td>
</tr>
<tr>
<td valign="top">scrimshaw.txt</td>
<td valign="top">Recipes for the Scrimshawing skill<br />
</td>
</tr>
<tr>
<td valign="top">scribing.txt</td>
<td valign="top">Recipes for the Scroll Scribing<br />
</td>
</tr>
<tr>
<td valign="top">sculpting.txt</td>
<td valign="top">Recipes for the Sculpting skill<br />
</td>
</tr>
<tr>
<td valign="top">shipwright.txt</td>
<td valign="top">Recipes for the ShipWrighting skill<br />
</td>
</tr>
<tr>
<td valign="top">smelting.txt</td>
<td valign="top">Recipes for the Smelting skill<br />
</td>
</tr>
<tr>
<td valign="top">tailor.txt</td>
<td valign="top">Recipes for the Tailoring skill<br />
</td>
</tr>
<tr>
<td valign="top">taxidermy.txt</td>
<td valign="top">Recipes/Descriptiong for the Taxidermy
skill<br />
</td>
</tr>
<tr>
<td valign="top">torturesmith.txt</td>
<td valign="top">Recipes for the Torturesmithing skill<br />
</td>
</tr>
<tr>
<td valign="top">wainwright.txt</td>
<td valign="top">Recipes for the Wainwrighting skill<br />
</td>
</tr>
<tr>
<td valign="top">weaponsmith.txt</td>
<td valign="top">Recipes for the Weaponsmithing skill<br />
</td>
</tr>
<tr>
<td valign="top">weaving.txt</td>
<td valign="top">Recipes for the Weaving skill<br />
</td>
</tr>
</tbody>
</table>
<p>The <code>resources/text</code> directory contains several
text files displayed at different points in the CoffeeMud engine. Feel
free to load these into a text editor and have at them. A summary is as
follows:</p>
<table border="1" width="100%">
<tbody>
<tr>
<td>alignment.txt</td>
<td>A text file describing alignment to new players.</td>
</tr>
<tr>
<td valign="top">blocked.txt<br />
</td>
<td valign="top">A file shown to someone permanently blocked.<br />
</td>
</tr>
<tr>
<td>classes.txt</td>
<td>A text file describing class selections for new players.</td>
</tr>
<tr>
<td valign="top">connblocked.txt<br />
</td>
<td valign="top">A file shown to someone temporarily blocked.<br />
</td>
</tr>
<tr>
<td>credits.txt</td>
<td>The text file shown to users who use the CREDITS
command.</td>
</tr>
<tr>
<td>down.txt</td>
<td>The text file displayed to users only when the OffLine
application is running.</td>
</tr>
<tr>
<td valign="top">doneacct.txt<br />
</td>
<td valign="top">A file shown after account creation, but
before character creation.<br />
</td>
</tr>
<tr>
<td>email.txt</td>
<td>The text shown to players during character creation
regarding the email address prompt.</td>
</tr>
<tr>
<td>intro.txt</td>
<td>The text file displayed to users when they connect to
your mud. To use multiple/random intros, just insert numbers before the
extension for additional ones (intro1.txt, intro234.txt)</td>
</tr>
<tr>
<td>mxp.txt</td>
<td>A text file containing the complete MXP dictionary. See
<a href="http://www.zuggsoft.com/zmud/mxp.htm">http://www.zuggsoft.com/zmud/mxp.htm</a>
for more information on this feature.</td>
</tr>
<tr>
<td valign="top">newacct.txt<br />
</td>
<td valign="top">A text file introducing new accounts.<br />
</td>
</tr>
<tr>
<td valign="top">newchar.txt<br />
</td>
<td valign="top">A text file introducing your mud to new
players.<br />
</td>
</tr>
<tr>
<td>newchardone.txt</td>
<td>A text file shown to players after they have created
their character.</td>
</tr>
<tr>
<td valign="top">nologins.txt<br />
</td>
<td valign="top">A text file shown to non-archons who try
to login when the LOGINS flag is disabled in the coffeemud.ini file.<br />
</td>
</tr>
<tr>
<td>offline.txt</td>
<td>A text file shown to players while your mud is booting.</td>
</tr>
<tr>
<td>races.txt</td>
<td>A text file describing race selections to new players.</td>
</tr>
<tr>
<td valign="top">rules.txt<br />
</td>
<td valign="top">A text file shown when players enter the
RULES command.<br />
</td>
</tr>
<tr>
<td valign="top">selchar.txt<br />
</td>
<td valign="top">A text file shown on account char
selection.<br />
</td>
</tr>
<tr>
<td>stats.txt</td>
<td>A text file describing the basic stats to new players</td>
</tr>
<tr>
<td valign="top">themes.txt<br />
</td>
<td valign="top">A text file shown to users when the
coffeemud.ini file is configured for multiple themes. Not presently
supported very well, however.<br />
</td>
</tr>
</tbody>
</table>
<br />
<br />
<img src="images/db.jpg" alt="database" />
<h2><a name="database">The CoffeeMud Database</a></h2>
<p>CoffeeMud requires a database for operation. A database is
simply the place where all the rooms, items, monsters, players, pets,
and other information is stored on the computer. Without the database,
you would have to start all over from scratch every time you booted the
MUD Server. And we all know that would be bad.</p>
<p>By default, CoffeeMud uses a custom JDBC flat-file database
called "fakedb". FakeDB stores its data into text formatted files
inside the "resources/fakedb" directory of your CoffeeMud package.
FakeDB is rather slow, and hardly a powerful or professional database
system, but it is quite sufficient for CoffeeMud tinkerers, and
performs well the
small tasks it was designed for.</p>
<p>For the more serious, CoffeeMud supports any JDBC or ODBC
compliant database system. This includes such systems as Microsoft
Access, Microsoft SQL Server, PostgreSQL, MySQL, Oracle, IBM DB2, and
others. While this document cannot cover the step by step installation
instructions for each of these systems, it can be pointed out that
everything you need has been provided. Inside the "guides/database/"
directory of your CoffeeMud package, you will find several files:
"coffeemuddb.sql", "coffeemuddbmssql.sql", "coffeemuddbaccess.sql",
"coffeemudibmdb2.sql", "coffeemuddbmysql.sql", "coffeemuddbpsql.sql",
"coffeemuddbhsql.sql", "coffeemuddderby.sql", and "fakedb.schema". The
first five are SQL Scripts which can be used to create the necessary
tables in Microsoft SQL Server ("coffeemuddbmssql.sql"), MySQL
("coffeemuddbmysql.sql"), Access ("coffeemuddbaccess.sql"), PostgreSQL
("coffeemuddbpsql.sql"), Derby ("coffeemuddbderby.sql"), HSQLDB
("coffeemuddbhsql.sql"), IBM DB2 ("coffeemudibmdb2.sql")and some of the
others. The last is a copy of the same fakedb file from your
"resources/fakedb" directory, in case it becomes corrupted. Although
the manner in which the SQL Scripts are used may differ from system to
system, they cannot all be covered here. Some of the scripts may need
to be changed slightly to work with some systems. Some systems will
require each SQL Statement be issued independently instead of as part
of a larger script. Please consult your database documentation for more
information on this.</p>
<p>In order to use your database with CoffeeMud, as specified in
the section on Settings, you must provide CoffeeMud with a JDBC
compliant Driver class. In a few cases, you may be creating a System
ODBC Data Source. When this is the case, the driver "<code>sun.jdbc.odbc.JdbcOdbcDriver</code>"
may be used to access the database.</p>
<p>Most systems, however, such as MySQL, IBM DB2, and Microsoft
SQL Server 2000, have native JDBC Drivers which may be used instead of
the general ODBC Driver. These native JDBC Drivers tend to be far
superior to their ODBC counterparts, and are highly recommended.</p>
<p>The care and feeding of the tables used by CoffeeMud should be
very low. The database will grow along with the areas created, and
along with the number of players which join your MUD. All of this
growth can be managed, however, within CoffeeMud itself, by your Archon
administrative user. You should not need to, nor should you attempt to
affect individual rows in your database for any reason.</p>
<h3><a name="access">Installing and using Microsoft Access with
CoffeeMud on a Windows machine</a></h3>
<ul>
<li>
<p>Open up Microsoft Access and select to create a Blank
Access Database. Give the database a name and save it on your hard
drive.</p>
</li>
<li>
<p>Under Objects, select the Queries section and select
Create Query in Design View. When the dialog box appears, click the
close button.</p>
</li>
<li>
<p>Now right click on the large grey area and select "SQL
View" from the context Menu.</p>
</li>
<li>
<p>Inside your CoffeeMud/guides/database folder, open up the
coffeemuddbaccess.sql file using a text editor. You will see that the
file
contains numerous blocks of sql text. Each block begins with CREATE
TABLE, and ends with a semicolon );</p>
</li>
<li>
<p>Select the first block of text in your sql file, from the
first CREATE TABLE line down through the ); line, and select Copy from
the text editor. Paste this block into the Select Query area in
Microsoft
Access. Paste it over any other text that may be in there.</p>
</li>
<li>
<p>Press the "!" symbol at the top to execute the block of
sql script.</p>
</li>
<li>
<p>Repeat steps 5 and 6 for the remaining CREATE TABLE blocks
in the coffeemuddbmssql.sql file.</p>
</li>
<li>
<p>Now go to your Windows Control Panel (under XP, switch to
Classic View) and double-click the <code>ODBC Data Sources (32-bit)</code>
icon. If you are using Windows 2000 or XP, double-click the <code>Administrative
Tools</code> option. Then select the <code>="">Data Sources (ODBC)</code>
icon.</p>
</li>
<li>
<p>Now, click on the <code>System DSN</code> tab. Click the <code>Add</code>
button. This will present you with a list of drivers. Select " <code>Microsoft
Access Driver (*.mdb)</code>"</p>
</li>
<li>
<p>Here you should probably name the data source something
sensical, like <code>CoffeeMudData</code> or the like. Under <code>Database</code>,
click <code>Select</code>. Locate and select your <code>CoffeeMud.mdb</code>
file that you saved in step 1. Click OK and then OK to get all the way
back out of things.</p>
</li>
<li>
<p>Open coffeemud.ini. Go to where it says "ODBC Database
fields". That section should instead look like this:</p>
<pre>#------------------------<br />
# ODBC Database fields<br />
#------------------------<br />
# DBCLASS is the name of the ODBC Driver, typically sun.jdbc.odbc.JdbcOdbcDriver<br />
# DBSERVICE is the name of the ODBC Service as defined by your local operating system<br />
# DBUSER is a user name required to log into the ODBC service<br />
# DBPASS is the password for the above user name<br />
# DBCONNECTIONS is the number of independent connections to make to the database<br />
DBCLASS=sun.jdbc.odbc.JdbcOdbcDriver<br />
DBSERVICE=jdbc:odbc:CoffeeMudData<br />
DBUSER=<br />
DBPASS=<br />
DBCONNECTIONS=1<br />
</pre>
<p>Where it says "<code>jdbc:odbc:CoffeeMudData</code>", make
sure the part after "<code>jdbc:odbc:</code>"
matches the DNS name you made earlier. Make sure your DBCONNECTIONS is
never set above 1 when using Microsoft Access. Now, reboot CoffeeMud,
and you are done!</p>
</li>
</ul>
<h3><a name="mysqlwin">Installing and using MySQL with CoffeeMud
on a Windows machine</a></h3>
<ul>
<li>
<p>Go to <a href="http://www.mysql.com">www.mysql.com</a>,
click on Downloads (one of the tabs at the very top). Download the
latest generally available production version.</p>
</li>
<li>
<p>Go back to the Downloads tab, this time scroll down to
MYSQL Connectors. Download the latest Connector/J, or whatever they are
calling their JDBC Driver at the time.</p>
</li>
<li>
<p>Install MySQL -- consult the web site if you are having
problems.</p>
</li>
<li>
<p>Go to your coffeemud folder, open the <code>guides\database
folder</code>,
and you will see a file called "coffeemuddbmysql.sql". Open that file
with a text editor or textpad etc... (you might want to make a backup
copy first...) Now, add the following:</p>
<pre># Connection: SQL<br /># Host: localhost<br /># Saved: 2003-04-01 00:29:14<br />#<br /># Connection: SQL<br /># Host: localhost<br /># Saved: 2003-04-01 00:27:39<br />#<br />use coffeemud <----ADD THIS LINE!<br />CREATE TABLE CMCHAB (<br />CMUSERID char (50) NULL ,<br />CMABID char (50) NULL ,<br />CMABPF int NULL ,<br />CMABTX text NULL<br />etc..<br />etc..<br /></pre>
<p>Now copy the edited coffeemuddbmysql.sql to your <code>c:\program
files\mysql\bin</code>
folder (or wherever you installed mysql).</p>
</li>
<li>
<p>Now, open a DOS window (Start > Run > type "cmd"
and hit enter) and type cd c:\program files\mysql<tab>\bin and
hit Enter. Type
"mysql" and enter. You should get a Welcome to the MySQL monitor etc.
etc. etc.. and now the prompt should simply say "mysql>" . Now type
"create database coffeemud;" (please note the semi-colon";"!!!) and hit
enter. You should get "Query OK, 1 row affected <0.11sec)" or
something like that... then type "use coffeemud" and hit enter. Next
enter "source coffeemuddbmysql.sql" and hit enter. After a moment or
two, it will be done. Lastly, enter "\q", that should quit you out of
the monitor.</p>
</li>
<li>
<p>If all went well, you should now have mysql running and
a coffeemud database all set for it to access.</p>
</li>
<li>
<p>Now go to your coffeemud folder and open your
coffeemud.ini file in a text editor, and look for the
section that says:</p>
<pre>DBCLASS=com.planet_ink.fakedb.Driver<br />DBSERVICE=jdbc:fakedb:resources/data<br />DBUSER=<br />DBPASS=<br />DBCONNECTIONS=2<br /></pre>
<p>and change it to:</p>
<pre>DBCLASS=com.mysql.jdbc.Driver<br />DBSERVICE=jdbc:mysql://localhost/coffeemud<br />DBUSER=<br />DBPASS=<br />DBREUSE=TRUE<br />DBPINGINTERVALMINS=60<br />DBCONNECTIONS=4<br /></pre>
</li>
<li>
<p>Go back to the other file you downloaded in STEP 2,
mysql-connector-java-???.zip, and now extract that into a temp
folder. Inside, there should be a "mysql-connector-java-???.jar" file.
Copy the jar file over into your <code>c:\coffeemud\lib</code>
folder. <code>.</code></p>
</li>
<li>Open up the mud.bat file and add the name of the JAR file
above to the classpath string. For example:</li>
<ul>
<li><span style="font-family: monospace;">java -classpath
".;.\lib\js.jar;.\lib\jzlib.jar;.\lib\</span><span style="font-family: monospace;">mysql-connector-java-5.1.6-bin.jar</span><span style="font-family: monospace;">" -Xms64m ....</span></li>
<li>** Your version of the connector jar file may vary!</li>
</ul>
<li>
<p>Now, with mysqld still running in the background, just
launch the mud.bat.</p>
</li>
</ul>
<h3><a name="mysqllinux">Installing and using MySQL with
CoffeeMud on a UN*X or Linux machine</a></h3>
<ul>
<li>
<p>Download and install mysql from <a href="http://www.mysql.com/downloads/index.html">http://www.mysql.com/downloads/index.html</a>.
Make sure mysqld is being run at boot time, and not by the root user.</p>
</li>
<li>
<p>Download and install the mysql jdbc api from <a href="http://www.mysql.com/downloads/api-jdbc-stable.html">http://www.mysql.com/downloads/api-jdbc-stable.html</a>.
Extract the .tar.gz file to a temporary directory. Then copy the
extracted driver JAR file into your <span style="font-family: monospace;">/CoffeeMud/lib</span> directory.</p>
</li>
<li>Open up the mudUNIX.sh file and add the name of the JAR
file above to the classpath string. For example:</li>
<ul>
<li><span style="font-family: monospace;">nohup java
-classpath
".:./lib/js.jar:./lib/jzlib.jar:./lib/mysql-connector-java-5.1.6-bin.jar"
-Xms65535000 ....</span></li>
<li>** Your version of the connector jar file may vary!<span style="font-family: monospace;"><br />
</span></li>
</ul>
<li>
<p>Create a coffeemud database from the shell as root type,
"mysqladmin create coffeemud" (in this example we name the db
coffeemud). If you screw up, or need to delete the new db for some
reason, you can always do a "mysqladmin drop coffeemud".</p>
</li>
<li>
<p>Create a user for the new database (user in this example
is called coffee). As root, type "mysql" into the shell. Now enter:
GRANT ALL ON coffeemud.* TO coffee@localhost IDENTIFIED BY "password";
Enter a password for the user inside the quotes. Now type, "quit".</p>
</li>
<li>
<p>Edit the file CoffeeMud/guides/coffeemuddbmysql.sql like
so: at line 9 insert "use coffeemud" (assuming the new db is called
coffeemud). Then save the changes.</p>
</li>
<li>
<p>Run the SQL file as follows: from the shell type, "mysql
< coffeemuddbmysql.sql"</p>
</li>
<li>
<p>Edit the following settings in CoffeeMud/coffeemud.ini:</p>
<pre>DBCLASS=com.mysql.jdbc.Driver<br />DBSERVICE=jdbc:mysql://localhost/coffeemud<br />DBUSER=coffee<br />DBPASS=password<br />DBREUSE=TRUE<br />DBPINGINTERVALMINS=60<br />DBCONNECTIONS=4<br /></pre>
<p>(no quotes on the password here)<br />
Save your changes and fire up CoffeeMud!</p>
</li>
</ul>
<h3><a name="hsqldb">Installing and using HSQLDB with CoffeeMud</a></h3>
<ul>
<li> Get the database software
<p>Go to <a href="http://sourceforge.net/projects/hsqldb/">http://sourceforge.net/projects/hsqldb/</a>
and download the applicable archive.</p>
</li>
<li> Putting HSQLDB into the classpath
<p>Go into the archive that was just downloaded. Extract the
file hsqldb.jar. This file needs to be placed into the classpath. I
merely placed it in "<JRE install path>\lib\ext" (C:\Program
Files\Java\jre1.6.0_22\lib\ext on my system)</p>
</li>
<li> Creating the coffeemud database
<p>Open a command window and navigate to the root of the
CoffeeMUD install directory.</p>
<p>Create the directory for the database to reside in by
executing the following command (or wherever you want to call it):</p>
<pre>mkdir coffeemud<br /></pre>
<p>Now navigate into the newly created directory.</p>
<p>Next, issue the following command to start the database
interface.</p>
<pre>java org.hsqldb.util.DatabaseManager<br /></pre>
<p>The system will respond by bringing up a small GUI
application.</p>
<p>Now we need to set up the correct parameters to create the
database. The final parameter of the URL is the name of the database</p>
<pre>Type: HSQL Database Engine Standalone<br />Driver: org.hsqldb.jdbcDriver<br />URL: jdbc:hsqldb:file:coffeemud<br />User: <whatever you want><br />Password: <whatever you want><br /></pre>
<p>Now that the values have been filled in click ok.</p>
<p>The tables necessary for CoffeeMUD can be setup by:</p>
<pre>Open File Menu.<br />Select Open Script.<br />Find and open the coffeemuddbhsql.sql file in the CoffeeMUD\guides\database directory.<br />The script will then be loaded into the program.<br />Click the Execute button.<br />The system should return with and update count of 0.<br /></pre>
<p>Now to shutdown the database and exit this utility:</p>
<pre>Open Command Menu.<br />Select SHUTDOWN.<br />Click the Execute Button.<br />Open the File Menu.<br />Select Exit.<br /></pre>
<p>The coffeemud database will exist in the folder where the
DatabaseManager utility was run.</p>
</li>
<li> Set up CoffeeMUD to use the correct driver
<p>Open coffeemud.ini and scroll down to the ODBC Database
fields section. Comment out the current settings (place a # in front of
them) and add the following lines below them:</p>
<pre>#here are the settings for HSQLDB<br />DBCLASS=org.hsqldb.jdbcDriver<br />DBSERVICE=jdbc:hsqldb:file:coffeemud/coffeemud<br />DBUSER=sa<br />DBPASS=<br />DBREUSE=TRUE<br />DBPINGINTERVALMINS=60<br />DBCONNECTIONS=4<br /></pre>
<p>The file: parameter of the DBSERVICE is the path to the
database (relative from the root of the coffeemud directory) followed
by the name of the database.</p>
</li>
<li> Shut down the database gracefully
<p>Open DBConnections.java (<code>com\planet_ink\coffee_mud\core\database\</code>)
in your text editor of choice. Go to the <code>public void
killConnections()</code> function.</p>
<p>Before the synchronized block opens add the following line:</p>
<pre> update( "SHUTDOWN COMPACT" );<br /> <br /></pre>
<p>Now recompile the source and it will work like a dream...</p>
</li>
<li>Smile, you are done.</li>
</ul>
<h3><a name="derby">Installing and using Derby (IBM Cloudscape)
with CoffeeMud</a></h3>
<ul>
<li> Get the database software
<p>Go to <a href="http://db.apache.org/derby/derby_downloads.html">http://db.apache.org/derby/derby_downloads.html</a>
and download the distribution( lib or bin, unless you want to build the
whole project ).</p>
</li>
<li> Putting Derby into the classpath
<p>Derby.jar and Derbytools.jar must be placed into the
classpath for them to be of any use. These archives live in the lib
subfolder of the Derby distribution. They can be placed into the root
of the CoffeeMUD folder or they can be placed into "<JRE install
path>\lib\ext" (C:\Program Files\Java\jdk1.6.0_22\lib\ext on my
system)</p>
</li>
<li> Creating the coffeemud database
<p>Open a command window and navigate to the root of the
CoffeeMUD install directory. Issue the following command to start the
database interface.</p>
<pre>java org.apache.derby.tools.ij<br /></pre>
<p>The system will respond with:</p>
<pre>ij version 10.1<br />ij><br /></pre>
<p>Now we will issue the command that will create the
database.</p>
<pre>connect 'jdbc:derby:coffeemud;create=true';<br /></pre>
<p>After a time the ij> prompt will return. Now to run the
SQL that will set up the tables:</p>
<pre>run '.\guides\database\coffeemuddbderby.sql';<br /></pre>
<p>A description of all of the tables created will fill up
the window. Finally, we must disconnect from the database and exit the
utility.</p>
<pre>disconnect;<br />exit;<br /></pre>
<p>The coffeemud database will exist in a folder called
'coffeemud' in the current working directory, and if CoffeeMUD is to
find it this must be the root of the coffeemud install.</p>
</li>
<li> Set up CoffeeMUD to use the correct driver
<p>Open coffeemud.ini and scroll down to the ODBC Database
fields section. Comment out the current settings (place a # in front of
them) and add the following lines below them:</p>
<pre>#here are the settings for IBM Cloudscape/Derby/ApacheDB<br />DBCLASS=org.apache.derby.jdbc.EmbeddedDriver<br />DBSERVICE=jdbc:derby:coffeemud<br />DBREUSE=TRUE<br />DBCONNECTIONS=2<br /></pre>
</li>
<li> Smile, you are done... well mostly
<p>Currently there are some minor changes that must be made
to the code for Derby to work properly.</p>
</li>
<li> Change?
<p>This step is not really necessary, it just makes things
cleaner. Currently when CoffeeMUD is shut down it does not exit the
database properly, I have not yet worked out a good way to fix this,
however, the following will work:</p>
<p>Open DBConnections.java (<code>com\planet_ink\coffee_mud\core\database\</code>)
in your text editor of choice. Go to the <code>public void
killConnections()</code> function.</p>
<p>after the synchronized block closes add this:</p>
<pre> try<br /> {<br /> DriverManager.getConnection("jdbc:derby:;shutdown=true");<br /> }<br /> catch (SQLException se)<br /> {<br /> }<br /> <br /></pre>
<p>Now recompile the source and it will work like a dream...</p>
</li>
<li> Increasing performance
<p>The basic settings for Derby end up in it being about half
the speed of other databases. The method to correct this is simple,
however, it is very memory intensive (I upped the maximum memory for
CoffeeMUD to 512 Megs, it really only uses about 300 Megs...)</p>
<p>Before running step 4 (the creation of the database),
create a file called 'derby.properties' in the root CoffeeMUD
directory. This file should contain:</p>
<pre># derby.properties<br />#<br />derby.storage.pageSize=32768<br />derby.storage.pageCacheSize=10000<br /></pre>
<p>When the coffeemud database is created this time it will
run at about the same speed as other databases. More information on
these properties can be found at <Derby Install
Path>\doc\pdf\tuning.pdf.</p>
</li>
</ul>
<br />
<br />
<img src="images/nuked.jpg" alt="offline and shutdown applications" />
<h2><a name="shutdown">The OffLine And Shutdown Applications</a></h2>
<p>In the off chance you should need to keep your mud down while
database, or other software (or hardware?) maintenance is going on, a
small footprint OffLine application is available. This application will
read the port information from your coffeemud.ini file just like the
regular mud server. It will accept connections, but only to display the
file resources/text/down.txt before disconnecting the user
automatically. To execute this application, you should go into your
coffeemud directory and enter:</p>
<pre>java com.planet_ink.coffee_mud.application.OffLine<br /></pre>
<p>The Shutdown application is a means of shutting down your MUD
remotely without logging in. It is part of the application package of
CoffeeMud, but it does not rely on any of the other internal classes.
You may therefore, if you like, copy the file Shutdown.class onto a
floppy disk and execute it from there, so long as the file is stored in
a com/planet_ink/coffee_mud/application folder or directory.</p>
<p>The Shutdown application requires that you pass to it the URL
of your server, the standard MUD port to connect to, the login name of
a valid Archon character, and the password. You may optionally also
include the word 'true' if you wish the system to reboot instead of
simply shutting down. To execute this application, you should go into
your coffeemud directory or wherever the "com" directory for CoffeeMud
is located, and enter:</p>
<pre>java com.planet_ink.coffee_mud.application.Shutdown localhost 5555 AdminName AdminPassword<br /></pre>
</td>
</tr>
</tbody>
</table>
</center>
</body></html>
