Installing and Using CoffeeMud 5.0 Installation: The first and most critical step in installing CoffeeMud 5.0 is to make sure that you have downloaded and installed the latest version of the Sun Java SDK. As of this writing, that version is Java 1.5.0. CoffeeMud uses the latest Sun classes, so stay up to date! 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. 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. 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". If you are using a UNIX/Linux system, you should now bring up a console and cd to whatever directory you unpacked CoffeeMud to. Make sure you can write to mudUNIX.sh by issung the the command chmod 766 mudUNIX.sh Now, enter sh InstallUNIX.sh Follow the prompts by inputting the directory of JAVA; do not enter a trailing slash, for instance: /opt/j2sdk/j2sdk1.4.2 Continue following the prompts: Say y if you want to compile the main program, n 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 y if you want to start your MUD now, and n if you don't. Hit enter after the nohup comes up. Send an email to wrichter@att.net if you have any problems with this script. If you are using Windows, or you are using UNIX/Linux and have completed the above instructions... Congratulations! You have successfully installed CoffeeMud. 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): java -classpath ".;.\lib\js.jar" -Xmx85535000 com.planet_ink.coffee_mud.application.MUD "Your Muds Name" And for Unix, Linux, or FreeBSD users, the command differs only in the classpath: java -classpath ".:./lib/js.jar" -Xmx85535000 com.planet_ink.coffee_mud.application.MUD "Your Muds Name" 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 mud.bat using Notepad, 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 chmod 755 mudLINUX.sh, and then execute. 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. 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: get book read book 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: ahelp import This will tell you how to import *.CMARE files, which are CoffeeMud formatted area files. Other formats are supported as well. If you'd like to actually learn how to use the CoffeeMud engine, you should do the following: o Finish reading this document o Review the coffeemud.ini file, or use the MudGrinders Control Panel o Read the Archon's Guide o Read the Builders FAQ. o Read the Web Server Guide. o Read the SMTP Server Guide. o Read the Programmers Guide. Otherwise, once you have your administrator and a few areas, you are technically ready to play! Upgrading From a Previous Version of CoffeeMud 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. Unchanged Database Schema Process 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: 1. 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. 2. 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. 3. Now unpack/unzip the new version of CoffeeMud on TOP of your olde one. 4. 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. Copy 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. 5. 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. 6. Smile, you are done. Changed FakeDB Database Schema Process 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: 1. 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! 2. Go back to the beginning of this section and follow steps 1 through 5 from the unchanged database schema process. 3. From the command line, go into your CoffeeMud directory, and from there into fakedb data directory. Delete all the files matching fakedb.data.* Do NOT delete the fakedb.schema! If everything went well, the new fakedb.schema from the new version of CoffeeMud is still in your fakedb data directory. 4. Still from the command line, go into your CoffeeMud directory and enter the following: java com.planet_ink.fakedb.DBUpgrade 5. Follow the instructions for this little program. 6. Smile, you are done. Changed Database Schema Process (not FakeDB) 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: 1.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. 2.Go back to the beginning of this section and follow steps 1 through 5 from the unchanged database schema process. 3. 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! 4. From the command line, go into your CoffeeMud directory and enter the following from the command line: java com.planet_ink.fakedb.DBUpgrade 5. Follow the instructions for this little program. 6. 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. 7. Smile, you are done. Settings: 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: notepad, 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. If you are happy with the standard installation, you will usually also be content to leave 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. 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 MUDGrinder web site. SYSMSGS, ERRMSGS, DBGMSGS These entries refer to logged system messages, logged error messages, and logged debug messages respectively. 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, or "BOTH" for both screen and file output. By default, SYSMSGS and ERRMSGS are set to "BOTH", while DBGMSGS is set to "OFF". PORT 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! START 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. CHANNELS This is a comma separated list of channels which the users of your system may converse publicly on. An miminum character level may optionally be specified after each channel name. The channel names given here are completely arbitrary and may be meaningful or whimsical terms, though the names may not contains spaces. A couple of standard channels are specified. The limit for the number of standard channels plus any InterMud channels (see I3CHANNELS below) is 16 or 32, I forget. BACKLOG This TCP/IP setting denotes how many connections can be queued up when the server is busy. Leave it at 6. BIND 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. RUNI3SERVER 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. I3PORT 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 RUNI3SERVER entry above is FALSE, this setting will have no effect. I3STATE This is a short description of the state of your mud as you want it published to the I3 network. A state is typically like "Private", or "Open to the public", or "Under Construction", etc. I3CHANNELS 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 locate channel name (no spaces in the name), followed by a space, followed by a minimum character level to view or chat on the channel, followed by a space, followed 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 CHANNELS above) plus any InterMud channels is 16 or 32, I forget. RUNWEBSERVERS This setting tells CoffeeMud whether to start up the built-in web servers. A value of "TRUE" will turn on the 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 MUDGrinder Guide for more information on this tool. For more information on the CoffeeMud web server in general, please read the WebServer Guide. RUNSMTPSERVER 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 SMTPServer Guide. ITEMS, MOBS, BEHAVIORS, ABILITIES, CHARCLASSES, RACES, COMMANDS, LOCALES, AREAS, EXITS 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 Programmer's Guide for more information on writing custom classes for CoffeeMud. DBCLASS 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. DBSERVICE 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. DBUSER, DBPASS 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. DBCONNECTIONS 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. * 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 them. The CoffeeMud Package: 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. The directories inside the com directory contain all the Java Class files, which are the executable portion of CoffeeMud. All of the Java source files are also found herein. The guides 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. The guides/database directory is where you'll find several SQL scripts necessary to configuring another database engine, such as SQL Server, MySQL, PostGRE, Access, and others. The guides/images directory contains image files used inside the HTML files in the guides directory. The lib 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. The web 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. admin.ini 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. common.ini The configuration file for certain settings common to both the admin and public web servers. pub.ini The configuration file for the public web server. email.ini The configuration file for the smtp server. The admin directory is where the pages made available by the admin web server are found, by default. This directory also contains the admin/images to store image files displayed by the admin pages, as well as the admin/grinder directory, where the MUDGrinder pages are stored by default. The admin.templates directory is where the default error page for the admin web server is found. The pub directory is where the pages made available by the pub web server are found, by default. This directory also contains the pub/images to store image files displayed by the public web pages, as well as the pub/sounds directory where MSP sound files are stored for players to access. The pub.templates directory is where the default error page for the pub web server is found. The resources 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: chat.dat The configuration file for the MudChat behavior. You can edit this one too. laws.ini The default configuration file for the Arrest behavior. You can edit this, but its easier to deal with law through law books. lawtoc.ini The default pages file for the GenLawBook item. alignment.ini The default faction configuration file for player alignments. There are command line tools for factions. movingroom.xml A sample configuration file for the MovingRoom behavior. socials.txt The text file holding all of the socials. There is a command line tool for updating this file. mxp_images.txt A definition table for the default image files used for mxp clients. The resources/fakedb 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. The resources/examples directory is where you'll find sample files for a variety of things. It contains a cmare file with some example deities to load into your mud. Use the import command to load this set of mobs. It also contains a sample faction ini file called "reputation.ini", which you may put into the proper tag in your coffeemud.ini file to make use of, as well as a template file for use when new factions are created. It also contains a sample MOB class written in javascript. Use LOAD MOB resources/examples/Lemming.js to load it up. The resources/help 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 \ The resources/progs directory contains several sample MOBPROG files loadable using the Scriptable behavior. The resources/quests 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. The resources/scripts directory will some day contain directories for each of the human languages CoffeeMud has been translated into. At present, only the EN_TX (English) directory exists, with some accompanying text files containing strings used in CoffeeMud. This set of strings is quite incomplete. The resources/skills 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 seperated by carriage returns. The resources/text 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: alignment.txt A text file describing alignment to new players. classes.txt A text file describing class selections for new players. credits.txt The text file shown to users who use the CREDITS command. down.txt The text file displayed to users only when the OffLine application is running. intro.txt The text file displayed to users when they connect to your mud. mxp.txt A text file containing the complete MXP dictionary. See http://www.zuggsoft.com/zmud/mxp.htm for more information on this feature. newchar.txt A text file introducing your mud to new players. offline.txt A text file shown to players while your mud is booting. races.txt A text file describing race selections to new players. stats.txt A text file describing the basic stats to new players motd.txt A text file shown to users when they log on. The existence of this file activates MOTD command, as well as the MOTD entry in the CONFIG command. Of course, since CoffeeMud News journals are also displayed at boot time, and their subjects may be prefixed with MOTD, MOTM, or MOTY to make their redisplay perpetual, there really is no good reason to use this feature as an Message Of The Day per se. Instead, this file is best used for fancy introductions to your mud, or congratulations for having figured out how to log in perhaps. The CoffeeMud Database: 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. 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, and performs well the small tasks it was designed for. For the more adventurous, CoffeeMud supports any JDBC or ODBC compliant database system. This includes such systems as Microsoft Access, Microsoft SQL Server, PostGRE SQL, 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", "coffeemuddb2.sql", "coffeemuddbaccess.sql", "coffeemudibmdb2.sql", "coffeemuddbmysql.sql", "coffeemuddbpsql.sql", "coffeemuddbh.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 ("coffeemuddb2.sql"), MySQL ("coffeemuddbmysql.sql"), Access ("coffeemuddbaccess.sql"), PostGRE ("coffeemuddbpsql.sql"), Derby ("coffeemuddbderby.sql"), HSQLDB ("coffeemuddbh.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. 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 many cases, you will be creating a System ODBC Data Source. When this is the case, the driver "sun.jdbc.odbc.JdbcOdbcDriver" may be used to access the database. Some 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. 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. Installing and using Microsoft Access with CoffeeMud on a Windows machine 1. Open up Microsoft Access and select to create a Blank Access Database. Give the database a name and save it on your hard drive. 2. Under Objects, select the Queries section and select Create Query in Design View. When the dialog box appears, click the close button. 3. Now right click on the large grey area and select "SQL View" from the context Menu. 4. Inside your CoffeeMud/guides/database folder, open up the coffeemuddbaccess.sql file using Notepad. You will see that the file contains numerous blocks of sql text. Each block begins with CREATE TABLE, and ends with a semicolon ); 5. Select the first block of text in your sql file, from the first CREATE TABLE line down through the ); line, and select Copy from Notepad. Paste this block into the Select Query area in Microsoft Access. Paste it over any other text that may be in there. 6. Press the "!" symbol at the top to execute the block of sql script. 7. Repeat steps 5 and 6 for the remaining CREATE TABLE blocks in the coffeemuddb2.sql file. 8. Now go to your Windows Control Panel (under XP, switch to Classic View) and double-click the ODBC Data Sources (32-bit) icon. If you are using Windows 2000 or XP, double-click the Administrative Tools option. Then select the Data Sources (ODBC) icon. 9. Now, click on the System DSN tab. Click the Add button. This will present you with a list of drivers. Select "Microsoft Access Driver (*.mdb)" 10. Here you should probably name the data source something sensical, like CoffeeMudData or the like. Under Database, click Select. Locate and select your CoffeeMud.mdb file that you saved in step 1. Click OK and then OK to get all the way back out of things. 11. Open coffeemud.CMVars. Go to where it says "ODBC Database fields". That section should instead look like this: #------------------------ # ODBC Database fields #------------------------ # DBCLASS is the name of the ODBC Driver, typically sun.jdbc.odbc.JdbcOdbcDriver # DBSERVICE is the name of the ODBC Service as defined by your local operating system # DBUSER is a user name required to log into the ODBC service # DBPASS is the password for the above user name # DBCONNECTIONS is the number of independent connections to make to the database DBCLASS=sun.jdbc.odbc.JdbcOdbcDriver DBSERVICE=jdbc:odbc:CoffeeMudData DBUSER= DBPASS= DBCONNECTIONS=1 Where it says "jdbc:odbc:CoffeeMudData", make sure the part after "jdbc:odbc:" 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! Installing and using MySQL with CoffeeMud on a Windows machine 1. Go to www.mysql.com, click on Downloads (one of the tabs at the very top), scroll down under "MySQL database server & Standard Clients:" and click on MySQL 4.0 -- Production release (recommended). Scroll down to "Windows downloads", you will see Windows 95/98/NT/2000/XP, and click on the "Pick a mirror" link to the right, and choose a place to download from.. You will be promted to save a file called "mysql-4.0.1.2-win.zip" (or whatever the newest version is). Save that to a temp folder (WARNING, the file is about 21 megs!). 2. Go back to the Downloads tab, this time scroll down to "Application Programming Interfaces (APIs), and click on "MySQL Connector /J -- for connecting to MySQL from Java". On the next screen, click on "MySQL Connector /J3.0 -- production release". On the next page, click on the download link for "Source and Binaries (zip)" ( be SURE to get the ZIP file, not the (tar.gz)!) The file name should be "mysql-connector-java-3.0.7-stable.zip". Again, save this file to your temp folder as well. 3. Locate the mysql-4.0.1.2-win.zip file you downloaded and unzip it ( if you dont know how to do that..I dont think running a mud should be on your list of priorities...) and run the setup.exe file there. Just hit Next for all the prompts, and it should install to c:\mysql by default. 4. Go to your coffeemud folder, open the guides\database folder, and you will see a file called "coffeemuddbmysql.sql". Open that file with a text editor or notepad etc... (you might want to make a backup copy first...) Now, add the following: # Connection: SQL # Host: localhost # Saved: 2003-04-01 00:29:14 # # Connection: SQL # Host: localhost # Saved: 2003-04-01 00:27:39 # use coffeemud <----ADD THIS LINE! CREATE TABLE CMCHAB ( CMUSERID char (50) NULL , CMABID char (50) NULL , CMABPF int NULL , CMABTX text NULL etc.. etc.. Now copy the edited coffeemuddbmysql.sql to your c:\mysql\bin folder. 5. Now, open a DOS window (Start > Run > type "command" and hit enter) and type cd c:\mysql\bin and hit Enter. Your prompt should now be c:\mysql\bin> then type "mysqld" (notice the d on the end..?). After a few moments, it should start up the mysql server. You wont get a new window or icon or anything, I check it by doing CTRL-ALT-DEL and see if Mysqld is listed in the Close Program Window. If it's there, you're in business, and MySQL is running in the background. You should now be back to the c:\mysql\bin> prompt. 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 "\q" and that should quit you out of the monitor. 6. Now that your out of the monitor, you should be back to the c:\mysql\bin> prompt. Now type "mysql < coffeemuddbmysql.sql" (without the quotes of course) and hit enter... again, after a moment or 2, it SHOULD return you to the c:\mysql\bin> prompt. Go ahead and close that window now. In theory, you should now have mysql running and a coffeemud database all set for it to access. 7. Now go to your coffeemud folder and open your coffeemud.ini file in notepad or some text editor, and look for the section that says: DBCLASS=com.planet_ink.fakedb.Driver DBSERVICE=jdbc:fakedb:resources/data DBUSER= DBPASS= DBCONNECTIONS=2 and change it to: DBCLASS=com.mysql.jdbc.Driver DBSERVICE=jdbc:mysql://localhost/coffeemud DBUSER= DBPASS= DBCONNECTIONS=4 8. Go back to the other file you downloaded in STEP 2, mysql-connector-java-3.0.7-stable.zip, and now extract that into a temp folder. Inside, there should be a "mysql-connector-java-3.0.7-stable" folder and inside that, a "com" folder, and inside THAT, a "mysql" folder. Copy the mysql folder over into your c:\coffeemud\com folder. So now inside c:\coffeemud\com, ther should be 2 folders, one called mysql, and one called planet_ink. 9. Now, with mysqld still running in the background, just launch the mud.bat AS IT IS to start the mud..( I didnt have to make ANY changes in there for this to work, hopefully the same for you...) Installing and using MySQL with CoffeeMud on a UN*X or Linux machine 1. Download and install mysql from http://www.mysql.com/downloads/index.html. Make sure mysqld is being run at boot time, and not by the root user. 2. Download and install the mysql jdbc api from http://www.mysql.com/downloads/api-jdbc-stable.html. Extract the .tar.gz file to a temporary directory. Then copy the extracted /com/mysql/ directory (not just its contents) into /CoffeeMud/com/. 3. 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". 4. 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". 5. 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. 6. Run the SQL file as follows: from the shell type, "mysql < coffeemuddbmysql.sql" 7. Edit the following settings in CoffeeMud/coffeemud.ini: DBCLASS=com.mysql.jdbc.Driver DBSERVICE=jdbc:mysql://localhost/coffeemud DBUSER=coffee DBPASS=password DBCONNECTIONS=4 (no quotes on the password here) Save your changes and fire up CoffeeMud! Installing and using HSQLDB with CoffeeMud on a UN*X or Linux machine 1. Get the database software Go to http://sourceforge.net/projects/hsqldb/ and download the applicable archive. 2. Putting HSQLDB into the classpath 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 "\lib\ext" (C:\Program Files\Java\j2re1.4.2_06\lib\ext on my system) 3. Creating the coffeemud database Open a command window and navigate to the root of the CoffeeMUD install directory. Create the directory for the database to reside in by executing the following command (or wherever you want to call it): mkdir coffeemud Now navigate into the newly created directory. Next, issue the following command to start the database interface. java org.hsqldb.util.DatabaseManager The system will respond by bringing up a small GUI application. 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 Type: HSQL Database Engine StandaloneDriver: org.hsqldb.jdbcDriverURL: jdbc:hsqldb:file:coffeemudUser: Password: Now that the values have been filled in click ok. The tables necessary for CoffeeMUD can be setup by: Open File Menu. Select Open Script. Find and open the coffeemuddbh.sql file in the CoffeeMUD\guides\database directory. The script will then be loaded into the small text box on the upper right. Click the Execute button. The system should return with and update count of 0. Now to shutdown the database and exit this utility: Open Command Menu. Select SHUTDOWN. Click the Execute Button. Open the File Menu. Select Exit. The coffeemud database will exist in the folder where the DatabaseManager utility was run. 4. Setup CoffeeMUD to use the correct driver 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: #here are the settings for HSQLDBDBCLASS=org.hsqldb.jdbcDriverDBSERVICE=jdbc:hsqldb:file:coffeemud/coffeemudDBUSER=saDBPASS=DBCONNECTIONS=4 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. 5. Smile, you are done. Installing and using Derby (IBM Cloudscape) for Windows or *nix 1. Get the database software Go to http://db.apache.org/derby/derby_downloads.html#Latest+Official+Release and download the applicable installer (I used the Java installer). 2. Install the database software Follow the instructions included with the installer. 3. Putting Derby into the classpath 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 path where Derby was installed. They can be placed into the root of the CoffeeMUD folder or they can be placed into "\lib\ext" (C:\Program Files\Java\j2re1.4.2_06\lib\ext on my system) 4. Creating the coffeemud database Open a command window and navigate to the root of the CoffeeMUD install directory. Issue the following command to start the database interface. java org.apache.derby.tools.ij The system will respond with: ij version 10.0 (C) Copyright IBM Corp. 1997, 2004.ij> Now we will issue the command that will create the database. connect 'jdbc:derby:coffeemud;create=true'; After a time the ij> prompt will return. Now to run the SQL that will set up the tables: run '.\guides\database\coffeemuddbderby.sql'; A description of all of the tables created will fill up the window. Finally, we must disconnect from the database and exit the utility. disconnect;exit; 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. 5. Setup CoffeeMUD to use the correct driver 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: #here are the settings for IBM Cloudscape(Derby)DBCLASS=org.apache.derby.jdbc.EmbeddedDriverDBSERVICE=jdbc:derby:coffeemudDBCONNECTIONS=2 6.Smile, you are done... well mostly Currently there are some minor changes that must be made to the code for Derby to work properly. 8.Change? 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: Open DBConnection.java in your text editor of choice. Goto the close() function. change if(myConnection!=null) myConnection.close(); into if(myConnection!=null){ try { DriverManager.getConnection("jdbc:derby:;shutdown=true"); } catch (SQLException se) { }} Now recompile the source and it will work like a dream... 9.Increasing performance 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...) Before running step 4 (the creation of the database), create a file called 'derby.properties' in the root CoffeeMUD directory. This file should contain: # derby.properties#derby.storage.pageSize=32768derby.storage.pageCacheSize=10000 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 \doc\pdf\tuning.pdf. The OffLine And Shutdown Applications: 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: java com.planet_ink.coffee_mud.application.OffLine 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. 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: java com.planet_ink.coffee_mud.application.Shutdown localhost 5555 AdminName AdminPassword