MUDDweller 1.2 User Manual O. Maquelin, February 21, 1994
==========================
MUDDweller 1.2 is a MUD client for the Macintosh. MUDs (Multi User Dungeon/Dimension) are multi-user games, usually running on UNIX machines and accessed through the internet. This program allows you to connect to a MUD, either with the communication toolbox or with MacTCP. It works roughly like a terminal emulator, but is line- oriented and offers additional functionality. Of course, it might also be possible to use this program for other types of line-oriented communication.
MUDDweller supports multiple sessions, connections with either the communication toolbox or with MacTCP, a command history and simple file transfer mechanisms. In version 1.2, the main window is now resizable and supports more than 32K of word-wrapped text in an arbitrary font and size. This version also adds support for logging a session to a file and for simple macros. Macros can be used to automate the login / logout process or to perform a fixed set of operations when a key is pressed.
Connecting to a MUD
-------------------
MUDDweller allows you to connect to a MUD, just like Telnet or other terminal emulators allow you to connect to a host. You can choose between using the communication toolbox or directly accessing the MUD with TCP/IP (using the MacTCP driver). The communication toolbox is part of System 7.0 and is available as an add-on for System 6.0.5 and later. You will also need a connection tool, such as e.g. the serial tool. A set of such tools offering basic communication capabilities is available from Apple. MacTCP is also available from Apple and is distributed with several third-party products.
Of course, you will need to know the address of a MUD before you can connect to it. A fairly complete list of MUDs is posted regularly to the reg.games.mud.announce newsgroup. When using MacTCP, all you have to do is to set the desired address and port number in the "TCP/IP Address…" dialog box and open the connection. When using the communication toolbox, the procedure will vary depending on your setup.
The main window is split into two parts. Most of the window is taken by the session log, which shows the output from the MUD and the result of your commands. At the bottom of the window there is an editable text field, separated from the rest by a double line. This is where you type and edit your commands. The input field can be resized by dragging the separation line with the mouse.
MUDDweller is line-oriented, i.e. you type and edit a line of text locally and then send the whole line at once to the MUD (by pressing "return" or "enter"). A command history is associated with each sesion. You can navigate through your last commands by pressing the UpArrow and DownArrow keys. If you edit one of the old commands and then press "return", the edited version will be sent and stored as the last command, but the history itself will not be modified. When the same command is sent more than once, it is remembered only once. Empty lines are not stored in the history at all.
"Send Break" is only enabled when using the communication toolbox. It can be used to send a break signal. The exact meaning of this signal depends on the connection tool used. With some tools, this command will have no effect on the connection. "Send File" sends the contents of any text file, as if it had been typed by the user.
Configuration
-------------
If you have the communication toolbox installed and a connection tool is available, you will be able to "Use Comm Toolbox" and then to choose and configure a connection tool with "Configure Tool". If MacTCP is installed, you will also be able to "Use MacTCP". This will respectively switch to the communication toolbox or the MacTCP driver respectively. The connection is configured either with the "Connection…" or the "TCP/IP Address…" menu items.
The "Preferences…" dialog box allows you to set your name and password (mainly used for file transfers, but also available to macros), as well as the font and text size of the main window, the maximum amount of text and commands to buffer and the creator type for log files.
In the "Comunication…" dialog you can define how carriage returns and linefeeds are handled, as well as the filters to use. The default values work well for direct TCP/IP connections. When using the communication toolbox it will usually be necessary to uncheck the "Local Echo" check box and to send only CRs at the end of a line.
The "File Transfers…" and "Macros…" menu items allow you to configure the file transfer options and to edit macros respectively. More informations on these features follow in the next sections.
File transfers
--------------
An important feature for LPmud wizards ist the support for MTP and ed-based file-transfers. MTP (Mud Transfer Protocol or Mini Transmission Patchwork) is a file-transfer protocol designed specifically for LPmud by Mentar of TUBMUD. It is available only if you are using the MacTCP driver. The MTP server is expected to be on the same machine as the MUD you are connected to. Of course, you must also be wizard on this MUD, or you won't be able to connect to the server. Instead of using the MTP protocol, it is also possible to have files transferred by sending an appropriate series of ed commands. This assumes that your mud has a fairly standard version of ed.
Before doing any file transfers with the MTP protocol, you should set the MTP port in the "TCP/IP Address…" dialog, as well as your name and password (in the "Preferences…" dialog). The program assumes that the MTP server is on the same machine as the MUD. Before using the commands "Update" or "Full Update", you should also tell MUDDweller where the local copies of your MUD files are located ("File Transfers…" dialog). The default value of the update folder is the directory in which the program is located.
The commands "Update" and "Full Update" automatically upload all or part of the files contained in the upload directory and its subdirectories. "Update" only sends files which are either new or which have been modified since the last update. A list of the files that have been updated, together with the corresponding modification dates is kept in the document. When updating, it is possible to stop the operation either by pressing Command-"." or by clicking on the "Stop" button.
Be sure that the upload folder is not accidentally set to the root of your harddisk or any other large directory, because the program will try to upload all its contents the next time you issue the "Update" command. Also, the local files must be organized in the exact same manner as the files on the MUD, with the same file names and the same directory structure.
"Upload" and "Download" can be used to transfer single files. With these commands it is also possible to specify the MUD filename explicitly. The list of updated files is not modified by the "Upload" command. If the option "Send 'update <filename>' after upload" is checked, the command "update <filename>" will be sent to the MUD each time a file ending with ".c" is uploaded.
Macros
------
Macros are a simple, but powerful feature, which allows simple tasks, like logging into or out of a MUD to be automated. In addition to the login and logout macros, which are invoked automatically when opening and closing the connection, further macros can be assigned to any combination of the shift, option and control keys together with a typing key. As an example for the use of this feature, the keys of a numeric keypad can be programmed to generate movement commands, allowing you to move around the MUD with the keypad.
Macros can be activated whenever the connection is open and do not disturb text that is being edited in the input field. They consist of one of more lines of text, with one command per line. Empty lines are skipped and lines beginning with a "#" character are treated as comments. All commands are executed sequentially, until the macro terminates or the user presses Command-"." to stop its execution.
Each command line consists of a command name, possibly followed with some parameters. The command names are not case sensitive. A very limited form of variable substitution is available: The strings "$n" and "$p" are replaced by your name and password repectively (taken from the "Preferences…" dialog box). In order to generate a "$" character, you must either use the combination "$$", or "\$".
Special characters can be generated in combination with the backslash character ("\"). "\b" generates a backspace, "\t" a tab character, "\n" a newline (its exact value depends on the "Communication…" settings), and "\f" a form feed. Arbitrary character codes can be generated with a backslash followed with one to three octal digits (e.g. \3 for Ctl-C).
The following macro commands are implemented:
SEND <text to send>
This command sends the rest of the line to the MUD. It does not automatically send a carriage return at the end of the text, however, so this has to be included in the text (e.g. "SEND quit\n"). Please note also that leading spaces are discarded. In order to include leading spaces, they have to be escaped with a backslash character (e.g. "SEND \ <- space\n"). Trailing spaces are not discarded, however.
ECHO <text to echo>
This command is very similar to send, except that the text is not sent to the MUD, but only echoed in the main window. This command also works while in QUIET mode (see below) and can be used e.g. for progress reports.
WAIT <number of seconds to wait>
The execution of the macro pauses for the number of seconds specified.
MATCH <text to match>
This command causes the program to wait until the specified text has been received. This has to be an exact match. Wilcards are not supported. The same considerations as for the SEND command apply with respect to the text to be matchedd.
QUIET [ON|OFF]
QUIET, or QUIET ON stops all MUD output from being displayed in the main window, except the output of ECHO commands, which is always displayed. The program returns to normal operation after a QUIET OFF command, or at the end of the macro. This command can be useful during login to discard unnecessary messages and to hide login names and passwords.
PASSWD [<password request>]
This command prompts the user for a password and then sends it, followed by a newline. This makes it possible to automate most of the login process, while still asking the user for passwords instead of storing them in the document. Using the PASSWD command (instead of typing the password in the input field) also has the advantage that the password is not echoed and that it is not stored in the command history.
Misc. Features
--------------
If you want to open a document without also opening the connection (e.g. if a MUD has moved), press the option key while selecting the document or while double-clicking it in the Finder.
If you press the option key while opening the application (not a document), the program will ask for a document to open instead of creating a new untitled one.
In dialog boxes, key equivalents are available for most buttons.
The PageUp, PageDown, Home and End keys can be used to scroll the main window.
Carriage returns can be inserted in the input field with Option-Return. Similarly, Option-UpArrow and Option-DownArrow move around the input field instead of switching to a different entry in the command history.
The execution of macros and the update process can be interrupted with Command-".".
Macros can also be assigned to typing keys. This allows you for example to assign a macro to the combination Ctl-C that actually sends this character code to the host (because of this new possibility, the "Send Interrupt" command is no longer available).
Troubleshooting
---------------
Some features of MUDDweller may be misleading. Here are the answers to some possible problems:
The program asks for the comm toolbox or MacTCP:
The communication toolbox is included in System 7.0 or later, but the communication tools, which do the actual work, are not. If you are using the CTB, you will have to install a tool for the communication mechanism you will be using. A set of basic tools (e.g. serial or modem connections) is available from Apple. More tools are also available from the main archive servers.
The connection is not opened at startup:
Save the document after having successfully opened a connection. The connection is not opened automatically for new documents, as the program assumes that they are not yet correctly configured.
The specified host can not be found:
Beware of spaces in the host name field. This field is sent as is to the name resolver.
The window does not remember its location:
The location of the main window and of the separator is saved only explicitly, together with the other document information.
When typing a password, spaces appear as spaces and not as bullets:
Sorry, this is a known bug.
The program beeps when I try to execute a macro or enter a command:
Macros can only be executed and commands can only be sent when the connection is open.
When connecting to a MUD (or a unix account), I can enter my name and password, but the password is rejected:
Try to let the program generate only a single CR or LF instead of a CR+LF combination. When using the communication toolbox, additional LFs may be generated, which are then included (erroneously) as part of the password.
After resizing the window, the scroll bar behaves somewhat erratically:
This is due to the fact that MUDDweller does not recalculate all line breaks after the window has been resized or the font changed. This dramatically improves response time when resizing the window, especially on slow machines. However, when scrolling the text, additional areas have to be recalculated, which may cause the text length to change and therefore the scroll bars to move in an unanticipated manner. This is especially the case when switching from a very wide window to a very narrow one.
