Fresh Fish 8/FreshFishVol8-CD1.bin/new/game/role/amigamud/client/doc/mud.txt

Text File | 1994-07-31 | 49KB | 1,064 lines

AmigaMUD, Copyright 1994 by Chris Gray


            The 'MUD' Client Program

The MUD client program (the file called "MUD") is used to connect to
an AmigaMUD server, either locally on the same machine as the server,
or remotely through a direct serial port or modem connection. The
operation of the program is the same in both cases, although some
details of starting it up vary. This client program must be used in
order to get graphics and audio output and to use mouse and keypad
input. This is the recommended interface for use with AmigaMUD,
although a remote user can operate in a simple text-only mode using
just a terminal program.

When running, MUD displays two windows. The top window displays 32
colour graphics in a 320 by 100 window centered in the display. The
bottom window displays text in a window sized to use up the remainder
of the available display space. It will be wider if overscan is in use
and it is higher on PAL systems. The text window has a scrollbar for
reviewing earlier output, and it is this window that contains the
menus. This means that the menus appear in the middle of the display,
which is a little unusual.

The bottom line of the text window is the input area. Output text
lines appear on the line above this one, thus any partial input lines
are not disturbed by output from other events taking place in the MUD.
Input line editing and history retrieval is done in this line and will
be described later. When RETURN is pressed, the current input line is
sent to the server, and is echoed (along with the current prompt) in
the output area. Note that the position of the command in the output
area does not necessarily correspond to the point at which the server
will process it, since the server may not get around to it for a
while, and because the server may already have generated other output
that hasn't arrived yet.

MUD can be started either from the Workbench or from a CLI. All of the
tool type values that can be put in the Workbench icon can also be
given on a CLI command line. Additional, shorter, forms for many of
the flags can also be used from a CLI. By default, MUD will attempt to
make a remote connection on the standard serial port at a speed of
19200 bps. If the environment variable "MUDLOCAL" is set to any of
YES/yes/ON/on/TRUE/true or to no value, then the default action is to
connect to a server running on the local machine.

NOTE: in order to run MUD, either locally or remotely, there must be a
copy of "mud.library" in your LIBS: directory.

NOTE: MUD requires a stack of at least 10000 bytes. It will exit right
away if the stack is not at least that large. If you are running MUD
from a shell, use the 'Stack' command (perhaps in your shell-startup)
to set a sufficient stack size. If you are running MUD from the
Workbench, use the "Icons"/"Information" Workbench menu item to set
the stack size on the MUD icon to at least 10000.

MUD is able to call up an external editor to edit strings (such as
character and room descriptions) and procs (AmigaMUD procedures). What
program to run as the editor can be controlled by setting the "EDITOR"
environment variable to the name (or a full path to) the editor to
use. If the variable is not set, "Ed" is used. The editor used must
accept the name of the text file to edit on the CLI command line, and
must be a able to edit and write a simple text file. MUD does not
understand text processor or word processor documents. Many users will
prefer to just use the simple editor built-in to the MUD program.

The MUD client program can display background pictures and brush
images loaded from the machine it is running on. It can also play
sound samples, and, in the future, will be able to play SMUS (and
perhaps CMUS) music. A single assign or volume name of "AmigaMUD:"
must be present when MUD is started. It does not need to contain
anything, but if it does, it should be arranged into the following
subdirectories:

    BackGrounds: 320 x 100 x 32 colour background images
    Images: 32 colour images of various sizes
    Brushes: smaller brush images with a mask plane or with a
    transparent colour specified
    Sounds: IFF 8SVX sound samples
    Music: IFF SMUS music scores
    Instruments: IFF 8SVX instruments

The text window in MUD has a close box. Clicking on this box will
start an exit sequence, which will normally result in MUD exiting.
This can also be done with a menu selection. If MUD is started from a
shell, using the 'Break' command on its process will also cause it to
exit. If MUD refuses to exit for some reason (such as the server
having been aborted, or the serial connection being lost), then MUD
can be exited with the Abort menu item. Using a 'Break f' shell
command will also cause MUD to abort. Note that you should not abort
unless absolutely necessary, since this can confuse the server if it
is still active. In particular, manual intervention on the server will
be required before you can log on again.

Following sections of this document will cover the CLI command line
and icon tool type flags in more detail. Others will cover the use of
the menus in MUD and the use of the internal editor. After that will
be a discussion of the the various types of caching done by the
program.


Using MUD to Connect to an AmigaMUD Server

When connecting to a server running on the same machine as MUD, the
connection is direct and immediate. The prompt to enter a character
name will appear right away, and the text window will be used only for
MUD input and output.

When connecting via a serial port (with or without a modem), the text
window will initially play the role of a very simple terminal program.
This mode has no emulations, does not support any escape sequences,
etc. You can, however, use the logging facility to do the equivalent
of "ASCII capture". The "Serial" menu can also be used to change the
CD (Carrier Detect) status, change the connection speed, and generate
BREAK conditions. When in this "terminal mode", characters typed are
not locally echoed (full duplex), and no special processing or
translation is done on sent or received carriage return or linefeed
characters.

When remotely connected, the MUD program on the remote machine uses a
reliable bidirectional binary protocol to talk to a copy of the
"MUDAgent" program running on the server machine. This means that
information (messages) can be sent in both directions at the same
time, and that messages are not limited to printable characters. Also,
the programs will automatically retry messages that are not
acknowledged by the other end.

This protocol operates quite differently than the simple "terminal
mode", so the programs must recognize and agree on when they switch to
the protocol. Normally, the MUDAgent on the server will attempt to
enter the protocol as soon as it is started up (e.g. as a result of a
menu option entered on a BBS). When the local MUD program recognizes
the special sequence sent out, it will display "REMOTE END DETECTED"
and switch into the protocol mode. If this message is not seen when
expected, then something is wrong in the connection. You may see the
data lights on a modem blink at one-second intervals - this is the
remote end resending its startup characters. If, however, the remote
end is setup to allow either a full binary or a text-only connection,
then it will not try to start the protocol until it sees a request.
In that case, you must use the 'Serial/Connect' menu item to start the
protocol from your end. If you don't know how the other end is set up,
just wait a few seconds to see if MUD connects automatically. If it
doesn't, then force the connection.

Because of the binary protocol, a serial connection for MUD must be an
8-bit no-parity connection. Other modes will not work, and will most
likely result in either a failure to connect, or a hung connection. In
that case, you must disconnect by exiting MUD, and try again with a
proper connection.

In the most common case, that of using MUD to connect to an AmigaMUD
server running elsewhere, the sequence of operations goes something
like this:

    - start MUD, possibly specifying options to change the baud rate,
    use a different serial po