The Cup-O MUD Client (v1.3)

Written by Alex Stewart (Richelieu) <>

in conjunction with

The Diversity University Technology Development Center

(This document requires HTML-3.0 table support)


  • What is Cup-O MUD?
  • Features of the Cup-O MUD client
  • Starting and Using the Cup-O MUD Applet
  • Integrating the Applet within a web page
  • Applet parameters
  • TELNET negotiation
  • MCP requests
  • footnotes

  • What is Cup-O MUD?

    The Cup-O MUD client is a fully functional client for Multi-User Virtual Environments (MUVEs, aka MUDs, MU*s, MOOs, etc), and other line-based text communication systems, written in the Java programming language.

    What this means is that you can now embed an active, real-time connection to a MUVE directly into a web page, allowing the user to not only interact with the system using their web browser, but also have most of the essential features most users of modern MUVE clients simply cannot live without (separate input/output windows, backscroll, command-recall, and more), all without the user having to download or install a single piece of software.

    The design goals of Cup-O MUD were as follows:

    Users of Cup-O MUD may also notice one other design consideration in its development. The Cup-O MUD interface has been specifically designed to be simple and clean, without lots of buttons or graphics taking up space on the screen which could be used instead for useful output window area. The result is an applet which, while perhaps looking a little less flashy, provides the optimum usability in a wide range of applications.

    Features of the Cup-O MUD client

    Currently supported features

    *: Cut and paste currently available only through implementation-specific built-in support in Java. May not be available or may work differently on different platforms.

    Planned for the near future (roughly in order)

    Starting and Using the Cup-O MUD Applet

    Due to the way Java applets work, in order for the Cup-O MUD applet to be used it must first be embedded in a web page located on the MUVE's host. See Integrating the Applet within a web page for more information on this. Once this has been done however, from a user's perspective encountering the web page in question, using the Cup-O MUD client is fairly straightforward.

    The Cup-O MUD user interface

    The Cup-O MUD applet has two main components to its user interface. A large output window comprises most of the applet's area, and is where text received from the MUVE is displayed. This output window also has a vertical scrollbar which can be used to scroll back through previous lines of output. At the bottom of the output window is an input field, where commands for the MUVE can be typed.

    Connecting to the MUVE

    When the web page containing the Cup-O MUD applet is loaded by the web browser, Cup-O MUD automatically starts by attempting to open a connection to the MUVE specified in its configuration parameters. While Cup-O MUD is attempting to connect to the MUVE, the input field has a grayed-out background and will not accept input, indicating that Cup-O MUD is not yet connected. As soon as the connection is established, the input field will change to the normal color and begin accepting input, and Cup-O MUD will begin displaying output from the MUVE in the output window.

    Cup-O MUD stays connected to the MUVE until either the connection is closed by the other end or the applet is destroyed. It is important to note here the use of the term "destroyed". Simply viewing another web page with the web browser will not close Cup-O MUD's connection. In fact, it is possible to go off and look at other web resources, and then return to a still-active Cup-O MUD session simply by hitting the "back" button in the browser.

    So when does the applet actually get destroyed? This depends somewhat on the web browser being used. Under Netscape, the basic rule of thumb is that an applet remains active as long as its page is in the "Go" list of the browser (the list shown when the "Go" pulldown menu is selected). The "Go" list basically just lists all of the web pages that can be gone back to using the "back" button (or forward to using the "forward" button). The best way to get a feel for this is to try out some things for yourself and see how they affect the "Go" list of the browser.

    In Netscape, if you back up (using the "back" button) and then go a different direction (by picking a different link), the "Go" list follows the new direction and discards anything which used to be "forward" of the current location. If the Cup-O MUD page happened to be one of those pages which was discarded from the "Go" list at this point, then the Cup-O MUD applet will be destroyed and will close its connection to the MUVE. This means that if, from the Cup-O MUD page you go "back" and then pick a new link, it will close the Cup-O MUD connection, which can be a handy way to close the Cup-O MUD applet if it should be necessary and isn't possible to do otherwise (such as quitting from the MUVE) for some reason.

    Communicating with the MUVE

    Once a connection to the MUVE has been opened, Cup-O MUD will begin displaying output from the MUVE in the output window and allow input in the input window. Under most circumstances, the input field will already be selected and will display a cursor. Sometimes, however, it may be necessary to click on the input field with the mouse in order to select it for entry. To send a command to the MUVE, simply type the command in the input window, and press the Return key. The typed line will be sent to the MUVE, and any results of the command will appear in the output window.

    While entering text in the input field, all of the standard editing keys work as one might expect. The left and right arrows, home, end, insert, delete, and so forth can all be used to edit the text of the input line just as they might be used for any other similar text entry. Pressing the up and down arrows allows one to recall previously typed commands, which can then be edited and resent to the MUVE.

    Using the output window

    (yet to be written)

    Integrating the Applet within a web page

    Integrating the Cup-O MUD applet within a web page is fairly easy. It simply requires adding an <APPLET> block in the HTML file where you would like the applet to appear. The <APPLET> block has the following format:

        <APPLET CODEBASE=url CODE="CupOmud.class" HEIGHT=height WIDTH=width>
          <PARAM NAME=name VALUE=value>
          (other HTML which will be shown on non-Java browsers)

    The CODEBASE attribute specifies the URL of the location of the CupOmud.class file, and if not specified defaults to the same location as the web page. The CODE attribute is required and must be "CupOmud.class". The HEIGHT and WIDTH attributes are also required, and may either be specified in pixels (HEIGHT=100, for example) or in a percentage of the available screen area (HEIGHT=75%).

    Inside the <APPLET>...</APPLET> block are one or more <PARAM> tags, which specify configuration parameters for the Cup-O MUD applet. Each parameter has a name and a value, specified with the NAME and VALUE attributes of the <PARAM> tag. The only required parameter for the Cup-O MUD applet is the "port" parameter, which specifies what TCP/IP port the MUVE it is to connect to is running on. The HTML for this would look something like:

          <PARAM NAME="port" VALUE="8888">

    While the "port" parameter is the only required parameter for Cup-O MUD, there are also quite a few optional parameters which control everything from Cup-O MUD's appearance to how it talks to the MUVE which may be worth looking into for various applications. All of Cup-O MUD's recognized parameters are listed in the Applet Parameters section, along with the specifics of how the various types of values are represented.

    Some of the configuration options for the Cup-O MUD applet are actually issues of user preference more than anything else. While in some cases it may be acceptable simply to decide on a particular set of parameters for all users of a particular Cup-O MUD page, more sophisticated applications may wish to allow the user to store configuration options on the MUVE or a related system, and generate custom Cup-O MUD pages with user-specific parameter values depending on who is accessing the page (the specifics of how to accomplish this are left as an exercise for the reader :) ).

    One other useful feature of the <APPLET>...</APPLET> block is the ability to specify a segment of HTML code which will be displayed if the page is loaded with a web browser which doesn't support Java applets. In addition to <PARAM> tags, other HTML can be included between the <APPLET> and </APPLET> tags. This HTML will be ignored by any browser which recognizes <APPLET> tags, but any browser which doesn't recognize them will display the enclosed HTML as part of the document. This allows a construction like the following:

        <APPLET CODE="CupOmud.class" HEIGHT=100% WIDTH=100%>
          <PARAM NAME="port" VALUE="8888">
          <CENTER><B>If you were using a Java browser you would be
          seeing Cup-O MUD here!</B></CENTER>

    Preloading the applet

    A useful feature available with the Cup-O MUD client is the ability to "preload" the applet. This involves embedding the applet within a previous web page (such as an introduction page), causing it to be downloaded from the remote site while the user is reading the text of the other page, or entering information in a web form, or whatever, but without actually executing the client itself. This way, when the user does move on to the page which actually uses the applet, it is already downloaded and can be retrieved quickly from the browser's cache, reducing the percieved delay in starting up the applet.

    If the "preload" parameter is specified and true, the applet will be loaded, and all the appropriate files will be fetched, but the applet won't actually do anything. Since this will, of course, leave a big blank spot on the screen where the applet is supposed to be, it is reccomended that the HEIGHT and WIDTH be set to 0 or some other very small values so that the "fake" applet's area is effectively invisible.

    Determining the applet size

    When the Cup-O MUD applet starts up, one of the first things it does is to determine exactly what size the applet will be and how many text rows and columns the output window will support. This can be done one of two ways (or a combination of the two):

    By default, the applet's size is dictated by the HEIGHT and WIDTH attributes found in the <APPLET> tag. From this information, the applet calculates the size which the output window will occupy, and from this determines how many rows and columns it can contain at the given font.

    Alternately, the number of rows and/or columns for the output window can be specified by supplying "rows" and "cols" parameters to the applet via <PARAM> tags. If one or both of these is specified explicitly, the applet will take this value and from it determine how high and/or wide the output window must be to hold the specified number of rows/columns at the given font. From this it will determine how high and/or wide the applet must be, and resize the entire applet appropriately.

    Thus, if no "rows" or "cols" parameters are provided, the applet will be whatever size the HEIGHT and WIDTH in the <APPLET> tag specify, and will have whatever output window size that allows. If "rows" and "cols" are specified, the applet will have that many rows and columns in its output window, and will automatically be sized to be whatever size it needs to be for that to be true. If "rows" is specified but not "cols" the applet will be however high it must be to have the right number of text rows, and will be however wide the WIDTH attribute specifies. Likewise if "cols" is specified without "rows", it will be however wide it needs to be for that many columns and however high the HEIGHT attribute dictates.

    NOTE: While resizing the applet based on rows/cols theoretically should work (and may in future), Netscape (so far the only real Java-enabled browser) does not support resizing of applet areas on the page. This means that while the Cup-O MUD applet can resize all its components appropriately, it cannot change the area Netscape has allocated for it on the page with the HEIGHT and WIDTH elements. If the "rows" or "cols" parameters require resizing larger than the initial size of the applet, the applet will be clipped at the right/bottom edges. If they reduce the size of the applet there will be empty space at the right/bottom edges. If Netscape or someone else fixes this in future this applet will then work the way it was intended, but until then, people will have to live with it, I guess.

    Tweaking the applet size

    the Cup-O MUD applet also supports a couple of parameters for making fine adjustments on the applet's size. These are not generally terribly useful, and their presence in no way means that their use is encouraged, or will even have the same effect on all platforms, but they can be useful in some specialized applications.

    The "hcorrect" and "vcorrect" parameters are really only useful if you are specifying the applet's HEIGHT and WIDTH as percentage values (as Netscape allows one to do). These parameters specify a horizontal and vertical correction to apply to the applet's size, respectively. This allows one to effectively specify "70% + 20 pixels", or "100% - 5 pixels", to get somewhat finer control over the relationship between the size of the applet and the size of the surrounding frame. Each parameter consists of two integers, separated by a comma. The first is a percentage (without the trailing "%"), indicating how big (in percent) the initial size of the applet will be compared to the desired base-size for the correction). The second number is the correction (in pixels) to apply starting from the specified base.

    Thus, for example, if you wished to specify a height of "100% + 10 pixels", you might set the HEIGHT in the <APPLET> tag to "120%", and give a "vcorrect" parameter of "120,10". On the other hand, if you wanted to specify a height of "70% + 10 pixels", you might specify a HEIGHT of "100%" and a vcorrect of "142,10" (because 100 is 142% of 70). To specify "100% - 10 pixels", you might specify a HEIGHT of "100%" and a vcorrect of "100,-10".

    As mentioned, this correction mechanism was developed for a specific application and probably will not be terribly useful for most uses of this applet. If you need to use it, you will know when.

    Applet Parameters

    Parameters to the Cup-O MUD client are specified using <PARAM NAME="name" VALUE="value"> tags within the <APPLET> ... </APPLET> block).

    The representation of string and numeric values is fairly obvious.

    Boolean values can be specified in a number of forms: Values of "yes", "y", "true", "on", or "1" (any case) are considered to be true-values. Everything else (note: including other nonzero numbers) is considered to be false. Therefore, the following are resonable ways to specify true/false:

    Font specifications have the form "name[-style][.size]" ([] indicates optional portions), where name is the font name (such as "Courier"), style is the font style (one of "Bold", "Italic", or "BoldItalic", the default is plain), and size is a number indicating point size (default is 10); for example, "Courier-Bold.12".

    Colors are specified using the same syntax as Netscape uses for background/foreground colors in its tag, specifically a sequence of 6 hexidecimal digits, representing the red (00-FF), green (00-FF), and blue (00-FF) components of the color, in order, thus:

    Color values can optionally be prefixed with "0x" (the standard C prefix indicating a hex number), but this is not required.

    Correction values (used for the "hcorrect" and "vcorrect" parameters) consist of two integral numbers, separated by a comma. The first number is a percentage (without the trailing "%"), specifying the size of the applet relative to a base size for the correction, and the second is an offset in pixels from the base size to find the desired ultimate size. (see above for more information)

    The Cup-O MUD client applet currently supports the following parameters:

    Required Parameters
    Name Type Meaning
    port number TCP port to connect to on the remote system's host
    Optional Parameters
    Name Type Default Value Meaning
    backscroll number 12288 (12K) The size (in bytes) of the backscroll (output history) buffer
    bgcolor color specification system default Color to use for the background of the unused applet space (generally not seen, but see note above).
    cols number (determined by applet size) Number of columns in output window
    command string (disabled) Command to send upon connecting
    echo string (disabled) Echo input commands with this prefix
    font font specification "Courier.12" A font specifier indicating the fontname, style, and point size to use for text in the input and output windows
    hcorrect correction (no correction) The size correction to apply to the applet's initial horizontal size (width)
    host hostname/IP Applet host Address of host to connect to (this usually must be the same host as the one on which the applet's class file resides)
    input_bgcolor color specification system default Color to use for the background of the input field.
    input_fgcolor color specification system default Color to use for the foreground of the input field.
    MCP boolean false Respond to MCP requests?
    MCPauth boolean false Require authenticated MCP negotiations? (if this is enabled, any MCP commands sent before an authentication key has been established will be ignored)
    output_bgcolor color specification system default Color to use for the background of the output window.
    output_fgcolor color specification system default Color to use for the foreground of the output window.
    preload boolean false If true, applet will only load, not execute.
    recall number 20 The number of previous commands to keep in the command-recall buffer
    rows number (determined by applet size) Number of rows (lines) in output window
    sysname string "host:port" Name of system being connected to (used in status messages)
    TelnetEcho boolean true Respect TELNET requests to disable/enable input echoing?
    URLtarget string applet's window Default frame/window for MCP display-url requests
    vcorrect correction (no correction) The size correction to apply to the applet's initial vertical size (height)
    waitfor string (disabled) Text to wait for from the remote system before displaying output lines

    TELNET Negotiation

    The Cup-O MUD client is compatible with the TELNET (RFC-854 et al.) protocol specification and will negotiate with TELNET-aware servers in a limited fashion.

    Please note that the telnet options supported by the client are only a very very small subset of those normally used by most telnet programs, and are basically only those which make sense for a line-based MUVE client application. The Cup-O MUD client is nowhere near a full telnet client, and will probably not work for most applications designed for one. It is, however, compliant with the official TELNET specification, and will respond to unsupported telnet options appropriately, as specified by the protocol.

    The Cup-O MUD client currently supports the following TELNET options:

    TELNET Options/Escapes
    Sequence Meaning Result
    IAC WILL ECHO* Request by server to echo client's input characters remotely [RFC-857] (As only line-mode input is supported, this is interpreted as a request to start password-input mode)
    Input area changed to password-style (input echoed as asterisks onscreen). Echoing of commands in output window temporarily disabled.
    IAC WONT ECHO* Request by server to echo client's input characters locally [RFC-857] (Interpreted as a request to end password-input mode)
    Input area and command-echoing set to normal.
    IAC IAC Escaped IAC code (character 255) Character 255 passed through to output window (NOTE: screen representation for codes above 126 may be platform-specific and/or undefined).

    *: WILL/WONT ECHO options require TelnetEcho=true.

    All Unrecognized WILL/DO option requests from the server are responded to with a negative (WONT or DONT) response by the client, as per the RFC-854 specification. Unrecognized WONT/DONT requests and other unrecognized escape sequences are ignored.

    MCP Requests

    The Cup-O MUD client supports MOO Client Protocol (version 1.0) requests if the "MCP" parameter is enabled. MCP requests consist of lines sent to/from the remote system of the following form:

      #$#request-name [authentication-key] [key: value] [key: value] ...

    Where items enclosed in [] are optional, and:

    specifies the type of MCP request.
    is a secret code shared between the client and server used to ensure the legitimacy of the MCP request.
    key/value pairs
    specify the data for the specific requests.
    consist of either
    1. A string of printing ASCII characters, not including space or quote characters, or
    2. A string of printing ASCII characters and spaces, enclosed in quotes, with quote characters and backslashes escaped by prefixing them with backslashes.

    For example:

      #$#display-url 12345678 url: "" target: my-frame

    The Cup-O MUD client currently supports the following MCP requests from the server:

    MCP Requests Received from Server
    Request Description
    mcp Initial MCP negotiation initiation. Responds by sending an "authentication-key" MCP response, followed by status information.
    Optional elements:
    version string Version of MCP supported. This is currently ignored by this client.
    display-url Display a WWW resource provided as a URL
    Required elements:
    url URL URL to display
    Optional elements:
    target* string Name of frame in which to display it

    The Cup-O MUD client currently will send the following MCP requests to the server under appropriate circumstances:

    MCP Requests Sent to Server
    Request Sent on Description
    authentication-key startup Sent to establish an authentication-key for security.
    (no MCP-style (key/value) data is provided, but the authentication-key portion of the request contains the new authentication key)
    window-info* startup or change Provides information on the current window width and height (in characters), and related parameters.
    Element Value Description
    rows number Number of rows (lines) in the output window.
    cols number Number of columns in the output window.
    wrap "local" or "remote" Whether word-wrapping at the end of lines is handled locally (by this client) or should be done remotely (by the server). This is always "local" for the Cup-O MUD client.
    page "local" or "remote" Whether output-paging/backscroll is handled locally (by this client) or should be done remotely (by the server). This is currently always "local" for the Cup-O MUD client.

    *: Not part of the standard MCP specification (what there is of one).


    What is a MUVE?

    ...or "A MUD by Any Other Name"

    MUVE stands for Multi-User Virtual Environment. It is a fairly recent term in growing use in many areas to refer to a whole plethora of variants on a common theme of interactive servers on the Internet today. Many people are familiar with various forms of interactive communication available on the net. Some have used programs such as 'talk' to communicate with others over the net, many others are familiar with "chat rooms" on commercial services, or Internet Relay Chat (IRC) which allows multiple people to communicate with each other at the same time, anywhere in the world. While IRC has gotten the most amount of attention in this area for a very long time, MUVEs have served as a less well known but nonetheless plentiful and diverse method of communicating and sharing ideas for hundreds of thousands of people all over the world and across the net, providing a great deal of flexibility and creativity in expression and interaction, unobtainable with most other forms of communication.

    But what actually is it? Well, for a (somewhat) brief summary of a very long story, we start by going back to the very beginnings of computer networks, actually back to the very beginnings of computers as most people know them altogether. Way way back in computer history, back when people communicated with computers using things which looked more like typewriters than terminals, a few enterprising individuals came up with something which would be the father of many thousands of software programs after it, and shape forever the way people looked at computers. It was a game. It was the first ever text adventure game. It was called, simply, "Adventure".

    In the game of "Adventure", the computer took on the role of a person navigating in a fictional world with puzzles and traps, and treasures and tools. The player of the game would type in instructions about what the computer was to do with objects in the game, and the computer would tell the user what happened, give descriptions of what things looked like, and so forth. Though the vocabulary was rather limited, the user communicated with the computer using basic english commands ("get torch", for example), and the computer would respond with english sentences and descriptions. It was a novel approach to interacting with a computer, and for many, a fascinating one, so much so that to date even the newest games and other computer systems still use aspects of it in their everyday operation, and it is still possible to find versions of the original Adventure game (not to mention the countless derivatives developed since) available for nearly every form of computer ever in existence.

    Well, needless to say that shortly after computers started getting big enough and powerful enough to support a bunch of people on the same computer at the same time, before people had even really started to think of actual communication using computers, let alone email, or networks, or chat programs, someone, as someone always was, was thinking about Adventure, and more importantly, was thinking how really neat it would be if a bunch of people could play the same Adventure game at the same time. So, as someone always did in those days, they decided to make it happen, and, well, it did. The first attempts were rather clumsy, as computers were never designed with this type of thing in mind, many of the "techniques" used to achieve this were very messy indeed, but they did work, and as time progressed, and computers got more sophisticated, things worked a lot better, and soon what they ended up with, while not quite Adventure anymore, was certainly something. From the simple beginnings of Adventure, adding many more aspects from role playing games such as Dungeons and Dragons, with the ability for multiple people to be in the same game and work with each other (or against each other) in a shared, completely fictional environment, it was something somehow more than just a game anymore -- The first Multi-User Dungeons had been born.

    At about this point, the first large-scale computer networks were being developed, and along with nearly everything else in this area, the development of MUDs exploded as a result. Before long, people on completely different college campuses were all hacking at monsters, discovering treasures, having a great deal of fun, and moreover, actually talking to one another in these worlds inside the computers.

    The Internet grew larger, and the world grew smaller. Many battles were fought in the virtual "dungeons" (and many social-lives were lost). Many people made many advances in the way MUDs worked, and the way they could be used. There was born the DikuMUD, the TinyMUD, the LPMUD, MUSEs, MUSHes, MUCKs, MOOs, and many others. The worlds became more elaborate, and it became possible to program sophisticated actions, and reactions, and commands, and entire system designs, all from within the virtual worlds themselves, changing the reality itself as one was inside it.

    Of course, not everyone was terribly happy about this. These were, after all, only games. They were huge, addictive, frivolous games which used up more and more computer resources which should've been being used for "real" work, or so many people saw them. Many system administrators (understandably) frowned on the use of MUDs. Some actively prohibited their use. In many circles, "MUD" became a four-letter word.

    But there were other people who were beginning to see something else in MUDs. These weren't really merely game programs anymore, many had evolved into sophisticated and flexible environments, full of objects and rooms and people who could be anything anyone wanted them to be, could interact however someone programmed them to act. The only thing which made a MUD a game was how the scenery was described, scenery which could just as easily be a social environment, or a research laboratory, or a classroom. And, as time went on, some of the scenery changed...

    Today, MUD-type systems are used for social communities, scientific forums, educational environments, process control systems, business conferencing systems, and nearly anything else people have come up with. Many MUD servers have been adapted to work with graphical web interfaces, and even 3D VR perspectives. Artificially intelligent "bots", both from outside and programmed directly into MUDs interact with users and with the environments, while users can build and shape their environments, and most importantly, share information, ideas, resources, and communities online, from thousands or millions of miles away.

    But still, after many years of "Multi-User Dungeons", many people still see MUDs as nothing more than games, frivolous, trivial, not something that should be supported or allowed. Some people still won't even consider allowing access to anything called a "MUD" from their system, and many others are denied many of the great resources now available as a result. Some people are working to remedy this problem (some people have been working for a long time). Ask many people nowadays what "MUD" means and they'll tell you "Multi-User Dimension", or "Multi-User Domain", but in the end, it usually comes back to "just a MUD". Just a game.

    For this reason, a growing number of people have stopped calling them MUDs altogether, in favor of other acronyms with less of a stigma attached. Many people call them "MOOs", mainly because the MOO server is a variety of MUD server which is used more than most others for the more "respectable" applications. This has a tendency to exclude some other types of systems which are equally valid, however. In an attempt to avoid this, an entirely new name is gaining acceptance, to include all manner of MUD-like systems without stigmas or prejudices, and suggest some of the true versatility and power these "Multi-User Virtual Environments" have come to provide.

    And this is the story of the MUVEs, and how they came to be, a powerful and flexible family of systems with a long history of being at the forefront of evolving computer technologies and human desires. A continuing history, full of even greater promise for the road ahead.

    Last updated on August 25, 1996 by Alex Stewart <>