Installing and Using CoffeeMud 3.0 Installation: The first and most critical step in installing CoffeeMud 3.0 is to make sure that you have downloaded and installed the latest version of the Sun Java JDK. As of this writing, that version is Java 1.4.0. CoffeeMud uses the latest Sun classes, so stay up to date! The second step in installing CoffeeMud 3.0 is to unpack the CoffeeMud.zip package into a directory on your hard drive. This directory may be called, for instance, "CoffeeMud". 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, finish reading this document. If you couldn't care less, then go into the your CoffeeMud directory on a command line and enter: java -Xms25535000 -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. Now, connect to the server on port 4444 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. If you are happy and ready to start making maps and other such nonsense, you may want to switch to reading the Archon's Guide, which is also part of the guides package in CoffeeMud. If you would like to learn a little more about Archon abilities first, however, you may want to finish reading this document. 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 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 (see the section on "CoffeeMud Administration") before the changes will take effect. 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 4444. 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 seperated 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. I3CHANNELS This is a comma seperated list of InterMud3 channels which the users of your system may converse publicly on. Each channel entry is seperated 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 (MUDGrinder.html) for more information on this tool. For more information on the CoffeeMud web server in general, please read the WebServer Guide (WebServer.html). 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. 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. 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 "data" 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, 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 three files: "coffeemuddb.sql", "coffeemuddb2.sql", and "fakedb.schema". The first two are SQL Scripts which can be used to create the necessary tables in Microsoft SQL Server, MySQL, Oracle, Access, and some of the others. The last is a copy of the same fakedb file from your "data" 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, 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. CoffeeMud Administration: The administration of your CoffeeMud server is done from within the game server itself, when you are logged in as your Archon player. You may use "ahelp" and "atopics" to see a list of some Archon specific functionality. Many of these commands are discussed in depth in the Archon's Guide (ArchonGuide.html). Here are a few highlights of the Archon commands: SHUTDOWN Although CoffeeMud can also be brought down by killing the Java virtual machine, the proper way to shut down CoffeeMud is by entering the shutdown command. This will ensure that all users are saved back to disk, and that the system goes down in a polite and orderly manner. This is also the command which should be used when changes are made to your "coffeemud.ini" file. Changes to your INI file do not take affect until your server is restarted. LIST The Archon is able to list lots of different things, for many different reasons. "list users" will show you all of the players, and when they logged on last. This is useful for weeding out olde players (see DESTROY below). "list sessions" will show you a list of all active players. "list threads" will show you how many Java threads are active. "list ticks" will show you all the objects making use of those threads! "list reports" will who you your resource usage. TAKE Use this command if a player or monster has something that doesn't belong to them, and you need it back. POSSESS Easily the most fun part of being an Archon is to possess one of the monsters and harass the players, making them think the monsters have truely come to life! ORDER Although any player may order around their followers, an Archon can order ANYONE to do ANYTHING. UNLOADHELP If you've made any changes to your help files, and don't want to have to reboot the whole MUD, you can use this command as a short-cut. DUMPFILE When you want to view some text file on your system through the MUD. WIZINV Sometimes an Archon wants a little privacy, and this command gives it to him or her. It will make the Archon completely undetectable, allowing free movement without harassment from players or monsters. RESET Giving a parameter of "room" or "area", this command will make everything reset back to the state it was last saved at. GOTO Allows the Archon to zap him or herself directly to the room or mob of his or her choice. The argument is a valid Room ID, room name, mob name, or area name. WHERE Allows the Archon to who all is online, and where they are on the map. An argument may be given to specify a specific mob name. EXPORT If you need a backup to your database, you can save your areas one at a time as files, for reimportation in the event of a disaster. IMPORT In addition to allowing the reimportation of areas saved using EXPORT, IMPORT will also take in area files from other MUDs, such as ROM, CircleMUD, and others. The ROM format is by far the best supported, however. SAVE This command, depending on the argument, can update the players data, or can make aspects of the Archons room permanent by saving it to the database. CREATE Depending on the argument, this command can bring almost anything into existence, from rooms to doors, from monsters to items. MODIFY If something which exists is not quite right, this command can make it right. DESTROY Last but not least, this powerful command can be used to banish objects and mobs, rooms and areas, or even players -- permanently. A player (user) need not be online to be destroyed. SNOOP Last but not least, this powerful command can be used to banish objects and mobs, rooms and areas, or even players -- permanently. A player (user) need not be online to be destroyed. CHARGEN Although it's not a vital administration tool, CharGen can be used to take a glimpse of what the "typical" user of a particular class might look like. This can be a helpful aid in the construction of monsters, perhaps.