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 port, etc. - using MUD as a terminal program, dial the remote machine and log on to it as normal. - do any further operations with the remote system as needed, such as using BBS menus to get to an AmigaMUD selection. - instruct the remote system to run MUDAgent (e.g. select the appropriate BBS menu item). - you should see some modem activity, followed by the "REMOTE END DETECTED" message, then some more modem activity, and the prompt to enter a character name. - enter your character name and start playing AmigaMUD The MUDAgent program is able to monitor a serial port and make connections itself. If the host machine is operating this way, then when the initial modem connection is made, MUDAgent will immediately connect with your MUD client. MUDAgent can also be started by the "Getty" program, in which case you will see a "login:" prompt when you connect. At that point, enter the "userid" that is used on that system to get to AmigaMUD. You may have to enter a password other than your character password to get into AmigaMUD. AmigaMUD also supports simple text-only connections. If you connect to one of these by, e.g. using the wrong BBS menu selection, then your MUD client and the MUDAgent program will not enter into the reliable protocol. You will not see the "REMOTE END DETECTED" message and will not get graphics/sound output and will not be able to use the normal features of the MUD program; instead, you will only have the "terminal mode" capabilities. Unless you will only be on the MUD for a short period, it is best if you disconnect and reconnect properly. The MUD program supports Christopher Wichura's OwnDevUnit library for sharing of serial ports. This should be all automatic. If you are running something like 'Getty' or 'MUDAgent' to answer incoming calls, then MUD will request the port from that other program, and will fail to start up if that program does not release the port. If your system does not run OwnDevUnit.library, then this paragraph does not apply and can be ignored. The MUD client program does not actually exit when you leave the scenario if you are connecting remotely. Instead, it goes back into its "terminal mode", allowing you to do more connections in the one session. Note that it does NOT flush its cache of effects, so if you next connect to a different AmigaMUD, you should select the "Options/Caches/Zap Effects" menu item to empty the effects cache, since a given effect identifier is unlikely to mean the same thing on another AmigaMUD. (Actually, you are safe until I get the programming documentation done and others can add/change effects in the scenario.) MUD Icon Tool Types Some tool types accept a boolean (true/false) argument. MUD interprets any of YES/yes/ON/on/TRUE/true or an empty argument as true, and any other value as false. Note that on early versions of the AmigaOS, empty values are not valid. They ARE valid under V2.0. Other tool types require numeric arguments. These must be given in decimal. String arguments can have any value not containing spaces. SERIAL (boolean) - this tool type tells MUD to connect to a remote server over a serial port. This is the default action, unless environment variable "MUDLOCAL" has been set to a true value, in which case MUD will connect to a local server. In that case, this tool type will override that behaviour and attempt a serial connection. Using any of the serial-specific tool types will also imply the setting of this tool type. LOCAL (boolean) - this tool type tells MUD to connect to a server running on the local machine, rather than trying to connect to a remote server via a serial port. CLOSEWORKBENCH (boolean) - this tool type tells MUD to try to close the Workbench screen after it has started up. This will normally only work from a Workbench startup, and only if there are no other programs active that were started from the Workbench. Using this option can recover system memory for use in caching effects, images, sounds, etc. The Workbench can also be closed (and opened) using menu items. BRIGHT (boolean) - this tool type tells MUD to start up using a brighter than normal set of colours for the text window. This is useful on bright sunny days. DIM (boolean) - this tool type tells MUD to start up using a dimmer than normal set of colours for the text window. This is useful for nighttime MUDding. EDITOR = { INTERNAL | SELECTED | EXTERNAL } - this tool type sets the default setting for the similar menu item. If INTERNAL is set, then all editing will use the built-in editor. If SELECTED is set, then MUD will use the built-in editor for editing strings, and an external editor for editing procs. If EXTERNAL is set, then MUD will use an external editor for everything. OHISTORY (numeric) - this tool type sets the size of the output history buffer that MUD maintains. This is the text that can be reviewed using the scroll bar in the text output window. The minimum size is 1920 characters. Note that giving too large a value can result in significant slowdown, as new text is inserted at the end of a large buffer. The default value is 5000 characters. IHISTORY (numeric) - this tool type sets the size of the input history buffer that MUD maintains. This is the command lines that can be retrieved using the up-arrow key, in the same method that is used in a shell window. As described later, the shell's input editing functions can also be used. The default size of the input history buffer is 1024 characters, and the minimum size is 160 characters. PORTNAME (string) - this tool type allows the user to change the name of the Amiga OS port that MUD will try to connect to. By default, this name is "MUD port". Using a different name allows the simultaneous use of multiple AmigaMUDs on a given system. This tool type lets MUD select which one to connect to. TEST - this tool type is a short way of picking "MUD test port" as the name of the Amiga OS port to connect to. BAUD (numeric) - this tool type allows the setting of the baud rate (more properly called bps) to use for a connection on a serial port. The default value is 19200. Note that the Amiga's internal serial port can accept a wide range of values, but standard values of 300, 1200, 2400, 9600, 19200 or 38400 should be used for compatibility. If a value that does not appear on MUD's serial menu is used, then none of the speeds in the menu will be checked. IGNORECD (boolean) - this tool type tells MUD to ignore the state of the CD (Carrier Detect) serial port control signal. Normally, MUD will exit when the CD signal is lost, since this means that the modem connection has been lost. Setting this flag is needed with modems that cannot (or have been instructed to not) properly generate the signal, or with serial cables that do not pass the signal. Also, when connecting two Amigas directly via their serial ports (and a "null modem"), this option is usually needed. 7WIRE (boolean) - this tool type tells MUD to instruct the serial driver to pay attention to the hardware flow control signals on the serial port. This is recommended for use with direct connections or high-speed modems. It should not be used if the modem is not generating and paying attention to the signals, or if the connecting cable is not carrying the signals. SHARED (boolean) - this tool type tells MUD to open the serial port in "shared" mode. This means that other programs can have the port open at the same time. MUD (and the MUDAgent program at the other end) will become confused if any other program actually reads from or writes to the port while MUD is connected, so this flag should be used with care. RETRIES (numeric) - this tool type specifies the number of times that MUD should attempt to send or receive any given message via the serial port connection. The default value is 10. Larger values may be needed for reliable operation over noisy telephone lines. Too large a value should not be given, however, since then MUD won't give up soon enough on a true lost connection. DIAL (string) - this tool type allows the specification of a string to be sent over the serial port (usually to a modem) on startup. With most modems, a dial string of the form ATD1234567 will cause the modem to start dialing a telephone number. This is handy to set up an icon for MUD to connect to a specific remote AmigaMUD, or in a shell alias. NAME (string) - specify the name of the character to log in as. Note that this is an AmigaMUD login, not a BBS or other one. PASSWORD (string) - specify the password for your character. It is not recommended that you use this flag if your system is open to use by others, since they can find your password easily. If the password given this way is incorrect, it counts as the first of your three attempts at getting it right. DEVICE (string) - this tool type allows the specification of the name of an alternative serial device to use for a connection. The default name is "serial.device", which refers to the standard built-in serial port. UNIT (numeric) - this tool type allows the specification of a particular serial port unit on a device with several ports. The default value is 0. FLAGS (numeric) - this tool type is used to specify some special flag values which MUD passes on to "mud.library". The flag values only effect the operation of some caching mechanisms which are of value to wizards. The value is the sum of the following: 1 - cache procs. This remote client will cache the definitions (but not the bodies) of builtin and user procs in the AmigaMUD language. This saves refetching them when parsing procs (such as after editing one). 2 - cache symbols. This remote client will cache the values of symbols that it has fetched from the server. Again, this cuts down on communications when parsing AmigaMUD procs. Note that both of these flags increase the amount of memory consumed by MUD. This memory is not freed until MUD exits. The default value of 'FLAGS' is 0, i.e. both caches off. Examples: LOCAL=true PORTNAME=MUD2 OHISTORY=10000 This requests a connection on the local machine to a server running with Amiga OS port name "MUD2". An output history buffer of 10000 characters will be allocated and used. BAUD=9600 7WIRE DEVICE=siosbx.device UNIT=1 This requests a 9600 bps connection, using hardware flow control, on the second port of an ASDG dual-port board. MUD CLI Command Line Flags All of the above icon tool types can be given on a CLI command line, as in: MUD BAUD=2400 7WIRE IHISTORY=2000 DIAL=atd1234567 In addition, there are short forms for many of the flags and some additional flags that are only meaningful from a CLI command line. In these flags, any needed value must directly follow the flag letter, i.e. there must not be any spaces between them. More detailed descriptions of these settings can be found in the previous section on icon tool types. The flags supported are: -L - make a local connection -T - make a local connection using port "MUD test port" -B - use the bright text window colours -D - use the dim text window colours -F - set the mud.library flags - see FLAGS tool type -P - use the given name as the local port to connect to -S - do a serial connection with the port opened in shared mode -w - try to close the Workbench on startup -d - use the named device instead of "serial.device" -u - use the given device unit instead of unit 0 -b - use the given serial speed instead of 19200 -i - ignore the Carrier Detect serial signal -7 - use 7-wire hardware serial handshaking -N - use as the name of the character for the playing sessions, rather than prompting for a name -W - use as the password for the playing sessions. If it is incorrect, it counts as the first attempt, and only two attempts remain. This is normally used in conjunction with -N, but can be used without it. -r - retry each failing message the given number of times -E - this flag was useful to me when I was testing the sample online building sessions - it starts up MUD with its editing capability disabled, so that text must be entered in the line- by-line mode. An interesting combination is to combine a DIAL= with -N and -W. If the system you are calling is directly running MUDAgent for a binary connection, then the call will happen and you will end up being connected to your character, without having to do anything else. The following flags are included for compatibility with the "Getty" program. There is currently no real use for this support, but I believe that it may become desireable to have a terminal program which can call out to the MUD client program, much as Getty or BBS's call out to the MUDAgent program. This is because the terminal support in MUD is minimal, and the user may want to do other activities during a BBS connection which require more functionality. A terminal program which supports callouts in this manner could then be used to provide both levels of functionality in a given connection. Most people can ignore these flags, at least for now. See Getty documentation for details. The flags are: -Getty - supresses any port initialization, and opens shared -DEVICE - name of device to use -UNIT - unit number on device -HLINK - ignore carrier detect -BAUD - set connection speed -USER - parameter ignored Menus in MUD Some of the menu items in MUD have function key shortcuts. Others have right-amiga command key shortcuts. Both types of shortcuts will work regardless of which of the windows (graphics or text) is currently the active one. Most of the "Serial" menus will only work while in "terminal mode", and some others will not work in terminal mode. Inactive menus are shown ghosted. Key shortcuts for menu items are shown here inside square brackets. Project - the Project menu contains general utility operations. Log [F7] - this item will enable or disable logging of text input and output. If no logfile name has been selected when logging is turned on, one will be requested. Log File - allows selection of a file to log to. Logging will be turned on after the selection of a name. Source - a file name is requested, and the contents of the file is read and inserted as input from the user. This operation works in either "wizard" mode (the user is operating directly with the AmigaMUD interpreter) or in normal mode, where input is being parsed as commands for the scenario. SnapShot Text - a file name is requested, and the entire contents of the output history buffer is written to the file. Graphics - a file name is requested, and the current contents of the graphics window is written to the file as an IFF ILBM image. The current graphics palette is included in the IFF file. Quit [R-A Q] - MUD disconnects from the server and either exits, or goes back to the "terminal mode", depending on whether you are running the client locally or remotely. Using the close box on the text window has the same effect, unless you are currently editing something, in which case only the edit is aborted, as with typing a ^C. Abort - MUD exits immediately. This is useful if the server has hung, or something has gone wrong with the connection to it. Using this instead of 'Quit' may prevent you from reconnecting to your character until the server times out and shuts the connection down at its end. In some cases, manual intervention on the server may be required before you can connect to your character again. Modes - the Modes menu controls various parts of MUD that can be enabled and disabled, or which give a choice of behaviours. History - this item allows you to control which of your input lines is entered into the input history buffer. In 'Full' mode, all input lines are entered, regardless of how they were generated. In 'New' mode, input lines are entered only if they were not taken unchanged from the input history. In 'Minimal' mode, input lines are entered into the history only if they did not originate from that history, i.e. only if they were typed in completely. I recommend 'New' mode. Scroll On - this item allows you to control when the output window is scrolled. If 'Input' is chosen, then the output window scrolls only when a new input line is entered, or when it must be scrolled because it is full and an output line must be added. If 'Output' is chosen, then the output window is scrolled whenever a new line of output is added to the bottom. If 'Either' is chosen, then both input and output lines will cause the scrolling. If 'Neither' is chosen, then the output window does not scroll unless the user scrolls it or it is full. This last mode is useful when typing input lines based on output history that has already scrolled out of the text window. Editor - this item allows you to choose when to use the internal editor and when to use an external editor. If 'Internal' is chosen, then the internal editor is used for editing strings (such as descriptions) and when editing AmigaMUD functions when in wizard mode. If 'Selected' is chosen, then strings are edited with the internal editor and functions with an external one. If 'External' is chosen, then an external editor is used for everything. If you are not familiar with running a text editor such as 'Ed' on the Amiga, I recommend using 'Internal'. When editing AmigaMUD functions, the internal editor can move the cursor to the position of errors when the function is submitted for parsing. Some external editors support this kind of operation using ARexx commands, but MUD does not currently support this. Picture [F1] - this item controls whether or not the graphics window is visible. A full screen text window can be useful when wizarding or when chatting with a number of other players. Graphics [F2] - this items allows the user to disable all graphics operations in the MUD client. This setting is sent to the server, so it will not even send graphics output messages. Note that turning graphics off and then on again at a later time can result in an out-of-date or inconsistent graphics view. Sound [F3] - this item allows the user to disable all playing of sound samples. The setting is sent to the server so that it doesn't even send sound requests to the client. Music [F4] - this item allows the user to disable all playing of music scores. The setting is sent to the server so that it doesn't even send music requests to the client. Voice [F5] - this item allows the user to disable all speech output. The setting is sent to the server so that it doesn't even send voice requests to the client. Edit Win [F6] - this menu item is the only way to switch between the full-screen internal editor window and the normal split-screen playing view. The item is not enabled when nothing is being edited. By switching to the normal view when editing, you can continue to operate in the MUD, but this shouldn't be done long, since you might suddenly need to edit something else. Options - these menu items select some supplementary functions. ScreenToBack [R-A B] - this item sends the MUD client screens (the graphics and text windows) to the back of the stack of screen on your Amiga. Unless you are running other programs, this will just result in the normal Workbench screen coming to the front. It is useful during testing, however, since then there might be several MUD clients running on the same system as a server. Workbench - this items allows you to try to turn the Amiga's Workbench on and off. Turning the Workbench off is useful to conserve memory. The Workbench will not turn off if other applications are open on the Workbench screen. Caches - this item allows you to examine and manipulate the local caches of graphics and sound effects that the MUD client maintains. Free File - a single cached IFF file will be freed. This can be a background, brush or image, a sound sample, or a music score. The next time the selected file is needed, it will have to be reloaded from disk. The system will chose the least recently used file. Free Effect - free the single least recently used unreferenced effect. See a later section on 'Caches' for more details. Zap Effects - free all effects Show Status - show the status of all cached files and effects. This status is affected by requests coming from the server and by the above three menu items. See the 'Caches' section for more information. Memory - the amount of available chip and total memory is shown. This can be useful in understanding why effects aren't happening (lack of memory), and to get a feel for the amount of memory that the MUD client can consume. Serial - these items are mostly of use only during an initial "terminal mode" with a serial connection. IgnoreCD - controls whether or not MUD will expect a valid CD (Carrier Detect) signal. This hardware signal should be generated by a modem when it detects a carrier signal on the telephone line. If your modem does not do this, or if you have told it not to, or if your serial cable does not transmit the signal, you should instruct MUD to ignore the signal, else it will not think a connection has been made. Speed - provides a few manually-selectable speeds for use when in terminal mode. Other values can be entered from an icon tool type or a CLI command line. Break [R-A .] - requests that a break condition be sent over the serial line. This condition is a lengthy pause in the raw transmit data stream that is detectable at the other end of the line. You can see it as an "on" pulse in your modem's TX light. Connect [R-A C] - this item forces MUD to attempt to initiate a binary connection with the other end. If the other end is set up to only handle a binary connection, this will not be necessary, since the other end will start things up. If, however the other end is waiting to distinguish either a binary or a text-only connection, then this menu item is used to start up a binary connection. Stats [R-A S] - this item shows some statistics maintained by the serial protocol code: Packets TX: - total number of packets (messages) sent out from this end. ACKs TX: number of positive acknowledgements of correctly received packets that this end has sent. NAKs TX: number of negative acknowledgements of incorrectly received packets that this end has sent. Incorrectly received packets must be resent by the sender. Packets RX: total number of packets that this end has received. ACKs RX: number of positive acknowledgements received. NAKs RX: number of negative acknowledgements received. Waits timed out: MUD puts a time limit on any of its waits for receiving something over the serial port. This number indicated how many times that time limit went off. Normally, this means that a packet sent from this end was completely lost, so the other end didn't either ACK or NAK it. Read no bytes: indicates the number of times a serial port read request returned, but indicated that no bytes were received. This can happen if a BREAK condition is received. Writes failed: indicates the number of times that a serial port write request did not complete due to some error, such as a loss of carrier signal. History Manipulation and Input Line Editing MUD maintains two forms of history. One is a history of commands entered by the user, and the other is a history of both input lines and output text from the server. The output history is straightforward - it can be accessed by using the scroll bar on the right hand side of the text window. Also, pressing an ALT key and an up or down arrow key at the same time will scroll the output window a line at a time. Additionally pressing a shift key will scroll by a full window at a time. Input history and input line editing is very similar to that done in the standard shell, with some minor additions. The available operations are as follows: up-arrow - scroll backwards in the input history down-arrow - scroll forwards in the input history shift-up-arrow - search backwards in the input history for a line which matches the input text to the left of the cursor. If any is found, insert it into the input region in place of what was previously there. shift-down-arrow - move the current history search point to the end of the input history and clear the input region HELP, and numeric keypad keys - these are sent as is to the AmigaMUD server, where they can be used as desired by the currently running scenario right-arrow - move the cursor right one column left-arrow - move the cursor left one column shift-right-arrow - move the cursor to the end of the current input shift-left-arrow - move the cursor to the beginning of the input region cntl-A - move the cursor to the beginning of the input region cntl-B - move the cursor left one column cntl-E - move the cursor to the end of the current input cntl-F - move the cursor right one column cntl-H (backspace) - delete the character before the cursor cntl-I (tab) - move the cursor forward to the next 8 column boundary cntl-K - delete all characters from the one under the cursor to the end of the current input. The deleted characters are saved in the "undo buffer". cntl-M (carriage return) - send the current input to the server and clear the input region ready for another line. The line may be added to the input history, depending on the setting of the history choice, and on whether any editing of the line had been done. cntl-N - go forward one line in the input history cntl-P - go backwards one line in the input history cntl-R - search backwards through the input history. Same as shift-up-arrow. cntl-U - delete all input characters to the left of the current cursor position. cntl-W - delete the "word" to the left of the cursor cntl-X - clear the input region cntl-Y - insert from the undo buffer at the current cursor position, and move the cursor to the end of the input data. DEL - delete the character under the cursor Using the Internal Editor The internal editor in the MUD client program can be started to edit a simple text string, such as a character description, a room description, etc. or to edit an AmigaMUD function while in wizard mode. The initial startup varies slightly between the two situations, mostly relating to the quoting and escaping of things, but the main operation of the editor is the same in both cases. The edit session is actually started by messages from the server, but the server is normally just responding to user requests. When editing is to be done, the text to be edited must first be sent from the server to the MUD client program. This can take a few seconds for a large function or description operating over a slow link. When all of the data has arrived, MUD will switch to a single full-screen text window (if it wasn't already) containing the first windowfull of the text. A menu item, or function key F6, can be used to temporarily switch back to the normal mode of operation. The switch-back should be short, however, since the system will not allow multiple things to be edited at once by any given client. While editing, the normal function keys and menus still operate, but their effect may not be immediately visible. Normal input and output history do not work, however, as they are replaced by an expanded set of editing operations. In edit mode, pressing the HELP key will display a short summary of the editing operations available. The internal editor is always in "insert mode"; that is, characters typed will always be inserted before any characters at or after the cursor on the current line, shifting those other characters to the right. The editor limits lines being edited to 160 characters (two displayed lines). Lines coming from the server will never be longer than can be displayed in the window, so longer lines can only be created by editing. There is no need to use long lines in AmigaMUD - lines of descriptions are all joined when the description is sent back to the server, and the spacing of functions is thrown away when the function is parsed. When editing things like letters and bulletins, the user's lines are preserved, but long ones will be wrapped when sent to any clients reading them. When editing an AmigaMUD function in wizard mode, the editor can work with the parser to identify the location of errors. When the user types the cntl-Q key combination, the text in the editor is parsed (on the local machine, by code in mud.library) into an internal data structure. If any errors are encountered, the parser gives an error message and a position to the editor. The editor displays the message in reverse video at the bottom of the window, and moves the cursor to the reported position, redrawing the window if necessary. The user can then immediately do editing to correct the error. If a further cntl-Q is entered, the parsing will be restarted from the beginning of the function. If, however, a cntl-G is entered, the parsing will continue from the first error, perhaps showing further errors in the function. A cntl-R combination can be entered to abort the parsing, but not start another parse. At any point in editing, a cntl-C can be entered to abort the entire edit session. Similarly, clicking on the edit window close box will abort the edit session, but will not cause MUD to exit. The text window's scroll bar is active while editing, and can be used to scroll around in a long function or description. Also, the same alt-up-arrow, alt-down-arrow, shift-alt-up-arrow and shift-alt-down- arrow key combinations that work in normal mode also operate while editing. When scrolling this way, the text cursor may have to move to remain visible in the window. The available editing operations are: Control operations: HELP - display a short summary of operations cntl-C - abort the edit. If editing a description, the scenario code is informed that the edit was aborted. If editing an AmigaMUD function, the function will be unchanged from before the edit. The edit can also be aborted by clicking on the close box of the edit window. This will not cause MUD to exit. cntl-Q - if editing a description, then the description as it is in the editor is sent to the server as the result of editing, and the MUD client program switches back to normal operation. If editing a function, then MUD starts parsing the function. If no errors are encountered, the function is sent to the server where the new definition immediately replaces the old one. If an error is encountered, its message is displayed at the bottom of the window, and the cursor is moved to the location of the error. cntl-G - this combination does nothing unless a function is being editing, and an error has been encountered. In that situation, the parsing continues and the next error is reported. If there are no more errors, that is indicated. cntl-R - this combination does nothing unless a function is being edited, and an error has been encountered. In that case, all further errors from this parse of the function are discarded. Cursor motion operations: left-arrow - move cursor left one column right-arrow - move cursor right one column shift-left-arrow - move cursor to the beginning of the line shift-right-arrow - move cursor to just past the end of the line down-arrow - move cursor down one line, scrolling the window if necessary up-arrow - move cursor up one line, scrolling the window if necessary shift-down-arrow - move cursor to the bottom of the window shift-up-arrow - move cursor to the top of the window cntl-A - move cursor to the beginning of the line cntl-B - move cursor back one column cntl-E - move cursor to the end of the current line cntl-F - move cursor forward one column cntl-I (tab) - move cursor forward to the next 8-column tabstop cntl-L - move cursor to the beginning of the next line cntl-N - move cursor to the next line cntl-P - move cursor to the previous line cntl-T - move cursor to the line at the top of the window cntl-Z - move cursor to the line at the bottom of the window Editing operations: cntl-D - delete the current line cntl-H (backspace) - delete the character before the cursor cntl-J - join this line with the next line. The text of the next line is appended to the end of the current line. cntl-K - characters from the current one under the cursor to the end of the line are deleted (killed) cntl-M (carriage return) - a new line is inserted after the current one and the cursor moves to the beginning of that empty line cntl-S - split the current line. Characters from the one under the cursor to the end of the line are moved into a new line inserted after the current one. cntl-U - characters from the beginning of the current line upto the one just before the cursor are deleted cntl-W - the previous "word" is deleted. A word is a sequence of non-spaces delimited by spaces or the beginning or end of the line. cntl-X - the current line is cleared, or emptied cntl-Y - the line is put back to the same state it had before any changes were made to it. This backup copy of the line is discarded if the cursor is moved out of the line, i.e. only changes made to the line while the cursor is in the line can be undone. Caches in the MUD Client Program In computer usage, a cache is a set of local copies of things that are expensive to get. An instruction cache in a CPU is a small memory which contains some of the instructions executed most recently. This cache memory can be accessed much faster than the main RAM memory external to the CPU chip. This same technique is used in AmigaMUD to speed up operation. This section will discuss the caches used in the MUD client program. The symbol cache and the function header cache are of benefit only to wizards, and were discussed earlier. AmigaMUD uses the term "effect" to refer to any of the non-text output items that are possible: graphics, sound, voice and music. Scenes in a scenario can be drawn in a variety of ways. The simplest way is to simply load an IFF ILBM image produced using a paint program. This image must be present on the remote client machines, however, since sending such an image over the serial connection every time it is needed would be too slow. Many players of an AmigaMUD scenario will not have the pictures, however, so an alternate method of drawing a scene is needed. As directed by code in AmigaMUD functions, the server can send messages to remote clients directing them to draw various simple graphical elements in the graphics window. These include lines, rectangles, circles, etc. A simple form of a scene can be drawn using these elements, and can be sent from the server to the client in less time than sending a full bitmap of a similar scene. It is useful, however, if a given scene needs to be sent over only once per session. Then, the scene can be called up by a short command from the server, thus greatly speeding up the play of the game. This storing of graphics elements (and commands to play sounds, etc. as well) by the remote clients is the "effects cache". Each effect is uniquely identified, and can be called up much like a subroutine or function can be called in a programming language. In fact, they ARE effects subroutines, and can in turn call on other, lower-level effects subroutines. Many Amiga systems have a megabyte or more of RAM, but have only a single floppy disk drive for permanent storage. Having to load up an IFF image or sound sample every time they are needed could make for slow and unpleasant playing of a graphics MUD. To alleviate this, the MUD client program will cache such items in RAM. This is termed the "file cache". The menu item "Caches"/"Show Status" displays the status of the caches in the client program. Here is a sample of its output: File cache: Images/streetsX >0< Sounds/birds >0< Effects: 4/18>2< 5/18>2< 3/18>10< 2/18>8< 13/240(7) 8/12 20/416(15) 6/112 1/48 Here there are currently two files loaded in the file cache. One is an image (IFF ILBM) called 'streetsX'. The other is a sound sample (IFF 8SVX) called 'birds'. The printed name shows the directory within the "AmigaMUD:" assign that the file came from. The '>0<' indicates that there are currently no references to the files, and thus they can be flushed from the cache as desired. Files can be flushed from the file cache using the "Caches"/"Free File" menu item, and can also be flushed by the program itself if it runs out of memory (e.g. to load in another file). When a file is flushed, the Least Recently Used one (the one such that all others have been used more recently) is chosen for flushing. A file cannot be flushed if its reference count is greater than zero. This will be true while a sound sample is playing, while a music score is playing, or while an instrument is referenced by a score in the file cache. There are nine effects subroutines currently stored in the effects cache. For each one, the first number displayed (before the '/') is the unique identifier for the effect. For a given compilation of the scenario, these numbers will not change. The number after the '/' is the size in bytes of the effect. The four length-18 effects in the above display are for the four styles of doors used in the standard scenario. A following number as in '>2<' shows the number of references to the effect subroutine from other effects subroutines. The various doors are used by both the 'streets' and the 'mall' effects subroutines. A following number as in '(15)' shows the number of references to other effects subroutines that this effect makes. The list of effects subroutines is shown in order of the most recently used one to the least recently used one. Thus, in this case, using the "Caches"/"Free Effect" item would free the effect with key 1 and size 48. Again, affects with non-zero reference counts cannot be freed. Freeing an effect is not instantaneous. The server keeps track of which effects each client has in its cache, so that it knows when it has to send a copy of an effect to a client. So, when the client wants to free an effect, it sends a request to the server, which will always reply in the affirmative. This allows the server to try to keep its records accurate. It is, however, still possible for the two to get out of agreement. If the server sends an effect that the client already has in its cache, the client just ignores the new copy. This can happen even in proper operation, because of timing issues. If an effect manages to call an effect that is not in the cache (this should not happen), the call is ignored. The "Caches"/"Zap Effects" menu item sends a request to the server saying that all of the effects subroutines cached by this client are to be freed. When the reply gets back to the client, it in turn will free all of the effects subroutines it has cached. This can be useful if for some reason, the server and the client seem to get out of agreement and the proper displays are not appearing. More likely, however, is a bug in the scenario which is not displaying the scenes correctly.