About PerlMUD 3.0

What is PerlMUD?

PerlMUD is a MultiUser Dimension (MUD), a text-based environment that allows multiple users to converse, explore, and interact. PerlMUD is written in Perl 5 and is highly compatible with the well-known TinyMUD command set, which provides a friendly interface to your online environment.

Complete Perl source code is included. Administrators can easily extend the PerlMUD system by writing additional Perl code.

What's new and nifty about version 3.0?

Version 3.0 is 100% backwards compatible with previous releases and the databases that they produced.

Version 3.0 has two major new features:

Topics offer some of the best features of IRC, while respecting the style and personality of MUD systems. Topics provide a way to hold open conversations on specific topics in a crowded MUD room while giving others the opportunity to opt out if they choose. See "help topics" for more information.
The new @reload command allows the administrator to reload new PerlMUD source code without shutting down the mud. Beginning in version 3.0, the vast majority of the code and configuration options are located in the file mudlib.pl. Essentially all of the MUD's behavior can be changed "on the fly" with this feature. Administrators in production environments can use this feature to activate new changes without restarting, after testing them in a separate test MUD environment. See help @reload and the mudlib.pl and mud source files for more information.

What Was New In Version 2.1

Version 2.1 lets the MUD administrator decide whether new users should be allowed to build. You control this by setting the $allowBuild flag (in the configuration section at the top of the mud source file) to 1 for yes or 0 for no.

Version 2.1 also lets the MUD admin decide whether users should be permitted to use the @emit command, which says things without prefixing them with the user's name. Set the $allowEmit flag to 1 or 0 to control this feature.

Version 2.1 adds the @gag and @ungag commands. @gag person prevents you from hearing anything that person says. (Beware: you won't see them coming or going either.) @ungag person lets you hear that person again. Type examine me to find out who is on your personal gag list if you have forgotten.

Finally, Version 2.1 writes a new database format which should not need to be changed again. The source code of version 2.1 has been rewritten to use an array of objects (hashes), instead of separate arrays for each characteristic of an object, and the new database format stores attribute-value pairs. This will make it much easier to customize your mud server code in a way that is compatible with new releases of PerlMUD.

What Was New in Version 2.0

Version 2.0 of PerlMUD includes a simple, effective web-based user interface that any web browser can use. Browsers that support frames get the best interface, with automatic refresh of the output frame, but other browsers can also use the system; even lynx can handle it! This simple web-based client is compatible with most firewalls if the user has web access through a proxy server. PerlMUD acts as a simple web server in its own right. This makes it drastically more efficient than CGI-based chat solutions.

A Java-based client, which is comparable to specialized mud clients in its friendliness, is also included.

What do I need to run a PerlMUD server?

You need access to a computer that offers Perl 5.001 or better. If you are still using Perl 4.0, you need to upgrade.

Most Unix systems offer Perl. PerlMUD may or may not work for you under Windows. PerlMUD will run just fine under MacOS X. If you do use the software with Windows, you will need to provide a compatible alternative to the Unix sendmail program, or give out accounts manually. Your input on NT experiences is welcome.

MacPerl can apparently run PerlMUD with some success on MacOS Classic; again, more input on this is welcome.

PerlMUD runs without problems under Linux and other common Unix operating systems with Perl 5 installed.

Where can I get PerlMUD?

Point your web browser at the following URL:

http://www.boutell.com/perlmud/perlmud-3.0.tar.gz

Save the file to disk. You will need to issue these commands after the download:

uncompress perlmud-3.0.tar.gz 
tar -xf perlmud-3.0.tar
cd perlmud-3.0

The above commands are intended for Unix, and will also work at the terminal prompt in MacOS X.

How do I set up PerlMUD?

Once you unpack the program, as shown above, you must configure it. The Perl source code is in the file "mud". You will need to edit the $dataDirectory setting at the top of that file to match the directoy where PerlMUD 3.0 hs been placed.

Perform the following steps:

1. Using a text editor, such as vi, set $dataDirectory in the file mud to point to the path where you have installed PerlMUD 3.0.
2. Copy the file "minimal.db" to "mud.db".
3. Set $serverName in mudlib.pl to the name you would prefer to see in the titles of various web pages produced by the simple web interface.
4. Set $hostName in mudlib.pl to the Internet host name of the server. Example: if your PerlMUD server runs on the machine www.mycompany.com, then put www.mycompany.com here. You cannot simply make up a name -- if you don't know what the machine is called, ask the administrator. This information is used to give new users instructions to connect to the MUD when they receive accounts via email.
5. Optionally, change $tinypPort (if you do not want to use port 4096) and code>$httpPort (if you do not want to use port 4196) in mudlib.pl. The first is used for telnet and java client access; the second is used by the simple web interface.

Now, to start the MUD, type (under Unix):

perl mud &

In the beginning, there are only two objects: The Void (a room, object #0) and Admin (a player, object #1).

Wait a few seconds for the mud to start, then type the following commands (under Unix):

telnet localhost 4096
connect admin initial

Once you have logged into the admin character, type "help" for more information. You will find the tutorial topics useful to get you started with PerlMUD administration.

SECURITY ALERT: change your password using the @password command before you let the public know your server exists! Try "help @password" while logged into the mud for further instructions. (Most administrative commands begin with an @ sign.)

How do I add more rooms and objects?

Type "help building" to read about how to create objects; type "help rooms" for information about creating new rooms and exits between them. Type "help admin" for a list of administrative commands.

How will my users access PerlMUD?

Your users can apply for accounts right on the web, by accessing the simple web server built in to your PerlMUD system! The URL to use is http://yourhost.com:4196/, where yourhost.com should be replaced with the hostname of the machine you are running your PerlMUD server on.

How do I restrict access?

Running a Completely Private System

The simplest solution is to create an empty file called allowed.txt in your PerlMUD directory. This will tell PerlMUD not to let anyone apply for an account online. Instead, you will use the @pcreate command when logged in as the admin user, to create accounts manually:

@pcreate name = password

You'll also want to edit the document home.html to no longer link to the special "public applications" URL of the server ( /apply ).

Open Access from Only One Organization

If you wish, you can allow users whose email addresses are in a specific domain to apply freely for accounts without any extra effort on your part. Just create a file called allowed.txt in your PerlMUD directory, and put the names of domains and/or individual email addresses that are allowed to apply for accounts.

Here's a simple example:

boutell.com

If your allowed.txt file contains the line above, then all users with addresses ending in boutell.com are permitted to apply for accounts.

Here's another example:

boutell.com
smith@jones.com

This allowed.txt file would permit anyone at boutell.com, or the specific email address smith@jones.com, to apply for an account.

Locking Out A Few Bad Apples

The last option, which public servers will want to use, is to simply lock out "bad apples" by domain or by email address. Each time a new user is given an account, a line is written to the file accounts.log, giving the account name and the email address for that user. You can use this information to decide who must be locked out of the system.

Just create a file called lockouts.txt in your PerlMUD directory, and put the names of domains and/or individual email addresses that are NOT allowed to apply for accounts.

Here's a simple example:

ugly.com

If your allowed.txt file contains the line above, then all users with addresses ending in ugly.com are NOT permitted to apply for accounts.

Here's another example:

ugly.com
jerk@jones.com

This allowed.txt file would not permit anyone at ugly.com, or the specific email address jerk@jones.com, to apply for an account under any circumstances.

How do I know where a jerk is coming from?

Each time a new user is given an account, a line is written to the file accounts.log, giving the account name and the email address for that user. You can use this information to decide who must be locked out of the system.

How do my users log on?

There are three ways to access PerlMUD servers.

The simplest, although the least attractive, is to connect through any web browser by accessing the URL http://yourhost.com:4196/.

This simple interface is easy to access, but users who are familiar with telnet programs will prefer to telnet to port 4096 on the server machine, or use a mud client program such as TinyFugue for Unix or one of the numerous Mac and Windows mud clients.

The third approach, which is as easy to understand as the web interface, as fast as the telnet interface, and more attractive than either, is to use the Java PerlMUD client. The Java client is far more user-friendly than a telnet session, and it appears as an integral part of the web browser.

What if my users are behind a firewall?

They will get best results using the simple web interface, which is accessed at the following URL: http://yourhost.com:4196/

Of course, yourhost.com must be replaced by the name of the host on which your PerlMUD server is running.

Some users with firewalls may also have telnet access if they are permitted to log into a special "gateway" machine first.

Is PerlMUD stable?

Version 3.0 of PerlMUD has withstood many years of daily use, including an online/real world wedding ceremony with over 50 active participants. Complete online help is included, with tutorial topics for new users and admins as well as a command-by- command reference.

Does PerlMUD require a lot of memory?

PerlMUD is RAM-based, so the database resides in virtual memory. A PerlMUD system with only two objects occupies about 2.3 megabytes of virtual memory, but each additional object requires very little space. My system, with 205 objects and several players logged on, occupies about 3 megabytes of virtual memory.

Is PerlMUD efficient?

PerlMUD requires very little CPU. PerlMUD wakes up only when a user issues a command, so typical CPU use is near zero.

Is PerlMUD extensible?

Yes, by the MUD administrator. The entire MUD is written in the extremely friendly Perl programming language, so adding new commands is straightforward.

What about programming documentation?

The code is reasonably well-commented.

How do I customize the web pages PerlMUD displays?

Just edit the HTML files accepted.html, application.html, and home.html.

Do I have to register PerlMUD?

No, PerlMUD was released under the MIT license on July 4th, 2011.

Boutell.Com, Inc. Email: perlmud@boutell.com