Copyright: Copyright 1995 Robert M. Free


Warnings and Known Bugs

Script Robustness

As indicated in the product description, robust script checking is not provided in MUTT Lite, in order to maximize other features within Lite's size constraint (32K).  Syntax and correct use of white space is critical to successful script handling.

Strange line wrapping

This can be caused by a number of things:

1. The display window is too small - either stretch the window wider, or maximize it.

2. The font is too big/small - change it in MUTT.INI.

3. The font is not a fixed-width font - change it to "terminal" or "courier".

Cursor Keys Don't Work in Send Window

All the sample script files have the numpad cursor keys defined for navigation; the gray cursor keys should be used for editing text in the send window.

If you do not have separate numpad and gray cursor keys, you can disable the numpad cursor key definitions by commenting out the hotkey definitions in MUTT.INI.

Non-standard EOL handling

Some older MUDs use a non-standard "newline" for end-of-line termination; the standard is "carriage-return + linefeed". Unfortunately, the native edit text control fails to handle non-CRLF line terminators, causing lines to run together and displaying a "block" character where the EOL should be.

MUTT  detects this condition and automatically converts NL EOLs to CRLF.  Note, however, that this will cause the display response to be a bit slower when connected to a MUD host with non-standard EOLs.

Winsock Read Errors

FTP's PC/TCP is known to have difficulties with asynchronous read handling.


Overview
Contents for MUTT Lite Help

MUTT Lite is a windows, Winsock-based client for access to networked multi-user virtual-reality worlds

Copyright Notice

MUTT Overview

Installation Requirements

Using MUTT

Startup Command File MUTT.INI

Scripts and Scripting

Debugging Scripts

Warnings and Known Bugs


Copyright
Multi-User Trivial Terminal  -  MUTT(tm) Lite  -  Version 0.1j

Copyright  ©1995 Robert M. Free  -  All rights reserved.

This software program (hereafter referred to as "WORK") is subject to U.S. and international copyright laws and treaties.

This WORK may be copied and distributed freely as an unmodified work in whole; no part of this WORK may be translated, embedded, repackaged, bundled or altered without the prior written consent of Robert M. Free.

No guarantee or warranty regarding the use of this WORK is made nor implied.

MUTT(tm), MUTTER(tm) and MUTTAPI(tm) are trademarks of Robert M. Free.

Critiques and questions are welcome; send them to mutt@graphcomp.com.

Online help is available on http://www.graphcomp.com/mutt/help.html


Debugging Scripts
Debugging

It is often useful to try out script file definitions before actually connecting to a host.  Starting MUTT with a "/d" command line argument will allow you to open a session and execute scripts without actually connecting.

Alternately, you can connect to an echo server (port 7) if one is available.  This is useful for debugging triggers.

A DEBUG.MUT script is supplied for use in confirming script functionality.  It may also be used as the basis for creating custom scripts.

From time to time, MUTTER tips will be made available at http://www.graphcomp.com/mutt/help.


Function Keys

f1	key 1	s_f1	shifted key 1

f2	key 2	s_f2	shifted key 2

f3	key 3	s_f3	shifted key 3

f4	key 4	s_f4	shifted key 4

f5	key 5	s_f5	shifted key 5

f6	key 6	s_f6	shifted key 6

f7	key 7	s_f7	shifted key 7

f8	key 8	s_f8	shifted key 8

f9	key 9	s_f9	shifted key 9

f10	key 10	s_f10	shifted key 10

f11	key 11	s_f11	shifted key 11

f12	key 12	s_f12	shifted key 12


Functions

Functions are commands that evaluate to expressions and may be used in place of variables within other commands.  MUTT Lite supports the following funtions:

chance( percent );

Evaluates to 1 every percent of the time; otherwise evaluates to 0.

equstr(variable, expression, case_flag, offset, count );

Compares contents of variable with expression; expression may be a variable or a string (eg. equstr( "0", TRIGGER_INDEX, 0, 0 )).

case_flag is 1 for case-sensitive matching; otherwise 0.

offset is the offset from the start of variable; may be 0.

count is the number of characters to compare; 0 indicates comparison to end of variable and expression.

Evaluates to 1 if compared strings are equal; otherwise 0.

findstr(variable, expression, case_flag );

Searches contents of variable for first occurence of expression; expression may be a variable or a string.

case_flag is 1 for case-sensitive matching; otherwise 0.

Evaluates to 0 if expression is _not_ found; otherwise non-0.

yesno(expression [, expression [...]] );

Pops up a message box with expression as a prompt.

expression may be a variable or a string within quotes.  The expressions are evaluated and concatenated.

Evaluates to 1 if user presses OK button; otherwise 0.


Extended (Grey) Keys

x_hom	extended home

x_end	extended end

x_lft	extended left arrow

x_rgt	extended right arrow

x_up	extended up arrow

x_dn	extended down arrow

x_pup	extended page up

x_pdn	extended page down

x_ins	extended insert

x_del	extended delete

x_ent	numeric enter


Hotkeys

HotKeys are keys that are associated with scripts; by pressing a HotKey, the associated script is executed.

HotKeys are defined within the "[HotKeys]" script group.  See the provided AA.MUT script as an example.

MUTT Lite supports a limited number of hotkeys.

The HotKey format is:

label = script

label is a HotKey identifier and script is the script that is associated with it.

Miscellaneous Keys

Keypad Numeric Keys

Keypad Keys

Function Keys

Shifted Function (Grey) Keys


Miscellaneous Keys

esc	escape


MUTTER Command Language

MUTTER is an interpretive command language that may be entered as command entries or used in scripting.  The following documents the commands available in MUTT Lite.  The first form is used in scripts.  Either form may be used for command entry; prepend the first form with the command prefix if used as a command (the default command prefix is ;).

break;

Stops the execution of a script. In the command line, this is a NOP.

clean( variable, filter );

Removes characters indicated by filter from variable. variable must be a user-defined variable in the script file. filter may be a string, a system variable or a user-defined variable.

clear;

Clears display window.

do( script );

Executes a previously defined script.

if( expression ) command [else command];

Conditionally executes command.  expression may be a variable, string or function.  command may be any of the previously described commands. If the expression evaluates to non-0, the first command is executed.  Otherwise the second command is executed, if provided.

log( filename );

Opens and closes a log file used to record text displayed in the Receive window.  filename is "", a string or a variable. If filename evaluates to "", the existing log file, if open, is closed.

note( expression [, expression [...]] );

Echos text to the display window and log files if echo is enabled. expression may be a variable or a string within quotes.

popup( expression [, expression [...]] );

Similar to note except that expression is displayed in a popup

message box, instead of being executed, echoed or logged.

prompt( variable, default, expression [, expression [...]] );

Similar to popup except that expression is displayed as a prompt in a popup dialog; user input is saved in variable.

If the user presses the dialog's cancel button, variable is untouched and a break occurs in the script. variable must be a user-defined variable in the script file. default is used as the default value and may be a string or variable.

put(expression [, expression [...]] );

Similar to say, except that the expressions are pasted into the command window, but not executed.  Anything previously in the command window is overwritten.

putmore( expression [, expression [...]] );

Similar to put, except that the expressions are appended to the end of the command window, without overwriting previous contents.

say(expression [, expression [...]] );

Sends text to the host.  expression may be a variable or a string within quotes.  The expressions are evaluated, concatenated and then sent with a terminating carriage return and line feed.

send( file [, file [...]] );

Sends the content of file to the host.  These should be text files containing carriage returns and line feeds.

set(variable, expression [, expression [...]] );

Similar to say, except that the expressions are copied into the specified variable, instead of being sent to the host. variable must be a user-defined variable in the script file.

setword( variable, expression, index );

Copies the Nth word of expression, as indicated by index, into variable.  A word in this context is any string separated by whitespace; adjacent punctuation is considered part of the word.  The clean command may be used to remove punctuation. variable must be a user-defined variable in the script file. expression is a string, system variable or a user-defined variable. index is a 1-based number.  A positive index indicates the count from the start of variable; a negative starts at the back.  index also may be TRIGGER_INDEX, TRIGGER_PREV or TRIGGER_NEXT.

term;

Terminates the MUD session.

trigger( label, script );

Enables trigger  label.  When the trigger is tripped by received text, the script is executed; the trigger remains enabled.  If script is break, the trigger is disabled.

The system variable TRIGGER_LINE is set to a string containing the line that caused the trigger.  TRIGGER_INDEX is set to the word number in the line that caused the trigger.  These values are overwritten by the next trigger match.

Note: increasing the number of active triggers will reduce the response performance of the app.  Triggers can be used most efficiently when a small number of key triggers are used to temporarily initialize other triggers.

wait( label, time, ok_script, fail_script );

Posts a trigger, label, that expires in time seconds.  If the trigger is tripped before expiration, the ok_script is executed; otherwise the fail_script is executed.  Either script may be break.

Note: the trigger is disabled after wait is either triggered or timed out.

xlat( variable, case_flag, old, new );

Substitutes occurences of old with new in variable. variable must be a user-defined variable in the script file, and must be large enough to hold the new string. case_flag is 1 for case-sensitive matching; 0 indicates that the case in variable is ignored. old is the string being searched for and may be a string, a system variable or a user-defined variable. new is the string used for replacement and may be "", a string, a system variable or a user-defined variable.


MUTT.INI Startup File

When you start MUTT, and when you open a new client window, MUTT looks for values and parameters stored in MUTT.INI, which is found in your windows startup directory (usually C:.INI).

The structure of MUTT.INI is the same as all INI files.  For an overview of INI file structure, look at the WININI.WRI file in your windows directory or check your system's documentation.

[Options]

Under "[Options]" section is a setting called cmd_prefix.  This defines what character is used to differentiate MUTT commands from literal text to be sent to the host.  By default, this character is ";".  The format is:

----------

cmd_prefix =char

----------

"char" is a decimal ASCII value indicating the command prefix.  This value must be between 33 and 126.

Also under "[Options]" section is a setting called edit_receive.  This defines whether or not the display (receive) window will allow copy/cut/paste operations.  The format is:

----------

edit_receive = state

----------

"state" is either 0 or 1; 1 enables copy/cut/paste operations in the diaply (receive) window - the default disables edit operations.  Use the standard <ctl-x> for cut <ctl-c> for copy and <ctl-v> for paste.

Cut&paste is always enabled for the command window.

[Fonts]

Under the "[Fonts]" section is a setting called send.  This defines the font used in the command (send) window.  The format is:

----------

send =font_name, height, width, boldness

----------

"font_name" is the name of the font, height and width are the size in pixels.  Boldness is 1 through 9, with 1 being light and 9 the boldest; 0 indicates that you don't care.

[Characters]

The "[Characters]" section stores your session character definitions.

----------

character =password, ip_address, port_num, script

----------

"password" is a non-encrypted password for the character.  "ip_address" is the IP address in a.b.c.d form.  "port_num" is the port number. "script" is an optional script file.

[AppWindow]

[SessionWindow]

[PromptWindow]

These sections define the default placement and size of various windows.


Numeric Keys
Numeric Keypad Keys

num0	keypad 0

num1	keypad 1

num2	keypad 2

num3	keypad 3

num4	keypad 4

num5	keypad 5

num6	keypad 6

num7	keypad 7

num8	keypad 8

num9	keypad 9


Overview
Overview of  MUTT Lite Help

MUTT is a simple Winsock-based MUD client that provides:

     ·   MDI presentation of multiple client connections.

     ·   Drag & Drop support for sending command files.

     ·   Separate command and display windows.

     ·   Simple scripting with limited user-definable variables.

     ·   User-definable hot keys and cursor navigation.

     ·   Log file recording.

     ·   Event triggering.

MUTT has been tested on various TinyMUDs, LP-MUDs and DIKU-MUDs.  It may also be used as a chat client, and in a pinch, can serve as a telnet client.

MUTT Lite is a freeware (but _not_ public domain) version with the following design criteria: the executable will remain below 32K in order to minimize internet traffic and ftp site impact.

Due to this constraint, the Lite version will not support the following features, planned for MUTT Elite:

     ·   Dialogs for setting options and defining scripts/triggers/hotkeys.

     ·   Advanced scripting capabilities.

     ·   Robust error checking in scripts.

     ·   Advanced string, arithmetic and boolean functions.

     ·   Regular expressions in triggers.

     ·   ANSI color support.

     ·   Command history.

     ·   User-supplied, DLL-based 'bots.

     ·   Peer-to-peer chatting.

     ·   Online help files.

If you would like to receive information on MUTT Elite, send email to mutt@graphcomp.com.


Keypad Keys

cntr	center key

home	home

end	end

left	left

right	right

up	up

down	down

pgup	page up

pgdn	page down

ins	insert

del	delete


MUTT Requirements
MUTT Installation Requirements

MUTT requires a correctly installed and configured 1.1-compliant Winsock with TCP/IP access to a MUD/MUSH/MUD host or some other telnet-based service.  See your Winsock documentation for correct usage.

This release has been tested with the following Winsocks: NT, MS Winsock32, Novell's Lan Workplace, Netmange's Chameleon and Trumpet.

Note: This release does not support FTP's PC/TCP.


Robots
Very simple 'bots may be created through the use of scripts and triggers.  However, more sophisticated robots may be created via DLLs using MUTTAPI.  MUTT Lite does not support MUTTAPI.


Scripts and Scripting
Scripts

Scripts are a list of commands that may be executed by command entry, other scripts, conditional commands and triggers.  Limited robots can also be created with script files.

Scripts are defined within the "[Scripts]" script group.  See the provided GENERIC.MUT and AA.MUT scripts or the section on scripting.

MUTT will automatically execute a script called INIT at the start of the session if found.  The script format is:

label = command; [command; [...]]

label is a unique script name with 16 characters or less and may not include spaces. command is any of the previously defined MUTTER commands.

Script Files

MUTTER Command Language

Functions

Variables

Triggers

Hotkeys


Script Files
Script Files xxxx.MUT

MUTTER script files have the extension ".MUT" and are compliant with WIN.INI file formats.  Script files may be associated with MUD sessions via the "Open..." dialog and are used for defining scripts, triggers, variables, functions and hotkeys.  MUTTER script files serve a function similar to that of "worlds" in traditional unix MUD clients.

Each line contains one of the following:

1. A group label enclosed by square brackets followed by a carriage-return and line feed, indicating the start of a new definition group.  Examples include: [Scripts], [Triggers].

2. A definition in the form of "label = definition", where "label" is a name unique in that definition group and "definition" is the item's definition in a format standard for that definition group. These definition groups are defined below.  Labels must be 16 characters or less with no white-space, and are case-insensitive.  Definitions must fit on a single line and are terminated by a carriage-return and line feed.

3. A blank line (carriage-return and line feed); ignored.

4. A line beginning with ";" and terminated by a carriage-return line feed is a comment and is ignored.

If multiple definitions within a script file have the same name within a definition group, the last definition of that name will overwrite the previous defintions.

When a session is first begun, the app will look for a script called "init".  If one has been defined, this is executed at connect time.  This can be used to setup automatic logins and to initialize triggers.

AA.MUT and GENERIC.MUT may be used as an examples of how many MUTTER features are used.

Note: MUTT Lite only supports 1024 definitions per definition group.


Triggers

Triggers are filters that may be set; they compare strings against received text.  If a match is found while the trigger is enabled, an associated script is executed.

In order to use a trigger, it must first be defined in the "[Triggers]" script group; then it must be enabled via a "trigger" or "wait" command.  Triggers are often enabled at start time within the "init" script.

See the provided SIMPLE.MUT sample script for an example of defining and enabling scripts.

The trigger definition format is:

label = string, case_flag

label is a unique trigger name with 16 characters or less and may not include spaces.  string is the trigger string that is used for seeking matches.  case_flag is 1 for case-sensitive matching; otherwise 0.

Note: increasing the number of active triggers will gradually slow MUTT's response time.

MUTT Lite does not support regular expressions in string.


Using MUTT
Once running, select the menubar's FILES menu and pick the"Open..." menu item.  A dialog box will appear; enter a character name.

If this is a new character, enter the MUD host's IP address or Internet name,  and port number.  Contact the host's administrator if you are unsure of these values.

The password and script fields may be left blank.  Passwords are only useful when scripts are used; script usage is described later in this document.  The BROWSE button may be used to select existing script files. TINY.MUT, LP.MUT and GENERIC.MUT scripts are provided as examples.

If you wish to define several characters without actually connecting, press the SAVE button between each definition.

Press the OK button to connect to the selected MUD host; the current character definition will be saved, a connection will be established and the script (if one is selected) will be executed.  The NEW button is identical to the OK button, except that the CREATE system variable is set to 1 for NEW and 0 for OK, allowing different startup scripts to be executed.

A session window will appear with a larger display box in the upper part of the window and a smaller command box in the lower part of the window.

At this point, any non-command text you type in the lower window will be sent to the MUD host when you press <enter>.  Text beginning with a command escape (the default is ";") are interpretted as MUTTER commands, which are described later in this document.

You can "execute" text file directly, by selecting them from the Windows File Manager and dragging them onto the active MUTT client window. The contents of these files are sent to the MUD host.

The upper window will display text received from the host, and optionally, commands echoed from your input and any executing scripts.

You can end the session by closing the session window or by entering the command ";term".

MUDs all have different command syntax (and operating systems and languages).  MUTTER does not interpret any commands or files sent to a MUD.  Contact the MUD managers or read the applicable FAQs for details on MUD commands.


Variables

Variables are memory slots for storing and retrieving values.  User-definable variables are defined within the "[Variables]" script group. The variable allocation format is:

label = type, size [, dimension [, dimension [....]]]

label is a unique variable name with 16 characters or less and may not include spaces.  type is either: "int", "dec" or "str".  size is the number of bytes used by an element of this variable.  "dimension" defines the dimension of the scalar/array/matrix variable.

Note:  is interpretted as carriage-return line feed in string variables. MUTT Lite only supports string variables, and does not support variable arrays.

MUTT Lite supports the following read-only, system variables:

character

Evaluates to a string containing the name entered in the "character" field of the "Open..." dialog box.

coin

Evaluates to 0 about 50% of the time and 1 the rest of the time.

create

Evaluates to 0 if the user pressed the "OK" button when starting the MUD session or 1 if the "NEW" button was pressed.

trigger_index

Evaluates to a string representing a 1-based number indicating the index of the word in TRIGGER_LINE that caused a trigger event.  May be used with "setword" to retrieve the trigger word.

trigger_line

Evaluates to a string containing the text line received from the host when a trigger occurs.

trigger_next

Evaluates to TRIGGER_INDEX plus 1.  May be used with "setword" to retrieve the word after the trigger word.

trigger_prev

Evaluates to TRIGGER_INDEX minus 1.  May be used with "setword" to retrieve the word after the trigger word.  See AA.MUT sample script.

password

Evaluates to a string containing the text entered in the "password" field of the "Open..." dialog box.

version

Evaluates to a string identifying the version; example: "0.1A".