AmigaMUD, Copyright 1997 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 or via a TCP/IP internet connection. The operation of the program is the same in all 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 or a telnet program in the case of an internet connection. The display that MUD produces depends on how it is configured. The default display uses two Amiga screens. The upper screen is for graphics, and is 320 pixels across by 100 pixels high by 32 colours. The lower screen is used for text, and is roughly 640 pixels across by 100 pixels high by 4 colours. The text window has a scrollbar for viewing output history, and supports input history and line editing. Hires mode doubles both sizes of the graphics window and the vertical size of the text window. Onescreen mode puts both areas as windows on a single screen. Onewindow mode puts both areas as regions within a single window on the Workbench. Twowindow mode uses two Workbench windows, one for text and one for graphics. In Workbench modes, the text area is sizeable. See the "Display" section for more details. 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 connection 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 "MUDEditor" environment variable to the full path to the editor to use. If the variable is not set, variable "EDITOR" (also used by other software) is checked, and if that 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. The editor must not "auto detach", since that causes the edit process to terminate prematurely from MUD's point of view. Many users will prefer to just use the simple editor built-in to the MUD program. If an external editor is used, the AmigaDOS process created for it will by default have a stack size of 9996 bytes. If you wish to use more or less bytes, you can use the '-s' CLI flag, or the "EDITORSTACK" icon tooltype, to specify a different size. MUD will enforce a minimum size of 4096 bytes. 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: background images (fill the graphics area) Images: images of various sizes (often fill half the graphics) 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. 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 in 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 TCP/IP stack, the stack should be active before you start the MUD program. The name of the machine running the server (or its IP address) must be given, either on a CLI command line or via an icon tooltype. The TCP port number can also be given if it is different from the default 6667. Nothing else need be done with this kind of connection - status messages will be displayed in the text window as needed. Note: this MUD client program is *not* a suitable client for use with any MUD servers other than the AmigaMUD server. The connection to the server goes through an agent program, MUDBinary, on the server machine, but the client is not affected by this. 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. This mode will attempt to ignore any ANSI escape sequences that it sees, however. When serially 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, or are corrupted during transmission. This protocol operates quite differently from 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 serial case, that of using MUD to connect via modem 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 Amiga 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 serially. 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/Effects/Zap Effects" menu item to empty the effects cache, since a given effect identifier is unlikely to mean the same thing on another AmigaMUD. If both AmigaMUD's are running the bare standard scenario, you are probably safe, however. Display The display types supported by MUD are influenced by the version of the OS that you are running, and the Amiga hardware you are running on. For example, systems running pre-2.0 versions of the OS will only get an "oldstyle" display. Non-AGA systems (i.e. not A1200 or A4000) can only get the lo-res "basic" display or the "Workbench" display. Note that the Amiga OS will happily attempt to open screens of unsupported types, and nothing serious goes wrong - you just won't see all of the colours you expect. For example, on my V1.3 A1000, trying to open a hi-res basic display simply produces a graphics screen on which only colour 0 is ever displayed. On my A3000, the same request gets a screen in which only half of the colours are displayed. It can also be dangerous to run with the maximum number of colours that your Amiga will display when in a Workbench type - this can affect the Amiga's ability to handle the built-in serial port, causing communication problems. Alternative serial drivers may help. As mentioned above, the on-Workbench display modes are only available on 2.0 and above systems. MUD's menus are designed to look most like standard 3.1 menus, but that appearance requires a 3.1 menu flag. So, on 2.0 and earlier systems, the menus will look like an intermediate between 2.0 style and 3.1 style (mostly 3.1 style with 2.0 colours). Other than that, MUD does not use any 3.1 features. In particular, it does not do any pen-locking, so on-Workbench colour handling is the same under 3.1 as it is under 2.0. There are ten distinct display types supported by the MUD program, although some are only minor variations. If not told otherwise, it will open up the "basic" display. In this type, a graphics screen that is 320 pixels wide, 100 pixels high, and 5 bits deep (32 colours) is opened at the top of the display. It will be horizontally centered within your overscan range. The remainder of the display will be filled with a hi-res text screen, that is roughly as wide as your horizontal overscan, and roughly fills your vertical overscan. Note that this means that PAL systems will have more text lines than NTSC systems. The text display has a scroll-bar on the right hand side. All Amigas can use this display type with their built-in hardware. Unless you are running a pre-2.0 system, the text colours of the "basic" display will be taken from your Workbench colours, so the text window should look much like a shell window with a scrollbar. The input prompt will be in a different colour, however. With this type, the menu-bar is attached to the text window in the text screen, so the menus will be half-way down the display, which is a bit unusual. Since the text window is using your Workbench colours, the effects function which changes the pens of the text window, and the scenario commands which use it (e.g. 'normalgrey' and 'brightgold'), are all disabled. To the basic display type can be added the "oldstyle" modifier. This modifier makes MUD operate the way it used to, before the V1.1 changes. With this display type, AmigaOS V2 and V3 features are not used, and the Workbench colours are ignored. Instead, the old gold colour scheme is used. When an oldstyle display is active, the function and commands for changing the text window colours are again active, and the 'dim' and 'bright' startup options are available. A second modifier is the "hires" modifier. With this modifier active, the basic display will have a graphics area that is 640 pixels across, 200 pixels high, and 5 bits deep. The text screen will also be twice as many pixels high, giving twice as many lines of text. The "hires" modifier can be mixed with the "oldstyle" modifier to produce a total of four styles of "basic" display. Note that the hires displays use more memory and are a bit slower than the non-hires displays. As mentioned above, the hires displays require an AGA system, or a graphics card. The second major display type is the "onescreen" display type. In this type of display, MUD opens only one screen, and uses Intuition windows on that screen for the graphics and text areas. In order that the standard 32 colours be available for graphics, in addition to the four (or more) colours needed for your standard Workbench windows, this display type opens a 64 colour (6 bit) display. The upper 32 colours are used for the graphics window, and the lower 32 are used (if at all) only by the text display, window borders, etc. The "onescreen" display type works on AGA systems, but is very slow. It is intended for those with graphics cards which cannot open multi-resolution or multi-depth displays. The "hires" modifier can be used with "onescreen" displays, with the expected effect. The combined type is, in my opinion, unusably slow on my all-CBM A4000T/040. In "onescreen" displays, the menus are attached to the graphics window, and so are at the top of the display. The third major display type is the "twowindow" type. In this display, MUD opens up two windows on the Workbench screen (actually, on the default public screen). In the lores variant, the text window will open at the top of the screen, and will have room for 23 lines of text (the space needed for the builtin editor's HELP display) of 80 columns each. This will be reduced if it will not fit. The graphics window will have interior room for 320x100 pixels, and will be opened just inside the top-right-hand corner of the text window. In the hires variant of the "twowindow" type, the graphics window is double-size and opens at the top of the screen. The text window opens below it, if possible. If the text window doesn't fit there, it will be moved upwards, overlapping the graphics window, until it does fit. The text window can be resized from fullscreen to very small. The graphics window cannot be resized, since the MUD client does not maintain enough information to be able to redraw its contents at a different size. Scaling of non-bitmap graphics is actually done by scenario code running in the server. The final major display type is the "onewindow" type. In this display, MUD opens up only a single window on the Workbench screen. There will be a fake separator between the graphics up top and the text down below. The text scroll-bar will only be beside the text portion of the window, and some user interface hacks can mess that up a bit. The combined window can be sized, but not narrower than the full width needed for the graphics, or shorter than the full height of the graphics plus a few lines of text. The graphics are always in the top- left corner of the window, to allow for the most resizing. In the hires variant, the graphics is twice as large, thus occupying twice as much space in the window. Note that in both Workbench display types, MUD is constrained to only using the colours available on your Workbench screen. This can seriously affect the viewability of the graphics. MUD attempts to remap colours as best it can, but the results can be pretty bad, depending on the available colours. It is best to have a least one of each of the major colours: white, black, grey, red, blue, yellow, brown, etc. Four colour displays can be useable, and 8-colour ones can work not bad. The various sizes and depths of available graphics displays have required some additional features in MUD, and some changes to the basic AmigaMUD programming language and builtin functions. When loading bitmap images (backgrounds, images or brushes), MUD will scale them to the required size. On pre-V2.0 systems, the scaling routine (in the Amiga's "graphics.library") does not exist, however, so those systems will get a mess. With a Workbench display, MUD probably does not have its chosen set of 32 colours available, and it is not allowed to alter the palette. Instead, MUD will map the 32 standard colours to the available colours. So, it will report a colour count of 32, regardless of the actual colour count. It will also report that it can change the palette, even though it never will. It can, however, change its colour mapping in response to palette change requests from the server. Remapping of IFF ILBM images is a slow process, and sometimes it doesn't work very well. The standard scenario is usable on my four- colour Workbench, but only just. Some images just do not come out at all. With an eight-colour display, things are much better, especially if the eight colours are chosen so as to give a good choice to MUD. A 32 colour Workbench can be just as good as letting MUD create its own screens (but slower, on my A4000T). One way of getting a good set of colours into your Workbench palette (since the Preferences tool only lets you set the lower 8 colours), is to set the included file "palette" as your background image, and then save your palette using the Preferences tool. Once you have your palette preferences set up, you can go back to your normal background pattern. If you normally use a background image, then the colours from the palette for that file will be the ones that MUD will have to use in "workbench" mode. [The following is a technical note that is mostly relevant to designers of AmigaMUD scenarios.] When colour remapping is in effect, changing the colour of a pen doesn't work quite the same. Instead of changing a real pen, MUD simply takes the new colour, finds the best match for it in the real Workbench palette, and enters that value in the slot in its colour mapping table for the colour being changed. This will affect future drawing using that pen. In types other than "Workbench", all existing pixels in that pen will also be affected. So, it is best if a scenario does all colour palette changes before it does any drawing. This also holds true for tiles cached by MUD - they are mapped when they are cached, not each time they are used, so palette changes should be done before any tiles have to be sent to the clients. When a Workbench display type is selected, you can also tell MUD to not do the above-mentioned colour remapping. When remapping is turned off, MUD works directly in the Workbench colour palette. The standard scenario drawn images (as opposed to the bitmap files, which will still be remapped as normal) will be drawn directly with the pen- numbers that the scenario gives. This will make a mess for the standard scenario, since it assumes the default 32 colours. However, if you are making a new scenario, this mode may be desireable, as it lets you access the full 256 colours of a 256-colour AGA Workbench. This will be reported via the GColours builtin returning 256. Note, however, that anyone playing such a scenario must have the same Workbench palette, for *all* colours that you use, in order for the graphics to come out right. Setting the MUD display type can be done with command-line flags, icon tooltypes or shell environment variables. See the relevant sections of this document for details. 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. IPHOST (string) - this tooltype specifies the name (or IP address) of the internet machine to connect to, and also forces MUD to use only an internet connection through a TCP/IP stack. Use this tooltype only on icons which you will use only when your TCP/IP stack is active. IPPORT (numeric) - this tooltype specifies a different IP port to use when connecting over the internet. The default value is 6667. Like IPHOST, this tooltype forces an internet connection. MODE = { ONESCREEN | TWOSCREEN | ONEWINDOW | TWOWINDOW } - this tooltype selects which display type the MUD program is to use. See the above section on "Display" for details on the various display types. HIRES (boolean) - this tooltype controls whether or not MUD will use higher resolution for its screens and windows. This provides twice the vertical and horizontal graphics resolution. In non-Workbench display types, this will also provide twice the number of text lines. This option does not work correctly on non-AGA systems, since the Amiga chips do not support the needed graphics capability. OLDSTYLE (boolean) - this tooltype controls whether or not MUD will use the old-style gold text colours, and allow text colour palette modification. The default is to not allow this under V2.0 and above of the AmigaOS. This flag is only useful with a "ONESCREEN" display. MAPCOLOURS (boolean) - this tooltype is only relevant in a Workbench display mode, and is normally enabled. Turning this option off forces MUD to work directly in the Workbench colours, and not attempt to remap colours. FULLREDRAW (boolean) - this tooltype should not be needed. MUD makes some undocumented assumptions about what happens when a window is resized. This allows it to do faster operations when showing or hiding the graphics window. If your display is messed up when doing those operations, try setting this flag, and let me know about it. EFFECTSQUIET (boolean) - this tooltype controls whether or not MUD prints a warning message in the text window whenever the scenario references an effects file (background, image, brush or sound) that is not available on this system. Seeing the warnings is useful in order to know what files the active scenario can use, but the warnings can be annoying. SERIAL (boolean) - this tool type tells MUD to connect to a remote server over a serial port. 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 or via a TCP/IP stack. This is the default action. 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. Only relevant for an "oldstyle" display. 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. Only relevant for an "oldstyle" display. 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 for a local connection. 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. Note that this is *not* an internet IP port number or service name. 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. EDITORSTACK (numeric) - this is the size of stack to use for an external editor process. The default is 9996 bytes, and the minimum is 4096 bytes. Examples: IPHOST=mud.myrias.com MODE=onescreen IHISTORY=10000 This requests a connection over the internet to a machine named "mud.myrias.com", using the default IP port. The display is to be on a single custom screen (useful mostly with graphics cards), and a large 10000 byte input history is used. MODE=twowindow HIRES=true 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. The display will use a high resolution graphics window and a separate text window on the Workbench screen. MODE=twoscreen OLDSTYLE=true 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. The display will be the oldstyle gold text display in a pair of custom screens. MUD CLI Command Line Flags All of the above icon tool types can be given on a CLI command line, as in: MUD HIRES BAUD=19200 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. When started from a CLI, the name and optional port number of an internet host to connect to can be given, without being preceeded by a minus sign. E.g. "mud supersys.com" will attempt a TCP/IP connection to a remote machine named "supersys.com", using the default IP port of 6667, and using all other default values (as modified by any environment variables set). The flags supported are: -w - open in one or two Workbench windows -1 - open in one window or screen, not two -h - hires display -O - oldstyle display -m - open on workbench, do not remap colours -f - fullredraw -q - effects quiet -w - try to close the Workbench on startup -L - make a local connection -T - make a local connection using port "MUD test port" -B - use the bright text window colours (oldstyle only) -D - use the dim text window colours (oldstyle only) -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 -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. The disabling is known to the MUD server, and hence to the scenario. -s - this flags specifies the size of stack to use for an external editor process. The default size is 9996 bytes, and the minimum size is 4096 bytes. 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 Environment Variables MUD checks for a number of environment variables (as set with the shell 'setenv' command). These values can override some default settings in MUD, and can be in turn overriden by icon tooltypes or command-line flags. All environment variables are of boolean type. The following variables are recognized: MUDLocal - if true, forces a local connection (no longer really needed, now that the default is a local connection) MUDMode - can contain the name of the display type to be used MUDHiRes - if true, forces hires display MUDMapColours - if false, turns of colour remapping MUDFullRedraw - if true, forces full redraw mode MUDEffectsQuiet - if true, supresses effects warnings MUDEditor - path to the text editor to use an external editor EDITOR - editor path to use if MUDEditor is not specified See the previous sections for discussion of the detailed meanings of these options. 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. Log Mode - the two modes, Both and Input, control what will be logged to a log file. If 'Both' is checked, then both the user's input and the game's output is logged. If 'Input' is checked, then only the user's input is logged, with any passwords omitted. 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. Do not attempt to change modes inside a sourced file, however, since the changing of modes is not a synchronous event, and a few commands will end up being given to the wrong mode. 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. Note that the picture cannot be hidden when MUD is running in a Workbench window. 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 speech 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 screens 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. Sending a ^F signal to MUD will cause it to move its screens to the front of the display. This function is not active when MUD is running in a Workbench window. Workbench - this item 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, or if MUD itself is running in a Workbench window. Effects - 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 [R-A Z] - 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. Quiet - when active (checked), this flag tells MUD to not print warning messages about not being able to find effects files. These messages let you know what files the scenario is trying to use, but can be annoying. 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 (along with the ALT key and the arrow 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 Amiga shell, with some minor additions. The available operations are as follows: up-arrow - scroll backward in the input history down-arrow - scroll forward in the input history shift-up-arrow - search backward 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 backward one line in the input history cntl-R - search backward 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 MUD 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 "Effects"/"Show Status" displays the status of the caches in the client program. Here is a sample of its output: Files: Sounds/clang >0< Images/Town/mall >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 Tiles: Here there are currently two files loaded in the file cache. One is an image (IFF ILBM) called 'Town/Mall'. The other is a sound sample (IFF 8SVX) called 'clang'. 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 "Effects"/"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 "Effects"/"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 "Tiles:" line in the output will currently always show nothing, since no current scenario uses the tiling facility of the system. When in use, each entry is simply the numeric identifier of the cached tile. The "Effects"/"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. There is one circumstance where all of your cached images and brushes will be removed. This is when you are running MUD with one or two custom screens (as opposed to in WorkBench windows), and a new background is loaded which has a different colour palette than the currently in-use palette. In this situation, the remapping of the colours of the images and brushes to the active palette becomes invalid, and needs to be rebuilt. This is currently side-stepped, by simply removing all of them from the cache, which will cause them to be reloaded if needed, and remapped at that time. This is arguably the best solution, since the images as mapped to the current palette may have lost information from their in-file forms, which can perhaps be fully utilized if they are remapped against the new palette.