What is Matchbot?

Matchbot is a simple Java application for creating scripted 'Chatterbots'
and embedding them in any system that can support/interact with
Java.

What is Matchbot not?

The MatchbotEngine is to all intents and purposes 'stateless', it is therefore
not possible to create 'bots that will remember visitors to your site.

Matchbot has no capabilities to use external sources such as
search engines on behalf of the user (however it can be scripted to show URLs).

Matchbots cannot 'learn from the user' nor 'learn from text
files'. Everything that the 'bot says must be scripted by you.

Features of Interest

Still with me after all that negativity? Good! There are some features of Matchbot
that are less common to 'bot engines:

The Matchbot applet loads scripts into the vistor's browser so, once started,
the user does not have long world-wide-waits in their conversation - because no extra connections to the server are necessary!

You can make links (similar to hyperlinks) from the main script to others
which will be loaded dynamically if required.

The Engine will make use of any Synonyms that you tell it
to.

E.g. chap,man,lad and bloke all (roughly) mean
'male'
By allowing you to specify which words you wish to mean the
same thing, Matchbots can appear to 'understand'
more words and slang than they actually do.

Some browsers support Jars (Java Archives) and
some do not.
By placing the class files both separatly and archived, browsers
can fetch all the classfiles at once (in the Jar file) making for
a quicker page load.
Browsers that don't support Jars will simply load the single
class files one at a time.

What is a Script?

A script is the basis for a Matchbot personality, it tells your Matchbot
what to say and when to say it.
Scripts are made up of 'trigger-response' pairs. The response is used
if the trigger matches the users input.

TRIGGER : *What*your*name*
RESPONSE : My name is Matchbot!

This means that if the user asks for the bots name, it should
reply "My name is Matchbot!".

When the user enters their sentence, it is stripped of all punctuation and then
tested against each trigger, starting from the top of the script. When a trigger is found that matches, its response will be used.
If you put more than one line after the trigger, one of the responses
will be chosen at random.
//TODO //HERE
You can also give the same response to a number of different triggers,
other trigger options.
eg
// Hints. If your triggers arn't working the way you expect have a look
in the Java console in your browser when the applet is running. If there are
any problems with the script, Matchbot will print them here.
// topics.
In normal conversation, when there is a mutual understanding as to what is
being discussed, it is natural to drop the subject of the conversation, leading to
questions in like "are they?" or even just "why?".
Grouping triggers into topics allows Matchbots to cope with this sort of
conversation.
topics

Triggers can be grouped into Topics.

The information given above should be enough to get you
started writing a Matchbot personality. However, there are a few
'special' trigger options...

Showing URLs

When writing triggers, the MatchbotEngine allows you to store
an arbitary string with each trigger.
In the MatchbotApplet, these strings are taken as URLs to be
shown if the trigger fires.

To associate a string with a trigger, you place
the string in brackets after the trigger condition.

Thus, if you wish a script to show the 'Altavista' search engine
if the user types:

"Hey, load altavista for me"

you would include the following trigger in the script:

*load*altavista*(http://altavista.digital.com)>avLoad
There you go.

When triggered in the MatchbotApplet, this would:

Load altavista into the frame named in the 'targetFrame'
applet parameter.

Change the topic to [avLoad]

Respond with "There you go."

NOTE:You don't have to change topic when you are using
URLs.
I simply included the topic change for completeness. The URL
would still be shown if ">avLoad" was removed from
the trigger.

If you are intending to write your own client, calling
MatchbotEngine.getURLToShow() after MatchbotEngine.respond();
will return any bracketed text (without the brackets) defined for
the trigger.
null is returned if nothing was defined.

If a trigger is defined in the triggers.mbt file
before a [topic] declaration is made,
the trigger is placed in the default [*] topic.

To * or not to *?

Its best to only use a '*' trigger in the root
[*] topic.

Matchbot will change from a subtopic to the topic tree root [*]
if no trigger matches in the subtopic

If you have a '*' trigger in the subtopic, it will always match
and the user may not be able to get out of the topic.
Of course there are ways round this, but you should only play if
you are sure you know what you are doing.

If you want a sort of catch all (say in the [work]
topic) using:

*work*

provides a fair (and much safer) alternative to a
'*' trigger.

Watcha tryna say?

You can also add entries in the synonym file to 'map'
contractions to their expanded form.

# These examples are from synonyms.mbt
how is=hows
let us=lets
i am=im

Setting up a Profanity filter

If you want to have a profanity filter, that is -
the program gives a standard message if the user types in rude words:

In the synomns file, map the swear words to a rootstring, EG:

profword=paycut,taxman,etc

Then in the triggers file add

*profword*
Hey not so harsh!

(Of course, this will also produce the
response 'Hey not so harsh' if the users sentence contains the
word 'profword' so choose your rootstring with care..)

Say Something! (Default responses)

To set responses that will be said if no other
triggers match
add a '*' (trigger that matches everything) at the end of the
default topic [*]

*
I didn't understand that!?
What are you on about?
Was that English?

Remember, a trigger can have as many responses as
you care to write, and in this case the more the better.

Line up in an orderly fashion!

Remember to order the triggers in each topic with the most
complicated triggers at the top, and the simplest ones at the
bottom.

In the worst case, if you put a trigger with a '*'
trigger at the start of a topic, then no other triggers will
ever be tested.
(Because the first trigger maches anything)

Data files

Blank lines in any machbot datafile will be
ignored (trigger and synonym files)

You can also put comments in any data file by starting them with
the '#' character.(Note this means that responses should not contain the '#'
character or the rest of the response will be ignored.)

Where does it all end?

If you use a trigger such as "*you*"
it will also match sentences that contain the word "your",
"yourself" etc

If you dont want this to happen, add underlines to show the word
terminator

*you_*

And if you dont want it to match 'thankyou'

then use:

*_you_*

Let me out of here!

Although you have to be careful with '*' triggers
in subtopics you can have some fun with them.

Suppose that you wish a bot to seem offended, simply change topic to the [bot_offended] topic given below and the bot will ignore any other input until the user apologises.

[bot_offended]
*sorry*>* # If they say sorry we will let them out of this subtopic
Ok, I forgive you
* # If they say anything else....
I refuse to talk to you until you have apologised...

Whats going on?

When the MatchbotEngine loads trigger and data files, it
writes out any syntax problems it found, or changes it made to
triggers to the Java console. (The Engine transforms any
synonyms it finds in a triggers to the rootstring.)

As the MatchbotEngine has been written as a module, it can be
used in a number of ways:

Applet Embedded in Webpage:
The setup given in the distribution file. All processing in done
by the visitors browser. (The MatchbotEngine loads scripts
dynamically from the server as required.)

Server-Side:
The Engine could be embedded into a servlet or dedicated-server.
(Although both of these seem a little OTT given the Engines
limited functionality.)
The client-side interface could then be written in any language
that can connect to the server.

Script-Interface:
If you want a non-Java interface but don't have the access to run
anything server-side, it is possible to write a 'stub' applet
making the Engine available to client-side scripting languages.
With such an applet in place, the interface can be created with
script/HTML. The script then only has to call the applet for
responses to user input.

Applications:

Just for fun like MeBot, the example script in the
distribution.

HTML Documentation interface / file server.
- Fed up of typing in URL's for files that you commonly
use, and want something a bit more interesting than a
link-filled HTML jump page. "Give me the sun
javascript reference stuff, (please)"

Web-site guide.
- (This is something that Matchbots can do as well as the
commercial bots. )
- Let a bot guide visitors around your site by answering
questions such as, "whats new?", "are
there any free downloads?" and "show me a
sitemap!" (and showing the relevant pages).

Components. Placing data files // All of the data files must
be in the same directory (they do NOT have to be with the applet)
// They must be on the same server due to unsigned applet
security restrictions.

If you wish to have a Matchbot on your web-page,
then you can simply write your own scripts and use the
MatchbotApplet to embed them into your web-page.
However the MatchbotApplet is a very plain example of an
interface and you might want to use the
MatchbotEngine in your own applets or applications.

Below is the minimum code necessary to use the
MatchbotEngine.

/* The engine is stateless so we must remember the current topic ID */
private String strCurrentTopic = "*";
/* We now instantiate a MatchbotEngine
* The creator takes the following parameters:
* The URL path to the data files
* The name of the primary triggers file
* The name of the synonmys file
* A flag setting the use of dynamic loading. true = use dynamic loading */
MatchbotEngine mbEngine = new MatchbotEngine(
"http://datapath/",
"triggers.mbt",
"synonyms.mbt",
false
);
/* Having instantiated an engine, you can handle user input */
while (pseudo_doInput)
{
/* The respond method returns the scripts response to strUserInput
* Note that we pass in the current topic */
String strResponse = mbEngine.respond(strUserInput, strCurrentTopic);
pseudo_print (strResponse);
/* We must remember the new topic as the engine is stateless */
strCurrentTopic = mbEngine.getCurrentTopic();
/* We can also find out if the trigger specifies a URL to show
* if a URL is returned, it will be exactly as it was specified in the script */
String showURL = mbEngine.getURLToShow();
if (showURL != null)
{
pseudo_showURL (showURL);
}
} // End while